@revikornmann/muka-ui 0.18.0 → 0.20.0

package/cli/templates/AGENTS.md

@@ -0,0 +1,128 @@
+# Project Guidelines for AI Development
+
+> Generated by `muka-ui init` on {{DATE}}
+
+This is the vendor-neutral brief every coding agent reads. `CLAUDE.md` points
+here rather than repeating it, so there is one copy to keep current.
+
+---
+
+## UI Component Constraint
+
+**This project uses Muka UI as its sole component library. All UI must be built with components from muka-ui.**
+
+### Rules
+
+1. **Only use components available in Muka UI**
+   - Check availability at {{STORYBOOK_URL}}
+   - Import from `'{{PACKAGE_NAME}}'`
+
+2. **No alternative styling solutions for UI components**
+   - No Tailwind utilities for component styling
+   - No CSS modules for UI elements
+   - No styled-components or Emotion
+   - No inline styles except for layout (using Muka tokens)
+
+3. **When a component doesn't exist**
+   - Do NOT create a local component as a workaround
+   - Note the missing component as a blocker
+   - The component must be built in muka-ui first
+   - Once available in Storybook, it can be used here
+
+### Imports
+
+```tsx
+// Import components
+import { Button, Card, Input, Chip } from '{{PACKAGE_NAME}}';
+
+// Import styles (choose one theme) — these bundles include the brand's fonts
+import '{{PACKAGE_NAME}}/styles';                     // Default muka-light + muka fonts
+import '{{PACKAGE_NAME}}/styles/muka-dark.css';       // muka-dark + muka fonts
+import '{{PACKAGE_NAME}}/styles/wireframe-light.css'; // wireframe (system fonts)
+
+// For a brand loaded via its raw token file (e.g. bouwplan/grip/fscl), also import fonts:
+import '{{PACKAGE_NAME}}/styles/tokens-bouwplan-light.css';
+import '{{PACKAGE_NAME}}/styles/fonts-bouwplan.css';
+```
+
+### Fonts come from Muka — never load them yourself
+
+- Muka self-hosts every brand's fonts as `@font-face` (offline-ready, no CDN). The
+  default `/styles` bundle and the `/styles/muka-*.css` + `/styles/wireframe-*.css`
+  bundles already include them; only a brand loaded via a raw `tokens-<brand>-<mode>.css`
+  file needs a separate `{{PACKAGE_NAME}}/styles/fonts-<brand>.css` import.
+- Do NOT load these fonts via `next/font` or a Google Fonts `<link>`.
+- Do NOT override the `--*-fontFamily` / `--alias-font-*-family` tokens — their
+  values are the exact `@font-face` family names.
+
+### Acceptable Styling Patterns
+
+```tsx
+// ✅ GOOD: Use Muka UI components
+import { Button, Card } from '{{PACKAGE_NAME}}';
+
+// ✅ GOOD: Use Muka UI tokens for layout
+<div style={{
+  display: 'flex',
+  gap: 'var(--spacing-4)',
+  padding: 'var(--spacing-6)'
+}}>
+
+// ✅ GOOD: Use semantic color tokens
+<span style={{ color: 'var(--color-text-subtle-default)' }}>
+
+// ❌ BAD: Tailwind classes
+<div className="flex gap-4 p-6">
+
+// ❌ BAD: CSS modules
+import styles from './Component.module.css';
+
+// ❌ BAD: Arbitrary values
+<div style={{ color: '#6366f1', padding: '24px' }}>
+```
+
+---
+
+## Available Components
+
+{{COMPONENT_LIST}}
+
+For the full component API and examples, visit: {{STORYBOOK_URL}}
+
+---
+
+## Theme and brand selection
+
+Muka's token stylesheets are `:root`-scoped. There are **no `[data-brand]` or
+`[data-theme]` selectors**, so the active theme is whichever stylesheet loaded
+last. Do not add those attributes expecting them to switch anything — to toggle
+at runtime, swap a `<link href>` to a different `tokens-<brand>-<mode>.css`.
+
+If this repo has a `brand/` directory, it owns a **custom brand** that overrides
+Muka's brand layer. In that case:
+
+- Edit colours and fonts only in `brand/light.json`, `brand/dark.json`, and
+  `brand/fonts.json`, using `{color.*}` primitive references rather than hex.
+- Run `npm run build:tokens` after any change, and after every Muka upgrade.
+- Never edit semantic or component tokens — they come from `node_modules` and are
+  replaced on upgrade.
+
+---
+
+## Muka skills
+
+`npx muka-ui install-skill --list` shows the skills the installed version ships.
+`/add-brand` creates or revises this repo's brand; `/figma-to-code` turns a Figma
+link into a screen built from Muka components.
+
+Skills install to `.claude/skills/`, which is the directory Claude Code and
+Cursor both read. An agent that does not read that path can still follow the
+skills, since each is a plain markdown file — point it at
+`.claude/skills/<name>/SKILL.md`.
+
+## Human Docs
+<!-- SYNC: Update paths when Storybook docs change -->
+- Storybook: {{STORYBOOK_URL}}
+- Local guidelines: `docs/muka-ui-guidelines.md`
+- Consumer docs: `node_modules/{{PACKAGE_NAME}}/docs/consumers/README.md`
+- Package: {{PACKAGE_NAME}} v{{VERSION}}

package/cli/templates/CLAUDE.md

@@ -1,95 +1,15 @@
-# Project Guidelines for AI Development
+# CLAUDE.md
 
 > Generated by `muka-ui init` on {{DATE}}
 
----
+The guidelines for this project live in [`AGENTS.md`](AGENTS.md) — the
+vendor-neutral file every coding agent reads. Read it before writing UI code.
 
-## UI Component Constraint
-
-**This project uses Muka UI as its sole component library. All UI must be built with components from muka-ui.**
-
-### Rules
-
-1. **Only use components available in Muka UI**
-   - Check availability at {{STORYBOOK_URL}}
-   - Import from `'{{PACKAGE_NAME}}'`
-
-2. **No alternative styling solutions for UI components**
-   - No Tailwind utilities for component styling
-   - No CSS modules for UI elements
-   - No styled-components or Emotion
-   - No inline styles except for layout (using Muka tokens)
-
-3. **When a component doesn't exist**
-   - Do NOT create a local component as a workaround
-   - Note the missing component as a blocker
-   - The component must be built in muka-ui first
-   - Once available in Storybook, it can be used here
-
-### Imports
-
-```tsx
-// Import components
-import { Button, Card, Input, Chip } from '{{PACKAGE_NAME}}';
-
-// Import styles (choose one theme) — these bundles include the brand's fonts
-import '{{PACKAGE_NAME}}/styles';                     // Default muka-light + muka fonts
-import '{{PACKAGE_NAME}}/styles/muka-dark.css';       // muka-dark + muka fonts
-import '{{PACKAGE_NAME}}/styles/wireframe-light.css'; // wireframe (system fonts)
-
-// For a brand loaded via its raw token file (e.g. bouwplan/grip/fscl), also import fonts:
-import '{{PACKAGE_NAME}}/styles/tokens-bouwplan-light.css';
-import '{{PACKAGE_NAME}}/styles/fonts-bouwplan.css';
-```
-
-### Fonts come from Muka — never load them yourself
-
-- Muka self-hosts every brand's fonts as `@font-face` (offline-ready, no CDN). The
-  default `/styles` bundle and the `/styles/muka-*.css` + `/styles/wireframe-*.css`
-  bundles already include them; only a brand loaded via a raw `tokens-<brand>-<mode>.css`
-  file needs a separate `{{PACKAGE_NAME}}/styles/fonts-<brand>.css` import.
-- Do NOT load these fonts via `next/font` or a Google Fonts `<link>`.
-- Do NOT override the `--*-fontFamily` / `--alias-font-*-family` tokens — their
-  values are the exact `@font-face` family names.
-
-### Acceptable Styling Patterns
-
-```tsx
-// ✅ GOOD: Use Muka UI components
-import { Button, Card } from '{{PACKAGE_NAME}}';
-
-// ✅ GOOD: Use Muka UI tokens for layout
-<div style={{
-  display: 'flex',
-  gap: 'var(--spacing-4)',
-  padding: 'var(--spacing-6)'
-}}>
-
-// ✅ GOOD: Use semantic color tokens
-<span style={{ color: 'var(--color-text-subtle-default)' }}>
-
-// ❌ BAD: Tailwind classes
-<div className="flex gap-4 p-6">
-
-// ❌ BAD: CSS modules
-import styles from './Component.module.css';
-
-// ❌ BAD: Arbitrary values
-<div style={{ color: '#6366f1', padding: '24px' }}>
-```
-
----
-
-## Available Components
-
-{{COMPONENT_LIST}}
-
-For the full component API and examples, visit: {{STORYBOOK_URL}}
-
----
+It covers: Muka UI as the sole component library, the styling patterns that are
+and are not allowed, how fonts and theme selection work, and the Muka skills
+available in this repo.
 
 ## Human Docs
-<!-- SYNC: Update paths when Storybook docs change -->
+- Guidelines: `AGENTS.md`
 - Storybook: {{STORYBOOK_URL}}
-- Local guidelines: `docs/muka-ui-guidelines.md`
-- Package: {{PACKAGE_NAME}} v{{VERSION}}
+- Consumer docs: `node_modules/{{PACKAGE_NAME}}/docs/consumers/README.md`

package/cli/templates/muka-ui-guidelines.md

@@ -71,17 +71,25 @@ import '{{PACKAGE_NAME}}/styles/fonts-bouwplan.css';
 
 ### Theme Switching
 
-To support dynamic theme switching, import all themes and toggle via a CSS class or attribute:
+Every Muka 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 — importing two of them means one always wins.
+Setting `data-theme` does nothing.
 
-```tsx
-// In your root layout
-import '{{PACKAGE_NAME}}/styles/muka-light.css';
-import '{{PACKAGE_NAME}}/styles/muka-dark.css';
+For a runtime light/dark toggle, swap a `<link>` rather than importing both:
 
-// Apply theme via data attribute or class
-<html data-theme="muka-dark">
+```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 this project's static/public directory so those
+hrefs resolve. If the app only ever needs one theme, a plain import is simpler.
+
 ---
 
 ## Available Components
@@ -120,7 +128,8 @@ var(--spacing-12)  /* 3rem */
 /* Text */
 var(--color-text-default-default)
 var(--color-text-subtle-default)
-var(--color-text-inverse-default)
+var(--color-text-muted-default)
+var(--color-text-default-inverse)   /* on an inverted surface */
 
 /* Backgrounds */
 var(--color-surface-level1)
@@ -143,9 +152,16 @@ var(--color-action-pressed)
 ```css
 var(--alias-font-brand-family)
 var(--alias-font-brand-weight-semibold)
-var(--text-label-sm-fontSize)
-var(--text-label-md-fontSize)
-var(--text-label-lg-fontSize)
+
+/* Text styles are composite: --text-<role>-<size>-<weight>-<property>.
+   The weight is part of the name, so there is no --text-label-md-fontSize.
+   Weights: regular | semibold | bold
+   label sizes: xs sm md lg xl 2xl
+   body sizes:  xs sm base lg xl 2xl   (body uses "base", not "md") */
+var(--text-label-md-regular-fontSize)
+var(--text-label-md-semibold-lineHeight)
+var(--text-body-base-regular-fontSize)
+var(--text-body-base-regular-lineHeight)
 ```
 
 ---
@@ -159,16 +175,36 @@ If you need a component that doesn't exist in Muka UI:
 2. **Don't create a local workaround** — this defeats the purpose of using a design system
 
 3. **Request the component** by:
-   - Opening an issue in the muka-ui repository
-   - Or building it yourself in muka-ui and submitting a PR
+   - Opening an issue at https://github.com/revikornmann/muka/issues
+   - Or building it yourself in muka and submitting a PR
 
 4. **Wait for availability** — once the component is in Storybook, you can use it
 
 ---
 
+## Muka skills available in this repo
+
+Installed with `npx muka-ui install-skill` (run `--list` to see what the
+installed version ships):
+
+| Skill | Use it to |
+|---|---|
+| `/setup-muka` | Install and wire up Muka, including the auto-update workflow |
+| `/add-brand` | Give this repo its own brand, overriding Muka's brand layer |
+| `/figma-to-code` | Turn a Figma link into a screen composed from Muka components |
+| `/push-to-figma` | Publish this repo's brand to Figma as variables |
+| `/pull-from-figma` | Bring a designer's Figma brand edits back into the token files |
+
+The two Figma sync skills need [Figma Console
+MCP](https://github.com/southleft/figma-console-mcp); see
+`node_modules/{{PACKAGE_NAME}}/docs/consumers/figma-console-mcp.md`.
+
+---
+
 ## Human Docs
 <!-- SYNC: Update paths when Storybook docs change -->
 
 - **Storybook:** {{STORYBOOK_URL}}
-- **GitHub:** https://github.com/uxdelta/muka
+- **GitHub:** https://github.com/revikornmann/muka
+- **Consumer docs:** `node_modules/{{PACKAGE_NAME}}/docs/consumers/README.md`
 - **Package:** {{PACKAGE_NAME}} v{{VERSION}}

package/dist/cjs/components/ActionSheet/ActionSheet.css

@@ -56,10 +56,10 @@
   cursor: pointer;
   text-align: left;
   color: var(--color-text-default-default);
-  font-family: var(--text-body-md-regular-fontFamily);
-  font-weight: var(--text-body-md-regular-fontWeight);
-  font-size: var(--text-body-md-regular-fontSize);
-  line-height: var(--text-body-md-regular-lineHeight);
+  font-family: var(--text-body-base-regular-fontFamily);
+  font-weight: var(--text-body-base-regular-fontWeight);
+  font-size: var(--text-body-base-regular-fontSize);
+  line-height: var(--text-body-base-regular-lineHeight);
   -webkit-tap-highlight-color: transparent;
   transition: background-color 0.12s ease;
 }

package/dist/cjs/components/BottomBar/BottomBar.css

@@ -141,7 +141,6 @@
   font-weight: var(--text-label-sm-regular-fontWeight);
   font-size: var(--text-label-sm-regular-fontSize);
   line-height: var(--text-label-sm-regular-lineHeight);
-  letter-spacing: var(--text-label-sm-regular-letterSpacing);
 }
 
 /* ─── Floating modifier ───────────────────────────────── */
@@ -227,7 +226,6 @@
     font-weight: var(--text-label-md-regular-fontWeight);
     font-size: var(--text-label-md-regular-fontSize);
     line-height: var(--text-label-md-regular-lineHeight);
-    letter-spacing: var(--text-label-md-regular-letterSpacing);
   }
 
   /* When floating and sidebar, remove the floating card styles */
@@ -292,7 +290,6 @@
     font-weight: var(--text-label-md-regular-fontWeight);
     font-size: var(--text-label-md-regular-fontSize);
     line-height: var(--text-label-md-regular-lineHeight);
-    letter-spacing: var(--text-label-md-regular-letterSpacing);
   }
 
   /* When floating and topnav, remove the floating card styles */

package/dist/cjs/components/Breadcrumb/Breadcrumb.css

@@ -16,19 +16,36 @@
   gap: var(--spacing-1);
 }
 
+.muka-breadcrumb__item:has(.muka-breadcrumb__icon) {
+  padding-left: var(--spacing-1);
+}
+
 .muka-breadcrumb__icon {
   display: inline-flex;
   align-items: center;
   color: var(--color-text-subtle-default);
 }
 
+.muka-breadcrumb__icon .muka-icon {
+  color: inherit;
+}
+
+.muka-breadcrumb__item:has(.muka-breadcrumb__current) .muka-breadcrumb__icon {
+  color: var(--color-text-default-default);
+}
+
+.muka-breadcrumb__item:has(.muka-breadcrumb__link:hover) .muka-breadcrumb__icon {
+  color: var(--color-text-action-default);
+}
+
 /* Link styles */
 .muka-breadcrumb__link {
   color: var(--color-text-subtle-default);
   text-decoration: none;
   border: none;
   background: none;
-  padding: 0;
+  padding-inline: var(--spacing-2);
+  padding-block: 0;
   cursor: pointer;
   font: inherit;
   transition: color 0.15s ease;
@@ -39,10 +56,17 @@
   text-decoration: underline;
 }
 
-/* Current page (last item) */
+/* Tighter gap after leading icon */
+.muka-breadcrumb__item:has(.muka-breadcrumb__icon) .muka-breadcrumb__link,
+.muka-breadcrumb__item:has(.muka-breadcrumb__icon) .muka-breadcrumb__current {
+  padding-left: var(--spacing-1);
+}
+
+/* Current page (last item, no context switcher) */
 .muka-breadcrumb__current {
   color: var(--color-text-default-default);
   font-weight: 600;
+  padding-inline: var(--spacing-2);
 }
 
 /* Separator */