@revikornmann/muka-ui 0.17.0 → 0.19.0

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
@@ -91,6 +112,7 @@ 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: components/Documentation/TokenArchitecture.mdx
-- Design Tokens in Storybook: stories/tokens/*.mdx (6 pages)
+- Token architecture guide: stories/tokens/01-Introduction.mdx
+- 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" }
         }

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

@@ -18,9 +18,9 @@
         "family": { "$type": "fontFamilies", "$value": "'IBM Plex Sans', ui-sans-serif, system-ui, sans-serif" },
         "weight": {
           "regular": { "$type": "fontWeights", "$value": "400" },
-          "medium": { "$type": "fontWeights", "$value": "400" },
-          "semibold": { "$type": "fontWeights", "$value": "400" },
-          "bold": { "$type": "fontWeights", "$value": "400" }
+          "medium": { "$type": "fontWeights", "$value": "500" },
+          "semibold": { "$type": "fontWeights", "$value": "500" },
+          "bold": { "$type": "fontWeights", "$value": "600" }
         }
       },
       "mono": {

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

@@ -6,7 +6,7 @@
   "alias": {
     "font": {
       "brand": {
-        "family": { "$type": "fontFamilies", "$value": "Helvetica" },
+        "family": { "$type": "fontFamilies", "$value": "Roboto" },
         "weight": {
           "regular": { "$type": "fontWeights", "$value": "400" },
           "medium": { "$type": "fontWeights", "$value": "500" },
@@ -15,7 +15,7 @@
         }
       },
       "plain": {
-        "family": { "$type": "fontFamilies", "$value": "Helvetica" },
+        "family": { "$type": "fontFamilies", "$value": "Roboto" },
         "weight": {
           "regular": { "$type": "fontWeights", "$value": "400" },
           "medium": { "$type": "fontWeights", "$value": "500" },

package/tokens/t4-components/menu.json

@@ -12,7 +12,7 @@
         },
         "border": {
           "$type": "color",
-          "$value": "{color.border.muted}"
+          "$value": "{color.border.contrast}"
         }
       },
       "border": {
@@ -35,11 +35,15 @@
       },
       "min-width": {
         "$type": "dimension",
-        "$value": "12rem"
+        "$value": "280px"
       },
       "max-height": {
         "$type": "dimension",
         "$value": "20rem"
+      },
+      "scroll-height": {
+        "$type": "dimension",
+        "$value": "20.625rem"
       }
     },
     "item": {
@@ -61,7 +65,7 @@
         "hover": {
           "background": {
             "$type": "color",
-            "$value": "{color.surface.hover}"
+            "$value": "{color.surface.level2}"
           },
           "foreground": {
             "$type": "color",
@@ -75,7 +79,7 @@
         "focus": {
           "background": {
             "$type": "color",
-            "$value": "{color.action.muted}"
+            "$value": "{color.surface.level2}"
           },
           "foreground": {
             "$type": "color",
@@ -86,6 +90,12 @@
             "$value": "{color.text.default.default}"
           }
         },
+        "selected": {
+          "background": {
+            "$type": "color",
+            "$value": "{color.surface.level1}"
+          }
+        },
         "disabled": {
           "background": {
             "$type": "color",
@@ -138,9 +148,14 @@
           "$type": "dimension",
           "$value": "{spacing.3}"
         },
+        "right": {
+          "$type": "dimension",
+          "$value": "{spacing.9}",
+          "$description": "Reserve trailing-icon gutter (Figma Dropdown Menu Item). Icons float in this space so hover/selected trailers do not change wrapping."
+        },
         "y": {
           "$type": "dimension",
-          "$value": "{spacing.2}"
+          "$value": "{spacing.3}"
         }
       },
       "gap": {