# ActuateCMS Admin Design System

Version **1.0** — canonical tokens for `@actuate-media/cms-admin` and downstream consumer apps.

## Token files (handoff)

| File                            | Purpose                                                                |
| ------------------------------- | ---------------------------------------------------------------------- |
| `tokens.json`                   | W3C Design Tokens format — Style Dictionary / CI pipelines             |
| `tokens.css`                    | CSS custom properties on `:root` + `[data-theme="dark"]`               |
| `tokens.scss`                   | Sass maps + `acms-css-vars` mixin (runtime theming)                    |
| `tokens.tailwind.cjs`           | Tailwind **v3** preset — `presets: [require('…/tokens.tailwind.cjs')]` |
| `ActuateCMS Design System.html` | Browsable reference (keep with handoff zip; not published to npm)      |

All exports default to **runtime theming** (CSS var references). Static hex fallbacks are documented in `tokens.tailwind.cjs` comments and `tokens.scss` maps.

## How the admin package consumes tokens

The published admin UI does **not** import `tokens.css` directly. It uses a scoped adapter:

| Layer        | File                                 | Role                                                         |
| ------------ | ------------------------------------ | ------------------------------------------------------------ |
| Raw tokens   | `src/styles/actuate-tokens.css`      | `--bg`, `--acc`, etc. under `.actuate-admin`                 |
| Dark mode    | `.actuate-admin.dark` + `data-theme` | `ThemeProvider` sets both on the scoped admin root           |
| Semantic map | `src/styles/theme.css`               | Tailwind v4 `@theme` aliases (`--primary`, `--sidebar-*`, …) |
| Primitives   | `src/components/ui/*`                | Input, Card, Toggle aligned to HTML reference                |

### Intentional differences from the handoff

1. **Dark mode selector** — Handoff targets `[data-theme="dark"]` on `<html>`. Admin sets `data-theme` on `.actuate-admin` (scoped) and toggles `.dark` for Tailwind v4.
2. **Default font** — Handoff `tokens.css` lists DM Sans. Admin defaults to **system-ui**; DM Sans remains selectable in Appearance.
3. **Tailwind version** — Admin builds with **Tailwind v4** (`@theme inline` in `theme.css`). The `.cjs` preset targets Tailwind v3 consumer apps.

## npm exports

```ts
import '@actuate-media/cms-admin/design-system/tokens.css'
// presets: [require('@actuate-media/cms-admin/design-system/tokens.tailwind.cjs')]
```

## Governance (subagency review)

When the design team or a subagency updates the system:

1. Open `ActuateCMS Design System.html` from the handoff zip and spot-check components.
2. Replace files in this folder from the handoff; diff `tokens.json` values against the previous version.
3. Sync changed values into `src/styles/actuate-tokens.css` (scoped runtime copy).
4. Update `src/styles/theme.css` semantic mappings if Tailwind aliases change.
5. Update shared primitives (`Input`, `Card`, `Toggle`, …) when component specs change.
6. Run `pnpm --filter @actuate-media/cms-admin build:css` and verify light + dark admin chrome.
7. Add a `@actuate-media/cms-admin` changeset.

Accent colors in **Appearance → Accent** map from `tokens.json` → `accentOptions` and `@actuate-media/cms-core` (`appearance/theme-tokens.ts`).
