@revikornmann/muka-ui 0.17.0 → 0.19.0

package/docs/consumers/brand.md

@@ -0,0 +1,261 @@
+# Building your own brand
+
+Muka ships five brands. When none of them is yours, you can add your own **in
+your repo** without forking Muka: you author one layer of the token system and
+inherit the rest from the package.
+
+The fastest path is the [`/add-brand`](skills.md) skill, which walks an agent
+through everything below:
+
+```
+/add-brand acme
+```
+
+This document is the reference behind it.
+
+## What you own, and what you don't
+
+Muka's tokens are four layers deep. A brand is defined entirely by the second
+one:
+
+| Layer | Owner | Example |
+|---|---|---|
+| **T1 Primitives** | Package | `color.violet.9`, `spacing.4`, `size.md` |
+| **T2 Alias — base** | Package | brand-agnostic defaults |
+| **T2 Alias — brand** | **You** | `alias.color.accent.default` → `{color.violet.9}` |
+| **T3 Semantics** | Package | `color.surface.level1`, `color.action.default` |
+| **T4 Components** | Package | `button.color.primary.background.default` |
+
+Components read T3 and T4. Those resolve through T2. So repointing
+`alias.color.accent.default` at a different primitive changes every button, link,
+focus ring, and selection highlight in the library at once — with no component
+code, and no fork to maintain.
+
+It also means **you should never edit T3 or T4**. They come from `node_modules`
+and are replaced on every upgrade.
+
+## Scaffold it
+
+```bash
+npx muka-ui brand init acme
+```
+
+Brand names are lowercase, start with a letter, and contain only letters,
+numbers, and hyphens. This writes, prompting before overwriting anything:
+
+| Path | Contents |
+|---|---|
+| `brand/light.json` | Light-mode colour aliases — 78 tokens |
+| `brand/dark.json` | Dark-mode colour aliases |
+| `brand/fonts.json` | Font families and weights for four roles |
+| `brand/muka.brand.json` | Build manifest: your files plus the package's token globs |
+| `brand/build.js` | Build entry using `TokenBuilder` from the package |
+
+It also adds a `build:tokens` script to `package.json` if there isn't one.
+
+The files start as copies of Muka's `wireframe` brand, so they are complete and
+buildable rather than empty. Prove the pipeline before editing:
+
+```bash
+npm run build:tokens
+```
+
+Expect `All theme combinations built successfully!` and two new files in
+`styles/`. Debugging is far easier against known-good values.
+
+## The token groups
+
+All 78 colour tokens live under `alias.color`:
+
+| Group | Tokens | Effect |
+|---|---|---|
+| `neutral` | `1`–`12` plus `alphaHued.1`–`12` | Every surface, border, and text colour. The widest-reaching choice in the file. |
+| `accent` | `default`, `hover`, `pressed`, `contrast`, `muted`, and an `inverse.*` set | The interactive colour: buttons, links, focus rings, selection. Change this first. |
+| `brand` | `primary.*`, `secondary.*` | Identity colours for marketing surfaces, distinct from ordinary controls. |
+| `state` | `success`, `warning`, `error`, `info` — each with `contrast`/`default`/`muted` and four `surface` levels | Feedback colours. Keep the hues conventional. |
+| `conversation` | `own`, `peer`, `agent` surfaces and borders, plus `meta` | Chat components. Leave as scaffolded if your app has no chat — they still need to resolve. |
+
+## Write references, not colours
+
+Every value is a reference to a T1 primitive:
+
+```json
+"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}" }
+}
+```
+
+A raw hex works, but opts that token out of the system: it gains no dark-mode
+counterpart and stops tracking the ramp. Use references.
+
+### Available palettes
+
+12-step ramps. Light mode uses the base name; dark mode appends **camelCase
+`Dark`**, and references are case-sensitive — `{color.violetdark.9}` resolves to
+nothing.
+
+- **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`, `black-alpha`, `white-alpha`
+- **Hued neutral alphas:** `mauveA`, `grayA`, `sandA`, `sageA` (and their `Dark`
+  variants) back `neutral.alphaHued.*`
+
+Full values:
+`node_modules/@revikornmann/muka-ui/tokens/t1-primitives/color.json`.
+
+### What the steps mean
+
+| 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 |
+| 9–10 | Solid fills — 9 is the most saturated, 10 its hover |
+| 11 | Low-contrast text |
+| 12 | High-contrast text and headings |
+
+Put `accent.default` at 9, `hover` at 10, `pressed` at 11, `contrast` at 12
+unless you have a reason not to. Every shipped brand follows this.
+
+### Mirror it for dark mode
+
+`brand/dark.json` repeats the structure using the `Dark` ramps, keeping the
+**same step numbers**:
+
+```json
+"accent": {
+  "default": { "$type": "color", "$value": "{color.violetDark.9}" }
+}
+```
+
+The ramps are built so equal steps read as equal emphasis in either mode, which
+is what makes the mirror work.
+
+## Typography
+
+`brand/fonts.json` sets four roles:
+
+| Role | Used for |
+|---|---|
+| `brand` | Headings, buttons, labels |
+| `plain` | Body copy and UI text |
+| `mono` | Code and numeric tables |
+| `script` | Decorative accents only |
+
+`family` values must be the **exact `@font-face` family name** that gets loaded —
+the generated CSS passes the literal through to `font-family`. List only weights
+the font actually provides; naming an absent weight makes the browser synthesise
+it, which looks wrong at display sizes.
+
+### Loading the fonts
+
+Muka self-hosts its own brands' fonts, but that pipeline does not extend to your
+brand. You have three options:
+
+1. **Reuse a font Muka already bundles** — import that brand's fonts file and you
+   are done:
+   ```ts
+   import '@revikornmann/muka-ui/styles/fonts-muka.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 uses system fonts only.
+2. **Use a system font** — `Helvetica`, `Arial`, `Menlo`, `Georgia`,
+   `system-ui`, and friends need no loading.
+3. **Bring your own** — self-host it with your own `@font-face` under the exact
+   family name from `fonts.json`. Don't use a Google Fonts `<link>`: it breaks
+   offline and air-gapped installs and adds a render-blocking request.
+
+## Build and load the CSS
+
+```bash
+npm run build:tokens
+```
+
+This writes `styles/tokens-acme-light.css` and `styles/tokens-acme-dark.css` —
+complete stylesheets with every resolved token, around 2,200 custom properties
+each.
+
+Import your brand CSS **after** Muka's component and reset layer:
+
+```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
+```
+
+Use `base.css`, **not** `@revikornmann/muka-ui/styles`. The latter is the bundled
+`muka-light` theme: it contains a full token set that will fight your brand
+depending on import order.
+
+### Switching brand and theme
+
+Every token stylesheet declares its variables on `:root`. There are **no
+`[data-brand]` or `[data-theme]` selectors**, so the active theme is simply
+whichever stylesheet loaded last. Adding `data-brand` / `data-theme` attributes
+does nothing.
+
+For a runtime light/dark toggle, swap a `<link>` rather than importing both:
+
+```ts
+const link = document.getElementById('muka-theme') as HTMLLinkElement;
+link.href = `/styles/tokens-acme-${mode}.css`;
+```
+
+Copy the generated CSS into your static/public directory so those hrefs resolve.
+This is exactly how Muka's own Storybook switches between its ten themes.
+
+## Keeping your brand current
+
+Your brand CSS is generated against the package's primitives, semantics, and
+component tokens, so it goes stale when Muka publishes new ones — a new component
+in a release has tokens your last build never saw.
+
+Wire the rebuild into your pipeline so it can't be forgotten:
+
+```json
+"scripts": {
+  "build": "npm run build:tokens && vite build",
+  "postinstall": "npm run build:tokens"
+}
+```
+
+Commit `brand/**`. Generated `styles/tokens-*.css` can be committed or
+gitignored — commit it if your host has no build step.
+
+## Verify
+
+- Both CSS files exist and were rebuilt after your last edit.
+- Neither contains `undefined` — that is an unresolved reference, usually a
+  typo'd palette or a missing `Dark` suffix.
+- Your accent colour is really there:
+  ```bash
+  grep -- '--alias-color-accent-default' styles/tokens-acme-light.css
+  ```
+- A primary `<Button>` renders in your accent colour and body text in your
+  typeface, in both light and dark.
+- Dark mode changes surfaces without leaving text unreadable.
+
+## Troubleshooting
+
+| Symptom | Cause |
+|---|---|
+| `undefined` in the generated CSS | Unresolved `{reference}` — typo'd palette name or missing `Dark` suffix |
+| Dark mode looks like light mode | `dark.json` still references light ramps |
+| Colours unchanged after rebuilding | Brand CSS imported before Muka's token bundle. Import `base.css`, then your brand last |
+| Text unreadable on accent fills | `accent.contrast` too close to `accent.default` — move it to step 12 or `white` |
+| Fonts fall back to a system face | No `@font-face` loaded for that family, or the name doesn't match byte-for-byte |
+| `Cannot find module '…/build'` | Regenerate with `npx muka-ui brand init` from a current version; older scaffolds wrote an unscoped package name |
+| New components look unstyled after an upgrade | Brand CSS predates the release. Re-run `npm run build:tokens` |

package/docs/consumers/figma-console-mcp.md

@@ -0,0 +1,116 @@
+# Figma Console MCP — one-time setup
+
+The [`/push-to-figma`](../../skills/push-to-figma/SKILL.md) and
+[`/pull-from-figma`](../../skills/pull-from-figma/SKILL.md) skills sync your
+brand's design tokens between your repo and Figma. Both talk to Figma through
+**Figma Console MCP**, which relays commands to a **Desktop Bridge** plugin
+running inside Figma Desktop. This guide gets that pipeline working.
+
+```
+Your agent ──(MCP: figma-console)──► Desktop Bridge plugin ──► Figma Desktop (variables)
+```
+
+> **Credits:** [Figma Console MCP](https://github.com/southleft/figma-console-mcp)
+> is an open-source (MIT) MCP server by **[Southleft](https://southleft.com)**,
+> published on npm as
+> [`figma-console-mcp`](https://www.npmjs.com/package/figma-console-mcp). It is
+> not a Muka project — Muka only ships the skills that drive it. Please raise
+> issues with the server itself
+> [upstream](https://github.com/southleft/figma-console-mcp/issues).
+
+This is only needed for the two token-sync skills. `/setup-muka`, `/add-brand`,
+and `/figma-to-code` do not require it — `/figma-to-code` works with Figma's own
+official MCP server, which is a separate thing.
+
+## 1. Get a Figma access token
+
+Create a personal access token in Figma (**Settings → Security → Personal access
+tokens**) with **Variables** read/write scope. It looks like `figd_…`.
+
+**Do not paste it into any file.** Keep it in your shell environment:
+
+```bash
+# ~/.zshrc (or ~/.bashrc)
+export FIGMA_ACCESS_TOKEN="figd_your_token_here"
+```
+
+Open a new shell (or `source` the file) so the variable is set.
+
+## 2. Register the server
+
+Add a project-scoped `.mcp.json` at your repo root. It uses **env expansion**, so
+no secret lives in the file and it is safe to commit:
+
+```json
+{
+  "mcpServers": {
+    "figma-console": {
+      "command": "npx",
+      "args": ["-y", "figma-console-mcp@latest"],
+      "env": {
+        "FIGMA_ACCESS_TOKEN": "${FIGMA_ACCESS_TOKEN}",
+        "ENABLE_MCP_APPS": "true"
+      }
+    }
+  }
+}
+```
+
+Because it is project-scoped, **Claude Code asks you to approve the
+`figma-console` server** the first time it reads `.mcp.json` (run `/mcp` to
+review and approve). Approve it, then **restart the session** — `.mcp.json` is
+only read at startup, so adding or editing it mid-session will not surface the
+tools.
+
+Need machine-specific overrides? Put them in `.mcp.local.json` and gitignore
+that path. Never inline a `figd_…` token in a committed file.
+
+## 3. Install the Desktop Bridge plugin
+
+The plugin files are written to `~/.figma-console-mcp/plugin/` the first time the
+server runs. Find the exact path with:
+
+```bash
+npx figma-console-mcp@latest --print-path
+```
+
+In **Figma Desktop**: `Plugins → Development → Import plugin from manifest…` →
+select `~/.figma-console-mcp/plugin/manifest.json`. Then open the file you want
+to edit and run `Plugins → Development → Figma Desktop Bridge` to connect it.
+
+The bridge needs **Figma Desktop**; it does not work in the browser.
+
+## 4. Verify
+
+From your agent, once the server is loaded:
+
+```
+figma_get_status { probe: true }
+```
+
+A healthy result reports `setup.valid: true`, `probeResult.success: true`, and
+the connected file name. `figma_list_open_files` shows which file the plugin is
+bridged to.
+
+## Which Figma file to connect
+
+Point the bridge at **your own copy or branch** of the Muka UI Figma Library, not
+the shared library itself. Your brand is your brand — pushing modes into the
+upstream library affects every other consumer.
+
+Duplicate the [Muka UI Figma
+Library](https://www.figma.com/design/RL5IFLUJk4yeAFNXlsX4b5/Muka-UI-Figma-Library)
+into your own team, or work on a branch of it, then connect the bridge there.
+
+The skills discover collections and modes **by name**, so a duplicate works
+without any ID configuration.
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `figma-console` tools don't appear | The session predates `.mcp.json`. Approve it via `/mcp` and restart the session. |
+| `FIGMA_ACCESS_TOKEN` unset | `${FIGMA_ACCESS_TOKEN}` expanded to empty. Export it and restart the session. |
+| Probe fails / no connected file | Open the target file in Figma Desktop and run the Desktop Bridge plugin, then re-check `figma_get_status { probe: true }`. |
+| Permission error writing variables | The token lacks Variables write scope, or you only have view access to the file. |
+| Pushed values show as raw swatches | They were written as hex instead of variable aliases. See Step 4 and Step 6 of `/push-to-figma`. |

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.17.0",
+  "version": "0.19.0",
   "description": "Muka Design System - Multi-brand design tokens and React components",
   "main": "dist/cjs/components/index.js",
   "module": "dist/esm/components/index.js",
@@ -69,8 +69,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 +106,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 +136,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
 `);