@revikornmann/muka-ui 0.18.0 → 0.20.0

package/docs/consumers/README.md

@@ -1,61 +1,140 @@
-# Consuming Muka UI in another repo
+# Using Muka UI in your app
 
-Muka UI is published as a **public package on npm** and released on a tag-gated
-cadence. Consumers install a specific version and stay current via an automated
-update workflow driven by GitHub Releases. Installing needs no registry config
-or auth token.
+Muka UI is a multi-brand, multi-theme React design system published as a
+**public package on npm**. Installing it needs no registry config or auth token.
 
-## Quick start
+These docs are for building an app **with** Muka. To work **on** Muka itself, see
+[`DEVELOPMENT.md`](../../DEVELOPMENT.md).
 
-The fastest path is the `/setup-muka` skill. Make it discoverable, then run it:
+## The workflow
+
+Five steps from an empty repo to a branded, designed, working app. Each one is a
+skill or a single command.
+
+```mermaid
+flowchart TD
+    repo["1. Create your repo"] --> install["2. Install Muka UI<br/>/setup-muka"]
+    install --> brand["3. Add your brand<br/>/add-brand"]
+    brand --> design["4. Design in Figma<br/>Muka UI Figma Library"]
+    design --> handover["5. Hand the Figma link to your agent<br/>/figma-to-code"]
+    handover --> app["A branded app built from<br/>Muka components"]
+    brand -.->|"designers need your brand"| push["/push-to-figma"]
+    push -.-> design
+    design -.->|"designer retunes the brand"| pull["/pull-from-figma"]
+    pull -.-> brand
+```
+
+### 1. Create your repo
+
+Any React app with a bundler that can import CSS — Vite, Next.js, Remix,
+webpack. React `>=16.8` is the only peer requirement.
+
+### 2. Install Muka UI
 
 ```bash
-npx muka-ui install-skill   # copies /setup-muka into .claude/skills
-# then in Claude Code / Cursor:
+npm install @revikornmann/muka-ui@latest
+npx muka-ui install-skill        # make the skills discoverable
+# then, in your agent:
 /setup-muka [brand]
 ```
 
-It installs Muka, sets up styles, adds the update workflow, and opens the
-consumer-registration PR for you.
+`/setup-muka` installs the package, imports the right stylesheet and fonts, adds
+the release auto-update workflow, and opens the PR that registers your repo as a
+consumer. Doing it by hand instead: [`setup-instructions.md`](setup-instructions.md).
 
-To do it by hand, follow [setup-instructions.md](setup-instructions.md):
+Muka ships five brands — `muka`, `wireframe`, `grip`, `fscl`, `bouwplan` — each
+in light and dark. If one of them fits, you can stop here.
 
-1. `npm install @revikornmann/muka-ui@latest`.
-2. Import `@revikornmann/muka-ui/styles` (+ brand token CSS) in your app root.
-3. Copy `templates/update-muka.yml` into `.github/workflows/`.
-4. Add the repo to [`.github/consumers.txt`](../../.github/consumers.txt).
+### 3. Add your brand
 
-## Release-gated update flow
+```
+/add-brand acme
+```
+
+This scaffolds a brand layer **in your repo** that overrides Muka's. You author
+about 78 colour references and four font families; primitives, semantics, and
+every component token keep coming from the package. One file of colour references
+restyles the entire component library, and there is no component code to change.
+
+Details and the token map: [`brand.md`](brand.md).
+
+### 4. Design in Figma
+
+Design against the [Muka UI Figma
+Library](https://www.figma.com/design/RL5IFLUJk4yeAFNXlsX4b5/Muka-UI-Figma-Library),
+so screens are assembled from the same components the code has, bound to the same
+variables the tokens generate.
+
+To let designers work in **your** brand, publish it to Figma as variables:
+
+```
+/push-to-figma
+```
 
-When a maintainer publishes a GitHub Release, [publish.yml](../../.github/workflows/publish.yml)
-builds and publishes the package to the public npm registry, then fires a
-`muka-released` `repository_dispatch` (carrying the version) to every repo in
-[`.github/consumers.txt`](../../.github/consumers.txt). Each consumer's
+When a designer retunes the brand there, bring it back with `/pull-from-figma`.
+Both need [Figma Console MCP](figma-console-mcp.md).
+
+### 5. Hand the Figma link to your agent
+
+```
+/figma-to-code https://figma.com/design/…?node-id=472-4248
+```
+
+Because the design is made of Muka components and the code has those same
+components, the agent's job is mapping rather than reinventing: it reads the Code
+Connect mapping, composes the screen from real components, and styles the gaps
+with token custom properties. The result inherits your brand and both themes for
+free.
+
+### And voilà
+
+A branded app built from a component library you did not have to write, that
+follows brand changes centrally and updates itself on each Muka release.
+
+## Reference
+
+| Doc | Contents |
+|---|---|
+| [`setup-instructions.md`](setup-instructions.md) | Canonical install, styles, fonts, theming, and auto-update setup |
+| [`brand.md`](brand.md) | Building your own brand on top of Muka's token layers |
+| [`skills.md`](skills.md) | Every shipped skill and what it is for |
+| [`figma-console-mcp.md`](figma-console-mcp.md) | One-time setup for the token-sync skills |
+
+Component APIs, live Playgrounds, and token documentation are in the Storybook at
+**<https://muka.kornmann.com>**.
+
+## Staying up to date
+
+When a maintainer publishes a GitHub Release,
+[`publish.yml`](../../.github/workflows/publish.yml) publishes to npm and fires a
+`muka-released` `repository_dispatch` (carrying the version) to every repo listed
+in [`.github/consumers.txt`](../../.github/consumers.txt). Your
 `update-muka.yml` installs that exact version and commits the lockfile bump.
 
 ```mermaid
 flowchart LR
     tag["Maintainer tags release"] --> publish["publish.yml builds + npm publish"]
-    publish --> pkg["npm registry (npmjs.org)"]
-    publish --> dispatch["repository_dispatch: muka-released (version)"]
-    dispatch --> update["consumer update-muka.yml"]
+    publish --> pkg["npm registry"]
+    publish --> dispatch["repository_dispatch: muka-released"]
+    dispatch --> update["your update-muka.yml"]
     update --> install["npm install @revikornmann/muka-ui@version"]
     install --> commit["Commit + push lockfile"]
-    commit --> deploy["Host redeploys (e.g. Vercel)"]
+    commit --> deploy["Host redeploys"]
 ```
 
-## Versioning
-
-- Consumers typically pin a caret range, e.g. `"@revikornmann/muka-ui": "^1.4.0"`.
-- The dispatch installs the **exact** published version, so bumps are predictable.
+- Pin a caret range, e.g. `"@revikornmann/muka-ui": "^0.18.0"`. The dispatch
+  installs the **exact** published version, so bumps are predictable.
 - Manual `workflow_dispatch` runs install `@latest`.
-- Develop freely on `main` — consumers are only notified on a published release.
-
-## Notes
-
-- The update only changes `package.json` + `package-lock.json`, so it never
+- The update only touches `package.json` and `package-lock.json`, so it never
   conflicts with app source.
-- `dist/` is built at publish time and shipped inside the tarball; it is not
+- `dist/` is built at publish time and shipped in the tarball; it is not
   committed to the Muka repo.
-- If you deploy on Vercel/Netlify, the push to your default branch triggers the
-  redeploy. The package is public, so the host needs no auth to install it.
+
+> **Muka is under active development.** A release can bring breaking changes —
+> visual shifts, changed component APIs, altered token values. Treat the update
+> workflow as a trigger to **re-test your app**, not a guarantee of stability.
+> Keep CI checks and visual review on the bump PR.
+>
+> If you maintain a custom brand, rebuild it after every upgrade: your brand CSS
+> is generated against the package's primitives and component tokens. See
+> [`brand.md`](brand.md#keeping-your-brand-current).

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`. |