# DV Layer

> DTCG-shaped CSS-native design token system with CSS, vanilla-JS, and React
> components. Tokens are the single source of truth; components compose
> semantic tokens via BEM classes. Storybook is the canonical interactive
> documentation surface.

## Repo layout

- [packages/tokens](packages/tokens/src) — DTCG-shaped JSON: `primitives/`, `semantic/`, `modes/`
- [packages/html](packages/html/src) — CSS (`src/css/components/*.css`) + vanilla JS (`src/js/components/*.js`)
- [packages/react](packages/react/src) — typed React wrappers, render-prop polymorphism (ADR-022)
- [packages/icons](packages/icons/src) — SVG icon set + sprite + React bindings
- [packages/animation](packages/animation/src) — WAAPI / springs / scroll / FLIP / gestures
- [packages/mcp](packages/mcp/README.md) — shared HTTP reference service and canonical consumer upgrade workflow
- [packages/storybook](packages/storybook) — narrative docs as `.stories.tsx` + interactive component browser

## Conventions

- BEM: `.dv-{block}__{element}--{modifier}` ([ADR-001](docs/adr/ADR-001-bem-components-use-tokens-not-utilities.md))
- Utilities: `.dv:{utility}` Tailwind-v4-style prefix-as-variant ([ADR-020](docs/adr/ADR-020-utility-prefix-as-variant.md))
- Dark utilities: CSS-only local mode scopes; Chrome/Edge 120+, Firefox 146+, Safari/iOS Safari 26.4+ (including WordPress CSS). For older targets use semantic colors/components ([ADR-042](docs/adr/ADR-042-scoped-dark-utilities.md)).
- Tokens: 2-tier — primitives → semantic, no component layer ([ADR-005](docs/adr/ADR-005-two-tier-token-architecture.md))
- Token shape: DTCG-shaped, not strictly conformant ([ADR-008](docs/adr/ADR-008-dtcg-shape-not-strict.md))
- Color: OKLCH primitives ([ADR-004](docs/adr/ADR-004-oklch-color-space.md))
- Theming: no prebuilt themes — override accent semantic tokens in `@layer dv-themes` ([ADR-025](docs/adr/ADR-025-themes-are-examples-not-shipped.md))
- React entry: per-file `'use client'`, ESM-only ([ADR-012](docs/adr/ADR-012-rsc-entry-point-split.md), [ADR-013](docs/adr/ADR-013-drop-cjs-output.md))
- Overlay state: `data-state` attribute, not BEM modifier ([ADR-021](docs/adr/ADR-021-overlay-state-attribute.md))
- Container-query utilities: `.dv:@md:p-6`, etc. ([ADR-019](docs/adr/ADR-019-container-query-utilities.md))

## Components (source of truth: `packages/html/src/css/components/`)

Each component CSS file carries an `@ai-component` JSDoc header (base class, React
component, element, variants, sizes, HTML examples, a11y notes). These headers —
plus the React `@ai-react-*` blocks and vanilla-JS behaviour — are parsed by
`scripts/build-ai-meta.mjs` into `.build-meta/ai-manifest.json` and inlined into
`llms-full.txt`. The list below is generated; for interactive examples use
Storybook (`pnpm storybook`), and for the canonical class shape read the CSS source.

- [accordion](packages/html/src/css/components/_accordion.css): React <Accordion>
- [alert](packages/html/src/css/components/_alert.css): info|success|warning|error · React <Alert>
- [alert-dialog](packages/html/src/css/components/_alert-dialog.css): React <AlertDialog>
- [app](packages/html/src/css/components/_app.css): React <App>
- [avatar](packages/html/src/css/components/_avatar.css): accent|success|info · sizes xs,sm,md,lg,xl · React <Avatar>
- [badge](packages/html/src/css/components/_badge.css): neutral|success|warning|error|info|accent|solid-accent|solid-success|solid-warning|solid-error|interactive|removable · sizes sm,lg · React <Badge>
- [banner](packages/html/src/css/components/_banner.css): info|success|warning|error|accent · React <Banner>
- [breadcrumb](packages/html/src/css/components/_breadcrumb.css): React <Breadcrumb>
- [bulk-bar](packages/html/src/css/components/_bulk-bar.css): React <BulkBar>
- [button](packages/html/src/css/components/_button.css): accent|neutral|outline|ghost|danger|link|success|icon-only|block|active|loading · sizes sm,lg · React <Button>
- [calendar](packages/html/src/css/components/_calendar.css): month|week|day|year · React <Calendar>
- [card](packages/html/src/css/components/_card.css): elevated|interactive|hover|hero|selectable|fill · React <Card>
- [carousel](packages/html/src/css/components/_carousel.css): fade|vertical · React <Carousel>
- [chart](packages/html/src/css/components/_chart.css): React <Chart>
- [checkbox](packages/html/src/css/components/_checkbox.css): React <Checkbox>
- [code](packages/html/src/css/components/_code.css): block|dark|success|error|warning · React <Code>
- [collapsible](packages/html/src/css/components/_collapsible.css): React <Collapsible>
- [color-picker](packages/html/src/css/components/_color-picker.css): sizes sm,lg · React <ColorPicker>
- [combobox](packages/html/src/css/components/_combobox.css): sizes sm,lg · React <Combobox>
- [command](packages/html/src/css/components/_command.css): React <Command>
- [data-table](packages/html/src/css/components/_data-table.css): stack|priority · React <DataTable>
- [date-picker](packages/html/src/css/components/_date-picker.css): sizes sm,lg · React <DatePicker>
- [description-list](packages/html/src/css/components/_description-list.css): raised|borderless|compact|striped|inline|space-between|stacked · React <DescriptionList>
- [dialog](packages/html/src/css/components/_dialog.css): sizes sm,lg,xl,full,sheet · React <Dialog>
- [drawer](packages/html/src/css/components/_drawer.css): left|right|top|bottom|level-2|level-3 · sizes sm,md,lg,xl · React <Drawer>
- [dropdown-menu](packages/html/src/css/components/_dropdown-menu.css): React <DropdownMenu>
- [empty-state](packages/html/src/css/components/_empty-state.css): compact · React <EmptyState>
- [eyebrow](packages/html/src/css/components/_eyebrow.css): accent|rule · React <Eyebrow>
- [file-upload](packages/html/src/css/components/_file-upload.css): sizes sm,lg · React <FileUpload>
- [grid](packages/html/src/css/components/_grid.css): cols-1|cols-2|cols-3|cols-4|cols-5|cols-6|cols-12|rows-1|rows-2|rows-3|rows-4|rows-5|rows-6|auto-fit-sm|auto-fit-md|auto-fit-lg|auto-fit-xl|auto-fill-sm|auto-fill-md|auto-fill-lg|bento|joined|flow-row|flow-column|flow-dense|flow-row-dense|flow-column-dense · React <Grid>
- [heading](packages/html/src/css/components/_heading.css): truncate|clamp-2|clamp-3 · sizes 2xl,xl,lg,md,sm,xs · React <Heading>
- [icon](packages/html/src/css/components/_icon.css): sizes xs,sm,md,lg,xl,2xl,3xl,4xl · React <Icon>
- [icon-box](packages/html/src/css/components/_icon-box.css): neutral|accent|info|success|warning|error · sizes sm,md,lg,xl · React <IconBox>
- [kbd](packages/html/src/css/components/_kbd.css): React <Kbd>
- [link](packages/html/src/css/components/_link.css): action|destructive|muted|underline|no-underline|external|icon · React <Link>
- [list](packages/html/src/css/components/_list.css): raised|borderless|compact|loose|unframed|striped|align-top|plain · React <List>
- [load-more](packages/html/src/css/components/_load-more.css): React <LoadMore>
- [media](packages/html/src/css/components/_media.css): video|square|portrait|landscape|photo|wide|contain|framed · React <Media>
- [multi-select](packages/html/src/css/components/_multi-select.css): sizes sm,lg · React <MultiSelect>
- [nav](packages/html/src/css/components/_nav.css): React <Nav>
- [number-field](packages/html/src/css/components/_number-field.css): React <NumberField>
- [otp](packages/html/src/css/components/_otp.css): React <OTP>
- [page-header](packages/html/src/css/components/_page-header.css): React <PageHeader>
- [pagination](packages/html/src/css/components/_pagination.css): React <Pagination>
- [panes](packages/html/src/css/components/_panes.css): React <Panes>
- [password](packages/html/src/css/components/_password.css): sizes sm,lg · React <Password>
- [popover](packages/html/src/css/components/_popover.css): React <Popover>
- [progress](packages/html/src/css/components/_progress.css): indeterminate|striped|animated|segmented · React <Progress>
- [prose](packages/html/src/css/components/_prose.css): lg|leading-tight|leading-snug|leading-normal|leading-loose|max-none · React <Prose>
- [qr-code](packages/html/src/css/components/_qr-code.css): sizes sm,lg · React <QrCode>
- [radio](packages/html/src/css/components/_radio.css): React <Radio>
- [reading-progress](packages/html/src/css/components/_reading-progress.css): React <ReadingProgress>
- [scrollspy](packages/html/src/css/components/_scrollspy.css): React <ScrollSpy>
- [section](packages/html/src/css/components/_section.css): muted|subtle|accent · sizes sm,md,lg,xl,full · React <Section>
- [section-header](packages/html/src/css/components/_section-header.css): React <SectionHeader>
- [select](packages/html/src/css/components/_select.css): sizes sm,lg · React <Select>
- [separator](packages/html/src/css/components/_separator.css): subtle|emphasis|vertical · sizes none,sm,md,lg,xl · React <Separator>
- [sidebar](packages/html/src/css/components/_sidebar.css): React <Sidebar>
- [skeleton](packages/html/src/css/components/_skeleton.css): text|avatar|button|static · React <Skeleton>
- [slider](packages/html/src/css/components/_slider.css): React <Slider>
- [sortable](packages/html/src/css/components/_sortable.css): React <Sortable>
- [sparkline](packages/html/src/css/components/_sparkline.css): accent|success|error|warning|neutral · React <Sparkline>
- [spinner](packages/html/src/css/components/_spinner.css): accent|success|warning|error|info|inverse · sizes xs,sm,lg,xl,2xl,3xl,4xl · React <Spinner>
- [stack](packages/html/src/css/components/_stack.css): row|row-nowrap|row-reverse|column-reverse|inline|wrap|nowrap|wrap-reverse · React <Stack>
- [stepper](packages/html/src/css/components/_stepper.css): horizontal|vertical · React <Stepper>
- [switch](packages/html/src/css/components/_switch.css): sizes sm · React <Switch>
- [tab-bar](packages/html/src/css/components/_tab-bar.css): React <TabBar>
- [table](packages/html/src/css/components/_table.css): striped|compact|mini|sticky-col · React <Table>
- [tabs](packages/html/src/css/components/_tabs.css): vertical|pills · React <Tabs>
- [text](packages/html/src/css/components/_text.css): truncate|clamp-2|clamp-3 · sizes 6xl,5xl,4xl,3xl,2xl,xl,lg,base,sm,xs · React <Text>
- [text-field](packages/html/src/css/components/_text-field.css): sizes sm,lg · React <TextField>
- [textarea](packages/html/src/css/components/_textarea.css): auto-resize|editor · sizes sm,lg · React <Textarea>
- [time-picker](packages/html/src/css/components/_time-picker.css): sizes sm,lg · React <TimePicker>
- [timeline](packages/html/src/css/components/_timeline.css): vertical|padded · React <Timeline>
- [toast](packages/html/src/css/components/_toast.css): success|error|warning|info · React <Toast>
- [toggle-group](packages/html/src/css/components/_toggle-group.css): React <ToggleGroup>
- [tooltip](packages/html/src/css/components/_tooltip.css): React <Tooltip>
- [topbar](packages/html/src/css/components/_topbar.css): sizes sm,md,lg,xl,full · React <Topbar>
- [visually-hidden](packages/html/src/css/components/_visually-hidden.css): React <VisuallyHidden>

Variant / size / JS / React detail per component is inlined in
[llms-full.txt](llms-full.txt), or read directly from the CSS source files.

## Tokens

- Primitives: [packages/tokens/src/primitives/](packages/tokens/src/primitives) — raw OKLCH colors, 4px-grid spacing, sizing, radii, shadows, motion
- Semantic: [packages/tokens/src/semantic/](packages/tokens/src/semantic) — `bg-*`, `fg-*`, `border-*`, `action-*`, etc.
- Dark mode: [packages/tokens/src/modes/dark.json](packages/tokens/src/modes/dark.json) — base overrides; activated via `data-mode="dark"`
- Typography: flat `rem` for body/UI (`xs`–`xl`, 12–20 px); fluid `clamp()` for display (`2xl`+). See [docs/typography.md](docs/typography.md) §Typography Scale.

## Theming (brand override)

No prebuilt themes ship. Branding = overriding the **accent chain** inside
`@layer dv-themes` (the last layer, established by `dv-layer.css`), activated with
`[data-theme]`. See [ADR-025](docs/adr/ADR-025-themes-are-examples-not-shipped.md) and
Storybook → *Foundations → Theming*.

The chain is **nine tokens**, and all nine need overriding **in both modes** — the rungs
you skip stay indigo. Partial override is the most common theming bug:

```css
@layer dv-themes {
  [data-theme='my-brand'] {
    --dv-color-bg-accent: …;         /* filled brand surface   */
    --dv-color-bg-accent-hover: …;
    --dv-color-bg-accent-active: …;
    --dv-color-bg-accent-subtle: …;  /* TINTED container — keep it a tint */
    --dv-color-fg-accent: …;         /* links / accent text on neutral surfaces */
    --dv-color-fg-accent-hover: …;
    --dv-color-fg-on-accent: …;        /* text ON bg-accent        */
    --dv-color-fg-on-accent-subtle: …; /* text ON bg-accent-subtle */
    --dv-color-border-accent: …;     /* focus ring aliases this — no separate override */
  }
  /* repeat for [data-theme='my-brand'][data-mode='dark'], .dark, .dv-dark */
}
```

- **`--dv-color-fg-on-accent` ships a static white.** Correct for the default indigo and
  must be rechecked for a custom accent, including its hover and active states.
  Override it with an explicitly measured foreground. OKLCH lightness thresholds
  do not guarantee WCAG contrast; validate all accent states with
  `pnpm validate:contrast --theme ./my-brand.css`.
- **`--dv-color-bg-accent-subtle` is a tint, not a second fill.** Three foregrounds ride on
  it by role: `fg-on-accent-subtle` (Badge/Banner), `fg-accent` (IconBox/Avatar/Nav),
  `fg-default` (Table/List/Card selection). Remapping it to a saturated fill breaks
  all three.
- DV Layer is **strictly single-accent** — no `secondary` tier ships. A second brand colour is
  a consumer-defined variable in `@layer dv-themes`.
- `pnpm validate:contrast` gates the accent pairs in both modes; run it after any change.

## Documentation surfaces

- **[MCP](packages/mcp/README.md)** — call `dvlayer_get_system_info` for the deployed snapshot identity. For upgrades, retrieve its `upgradeWorkflow` with `dvlayer_get_guide`; no local skill is required. The service supplies read-only guidance, and the local shared CLI executes changes.
- **[Utilities](docs/utilities.md)** — bundle availability, responsive variants, mode scopes and hybrid ownership. MCP `dvlayer_list_utilities` discovers families; `dvlayer_get_utility` verifies an exact class against the compiled bundles.
- **[Animation](packages/animation/README.md)** — engine APIs and lifecycle contracts; browser emulation does not establish physical-device certification.
- **[Storybook](packages/storybook)** — interactive components + narrative docs (`docs/**/*.stories.tsx`)
- **[ADRs](docs/adr)** — architecture decision records
- **[CLAUDE.md](CLAUDE.md)** — agent workflow, builds, publishing, and commit format
- **[Authoring references](docs/README.md)** — CSS, tokens, typography, responsive layout, JavaScript, and Storybook conventions
- **[CHANGELOG.md](CHANGELOG.md)** — `keepachangelog.com` format

## Build & verification

- `pnpm build` — turbo orchestration (tokens, html, react, animation, icons, dist, ai-meta)
- `pnpm build:ai-meta` — regenerate `ai-manifest.json`, `llms.txt`, `llms-full.txt` from the `@ai-*` headers (do not hand-edit those outputs; edit `scripts/templates/llms.txt.tmpl` or the headers)
- `pnpm test` — vitest suites across packages
- `pnpm lint` / `pnpm typecheck`
- `pnpm validate:consistency` — cross-layer class/token/data-attr validation
- `pnpm storybook` — local interactive docs