@revikornmann/muka-ui 0.18.0 → 0.20.0

package/skills/figma-to-code/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: figma-to-code
+description: Build a screen in this app from a Figma link, composing Muka UI components and design tokens instead of writing new styled markup.
+disable-model-invocation: true
+argument-hint: "[figma-url]"
+---
+
+# Figma link → Muka UI screen
+
+Turn a Figma design into working code in **this app** by assembling it from Muka
+UI components. `$ARGUMENTS` is the Figma URL.
+
+The goal is assembly, not reproduction. A Figma frame drawn with the Muka UI
+Figma Library is already made of Muka components, so the right output is those
+same components with props — not a pixel-matched rebuild in bespoke CSS. If the
+result is a pile of `<div>`s with hardcoded colours, the design was
+re-implemented instead of mapped, and it will not follow brand or theme changes.
+
+**Prerequisite:** `@revikornmann/muka-ui` is installed (`/setup-muka`) and a
+Figma MCP server is connected.
+
+## Step 1: Read the design
+
+Extract `fileKey` and `nodeId` from the URL:
+
+- `figma.com/design/:fileKey/:fileName?node-id=:nodeId` — convert `-` to `:` in
+  the nodeId (`472-4248` → `472:4248`)
+- `figma.com/design/:fileKey/branch/:branchKey/…` — use `branchKey` as the
+  fileKey
+
+Then pull the design context:
+
+```
+get_code_connect_map(fileKey, nodeId)  # FIRST — Figma node → real component names
+get_design_context(fileKey, nodeId)    # structure, tokens, variants
+get_screenshot(fileKey, nodeId)        # visual reference to check yourself against
+```
+
+Read `get_code_connect_map` **first**. Muka publishes Code Connect mappings for
+its components, so this is what tells you a node is a Muka `Button` rather than a
+rounded rectangle with a label. Treat its answer as authoritative over your own
+reading of the layers.
+
+Treat `get_design_context` output as a **reference, not final code**. It
+describes the design in generic terms; your job is the translation.
+
+## Step 2: Inventory what Muka already provides
+
+Before writing any JSX, find out what exists. In order of reliability:
+
+1. **Storybook MCP**, if Muka's Storybook is running — the component list and
+   live prop tables are the most accurate source there is.
+2. **The published Storybook** at <https://muka.kornmann.com> — component APIs,
+   Playgrounds, and usage patterns.
+3. **The installed types**:
+   ```bash
+   grep 'export' node_modules/@revikornmann/muka-ui/dist/types/components/index.d.ts
+   ```
+4. **`npx muka-ui components -v`** — names and prop summaries from the package
+   manifest.
+5. **`docs/muka-ui-guidelines.md`** in this repo, if `npx muka-ui init` has run.
+
+Write out the mapping before you build, so the gaps are visible up front:
+
+| Figma layer | Muka component | Props |
+|---|---|---|
+| "Primary CTA" | `Button` | `variant="primary" size="md"` |
+| "Search field" | `Input` | `placeholder`, leading icon slot |
+| "Nav bar" | `TopBar` | title, actions |
+
+## Step 3: Compose the screen
+
+Build from the outside in: page shell, then regions, then controls.
+
+- **Use Muka components for anything Muka has.** Reach for a raw element only
+  when nothing fits.
+- **Compose, don't fork.** Prefer slots and composition over copying a
+  component's source to tweak it. A forked component stops receiving upgrades
+  and brand changes.
+- **Only Muka's CSS custom properties for styling.** For app-specific layout,
+  read T3 semantic properties:
+  ```css
+  .checkout-summary {
+    background-color: var(--color-surface-level1);
+    color: var(--color-text-default-default);
+    padding: var(--spacing-4);
+    border-radius: var(--radius-md);
+  }
+  ```
+  Never paste a hex, px type size, or radius out of Figma. Those values belong to
+  one brand in one theme; the token survives both.
+- **Match the design's intent, not its pixels.** If Figma shows 15px of padding
+  and the nearest token is 16, use the token. Report differences larger than a
+  step rather than hardcoding around them.
+- **Mobile first.** Muka is designed mobile-up with the desktop breakpoint at
+  `1024px`. Build the narrow layout first, then enhance.
+
+## Step 4: Handle what Muka does not have
+
+When a design needs something Muka does not ship, say so explicitly rather than
+quietly inventing a lookalike — a bespoke component that mimics a Muka one is
+the most expensive outcome, because it looks correct until the brand changes.
+
+1. Re-check whether composing existing primitives covers it.
+2. If not, build it in **this repo** (not in Muka) styled entirely with Muka's
+   token custom properties, so it tracks brand and theme.
+3. Tell the user it is app-local and worth requesting upstream at
+   <https://github.com/revikornmann/muka/issues> if it is generic.
+
+## Step 5: Verify
+
+- The screen renders and type-checks.
+- **No hardcoded colours, type sizes, or radii.** Grep your diff for `#`,
+  `rgb(`, and `px` and justify every remaining hit.
+- Compare against `get_screenshot` for structure, hierarchy, and spacing rhythm.
+- **Switch theme and confirm nothing breaks.** Load the dark stylesheet and
+  re-check: anything that does not react was hardcoded. This is the single most
+  effective check that the mapping was done properly.
+- Keyboard reachability: every interactive element is tabbable with a visible
+  focus ring.
+- If this repo has a custom brand, confirm the screen picks it up.
+
+## Next
+
+- `/add-brand` — if the design is in a brand this repo does not have yet.
+- `/pull-from-figma` — if a designer changed brand colours in Figma and the code
+  needs to catch up.

package/skills/pull-from-figma/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: pull-from-figma
+description: Pull brand colour and font changes a designer made in Figma back into this repo's brand token files.
+disable-model-invocation: true
+---
+
+# Pull brand changes from Figma
+
+A designer retuned your brand's colours in Figma; bring those edits back into
+`brand/light.json`, `brand/dark.json`, and `brand/fonts.json`.
+
+**Direction:** Figma → Code. **Scope:** only your brand's `alias/*` tokens.
+Nothing is created or deleted — existing `$value` fields are updated in place.
+
+## Prerequisites
+
+1. This repo has a custom brand with modes pushed to Figma — run `/add-brand`
+   then `/push-to-figma` first.
+2. **Figma Console MCP** is configured and the Desktop Bridge plugin is running.
+   One-time setup:
+   `node_modules/@revikornmann/muka-ui/docs/consumers/figma-console-mcp.md`
+   (also online at
+   <https://github.com/revikornmann/muka/blob/main/docs/consumers/figma-console-mcp.md>).
+
+## Why only the alias layer
+
+Your repo owns exactly one layer of the token system. Semantics and component
+tokens come from the installed package and are overwritten on the next upgrade,
+so pulling them in would produce changes that silently disappear. If a designer
+changed `color/surface/level1` or a `button/*` variable, that is a **library**
+change: it belongs in a pull request against
+<https://github.com/revikornmann/muka>, and you should say so rather than writing
+it into `brand/`.
+
+## Step 1: Confirm the bridge is live
+
+```
+figma_get_status { probe: true }
+```
+
+## Step 2: Find your brand's modes
+
+Look collections and modes up by name — never hardcode IDs:
+
+```javascript
+const collections = await figma.variables.getLocalVariableCollectionsAsync();
+const theme = collections.find((c) => c.name === 'Theme');
+const light = theme.modes.find((m) => m.name === 'Acme Light').modeId;
+const dark = theme.modes.find((m) => m.name === 'Acme Dark').modeId;
+```
+
+## Step 3: Read the alias variables
+
+Read every variable whose name starts with `alias/`, taking the value for your
+two modes only. Ignore all other modes — they are other brands.
+
+## Step 4: Resolve each value back to a token reference
+
+- **Variable alias** (the normal case, pointing into Primitives): resolve the
+  target variable's name and convert slashes to dots.
+  `color/violet/9` → `{color.violet.9}`
+- **Concrete string** (font family or weight): keep the string, converting
+  Figma's style names back to CSS numerics — `SemiBold` → `600`, `Bold` → `700`,
+  `Medium` → `500`, `Regular` → `400`.
+- **Raw colour value**: this is a problem, not a value to pull. It means the
+  variable was detached from the ramp. Report it and re-push that token as an
+  alias instead of writing a hex into the token files, which would opt it out of
+  the system permanently.
+
+## Step 5: Map to files
+
+| Variable prefix | Target file |
+|---|---|
+| `alias/color/*` read at your **light** mode | `brand/light.json` |
+| `alias/color/*` read at your **dark** mode | `brand/dark.json` |
+| `alias/font/*` | `brand/fonts.json` |
+
+Figma slash-paths map to token dot-paths directly:
+`alias/color/accent/default` → `alias.color.accent.default`.
+
+## Step 6: Apply the diff
+
+For each token that already exists in the target file:
+
+1. Compare the current `$value` with the resolved Figma value.
+2. **Show the user the full diff before writing anything.**
+3. Update only `$value`. Never touch `$type`, and preserve the `$schema` entry
+   and key order so the diff stays reviewable.
+
+Safety rules:
+
+- Only tokens already present in the files are updated.
+- No tokens are created or deleted. A variable in Figma with no counterpart in
+  the files is reported, not added — it usually means the designer added
+  something that needs a code-side decision first.
+- A token missing from Figma is left alone, not blanked.
+
+## Step 7: Rebuild and check
+
+```bash
+npm run build:tokens
+```
+
+Then verify:
+
+- No `undefined` in `styles/tokens-<brand>-*.css` — a failed reference resolution.
+- Both light and dark still read correctly; a designer tuning light mode in
+  isolation is the usual way dark-mode contrast regresses.
+- Muka components pick up the change in the app.
+- The dark values reference `Dark` ramps (`{color.violetDark.9}`). If a dark
+  token came back pointing at a light ramp, the designer edited the wrong mode.
+
+Commit `brand/**` with a message naming what the designer changed.
+
+## Troubleshooting
+
+| Symptom | Cause |
+|---|---|
+| Values come back as raw colours | The variable was detached from the ramp — re-push it as an alias |
+| Everything appears unchanged | Reading the wrong modes; confirm the mode names match your brand |
+| Dark values reference light ramps | The wrong Figma mode was edited |
+| Semibold and bold pull the same weight | They were pushed as numerics and collapsed in Figma |
+| `figma-console` tools absent | Session predates `.mcp.json`; approve via `/mcp` and restart |

package/skills/push-to-figma/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: push-to-figma
+description: Push this repo's custom brand tokens into Figma as variables, so designers can design in your brand using the Muka UI Figma Library.
+disable-model-invocation: true
+---
+
+# Push your brand to Figma
+
+Publish this repo's brand layer (`brand/light.json`, `brand/dark.json`,
+`brand/fonts.json`) into Figma as variables, so designers see your brand in the
+Muka UI Figma Library instead of one of Muka's.
+
+**Direction:** Code → Figma. **The codebase is the source of truth.** Use
+`/pull-from-figma` for the other direction.
+
+## Prerequisites
+
+1. This repo has a custom brand — run `/add-brand` first.
+2. **Figma Console MCP** is configured and the Desktop Bridge plugin is running.
+   One-time setup:
+   `node_modules/@revikornmann/muka-ui/docs/consumers/figma-console-mcp.md`
+   (also online at
+   <https://github.com/revikornmann/muka/blob/main/docs/consumers/figma-console-mcp.md>).
+3. You can edit the target Figma file (your own copy or branch of the Muka UI
+   Figma Library).
+
+## What gets pushed, and what does not
+
+Only your **brand alias layer** — the ~78 `alias/color/*` tokens plus
+`alias/font/*`. That is the whole point: primitives, semantics, and component
+tokens belong to the Muka library and are inherited, exactly as in code.
+
+```
+component  (button/color/primary/background/default)  → library, do not touch
+semantic   (color/surface/level0, color/action/default) → library, do not touch
+alias      (alias/color/accent/default)               → YOURS, pushed here
+Primitives (color/violet/9)                           → library, raw values
+```
+
+If you find yourself pushing a `button/*` or `color/surface/*` variable, stop —
+that is a library-level change and belongs in a Muka pull request, not your
+brand.
+
+## Step 1: Confirm the bridge is live
+
+```
+figma_get_status { probe: true }
+```
+
+Expect `setup.valid: true`, `probeResult.success: true`, and the connected file
+name. If the tools are missing entirely, the session started before the MCP
+server was registered — restart it.
+
+## Step 2: Locate the collections
+
+Do **not** hardcode collection or mode IDs; look them up by name in the file you
+are connected to. Muka's own IDs differ in every copy and branch of the library.
+
+```javascript
+const collections = await figma.variables.getLocalVariableCollectionsAsync();
+for (const c of collections) {
+  console.log(c.name, c.id, c.modes.map((m) => `${m.name}=${m.modeId}`));
+}
+```
+
+You need two:
+
+- **Primitives** — the raw ramps (`color/violet/9`). One mode. Read-only for you.
+- **Theme** — one mode per brand/theme combination (`Muka Light`, `Muka Dark`, …).
+  This is where your brand's modes live.
+
+Build a name → id map across **both** collections; you will alias into Primitives
+by name.
+
+## Step 3: Add modes for your brand
+
+Your brand needs two modes in the Theme collection, named to match the existing
+convention:
+
+```javascript
+const theme = collections.find((c) => c.name === 'Theme');
+const lightModeId = theme.addMode('Acme Light');
+const darkModeId = theme.addMode('Acme Dark');
+```
+
+Skip this if the modes already exist — find them by name and reuse their
+`modeId`. Figma has a per-collection mode limit that depends on the plan; if
+`addMode` throws, the file has hit it and modes must be freed before continuing.
+
+## Step 4: Bind values — as aliases, never raw colours
+
+**This is the step that goes wrong.** Every alias token must be a variable
+**alias** pointing at a Primitive, not a resolved hex. A raw value is a
+disconnected duplicate: it will not cascade when the ramp is edited, and it
+drifts silently from your `{color.violet.9}` references in code.
+
+Your `brand/light.json` already stores exactly the reference you need
+(`{color.violet.9}` → the Primitives variable `color/violet/9`), so convert the
+path and bind:
+
+```javascript
+// '{color.violet.9}' → 'color/violet/9'
+const target = value.replace(/[{}]/g, '').split('.').join('/');
+
+const variable = await figma.variables.getVariableByIdAsync(aliasVarId);
+variable.setValueForMode(lightModeId, {
+  type: 'VARIABLE_ALIAS',
+  id: nameToId[target],
+});
+```
+
+Each mode gets a **different** Primitives target — light mode points at
+`color/violet/9`, dark mode at `color/violetDark/9`. Per-mode cross-collection
+aliases do cascade, and that is what makes mode switching work.
+
+> `figma_batch_create_variables` and `figma_batch_update_variables` accept only
+> scalar/hex `valuesByMode` — they **cannot** set alias bindings. Use them to
+> create bare variables in bulk, then bind in a separate `figma_execute` pass.
+
+Raw `{r, g, b, a}` values are correct only in the Primitives collection. If you
+ever must write one, pass an object — **never a hex string**, which drops the
+alpha channel and flattens the `black-alpha` / `white-alpha` ramps to opaque.
+
+## Step 5: Push the fonts
+
+`alias/font/*` variables are strings, not aliases, so set them directly — with
+two conversions:
+
+- **Family**: reduce a CSS stack to the single installed face name. Pushing
+  `'IBM Plex Sans', ui-sans-serif, system-ui` makes every bound text node render
+  as a **missing font**; push `IBM Plex Sans`.
+- **Weight**: Figma `fontStyle` bindings need style **names**, not the CSS
+  numerics your tokens hold — `600` → `SemiBold`, `700` → `Bold`, `500` →
+  `Medium`, `400` → `Regular`. Pushing numerics collapses semibold and bold onto
+  the same face.
+
+The font must be installed locally or available to the file, or every bound text
+node shows as missing.
+
+> Repairing a font-family variable that *already* holds a missing font is
+> blocked, because Figma cannot re-render bound text in a font that will not
+> load. Temporarily flip the consuming containers' mode
+> (`node.explicitVariableModes`), set the variable, then flip back. Do **not**
+> override `node.fontName` on bound instance text — that detaches the binding and
+> breaks the other modes.
+
+## Step 6: Verify
+
+1. **Every pushed token reads as an _Alias_** in the inspector — an alias pill,
+   not a colour swatch. Programmatically, assert every `valuesByMode` entry has
+   `type === 'VARIABLE_ALIAS'`. A swatch means Step 4 was done wrong.
+2. **Resolve and diff against the source.** Follow each alias to a concrete
+   colour and confirm it matches `styles/tokens-<brand>-light.css`. A
+   concatenated-hex checksum per variable across both modes is a cheap way to
+   compare in bulk.
+3. **Switch modes in Figma** and confirm the design visibly changes: your light
+   mode shows your accent colour, dark mode shows dark surfaces with readable
+   text.
+4. **Spot-check a component instance.** A primary Button in your mode should be
+   your accent colour, which proves the whole component → semantic → alias →
+   primitive chain resolved.
+
+## Troubleshooting
+
+| Symptom | Cause |
+|---|---|
+| Tokens show a colour swatch, not an alias pill | Pushed as raw hex — rebind per Step 4 |
+| Mode switching changes nothing | Every mode was bound to the same target; each needs its own |
+| Text renders as missing font | A CSS stack or an uninstalled family was pushed |
+| Semibold and bold look identical | Numeric weights were pushed instead of style names |
+| Transparency ramps look opaque | A hex string was pushed instead of `{r, g, b, a}` |
+| `figma-console` tools absent | Session predates `.mcp.json`; approve via `/mcp` and restart |

package/skills/setup-muka/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup-muka
-description: Set up a consumer repo to use Muka UI from npm — install the package, wire up the auto-update workflow, and register as a consumer.
+description: Install Muka UI in this repo from npm, wire up styles and fonts, add the auto-update workflow, and register as a consumer.
 disable-model-invocation: true
 argument-hint: "[brand]"
 ---
@@ -8,16 +8,17 @@ argument-hint: "[brand]"
 # Set up Muka UI in this repo
 
 Configure the current repo to consume the **public npm package**
-`@revikornmann/muka-ui` and stay current with releases automatically. The
-optional `$ARGUMENTS` is the brand to theme with (e.g. `fscl`, `grip`,
-`bouwplan`); default brand is `muka`.
+`@revikornmann/muka-ui`. The optional `$ARGUMENTS` is the brand to theme with
+(`muka`, `wireframe`, `grip`, `fscl`, `bouwplan`); default is `muka`.
 
 Muka UI is a public npm package — **no `.npmrc`, registry config, or auth token
-is required**. When the package is installed, the version-locked copy of these
-steps lives at
+is required**. Once installed, the version-locked copy of these steps lives at
 `node_modules/@revikornmann/muka-ui/docs/consumers/setup-instructions.md`; read
 it and prefer it when present, since it always matches the installed version.
 
+To build a **custom brand** for this repo instead of using one of Muka's five,
+finish this skill first and then run `/add-brand`.
+
 ## Step 1: Install the package
 
 If a previous git dependency exists (e.g.
@@ -39,26 +40,59 @@ npm ls @revikornmann/muka-ui   # or: pnpm why … / yarn why …
 
 ## Step 2: Import styles and components
 
-In the app's root/entry, import the stylesheet once, then components anywhere:
+In the app's root/entry, import one stylesheet, then components anywhere:
 
 ```ts
 import '@revikornmann/muka-ui/styles';
 import { Button, Card, Input } from '@revikornmann/muka-ui';
 ```
 
-For a brand theme, also import the brand token CSS and set the data attributes.
-Replace `<brand>` with `$ARGUMENTS` (or `muka`) and pick `light`/`dark`:
+`/styles` is the **`muka-light`** bundle: base styles, the muka-light tokens,
+every component's CSS, and muka's self-hosted fonts. Four pre-bundled
+alternatives ship alongside it and are drop-in replacements:
+
+```ts
+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 `grip`, `fscl`, or `bouwplan` there is no pre-bundled file, so compose it
+from three imports — base styles, the brand's raw token CSS, and the brand's
+fonts (the raw token CSS carries no `@font-face`):
 
 ```ts
+import '@revikornmann/muka-ui/styles/base.css';
 import '@revikornmann/muka-ui/styles/tokens-<brand>-light.css';
+import '@revikornmann/muka-ui/styles/fonts-<brand>.css';
 ```
 
-```html
-<html data-brand="<brand>" data-theme="light">
+### How brand and theme selection actually works
+
+Every token stylesheet declares its variables on `:root`. There are **no
+`[data-brand]` or `[data-theme]` selectors**, so you select a brand and theme by
+**choosing which stylesheet is loaded**, and importing two of them means the
+last one wins. Do not add `data-brand` / `data-theme` attributes expecting them
+to switch anything.
+
+For a runtime light/dark toggle, swap a `<link>` instead of importing both:
+
+```ts
+const link = document.getElementById('muka-theme') as HTMLLinkElement;
+link.href = `/styles/tokens-${brand}-${mode}.css`;
 ```
 
-Apps that already centralize CSS (e.g. a `src/styles/index.css`) may instead
-`@import '@revikornmann/muka-ui/styles/base.css'` and the brand token CSS there.
+Copy the brand's token CSS into the app's static/public directory (or let the
+bundler emit it with a stable URL) so those hrefs resolve. This is exactly what
+Muka's own Storybook does.
+
+### Fonts come from Muka — do not load them yourself
+
+Muka self-hosts every brand's fonts as `@font-face` backed by bundled WOFF2.
+Do **not** load them again via `next/font`, a Google Fonts `<link>`, or another
+loader, and do **not** override the `--alias-font-*-family` tokens — the token
+values are the exact `@font-face` family names, so overriding them only breaks
+resolution.
 
 ## Step 3: Add the auto-update workflow
 
@@ -82,6 +116,10 @@ lockfile, `lockfileVersion: 9.0` → pnpm 9). Without it, CI's corepack pulls th
 `minimumReleaseAge` default rejecting a just-published version). Add it if
 missing.
 
+Muka is under active development and a new version can change component
+behaviour or appearance. Keep CI checks in place so the update workflow's bump
+is reviewed rather than trusted.
+
 ## Step 4: Register this repo as a consumer
 
 So releases dispatch updates here, add `owner/repo` to Muka's
@@ -90,9 +128,31 @@ Open a PR against `revikornmann/muka` adding the line (skip if it is already
 listed). The Muka `CONSUMER_DISPATCH_TOKEN` PAT must have **write** access to
 this repo for the `repository_dispatch` to succeed.
 
+## Step 5: Give future agents the house rules
+
+```bash
+npx muka-ui init
+```
+
+This writes `AGENTS.md`, `CLAUDE.md`, and `docs/muka-ui-guidelines.md` into the
+repo (it prompts before overwriting any of them) so any agent working here knows
+to compose Muka components and use token custom properties instead of hardcoded
+values. It also warns about styling libraries that conflict with Muka.
+
+`AGENTS.md` carries the rules — it is the filename most agents read — and
+`CLAUDE.md` is a short pointer to it, so there is only one copy to keep current.
+
 ## Verify
 
 - `npm ls @revikornmann/muka-ui` shows a semver version resolved from npmjs.
 - The app builds/type-checks and Muka components render with brand tokens.
+- A component's computed `background-color` resolves to a real value, not the
+  `var(...)` fallback — that is the check that the token CSS actually loaded.
 - `.github/workflows/update-muka.yml` exists and is valid YAML.
 - This repo appears in Muka's `.github/consumers.txt` (or a PR is open for it).
+
+## Next
+
+- `/add-brand` — build a custom brand that overrides Muka's brand layer.
+- `/figma-to-code` — turn a Figma link into a screen built from Muka components.
+- `npx muka-ui install-skill --list` — every skill shipped with the package.

package/tokens/README.md

@@ -1,26 +1,37 @@
-`# Design Tokens
+# Design Tokens
 
 ## Directory Structure
 
 ```
 tokens/
-├── t1-primitives/         # Raw values: color.json, scale.json, typography.json
+├── t1-primitives/         # Raw values: color.json, scale.json, typography.json, motion.json
 ├── t2-alias/
 │   ├── base.json          # Brand-agnostic aliases
-│   ├── brand/
-│   │   ├── muka/          # fonts.json, light.json, dark.json
-│   │   ├── wireframe/     # fonts.json, light.json, dark.json
-│   │   └── grip/          # fonts.json, light.json, dark.json
+│   ├── brand/             # One directory per brand, each with fonts/light/dark.json
+│   │   ├── muka/          # + radius.json
+│   │   ├── wireframe/
+│   │   ├── grip/
+│   │   ├── fscl/
+│   │   └── bouwplan/
 │   └── layout/
 │       ├── mobile.json    # Mobile-first base (default)
 │       ├── tablet.json    # md breakpoint (768px) overrides
-│       └── desktop.json   # lg breakpoint (1024px) overrides
+│       ├── desktop.json   # lg breakpoint (1024px) overrides
+│       └── wide.json      # xl breakpoint (1280px) overrides
 ├── t3-semantics/          # ui.json — usage-intent tokens
-├── t4-components/         # 28 component token files
+├── t4-components/         # 35 component token files
 ├── $themes.json           # Tokens Studio theme config
 └── $metadata.json         # Token metadata
 ```
 
+Five brands × light/dark = **10 theme builds**, each emitting one
+`styles/tokens-<brand>-<theme>.css`. The authoritative list is
+`build/manifest.json`.
+
+The whole `tokens/` tree ships in the npm package, so consumers can build a
+custom brand against these primitives without forking. See
+`docs/consumers/brand.md`.
+
 ## Naming Convention
 
 ```
@@ -38,14 +49,18 @@ tokens/
 { "$value": "{color.gray.11}" }
 ```
 
+Dark-mode ramps append a **camelCase `Dark`** — `{color.mauveDark.1}`,
+`{color.indigoDark.9}`. References are case-sensitive, so `{color.mauvedark.1}`
+resolves to nothing.
+
 ## Inheritance Order
 
 1. T1 Primitives (base values)
 2. T2 Alias (brand-agnostic references)
 3. T3 Semantic (meaningful abstractions)
 4. T4 Component (component-specific)
-5. Brand overrides (muka/, wireframe/, grip/)
-6. Theme overrides (light.json, dark.json)
+5. Brand overrides (`brand/<name>/`)
+6. Theme overrides (`light.json`, `dark.json`)
 
 ## CSS Output
 
@@ -55,17 +70,23 @@ tokens/
 
 ## Brand/Theme Switching
 
-```html
-<html data-theme="light" data-brand="muka">
-```
+Every generated stylesheet declares its variables on `:root`, so the active
+brand and theme are determined by **which stylesheet is loaded** — there are no
+`[data-brand]` / `[data-theme]` selectors, and loading two means the last one
+wins.
+
+Storybook switches by swapping a `<link href>` (`.storybook/ThemeDecorator.ts`);
+consumers do the same, or import a single theme statically.
 
 ## Build Commands
 
 ```bash
-node scripts/build-tokens.js       # Build all tokens → CSS
-node scripts/export-for-figma.js   # Export for Figma Variables
-node scripts/export-for-penpot.js  # Export for Penpot
+npm run build:tokens               # Build all themes → styles/tokens-*.css
+npm run build:fonts                # Self-host brand fonts → styles/fonts-*.css
 npm run validate:tokens            # Validate JSON structure
+node scripts/export-figma-variables.js  # Export for Figma Variables
+node scripts/export-for-penpot.js       # Export for Penpot
+node scripts/export-for-webflow.js      # Export for Webflow
 ```
 
 ## Rules
@@ -92,5 +113,6 @@ to flow upward by reference; a brand file cannot override a `{component}.*` toke
 ## Human Docs
 <!-- SYNC: Update paths when Storybook docs change -->
 - Token architecture guide: stories/tokens/01-Introduction.mdx
-- Design Tokens in Storybook: stories/tokens/*.mdx (6 pages)
+- Design Tokens in Storybook: stories/tokens/*.mdx (7 pages)
+- Consumer brand guide: docs/consumers/brand.md
 - All Storybook docs: `npm run dev` → localhost:6006

package/tokens/t2-alias/brand/bouwplan/fonts.json

@@ -18,7 +18,7 @@
         "family": { "$type": "fontFamilies", "$value": "Red Hat Text" },
         "weight": {
           "regular": { "$type": "fontWeights", "$value": "400" },
-          "medium": { "$type": "fontWeights", "$value": "400" },
+          "medium": { "$type": "fontWeights", "$value": "500" },
           "semibold": { "$type": "fontWeights", "$value": "500" },
           "bold": { "$type": "fontWeights", "$value": "600" }
         }