# Enterprise readiness: frictions → shipped primitives This guide answers an "enterprise-readiness" report that proposed six architectural additions after a Vercel-style dashboard dry run. The valuable part of that report is the list of **frictions** — the recurring pain points an enterprise team (or an LLM generating their code) hits. The proposed _code_, however, was written against a generic React/Tailwind mental model, not against cascivo: it reached for `useState`, `useEffect`, `useContext`, Tailwind utility classes, a `data-cascivo-theme` attribute, a `@cascivo/theme` package, and dot-notation tokens like `color.background.primary` — none of which exist here, and most of which this project's [component rules](https://github.com/cascivo/cascivo/blob/main/CLAUDE.md) ban outright. The important finding is that **cascivo already solves five of the six frictions**, and the sixth (a reusable theme runtime) now ships too. This page maps each friction to the real primitive, shows the idiomatic code, and calls out the misconception so an agent reading it never regenerates the banned pattern. | # | Friction from the report | Real answer in cascivo | | --- | ----------------------------------------------- | ---------------------------------------------------------------------- | | 1 | Signal vs. React-state cognitive split | `useControllableSignal` + `useSignals` (`@cascivo/core`) | | 2 | No layout primitives for dense grids | `Grid` / `AutoGrid` / `Flex` / `Columns` / `Center` / `Stack` | | 3 | Theme switching flashes / fights the cascade | `ThemeProvider` / `useTheme` / `themePreloadScript` (`@cascivo/react`) | | 4 | Signal leaks across route changes | `useScope` / `createScope` (`@cascivo/core`) | | 5 | Token names invisible to the LLM context window | `CascivoToken` / `CascivoColorToken` (`@cascivo/tokens/tokens`) | | 6 | Forms fight signal reactivity | `createForm` / `useForm` / `Form` / `field` (`@cascivo/components`) | --- ## 1 — Signal ↔ React state, without a "cognitive split" **The friction is real:** an author (or LLM) shouldn't have to hand-wire the controlled/uncontrolled prop pattern onto a signal every time, and a raw React `useState` next to a signal does cause double reactivity. **The report's fix was wrong for cascivo:** its `useSignalState` is built on `useState` - `useEffect` + a `forceUpdate({})` — all three hooks are banned in cascivo components, and it re-introduces the very React render cycle it claims to avoid. The `$isActive={signal}` JSX directive it proposes doesn't exist and contradicts the owned-code model (there is no compiler intercepting your JSX). **The shipped answer** is [`useControllableSignal`](https://github.com/cascivo/cascivo/blob/main/packages/core/src/controllable.ts) — it codifies the controlled/uncontrolled bridge once, with no effect: ```tsx import { useControllableSignal, useSignals } from '@cascivo/core' function Toggle({ pressed, defaultPressed, onPressedChange }: ToggleProps) { useSignals() // subscribe this React component to signal reads (no Babel transform in app code) const [on, setOn] = useControllableSignal({ value: pressed, // controlled when defined; uncontrolled otherwise — fixed for the component's life defaultValue: defaultPressed, onChange: onPressedChange, }) return setOn(!on.peek())} /> } ``` The rule an agent must internalize: **the signal _is_ the state.** You never pair a signal with `useState`. In React apps that don't run the Babel signals transform (`apps/examples/*`, any consumer app), a component that reads `signal.value` during render calls `useSignals()` as its first statement — that is the entire "bridge." --- ## 2 — Layout primitives for dense grids **The friction is real:** without layout components, an LLM falls back to ad-hoc inline styles or Tailwind, fragmenting the cascade. **The report's fix was wrong for cascivo:** it emits Tailwind-style `className` utility strings (`c-layer-layout`) and imports a `@cascivo/theme` package that doesn't exist. cascivo bans Tailwind and applies layout via **CSS Modules inside `@layer cascivo.component`**, with dynamic values passed as scoped custom properties — never utility classes. **The shipped answer** is the [`@cascivo/layouts`](https://github.com/cascivo/cascivo/tree/main/packages/layouts) primitive set, re-exported from `@cascivo/react`. Gaps are token-scaled; column counts are responsive objects: ```tsx import { Grid, GridItem, AutoGrid, Flex } from '@cascivo/react' // Dashboard card grid: 1 col on phones → 4 on desktop, gap from the space scale. {/* wide KPI tile */} // Self-sizing card wall — no breakpoints, tracks wrap at a min width. {cards} // Alignment-sensitive rows (e.g. status badges) — align/justify map to the grid axes. {statusCells} ``` `gap` is constrained to the token scale (`1 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | 12` → `--cascivo-space-*`), so there is no arbitrary spacing to hallucinate. See [the layout cookbook](https://github.com/cascivo/cascivo/blob/main/docs/cookbooks/layout-and-spacing.md) for the full set (`Columns`, `Center`, `Spacer`, `Stack`, `Section`, `SplitView`, `Masonry`) and the page/app scaffolds (`AppShell`, `dashboard-layout`, `console-app`). --- ## 3 — Theme switching that never flashes or fights the cascade **The friction is real, and this was the one genuine gap.** Every consumer app had to hand-roll the "persist the choice, mirror it onto `data-theme`, and pre-paint it to avoid a flash" wiring; only an app-local copy existed in `apps/site/src/theme.ts`. **The report's fix was wrong for cascivo:** it uses `useEffect` (banned) and writes a `data-cascivo-theme` attribute the themes don't read — cascivo themes are scoped by `[data-theme='…']`. FOUC isn't solved by a React effect at all; it's solved by a pre-paint script in the document head. **The shipped answer** is [`ThemeProvider`](https://github.com/cascivo/cascivo/blob/main/packages/core/src/theme.tsx), now exported from `@cascivo/react`. It packages the exact reference wiring, rules-compliant: the DOM write happens in `useSignalEffect` (not `useEffect`), the active theme is a module-level signal (not React context), and it drives the real `data-theme` attribute. ```tsx import { ThemeProvider, useTheme, themePreloadScript } from '@cascivo/react' function App() { return ( ) } function ThemeToggle() { const [theme, setTheme] = useTheme() // [themeName: string, setter]; the hook calls useSignals() for you return ( setTheme(theme === 'dark' ? 'light' : 'dark')}> {theme === 'dark' ? '☀︎' : '☾'} ) } ``` For SSR / Next.js, inline the pre-paint script so the persisted theme paints on the first byte — no flash on a hard reload: ```tsx // app/layout.tsx (before the app bundle)