@create-ui/cli 0.5.9 → 0.6.1

package/dist/mcp/index.js

@@ -1,2 +1,2 @@
-export{b as server}from'../chunk-643QI2I2.js';import'../chunk-2ELKDGGM.js';import'../chunk-KQTXDVKV.js';import'../chunk-Y7WZRQWW.js';//# sourceMappingURL=index.js.map
+export{b as server}from'../chunk-OITQ46YK.js';import'../chunk-OGAWGP7T.js';import'../chunk-KFQXWKJJ.js';import'../chunk-Y7WZRQWW.js';//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/registry/index.d.ts

@@ -25,6 +25,8 @@ declare function searchRegistries(registries: string[], options?: {
     };
 }>;
 
+declare function fetchReference(query: string): Promise<string>;
+
 declare const RegistryErrorCode: {
     readonly NETWORK_ERROR: "NETWORK_ERROR";
     readonly NOT_FOUND: "NOT_FOUND";
@@ -92,4 +94,4 @@ declare class RegistryParseError extends RegistryError {
     constructor(item: string, parseError: unknown);
 }
 
-export { RegistryError, RegistryFetchError, RegistryForbiddenError, RegistryLocalFileError, RegistryNotFoundError, RegistryParseError, RegistryUnauthorizedError, searchRegistries };
+export { RegistryError, RegistryFetchError, RegistryForbiddenError, RegistryLocalFileError, RegistryNotFoundError, RegistryParseError, RegistryUnauthorizedError, fetchReference, searchRegistries };

package/dist/registry/index.js

@@ -1,2 +1,2 @@
-export{a as searchRegistries}from'../chunk-2ELKDGGM.js';export{G as RegistryError,K as RegistryFetchError,J as RegistryForbiddenError,L as RegistryLocalFileError,H as RegistryNotFoundError,M as RegistryParseError,I as RegistryUnauthorizedError,U as getRegistry,V as getRegistryItems,W as resolveRegistryItems}from'../chunk-KQTXDVKV.js';import'../chunk-Y7WZRQWW.js';//# sourceMappingURL=index.js.map
+export{a as searchRegistries}from'../chunk-OGAWGP7T.js';export{G as RegistryError,K as RegistryFetchError,J as RegistryForbiddenError,L as RegistryLocalFileError,H as RegistryNotFoundError,M as RegistryParseError,I as RegistryUnauthorizedError,S as fetchReference,V as getRegistry,W as getRegistryItems,X as resolveRegistryItems}from'../chunk-KFQXWKJJ.js';import'../chunk-Y7WZRQWW.js';//# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/dist/skills/createui/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: createui
-description: Create UI component library and design system. Use whenever writing or editing ANY React/JSX UI - pages, views, components, layouts, styling - in a project that uses Create UI (has a components.json, the @createui registry, or @create-ui/* packages), and for createui CLI or MCP operations (init/add/create/diff/view/search/migrate/mcp). Provides per-component API references (reference/<component>.md), composition rules, semantic tokens, and design recipes.
+description: Create UI component library and design system. Use whenever writing or editing ANY React/JSX UI - pages, views, components, layouts, styling - in a project that uses Create UI (has a components.json, the @createui registry, or @create-ui/* packages), and for createui CLI or MCP operations (init/add/create/diff/view/search/migrate/mcp). Provides per-component API references (via the MCP `get_component_reference` tool), composition rules, semantic tokens, and design recipes.
 user-invocable: true
 allowed-tools: Bash(npx @create-ui/cli *), Bash(pnpm dlx @create-ui/cli *)
 ---
@@ -13,16 +13,16 @@ Create UI is a design code system: **one unified styling system + many themes**.
 
 1. **Get project context** - `npx @create-ui/cli info` (prints components.json: aliases, `rsc`, `tailwind.css` path, `iconLibrary`). Use the real aliases in imports.
 2. **Check installed components** - list the `ui` alias directory (e.g. `components/ui/`). Never import a component that hasn't been added; never re-add installed ones.
-3. **Before the FIRST use of any component, read [`reference/<component>.md`](./reference/) in this skill folder.** It is generated from the component source and is the API authority (props, variants, defaults, icon usage, canonical example). If you cannot read it, fetch real usage instead: MCP `get_item_examples_from_registries` with `"<name>-demo"`, or `npx @create-ui/cli view <name>`.
+3. **Before the FIRST use of any component, fetch its API authority** - call MCP `get_component_reference('<component>')` (props, variants, defaults, icon usage, a canonical example, and gotchas; auth-aware - free or pro). A keyword works too (`'tabs'`, `'removable tag'`), and an empty query lists every component. Offline fallback: `npx @create-ui/cli view <name>` or MCP `get_item_examples_from_registries` with `"<name>-demo"`.
 4. **Add what's missing** - `npx @create-ui/cli add <name>`.
 5. **Compose per the invariants below.** Never hand-roll a pattern listed in "Never hand-roll".
 6. **Exercise the component API - never ship bare defaults.** Pick `variant` / `appearance` / `size` / `state` / `orientation` to fit each element's role on every build (see "Use the full component API" below). For marketing / landing / showcase, also read [`rules/design.md`](./rules/design.md) first (section recipes, spacing rhythm, anti-patterns); for any other rich UI, skim its richness checklist + anti-patterns. Build to the user's brand and request; never clone the Create UI site.
 
 ## Component inventory
 
-Every item below ships in `@createui` - and nothing else does. There is **no card, table, tabs, sheet, drawer, skeleton, sidebar, dialog/modal, popover, or alert-banner component**; the only modal surface is `CommandDialog` (part of `command`). Build other layouts from semantic-token markup and these primitives - don't invent lookalikes.
+Every **free** item ships below. At no tier is there a **card, table, tabs-with-panels, sheet, drawer, skeleton, sidebar, or alert-banner component** - build those from semantic-token markup and these primitives (see the table/card recipe in [`rules/composition.md`](./rules/composition.md)), never invent lookalikes. **`modal` and `popover` exist only as Pro components** (a developer seat is required; `add modal` returns 401 without one) - inspect them with `get_component_reference('modal')` / `('popover')`. The only free modal surface is `CommandDialog` (part of `command`).
 
-<!-- MAINTENANCE: if modal/popover/alert-banner ever get registered in ui/_registry.ts, update the sentence above and the matching negations in rules/composition.md and the notes files - the generator does not maintain hand-written prose. -->
+<!-- MAINTENANCE: the free inventory is generated below. modal/popover are Pro (listed in __pro-manifest__ gated); alert-banner/dialog/sheet/drawer/table/card do not exist at any tier. Keep these negations in sync here, in rules/composition.md, and in the notes files - the generator does not maintain hand-written prose. -->
 
 <!-- BEGIN GENERATED:INVENTORY -->
 
@@ -40,7 +40,6 @@ Every item below ships in `@createui` - and nothing else does. There is **no car
 | checkbox-group | CheckboxGroup | variant: primary*\|danger · size: xs\|sm\|md* · placement: left*\|right |
 | chip | Chip | variant: neutral*\|info\|danger\|success · appearance: outline*\|soft · size: xs\|sm\|md\|lg*\|xl · shape: pill\|rounded* · selected · disabled · dragging · closable |
 | close-button | CloseButton | variant: neutral*\|inverse · appearance: solid\|outline\|ghost*\|soft · size: xs\|sm\|md*\|lg\|xl\|2xl · shape: rounded*\|pill\|square |
-| command | Command, CommandDialog, CommandInput, CommandList, CommandEmpty, CommandGroup, +13 more | CommandDialog: showCloseButton |
 | country-flag | CountryFlag, CurrencyFlag, FlagFallback | code (required) |
 | credit-card-input | CreditCardInput | size: xs\|sm\|md · leadingIcon · invalid · disabled · loading · showLeadingIcon · showBadge · showValidationIcon |
 | date-input | DateInput | size: xs\|sm\|md · leadingIcon · invalid · disabled · loading · showLeadingIcon |
@@ -54,7 +53,6 @@ Every item below ships in `@createui` - and nothing else does. There is **no car
 | input-stepper | InputStepper | variant: connected\|separated · size: xs\|sm\|md · value/onValueChange · defaultValue · min · max · step · invalid · disabled |
 | label | Label, LabelBlock, LabelMain, LabelIcon, LabelRequired, LabelOptional, +4 more | size: xs\|sm\|md |
 | pagination | Pagination, PaginationContent, PaginationLink, PaginationFirst, PaginationPrevious, PaginationNext, +2 more | variant: compact\|compact-grouped* · shape: rounded*\|pill |
-| password-strength | PasswordStrength | size: xs\|sm\|md* |
 | phone-input | PhoneInput | size: xs\|sm\|md · invalid · disabled · loading · showHelperIcon |
 | progress | Progress | variant: primary*\|info\|success\|warning\|danger\|away\|neutral\|neutral-static\|neutral-soft\|inverse\|inverse-static\|inverse-soft · appearance: solid*\|gradient · size: xs\|sm\|md*\|lg · shape: sharp\|pill* · type: line*\|circle · value · max · duration |
 | radio | Radio | variant: primary*\|neutral\|danger\|success\|inverse · size: xs\|sm\|md* |
@@ -68,7 +66,7 @@ Every item below ships in `@createui` - and nothing else does. There is **no car
 | status-badge | StatusBadge | variant: primary*\|danger\|success\|warning\|info\|highlighted\|away\|verified\|cyan\|lime\|neutral\|white · size: xs\|sm\|md* |
 | switch | Switch | variant: primary*\|info\|neutral\|inverse\|semantic · size: md*\|sm\|xs · shape: pill*\|rounded · thumbType: short*\|long · ioTrigger · thumbIcon |
 | switch-group | SwitchGroup | size: xs\|sm\|md* · ioTrigger · placement: left*\|right |
-| tab-menu | TabMenu, TabMenuItem | variant: vertical-button*\|vertical-line\|horizontal-line\|horizontal-button · size: sm\|md*\|lg · value/onValueChange · indicator: left\|top\|bottom |
+| tab-menu | TabMenu, TabMenuItem | variant: horizontal-line* · size: sm\|md*\|lg · value/onValueChange · indicator: bottom* · **Pro** adds variant: vertical-button\|vertical-line\|horizontal-button · indicator: left\|top |
 | text-link | TextLink | variant: primary*\|neutral\|inverse\|danger\|success\|info · size: xs\|sm\|md*\|lg · leadingIcon/trailingIcon · visited · disabled · underline |
 | textarea | Textarea | size: xs\|sm*\|md · resizable: x\|y\|both · loading |
 | toast | Toast, ToastBody, ToastIcon, ToastContent, ToastTitle, ToastDescription, +3 more | variant: primary*\|neutral\|danger\|success\|warning\|info\|away · appearance: solid*\|soft\|outline\|default |
@@ -115,37 +113,97 @@ Components NOT in this table take no leadingIcon/trailingIcon props:
 
 <!-- END GENERATED:ICON-MATRIX -->
 
+## Design tokens
+
+The styling vocabulary - semantic colors, spacing, radius, typography, shadow, and the project themes. These back the "semantic tokens only" invariant below. For the on-demand version (or from an MCP client), call `get_component_reference('tokens')` (or `'colors'` / `'spacing'` / `'typography'`).
+
+<!-- BEGIN GENERATED:DESIGN-TOKENS -->
+
+Use semantic tokens, never the raw palette (`bg-blue-500`) or hex. Token values differ between light and dark - reference the token, never hardcode a color.
+
+### Colors -> `bg-`/`text-`/`border-`/`outline-<token>`
+
+- **Surfaces & text** (low -> high contrast): `static`, `weakest`, `weak`, `light`, `medium`, `heavy`, `strong`, `strongest`, `body`, `placeholder`, `disabled`.
+- **Intent** (each x `weakest|weak|base|strong|strongest`): `primary`, `error`, `success`, `warning`, `info`, `away`, `verified`, `feature`, `highlighted`, `stable` - e.g. `bg-primary-base`, `text-error-strong`, `border-success-weak`.
+- **Interaction & overlay**: `hover`, `active`, `hover-inverted`, `active-inverted`, `scrim`, `scrim-strong`.
+- **Static (non-theming, fixed light/dark)**: `static-white`, `static-black`, `static-{white,black}-alpha-{0,8,16,24,32,48,64,80}`.
+
+Gotchas: `variant="danger"` but the color token family is **`error-*`** (there is no `danger-*`); the neutral intent color is **`stable-*`**; `neutral-*` exists only as a component `variant`, not a color token. Never `bg-blue-500`, never hex.
+
+### Spacing -> `gap-`/`p-`/`m-`/`px-`/`py-<token>`
+
+`component-lg`, `component-md`, `component-none`, `component-sm`, `component-xl`, `component-xs`, `layout-lg`, `layout-md`, `layout-none`, `layout-sm`, `layout-xl`, `layout-xs`, `section-lg`, `section-md`, `section-none`, `section-sm`, `section-xl`, `section-xs`.
+
+`component-*` = tight component-internal padding/gaps · `layout-*` = section padding/gaps · `section-*` = page-section rhythm. **Only use a semantic spacing class when a Figma design references that token**; for a plain value use standard Tailwind (`gap-4`, `p-6`).
+
+### Radius -> `rounded-<token>`
+
+`2xl`, `3xl`, `4xl`, `5xl`, `component-2xl`, `component-3xl`, `component-4xl`, `component-5xl`, `component-full`, `component-lg`, `component-md`, `component-none`, `component-sm`, `component-xl`, `full`, `lg`, `md`, `none`, `sm`, `xl`, `xs`.
+
+`component-*` radii rescale responsively (prefer them on new components); the bare scale (`sm`, `lg`, `xl`, ...) stays static.
+
+### Typography -> `text-<token>` (the class IS the token)
+
+- **heading**: `heading-h1`, `heading-h2`, `heading-h3`, `heading-h4`, `heading-h5`, `heading-h6`.
+- **display**: `display-lg`, `display-xl`.
+- **paragraph**: `paragraph-lg`, `paragraph-md`, `paragraph-sm`, `paragraph-xl`, `paragraph-xs`.
+- **body**: `body-lg`, `body-md`, `body-sm`, `body-xl`, `body-xs`.
+- **ui-control**: `ui-control-lg`, `ui-control-md`, `ui-control-sm`, `ui-control-xl`, `ui-control-xs`.
+- **ui-caption**: `ui-caption-md`, `ui-caption-xs`.
+- **ui-overline**: `ui-overline-md`, `ui-overline-sm`, `ui-overline-xs`.
+- **code**: `code-lg`, `code-md`, `code-sm`, `code-xs`.
+- **numeric**: `numeric-lg`, `numeric-md`, `numeric-sm`, `numeric-xl`, `numeric-xs`.
+- **Fonts**: `font-body`, `font-display`, `font-numeric`.
+
+### Shadow -> `shadow-<token>`
+
+`component-error-default`, `component-error-focused`, `component-error-hover`, `component-icon-wrapper`, `component-info-default`, `component-info-focused`, `component-info-hover`, `component-inverted-default`, `component-inverted-focused`, `component-inverted-hover`, `component-neutral-default`, `component-neutral-focused`, `component-neutral-hover`, `component-primary-default`, `component-primary-focused`, `component-primary-hover`, `component-success-default`, `component-success-focused`, `component-success-hover`, `neutral-2xl`, `neutral-2xs`, `neutral-3xl`, `neutral-lg`, `neutral-md`, `neutral-sm`, `neutral-xl`, `neutral-xs`.
+
+### Themes (chosen at `init` - never ask or re-pick)
+
+- **Primary** (accent; use `primary-*` color tokens, do not invent a color): `indigo*`, `lime`, `green`, `red`, `orange`, `yellow`, `cyan`, `blue`.
+- **Neutral**: `gray*`, `slate`, `zinc`, `base`, `stone`.
+
+(`*` = default.) Switch the whole project only via `npx @create-ui/cli init --theme <name>` / `--neutral <name>`, and only when the user explicitly asks.
+
+<!-- END GENERATED:DESIGN-TOKENS -->
+
 ## Cross-cutting invariants
 
 - **Prop taxonomy**: `variant` = color intent (`primary`, `danger`, `success`, `neutral-*`, ...) · `appearance` = fill weight (`solid` / `outline` / `soft` / `ghost`) · `size` · `shape`. **There is no `variant="outline"`, `variant="secondary"`, or `variant="destructive"`** - an outline style is `appearance="outline"`, a destructive action is `variant="danger"`.
 - **`Field` owns size; children inherit it.** Set `size` (`xs` | `sm` | `md`) once on `Field`; `Input`, `Select`, `Textarea`, labels and helpers read it via context. Never re-set or downgrade size on a child.
+- **Adjacent components don't share a size scale** - `Avatar md` ≠ `Button md` in height. Harmonize a row by optical height: prefer a size-owning container (`Field` / `InputGroup` / `Chip`) when one exists, otherwise anchor on the text scale and move the whole cluster's sizes together, aligned with `flex items-center` + a gap. Never match size prop names across different components (see rules/composition.md "Sizing across adjacent components").
 - **Validation**: `data-invalid` on `Field`, `aria-invalid` on the control. Disabled: `data-disabled` on `Field`, `disabled` on the control.
 - **`Button` has a real `loading` prop** - `<Button loading>Saving...</Button>`. Don't compose spinners into buttons.
 - **Use `asChild` for custom triggers/links** - `<Button asChild><Link href="/x">Docs</Link></Button>`.
 - **Items live inside their Group**: `SelectItem` → `SelectGroup` and `CommandItem` → `CommandGroup` are structural (always wrap); `DropdownMenuGroup` is semantic grouping - a lone `DropdownMenuItem` may sit directly in `DropdownMenuContent`.
-- **Semantic tokens only, never raw colors.** Surfaces `bg-static` / `bg-weak` / `bg-light`, text `text-strongest` / `text-body` / `text-placeholder` / `text-disabled` / `text-static`, borders `border-weak` / `border-light`, primary `bg-primary-base` / `text-primary-base` / `bg-primary-weakest`, status `{error,success,warning,info,away,verified,highlighted}-{base,weak,weakest}`. Never `bg-blue-500`, never hex.
-- **The theme is already chosen - never ask for or re-pick the brand color.** The project's primary and neutral colors were selected at `init` (primary: `indigo`* / `blue` / `lime` / `green` / `red` / `orange` / `yellow` / `cyan`; neutral: `gray`* / `slate` / `zinc` / `base` / `stone`) and live as tokens in the global CSS. Use `bg-primary-base` / `text-primary-base` / `border-primary-*` for any accent - they already render that choice. Do NOT ask the user "what color/theme", do NOT offer or invent a color (there is no `violet` etc. - the set above is fixed), and do NOT rewrite the theme token values in the CSS to "apply" a color. Switching the whole project's theme is `npx @create-ui/cli init --theme <name>` / `--neutral <name>` - only when the user explicitly asks for it.
+- **Semantic tokens only, never raw palette or hex** - use the surface / text / border / intent tokens from the Design tokens block above (`bg-static`, `text-strongest`, `border-light`, `bg-primary-base`, `{error,success,…}-{base,weak}`). Never `bg-blue-500`, never hex.
+- **The theme is already chosen** - primary + neutral were picked at `init` and live as tokens. Use `bg-primary-base` / `text-primary-base` / `border-primary-*` for any accent; never ask for a color, invent one, or hand-edit the theme token hex. Re-theming is `init --theme <name>` / `--neutral <name>`, only on explicit request (see [customization.md](./customization.md)).
 - **Focus is `outline-*`, never `ring-*`.**
 - **Spacing**: vertical stacks are `flex flex-col gap-*` (never `space-y-*`); `size-10` not `w-10 h-10`; semantic spacing classes (`gap-component-sm`) only when a Figma design references a token - otherwise standard Tailwind (`gap-4`).
 - **`className` is for layout, not restyling** - don't override a component's colors or typography; reach for `variant`/`appearance` first.
 
 ## Use the full component API
 
-Every component exposes many axes - `variant`, `appearance`, `size`, `shape`, state flags, often `orientation` / `layout` / `placement`, and more - and the set differs per component. **Defaults are a baseline, not the answer**; one size and one variant everywhere reads as a wireframe. Before building with a component, read its `reference/<component>.md` prop table and deliberately use the axes that fit the design. The heuristics below show the *kind* of judgment, not a closed list - `shape` and any component-specific axis count just as much:
+Props encode an element's *role*; a default is right only when it happens to match that role. **This holds for all UI - app screens as much as marketing** - and one size + one variant everywhere reads as a wireframe. Fetch the prop table with `get_component_reference('<component>')` and set the axes deliberately: `variant` = intent, `appearance` = hierarchy (one `solid` primary per group, the rest `soft` / `outline` / `ghost`), `size` = density, plus state props (`loading` / `invalid` + `aria-invalid` / `disabled` / `selected`) and any component-specific axis (`shape`, `orientation`, `layout`, `placement`). Map role → props (Button/Badge, the highest-traffic axes):
 
-- **`size`** tracks density / prominence: small for dense or secondary chrome, the default for standard body UI, large for the primary CTA or hero.
-- **`appearance`** tracks hierarchy: exactly one `solid` (primary) action per group, secondary `soft` / `outline`, tertiary or dismiss `ghost`.
-- **`variant`** tracks intent: `primary` for the main action, `neutral-*` for neutral chrome, semantic (`danger` / `success` / `warning` / `info`) only for real meaning - status on Badge / InlineAlert / Toast rides `variant`, never raw color.
-- **State is a prop, not markup**: reach for built-in `loading` / `invalid` (+ `aria-invalid`) / `disabled` / `selected` / `checked` / `readOnly` when context implies them.
-- **Everything else is a real choice too** - `shape`, `orientation` / `layout` (e.g. `Field orientation="horizontal"`, `InlineAlert layout="vertical"`, `TabMenu variant="horizontal-line"` vs `"vertical-button"`), `placement`, and whatever else the component's reference lists. Match it to the design; don't leave it at default out of habit.
+| Element's role | Props |
+| --- | --- |
+| The one primary action in a view / form / section | `variant="primary" appearance="solid"` |
+| A secondary action beside it | `appearance="outline"` / `"soft"` (often `variant="neutral-light"`) |
+| Tertiary / dismiss / toolbar action | `appearance="ghost"` |
+| Destructive / positive action | `variant="danger"` / `variant="success"` |
+| Any action on a dark / colored panel | `variant="inverse-solid"` |
+| Status / tag (Badge) | `soft` workhorse · `outline` quiet eyebrow/version · `solid` high-priority count · `variant` = meaning |
+| `size` by context | dense / toolbar `xs`–`sm` · standard `md` · primary CTA / hero `lg`–`xl` |
 
-Each `reference/<component>.md` canonical example already spans its component's axes - mirror that range, don't collapse to defaults. `rules/design.md` has the per-component richness checklist and anti-patterns.
+**Default monoculture is a bug**: if every Button/Badge shares one default size+variant, the primary action isn't standing out - you skipped this. Each component's `get_component_reference` example already spans its axes; mirror that range. `rules/design.md` has the per-component richness checklist and anti-patterns.
 
 ## Never hand-roll
 
 | You need | Use (never raw markup) |
 | --- | --- |
-| Tabs | `TabMenu` + `TabMenuItem` + your own value-keyed panels (recipe below) |
+| Tabs | `TabMenu` + `TabMenuItem` + your own value-keyed panels (TabMenu renders only the bar) |
 | Toggle between 2-7 options | `SegmentedControl` + `SegmentedControlItem` (`value`/`onValueChange`) - never a row of `Button`s with manual active state |
 | Tag / label | `Badge` (icons via `leadingIcon`/`trailingIcon`) |
 | Removable / interactive tag | `Chip` (icon or `Avatar` as FIRST CHILD, `closable`/`onClose`) |
@@ -160,43 +218,11 @@ Each `reference/<component>.md` canonical example already spans its component's
 
 ## Recipes
 
-**Tabs with content panels** - `TabMenu` renders the tab list only; you render the panels, keyed by value:
-
-```tsx
-const [tab, setTab] = React.useState("overview")
-
-<TabMenu variant="horizontal-line" indicator="bottom" value={tab} onValueChange={setTab}>
-  <TabMenuItem value="overview" label="Overview" />
-  <TabMenuItem value="billing" label="Billing" leadingIcon={<RiBankCardLine />} />
-</TabMenu>
-{tab === "overview" && <OverviewPanel />}
-{tab === "billing" && <BillingPanel />}
-```
-
-**Billing / pricing toggle** - the active pill slides between items in both appearances; `appearance="grouped"` adds the padded `bg-weak` container (the classic pricing-toggle look):
-
-```tsx
-const [billing, setBilling] = React.useState("monthly")
-
-<SegmentedControl appearance="grouped" variant="neutral" value={billing} onValueChange={setBilling}>
-  <SegmentedControlItem value="monthly">Monthly</SegmentedControlItem>
-  <SegmentedControlItem value="yearly">Yearly</SegmentedControlItem>
-</SegmentedControl>
-```
-
-**Showcase-quality switch** - bare `<Switch />` is for dense forms; showcases should exercise the richer API (see `reference/switch.md`). Labelled apply-immediately rows use `SwitchGroup`; the `Field` composition below is for submit-to-save forms:
-
-```tsx
-<Field size="md" orientation="horizontal">
-  <FieldContent>
-    <FieldLabel htmlFor="2fa">Enforce two-factor auth</FieldLabel>
-  </FieldContent>
-  <Switch id="2fa" thumbIcon defaultChecked />
-</Field>
-<Switch variant="semantic" thumbType="long" ioTrigger aria-label="Accept" />
-```
+Copy-ready patterns live in the on-demand rules - fetch the one you need instead of inlining:
 
-(`Field` size does not cascade to `Switch` - pair them explicitly, or use `SwitchGroup` which pairs both automatically.)
+- **Tabs with panels** (`TabMenu` is the bar only; render panels keyed by value) and **table / card / empty state** (no such primitives - build from semantic markup) → [composition.md](./rules/composition.md).
+- **Forms, billing/pricing toggle (grouped `SegmentedControl`), showcase-quality `Switch`** → [forms.md](./rules/forms.md).
+- **Hero / dark CTA / footer / pricing section, spacing rhythm, richness checklist** → [design.md](./rules/design.md).
 
 ## components.json keys
 
@@ -222,12 +248,13 @@ npx @create-ui/cli mcp init --client claude   # set up the MCP server
 
 ## Detailed references
 
-- [reference/](./reference/) - **per-component API (generated from source - read before first use)**.
+- **Per-component API / gotchas**: MCP `get_component_reference('<name>')` - generated from source, auth-aware (free or pro). Empty query lists every component; offline fallback `npx @create-ui/cli view <name>`.
 - [rules/design.md](./rules/design.md) - design taste: hero/CTA/footer/pricing recipes, richness checklist, anti-patterns.
 - [rules/icons.md](./rules/icons.md) - icon props per component, sizing, assets packages.
 - [rules/composition.md](./rules/composition.md) - groups, overlays, TabMenu, Avatar, InlineAlert, Toast.
 - [rules/forms.md](./rules/forms.md) - FieldGroup/Field, size cascade, InputGroup, SegmentedControl, validation.
 - [rules/styling.md](./rules/styling.md) - semantic tokens, className scope, spacing, focus.
+- [rules/a11y.md](./rules/a11y.md) - accessible names, labelling, validation/state wiring, overlay a11y, reduced motion.
 - [cli.md](./cli.md) - every command and flag. [mcp.md](./mcp.md) - MCP tools and workflow. [customization.md](./customization.md) - theming and tokens.
 
 ## Resources

package/dist/skills/createui/cli.md

@@ -117,7 +117,7 @@ With no argument, lists the components that have updates available. With a compo
 npx @create-ui/cli view <items...> [options]
 ```
 
-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.
+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 MCP `get_component_reference('<name>')`) before the first use of a component.
 
 | Flag          | Short | Description       | Default |
 | ------------- | ----- | ----------------- | ------- |

package/dist/skills/createui/customization.md

@@ -51,7 +51,7 @@ Create UI uses **semantic** token names. Backgrounds, borders, and text share a
 
 ### Primary scale
 
-`bg-primary-50` … `bg-primary-950`, plus `bg-primary-base` (= `bg-primary-500`), `text-primary-base`, and the alphas `bg-primary-alpha-16` / `bg-primary-alpha-48` (subtle/hover tints). Focus uses `outline-primary-500` / `outline-primary-700`.
+The **semantic primary tokens swap with the theme** like everything else - `primary-weakest` / `weak` / `base` / `strong` / `strongest` (`bg-primary-base`, `text-primary-base`, `border-primary-strong`). Use these: each resolves to a *different* ramp step in dark vs light (`primary-base` = `primary-500` in light but `primary-400` in dark), so it stays legible in both modes. The raw numeric ramp `primary-50` … `primary-950` is the **fixed brand palette** those tokens point at - it does not swap, so don't apply it directly (`bg-primary-500` is a raw color, like `bg-blue-500`). For tints prefer the swapping `primary-weakest` / `weak` over raw `primary-alpha-*`; `outline-primary-500/700` focus is a fixed-ramp helper primitives already wire up.
 
 ### Status families
 
@@ -87,13 +87,13 @@ If you are porting markup written against common component-library token names,
 | `bg-card` | `bg-static` (or `bg-weakest` for subtle surfaces) |
 | `text-foreground` | `text-body` |
 | `text-muted-foreground` | `text-placeholder` |
-| `bg-primary` | `bg-primary-base` (or `bg-primary-500`) |
+| `bg-primary` | `bg-primary-base` (swaps; not `bg-primary-500`, which is fixed) |
 | `text-primary-foreground` | `text-white` (on solid primary) |
 | `border-border` / `border-input` | `border-light` or `border-medium` |
 | `bg-muted` | `bg-weak` |
 | `bg-destructive` | `bg-error-base` |
 | `text-destructive` | `text-error-base` |
-| `bg-accent` | `bg-primary-alpha-16` |
+| `bg-accent` | `bg-primary-weakest` (swaps; the raw `primary-alpha-16` does not) |
 | `ring-ring` (focus) | `outline-primary-700` (primary) / `outline-strong` (neutral) |
 
 ---
@@ -162,29 +162,31 @@ Because every color is a token that already has a `.dark` override, **never writ
 
 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:
+Match how the system works: **a color is a semantic token with both a light and a dark value**, so it swaps with the theme like every built-in token. Define the pair in `:root` and `.dark`, then use the semantic name - not a raw step that only exists in one mode:
 
 ```css
 /* app/globals.css */
 :root {
-  --color-brand-50: #eef6ff;
-  --color-brand-500: #2f7bff;
-  --color-brand-900: #14315f;
-  --radius-lg: 0.75rem; /* override radius */
+  --color-brand-base: #2f7bff; /* light */
+  --color-brand-weak: #eef6ff;
+  --radius-lg: 0.75rem; /* radius is a single value - no theme swap needed */
 }
 
 .dark {
-  --color-brand-500: #5a96ff;
+  --color-brand-base: #5a96ff; /* dark - keeps contrast */
+  --color-brand-weak: #16243a;
 }
 ```
 
-Tailwind v4 auto-generates the utilities (`bg-brand-500`, `text-brand-900`, …) from those `--color-*` variables:
+Tailwind v4 auto-generates `bg-brand-base`, `text-brand-base`, `bg-brand-weak`, … and they swap under `.dark` automatically:
 
 ```tsx
-<div className="bg-brand-50 text-brand-900">Brand surface</div>
+<div className="bg-brand-weak text-brand-base">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.)
+A single `:root` scale with no `.dark` pair is only for a color that must stay fixed across themes (e.g. a logo color) - it will NOT dark-adapt, so never use it for surfaces or text that appear in both modes.
+
+To restyle existing components, prefer **overriding the semantic token families** - redefine the light *and* dark values of `primary-*` or a status family - over adding new colors; every component already references them. (No build step - editing the CSS is the whole change.)
 
 ---
 

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

@@ -106,6 +106,83 @@
         "Spacing uses flex/grid + gap-*, never space-y-*",
         "Column titles use text-strongest with body links in text-body/text-placeholder"
       ]
+    },
+    {
+      "id": 9,
+      "prompt": "Build a 'plan limits' summary block: a row that says the account is over its seat limit (an error), a row showing storage is healthy (success), and a neutral row for the current region. Use Create UI semantic tokens.",
+      "expected_output": "Status communicated with semantic status tokens and/or StatusBadge plus text labels - error family is error-*, neutral is stable-*, no raw palette or danger-* color tokens.",
+      "files": [],
+      "expectations": [
+        "Error/negative state uses the error-* token family (e.g. text-error-base, bg-error-weak) - never a danger-* color token (there is no danger-* color; danger is only a component variant) and never bg-red-500/hex",
+        "Positive state uses success-* tokens (e.g. text-success-base) and informational/neutral uses stable-* or neutral surface tokens - not raw emerald/green/gray palette classes",
+        "Status is not conveyed by color alone: each row pairs the color with a text label (or a StatusBadge dot plus an adjacent label)",
+        "Surfaces and text use semantic tokens (bg-static/bg-weak, text-body/text-placeholder/text-strongest), never foreign tokens or hex"
+      ]
+    },
+    {
+      "id": 10,
+      "prompt": "Create a checkout details form with: cardholder name, card number, card expiry, a one-time verification code field, the customer's phone number, and their date of birth. Using Create UI.",
+      "expected_output": "Each field uses the purpose-built control - CreditCardInput, InputOTP, PhoneInput, DateInput - inside FieldGroup/Field, never a plain Input with hand-rolled masking.",
+      "files": [],
+      "expectations": [
+        "Card number uses CreditCardInput (not a raw Input with manual formatting)",
+        "The verification code uses InputOTP",
+        "Phone number uses PhoneInput and date of birth uses DateInput - not plain Inputs",
+        "Fields are laid out with FieldGroup + Field (size/state cascade from Field), with FieldLabel wired via htmlFor",
+        "No invented or shadcn-style components (no DatePicker, no PhoneNumberInput) - only the registry's actual control names"
+      ]
+    },
+    {
+      "id": 11,
+      "prompt": "Create a billing page with a table of recent invoices (date, amount, status, and a row action menu), an empty state for when there are no invoices, and a 'Cancel subscription' action that asks the user to confirm before proceeding. Using Create UI.",
+      "expected_output": "A semantic <table> (no Table primitive) with Badge status cells and a DropdownMenu row action, a semantic empty-state surface, and a confirmation handled inline or via CommandDialog - not an invented Dialog/Card/Table component.",
+      "files": [],
+      "expectations": [
+        "The table is built from semantic markup (a real <table> with bg-weak header, border-light row separators) - there is no Table/DataTable component; cell content uses primitives (Badge for status, DropdownMenu or an iconOnly Button for the row action) rather than styled spans",
+        "No Card primitive is used or imported - surfaces are bg-static/bg-weakest panels with border-light and an elevation shadow",
+        "At the free tier there is no Dialog/Modal primitive: the cancel confirmation is surfaced inline (expanding section, dedicated step, or InlineAlert), via CommandDialog, or the answer notes Modal is Pro - it does not invent a Dialog/AlertDialog component",
+        "The empty state reuses the same surface with text-placeholder copy and a primary Button, not a bare 'No data' string or a fixed-height box with only a Spinner",
+        "Spacing uses gap-*/padding utilities, not space-y-*, and status colors use semantic tokens"
+      ]
+    },
+    {
+      "id": 12,
+      "prompt": "Create a compact toolbar: an icon-only search button, an icon-only filter button, an icon-only overflow menu, and a view toggle between Grid and List shown as two icons. Make it accessible. Using Create UI.",
+      "expected_output": "Icon-only Buttons each with an aria-label, the overflow opening a DropdownMenu, and the view toggle a SegmentedControl with iconOnly items that each carry an aria-label - icons from @create-ui/assets/icons, no sizing classes.",
+      "files": [],
+      "expectations": [
+        "Every icon-only control has an aria-label (icon-only Buttons and iconOnly SegmentedControlItems) so it has an accessible name",
+        "Icon-only buttons pass the icon as the child with iconOnly set (leadingIcon is ignored in iconOnly mode), never as a leadingIcon",
+        "The Grid/List toggle is a SegmentedControl with value/onValueChange (or defaultValue), not two manually-toggled Buttons",
+        "The overflow menu uses DropdownMenu with DropdownMenuTrigger asChild around the icon button",
+        "Icons come from @create-ui/assets/icons (Ri*), with no size-4/w-4/h-4 sizing classes on icons inside components"
+      ]
+    },
+    {
+      "id": 13,
+      "prompt": "Build a profile photo row for a settings page: the user's avatar on the left, and to its right a 'Profile photo' label with a 'Change' link under it. Make the avatar and the text/link sizes feel balanced and aligned. Using Create UI.",
+      "expected_output": "An items-center flex row with an Avatar (AvatarImage + AvatarText) as the visual anchor and a stacked label + TextLink whose sizes track one coherent scale (e.g. Avatar lg with text-body-sm + TextLink size=\"sm\"), spaced with gap-*.",
+      "files": [],
+      "expectations": [
+        "The row uses flex items-center so the avatar aligns to the optical center of the text block, with a gap-* between them (not margins)",
+        "The avatar is the Avatar component with AvatarText for initials (not AvatarFallback) and is the visual anchor of the cluster",
+        "The label text token and the TextLink size sit on one coherent scale (e.g. text-body-sm paired with TextLink size=\"sm\"), rather than mismatched sizes - and the answer does not assume Avatar and TextLink share the same size name to align",
+        "The change affordance is a TextLink (with a variant/size), not a styled <a> or a Button",
+        "Sizes are harmonized by optical height, not by blindly matching size prop names across the Avatar and TextLink"
+      ]
+    },
+    {
+      "id": 14,
+      "prompt": "Create the action bar for an account settings form (a plain app screen, not a marketing page): a 'Save changes' button, a 'Cancel' button, and a 'Delete account' button. Using Create UI.",
+      "expected_output": "Buttons whose props reflect their distinct roles - one solid primary Save, a non-solid secondary Cancel, and a danger Delete - not three identical default buttons.",
+      "files": [],
+      "expectations": [
+        "Save is the single primary action: variant=\"primary\" appearance=\"solid\" - and it is the only solid button in the bar",
+        "Cancel is visually secondary (appearance=\"outline\" / \"soft\" / \"ghost\"), never a second solid button",
+        "Delete account uses variant=\"danger\" (not a default neutral button, and not variant=\"destructive\" which does not exist)",
+        "The three buttons are NOT all left at the same default size+variant - their props differ to express primary vs secondary vs destructive roles, even though this is plain app UI rather than a showcase",
+        "Sizes are deliberate and consistent for the cluster (not a mix of unrelated sizes), and any icons go through leadingIcon/trailingIcon"
+      ]
     }
   ]
 }

package/dist/skills/createui/mcp.md

@@ -48,34 +48,27 @@ 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.
+1. **`get_component_reference` BEFORE writing code for any component whose Create UI API you haven't already confirmed this session** - pass a name or keyword (`"tab-menu"`, `"tabs"`, `"removable tag"`). Call it with an **empty query** first to get the catalog of every component and whether the current user can use each one (free / pro / locked). Create UI APIs differ from shadcn; do not guess. Offline fallback when the MCP is unavailable: `npx @create-ui/cli view <name>`.
+2. `get_item_examples_from_registries` for full working demos of an item you haven't used - query `"<name>-demo"` (canonical usage), `"<name>-example"` (full gallery), or facet names like `"switch-thumb-icon"`, `"segmented-control-appearance"`. The reference is the concise API + gotchas; examples are the full galleries - they complement.
+3. `view_items_in_registries` when you need the raw component source.
+4. `search_items_in_registries` for a broader or cross-registry search.
+5. Install with `npx @create-ui/cli add <items>` - never import a component that hasn't been added.
+6. `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 five 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
+### get_component_reference
 
-Returns the registries configured in the current project's `components.json`.
-
-**Inputs:** none
-
-### list_items_in_registries
-
-Lists all items available in the specified registries.
+Fetches the auth-aware usage reference for a component: props/variants, 1-2 canonical snippets, when-to-use, and gotchas. Call it before writing code with any component whose API you have not confirmed this session. Accepts a name **or** a keyword; an **empty query returns the catalog** of every component with its tier and whether the current user can use it (free / pro / locked). This is the concise API; `get_item_examples_from_registries` is the full gallery. Auth-aware: a logged-in seat holder gets the richer pro reference, everyone else gets the free tier (or a locked upsell for pro-only components).
 
 **Inputs:**
-- `registries` (string[]) - registry namespaces to query
-- `limit` (number, optional)
-- `offset` (number, optional)
+- `query` (string, optional) - component name or keyword; empty string returns the catalog
 
 ### search_items_in_registries
 
-Searches for items across registries by query string.
+Searches for items across registries by query string (fuzzy match over names and descriptions). Use for a broad or cross-registry search; for a single component's usage prefer `get_component_reference`.
 
 **Inputs:**
 - `registries` (string[])
@@ -85,7 +78,7 @@ Searches for items across registries by query string.
 
 ### view_items_in_registries
 
-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`.
+Returns detailed information about specific items, including file contents (the raw source). For *usage* (props, composition, icon props) use `get_component_reference` instead - source alone does not show canonical usage.
 
 **Inputs:**
 - `items` (string[]) - bare item names, e.g. `button` (the MCP server also accepts a `@createui/` prefix and strips it)
@@ -98,13 +91,6 @@ Finds example and demo code for items with full source. Call it before the first
 - `registries` (string[])
 - `query` (string)
 
-### get_add_command_for_items
-
-Returns the `add` command for the specified items.
-
-**Inputs:**
-- `items` (string[])
-
 ### get_audit_checklist
 
 Returns a checklist to verify after adding components.