@create-ui/cli 0.5.8 → 0.5.9

package/dist/skills/createui/reference/accordion.md

@@ -0,0 +1,127 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/accordion.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/accordion.md -->
+
+# accordion
+
+Vertically stacked disclosure panels for FAQs and settings; six appearances from ghost-default to filled-rounded
+
+Install: `npx @create-ui/cli add accordion`
+
+## Import
+
+```tsx
+import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from "@/components/ui/accordion"
+```
+
+## Accordion props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| appearance | `ghost-default \| ghost-underline \| ghost-rounded \| outline-rounded \| outline-sharp \| filled-rounded` (Set on the root Accordion only; it cascades to Item/Trigger/Content via React context. Subcomponents have no appearance prop.) | `ghost-default` |
+
+Extends `React.ComponentProps<typeof AccordionPrimitive.Root>`.
+
+## AccordionTrigger props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| icon | `ReactNode` (Leading icon only (wrapper auto-sizes the svg to size-5); it does NOT replace the built-in trailing chevron.) | - |
+
+Extends `React.ComponentProps< typeof AccordionPrimitive.Trigger >`.
+
+## Examples
+
+From `accordion-demo`:
+
+```tsx
+import {
+  Accordion,
+  AccordionContent,
+  AccordionItem,
+  AccordionTrigger,
+} from "@/components/ui/accordion"
+
+export default function AccordionDemo() {
+  return (
+    <Accordion
+      type="single"
+      collapsible
+      appearance="filled-rounded"
+      defaultValue="accessible"
+      className="w-full max-w-[560px]"
+    >
+      <AccordionItem value="accessible">
+        <AccordionTrigger>Is it accessible?</AccordionTrigger>
+        <AccordionContent>
+          Yes. It follows the WAI-ARIA disclosure pattern.
+        </AccordionContent>
+      </AccordionItem>
+      <AccordionItem value="animated">
+        <AccordionTrigger>Is it animated?</AccordionTrigger>
+        <AccordionContent>
+          Yes. Expand, collapse, and chevron rotation are animated.
+        </AccordionContent>
+      </AccordionItem>
+    </Accordion>
+  )
+}
+```
+
+From `accordion-with-trailing-content`:
+
+```tsx
+import { RiAlertFill, RiBankCardFill } from "@create-ui/assets/icons"
+
+import {
+  Accordion,
+  AccordionContent,
+  AccordionItem,
+  AccordionTrigger,
+} from "@/components/ui/accordion"
+import { Badge } from "@/components/ui/badge"
+
+export default function AccordionWithTrailingContent() {
+  return (
+    <Accordion type="single" collapsible className="w-full max-w-[560px]">
+      <AccordionItem value="payment">
+        <AccordionTrigger icon={<RiBankCardFill />}>
+          Why isn’t my payment going through?
+          <Badge
+            variant="warning"
+            appearance="soft"
+            size="sm"
+            leadingIcon={<RiAlertFill />}
+            className="ml-auto"
+          >
+            Issue
+          </Badge>
+        </AccordionTrigger>
+        <AccordionContent>
+          Usually caused by incorrect card details, insufficient funds, or a
+          temporary block from your bank.
+        </AccordionContent>
+      </AccordionItem>
+    </Accordion>
+  )
+}
+```
+
+More: `npx @create-ui/cli view accordion` or MCP `get_item_examples_from_registries` with "accordion-demo" / "accordion-example".
+
+## When to use
+A vertical stack of same-shaped disclosure rows: FAQs, settings groups, expandable lists. Do NOT use it for switching between sibling views (use TabMenu or SegmentedControl) or for blocking overlay content (there is no dialog/modal component; the only modal surface is CommandDialog - surface such flows inline or on a route). There is no separate Collapsible component; for one standalone show/hide region use a single-item Accordion with type="single" collapsible.
+
+## Gotchas
+- `appearance` lives only on the root and flows down via context. An `AccordionItem`/`AccordionTrigger`/`AccordionContent` rendered outside an `Accordion` silently falls back to `ghost-default` styling.
+- The rotating chevron is built in and always trailing; never add your own. Trailing badges/status go in trigger `children` with `ml-auto` (children render inside a `flex-1` label slot that sits before the chevron):
+
+```tsx
+<AccordionTrigger icon={<RiBankCardFill />}>
+  Why is my payment failing?
+  <Badge variant="warning" size="sm" className="ml-auto">Issue</Badge>
+</AccordionTrigger>
+```
+
+- `AccordionContent`'s `className` merges onto the inner padding wrapper, not the outer animated Radix element; the expand/collapse animation and `overflow-hidden` cannot be overridden there. The inner wrapper already supplies `flex flex-col gap-4`, so direct children stack; do not add your own stack wrapper.
+- `AccordionItem`s must be direct siblings: `ghost-underline` uses `border-b last:border-b-0` and `outline-sharp` collapses borders with `-mt-px first:mt-0`. Wrapping items in extra divs breaks separators and border collapsing.
+- The focus-visible ring is drawn on `AccordionItem` (via a `has-[[data-slot=accordion-trigger]:focus-visible]` selector); the trigger base is `outline-hidden`. Restyle the focus ring on the Item, not the trigger.
+- The root bakes in `min-w-90` (360px); in narrower containers override it via `className` on `Accordion`.

package/dist/skills/createui/reference/app-store-badge.md

@@ -0,0 +1,88 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/app-store-badge.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/app-store-badge.md -->
+
+# app-store-badge
+
+Marketplace download link badge covering 12 brands like App Store and Google Play; variant black/white, iconOnly option
+
+Install: `npx @create-ui/cli add app-store-badge`
+
+## Import
+
+```tsx
+import { AppStoreBadge } from "@/components/ui/app-store-badge"
+```
+
+Also exported: `appStoreBadgeVariants`
+
+## AppStoreBadge props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `black \| white` (Pick by the surface the badge sits on, not the app theme; filled colors are literal neutrals that never flip in dark mode) | `black` |
+| appearance | `filled \| outline` | `filled` |
+| iconOnly | `boolean` (Removes all visible text and the SVGs carry no title, so the link has no accessible name - always add an aria-label) | `false` |
+| brand | `app-store \| google-play \| galaxy-store \| shopify-store \| spotify \| add-on \| chrome-web-store \| app-gallery \| windows \| amazon-store \| microsoft \| youtube-music` (Required; selects glyph, subtitle, and title from a fixed preset - the copy is not customizable) | - |
+| asChild | `boolean` (The child element's own children are replaced with the badge content; the child only supplies the wrapper element and its props) | `false` |
+
+Extends `React.ComponentProps<"a">`.
+
+## Icons
+
+Icons go through icon props - never as children next to text, and never with sizing classes (the component sizes icons per `size`): `AppStoreBadge` (). Import icons from `@create-ui/assets/icons` (Remix `Ri*`).
+
+## Examples
+
+From `app-store-badge-demo`:
+
+```tsx
+import { AppStoreBadge } from "@/components/ui/app-store-badge"
+
+export default function AppStoreBadgeDemo() {
+  return (
+    <div className="flex flex-wrap items-center gap-2 rounded-2xl bg-white p-4">
+      <AppStoreBadge brand="app-store" href="#" />
+      <AppStoreBadge brand="google-play" href="#" />
+    </div>
+  )
+}
+```
+
+From `app-store-badge-in-surface`:
+
+```tsx
+import { AppStoreBadge } from "@/components/ui/app-store-badge"
+
+export default function AppStoreBadgeInSurface() {
+  return (
+    <div className="flex flex-col items-start gap-4 rounded-lg bg-black p-6">
+      <div className="flex flex-col gap-1">
+        <p className="text-base font-medium text-neutral-50">Get the app</p>
+        <p className="text-sm text-neutral-400">
+          Take Create UI with you, on any device.
+        </p>
+      </div>
+      <div className="flex flex-wrap items-center gap-2">
+        <AppStoreBadge brand="app-store" variant="white" href="#" />
+        <AppStoreBadge brand="google-play" variant="white" href="#" />
+      </div>
+    </div>
+  )
+}
+```
+
+More: `npx @create-ui/cli view app-store-badge` or MCP `get_item_examples_from_registries` with "app-store-badge-demo" / "app-store-badge-example".
+
+## When to use
+Branded download CTA linking to an external storefront (App Store, Google Play, Chrome Web Store, Spotify, etc.) on landing pages, footers, and CTA panels. It renders an `<a>` by default; pass `href` directly. Do NOT use it for generic in-product actions (use `Button`), for passive status/count labels (use `Badge`), or for "sign in with provider" buttons (use `SocialLoginButton`).
+## Gotchas
+- Children are silently discarded in normal usage: the icon + subtitle + title are generated entirely from `brand`. You cannot customize the copy via children or any prop.
+- With `asChild`, the single child element's own children are also replaced (`cloneElement(child, undefined, content)`). The child is only the wrapper, e.g. an anchor or Next.js `Link` with `href` and `aria-label`, never text content:
+```tsx
+<AppStoreBadge asChild brand="app-store">
+  <a href="https://apps.apple.com" aria-label="Download on the App Store" />
+</AppStoreBadge>
+```
+- There are no `leadingIcon`/`trailingIcon` props on this component; ignore any generic icon-prop guidance. The glyph is auto-selected from `brand` + `variant` + `appearance`: full-color for `filled`, monochrome black/white for `outline`. The monochrome brands (`app-store`, `amazon-store`) flip to the contrast glyph on filled with pinned literal colors so dark mode cannot recolor them.
+- Filled backgrounds are literal `bg-neutral-950`/`bg-neutral-50` and intentionally do not respond to dark mode; only the `outline` appearance uses theme tokens. Choose `variant` by the actual surface color (white variant on dark panels) and do not "fix" contrast via `className` color overrides.
+- `iconOnly` drops the text entirely, leaving the anchor with no accessible name; pair it with an `aria-label` naming the destination (e.g. "Download on the App Store").
+- Hover feedback is opacity-based and built in (`hover:opacity-90`); do not add your own hover background classes.

package/dist/skills/createui/reference/aspect-ratio.md

@@ -0,0 +1,52 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/aspect-ratio.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/aspect-ratio.md -->
+
+# aspect-ratio
+
+Constrains children like images or video embeds to a fixed width-to-height ratio via the ratio prop
+
+Install: `npx @create-ui/cli add aspect-ratio`
+
+## Import
+
+```tsx
+import { AspectRatio } from "@/components/ui/aspect-ratio"
+```
+
+## Examples
+
+From `aspect-ratio-demo`:
+
+```tsx
+import { AspectRatio } from "@/components/ui/aspect-ratio"
+
+export default function AspectRatioDemo() {
+  return (
+    <div className="w-full max-w-[480px]">
+      <AspectRatio
+        ratio={16 / 9}
+        className="from-light to-weak rounded-lg bg-gradient-to-br"
+      />
+    </div>
+  )
+}
+```
+
+More: `npx @create-ui/cli view aspect-ratio` or MCP `get_item_examples_from_registries` with "aspect-ratio-demo" / "aspect-ratio-example".
+
+## When to use
+Reserve a fixed width-to-height slot for media: image thumbnails in grids, video or iframe embeds, cover photos. Do NOT use it for circular user portraits; that is Avatar's job in Create UI. It is a layout-only wrapper with no visual styling of its own.
+
+## Gotchas
+- It has no width of its own and stretches to its parent, so wrap it in a width-constrained container; aspect-ratio-demo wraps it in `<div className="w-full max-w-[480px]">`.
+- It only reserves the box; it never crops or stretches the child. The registry examples pair it with next/image `fill` plus `h-full w-full object-cover` on the image.
+- Rounding the AspectRatio does not clip the child: the registry examples repeat `rounded-lg` on both the AspectRatio and the inner Image.
+- The source is a bare pass-through of Radix `AspectRatio.Root` plus `data-slot="aspect-ratio"`: no CVA variants, no size prop, no `cn()`, no Field/InputGroup context participation. Nothing cascades into or out of it.
+- Children are optional: aspect-ratio-demo renders a self-closing `<AspectRatio />` with only gradient background classes as a placeholder slot.
+
+```tsx
+<div className="w-full max-w-[480px]">
+  <AspectRatio ratio={16 / 9} className="bg-weak rounded-lg">
+    <Image src="/photo.jpg" alt="Photo" fill className="h-full w-full rounded-lg object-cover" />
+  </AspectRatio>
+</div>
+```

package/dist/skills/createui/reference/avatar.md

@@ -0,0 +1,230 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/avatar.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/avatar.md -->
+
+# avatar
+
+Avatar with AvatarImage, AvatarText initials fallback, AvatarIcon, AvatarBadge and AvatarGroup; 55 color variants
+
+Install: `npx @create-ui/cli add avatar`
+
+## Import
+
+```tsx
+import { Avatar, AvatarImage, AvatarText, AvatarIcon, AvatarRing, AvatarBadge, AvatarBadgeText, AvatarBadgeIcon, AvatarBadgeFlag, AvatarBadgeLogo, AvatarBadgePolygon, AvatarBadgeStatus, AvatarGroup, AvatarGroupAction } from "@/components/ui/avatar"
+```
+
+Also exported: `avatarVariants`, `badgeTextVariants`, `badgeIconVariants`, `badgeFlagVariants`, `badgeLogoVariants`, `badgePolygonVariants`, `avatarGroupVariants`, `avatarGroupActionVariants`
+
+## Avatar props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `2xs \| xs \| sm \| md \| lg \| xl \| 2xl` | `md` |
+| shape | `circle \| rounded` | `circle` |
+| variant | `{gradient\|strong\|base\|weak\|alpha}-{inverse\|neutral\|red\|green\|orange\|blue\|sky\|indigo\|fuchsia\|yellow\|stable} (55 values)` (color recipe {style}-{hue}; e.g. weak-blue for initials, gradient-indigo for showcases) | - |
+| background | `boolean` (set false when AvatarImage always loads) | `true` |
+| stroke | `boolean` (hairline outline; defaults ON for a standalone Avatar, OFF inside AvatarGroup) | - |
+
+Extends `React.ComponentProps<"div">`.
+
+## AvatarIcon props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `{base\|weak\|strong}-{inverse\|neutral\|red\|green\|orange\|blue\|sky\|indigo\|fuchsia\|yellow\|stable} (33 values)` (color recipe {style}-{hue}; e.g. weak-blue for initials, gradient-indigo for showcases) | - |
+
+Extends `React.ComponentProps<"span">`.
+
+## AvatarRing props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `full \| progress \| loading` (color recipe {style}-{hue}; e.g. weak-blue for initials, gradient-indigo for showcases) | `full` |
+| value | `number` | `100` |
+| color | `strongest \| static \| error \| success \| info \| away \| linear-1 \| linear-2 \| linear-3` | `info` |
+| strokeWidth | `number` | - |
+| gap | `number` | - |
+| size | `2xs \| xs \| sm \| md \| lg \| xl \| 2xl` | - |
+
+Extends `React.ComponentProps<"div">`.
+
+## AvatarBadge props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| position | `top \| bottom` | `bottom` |
+
+Extends `React.ComponentProps<"span">`.
+
+## AvatarBadgeText props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md \| lg` | `lg` |
+| color | `rose \| blue` | `rose` |
+
+Extends `React.ComponentProps<"span">`.
+
+## AvatarBadgeIcon props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md \| lg` | `lg` |
+| shape | `circle \| rounded` | `circle` |
+| color | `yellow \| green \| violet \| blue \| sky \| red \| amber \| heavy \| strongest \| light \| static-white` | `blue` |
+
+Extends `React.ComponentProps<"span">`.
+
+## AvatarBadgeFlag props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md \| lg` | `lg` |
+| shape | `circle \| rounded` | `circle` |
+
+Extends `React.ComponentProps<"span">`.
+
+## AvatarBadgeLogo props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md \| lg` | `lg` |
+| shape | `circle \| rounded` | `circle` |
+
+Extends `React.ComponentProps<"span">`.
+
+## AvatarBadgePolygon props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `xs \| sm \| md \| lg` | `lg` |
+| color | `sky \| yellow \| neutral-100 \| neutral-700 \| light` | `sky` |
+
+Extends `React.ComponentProps<"span">`.
+
+## AvatarBadgeStatus props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `invisible \| online \| busy \| offline \| away \| do-not-disturb \| recording \| typing` (color recipe {style}-{hue}; e.g. weak-blue for initials, gradient-indigo for showcases) | `online` |
+| size | `xs \| sm \| md \| lg` | - |
+| shape | `circle \| rounded` | `circle` |
+
+Extends `React.ComponentProps<"span">`.
+
+## AvatarGroup props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `2xs \| xs \| sm \| md \| lg \| xl \| 2xl` | `md` |
+| shape | `circle \| rounded` | `circle` |
+| variant | `{gradient\|strong\|base\|weak\|alpha}-{inverse\|neutral\|red\|green\|orange\|blue\|sky\|indigo\|fuchsia\|yellow\|stable} (55 values)` (color recipe {style}-{hue}; e.g. weak-blue for initials, gradient-indigo for showcases) | - |
+
+Extends `React.ComponentProps<"div">`.
+
+## AvatarGroupAction props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| size | `2xs \| xs \| sm \| md \| lg \| xl \| 2xl` | `md` |
+| shape | `circle \| rounded` | `circle` |
+
+Extends `React.ComponentProps<"span">`.
+
+## Examples
+
+From `avatar-demo`:
+
+```tsx
+import {
+  Avatar,
+  AvatarBadge,
+  AvatarBadgeStatus,
+  AvatarImage,
+  AvatarText,
+} from "@/components/ui/avatar"
+
+export default function AvatarDemo() {
+  return (
+    <div className="flex flex-wrap items-center gap-4">
+      <Avatar stroke={false}>
+        <AvatarImage
+          src="https://createui.co/avatars/ayla-karagoz.webp"
+          alt="Ayla Karagöz"
+        />
+      </Avatar>
+      <Avatar stroke={false}>
+        <AvatarImage
+          src="https://createui.co/avatars/luca-moretti.webp"
+          alt="Luca Moretti"
+        />
+        <AvatarBadge>
+          <AvatarBadgeStatus variant="online" />
+        </AvatarBadge>
+      </Avatar>
+      <Avatar variant="weak-blue" stroke={false}>
+        <AvatarText>YT</AvatarText>
+      </Avatar>
+    </div>
+  )
+}
+```
+
+From `avatar-group`:
+
+```tsx
+import { Avatar, AvatarGroup, AvatarImage } from "@/components/ui/avatar"
+
+const people = [
+  {
+    src: "https://createui.co/avatars/ayla-karagoz.webp",
+    name: "Ayla Karagöz",
+  },
+  {
+    src: "https://createui.co/avatars/luca-moretti.webp",
+    name: "Luca Moretti",
+  },
+  { src: "https://createui.co/avatars/yuki-tanaka.webp", name: "Yuki Tanaka" },
+  { src: "https://createui.co/avatars/sofia-reis.webp", name: "Sofia Reis" },
+]
+
+const sizes = ["sm", "md", "lg"] as const
+
+export default function AvatarGroupExample() {
+  return (
+    <div className="flex flex-col gap-6">
+      {sizes.map((size) => (
+        <AvatarGroup key={size} size={size}>
+          {people.map((person) => (
+            <Avatar key={person.name}>
+              <AvatarImage src={person.src} alt={person.name} />
+            </Avatar>
+          ))}
+        </AvatarGroup>
+      ))}
+    </div>
+  )
+}
+```
+
+More: `npx @create-ui/cli view avatar` or MCP `get_item_examples_from_registries` with "avatar-demo" / "avatar-example".
+
+## When to use
+
+Identity thumbnail for a person, team, or brand: image, initials (`AvatarText`), or built-in person glyph (`AvatarIcon`), plus `AvatarRing` / `AvatarBadge` overlays and `AvatarGroup` stacks. Not for textual status or count labels (use `Badge`) or standalone presence dots with no portrait (use `StatusBadge`).
+
+## Gotchas
+
+- `AvatarFallback` does NOT exist; the fallback slot is `AvatarText`, placed as a sibling of `AvatarImage`. The image stays invisible until it reports loaded, and `AvatarText`/`AvatarIcon` auto-unmount once it does; an image avatar without an `AvatarText` shows only the background shape while loading or on error. Avatar has NO default `variant` (and no background fill without one), so whenever `AvatarText` is present - standalone initials or image fallback - always set a `variant` (e.g. `weak-neutral`, `weak-blue`), or the initials float on a transparent circle.
+
+```tsx
+<Avatar variant="weak-blue">
+  <AvatarImage src="/u.png" alt="User" />
+  <AvatarText>JD</AvatarText>
+</Avatar>
+```
+
+- `AvatarIcon` takes NO children; it draws its own built-in person glyph. Its own `variant` tints the glyph independently of the root `variant` (e.g. `base-red` icon on a `weak-red` avatar).
+- `AvatarGroup` separates children with its own white ring and paints a gradient placeholder background on every child avatar; child `stroke` switches off automatically inside it.
+- `AvatarGroup` cascades `size`/`shape`/`variant` to nested `Avatar`s (and `size`/`shape` to `AvatarGroupAction`) via context: set them once on the group, never per child.
+- `AvatarBadge*` content components must sit inside `AvatarBadge` (it does the corner positioning) and auto-size from the surrounding avatar's size (2xs/xs -> xs, sm/md -> sm, lg/xl -> md, 2xl -> lg); pass `size` only to break that pairing.
+- `AvatarRing` draws OUTSIDE the avatar's box via negative margin (stroke and gap scale with the avatar's size), so leave layout room around it; `variant="full"` ignores `value`, and `progress` clamps `value` to 0-100.

package/dist/skills/createui/reference/badge.md

@@ -0,0 +1,110 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/badge.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/badge.md -->
+
+# badge
+
+Passive non-interactive label for statuses and counts; leadingIcon, trailingIcon, iconOnly and numberOnly props
+
+Install: `npx @create-ui/cli add badge`
+
+## Import
+
+```tsx
+import { Badge } from "@/components/ui/badge"
+```
+
+Also exported: `badgeVariants`
+
+## Badge props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `primary \| neutral \| neutral-static \| danger \| success \| warning \| info \| verified \| highlighted \| away \| inverse \| inverse-static` | `primary` |
+| appearance | `solid \| outline \| soft \| ghost` | `soft` |
+| size | `xs \| sm \| md` | `sm` |
+| shape | `rounded \| pill` | `rounded` |
+| iconOnly | `boolean` (square badge; the icon is the children (NOT leadingIcon); pair with aria-label) | `false` |
+| numberOnly | `boolean` (count style with per-size min-width; children is the numeral) | `false` |
+| asChild | `boolean` (child renders as-is: icon props and the badge-label wrapper are dropped, root classes stay) | `false` |
+| disabled | `boolean` (visual only via data-disabled (muted text, pointer-events-none); renders a span, no HTML disabled attribute) | `false` |
+| leadingIcon | `ReactNode` | - |
+| trailingIcon | `ReactNode` | - |
+
+Extends `React.ComponentProps<"span">`.
+
+## Icons
+
+Icons go through icon props - never as children next to text, and never with sizing classes (the component sizes icons per `size`): `Badge` (`leadingIcon` / `trailingIcon`). Import icons from `@create-ui/assets/icons` (Remix `Ri*`).
+
+## Examples
+
+From `badge-demo`:
+
+```tsx
+import { RiCheckLine, RiSparklingFill } from "@create-ui/assets/icons"
+
+import { Badge } from "@/components/ui/badge"
+
+export default function BadgeDemo() {
+  return (
+    <div className="flex flex-wrap items-center gap-2">
+      <Badge>New</Badge>
+      <Badge variant="success" leadingIcon={<RiCheckLine />}>
+        Verified
+      </Badge>
+      <Badge variant="warning">Pending</Badge>
+      <Badge variant="danger" appearance="solid">
+        Down
+      </Badge>
+      <Badge variant="primary" iconOnly aria-label="Sparkle">
+        <RiSparklingFill />
+      </Badge>
+      <Badge variant="danger" numberOnly>
+        12
+      </Badge>
+    </div>
+  )
+}
+```
+
+From `badge-with-icon`:
+
+```tsx
+import { RiArrowRightLine, RiSparklingFill } from "@create-ui/assets/icons"
+
+import { Badge } from "@/components/ui/badge"
+
+export default function BadgeWithIcon() {
+  return (
+    <div className="flex flex-wrap items-center gap-2">
+      <Badge variant="primary" leadingIcon={<RiSparklingFill />}>
+        Leading
+      </Badge>
+      <Badge variant="primary" trailingIcon={<RiArrowRightLine />}>
+        Trailing
+      </Badge>
+      <Badge
+        variant="primary"
+        leadingIcon={<RiSparklingFill />}
+        trailingIcon={<RiArrowRightLine />}
+      >
+        Both
+      </Badge>
+    </div>
+  )
+}
+```
+
+More: `npx @create-ui/cli view badge` or MCP `get_item_examples_from_registries` with "badge-demo" / "badge-example".
+
+## When to use
+
+Passive, non-interactive labels: statuses, counts, metadata. Interactive or removable tags are `Chip`; bare presence dots are `StatusBadge`; anything clickable is `Button`; callouts with title and body are `InlineAlert`.
+
+## Gotchas
+
+- Color and fill are separate axes, unlike shadcn: `variant` is color only, `appearance` is fill. shadcn's `variant="outline"` is `appearance="outline"` here, and `variant="destructive"` is `variant="danger"`; there is no `secondary`.
+- With text, icons go ONLY through `leadingIcon` / `trailingIcon`, never as children. `iconOnly` inverts this: the icon IS the children (same convention as Button).
+- `iconOnly` and `numberOnly` render children only; any `leadingIcon` / `trailingIcon` passed alongside them is silently ignored.
+- `asChild` skips the content pipeline (icon props, the `badge-label` wrapper); the styled root classes still apply, so the child element must carry its full content itself.
+- The root is `w-fit`, so it never stretches in a flex column. Need full width? That is almost always the wrong component.
+- `appearance="ghost"` strips both the background and the horizontal padding (`px-0`), so it sits flush with surrounding content.