# Strata — the Layers design system

> **You are an agent building UI for a Layers surface. Read this index, then
> open only the topic docs your task needs.** Strata is the single design
> system behind every Layers surface: the product app (`apps/web-v2`), the
> marketing site (`apps/marketing`), the docs sites, and Elle's generated UI.
> "Elle builds with Strata" — the agent composes from the same vocabulary
> developers do.

Strata is not a published package. It is the sum of:

| Piece | Lives at | What it is |
|-------|----------|------------|
| **Tokens** | `packages/ui/src/css/theme.css` + `css/tailwind.css` | The palette (`:root` + `.dark`), radius ramp, 14px type scale, base document styles. Every consumer `@import`s these two files — there are no local copies. |
| **Components** | `packages/ui/src/*.tsx` (`@layers/ui`) | ~70 source-consumed components: shadcn primitives (radix-maia style) + Layers wrappers + app components. Subpath imports: `@layers/ui/button`. |
| **Generative-UI catalog** | `packages/ui-schema` (`@layers/ui-schema`) | The closed, Zod-validated vocabulary Elle composes sheets from. Each entry maps 1:1 onto a real `@layers/ui` component. |
| **Workbench** | `apps/strata` | Dev-only visual surface: token inspector (light/dark side by side), component gallery, catalog browser. `cd apps/strata && pnpm dev`. |

## Route by task

| Your task touches… | Read |
|--------------------|------|
| Colors, dark mode, radii, type scale, fonts | [`tokens.md`](./tokens.md) |
| Using or adding a component; variants | [`components.md`](./components.md), then the component's page on the strata site (`apps/strata/src/component-docs/`, rendered at `strata.layers.com/components/<slug>`) |
| Spacing, typography, iconography, copy — the do/don't rules | [`rules.md`](./rules.md) — **read this for ANY visual work** |
| Page/sheet structure: canvas sheets, inspectors, area navigation | [`layouts.md`](./layouts.md), then `apps/web-v2/docs/AGENT_APP_UI_CONVENTIONS.md` (the chat ↔ canvas doctrine) |
| Elle's generated UI (`renderSheet`, the catalog) | [`generative-ui.md`](./generative-ui.md) |
| Marketing surfaces: brand patterns, motion, page templates | [`brand.md`](./brand.md), then `apps/marketing/docs/ILLUSTRATIONS.md` for illustration work |

## The three laws (apply to every consumer)

1. **One token source.** All colors/radii/type come from the shared theme
   files. Never define a local `--background`-style token, never write a raw
   color utility (`text-neutral-900`) — semantic tokens only. Verify a CSS
   variable exists in `packages/ui/src/css/theme.css` before writing
   `var(--x)`.
2. **One component vocabulary.** Use `@layers/ui` and shadcn primitives;
   never hand-roll an equivalent, never copy component source from the legacy
   `apps/web-v1`. A new layout need is a new `packages/ui` component (plus a
   catalog entry if Elle should compose with it), never bespoke one-off DOM.
3. **The shadcn website is the sole authority for stock component structure**
   (the MCP's demo registry is stale — WebFetch the site). No custom
   className/spacing inside shadcn compounds; extend via variants, not
   parallel components.

## Consuming Strata in a new app

```css
@import 'tailwindcss';
@source "../../packages/ui/src";   /* Tailwind's scanner skips node_modules —
                                       without this, classes used only inside
                                       @layers/ui silently drop */
@import 'tw-animate-css';
@import 'shadcn/tailwind.css';
@import '@fontsource-variable/inter';
@import '@layers/ui/css/theme.css';
@import '@layers/ui/css/tailwind.css';

@custom-variant dark (&:is(.dark *));
```

Add `"@layers/ui": "workspace:*"` (source-consumed — the consumer transpiles
`src/` directly; there is no build step). Dark mode is class-based `.dark` on
the root element in every consumer. Berkeley Mono is self-hosted per app
(`@font-face`, weights as needed); Inter ships via `@fontsource-variable/inter`.