@revikornmann/muka-ui 0.18.0 → 0.20.0

package/docs/consumers/setup-instructions.md

@@ -9,6 +9,9 @@ version.
 Muka UI is a **public npm package** — installing it needs no `.npmrc`, registry
 configuration, or auth token.
 
+For the wider picture — brands, Figma, the skills — start at
+[`README.md`](README.md).
+
 ## 1. Install
 
 ```bash
@@ -22,29 +25,80 @@ import '@revikornmann/muka-ui/styles'; // default muka-light — muka fonts incl
 import { Button } from '@revikornmann/muka-ui';
 ```
 
-The default `/styles` bundle — and the pre-bundled `/styles/muka-dark.css` and
-`/styles/wireframe-{light,dark}.css` files — already include that brand's self-hosted
-fonts, so on those themes you need no separate fonts import. Other brands are loaded
-via their raw `tokens-<brand>-<mode>.css` (below), which carries no fonts, so those
-also import `fonts-<brand>.css`.
+## 2. Pick a brand and theme
+
+Muka ships five brands — `muka`, `wireframe`, `grip`, `fscl`, `bouwplan` — each in
+light and dark, for **ten themes**. How you load one depends on the brand.
+
+**Pre-bundled (muka and wireframe).** `/styles` is `muka-light`; three
+alternatives are drop-in replacements for it. Each is self-contained: base
+styles, tokens, every component's CSS, and that brand's self-hosted fonts.
+
+```ts
+import '@revikornmann/muka-ui/styles';                    // muka-light
+import '@revikornmann/muka-ui/styles/muka-dark.css';
+import '@revikornmann/muka-ui/styles/wireframe-light.css';
+import '@revikornmann/muka-ui/styles/wireframe-dark.css';
+```
 
-For a brand theme, also load the brand CSS **and the brand's fonts** and set the
-data attributes (replace `bouwplan` with your brand):
+**Composed (grip, fscl, bouwplan).** No pre-bundled file, so combine three
+imports — base styles, the brand's raw token CSS, and the brand's fonts. The raw
+token CSS carries no `@font-face`, which is why the fonts import is separate:
 
 ```ts
+import '@revikornmann/muka-ui/styles/base.css';
 import '@revikornmann/muka-ui/styles/tokens-bouwplan-light.css';
 import '@revikornmann/muka-ui/styles/fonts-bouwplan.css';
 ```
 
+None of the five fitting? Build your own brand — see [`brand.md`](brand.md).
+
+### How theme selection actually works
+
+Every token stylesheet declares its variables on `:root`. There are **no
+`[data-brand]` or `[data-theme]` selectors in Muka's CSS**, so you select a theme
+by **choosing which stylesheet loads**, and importing two means the last one
+wins. Setting `data-brand` / `data-theme` attributes has no effect.
+
+For a runtime light/dark toggle, swap a `<link>` instead of importing both:
+
+```html
+<link id="muka-theme" rel="stylesheet" href="/styles/tokens-muka-light.css" />
+```
+
+```ts
+document.getElementById('muka-theme').href =
+  `/styles/tokens-${brand}-${mode}.css`;
+```
+
+Copy the token CSS you need into your static/public directory (or let your
+bundler emit it at a stable URL) so those hrefs resolve. Muka's own Storybook
+switches between all ten themes exactly this way — see
+`.storybook/ThemeDecorator.ts` in the repo.
+
+### `data-layout`: the one attribute that does do something
+
+Brand and theme are not attributes, but **layout density is**. Section padding
+and container gaps respond to viewport width through `@media` blocks, and
+`data-layout` forces one of those steps regardless of viewport:
+
 ```html
-<html data-brand="bouwplan" data-theme="light">
+<div data-layout="desktop">…</div>
 ```
 
+Accepted values are `tablet`, `desktop`, and `widescreen`; omit the attribute to
+let the media queries decide. Use it when a region should keep desktop spacing
+inside a narrow container (or the reverse) — it only overrides
+`--section-padding-*` and `--container-gap-*`, never colours or type.
+
+If your app only ever needs one theme, a plain import is simpler and this does
+not apply.
+
 ### Fonts come from Muka — do not load them yourself
 
 Muka self-hosts every brand's fonts and ships them as `@font-face` in
-`styles/fonts-<brand>.css` (backed by bundled WOFF2, so they work offline with no
-CDN). Importing that one file is all the wiring you need:
+`styles/fonts-<brand>.css`, backed by bundled WOFF2, so they work offline with no
+CDN. Importing that one file is all the wiring you need:
 
 - **Do not** load these fonts via `next/font`, a Google Fonts `<link>`, or any
   other loader — you'd ship the bytes twice and risk a name mismatch.
@@ -52,7 +106,7 @@ CDN). Importing that one file is all the wiring you need:
   font-family names in Muka's tokens are the exact `@font-face` family names, so
   overriding them only breaks the resolution.
 
-## 2. Add the auto-update workflow
+## 3. Add the auto-update workflow
 
 Copy the shipped template into your repo so it stays current with Muka releases:
 
@@ -77,7 +131,10 @@ The workflow auto-detects your package manager from the lockfile
 > rejecting a just-published version). Match the value to the pnpm/yarn version
 > you use locally (e.g. `lockfileVersion: 9.0` → pnpm 9).
 
-## 3. Register as a consumer
+Muka is under active development, so a bump can change component behaviour or
+appearance. Keep CI checks on the update PR rather than trusting it blindly.
+
+## 4. Register as a consumer
 
 Add `owner/repo` to Muka's [`.github/consumers.txt`](../../.github/consumers.txt)
 so the release pipeline dispatches updates here. The `/setup-muka` skill opens
@@ -85,3 +142,32 @@ this PR automatically; merge it to enable automatic updates.
 
 The Muka `CONSUMER_DISPATCH_TOKEN` PAT must have **write** access to this repo
 for the `repository_dispatch` to succeed.
+
+## 5. Give your agents the house rules
+
+```bash
+npx muka-ui init
+```
+
+Writes `AGENTS.md`, `CLAUDE.md`, and `docs/muka-ui-guidelines.md` into your repo
+(prompting before overwriting any of them), so agents working here compose Muka
+components and use token custom properties instead of inventing markup and
+hardcoding values. It also warns about styling libraries that conflict with Muka.
+
+`AGENTS.md` holds the rules, because that filename is the vendor-neutral
+convention most agents read. `CLAUDE.md` is a few lines pointing at it, so Claude
+Code finds them too without a second copy that can drift.
+
+## Verify
+
+- `npm ls @revikornmann/muka-ui` shows a semver version resolved from npmjs.
+- The app builds and Muka components render with brand tokens.
+- A component's computed `background-color` resolves to a real colour rather than
+  falling back — that is the check that the token CSS actually loaded.
+- `.github/workflows/update-muka.yml` exists and is valid YAML.
+
+## Next
+
+- [`brand.md`](brand.md) — build your own brand
+- [`skills.md`](skills.md) — every shipped agent skill
+- <https://muka.kornmann.com> — component APIs, Playgrounds, token docs

package/docs/consumers/skills.md

@@ -0,0 +1,79 @@
+# Agent skills shipped with Muka UI
+
+`@revikornmann/muka-ui` ships agent skills inside the package. They turn the
+multi-step jobs around a design system — installing it, branding it, translating
+a design into code, syncing tokens with Figma — into one command each.
+
+## Installing them
+
+Agents discover skills under `.claude/skills/`, never inside `node_modules/`, so
+the package ships them and the CLI copies them in:
+
+```bash
+npx muka-ui install-skill          # install all of them
+npx muka-ui install-skill --list   # see what's available first
+npx muka-ui install-skill add-brand figma-to-code   # install specific ones
+```
+
+Restart your agent afterwards so it picks up the new slash commands. Re-run the
+same command after a Muka upgrade to refresh them; it skips anything already
+identical and prompts before overwriting local edits.
+
+## Which agents can use them
+
+The directory name is Claude's, but the contents are not: a skill is a plain
+markdown file with YAML frontmatter, and `.claude/skills/` is scanned by **Claude
+Code and Cursor** alike. For an agent that reads neither, the skills still work
+as documentation — point it at `.claude/skills/<name>/SKILL.md` and it has the
+same instructions, just without a slash command to trigger them.
+
+Nothing else Muka ships is agent-specific. The tokens are CSS custom properties,
+the components are React, and these consumer docs are prose — none of that cares
+what is editing your repo. `npx muka-ui init` writes the house rules to
+`AGENTS.md`, the vendor-neutral convention, and leaves a short `CLAUDE.md`
+pointing at it.
+
+## The skills
+
+| Skill | What it does | Needs |
+|---|---|---|
+| `/setup-muka` | Installs the package, wires up styles and fonts, adds the release auto-update workflow, and registers your repo as a consumer. Start here. | — |
+| `/add-brand` | Creates a custom brand in **your** repo that overrides Muka's brand layer, so every Muka component takes your colours and typography. Scaffolds the token files, explains the palette choices, and builds the CSS. | `/setup-muka` |
+| `/figma-to-code` | Turns a Figma link into a working screen composed from Muka components and token custom properties — rather than a pixel-matched rebuild that ignores your brand. | A Figma MCP server |
+| `/push-to-figma` | Publishes your brand's tokens into Figma as variables, so designers can design in your brand. Code → Figma. | `/add-brand` + Figma Console MCP |
+| `/pull-from-figma` | Brings brand colour and font changes a designer made in Figma back into your token files. Figma → Code. | `/push-to-figma` + Figma Console MCP |
+
+`/setup-muka` and `/add-brand` are the two most people need. The Figma pair
+matters once designers and engineers are both editing the brand.
+
+## The Figma Console MCP dependency
+
+`/push-to-figma` and `/pull-from-figma` read and write Figma **variables**, which
+the Figma REST API cannot do for local variables. They therefore drive
+[**Figma Console MCP**](https://github.com/southleft/figma-console-mcp), an
+open-source (MIT) MCP server by **[Southleft](https://southleft.com)** published
+as [`figma-console-mcp`](https://www.npmjs.com/package/figma-console-mcp). It
+relays commands to a Desktop Bridge plugin inside Figma Desktop.
+
+It is a third-party project. Muka ships only the skills that drive it; report
+server problems [upstream](https://github.com/southleft/figma-console-mcp/issues).
+
+One-time setup — token, `.mcp.json`, Desktop Bridge plugin, verification — is in
+[`figma-console-mcp.md`](figma-console-mcp.md). Without it, those two skills
+cannot run; the other three are unaffected.
+
+`/figma-to-code` is different: it reads designs through **Figma's own official
+MCP server**, not Figma Console MCP, and needs no Desktop Bridge.
+
+## Maintainer skills are not shipped
+
+The Muka repo has its own skills for working **on** the design system —
+`/component-rules`, `/token-system`, `/new-component`, `/release`, and a
+repo-scoped `/add-brand` that adds a brand to Muka itself for every consumer.
+Those live in
+[`.claude/skills/`](https://github.com/revikornmann/muka/tree/main/.claude/skills)
+and are deliberately excluded from the package, because they edit files that
+exist only in the Muka repo.
+
+If you are contributing to Muka rather than consuming it, clone the repo and use
+those directly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@revikornmann/muka-ui",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Muka Design System - Multi-brand design tokens and React components",
   "main": "dist/cjs/components/index.js",
   "module": "dist/esm/components/index.js",
@@ -62,6 +62,7 @@
     "figma:connect:publish": "figma-code-connect --publish",
     "typecheck": "tsc --project tsconfig.typecheck.json",
     "check:docs": "node scripts/check-doc-sync.js",
+    "check:tokens-used": "node scripts/check-tokens-used.js",
     "lint": "eslint .",
     "lint:rsc": "eslint --config eslint.rsc.mjs \"components/**/*.{ts,tsx}\"",
     "validate:tokens": "node scripts/validate-tokens.js",
@@ -69,8 +70,6 @@
     "disable:automation": "node scripts/disable-automation.js",
     "enable:automation": "node scripts/enable-automation.js",
     "check:automation": "node scripts/check-automation-status.js",
-    "sync:skills": "node scripts/sync-shipped-skills.js",
-    "prepack": "node scripts/sync-shipped-skills.js",
     "prepublishOnly": "npm run build",
     "postinstall": "node scripts/postinstall-nudge.js",
     "prepare": "husky || true"
@@ -108,15 +107,14 @@
     "@fontsource-variable/ibm-plex-sans": "^5.2.8",
     "@fontsource-variable/lora": "^5.2.8",
     "@fontsource-variable/quicksand": "^5.2.10",
-    "@fontsource-variable/red-hat-display": "^5.2.8",
-    "@fontsource-variable/red-hat-text": "^5.2.8",
+    "@fontsource-variable/red-hat-display": "^5.3.0",
+    "@fontsource-variable/red-hat-text": "^5.3.0",
     "@fontsource/yesteryear": "^5.2.8",
     "@playwright/test": "^1.56.1",
     "@storybook/addon-a11y": "^10.3.4",
     "@storybook/addon-designs": "^11.1.3",
     "@storybook/addon-docs": "^10.3.4",
     "@storybook/addon-mcp": "^0.5.0",
-    "@storybook/addon-onboarding": "^10.3.4",
     "@storybook/addon-vitest": "^10.3.4",
     "@storybook/react-vite": "^10.3.4",
     "@testing-library/dom": "^10.4.1",
@@ -139,6 +137,7 @@
     "playwright": "^1.56.1",
     "react": "^18.0.0",
     "react-dom": "^18.0.0",
+    "remark-gfm": "^4.0.1",
     "storybook": "^10.3.4",
     "typescript": "^5.0.0",
     "typescript-eslint": "^8.59.2",

package/scripts/postinstall-nudge.js

@@ -18,9 +18,13 @@ if (!__dirname.includes(`${require('path').sep}node_modules${require('path').sep
 console.log(`
 🎨 Muka UI installed.
 
-Finish setup in Claude Code:
-  1. npx muka-ui install-skill   # makes /setup-muka available
-  2. /setup-muka [brand]         # installs styles + auto-update workflow
+Finish setup in your agent:
+  1. npx muka-ui install-skill   # makes the Muka skills available
+  2. /setup-muka [brand]         # styles, fonts, auto-update workflow
 
-Docs: node_modules/@revikornmann/muka-ui/docs/consumers/setup-instructions.md
+Then, when you want your own brand:
+  /add-brand <name>              # overrides Muka's brand layer in this repo
+
+See every shipped skill:  npx muka-ui install-skill --list
+Docs: node_modules/@revikornmann/muka-ui/docs/consumers/README.md
 `);

package/skills/add-brand/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: add-brand
+description: Create a custom brand in this repo that overrides Muka UI's brand layer, so every Muka component picks up your colours and typography.
+disable-model-invocation: true
+argument-hint: "[brand-name]"
+---
+
+# Add your own brand
+
+Give this repo its own brand without forking Muka UI. You author **only the T2
+brand layer**; primitives, semantics, and all component tokens keep coming from
+the installed package, so every Muka component restyles itself with no component
+code changes.
+
+`$ARGUMENTS` is the brand name — lowercase, starting with a letter, letters,
+numbers and hyphens only (e.g. `acme`, `northwind`, `blue-harbour`).
+
+**Prerequisite:** `@revikornmann/muka-ui` is installed. If not, run
+`/setup-muka` first.
+
+See [`reference.md`](reference.md) for the full token map, the available
+primitive palettes, and the colour-scale conventions.
+
+## How the override works
+
+```
+T1 Primitives   (package)  raw ramps: color.indigo.9, spacing.4, size.md
+T2 Alias base   (package)  brand-agnostic defaults
+T2 Alias brand  ← YOU      brand/light.json, brand/dark.json, brand/fonts.json
+T3 Semantics    (package)  color.surface.level1, color.action.default
+T4 Components   (package)  button.color.primary.background.default
+```
+
+Your three files replace the brand slice of T2. Everything above resolves
+through them, which is why one file of colour references repaints the whole
+library.
+
+## Step 1: Scaffold the brand
+
+```bash
+npx muka-ui brand init $ARGUMENTS
+```
+
+This creates, prompting before overwriting anything that exists:
+
+| Path | Contents |
+|---|---|
+| `brand/fonts.json` | Font families and weights for the `brand`, `plain`, `mono`, `script` roles |
+| `brand/light.json` | Light-mode colour aliases (78 tokens) |
+| `brand/dark.json` | Dark-mode colour aliases |
+| `brand/muka.brand.json` | Build manifest — your brand files plus package token globs |
+| `brand/build.js` | Build entry using `TokenBuilder` from the package |
+
+It also adds a `build:tokens` script to `package.json` if one is not there.
+
+The scaffolded files are copies of Muka's `wireframe` brand, so they are a
+complete, valid, buildable starting point rather than empty stubs. Confirm the
+build works before editing anything:
+
+```bash
+npm run build:tokens
+```
+
+That must print `All theme combinations built successfully!` and produce
+`styles/tokens-$ARGUMENTS-light.css` and `styles/tokens-$ARGUMENTS-dark.css`.
+Fix any failure here before moving on — it is much easier to debug against
+known-good token values.
+
+## Step 2: Decide the brand identity
+
+Before editing, settle these and write them down in the conversation:
+
+| Decision | Feeds |
+|---|---|
+| Neutral ramp | `alias.color.neutral.*` — every surface, border, and text colour |
+| Accent colour | `alias.color.accent.*` — buttons, links, focus rings, selection |
+| Primary / secondary brand colours | `alias.color.brand.*` — logos, marketing accents |
+| State colours | `alias.color.state.{success,warning,error,info}` |
+| Brand and body typefaces | `alias.font.brand.family`, `alias.font.plain.family` |
+
+Pick a **hue-matched pair** of primitive ramps for light and dark: light mode
+uses `{color.<name>.N}`, dark mode uses `{color.<name>dark.N}`. Ask the user for
+the brand's colours if they have not supplied them; do not invent a palette.
+
+## Step 3: Edit the colour aliases
+
+Edit `brand/light.json`. Every value is a **reference to a T1 primitive**, never
+a raw hex — that is what keeps the ramp coherent and lets dark mode mirror it:
+
+```json
+"neutral": {
+  "1":  { "$type": "color", "$value": "{color.slate.1}" },
+  "12": { "$type": "color", "$value": "{color.slate.12}" }
+},
+"accent": {
+  "default":  { "$type": "color", "$value": "{color.violet.9}" },
+  "hover":    { "$type": "color", "$value": "{color.violet.10}" },
+  "pressed":  { "$type": "color", "$value": "{color.violet.11}" },
+  "contrast": { "$type": "color", "$value": "{color.violet.12}" },
+  "muted":    { "$type": "color", "$value": "{color.violet.8}" }
+}
+```
+
+Then mirror it in `brand/dark.json` using the `Dark` ramps —
+`{color.slateDark.1}`, `{color.violetDark.9}`. The suffix is **camelCase
+`Dark`**, and references are case-sensitive: `{color.slatedark.1}` resolves to
+nothing. Keep the **same step numbers** in both files; the ramps are designed so
+equal steps read as equal emphasis in either mode.
+
+Rules that matter:
+
+- **Reference primitives, never hex.** A raw hex silently opts that token out of
+  the system and will not have a dark-mode counterpart.
+- **Keep every key.** Deleting a token leaves the semantic layer resolving to
+  the base alias value, which is rarely what you want. Repoint it instead.
+- **Do not edit anything above T2.** Semantics and component tokens come from
+  the package and are overwritten on every upgrade.
+- Only `alias.*` belongs in these files.
+
+Available palettes and the meaning of each step are in
+[`reference.md`](reference.md).
+
+## Step 4: Set the typography
+
+Edit `brand/fonts.json`. The `family` values must be the **exact `@font-face`
+family name** that will be loaded, because the generated CSS passes the literal
+through to `font-family`.
+
+- **Reusing a font Muka already bundles** (Funnel Display, Funnel Sans, Red Hat
+  Display, Red Hat Text, Quicksand, IBM Plex Sans, Lora, Yesteryear) — import
+  that brand's fonts file and you are done:
+  ```ts
+  import '@revikornmann/muka-ui/styles/fonts-muka.css';
+  ```
+- **Using a system font** (Helvetica, Arial, Menlo, Georgia, …) — nothing to
+  load.
+- **Bringing your own font** — self-host it with your own `@font-face` under the
+  exact family name you put in `fonts.json`. Do not use a Google Fonts `<link>`:
+  it breaks offline and air-gapped installs and adds a render-blocking request.
+  Muka's own font pipeline is not available to consumer brands, so this
+  `@font-face` block is yours to own.
+
+## Step 5: Build and wire up the CSS
+
+```bash
+npm run build:tokens
+```
+
+Import your brand CSS **after** Muka's base and component styles so your `:root`
+block wins the cascade:
+
+```ts
+import '@revikornmann/muka-ui/styles/base.css';
+import './styles/tokens-acme-light.css';
+import '@revikornmann/muka-ui/styles/fonts-muka.css';  // or your own @font-face
+```
+
+Do **not** import `@revikornmann/muka-ui/styles` as well — that bundle contains
+the full muka-light token set and, depending on import order, will fight your
+brand. Use `base.css` instead, which is the component and reset layer only.
+
+There are no `[data-brand]` / `[data-theme]` selectors; to toggle light/dark at
+runtime, swap the stylesheet rather than importing both:
+
+```ts
+link.href = `/styles/tokens-acme-${mode}.css`;
+```
+
+## Step 6: Rebuild on every Muka upgrade
+
+Your brand CSS is generated against the package's primitives, semantics, and
+component tokens, so it goes stale when Muka publishes new ones. Add the build
+to the existing pipeline so it cannot be forgotten:
+
+```json
+"scripts": {
+  "build": "npm run build:tokens && <your existing build>",
+  "postinstall": "npm run build:tokens"
+}
+```
+
+Commit `brand/**`. Generated CSS under `styles/tokens-*.css` can be committed or
+gitignored — commit it if your host does not run a build step.
+
+## Verify
+
+- `styles/tokens-$ARGUMENTS-light.css` and `-dark.css` exist and were rebuilt
+  after your last edit.
+- Neither file contains `undefined` — that means an unresolved `{reference}`,
+  usually a typo'd primitive name.
+- Your accent colour appears as a real value:
+  ```bash
+  grep -- '--alias-color-accent-default' styles/tokens-$ARGUMENTS-light.css
+  ```
+- A primary `<Button>` renders in your accent colour and body text in your
+  typeface, in both light and dark.
+- Toggling to dark mode changes surfaces without leaving light-mode text
+  unreadable.
+
+## Next
+
+- `/push-to-figma` — publish this brand to Figma as variables, so designers can
+  design in your brand.
+- `/figma-to-code` — turn a Figma link into a screen built from Muka components.

package/skills/add-brand/reference.md

@@ -0,0 +1,160 @@
+# Brand token reference
+
+Everything you need while editing `brand/light.json`, `brand/dark.json`, and
+`brand/fonts.json`. The authoritative values live in
+`node_modules/@revikornmann/muka-ui/tokens/t1-primitives/color.json`.
+
+## Available primitive palettes
+
+Each palette is a 12-step ramp. Light-mode references use the base name; dark
+mode appends **camelCase `Dark`** (`{color.violet.9}` → `{color.violetDark.9}`).
+References are case-sensitive.
+
+**Neutrals** — `gray`, `mauve`, `slate`, `sage`, `olive`, `sand`
+
+**Colours** — `tomato`, `red`, `ruby`, `crimson`, `pink`, `plum`, `purple`,
+`violet`, `iris`, `indigo`, `blue`, `cyan`, `teal`, `jade`, `green`, `grass`,
+`bronze`, `gold`, `brown`, `orange`, `amber`, `yellow`, `lime`, `mint`, `sky`
+
+**Absolutes** — `white`, `black`, and the transparency ramps `black-alpha`,
+`white-alpha`
+
+**Hued neutral alphas** — `mauveA`, `grayA`, `sandA`, `sageA` (and
+`mauveDarkA`, `grayDarkA`, `sandDarkA`, `sageDarkA`) back
+`alias.color.neutral.alphaHued.*`, which is used for overlays and scrims that
+must tint rather than cover. Match these to whichever neutral ramp you chose.
+
+Every palette has a dark counterpart except `white`, `black`, and the alpha
+ramps, which are mode-independent.
+
+## What each step in a 12-step ramp is for
+
+| Steps | Use |
+|---|---|
+| 1–2 | App and component backgrounds |
+| 3–5 | Subtle backgrounds: hover, selected, muted fills |
+| 6–8 | Borders and separators (8 is the strongest border / focus ring) |
+| 9–10 | Solid fills — 9 is the palette's most saturated step, 10 is its hover |
+| 11 | Low-contrast text, and text on light backgrounds |
+| 12 | High-contrast text and headings |
+
+Pick `accent.default` at step **9**, `hover` at **10**, `pressed` at **11**, and
+`contrast` at **12** unless you have a reason not to. This pattern is what every
+shipped brand uses.
+
+## Token groups in `light.json` / `dark.json`
+
+78 tokens across five groups. All are `$type: "color"`.
+
+### `alias.color.neutral`
+
+- `1`–`12` — the neutral ramp. Drives every surface level, border, and text
+  colour in the semantic layer, so this choice has the widest visual effect of
+  anything in the file.
+- `alphaHued.1`–`12` — translucent neutrals for overlays and scrims.
+
+### `alias.color.brand`
+
+- `primary.{regular,contrast,muted}`
+- `secondary.{regular,contrast,muted}`
+
+Brand identity colours. Used for marketing surfaces and accents rather than
+ordinary controls — controls read from `accent`.
+
+### `alias.color.accent`
+
+- `{default,hover,pressed,contrast,muted}`
+- `inverse.{default,hover,pressed,contrast,muted}`
+
+The interactive colour: primary buttons, links, focus rings, selection,
+active navigation. `inverse` is the same role on top of an accent-filled
+surface, so it usually runs from step 1 up to `white`.
+
+If you only change one thing, change this.
+
+### `alias.color.state`
+
+For each of `success`, `warning`, `error`, `info`:
+
+- `{contrast,default,muted}`
+- `surface.{level0,level1,level2,level3}`
+
+Keep the hues conventional — green for success, red for error, amber for
+warning. `default` is the solid step 9, `contrast` the readable step 11, `muted`
+a step 3 fill, and the `surface` levels are the elevation ramp for banners and
+alerts.
+
+### `alias.color.conversation`
+
+For each of `own`, `peer`, `agent`:
+
+- `surface.{default,raised}`
+- `border`
+
+Plus `meta` for timestamps and read receipts. These back the chat components. If
+your app has no chat surface, leave them as scaffolded — they still need to
+resolve.
+
+## `fonts.json` roles
+
+| Role | Used for |
+|---|---|
+| `brand` | Headings, buttons, labels — the expressive typeface |
+| `plain` | Body copy and UI text — the readable typeface |
+| `mono` | Code, numeric tables, anything needing fixed advance |
+| `script` | Decorative accents only |
+
+Each role has `family` plus a `weight` map. `brand` and `plain` carry
+`regular` / `medium` / `semibold` / `bold`; `mono` carries `regular` / `bold`;
+`script` is `family` only.
+
+Weights are CSS numerics as strings (`"400"`, `"600"`). Only list weights the
+font actually provides — naming a weight the file lacks makes the browser
+synthesise it, which looks wrong at large sizes.
+
+Pointing `brand` and `plain` at the same family is normal and is what the
+`wireframe` and `fscl` brands do.
+
+## Fonts Muka already bundles
+
+Reference any of these and you get a real self-hosted face by importing the
+matching `fonts-<brand>.css`:
+
+| Family | Import this brand's fonts file |
+|---|---|
+| `Funnel Display`, `Funnel Sans` | `fonts-muka.css` |
+| `Quicksand` | `fonts-grip.css` |
+| `IBM Plex Sans`, `Lora` | `fonts-fscl.css` |
+| `Red Hat Display`, `Red Hat Text` | `fonts-bouwplan.css` |
+| `Yesteryear` (script role) | `fonts-muka.css`, `fonts-grip.css`, or `fonts-bouwplan.css` |
+
+`fonts-wireframe.css` is empty — that brand is system fonts only.
+
+System families need no loading: `Helvetica`, `Arial`, `Menlo`,
+`Lucida Console`, `Times New Roman`, `Courier New`, `Georgia`, `Verdana`,
+`Tahoma`, `Trebuchet MS`, `system-ui`, `ui-sans-serif`, `ui-serif`,
+`ui-monospace`, and the generic `sans-serif` / `serif` / `monospace`.
+
+## Generated CSS names
+
+Token paths become custom properties by flattening on `-`:
+
+| Token | Custom property |
+|---|---|
+| `alias.color.accent.default` | `--alias-color-accent-default` |
+| `alias.color.neutral.3` | `--alias-color-neutral-3` |
+| `alias.font.brand.family` | `--alias-font-brand-family` |
+
+You will rarely reference these directly — components read T3/T4 properties like
+`--color-action-default` and `--button-color-primary-background-default`, which
+resolve through your aliases. Grep for `--alias-` only when debugging.
+
+## Debugging
+
+| Symptom | Cause |
+|---|---|
+| `undefined` in the generated CSS | An unresolved `{reference}` — usually a typo'd palette name or a missing `Dark` suffix |
+| Dark mode looks identical to light | `dark.json` still references light ramps |
+| Text unreadable on accent fills | `accent.contrast` is too close to `accent.default`; move it to step 12 or `white` |
+| Fonts fall back to a system face | No `@font-face` is loaded for that family name, or the name does not match byte-for-byte |
+| Colours unchanged after a rebuild | The brand CSS is imported before Muka's token bundle, so the bundle wins. Import `base.css` instead of `styles`, and your brand CSS last |