@revikornmann/muka-ui 0.17.0 → 0.19.0

package/README.md

@@ -1,91 +1,112 @@
-# Muka Design System
+<img src=".storybook/public/logo-on-light.svg" alt="Muka UI" height="40" />
 
-A comprehensive design system that provides a consistent and scalable foundation for building user interfaces.
+# Muka UI
 
-## Overview
+A multi-brand, multi-theme React design system for mobile-first web apps, built
+so that coding agents can consume it accurately. Five brands × light and dark =
+**ten themes**, one component library, no per-brand component code.
 
-Muka is a design system that combines design tokens, components, and guidelines to create a cohesive user experience across different brands and platforms.
+- **Storybook:** <https://muka.kornmann.com> — component APIs, Playgrounds, token docs
+- **npm:** [`@revikornmann/muka-ui`](https://www.npmjs.com/package/@revikornmann/muka-ui)
+  (public — no registry config or auth token)
 
-## Key Features
+> **Under active development.** Releases can bring breaking changes — visual
+> shifts, changed component APIs, altered token values. Pin a version and
+> re-test your app when you upgrade.
 
-- **Design Tokens**: A robust token system for colors, typography, spacing, and more
-- **Component Library**: Reusable UI components built with design tokens
-- **Theme Support**: Light and dark mode support with brand-specific variations
-- **Responsive Design**: Built-in support for mobile, tablet, and desktop layouts
+## Use it in your app
 
-## Documentation
-
-- [Design Tokens](./tokens/README.md): Comprehensive documentation of our design token system
-- Components: Coming soon
-- Guidelines: Coming soon
-
-## Installation
-
-Muka is a **public npm package** published under the scoped name
-`@revikornmann/muka-ui` (the bare `muka-ui` name is taken on npm by an unrelated
-package). No registry config or auth token is needed.
+Five steps from an empty repo to a branded, designed, working app. Each one is a
+skill or a single command.
 
 ```bash
 npm install @revikornmann/muka-ui
+npx muka-ui install-skill        # make the Muka skills discoverable
 ```
 
-Import the stylesheet once in your app root, then components anywhere:
+Then, in Claude Code or Cursor:
 
-```ts
-import '@revikornmann/muka-ui/styles';
-import { Button, Card, Input } from '@revikornmann/muka-ui';
-```
+| # | Step | How |
+|---|---|---|
+| 1 | Create your repo | Any React app with a bundler that imports CSS |
+| 2 | Install and wire up Muka UI | `/setup-muka [brand]` |
+| 3 | Add your own brand, overriding Muka's brand layer | `/add-brand acme` |
+| 4 | Design against the Muka UI Figma Library | `/push-to-figma` to publish your brand to Figma |
+| 5 | Hand the Figma link to your agent | `/figma-to-code <figma-url>` |
+
+And voilà — a branded app built from a component library you didn't write, that
+follows brand changes centrally and updates itself on each release.
+
+**Full guide: [`docs/consumers/README.md`](docs/consumers/README.md).**
+
+### Skills shipped in the package
+
+| Skill | What it does |
+|---|---|
+| `/setup-muka` | Install the package, wire up styles and fonts, add the auto-update workflow, register as a consumer |
+| `/add-brand` | Create a custom brand in your repo that overrides Muka's brand layer |
+| `/figma-to-code` | Turn a Figma link into a screen composed from Muka components and tokens |
+| `/push-to-figma` | Publish your brand tokens to Figma as variables, so designers design in your brand |
+| `/pull-from-figma` | Bring a designer's brand edits in Figma back into your token files |
+
+`npx muka-ui install-skill --list` prints these from the installed version.
+
+`/push-to-figma` and `/pull-from-figma` read and write Figma **variables**, which
+the REST API cannot do, so they drive
+[**Figma Console MCP**](https://github.com/southleft/figma-console-mcp) — an
+open-source (MIT) MCP server by **[Southleft](https://southleft.com)**. It needs
+a one-time setup: [`docs/consumers/figma-console-mcp.md`](docs/consumers/figma-console-mcp.md).
+The other three skills don't require it.
 
-For a brand theme, also import the brand token CSS and set the data attributes
-(`<brand>` is e.g. `muka`, `fscl`, `grip`, `bouwplan`):
+Reference: [`docs/consumers/skills.md`](docs/consumers/skills.md).
+
+### Installing by hand
 
 ```ts
-import '@revikornmann/muka-ui/styles/tokens-<brand>-light.css';
+import '@revikornmann/muka-ui/styles';                 // muka-light, fonts included
+import { Button, Card, Input } from '@revikornmann/muka-ui';
 ```
 
-```html
-<html data-brand="<brand>" data-theme="light">
-```
+Other brands load a different stylesheet — `muka-dark`, `wireframe-light`, and
+`wireframe-dark` are pre-bundled; `grip`, `fscl`, and `bouwplan` compose from
+`base.css` + `tokens-<brand>-<mode>.css` + `fonts-<brand>.css`. Brand and theme
+are selected by **which stylesheet loads**, not by data attributes. See
+[`docs/consumers/setup-instructions.md`](docs/consumers/setup-instructions.md).
 
-### Fastest path: the `/setup-muka` skill
+## How the token system works
 
-If you use Claude Code / Cursor, let the skill wire everything up — install,
-styles, the auto-update workflow, and consumer registration:
+Four layers, each resolving through the one below:
 
-```bash
-npx muka-ui install-skill   # makes /setup-muka discoverable in .claude/skills
-# then in Claude Code:
-/setup-muka [brand]
-```
+| Layer | Purpose | Example |
+|---|---|---|
+| **T1 Primitives** | Raw ramps, never used directly | `color.indigo.9`, `spacing.4` |
+| **T2 Alias** | Brand-specific references — **the layer a brand swaps** | `alias.color.accent.default` |
+| **T3 Semantics** | Design intent | `color.surface.level1`, `color.action.default` |
+| **T4 Components** | Component-specific | `button.color.primary.background.default` |
+
+Components read T3 and T4 only. Swapping T2 cascades a whole new visual identity
+through the library, which is what makes both the five shipped brands and your
+own brand possible without touching component code.
 
-See [docs/consumers/README.md](docs/consumers/README.md) and
-[docs/consumers/setup-instructions.md](docs/consumers/setup-instructions.md) for
-the full consumer flow and the release-gated auto-update mechanism.
+Details: [`tokens/README.md`](tokens/README.md) and the Design Tokens section of
+the Storybook.
 
-## Getting Started (local development)
+## Contribute to Muka itself
 
 ```bash
-# Install dependencies
 npm install
-
-# Start development server
-npm run dev
+npm run build:tokens   # required before Storybook — postinstall does not do it
+npm run dev            # Storybook on port 6006
 ```
 
-## Project Structure
-
-```
-muka/
-├── tokens/           # Design tokens
-├── components/       # UI components
-├── styles/          # Global styles
-└── docs/            # Documentation
-```
+[`DEVELOPMENT.md`](DEVELOPMENT.md) is the maintainer guide: commands, token
+layers, component structure, CI, and releases. Maintainer skills live in
+[`.claude/skills/`](.claude/skills) and are not shipped to consumers.
 
-## Contributing
+## License
 
-Please read our [Contributing Guide](./CONTRIBUTING.md) for details on our code of conduct and the process for submitting pull requests.
+MIT.
 
-## License
+---
 
-This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
+Created by **Revi Körnmann** · [LinkedIn](https://linkedin.com/in/revikornmann) · [kornmann.com](https://kornmann.com)

package/cli/bin/muka-ui.js

@@ -5,7 +5,7 @@
  *
  * Commands:
  *   init              - Set up a project to use Muka UI
- *   install-skill     - Copy shipped skills into .claude/skills (e.g. /setup-muka)
+ *   install-skill     - Copy shipped skills into .claude/skills
  *   brand init <name> - Scaffold a custom brand override
  *   link [path]       - Set up npm link for local development
  *   components        - List available components
@@ -24,8 +24,8 @@ Usage:
   muka-ui <command> [options]
 
 Commands:
-  init              Set up project for Muka UI (creates CLAUDE.md, guidelines)
-  install-skill     Copy shipped skills into .claude/skills (e.g. /setup-muka)
+  init              Set up project for Muka UI (creates AGENTS.md, guidelines)
+  install-skill     Copy shipped skills into .claude/skills
   brand init <name> Scaffold a custom brand (T2 tokens, manifest, build script)
   link [path]       Set up npm link for local muka-ui development
   components        List available Muka UI components
@@ -35,11 +35,18 @@ Options:
   --version, -v     Show version
 
 Examples:
+  npx muka-ui install-skill --list    # what skills ship with the package
+  npx muka-ui install-skill           # install them, then run /setup-muka
   npx muka-ui init
-  npx muka-ui install-skill
-  npx muka-ui brand init fscl
+  npx muka-ui brand init acme
   npx muka-ui link /path/to/muka
   npx muka-ui components
+
+Typical flow:
+  npm install @revikornmann/muka-ui
+  npx muka-ui install-skill
+  /setup-muka            # in your agent
+  /add-brand acme        # optional: your own brand
 `;
 
 // Version from package.json

package/cli/commands/brand.js

@@ -19,24 +19,36 @@ const {
   readPackageJson
 } = require('../lib/fs-utils');
 
+// The published package name, read from the package's own manifest so the paths
+// written into a consumer repo stay correct if the package is ever renamed.
+const PACKAGE_ROOT = path.resolve(__dirname, '..', '..');
+const PACKAGE_NAME = JSON.parse(
+  fs.readFileSync(path.join(PACKAGE_ROOT, 'package.json'), 'utf8')
+).name;
+
 /**
  * Read a wireframe brand file as a template
  */
 function readBrandTemplate(filename) {
-  const templatePath = path.join(__dirname, '../../tokens/t2-alias/brand/wireframe', filename);
+  const templatePath = path.join(PACKAGE_ROOT, 'tokens/t2-alias/brand/wireframe', filename);
   return JSON.parse(fs.readFileSync(templatePath, 'utf8'));
 }
 
 /**
- * Generate the brand manifest for a consumer repo
+ * Generate the brand manifest for a consumer repo.
+ *
+ * Every layer except the brand's own T2 files is read straight out of
+ * node_modules, so the consumer only owns the brand layer and inherits
+ * primitives, semantics, and component tokens from the installed package.
  */
 function generateManifest(brandName) {
-  const t1 = 'node_modules/muka-ui/tokens/t1-primitives/**/*.json';
-  const base = 'node_modules/muka-ui/tokens/t2-alias/base.json';
+  const pkgTokens = `node_modules/${PACKAGE_NAME}/tokens`;
+  const t1 = `${pkgTokens}/t1-primitives/**/*.json`;
+  const base = `${pkgTokens}/t2-alias/base.json`;
   const fonts = `brand/fonts.json`;
-  const layout = 'node_modules/muka-ui/tokens/t2-alias/layout/mobile.json';
-  const semantics = 'node_modules/muka-ui/tokens/t3-semantics/ui.json';
-  const components = 'node_modules/muka-ui/tokens/t4-components/**/*.json';
+  const layout = `${pkgTokens}/t2-alias/layout/mobile.json`;
+  const semantics = `${pkgTokens}/t3-semantics/ui.json`;
+  const components = `${pkgTokens}/t4-components/**/*.json`;
 
   return {
     themes: {
@@ -50,8 +62,9 @@ function generateManifest(brandName) {
       ]
     },
     breakpoints: {
-      md: 'node_modules/muka-ui/tokens/t2-alias/layout/tablet.json',
-      lg: 'node_modules/muka-ui/tokens/t2-alias/layout/desktop.json'
+      md: `${pkgTokens}/t2-alias/layout/tablet.json`,
+      lg: `${pkgTokens}/t2-alias/layout/desktop.json`,
+      xl: `${pkgTokens}/t2-alias/layout/wide.json`
     }
   };
 }
@@ -61,7 +74,7 @@ function generateManifest(brandName) {
  */
 function generateBuildScript() {
   return `const path = require('path');
-const TokenBuilder = require('muka-ui/build');
+const TokenBuilder = require('${PACKAGE_NAME}/build');
 const manifest = require('./muka.brand.json');
 
 const builder = new TokenBuilder({ rootDir: path.resolve(__dirname, '..') });
@@ -183,13 +196,18 @@ async function brand(args) {
   console.log('');
   console.log('2. Build your brand CSS:');
   console.log('   npm run build:tokens');
+  console.log(`   → styles/tokens-${brandName}-light.css and -dark.css`);
   console.log('');
-  console.log(`3. Link the generated CSS in your HTML:`);
-  console.log(`   <link rel="stylesheet" href="/styles/tokens-${brandName}-light.css" />`);
+  console.log('3. Import your brand CSS AFTER the Muka base styles, so your brand');
+  console.log('   layer wins the cascade:');
+  console.log(`     import '${PACKAGE_NAME}/styles/base.css';`);
+  console.log(`     import './styles/tokens-${brandName}-light.css';`);
+  console.log('   Both files target :root, so the one imported last is the active');
+  console.log('   theme. To switch brand or mode at runtime, swap the stylesheet.');
   console.log('');
   console.log('4. Fonts: the family names in brand/fonts.json must be loaded somewhere.');
   console.log('   - Reusing a font Muka already ships? Import its fonts file, e.g.');
-  console.log("     import '@revikornmann/muka-ui/styles/fonts-muka.css';");
+  console.log(`     import '${PACKAGE_NAME}/styles/fonts-muka.css';`);
   console.log('   - Introducing your own font? Self-host it with your own @font-face');
   console.log('     under the exact family name you put in fonts.json (do NOT use a');
   console.log('     Google Fonts <link> in production — it breaks offline installs).');
@@ -198,7 +216,8 @@ async function brand(args) {
   console.log('  Colors use T1 primitives like {color.gray.9}, {color.indigo.11}');
   console.log('  Available palettes: gray, mauve, sand, indigo, iris, mint, jade,');
   console.log('  tomato, red, amber, green, blue, and more.');
-  console.log('  See node_modules/muka-ui/tokens/t1-primitives/color.json for all values.');
+  console.log(`  See node_modules/${PACKAGE_NAME}/tokens/t1-primitives/color.json`);
+  console.log('  for all values.');
   console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━\n');
 }
 

package/cli/commands/init.js

@@ -2,7 +2,8 @@
  * `muka-ui init` command
  *
  * Sets up a project for Muka UI usage:
- * - Creates CLAUDE.md with AI development guidelines
+ * - Creates AGENTS.md with the development guidelines every agent reads
+ * - Creates CLAUDE.md pointing at AGENTS.md, for Claude Code
  * - Creates docs/muka-ui-guidelines.md with usage documentation
  * - Checks for conflicting dependencies and warns
  */
@@ -95,21 +96,24 @@ async function init(args) {
   // Get template replacements
   const replacements = getReplacements();
 
-  // --- CLAUDE.md ---
-  const claudeMdPath = path.join(projectRoot, 'CLAUDE.md');
-  let createClaudeMd = true;
-
-  if (fileExists(claudeMdPath)) {
-    console.log('CLAUDE.md already exists.');
-    createClaudeMd = await confirm('Overwrite with Muka UI template?');
-  }
-
-  if (createClaudeMd) {
-    const claudeContent = loadTemplate('CLAUDE.md', replacements);
-    writeFile(claudeMdPath, claudeContent);
-    console.log('✓ Created CLAUDE.md\n');
-  } else {
-    console.log('⏭ Skipped CLAUDE.md\n');
+  // --- Agent briefs ---
+  // AGENTS.md holds the rules and is read by most agents; CLAUDE.md is a
+  // pointer to it so Claude Code finds them without a second copy to maintain.
+  for (const name of ['AGENTS.md', 'CLAUDE.md']) {
+    const target = path.join(projectRoot, name);
+    let write = true;
+
+    if (fileExists(target)) {
+      console.log(`${name} already exists.`);
+      write = await confirm('Overwrite with Muka UI template?');
+    }
+
+    if (write) {
+      writeFile(target, loadTemplate(name, replacements));
+      console.log(`✓ Created ${name}\n`);
+    } else {
+      console.log(`⏭ Skipped ${name}\n`);
+    }
   }
 
   // --- docs/muka-ui-guidelines.md ---
@@ -163,7 +167,7 @@ async function init(args) {
   console.log(`3. Browse components: ${manifest.storybook_url}`);
   console.log('');
   console.log('4. Stay current: run `npx muka-ui install-skill` then `/setup-muka`');
-  console.log('   in Claude Code — it adds the auto-update workflow and registers');
+  console.log('   in your agent — it adds the auto-update workflow and registers');
   console.log('   this repo as a consumer. (Or copy templates/update-muka.yml into');
   console.log('   .github/workflows/ by hand.)');
   console.log(`   See node_modules/${manifest.package_name}/docs/consumers/setup-instructions.md`);

package/cli/commands/install-skill.js

@@ -2,15 +2,16 @@
  * `muka-ui install-skill` command
  *
  * Copies the consumer-facing skills shipped inside the package (under
- * `skills/`) into the consuming repo's `.claude/skills/` so Claude Code can
- * discover them — most importantly `/setup-muka`.
+ * `skills/`) into the consuming repo's `.claude/skills/`, the directory Claude
+ * Code and Cursor both scan for skills.
  *
- * Claude Code only discovers skills under `.claude/skills/`, never inside
- * `node_modules/`, so a skill shipped in the package is present but not
- * discoverable until it is copied in. This command is that bridge.
+ * Agents discover skills under `.claude/skills/`, never inside `node_modules/`,
+ * so a skill shipped in the package is present but not discoverable until it is
+ * copied in. This command is that bridge.
  *
  *   npx muka-ui install-skill            # install all shipped skills
- *   npx muka-ui install-skill setup-muka # install a specific skill
+ *   npx muka-ui install-skill setup-muka # install specific skills
+ *   npx muka-ui install-skill --list     # show what is available
  */
 
 const path = require('path');
@@ -39,28 +40,63 @@ function listShippedSkills() {
   return fs
     .readdirSync(SHIPPED_SKILLS_DIR, { withFileTypes: true })
     .filter((d) => d.isDirectory() && fileExists(path.join(SHIPPED_SKILLS_DIR, d.name, 'SKILL.md')))
-    .map((d) => d.name);
+    .map((d) => d.name)
+    .sort();
+}
+
+/**
+ * Pull the `description:` line out of a skill's YAML frontmatter so `--list`
+ * can explain what each skill does without the caller opening the files.
+ */
+function describeSkill(skillName) {
+  const content = readFile(path.join(SHIPPED_SKILLS_DIR, skillName, 'SKILL.md'));
+  const match = content.match(/^description:\s*(.+)$/m);
+  return match ? match[1].trim() : '';
+}
+
+/**
+ * Every file in a skill directory, as paths relative to that directory. Skills
+ * may ship reference files alongside SKILL.md, and dropping them would leave
+ * the skill pointing at documentation that never arrived.
+ */
+function skillFiles(skillDir, prefix = '') {
+  const files = [];
+  for (const entry of fs.readdirSync(path.join(skillDir, prefix), { withFileTypes: true })) {
+    const relative = path.join(prefix, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...skillFiles(skillDir, relative));
+    } else if (entry.isFile()) {
+      files.push(relative);
+    }
+  }
+  return files;
 }
 
 /**
  * Copy one shipped skill into the project's .claude/skills directory.
- * Returns true if written, false if skipped.
+ * Returns true if anything was written, false if skipped.
  */
 async function installOne(skillName, projectRoot) {
-  const src = path.join(SHIPPED_SKILLS_DIR, skillName, 'SKILL.md');
-  if (!fileExists(src)) {
+  const srcDir = path.join(SHIPPED_SKILLS_DIR, skillName);
+  if (!fileExists(path.join(srcDir, 'SKILL.md'))) {
     console.log(`⚠️  No shipped skill named "${skillName}".`);
     return false;
   }
 
   const destDir = path.join(projectRoot, '.claude', 'skills', skillName);
-  const dest = path.join(destDir, 'SKILL.md');
+  const files = skillFiles(srcDir);
 
-  if (fileExists(dest)) {
-    if (readFile(dest) === readFile(src)) {
-      console.log(`✓ /${skillName} already up to date`);
-      return false;
-    }
+  const identical = files.every((file) => {
+    const dest = path.join(destDir, file);
+    return fileExists(dest) && readFile(dest) === readFile(path.join(srcDir, file));
+  });
+
+  if (identical) {
+    console.log(`✓ /${skillName} already up to date`);
+    return false;
+  }
+
+  if (dirExists(destDir)) {
     const overwrite = await confirm(`/${skillName} already exists. Overwrite?`);
     if (!overwrite) {
       console.log(`⏭ Skipped /${skillName}`);
@@ -68,20 +104,20 @@ async function installOne(skillName, projectRoot) {
     }
   }
 
-  ensureDir(destDir);
-  writeFile(dest, readFile(src));
-  console.log(`✓ Installed /${skillName} → .claude/skills/${skillName}/SKILL.md`);
+  for (const file of files) {
+    const dest = path.join(destDir, file);
+    ensureDir(path.dirname(dest));
+    writeFile(dest, readFile(path.join(srcDir, file)));
+  }
+
+  const extra = files.length > 1 ? ` (+${files.length - 1} reference file(s))` : '';
+  console.log(`✓ Installed /${skillName} → .claude/skills/${skillName}/${extra}`);
   return true;
 }
 
 async function installSkill(args) {
   console.log('\n🎨 Muka UI — install skills\n');
 
-  const projectRoot = findProjectRoot();
-  if (!projectRoot) {
-    throw new Error('Could not find package.json. Are you in a Node.js project?');
-  }
-
   const available = listShippedSkills();
   if (available.length === 0) {
     throw new Error(
@@ -90,8 +126,26 @@ async function installSkill(args) {
     );
   }
 
+  if (args && (args.includes('--list') || args.includes('-l'))) {
+    console.log('Shipped skills:\n');
+    for (const name of available) {
+      console.log(`  /${name}`);
+      const description = describeSkill(name);
+      if (description) console.log(`      ${description}`);
+    }
+    console.log('\nInstall all of them with: npx muka-ui install-skill');
+    console.log('Or just some:             npx muka-ui install-skill setup-muka add-brand\n');
+    return;
+  }
+
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) {
+    throw new Error('Could not find package.json. Are you in a Node.js project?');
+  }
+
   const requested = args && args.length > 0 ? args : available;
   let installed = 0;
+  const present = [];
   for (const name of requested) {
     if (!available.includes(name)) {
       console.log(`⚠️  "${name}" is not a shipped skill (available: ${available.join(', ')})`);
@@ -100,12 +154,16 @@ async function installSkill(args) {
     if (await installOne(name, projectRoot)) {
       installed += 1;
     }
+    present.push(name);
   }
 
   console.log('\n━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
   if (installed > 0) {
-    console.log('Done. Restart Claude Code if it is open, then run:');
-    console.log('   /setup-muka [brand]');
+    // Suggest a skill that is actually there — a partial install may not
+    // include /setup-muka.
+    const next = present.includes('setup-muka') ? '/setup-muka [brand]' : `/${present[0]}`;
+    console.log('Done. Restart your agent if it is open, then run:');
+    console.log(`   ${next}`);
   } else {
     console.log('Nothing to install — skills already present.');
   }