@create-ui/cli 0.5.7 → 0.5.9

package/dist/skills/createui/rules/design.md

@@ -0,0 +1,266 @@
+# Design & Showcase Quality
+
+How to make pages built with Create UI look premium, not just API-correct - the taste layer for marketing, landing, and showcase UI.
+
+**Build to the user's brand and what they asked for - never reproduce the Create UI marketing site.** The recipes below are worked examples of the principles in action (which token belongs on which surface, how to keep a footer neutral, how to avoid bare-default poverty). Lift the *principle*, adapt the specifics: your colors, gradients, copy, spacing, and layout should serve the user's design, not clone createui.co. The universal rules - spacing rhythm, the richness checklist, the anti-patterns, the dark-panel token rule - apply to every project regardless of brand.
+
+---
+
+## Surface & color recipes
+
+### Hero *(source: hero-section.tsx)*
+
+Heading is `text-heading-h1` (it auto-scales down at smaller breakpoints - no `md:`/`xl:` prefixes) with `text-strongest font-semibold`; the lede is `text-body-lg text-body`. The CTA pair is one solid neutral button plus one soft neutral button, both `size="xl" shape="rounded"`, in a `gap-component-sm` row:
+
+```tsx
+<div className="gap-component-xl flex max-w-[800px] flex-col">
+  <h1 className="text-heading-h1 text-strongest font-semibold">Stop rebuilding UI.</h1>
+  <p className="text-body-lg text-body">One library, one design system, one source.</p>
+  <div className="gap-component-sm flex flex-wrap">
+    <Button variant="neutral-solid" appearance="solid" size="xl" shape="rounded" leadingIcon={<RiCodeFill />}>
+      Start Free
+    </Button>
+    <Button variant="neutral-light" appearance="soft" size="xl" shape="rounded">View Pricing</Button>
+  </div>
+</div>
+```
+
+**One solid action per section.** The secondary action is always a softer appearance (`soft`, `ghost`, or `outline`), never a second solid button.
+
+### Dark CTA / premium panel *(source: cta-section.tsx)*
+
+The surface is a dark linear gradient, not flat black: `bg-[linear-gradient(82deg,#030712_-0.01%,#1e2939_55.88%)]` with `px-layout-sm py-layout-lg`. On top of it:
+
+- Eyebrow: `Badge variant="primary" appearance="outline" size="md" className="dark"`; the `dark` class flips the badge's tokens so the outline reads correctly on the dark panel. Heading: `text-heading-h2 text-white font-medium`; body: `text-body-lg text-white/70`. **Use raw `text-white` here, never `text-static`** (see the note below).
+- Buttons switch to `variant="inverse-solid"` (`appearance="solid"` primary, `appearance="soft"` secondary, both `size="xl"`); optional micro-caption under them: `text-ui-overline-xs text-white/50 uppercase`.
+
+```tsx
+<section className="px-layout-sm py-layout-lg gap-component-md flex flex-col items-start bg-[linear-gradient(82deg,#030712_-0.01%,#1e2939_55.88%)]">
+  <Badge variant="primary" appearance="outline" size="md" className="dark">
+    PRE-SALE · 70% OFF · LIMITED TIME
+  </Badge>
+  <h2 className="text-heading-h2 text-white font-medium">Stop deciding.</h2>
+  <p className="text-body-lg text-white/70">The system is ready.</p>
+  <div className="gap-component-sm flex flex-col xl:flex-row">
+    <Button variant="inverse-solid" appearance="solid" size="xl" leadingIcon={<RiCodeFill />}>Get 70% off now</Button>
+    <Button variant="inverse-solid" appearance="soft" size="xl" trailingIcon={<RiArrowRightSLine />}>Start for Free</Button>
+  </div>
+</section>
+```
+
+> **Why raw `text-white`, not `text-static`, on a fixed dark gradient:** the gradient is a hardcoded dark color (not a theme surface token), so the text must be light in BOTH themes. `text-static` is theme-relative - white in light, **black under `.dark`** - so on a dark-mode page the heading turns black-on-dark. (The Create UI marketing site does use `text-static` on this exact panel, but only because its marketing routes are force-light; don't copy that into a dark-mode-capable page.) Rule: on any fixed-color surface, always-light text is raw `text-white`. Alternative architecture: put `className="dark"` on the whole panel and use `text-strongest` / `text-body` / `text-placeholder`, which resolve light under `.dark`.
+
+### Footer *(source: site-footer.tsx, footer-link-row.tsx)*
+
+**Footers are neutral surfaces. Never use random saturated colors in a footer.** The shell is `bg-static`, every divider is `border-light`, the bottom bar is `bg-weak`. The only color moment is the newsletter panel's primary gradient (below).
+
+- Shell: `<footer className="bg-static">`, inner wrapper `px-layout-sm py-layout-lg`, top-level blocks stacked with `gap-layout-sm`, content capped at `max-w-[1280px]`.
+- Column dividers: `<Separator />` between stacked blocks; for VERTICAL dividers between side-by-side columns the site uses `<span aria-hidden className="border-light border-t md:border-t-0 md:border-l" />` inside the `gap-section-md` grid (Separator has no `orientation` prop - it is horizontal only).
+- Brand row: logo plus a version chip `Badge variant="neutral" appearance="outline" size="xs"`; tagline `text-body-md text-body`.
+- Social links: icon-only ghost buttons in a `gap-component-xs` row, never raw `<a>` tags with an svg: `<Button size="md" iconOnly variant="neutral-solid" appearance="ghost" aria-label="GitHub" asChild>` wrapping an `<a target="_blank" rel="noreferrer">` with an `Ri*` icon.
+- Bottom bar: `bg-weak px-layout-sm py-section-md`; copyright `text-body-md text-body`; policy links `TextLink variant="neutral" size="sm"`.
+
+Link columns: title `text-body-md text-strongest font-semibold`, then a `gap-component-sm` stack of neutral TextLinks; "soon" markers are pill badges next to the link, never recolored links:
+
+```tsx
+<div className="gap-component-lg flex flex-col">
+  <h3 className="text-body-md text-strongest font-semibold">Products</h3>
+  <div className="gap-component-sm flex flex-col items-start">
+    <TextLink href="/docs" variant="neutral" size="sm" leadingIcon={<RiArrowRightSFill />}>
+      Documentation
+    </TextLink>
+    <div className="gap-component-xs flex items-center">
+      <TextLink href="/templates" variant="neutral" size="sm">Templates</TextLink>
+      <Badge variant="primary" appearance="soft" size="sm" shape="pill">Soon</Badge>
+    </div>
+  </div>
+</div>
+```
+
+### Newsletter panel *(source: site-footer.tsx, newsletter-form.tsx)*
+
+The footer's single intentional color block: a primary gradient panel with an inverse-outline eyebrow, `text-white` title, `text-white/70` description. (Same rule as the dark CTA - the panel is a fixed primary color, so its text is raw `text-white`, never `text-static`, which would flip to black under `.dark`.)
+
+```tsx
+<div className="p-section-xl from-primary-base via-primary-weak to-primary-weakest gap-component-md flex flex-col items-start rounded-xl bg-linear-to-b from-[31.34%] via-[65.67%]">
+  <Badge variant="inverse" appearance="outline" size="md">NEWSLETTER</Badge>
+  <h2 className="text-heading-h4 text-white">Stay in the loop</h2>
+  <p className="text-body-lg text-white/70">Releases and updates, no spam.</p>
+</div>
+```
+
+The form is a `Field` (with `invalid` / `loading` bound to submit state) wrapping an `InputGroup` with a leading mail icon, plus a solid primary submit:
+
+```tsx
+<Field size="md" invalid={status === "error"} loading={status === "submitting"}>
+  <InputGroup>
+    <InputGroupLeadingIcon><RiMailOpenLine /></InputGroupLeadingIcon>
+    <InputGroupSlot>
+      <InputGroupControl type="email" placeholder="hi@createui.co" aria-label="Email address" />
+    </InputGroupSlot>
+  </InputGroup>
+</Field>
+<Button type="submit" variant="primary" appearance="solid" size="xl">Sign Up</Button>
+```
+
+Submit feedback is inline and the form stays mounted (source: newsletter-form.tsx): on success render a `FieldDescription` under the input (give it `className="text-white"` on the colored gradient panel - not `text-static`), on error render `FieldError`. Never unmount the form to swap in a success badge or alert.
+
+The form is the footer's ONLY client boundary: put it in its own file with `"use client"` and import it; the footer shell stays a Server Component. Never hoist `"use client"` over a whole static section to accommodate one interactive form.
+
+### Pricing *(source: pricing-section.tsx)*
+
+The billing toggle is a grouped `SegmentedControl` (animated sliding indicator), never a pair of hand-styled buttons. The site uses `variant="neutral"` at `size="xl"` (`lg` on mobile), controlled:
+
+```tsx
+<SegmentedControl appearance="grouped" variant="neutral" size="xl" value={billing} onValueChange={setBilling}>
+  <SegmentedControlItem value="individual">Individual</SegmentedControlItem>
+  <SegmentedControlItem value="teams">Teams</SegmentedControlItem>
+</SegmentedControl>
+```
+
+A discount badge rides INSIDE the item as a plain extra child (the item's content slot is already a gapped inline-flex row; no wrapper span, no manual gap classes):
+
+```tsx
+<SegmentedControlItem value="yearly">
+  Yearly
+  <Badge variant="success" appearance="soft" size="sm" shape="pill">-20%</Badge>
+</SegmentedControlItem>
+```
+
+- Section eyebrow: `Badge variant="primary" appearance="soft" size="md"` above a `text-heading-h2 text-strongest font-medium` heading and a `text-body-lg text-body` lede.
+- Section background: a subtle vertical gradient `from-weakest to-light bg-gradient-to-b from-25%`, not a flat gray.
+- Cards: `bg-static` with `shadow-neutral-md`; the highlighted plan gets `shadow-neutral-lg` plus a gradient frame (`from-primary-base via-primary-strong to-light bg-gradient-to-b via-10%`).
+- Discount treatment: struck-through anchor price next to a soft badge, then the real price large:
+
+```tsx
+<div className="gap-component-sm flex items-center">
+  <span className="text-heading-h5 text-placeholder font-medium line-through">$399</span>
+  <Badge variant="warning" appearance="soft" size="md">70% OFF</Badge>
+</div>
+<span className="text-heading-h2 text-strongest font-semibold">$119</span>
+```
+
+- Feature-list group breaks ride on a Separator with an outline badge (`<Separator align="start"><Badge variant="neutral" appearance="outline" size="sm">COMING SOON</Badge></Separator>`); feature rows pair the label with a small soft badge (`appearance="soft" size="sm"`, tones `success` / `verified` / `primary`, optionally `trailingIcon={<RiCheckLine />}`).
+
+---
+
+## Spacing rhythm
+
+Three semantic tiers. They auto-scale across breakpoints, so never prefix them with `md:` / `xl:` (see [styling.md](./styling.md)).
+
+| Tier | Tokens | Scale (px) | Used for |
+| --- | --- | --- | --- |
+| Component | `gap-component-xs..xl`, `p-component-*` | 4 / 8 / 12 / 16 / 24 | inside one block: CTA button rows (`gap-component-sm`), heading-to-lede stacks (`gap-component-md`, `gap-component-xl`), card internals (`p-component-xl`), footer link lists (`gap-component-sm`) |
+| Section | `gap-section-xs..xl`, `p-section-*` | 12 / 16 / 24 / 32 / 48 | between clusters in one section: header cluster to toggle (`gap-section-lg`), plan-card row (`gap-section-sm`), newsletter panel padding (`p-section-xl`), footer grid columns (`gap-section-md`) |
+| Layout | `gap-layout-xs..xl`, `p-layout-*` | 32 / 48 / 64 / 96 / 128 | page level: section outer padding (`px-layout-sm py-layout-lg`), gaps between a page's top-level blocks (`gap-layout-sm`) |
+
+Rule of thumb from the site: a marketing section is `px-layout-sm py-layout-lg` outside, `gap-section-*` between its clusters, `gap-component-*` inside each cluster. If a Figma spec hands you a static value (e.g. `space-space-4`), use the plain Tailwind class (`gap-4`) instead; semantic spacing is for token-specified or site-recipe spacing.
+
+---
+
+## Richness checklist
+
+No UI should ship bare defaults - exercise each component's axes per SKILL.md "Use the full component API". This is most critical in marketing, landing, and showcase work; before calling a section done:
+
+- **Switch**: never a bare `<Switch />`. Pick a `variant` (`primary` | `info` | `neutral` | `inverse` | `semantic`) and exercise at least one extra axis: `ioTrigger` (I/O glyphs in the track), `thumbIcon` (check / cross on the thumb), `thumbType="long"`, or `shape="rounded"`.
+- **Badge**: choose `appearance` deliberately. `soft` is the workhorse tint (feature tags, discounts), `outline` is the quiet chip (version numbers, eyebrows on dark, COMING SOON), `solid` is for high-priority counts and statuses. Vary `variant` to match meaning and use `shape="pill"` for tag-like chips.
+- **SegmentedControl**: marketing and pricing toggles use `appearance="grouped"`; `flat` is for dense app toolbars.
+- **Avatar**: use a real color variant (`variant="gradient-blue"`, `"weak-green"`, `"base-indigo"`; pattern `{gradient|strong|base|weak|alpha}-{color}`) with `AvatarText` initials, or an `AvatarImage` plus `AvatarBadge` with `AvatarBadgeStatus variant="online"`. Never an empty gray circle.
+- **Button**: exactly one `appearance="solid"` action per section; secondary actions are `soft`, `ghost`, or `outline`. On dark panels both use `variant="inverse-solid"`. Icons go through `leadingIcon` / `trailingIcon`, never as children next to text (`iconOnly` buttons are the exception: there the icon is the child).
+- **Links**: inline and footer links are `TextLink` (e.g. `variant="neutral" size="sm"`), not styled `<a>` tags.
+
+---
+
+## Anti-patterns
+
+### Icon as a child inside Badge
+
+**Incorrect:**
+
+```tsx
+<Badge variant="success"><RiCheckLine className="size-3" /> Ready</Badge>
+```
+
+**Correct:**
+
+```tsx
+<Badge variant="success" appearance="soft" size="sm" trailingIcon={<RiCheckLine />}>Ready</Badge>
+```
+
+### Hand-rolled tab buttons
+
+**Incorrect:**
+
+```tsx
+<div className="flex gap-2 border-b">
+  <button className="border-b-2 border-primary-500 px-3 py-2">Preview</button>
+  <button className="px-3 py-2">Code</button>
+</div>
+```
+
+**Correct:**
+
+```tsx
+<TabMenu variant="horizontal-line" indicator="bottom" value={tab} onValueChange={setTab}>
+  <TabMenuItem value="preview" label="Preview" />
+  <TabMenuItem value="code" label="Code" leadingIcon={<RiCodeFill />} />
+</TabMenu>
+{tab === "preview" ? <PreviewPanel /> : <CodePanel />}
+```
+
+### Flat pricing toggle
+
+**Incorrect:**
+
+```tsx
+<div className="flex rounded-lg border">
+  <button className="bg-primary-500 px-4 py-2 text-white">Monthly</button>
+  <button className="px-4 py-2">Yearly</button>
+</div>
+```
+
+**Correct:**
+
+```tsx
+<SegmentedControl appearance="grouped" variant="neutral" size="xl" value={billing} onValueChange={setBilling}>
+  <SegmentedControlItem value="monthly">Monthly</SegmentedControlItem>
+  <SegmentedControlItem value="yearly">Yearly</SegmentedControlItem>
+</SegmentedControl>
+```
+
+### Bare Switch in a showcase
+
+**Incorrect:**
+
+```tsx
+<Switch />
+```
+
+**Correct:**
+
+```tsx
+<Switch variant="primary" size="md" ioTrigger defaultChecked />
+<Switch variant="neutral" size="md" shape="rounded" thumbIcon />
+```
+
+### Raw palette colors in the footer
+
+**Incorrect:**
+
+```tsx
+<footer className="bg-slate-900">
+  <h3 className="text-indigo-400">Products</h3>
+  <a className="text-blue-500 hover:text-blue-400" href="/docs">Docs</a>
+</footer>
+```
+
+**Correct:**
+
+```tsx
+<footer className="bg-static">
+  <h3 className="text-body-md text-strongest font-semibold">Products</h3>
+  <TextLink href="/docs" variant="neutral" size="sm">Docs</TextLink>
+</footer>
+```
+
+When unsure, adapt a recipe from this file as a starting point (to the user's brand, not as a createui.co clone), or fetch a real implementation to study: `get_item_examples_from_registries` over MCP, or `npx @create-ui/cli view <name>`.

package/dist/skills/createui/rules/forms.md

@@ -7,6 +7,7 @@
 - InputGroup requires InputGroupControl/InputGroupTextarea
 - Buttons inside inputs use InputGroup + InputGroupButton
 - Option sets (2–7 choices) use SegmentedControl
+- Switches are richer than the bare default
 - Dropdowns use Select
 - FieldSet + FieldLegend for grouping related fields
 - Field validation and disabled states
@@ -15,7 +16,7 @@
 
 ## Forms use FieldGroup + Field
 
-Always lay out a form with `FieldGroup` + `Field` — never a raw `div` with `space-y-*`. `Field` owns the size, invalid, disabled and loading state for everything inside it, and the nested control reads that state automatically.
+Always lay out a form with `FieldGroup` + `Field` - never a raw `div` with `space-y-*`. `Field` owns the size, invalid, disabled and loading state for everything inside it, and the nested control reads that state automatically.
 
 **Incorrect:**
 
@@ -47,11 +48,12 @@ import { Input } from "@/components/ui/input"
 </FieldGroup>
 ```
 
-`Field` accepts `size` (`"xs" | "sm" | "md"`, default `"sm"`) and `orientation` (`"vertical" | "horizontal" | "responsive"`, default `"vertical"`). Size cascades top-down: set it once on `Field` and the control, label, and description inherit it — never re-set the size on each child.
+`Field` accepts `size` (`"xs" | "sm" | "md"`, default `"sm"`) and `orientation` (`"vertical" | "horizontal" | "responsive"`, default `"vertical"`). Size cascades top-down: set it once on `Field` and the control, label, and description inherit it - never re-set the size on each child.
 
 ```tsx
-// Horizontal layout for settings rows.
-<Field orientation="horizontal">
+// Horizontal layout for settings rows (apply-immediately rows use SwitchGroup instead;
+// Field size does not cascade to Switch, so pair the sizes explicitly).
+<Field size="md" orientation="horizontal">
   <FieldLabel htmlFor="notifications">Email notifications</FieldLabel>
   <Switch id="notifications" />
 </Field>
@@ -72,11 +74,12 @@ Every control below exists in the registry. Pick by intent:
 | Single-line text | `Input` |
 | Multi-line text | `Textarea` |
 | Dropdown of predefined options | `Select` |
-| Boolean in a settings row | `Switch` |
+| Bare boolean toggle (no label row) | `Switch` |
+| Labelled apply-immediately settings row | `SwitchGroup` (one labelled row per switch) |
 | Boolean in a form | `Checkbox` |
 | One choice from a few options | `RadioGroup` |
 | One choice across 2–7 visible options | `SegmentedControl` |
-| Several related on/off options | `CheckboxGroup` / `SwitchGroup` |
+| Several related on/off options | one labelled row per option - stack `CheckboxGroup` rows (submit-to-save) / `SwitchGroup` rows (apply-immediately) |
 | Verification / OTP code | `InputOTP` |
 | Numeric value with step controls | `InputStepper` |
 | Date | `DateInput` |
@@ -122,7 +125,7 @@ import { InputGroup, InputGroupTextarea } from "@/components/ui/input-group"
 
 ## Buttons inside inputs use InputGroup + InputGroupButton
 
-Never absolutely-position a `Button` over an `Input`. Compose `InputGroup` + `InputGroupButton` (or `InputGroupAddon` for non-interactive affordances). `InputGroupButton` inherits the group's size and state, so you don't set `size` on it. Pass the icon through `leadingIcon`, or use `iconOnly` for an icon-only button — never a `data-icon` attribute.
+Never absolutely-position a `Button` over an `Input`. Compose `InputGroup` + `InputGroupButton` (or `InputGroupAddon` for non-interactive affordances). `InputGroupButton` inherits the group's size and state, so you don't set `size` on it. With a text label pass the icon through `leadingIcon`; for an icon-only button set `iconOnly` and pass the icon as the child (like `Button`, `iconOnly` ignores `leadingIcon`) - never a `data-icon` attribute.
 
 **Incorrect:**
 
@@ -143,7 +146,9 @@ import { RiSearchLine } from "@create-ui/assets/icons"
 
 <InputGroup>
   <InputGroupControl placeholder="Search…" />
-  <InputGroupButton iconOnly aria-label="Search" leadingIcon={<RiSearchLine />} />
+  <InputGroupButton iconOnly aria-label="Search">
+    <RiSearchLine />
+  </InputGroupButton>
 </InputGroup>
 ```
 
@@ -195,7 +200,7 @@ import { SegmentedControl, SegmentedControlItem } from "@/components/ui/segmente
 </SegmentedControl>
 ```
 
-`SegmentedControl` is single-select: the value props are `value` / `defaultValue` / `onValueChange` (a string — there is no `type="multiple"`). Style it with `variant` (`primary` | `neutral`) and `appearance` (`flat` | `grouped`); items take `leadingIcon`. When more than one option can be active at once, that's not a segmented control — use `CheckboxGroup` (or `SwitchGroup`) instead.
+`SegmentedControl` is single-select: the value props are `value` / `defaultValue` / `onValueChange` (a string - there is no `type="multiple"`). Style it with `variant` (`primary` | `neutral`) and `appearance` (`flat` | `grouped` - `grouped` wraps the items in a padded `bg-weak` container, the classic pricing-toggle look; the active pill slides with an animated indicator in **both** appearances). Items take `leadingIcon` / `trailingIcon` / `iconOnly`. When more than one option can be active at once, that's not a segmented control - stack `CheckboxGroup` (or `SwitchGroup`) rows instead.
 
 Wrap a labelled segmented control in a `Field` and connect them with `aria-labelledby`:
 
@@ -213,17 +218,39 @@ import { SegmentedControl, SegmentedControlItem } from "@/components/ui/segmente
 </Field>
 ```
 
+The `Field` here must be `orientation="horizontal"` (or wrap the control in a plain `div`): a vertical Field applies `[&>*]:w-full` to every direct child, so an intrinsic-width control like `SegmentedControl` gets stretched to the full field width - `self-start` does not prevent it.
+
+---
+
+## Switches are richer than the bare default
+
+`Switch` is a Radix switch (`checked` / `onCheckedChange` / `defaultChecked`) with a much richer API than `<Switch />`: `variant` (`primary` | `info` | `neutral` | `inverse` | `semantic` - semantic is red when off, green when on), `size` (`xs` | `sm` | `md`), `shape` (`pill` | `rounded`), `thumbType` (`short` | `long`), and the `ioTrigger` / `thumbIcon` booleans for I/O glyphs and check/close icons. Bare defaults are for dense forms; settings pages and showcases should pick deliberate options:
+
+```tsx
+<Field size="md" orientation="horizontal">
+  <FieldLabel htmlFor="2fa">Enforce two-factor auth</FieldLabel>
+  <Switch id="2fa" thumbIcon defaultChecked />
+</Field>
+
+<Switch variant="semantic" thumbType="long" ioTrigger aria-label="Accept" />
+```
+
+`Field` size does not cascade to `Switch` (it reads only `SwitchContext`) - pair them explicitly: a default (sm) `Field` row takes `<Switch size="sm">`, and a bare (md) `Switch` belongs in a `<Field size="md">` row. `SwitchGroup` pairs the two automatically.
+
+Apply-immediately settings rows use `SwitchGroup` - one labelled row per switch; there is no `SwitchGroupItem` (compose `Switch` + `FieldContent` + `LabelMain` per `reference/switch-group.md`). Inside a submit-to-save form prefer `Checkbox` / `CheckboxGroup`: a switch implies the setting takes effect the moment it flips. If a task explicitly demands toggles plus a Save button, keep the toggles deliberately - but don't present that as the default form pattern.
+
 ---
 
 ## Dropdowns use Select
 
-`Select` is composed from Radix parts: `SelectTrigger`, `SelectValue`, `SelectContent`, and `SelectItem`. There is no `items` prop — render `SelectItem` children. Inside a `Field`, the trigger inherits the field's size, invalid, and disabled state automatically, so set them on `Field`, not on each part.
+`Select` is composed from Radix parts: `SelectTrigger`, `SelectValue`, `SelectContent`, and `SelectItem`. There is no `items` prop - render `SelectItem` children. Inside a `Field`, the trigger inherits the field's size, invalid, and disabled state automatically, so set them on `Field`, not on each part.
 
 ```tsx
 import { Field, FieldLabel } from "@/components/ui/field"
 import {
   Select,
   SelectContent,
+  SelectGroup,
   SelectItem,
   SelectTrigger,
   SelectValue,
@@ -236,21 +263,23 @@ import {
       <SelectValue placeholder="Select a role" />
     </SelectTrigger>
     <SelectContent>
-      <SelectItem value="admin">Admin</SelectItem>
-      <SelectItem value="editor">Editor</SelectItem>
-      <SelectItem value="viewer">Viewer</SelectItem>
+      <SelectGroup>
+        <SelectItem value="admin">Admin</SelectItem>
+        <SelectItem value="editor">Editor</SelectItem>
+        <SelectItem value="viewer">Viewer</SelectItem>
+      </SelectGroup>
     </SelectContent>
   </Select>
 </Field>
 ```
 
-`Select` accepts `size` (`"xs" | "sm" | "md"`), `invalid`, `disabled`, and `loading`. When it's not inside a `Field`, set these on the `Select` itself.
+`Select` accepts `size` (`"xs" | "sm" | "md"`), `invalid`, `disabled`, and `loading`. When it's not inside a `Field`, set these on the `Select` itself; inside a `Field` they cascade automatically - don't re-set them. Inside an `InputGroup`, also pass `variant="compact"` yourself - only the dedicated `InputGroupSelect` applies compact automatically.
 
 ---
 
 ## FieldSet + FieldLegend for grouping related fields
 
-Use `FieldSet` + `FieldLegend` to group related checkboxes, radios, or switches — not a `div` with a heading. `FieldLegend` takes `variant="legend"` (default, section-sized) or `variant="label"` (form-control-sized).
+Use `FieldSet` + `FieldLegend` to group related checkboxes, radios, or switches - not a `div` with a heading. `FieldLegend` takes `variant="legend"` (default, section-sized) or `variant="label"` (form-control-sized).
 
 ```tsx
 import {

package/dist/skills/createui/rules/icons.md

@@ -3,7 +3,9 @@
 ## Contents
 
 - [Icons and assets come from @create-ui/assets](#icons-and-assets-come-from-create-uiassets)
-- [Icons in Button use the leadingIcon / trailingIcon props](#icons-in-button-use-the-leadingicon--trailingicon-props)
+- [Icon props across components](#icon-props-across-components)
+- [Chip takes its icon as the first child](#chip-takes-its-icon-as-the-first-child)
+- [InlineAlert and Toast use icon subcomponents](#inlinealert-and-toast-use-icon-subcomponents)
 - [Icon-only buttons](#icon-only-buttons)
 - [No sizing classes on icons inside components](#no-sizing-classes-on-icons-inside-components)
 - [Pass icons as component values, not string keys](#pass-icons-as-component-values-not-string-keys)
@@ -12,7 +14,7 @@
 
 ## Icons and assets come from @create-ui/assets
 
-**All icons and marks come from `@create-ui/assets`** — Create UI's own asset library. Registry components already import from it, and the CLI ships those imports as-is. Never reach for `lucide-react`, `@tabler/icons-react`, or any other icon package.
+**All icons and marks come from `@create-ui/assets`** - Create UI's own asset library. Registry components already import from it, and the CLI ships those imports as-is. Never reach for `lucide-react`, `@tabler/icons-react`, or any other icon package.
 
 **General-purpose UI icons** → `@create-ui/assets/icons` (Remix Icon, `Ri*` names). This subpath re-exports [`@remixicon/react`](https://remixicon.com), so the full Remix set is available:
 
@@ -29,15 +31,15 @@ import { VisaColor } from "@create-ui/assets/payments"
 import { Docker } from "@create-ui/assets/brands"
 ```
 
-Subpaths: `icons` (Remix UI icons), `social`, `flags`, `payments`, `brands`, `banks`, `badges`, `crypto` (Web3 Icons). Marks that ship multiple treatments carry a suffix — pick the variant: `VisaColor` / `VisaBlack` / `VisaWhite`.
+Subpaths: `icons` (Remix UI icons), `social`, `flags`, `payments`, `brands`, `banks`, `badges`, `crypto` (Web3 Icons). Marks that ship multiple treatments carry a suffix - pick the variant: `VisaColor` / `VisaBlack` / `VisaWhite`.
 
-**Sizing & color differ from UI icons.** Standalone marks have their source dimensions stripped, so set a size explicitly (`className="size-6"` or `width`/`height`), and their brand colors are baked in — don't recolor; use the `Black` / `White` variant for contrast. This is the opposite of `Ri*` icons rendered *inside* Create UI components (`Button`, `DropdownMenuItem`, …), which are auto-sized via CVA — see [No sizing classes on icons inside components](#no-sizing-classes-on-icons-inside-components).
+**Sizing & color differ from UI icons.** Standalone marks have their source dimensions stripped, so set a size explicitly - and match the mark's aspect ratio: social/brand/crypto/badge marks are square 24×24 (`className="size-6"`), but payment marks are wide (most are 38×24; the `*Logotype` variants 58×24) and need paired classes like `className="h-5 w-8 shrink-0"`, never a square `size-*`. Brand colors are baked in - don't recolor; use the `Black` / `White` variant for contrast. This is the opposite of `Ri*` icons rendered *inside* Create UI components (`Button`, `DropdownMenuItem`, …), which are auto-sized via CVA - see [No sizing classes on icons inside components](#no-sizing-classes-on-icons-inside-components).
 
 ---
 
-## Icons in Button use the leadingIcon / trailingIcon props
+## Icon props across components
 
-`Button` accepts icons through the `leadingIcon` and `trailingIcon` props — not as children. The button sizes the icon automatically per `size` (via its CVA `[&_svg]:size-N`), so the icon never needs a sizing class. There is no `data-icon` attribute in Create UI.
+**Every component that supports inline icons takes them through the `leadingIcon` / `trailingIcon` props - never as children next to text.** This applies to `Button`, `Badge`, `SegmentedControlItem`, `TabMenuItem`, `BreadcrumbItem`, `TextLink`, and `ButtonGroupItem` (the generated icon matrix in SKILL.md is the authoritative list). The component sizes the icon automatically per `size` (via its CVA `[&_svg]:size-N`), so the icon never needs a sizing class. There is no `data-icon` attribute in Create UI.
 
 **Incorrect:**
 
@@ -47,10 +49,14 @@ Subpaths: `icons` (Remix UI icons), `social`, `flags`, `payments`, `brands`, `ba
   Search
 </Button>
 
-<Button>
-  Next
-  <RiArrowRightLine className="ml-2 size-4" />
-</Button>
+<Badge variant="primary" appearance="soft">
+  <RiSparklingFill />
+  Built with Create UI
+</Badge>
+
+<SegmentedControlItem value="grid">
+  <RiLayoutGridFill /> Grid
+</SegmentedControlItem>
 ```
 
 **Correct:**
@@ -58,36 +64,76 @@ Subpaths: `icons` (Remix UI icons), `social`, `flags`, `payments`, `brands`, `ba
 ```tsx
 <Button leadingIcon={<RiSearchLine />}>Search</Button>
 
-<Button trailingIcon={<RiArrowRightLine />}>Next</Button>
+<Badge variant="primary" appearance="soft" leadingIcon={<RiSparklingFill />}>
+  Built with Create UI
+</Badge>
+
+<SegmentedControlItem value="grid" leadingIcon={<RiLayoutGridFill />}>
+  Grid
+</SegmentedControlItem>
+
+<TabMenuItem value="billing" label="Billing" leadingIcon={<RiBankCardLine />} />
+```
+
+The icon-as-children cases are: `iconOnly` mode on `Button`, `Badge`, `SegmentedControlItem`, and `ButtonGroupItem` (the icon IS the children there - `leadingIcon` / `trailingIcon` are ignored), and menu-ish items like `DropdownMenuItem` / `CommandItem`, where a bare `<RiIcon />` child before the text is the convention. All four `iconOnly` components follow the same rule, so `<SegmentedControlItem iconOnly aria-label="Grid"><RiLayoutGridFill /></SegmentedControlItem>`. When in doubt, check `reference/<component>.md`.
+
+---
+
+## Chip takes its icon as the first child
+
+`Chip` has **no** `leadingIcon` / `trailingIcon` props. Its first element child (an icon or an `Avatar`) is auto-slotted into the lead position and sized by the chip; the close affordance comes from `closable` / `onClose`.
+
+```tsx
+<Chip closable onClose={remove}><RiUserLine />Ayse Yilmaz</Chip>
+<Chip><Avatar size="2xs"><AvatarText>AY</AvatarText></Avatar>Ayse</Chip>
 ```
 
 ---
 
+## InlineAlert and Toast use icon subcomponents
+
+`InlineAlert` and `Toast` take their icon through dedicated subcomponents, not props:
+
+```tsx
+<InlineAlert variant="danger" appearance="soft">
+  <InlineAlertIcon><RiErrorWarningFill /></InlineAlertIcon>
+  <InlineAlertContent>
+    <InlineAlertTitle>Payment failed</InlineAlertTitle>
+  </InlineAlertContent>
+</InlineAlert>
+```
+
+`FieldHelper` is the exception that takes an `icon` prop.
+
+---
+
 ## Icon-only buttons
 
-For a button that shows only an icon, set `iconOnly`, pass the icon via `leadingIcon`, and always supply an `aria-label`. There is no separate icon-button component. For a close affordance, use the `close-button` component instead.
+For a button that shows only an icon, set `iconOnly`, pass the icon as the CHILD, and always supply an `aria-label`. In `iconOnly` mode `leadingIcon` / `trailingIcon` are silently ignored - a `<Button iconOnly leadingIcon={...} />` renders empty. There is no separate icon-button component. For a close affordance, use the `close-button` component instead.
 
 **Incorrect:**
 
 ```tsx
-<Button>
-  <RiSearchLine className="size-4" />
-</Button>
+<Button iconOnly aria-label="Search" leadingIcon={<RiSearchLine />} />
 ```
 
 **Correct:**
 
 ```tsx
-<Button iconOnly aria-label="Search" leadingIcon={<RiSearchLine />} />
+<Button iconOnly aria-label="Search">
+  <RiSearchLine />
+</Button>
 
-<Button iconOnly aria-label="More options" appearance="ghost" leadingIcon={<RiMore2Line />} />
+<Button iconOnly aria-label="More options" appearance="ghost">
+  <RiMore2Line />
+</Button>
 ```
 
 ---
 
 ## No sizing classes on icons inside components
 
-Components handle icon sizing via CSS. Don't add `size-4`, `w-4 h-4`, or other sizing classes to icons rendered inside `Button`, `DropdownMenuItem`, `InlineAlert`, `Toast`, or other Create UI components — unless the user explicitly asks for a custom icon size.
+Components handle icon sizing via CSS. Don't add `size-4`, `w-4 h-4`, or other sizing classes to icons rendered inside `Button`, `DropdownMenuItem`, `InlineAlert`, `Toast`, or other Create UI components - unless the user explicitly asks for a custom icon size.
 
 **Incorrect:**