@revikornmann/muka-ui 0.18.0 → 0.19.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/Combobox/Combobox.css

@@ -1,186 +1,170 @@
-/* Combobox Component Styles */
+/* Combobox — Figma Input Combobox (free-input chips + suggestion Menu) */
 
-/* ─── Trigger group (positioning context for the trailing controls) ── */
+.muka-combobox {
+  display: inline-flex;
+  flex-direction: column;
+  gap: var(--spacing-2);
+  min-width: 200px;
+}
 
-/*
- * The clear control is a sibling of the trigger, not a child (a <button> may
- * not contain interactive content), so it is overlaid on the trigger's trailing
- * padding. The trigger reserves that space with padding-right below.
- */
-.muka-combobox__trigger-group {
-  position: relative;
-  display: block;
+.muka-combobox--full-width {
   width: 100%;
 }
 
-/* ─── Trigger (looks like an Input field, behaves like a button) ── */
+.muka-combobox__label {
+  color: var(--color-text-default-default);
+  cursor: pointer;
+}
+
+.muka-combobox__label--sm {
+  font-family: var(--text-label-sm-semibold-fontFamily);
+  font-weight: var(--text-label-sm-semibold-fontWeight);
+  font-size: var(--text-label-sm-semibold-fontSize);
+  line-height: var(--text-label-sm-semibold-lineHeight);
+}
 
-.muka-combobox {
-  display: inline-flex;
+.muka-combobox__label--md {
+  font-family: var(--text-label-md-semibold-fontFamily);
+  font-weight: var(--text-label-md-semibold-fontWeight);
+  font-size: var(--text-label-md-semibold-fontSize);
+  line-height: var(--text-label-md-semibold-lineHeight);
+}
+
+.muka-combobox__label--lg {
+  font-family: var(--text-label-lg-semibold-fontFamily);
+  font-weight: var(--text-label-lg-semibold-fontWeight);
+  font-size: var(--text-label-lg-semibold-fontSize);
+  line-height: var(--text-label-lg-semibold-lineHeight);
+}
+
+.muka-combobox__field {
+  display: flex;
   align-items: center;
-  gap: var(--spacing-2);
   width: 100%;
-  padding: 0 var(--muka-combobox-trailing-space) 0 var(--input-field-padding-x);
+  position: relative;
+  isolation: isolate;
+  box-sizing: border-box;
   background-color: var(--input-field-color-default-background);
   border: var(--border-width-regular) solid var(--input-field-color-default-border);
-  color: var(--color-text-default-default);
-  text-align: left;
-  cursor: pointer;
-  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);
-  -webkit-tap-highlight-color: transparent;
-  transition: border-color 0.12s ease;
-
-  /* Room for the chevron overlaid on the trailing edge. */
-  --muka-combobox-trailing-space: calc(
-    var(--input-field-padding-x) + var(--icon-size-sm) + var(--spacing-2)
-  );
+  border-radius: var(--input-field-radius-lg);
+  padding: var(--spacing-2);
+  cursor: text;
+  transition: border-color 0.12s ease, background-color 0.12s ease;
 }
 
-/* …and for the clear button next to it, when one is rendered. */
-.muka-combobox--clearable {
-  --muka-combobox-trailing-space: calc(
-    var(--input-field-padding-x) + var(--icon-size-sm) + var(--spacing-2) +
-      var(--icon-size-xs) + var(--spacing-1) * 2 + var(--spacing-2)
-  );
+.muka-combobox__field::after {
+  content: '';
+  position: absolute;
+  inset: 0;
+  border-radius: inherit;
+  box-shadow: inset 0 1px 2px 0 rgba(26, 26, 26, 0.08);
+  pointer-events: none;
 }
 
-.muka-combobox--sm {
+.muka-combobox__field--sm {
   min-height: var(--input-field-height-sm);
   border-radius: var(--input-field-radius-sm);
 }
 
-.muka-combobox--md {
+.muka-combobox__field--md {
   min-height: var(--input-field-height-default);
   border-radius: var(--input-field-radius-md);
 }
 
-.muka-combobox--lg {
+.muka-combobox__field--lg {
   min-height: var(--input-field-height-lg);
   border-radius: var(--input-field-radius-lg);
 }
 
-.muka-combobox:hover:not(:disabled) {
-  border-color: var(--input-field-color-hover-border, var(--input-field-color-default-border));
+.muka-combobox__field--focused:not(.muka-combobox__field--disabled) {
+  border-width: var(--border-width-bold);
+  border-color: var(--input-field-color-focus-border);
+  background-color: var(--input-field-color-focus-background);
+  padding: calc(var(--spacing-2) - 1px);
 }
 
-.muka-combobox:focus-visible {
-  outline: none;
-  border-color: var(--input-field-color-focus-border, var(--color-action-default));
+.muka-combobox__field--error:not(.muka-combobox__field--disabled) {
+  border-color: var(--color-state-error-border, var(--color-state-error-foreground));
 }
 
-.muka-combobox--disabled,
-.muka-combobox:disabled {
+.muka-combobox__field--disabled {
   opacity: 0.5;
   cursor: not-allowed;
 }
 
-.muka-combobox--placeholder .muka-combobox__label {
-  color: var(--color-text-subtle-default);
-}
-
-.muka-combobox__leading {
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  flex-shrink: 0;
-  color: var(--color-text-subtle-default);
-}
-
-.muka-combobox__label {
-  flex: 1 1 auto;
-  min-width: 0;
-  white-space: nowrap;
-  overflow: hidden;
-  text-overflow: ellipsis;
+.muka-combobox__field--multiline {
+  align-items: flex-start;
+  min-height: 7rem;
 }
 
-/* ─── Trailing controls (clear + chevron) ─────────────── */
-
-.muka-combobox__actions {
-  position: absolute;
-  top: 0;
-  right: var(--input-field-padding-x);
-  height: 100%;
+.muka-combobox__chips {
   display: flex;
-  align-items: center;
+  flex: 1 1 auto;
+  flex-wrap: wrap;
   gap: var(--spacing-2);
-  /*
-   * The strip sits on top of the trigger, so it must not swallow taps meant to
-   * open the picker. Only the clear button takes pointer events back.
-   */
-  pointer-events: none;
-}
-
-.muka-combobox__clear,
-.muka-combobox__chevron {
-  display: inline-flex;
   align-items: center;
-  justify-content: center;
-  flex-shrink: 0;
-  color: var(--color-text-subtle-default);
+  min-width: 0;
+  width: 100%;
+  position: relative;
+  z-index: 1;
 }
 
-.muka-combobox__clear {
-  pointer-events: auto;
-  cursor: pointer;
-  padding: var(--spacing-1);
+.muka-combobox__input {
+  flex: 1 1 5rem;
+  min-width: 5rem;
+  min-height: 2rem;
+  margin: 0;
+  padding: 0 var(--spacing-1);
   border: none;
-  background: none;
-  border-radius: var(--radius-sm);
-  -webkit-tap-highlight-color: transparent;
-}
-
-.muka-combobox__clear:hover {
-  color: var(--color-text-default-default);
-  background-color: var(--color-surface-level1);
-}
-
-.muka-combobox__clear:focus-visible {
-  outline: 2px solid var(--color-border-focus);
-  outline-offset: 2px;
-  color: var(--color-text-default-default);
+  outline: none;
+  background: transparent;
+  color: var(--input-field-color-default-foreground);
+  caret-color: var(--input-field-color-default-foreground);
+  font-family: var(--text-label-md-regular-fontFamily);
+  font-size: var(--text-label-md-regular-fontSize);
+  font-weight: var(--text-label-md-regular-fontWeight);
+  line-height: var(--text-label-md-regular-lineHeight);
 }
 
-.muka-combobox--disabled ~ .muka-combobox__actions,
-.muka-combobox:disabled ~ .muka-combobox__actions {
-  opacity: 0.5;
+.muka-combobox__input::placeholder {
+  color: var(--color-text-subtle-default);
 }
 
-/* ─── Picker sheet body ───────────────────────────────── */
-
-.muka-combobox__picker {
-  display: flex;
-  flex-direction: column;
-  gap: var(--spacing-3);
-  padding: 0 var(--spacing-4) var(--spacing-4);
-  min-height: 0;
-  max-height: 80vh;
+.muka-combobox__helper {
+  margin: 0;
+  color: var(--color-text-subtle-default);
+  font-family: var(--text-label-sm-regular-fontFamily);
+  font-size: var(--text-label-sm-regular-fontSize);
+  font-weight: var(--text-label-sm-regular-fontWeight);
+  line-height: var(--text-label-sm-regular-lineHeight);
 }
 
-.muka-combobox__title {
+.muka-combobox__error {
   margin: 0;
-  padding: var(--spacing-2) 0;
-  color: var(--color-text-default-default);
-  font-family: var(--text-heading-sm-fontFamily);
-  font-weight: var(--text-heading-sm-fontWeight);
-  font-size: var(--text-heading-sm-fontSize);
-  line-height: var(--text-heading-sm-lineHeight);
+  color: var(--color-state-error-foreground);
+  font-family: var(--text-label-sm-regular-fontFamily);
+  font-size: var(--text-label-sm-regular-fontSize);
+  font-weight: var(--text-label-sm-regular-fontWeight);
+  line-height: var(--text-label-sm-regular-lineHeight);
 }
 
-.muka-combobox__search {
-  position: sticky;
-  top: 0;
-  z-index: 1;
-  padding-bottom: var(--spacing-2);
-  background-color: var(--color-surface-level3);
+.muka-combobox__menu-anchor {
+  position: absolute;
+  inset: 0;
+  z-index: 0;
+  width: 100%;
+  height: 100%;
+  margin: 0;
+  padding: 0;
+  border: none;
+  background: transparent;
+  pointer-events: none;
+  opacity: 0;
 }
 
-.muka-combobox__list {
-  flex: 1 1 auto;
-  min-height: 0;
-  overflow-y: auto;
-  -webkit-overflow-scrolling: touch;
+.muka-combobox__menu {
+  /* Prefer Menu token min-width (280px); may exceed the field when left-aligned. */
+  min-width: var(--menu-content-min-width);
+  width: max-content;
+  max-width: min(100vw - 2rem, 24rem);
 }