@revikornmann/muka-ui 0.17.0 → 0.19.0

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 |

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 |