@create-ui/cli 0.5.8 → 0.6.0

package/dist/skills/createui/cli.md

@@ -2,9 +2,9 @@
 
 Configuration is read from `components.json`.
 
-The CLI is published as **`@create-ui/cli`** and exposes the **`createui`** bin. Run it with `npx @create-ui/cli <command>` — or install it globally with `pnpm add -g @create-ui/cli` and then run `createui <command>`.
+The CLI is published as **`@create-ui/cli`** and exposes the **`createui`** bin. Run it with `npx @create-ui/cli <command>` - or install it globally with `pnpm add -g @create-ui/cli` and then run `createui <command>`.
 
-> **IMPORTANT:** Only use the flags documented below. Do not invent or guess flags — if a flag isn't listed here, it doesn't exist.
+> **IMPORTANT:** Only use the flags documented below. Do not invent or guess flags - if a flag isn't listed here, it doesn't exist.
 
 ## Contents
 
@@ -12,7 +12,7 @@ The CLI is published as **`@create-ui/cli`** and exposes the **`createui`** bin.
 - Templates: next, vite, start, next-monorepo
 - Registry & namespaces: the built-in `@createui` (the only registry)
 
-(The CLI also has `build` / `registry:build` commands for registry authors publishing their own items — not needed for using Create UI in an app.)
+(The CLI also has `build` / `registry:build` commands for registry authors publishing their own items - not needed for using Create UI in an app.)
 
 ---
 
@@ -20,7 +20,7 @@ The CLI is published as **`@create-ui/cli`** and exposes the **`createui`** bin.
 
 Program name `createui`. Description: "add items from registries to your project". Print the version with `-v, --version`.
 
-### `init` — Initialize your project and install dependencies
+### `init` - Initialize your project and install dependencies
 
 ```bash
 npx @create-ui/cli init [components...] [options]
@@ -30,50 +30,50 @@ Initializes Create UI in an existing project: writes `components.json`, installs
 
 | Flag                     | Short | Description                                                       | Default |
 | ------------------------ | ----- | --------------------------------------------------------------- | ------- |
-| `--template <template>`  | `-t`  | Template: `next`, `start`, `vite`, `next-monorepo`              | —       |
-| `--theme <theme>`        |       | Primary color theme: `indigo`, `blue`, `lime`, `green`, `red`, `orange`, `yellow`, `cyan` | —       |
-| `--neutral <neutral>`    |       | Neutral color theme: `gray`, `slate`, `zinc`, `base`, `stone`   | —       |
-| `--font-variant <v>`     |       | Font variant: `v1`                                              | —       |
-| `--base-color <color>`   | `-b`  | DEPRECATED — use `--theme` instead                             | —       |
+| `--template <template>`  | `-t`  | Template: `next`, `start`, `vite`, `next-monorepo`              | -       |
+| `--theme <theme>`        |       | Primary color theme: `indigo`, `blue`, `lime`, `green`, `red`, `orange`, `yellow`, `cyan` | -       |
+| `--neutral <neutral>`    |       | Neutral color theme: `gray`, `slate`, `zinc`, `base`, `stone`   | -       |
+| `--font-variant <v>`     |       | Font variant: `v1`                                              | -       |
+| `--base-color <color>`   | `-b`  | DEPRECATED - use `--theme` instead                             | -       |
 | `--yes`                  | `-y`  | Skip confirmation prompt                                        | `true`  |
 | `--defaults`             | `-d`  | Use default configuration                                       | `false` |
 | `--force`                | `-f`  | Force overwrite of existing config                             | `false` |
 | `--cwd <cwd>`            | `-c`  | Working directory                                              | current |
 | `--silent`               | `-s`  | Mute output                                                    | `false` |
-| `--src-dir`              |       | Use the `src` directory                                       | —       |
-| `--no-src-dir`           |       | Do not use the `src` directory                               | —       |
+| `--src-dir`              |       | Use the `src` directory                                       | -       |
+| `--no-src-dir`           |       | Do not use the `src` directory                               | -       |
 | `--css-variables`        |       | Use CSS variables for theming                                | `true`  |
-| `--no-css-variables`     |       | Do not use CSS variables for theming                        | —       |
-| `--no-base-style`        |       | Do not install the base Create UI style                      | —       |
+| `--no-css-variables`     |       | Do not use CSS variables for theming                        | -       |
+| `--no-base-style`        |       | Do not install the base Create UI style                      | -       |
 
 Pick a theme with `--theme` and `--neutral`; these are swappable token sets layered on the one Create UI system (there is no style/base split to choose).
 
-### `create` — Create a new project with Create UI
+### `create` - Create a new project with Create UI
 
 ```bash
 npx @create-ui/cli create [name] [options]
 ```
 
-Scaffolds a brand-new project. Anything not passed as a flag is prompted interactively: project name, template, then the theme choices (primary / neutral / font). `--preset` skips the theme prompts — bare `--preset` shows an interactive preset list, or pass a preset name/URL directly.
+Scaffolds a brand-new project. Anything not passed as a flag is prompted interactively: project name, template, then the theme choices (primary / neutral / font). `--preset` skips the theme prompts - bare `--preset` shows an interactive preset list, or pass a preset name/URL directly.
 
 | Flag                    | Short | Description                                   | Default |
 | ----------------------- | ----- | --------------------------------------------- | ------- |
-| `--template <template>` | `-t`  | Template: `next`, `start`, `vite`             | —       |
-| `--preset [name]`       | `-p`  | Use a preset configuration (interactive list if no name) | —       |
+| `--template <template>` | `-t`  | Template: `next`, `start`, `vite`             | -       |
+| `--preset [name]`       | `-p`  | Use a preset configuration (interactive list if no name) | -       |
 | `--cwd <cwd>`           | `-c`  | Working directory                             | current |
-| `--src-dir`             |       | Use the `src` directory                       | —       |
-| `--no-src-dir`          |       | Do not use the `src` directory                | —       |
+| `--src-dir`             |       | Use the `src` directory                       | -       |
+| `--no-src-dir`          |       | Do not use the `src` directory                | -       |
 | `--yes`                 | `-y`  | Skip confirmation prompt                      | `true`  |
 
 `create` scaffolds a **project**; it is not an alias for `init`. To set up Create UI inside an existing project, use `init`.
 
-### `add` — Add a component to your project
+### `add` - Add a component to your project
 
 ```bash
 npx @create-ui/cli add [components...] [options]
 ```
 
-Accepts bare names (`button`), full URLs, and local paths. There is no namespaced item form — `add @createui/button` does not resolve; always use the bare name.
+Accepts bare names (`button`), full URLs, and local paths. There is no namespaced item form - `add @createui/button` does not resolve; always use the bare name.
 
 | Flag                  | Short | Description                            | Default |
 | --------------------- | ----- | -------------------------------------- | ------- |
@@ -81,12 +81,12 @@ Accepts bare names (`button`), full URLs, and local paths. There is no namespace
 | `--overwrite`         | `-o`  | Overwrite existing files               | `false` |
 | `--cwd <cwd>`         | `-c`  | Working directory                      | current |
 | `--all`               | `-a`  | Add all available components           | `false` |
-| `--path <path>`       | `-p`  | The path to add the component to       | —       |
+| `--path <path>`       | `-p`  | The path to add the component to       | -       |
 | `--silent`            | `-s`  | Mute output                            | `false` |
-| `--src-dir`           |       | Use the `src` directory                | —       |
-| `--no-src-dir`        |       | Do not use the `src` directory         | —       |
+| `--src-dir`           |       | Use the `src` directory                | -       |
+| `--no-src-dir`        |       | Do not use the `src` directory         | -       |
 | `--css-variables`     |       | Use CSS variables for theming          | `true`  |
-| `--no-css-variables`  |       | Do not use CSS variables for theming   | —       |
+| `--no-css-variables`  |       | Do not use CSS variables for theming   | -       |
 
 ```bash
 # Add by name.
@@ -98,7 +98,7 @@ npx @create-ui/cli add https://createui.co/r/button.json
 
 To check whether installed components are out of date, use the `diff` command (below).
 
-### `diff` — Check for updates against the registry
+### `diff` - Check for updates against the registry
 
 ```bash
 npx @create-ui/cli diff [component] [options]
@@ -111,19 +111,19 @@ With no argument, lists the components that have updates available. With a compo
 | `--yes`       | `-y`  | Skip confirmation prompt | `false` |
 | `--cwd <cwd>` | `-c`  | Working directory        | current |
 
-### `view` — View items from the registry
+### `view` - View items from the registry
 
 ```bash
 npx @create-ui/cli view <items...> [options]
 ```
 
-Prints item metadata plus file contents (as JSON). Items are bare names or URLs, e.g. `button`.
+Prints item metadata plus file contents (as JSON). Items are bare names or URLs, e.g. `button`. Examples are registry items too - `view badge-demo` prints a component's canonical usage; check it (or the skill's `reference/<name>.md`) before the first use of a component.
 
 | Flag          | Short | Description       | Default |
 | ------------- | ----- | ----------------- | ------- |
 | `--cwd <cwd>` | `-c`  | Working directory | current |
 
-### `search` (alias: `list`) — Search items from registries
+### `search` (alias: `list`) - Search items from registries
 
 ```bash
 npx @create-ui/cli search <registries...> [options]
@@ -134,7 +134,7 @@ Searches one or more registries. Registry names must start with `@` (e.g. `@crea
 
 | Flag                | Short | Description            | Default |
 | ------------------- | ----- | ---------------------- | ------- |
-| `--query <query>`   | `-q`  | Search query           | —       |
+| `--query <query>`   | `-q`  | Search query           | -       |
 | `--limit <number>`  | `-l`  | Max items per registry | `100`   |
 | `--offset <number>` | `-o`  | Items to skip          | `0`     |
 | `--cwd <cwd>`       | `-c`  | Working directory      | current |
@@ -147,7 +147,7 @@ npx @create-ui/cli search @createui
 npx @create-ui/cli search @createui -q select
 ```
 
-### `migrate` — Run a migration
+### `migrate` - Run a migration
 
 ```bash
 npx @create-ui/cli migrate [migration] [options]
@@ -155,16 +155,16 @@ npx @create-ui/cli migrate [migration] [options]
 
 Available migrations:
 
-- `icons` — migrate a project from a legacy icon library (lucide / radix) to Create UI's `@create-ui/assets/icons` (Remix `Ri*`).
-- `radix` — migrate to `radix-ui`, consolidating `@radix-ui/react-*` imports into the unified `radix-ui` package.
+- `icons` - migrate a project from a legacy icon library (lucide / radix) to Create UI's `@create-ui/assets/icons` (Remix `Ri*`).
+- `radix` - migrate to `radix-ui`, consolidating `@radix-ui/react-*` imports into the unified `radix-ui` package.
 
 | Flag          | Short | Description              | Default |
 | ------------- | ----- | ------------------------ | ------- |
-| `--list`      | `-l`  | List available migrations | —       |
-| `--yes`       | `-y`  | Skip confirmation prompt | —       |
+| `--list`      | `-l`  | List available migrations | -       |
+| `--yes`       | `-y`  | Skip confirmation prompt | -       |
 | `--cwd <cwd>` | `-c`  | Working directory        | current |
 
-### `info` — Get information about your project
+### `info` - Get information about your project
 
 ```bash
 npx @create-ui/cli info [options]
@@ -176,7 +176,7 @@ Prints project information plus the contents of `components.json`. Run this firs
 | ------------- | ----- | ----------------- | ------- |
 | `--cwd <cwd>` | `-c`  | Working directory | current |
 
-### `mcp` — MCP server and configuration commands
+### `mcp` - MCP server and configuration commands
 
 ```bash
 # Start the stdio MCP server.
@@ -191,11 +191,11 @@ Running `createui mcp` starts the stdio MCP server. The `mcp init` subcommand wr
 | Subcommand / Flag       | Description                                                        | Default |
 | ----------------------- | ----------------------------------------------------------------- | ------- |
 | `mcp` `--cwd <cwd>`     | Working directory                                                 | current |
-| `mcp init --client <c>` | Client to configure: `claude`, `cursor`, `vscode`, `codex`, `opencode` | —       |
+| `mcp init --client <c>` | Client to configure: `claude`, `cursor`, `vscode`, `codex`, `opencode` | -       |
 
 See [mcp.md](./mcp.md) for the MCP server details, the available tools, and per-client config paths.
 
-### `skill` — Install the Create UI agent skill
+### `skill` - Install the Create UI agent skill
 
 ```bash
 npx @create-ui/cli skill
@@ -208,7 +208,7 @@ Installs this skill into the agent's skills directory (personal home directory b
 | ------------------- | ----- | -------------------------------------------------------------------- | -------- |
 | `--client <client>` |       | Agent to install for: `claude`, `gemini`, `codex`, `agents`          | `claude` |
 | `--project`         |       | Install into the project instead of the home directory               | `false`  |
-| `--path <path>`     | `-p`  | Install into an explicit skills directory (for other agents)         | —        |
+| `--path <path>`     | `-p`  | Install into an explicit skills directory (for other agents)         | -        |
 | `--cwd <cwd>`       | `-c`  | Working directory                                                    | current  |
 | `--force`           | `-f`  | Overwrite an existing skill installation                             | `false`  |
 | `--yes`             | `-y`  | Skip the overwrite confirmation prompt                               | `false`  |
@@ -230,12 +230,12 @@ The `init` `--template` option accepts:
 
 ## Registry & namespaces
 
-**`@createui` is the only registry.** It is built in — nothing to configure — and resolves item names to:
+**`@createui` is the only registry.** It is built in - nothing to configure - and resolves item names to:
 
 ```
 https://createui.co/r/{name}.json
 ```
 
-So `add button` fetches `https://createui.co/r/button.json`. Items are always referenced by **bare name**; the `@createui` name itself is only used as the registry argument to `search` / `list`. Never prefix item names with it — `view @createui/button` resolves to the literal path `…/r/@createui/button.json` and 404s.
+So `add button` fetches `https://createui.co/r/button.json`. Items are always referenced by **bare name**; the `@createui` name itself is only used as the registry argument to `search` / `list`. Never prefix item names with it - `view @createui/button` resolves to the literal path `…/r/@createui/button.json` and 404s.
 
 Never configure additional registries, add a `registries` field to `components.json`, or point the CLI at another registry host.

package/dist/skills/createui/customization.md

@@ -20,7 +20,7 @@ Create UI is **one styling system with many themes**. Components reference seman
 
 1. CSS variables are defined in `:root` (light) and overridden under `.dark` (dark mode), as **HEX** values.
 2. Tailwind v4 auto-generates utilities from those `--color-*` / `--spacing-*` / `--radius-*` variables (`bg-weakest`, `text-body`, `gap-component-sm`, …).
-3. Components consume those utilities — change a variable, or swap the active theme, and every component that references it updates.
+3. Components consume those utilities - change a variable, or swap the active theme, and every component that references it updates.
 
 There is no OKLCH, no `--primary`/`--muted` convention, and no parallel style/base stack. One system, layered themes.
 
@@ -36,7 +36,7 @@ Create UI uses **semantic** token names. Backgrounds, borders, and text share a
 | --- | --- |
 | `bg-weakest` … `bg-strongest` | Neutral surface scale (`weakest`, `weak`, `light`, `medium`, `heavy`, `strong`, `strongest`) |
 | `bg-static` | Page/card surface that swaps with theme (white in light, black in dark) |
-| `bg-static-white` / `bg-static-black` | Surfaces that never swap |
+| `bg-static-white` / `bg-static-black` | Theme-relative anchors that SWAP: `static-white` = white (light) / black (dark), `static-black` the inverse. For a surface that never swaps, use raw `bg-white` / `bg-black`. |
 | `border-weakest` … `border-strongest` | Border scale (use `border-light` / `border-medium` for inputs and dividers) |
 
 ### Text
@@ -47,7 +47,7 @@ Create UI uses **semantic** token names. Backgrounds, borders, and text share a
 | `text-placeholder` | Hints, secondary, muted text |
 | `text-disabled` | Disabled text |
 | `text-strongest` | High-contrast headings |
-| `text-static` / `text-static-white` | Text that never swaps with theme |
+| `text-static` / `text-static-white` | Theme-relative text anchors that SWAP (white in light, black in dark). For always-white text on a colored surface use raw `text-white`; for light text in a `dark` island use `text-strongest` / `text-body`. |
 
 ### Primary scale
 
@@ -55,7 +55,7 @@ Create UI uses **semantic** token names. Backgrounds, borders, and text share a
 
 ### Status families
 
-Each of `error`, `success`, `warning`, `info`, and `away` has a `-base` plus a `-weakest` … `-strongest` scale, e.g. `bg-error-base`, `text-error-base`, `outline-error-strongest`, `bg-success-base`, `bg-info-base`, `bg-away-base` (`away` backs the `variant="away"` of `Toast` / `InlineAlert` / `StatusBadge`). **Prefer the semantic status tokens** in your own code. The shipped Button implements its danger/success variants with the raw `red-*` / `green-*` scales (e.g. `bg-red-600`, `bg-red-alpha-16`) — that is the implementation detail, not a pattern you need to copy.
+Each of `error`, `success`, `warning`, `info`, and `away` has a `-base` plus a `-weakest` … `-strongest` scale, e.g. `bg-error-base`, `text-error-base`, `outline-error-strongest`, `bg-success-base`, `bg-info-base`, `bg-away-base` (`away` backs the `variant="away"` of `Toast` / `InlineAlert` / `StatusBadge`). **Prefer the semantic status tokens** in your own code. The shipped Button implements its danger/success variants with the raw `red-*` / `green-*` scales (e.g. `bg-red-600`, `bg-red-alpha-16`) - that is the implementation detail, not a pattern you need to copy.
 
 ### Shadows
 
@@ -107,6 +107,7 @@ Tailwind v4 also auto-generates spacing and typography utilities from `--spacing
 | Family | Utilities |
 | --- | --- |
 | component | `gap-component-none`, `gap-component-xs`, `gap-component-sm`, `p-component-md`, `gap-component-lg`, `p-component-xl`, `px-component-none` |
+| section | `gap-section-xs` … `gap-section-xl`, `p-section-*` (between clusters inside one section) |
 | layout | `gap-layout-xs`, `p-layout-sm`, `gap-layout-md`, `p-layout-lg`, `p-layout-xl` |
 
 **Figma-token rule:** use a semantic spacing class **only when Figma references a semantic token** (e.g. `var(--component/sm,8px)` → `gap-component-sm`). When Figma shows a static value (`space-space-4`), use the standard Tailwind class (`gap-4`). Prefer `px-component-none` over `px-0` when it is an intentional "no padding" override of a token.
@@ -115,13 +116,13 @@ Tailwind v4 also auto-generates spacing and typography utilities from `--spacing
 
 `text-display-{lg,xl}`, `text-heading-h1` … `text-heading-h6`, `text-body-{xs,sm,md,lg,xl}`, `text-paragraph-{xs…xl}`, `text-ui-{xs,sm,md,lg,xl}`, `text-ui-overline-*`, `text-ui-caption-*`, `text-numeric-{xs…xl}`.
 
-Spacing and typography tokens **auto-scale across breakpoints** — never add `md:` / `xl:` prefixes to `gap-component-sm`, `text-heading-h2`, and the like.
+Spacing and typography tokens **auto-scale across breakpoints** - never add `md:` / `xl:` prefixes to `gap-component-sm`, `text-heading-h2`, and the like.
 
 ---
 
 ## Theming
 
-One system, many themes. A theme is a swappable **token set** (a `registry:theme` item carrying a `primary` 50…950 palette), layered on the single foundation — it is not a style/base split and not a preset color.
+One system, many themes. A theme is a swappable **token set** (a `registry:theme` item carrying a `primary` 50…950 palette), layered on the single foundation - it is not a style/base split and not a preset color.
 
 - **Primary themes (8):** `indigo` (default), `blue`, `lime`, `green`, `red`, `orange`, `yellow`, `cyan`
 - **Neutral themes (5):** `gray` (default), `slate`, `zinc`, `base`, `stone`
@@ -133,7 +134,9 @@ Pick a theme at init, interactively or via flags:
 npx @create-ui/cli init --theme blue --neutral slate --font-variant v1
 ```
 
-`init` applies the choice by adding the matching registry items (`theme-<primary>`, `neutral-<neutral>`, `font-variant-<v>`). There is **no `apply` command** and **no preset codes** — to change theme later, re-run `init` with new flags or edit the token variables in your global CSS.
+`init` applies the choice by adding the matching registry items (`theme-<primary>`, `neutral-<neutral>`, `font-variant-<v>`). There is **no `apply` command** and **no preset codes** - to change theme later, re-run `init` with new flags (or, for an advanced hand-tweak, edit the token variables in your global CSS).
+
+> **Behavioral rule for agents:** the theme is ALREADY chosen by the time you build UI. Do **not** treat the brand color as an open design question: never ask the user "what theme/color", never offer a color palette, never invent a color (the 8 names above are the whole set - there is no `violet`/`purple`/etc.), and never rewrite the `--color-primary-*` token values to "apply" a look. Just use `bg-primary-base` / `text-primary-base` / `border-primary-*` and the chosen theme renders automatically. Only touch the theme when the user **explicitly** asks to change the whole project's theme - and then prefer re-running `init --theme <name>` over hand-editing hex.
 
 ---
 
@@ -149,13 +152,15 @@ import { ThemeProvider } from "next-themes"
 </ThemeProvider>
 ```
 
-Because every color is a token that already has a `.dark` override, **never write manual `dark:` color overrides** on components — let the tokens do the work.
+Because every color is a token that already has a `.dark` override, **never write manual `dark:` color overrides** on components - let the tokens do the work.
+
+> **`static` is theme-relative, not absolute.** `static` / `static-white` / `static-black` (and their `-alpha` variants) FLIP under `.dark` - e.g. `text-static-white` is white in light but **black in dark**; `static-black` is the inverse. They are surface anchors, not "always white/black." For a color that is fixed across themes (white text on a primary/colored surface, a brand mark) use the raw `white` / `black` palette. For light text inside an always-`dark` island, use `text-strongest` / `text-body` / `text-placeholder` (which resolve light under `.dark`), never `text-static` / `text-static-white`.
 
 ---
 
 ## Adding a Custom Color / Changing Radius
 
-Edit the project's global CSS file — the `tailwind.css` path reported by `createui info` (typically `app/globals.css`). **Never create a new CSS file** for this.
+Edit the project's global CSS file - the `tailwind.css` path reported by `createui info` (typically `app/globals.css`). **Never create a new CSS file** for this.
 
 Define the HEX scale under `:root` (and `.dark`), then expose it to Tailwind in the same file:
 
@@ -179,7 +184,7 @@ Tailwind v4 auto-generates the utilities (`bg-brand-500`, `text-brand-900`, …)
 <div className="bg-brand-50 text-brand-900">Brand surface</div>
 ```
 
-To restyle existing components, override the semantic tokens themselves (e.g. redefine the `primary` scale or a status family) rather than adding new ones. (There is no token build step to run — editing the CSS is the whole change.)
+To restyle existing components, override the semantic tokens themselves (e.g. redefine the `primary` scale or a status family) rather than adding new ones. (There is no token build step to run - editing the CSS is the whole change.)
 
 ---
 
@@ -217,8 +222,8 @@ import { Button } from "@/components/ui/button"
 If you need a new look, add it to the component's `cva` config in the source, using real Create UI tokens:
 
 ```tsx
-// components/ui/button.tsx — add to the buttonVariants config
-warning: "bg-warning-base text-static-white hover:bg-warning-strong",
+// components/ui/button.tsx - add to the buttonVariants config
+warning: "bg-warning-base text-white hover:bg-warning-strong",
 ```
 
 ### 4. Wrapper components
@@ -227,7 +232,7 @@ Compose Create UI primitives into higher-level components. Verify each primitive
 
 ```tsx
 import { RiLogoutBoxLine, RiSettingsLine, RiUserLine } from "@create-ui/assets/icons"
-import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"
+import { Avatar, AvatarImage, AvatarText } from "@/components/ui/avatar"
 import { Button } from "@/components/ui/button"
 import {
   DropdownMenu,
@@ -251,7 +256,7 @@ export function UserMenu({ name, avatarSrc, onSignOut, children }) {
         >
           <Avatar>
             <AvatarImage src={avatarSrc} alt={name} />
-            <AvatarFallback>{name.slice(0, 2)}</AvatarFallback>
+            <AvatarText>{name.slice(0, 2)}</AvatarText>
           </Avatar>
         </Button>
       </DropdownMenuTrigger>
@@ -298,4 +303,4 @@ When you re-add a component, pass `--overwrite` to replace local files:
 npx @create-ui/cli add button --overwrite
 ```
 
-See [Updating Components in SKILL.md](./SKILL.md#updating-components) for the full workflow.
+See the update workflow under [CLI quick reference in SKILL.md](./SKILL.md#cli-quick-reference) (prefer `diff`, and `add --overwrite` only with explicit approval).

package/dist/skills/createui/evals/evals.json

@@ -11,21 +11,21 @@
         "Uses Switch for independent on/off notification toggles (not looping Button with manual active state)",
         "Uses data-invalid on Field and aria-invalid on the input control for validation states",
         "Uses gap-* (e.g. gap-4, gap-6) instead of space-y-* or space-x-* for spacing",
-        "Uses Create UI semantic tokens (e.g. bg-static, text-body, text-placeholder, text-error-base) — never foreign tokens like bg-background/text-muted-foreground or raw colors like bg-red-500",
+        "Uses Create UI semantic tokens (e.g. bg-static, text-body, text-placeholder, text-error-base) - never foreign tokens like bg-background/text-muted-foreground or raw colors like bg-red-500",
         "No manual dark: color overrides (tokens swap via the .dark class)"
       ]
     },
     {
       "id": 2,
       "prompt": "Create an account menu component for the app header. The trigger is the user's avatar; the menu shows Profile, Billing, and Settings items with appropriate icons, then a separated Sign out item. Below the menu component, also add a Save changes button that shows a pending state while saving. Using Create UI.",
-      "expected_output": "A React component with DropdownMenu (trigger via asChild wrapping a Button + Avatar with AvatarFallback), DropdownMenuGroup/DropdownMenuSeparator structure, icons from @create-ui/assets/icons without sizing classes, and a Button using the loading prop.",
+      "expected_output": "A React component with DropdownMenu (trigger via asChild wrapping a Button + Avatar with AvatarText initials), DropdownMenuGroup/DropdownMenuSeparator structure, icons from @create-ui/assets/icons without sizing classes, and a Button using the loading prop.",
       "files": [],
       "expectations": [
         "Uses DropdownMenu with DropdownMenuTrigger asChild (Radix Slot) instead of hand-rolling a menu or using a popover (no popover component exists in Create UI)",
-        "Avatar component includes AvatarFallback",
+        "Avatar uses AvatarText for the initials fallback (AvatarFallback does not exist in Create UI)",
         "Menu items are wrapped in DropdownMenuGroup, with DropdownMenuSeparator before Sign out",
         "Icons are imported from @create-ui/assets/icons (Remix Ri*), never from lucide-react or another icon package",
-        "No sizing classes on icons inside components (no size-4, w-4, h-4, etc.) — the component sizes icons via CVA",
+        "No sizing classes on icons inside components (no size-4, w-4, h-4, etc.) - the component sizes icons via CVA",
         "Uses the Button loading prop for the pending Save state instead of manually composing a Spinner",
         "Button icons (if any) are passed via the leadingIcon/trailingIcon props (never a data-icon attribute, which does not exist in Create UI)"
       ]
@@ -36,13 +36,76 @@
       "expected_output": "A React component with stat tiles built from semantic-token markup (bg-static/border-light surfaces, text-placeholder label, text-strongest number), a Badge for the percentage change, a Spinner for the loading state, and gap-* spacing.",
       "files": [],
       "expectations": [
-        "Builds the stat tiles from semantic-token markup (e.g. bg-static or bg-weakest surface, border-light, text-placeholder for the label, text-strongest for the number) — there is no Card component in Create UI",
+        "Builds the stat tiles from semantic-token markup (e.g. bg-static or bg-weakest surface, border-light, text-placeholder for the label, text-strongest for the number) - there is no Card component in Create UI",
         "Uses the Spinner component for the loading state instead of a skeleton placeholder (no skeleton component exists in Create UI) or custom animate-pulse/animate-spin divs",
         "Uses a Badge (e.g. variant=\"success\" / \"danger\") for the percentage change instead of custom styled spans",
         "Uses Create UI semantic tokens (e.g. text-body, text-strongest, text-success-base) instead of foreign tokens or raw colors like bg-green-500",
         "Uses gap-* instead of space-y-* or space-x-* for spacing",
         "Uses size-* when width and height are equal instead of separate w-* h-*"
       ]
+    },
+    {
+      "id": 4,
+      "prompt": "Create a hero section for a product landing page: an eyebrow badge that says 'Now shipping - v1 components' with a sparkle icon, a large heading, a short description, and two CTA buttons (primary with a trailing arrow icon, secondary ghost). Using Create UI.",
+      "expected_output": "A hero section where the Badge gets its icon via the leadingIcon prop, buttons get icons via leadingIcon/trailingIcon, headings/body use semantic text tokens, and the badge does not stretch.",
+      "files": [],
+      "expectations": [
+        "Badge icon is passed via the leadingIcon prop (never as an icon child next to the text, e.g. <Badge><RiSparkling2Line />text</Badge> is wrong)",
+        "Button icons are passed via leadingIcon/trailingIcon props, never as children",
+        "Icons are imported from @create-ui/assets/icons (Remix Ri*), never lucide-react",
+        "No sizing classes on icons inside Badge or Button",
+        "Text uses semantic tokens (text-strongest for the heading, text-body/text-placeholder for the description), never raw palette colors",
+        "There is no variant=\"outline\"/\"secondary\"/\"destructive\" anywhere - outline looks come from appearance=\"outline\""
+      ]
+    },
+    {
+      "id": 5,
+      "prompt": "Create a settings page section with three tabs: Profile, Billing, and Notifications. Each tab shows its own panel of content. Using Create UI.",
+      "expected_output": "TabMenu + TabMenuItem for the tab bar with value/onValueChange state, and the panels rendered by the page itself keyed on the active value.",
+      "files": [],
+      "expectations": [
+        "Uses the TabMenu + TabMenuItem components for the tab bar - never a hand-rolled row of styled buttons or an invented Tabs/TabsList/TabsTrigger/TabsContent set",
+        "Panels are rendered by the consumer keyed on the active value (e.g. {tab === \"billing\" && <BillingPanel />}) - TabMenu has no content-panel component",
+        "Tab icons (if any) are passed via the leadingIcon prop on TabMenuItem",
+        "Selection is driven by value/onValueChange (or defaultValue), not by manual className toggling"
+      ]
+    },
+    {
+      "id": 6,
+      "prompt": "Add a monthly/yearly billing toggle to a pricing section. The active option's background should slide smoothly between the options. Show a '-20%' badge next to the yearly label. Using Create UI.",
+      "expected_output": "A SegmentedControl with appearance=\"grouped\" driven by value/onValueChange, plus a Badge for the discount.",
+      "files": [],
+      "expectations": [
+        "Uses SegmentedControl + SegmentedControlItem with value/onValueChange (or defaultValue) - never a row of Buttons with manual active state",
+        "Uses appearance=\"grouped\" for the classic padded pricing-toggle container (the active pill slides in both appearances)",
+        "The discount indicator is a Badge, not a custom styled span",
+        "An initial value is set (value or defaultValue) so one option is active on mount"
+      ]
+    },
+    {
+      "id": 7,
+      "prompt": "Create a notification preferences panel that feels premium for a marketing showcase: rows for Email, SMS, and Push notifications, each with a label, a description, and a toggle. Make the toggles feel rich, not bare. Using Create UI.",
+      "expected_output": "Field/SwitchGroup rows with Switch components that exercise the richer API (thumbIcon, ioTrigger, thumbType, or a deliberate variant), not bare <Switch /> defaults.",
+      "files": [],
+      "expectations": [
+        "Uses Switch (or SwitchGroup labelled rows - there is no SwitchGroupItem) - never a hand-rolled toggle",
+        "At least one richer Switch option is exercised: thumbIcon, ioTrigger, thumbType=\"long\", or a non-default variant - bare <Switch /> everywhere fails the 'premium' ask",
+        "Rows are laid out with Field orientation=\"horizontal\" + FieldLabel/FieldDescription (or SwitchGroup), not raw flex divs with hand-styled labels",
+        "Switch state is controlled via checked/onCheckedChange or defaultChecked"
+      ]
+    },
+    {
+      "id": 8,
+      "prompt": "Create a marketing site footer: brand column with a short description, three link columns (Product, Resources, Company), a newsletter signup, and a bottom bar with the copyright. Using Create UI.",
+      "expected_output": "A footer on neutral semantic surfaces (bg-static/bg-weak, border-light dividers) with TextLink columns, a Field + Input + Button newsletter form, and no raw palette colors.",
+      "files": [],
+      "expectations": [
+        "Footer surfaces use neutral semantic tokens (bg-static or bg-weak, border-light dividers) - never saturated raw palette colors (bg-blue-500, text-indigo-400) or hex values",
+        "Link columns use TextLink (or styled anchors with semantic text tokens like text-body/text-strongest), never primary-colored link soup",
+        "Newsletter form is FieldGroup/Field + Input + Button, not raw inputs",
+        "Spacing uses flex/grid + gap-*, never space-y-*",
+        "Column titles use text-strongest with body links in text-body/text-placeholder"
+      ]
     }
   ]
 }

package/dist/skills/createui/mcp.md

@@ -5,6 +5,7 @@ The Create UI MCP server lets AI assistants browse, search, and install componen
 ## Contents
 
 - [Setup](#setup)
+- [Recommended workflow for writing UI](#recommended-workflow-for-writing-ui)
 - [Available Tools](#available-tools)
 - [Usage Examples](#usage-examples)
 
@@ -45,9 +46,17 @@ The generated config always runs `npx @create-ui/cli mcp` (the package is `@crea
 }
 ```
 
+## Recommended workflow for writing UI
+
+1. `search_items_in_registries` / `list_items_in_registries` to find components.
+2. `view_items_in_registries` for an item's source and metadata.
+3. **`get_item_examples_from_registries` BEFORE writing usage code for a component you haven't used yet** - query `"<name>-demo"` (canonical usage), `"<name>-example"` (full gallery), or facet names like `"switch-thumb-icon"`, `"segmented-control-appearance"`, `"badge-with-icon"`. Create UI APIs differ from shadcn; the examples show the correct usage (icon props, composition, variants). The skill's `reference/<name>.md` files carry the same facts offline.
+4. `get_add_command_for_items` and run it - never import a component that hasn't been added.
+5. `get_audit_checklist` after generating code and fix anything it flags.
+
 ## Available Tools
 
-The MCP server exposes seven tools. **`@createui` is the only registry** — it is built in and needs no configuration, and there are no other registries to add. Wherever a tool takes a `registries` array, pass `["@createui"]`.
+The MCP server exposes seven tools. **`@createui` is the only registry** - it is built in and needs no configuration, and there are no other registries to add. Wherever a tool takes a `registries` array, pass `["@createui"]`.
 
 ### get_project_registries
 
@@ -60,7 +69,7 @@ Returns the registries configured in the current project's `components.json`.
 Lists all items available in the specified registries.
 
 **Inputs:**
-- `registries` (string[]) — registry namespaces to query
+- `registries` (string[]) - registry namespaces to query
 - `limit` (number, optional)
 - `offset` (number, optional)
 
@@ -76,14 +85,14 @@ Searches for items across registries by query string.
 
 ### view_items_in_registries
 
-Returns detailed information about specific items.
+Returns detailed information about specific items, including file contents. Component source alone does not show canonical usage - pair it with `get_item_examples_from_registries`.
 
 **Inputs:**
-- `items` (string[]) — bare item names, e.g. `button` (the MCP server also accepts a `@createui/` prefix and strips it)
+- `items` (string[]) - bare item names, e.g. `button` (the MCP server also accepts a `@createui/` prefix and strips it)
 
 ### get_item_examples_from_registries
 
-Finds example and demo code for items.
+Finds example and demo code for items with full source. Call it before the first use of any component. Useful query patterns: `{item}-demo`, `{item}-example`, and facet names like `switch-io-trigger` or `badge-with-icon`.
 
 **Inputs:**
 - `registries` (string[])