@create-ui/cli 0.5.8 → 0.6.0

package/dist/skills/createui/reference/phone-input.md

@@ -0,0 +1,77 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/phone-input.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/phone-input.md -->
+
+# phone-input
+
+Phone number input with a country flag select and dial code prefix; onValueChange emits the E.164 value
+
+Install: `npx @create-ui/cli add phone-input`
+
+## Import
+
+```tsx
+import { PhoneInput } from "@/components/ui/phone-input"
+```
+
+## PhoneInput props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| defaultValue | `string` (E.164 or national digits; the dial code is stripped only when it matches the active country, so pair it with the matching defaultCountry) | - |
+| defaultCountry | `PhoneCountryCode` | `DE` |
+| country | `PhoneCountryCode` | - |
+| onCountryChange | `(country: PhoneCountryCode) => void` | - |
+| onValueChange | `(value: string, details: PhoneInputDetails) => void` (Emits the full E.164 string ('' when empty) plus { country, dialCode, nationalNumber }; re-fires immediately when the country changes) | - |
+| countries | `PhoneCountryConfig[]` (Subset or reorder the dropdown; build entries from PHONE_COUNTRIES exported by use-phone-input (default: every country, sorted by English name)) | - |
+| size | `xs \| sm \| md` (Omit inside Field; InputGroup resolves it from Field context (falls back to sm)) | - |
+| invalid | `boolean` | - |
+| disabled | `boolean` | - |
+| loading | `boolean` | - |
+| showHelperIcon | `boolean` | `true` |
+| helperIcon | `ReactNode` | - |
+| helperTooltip | `ReactNode` (Pass null to keep the helper icon without a tooltip; hide the icon entirely with showHelperIcon={false}) | `Enter your phone number without the country code.` |
+| className | `string` | - |
+| ref | `React.Ref<HTMLInputElement>` | - |
+
+Extends `React.ComponentProps<"input">`.
+
+## Examples
+
+From `input-group-phone`:
+
+```tsx
+"use client"
+
+import { Field, FieldLabel } from "@/components/ui/field"
+import { PhoneInput } from "@/components/ui/phone-input"
+
+export default function InputGroupPhone() {
+  return (
+    <Field className="max-w-md">
+      <FieldLabel htmlFor="input-group-phone">Phone Number</FieldLabel>
+      <PhoneInput
+        id="input-group-phone"
+        defaultCountry="US"
+        onValueChange={(value, { country }) => console.log(value, country)}
+      />
+    </Field>
+  )
+}
+```
+
+More: `npx @create-ui/cli view phone-input` or MCP `get_item_examples_from_registries` with "phone-input-demo" / "phone-input-example".
+
+## When to use
+Complete phone-number field: country flag select, display-only dial code prefix, auto-formatting national-digit input, and an E.164 value via onValueChange. Use it whenever a form collects a phone number; do not rebuild it from InputGroup + InputGroupSelect + CountryFlag, because it already is exactly that composition. For other prefix-plus-select combos (amount, currency) compose InputGroup directly, and for plain text use Input.
+
+## Gotchas
+- It renders its own InputGroup; never nest it inside another InputGroup. Wrap it in Field for the label, and leave size/invalid/disabled/loading unset there so they cascade from Field context.
+- The text value cannot be controlled: native value/onChange are stripped from the prop type. Seed with defaultValue and read through onValueChange. Only the country supports controlled mode (country + onCountryChange).
+- The country is never auto-detected from the value (unlike react-phone-number-input). The dial code in defaultValue is stripped only when it matches the active country, so an E.164 defaultValue must ship with the matching defaultCountry or the dial digits leak into the national number:
+
+```tsx
+<PhoneInput defaultCountry="US" defaultValue="+15551234567" />
+```
+
+- The visible input holds national digits only, live-formatted per country by libphonenumber's AsYouType; the dial code is a display-only span. The E.164 string exists solely in the onValueChange payload, and an empty input emits "" rather than the bare dial code.
+- Switching country keeps the typed digits and instantly re-fires onValueChange with the new dial code applied to the same national number.
+- Non-digit keystrokes are stripped on input; do not layer your own masking or formatting on top.

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

@@ -0,0 +1,158 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/progress.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/progress.md -->
+
+# progress
+
+Determinate progress as a line or circle via the type prop; solid or gradient appearance, value/max with animated fill
+
+Install: `npx @create-ui/cli add progress`
+
+## Import
+
+```tsx
+import { Progress } from "@/components/ui/progress"
+```
+
+Also exported: `progressLineVariants`
+
+## Progress props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| type | `line \| circle` | `line` |
+| variant | `primary \| info \| success \| warning \| danger \| away \| neutral \| neutral-static \| neutral-soft \| inverse \| inverse-static \| inverse-soft` | `primary` |
+| appearance | `solid \| gradient` | `solid` |
+| size | `xs \| sm \| md \| lg` (Line: bar thickness; circle: fixed outer diameter (12/16/20/24px) with matching stroke width) | `md` |
+| shape | `sharp \| pill` (Visual effect on line only; the circle ring renders identically and merely emits data-shape) | `pill` |
+| value | `number` | `0` |
+| max | `number` (Values <= 0 silently fall back to 100; value is clamped to 0..max for both fill width and aria-valuenow) | `100` |
+| duration | `number` (Line only; overrides the default 300ms ease-out width transition. type=circle discards it (the ring has no transition at all)) | - |
+
+Extends `React.ComponentProps<"div">`.
+
+## Examples
+
+From `progress-demo`:
+
+```tsx
+import { Progress } from "@/components/ui/progress"
+
+export default function ProgressDemo() {
+  return (
+    <div className="flex items-center gap-8">
+      <div className="w-64">
+        <Progress value={42} />
+      </div>
+      <Progress type="circle" size="lg" value={42} />
+    </div>
+  )
+}
+```
+
+From `progress-upload`:
+
+```tsx
+"use client"
+
+import * as React from "react"
+import {
+  RiCheckLine,
+  RiRefreshLine,
+  RiUploadCloud2Line,
+} from "@create-ui/assets/icons"
+
+import { Button } from "@/components/ui/button"
+import { Progress } from "@/components/ui/progress"
+
+const DURATION_MS = 2000
+
+type Status = "idle" | "uploading" | "done" | "error"
+
+export default function ProgressUpload() {
+  const [attempt, setAttempt] = React.useState(0)
+  const [status, setStatus] = React.useState<Status>("idle")
+  const [progress, setProgress] = React.useState(0)
+
+  React.useEffect(() => {
+    if (status !== "uploading") return
+
+    // First attempt fails to demo the retry flow, later attempts succeed.
+    const willFail = attempt === 1
+    const target = willFail ? 60 : 100
+
+    const raf = requestAnimationFrame(() => setProgress(target))
+    const timeout = setTimeout(
+      () => setStatus(willFail ? "error" : "done"),
+      DURATION_MS
+    )
+
+    return () => {
+      cancelAnimationFrame(raf)
+      clearTimeout(timeout)
+    }
+  }, [status, attempt])
+
+  function startUpload() {
+    setProgress(0)
+    setAttempt((a) => a + 1)
+    setStatus("uploading")
+  }
+
+  const isUploading = status === "uploading"
+  const isDone = status === "done"
+  const isError = status === "error"
+
+  const variant = isDone ? "success" : isError ? "danger" : "primary"
+
+  return (
+    <div className="flex w-80 items-center gap-4">
+      <Progress
+        key={attempt}
+        value={progress}
+        duration={DURATION_MS}
+        variant={variant}
+      />
+      <Button
+        variant={variant}
+        loading={isUploading}
+        leadingIcon={
+          isDone ? (
+            <RiCheckLine />
+          ) : isError ? (
+            <RiRefreshLine />
+          ) : (
+            <RiUploadCloud2Line />
+          )
+        }
+        onClick={startUpload}
+        className="w-32 shrink-0"
+      >
+        {isDone
+          ? "Done"
+          : isError
+            ? "Retry"
+            : isUploading
+              ? "Uploading"
+              : "Upload"}
+      </Button>
+    </div>
+  )
+}
+```
+
+More: `npx @create-ui/cli view progress` or MCP `get_item_examples_from_registries` with "progress-demo" / "progress-example".
+
+## When to use
+Determinate progress against a known total: uploads, multi-step flows, download bars, and compact dashboard stat rings (type="circle"). Do not use it when duration or total is unknown; use Spinner for indeterminate loading. For a passive status or count that does not track completion, use Badge or Status Badge.
+
+## Gotchas
+- Single self-closing component built on plain divs, not Radix: there is no Root/Indicator subcomponent and `children` is type-omitted, so the shadcn pattern `<Progress><ProgressIndicator /></Progress>` will not compile. Render labels or percentage text outside the component.
+- `type="line"` is `w-full` and stretches to fill its parent; always wrap it in a width-constrained container. `type="circle"` sets width/height via inline style from `size`, so className width utilities cannot resize the ring.
+- Every `value` change animates the line width. To restart a fill from 0 (e.g. a retry), remount with a `key` and set the target value on the next frame, as progress-upload does; resetting value in place animates the bar backward first.
+
+```tsx
+<Progress key={attempt} value={progress} duration={2000} variant={isError ? "danger" : "primary"} />
+```
+
+- The root carries `role="progressbar"` and aria-valuemin/max/now automatically but has no accessible name; pass `aria-label` yourself (div props pass through).
+- The circle is pure CSS (conic-gradient arc + radial mask), no SVG, so there are no stroke props. The arc paints with `currentColor`; a `text-*` class on the component recolors it (the inline-styled indicator cannot be themed via `data-slot` CSS).
+- `inverse*` variants render in white/static-white tones for dark surfaces; the examples place them on a `bg-strongest` canvas.

package/dist/skills/createui/reference/radio-group.md

@@ -0,0 +1,133 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/radio-group.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/radio-group.md -->
+
+# radio-group
+
+Radix radio group wrapped in a Field; cascades variant and size to Radio items, placement left or right
+
+Install: `npx @create-ui/cli add radio-group`
+
+## Import
+
+```tsx
+import { RadioGroup } from "@/components/ui/radio-group"
+```
+
+Also exported: `radioGroupVariants`
+
+## RadioGroup props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `primary \| neutral \| danger` | `primary` |
+| size | `xs \| sm \| md` | `md` |
+| placement | `left \| right` (right only sets flex-row-reverse on the single Field row; in a stacked flex-col layout add flex-row-reverse to each per-option wrapper div instead) | `left` |
+| disabled | `boolean` (Styles the inner Field only; it is NOT forwarded to the Radix root, so also set disabled on each Radio to actually block interaction) | - |
+| invalid | `boolean` (Forwarded to the inner Field; variant='danger' does not set it for you - pass both together for a full error state) | - |
+| fieldClassName | `string` (Layout lives here: fieldClassName='flex-col items-stretch gap-4' is the stacked-list recipe; className only styles the outer Radix root) | - |
+
+Extends `React.ComponentProps<typeof RadioGroupPrimitive.Root>`.
+
+## Examples
+
+From `radio-group-demo`:
+
+```tsx
+import { FieldContent } from "@/components/ui/field"
+import { Label, LabelDescription, LabelMain } from "@/components/ui/label"
+import { Radio } from "@/components/ui/radio"
+import { RadioGroup } from "@/components/ui/radio-group"
+
+const options = [
+  { value: "free", title: "Free", description: "For personal projects." },
+  {
+    value: "pro",
+    title: "Pro",
+    description: "For freelancers and small teams.",
+  },
+  {
+    value: "team",
+    title: "Team",
+    description: "For larger teams with shared workspaces.",
+  },
+]
+
+export default function RadioGroupDemo() {
+  return (
+    <RadioGroup
+      defaultValue="pro"
+      className="w-[340px]"
+      fieldClassName="flex-col items-stretch gap-4"
+    >
+      {options.map((option) => (
+        <div key={option.value} className="flex items-start gap-2">
+          <Radio id={`plan-${option.value}`} value={option.value} />
+          <FieldContent>
+            <LabelMain>
+              <Label htmlFor={`plan-${option.value}`}>{option.title}</Label>
+              <LabelDescription>{option.description}</LabelDescription>
+            </LabelMain>
+          </FieldContent>
+        </div>
+      ))}
+    </RadioGroup>
+  )
+}
+```
+
+From `radio-group-controlled`:
+
+```tsx
+"use client"
+
+import * as React from "react"
+
+import { FieldContent } from "@/components/ui/field"
+import { Label, LabelMain } from "@/components/ui/label"
+import { Radio } from "@/components/ui/radio"
+import { RadioGroup } from "@/components/ui/radio-group"
+
+const options = ["light", "dark", "system"] as const
+
+export default function RadioGroupControlled() {
+  const [value, setValue] = React.useState<(typeof options)[number]>("system")
+
+  return (
+    <div className="flex flex-col gap-3">
+      <RadioGroup
+        value={value}
+        onValueChange={(next) => setValue(next as (typeof options)[number])}
+        className="w-[280px]"
+        fieldClassName="flex-col items-stretch gap-3"
+      >
+        {options.map((option) => (
+          <div key={option} className="flex items-start gap-2">
+            <Radio id={`theme-${option}`} value={option} />
+            <FieldContent>
+              <LabelMain>
+                <Label htmlFor={`theme-${option}`}>
+                  {option.charAt(0).toUpperCase() + option.slice(1)}
+                </Label>
+              </LabelMain>
+            </FieldContent>
+          </div>
+        ))}
+      </RadioGroup>
+      <p className="text-placeholder text-ui-control-sm">
+        Selected: <span className="text-body font-medium">{value}</span>
+      </p>
+    </div>
+  )
+}
+```
+
+More: `npx @create-ui/cli view radio-group` or MCP `get_item_examples_from_registries` with "radio-group-demo" / "radio-group-example".
+
+## When to use
+Single-select group where all options are visible at once (plan picker, theme, sort order). For multi-select use CheckboxGroup; for long collapsible lists use Select; for a lone on/off use Switch or Checkbox.
+## Gotchas
+- There is no `RadioGroupItem` (shadcn divergence): the item is the separate `Radio` component, and each option is composed manually as a wrapper div with `Radio` plus `FieldContent > LabelMain > Label / LabelDescription` (see radio-group-demo).
+- The component renders ONE `Field` wrapping all children, not a Field per option; `Label`/`LabelDescription` sizing and disabled/invalid styling all cascade from that single Field context.
+- `variant` and `size` cascade to every child `Radio` via `RadioContext`; an explicit prop on a `Radio` wins (`variant ?? ctx ?? default`). Radio's `success`/`inverse` variants cannot be set at group level - pass them per `Radio`.
+- `variant="danger"` recolors every descendant `[data-slot=field-footer]` to `text-error-base`, including per-option footers nested in `FieldContent`.
+- The Radix root sets `orientation="horizontal"` and `display: flex`; a vertical list comes purely from `fieldClassName="flex-col items-stretch ..."`, not from any orientation or layout prop.
+- Group `disabled` never reaches the Radix root, so radios stay interactive unless each `Radio` also gets `disabled` (the disabled demos in radio-group-example set both).

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

@@ -0,0 +1,79 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/radio.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/radio.md -->
+
+# radio
+
+Single radio item for use inside RadioGroup; five variants and xs/sm/md sizes inherit from group context
+
+Install: `npx @create-ui/cli add radio`
+
+## Import
+
+```tsx
+import { Radio } from "@/components/ui/radio"
+```
+
+Also exported: `RadioContext`, `radioVariants`, `radioIndicatorVariants`
+
+## Radio props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| variant | `primary \| neutral \| danger \| success \| inverse` (Own prop beats RadioGroup context; the only way to get success or inverse inside a group, since RadioGroup's own variant prop offers only primary/neutral/danger) | `primary` |
+| size | `xs \| sm \| md` (Resolved as own prop ?? RadioGroup context ?? md; the CVA defaultVariants sm is dead code because a resolved value is always passed) | `md` |
+
+Extends `React.ComponentProps<typeof RadioGroupPrimitive.Item>`.
+
+## Examples
+
+From `radio-demo`:
+
+```tsx
+import { Radio } from "@/components/ui/radio"
+import { RadioGroup } from "@/components/ui/radio-group"
+
+export default function RadioDemo() {
+  return (
+    <RadioGroup defaultValue="a">
+      <Radio value="a" aria-label="Option A" />
+      <Radio value="b" aria-label="Option B" />
+    </RadioGroup>
+  )
+}
+```
+
+From `radio-in-group`:
+
+```tsx
+import { Radio } from "@/components/ui/radio"
+import { RadioGroup } from "@/components/ui/radio-group"
+
+export default function RadioInGroup() {
+  return (
+    <div className="flex flex-col gap-6">
+      <RadioGroup variant="neutral" size="md" defaultValue="b">
+        <Radio value="a" aria-label="Option A" />
+        <Radio value="b" aria-label="Option B" />
+        <Radio value="c" aria-label="Option C" />
+      </RadioGroup>
+      <p className="text-placeholder text-ui-control-sm">
+        Children inherit <code>variant</code> and <code>size</code> from the
+        group via context — pass them on the group, not each child.
+      </p>
+    </div>
+  )
+}
+```
+
+More: `npx @create-ui/cli view radio` or MCP `get_item_examples_from_registries` with "radio-demo" / "radio-example".
+
+## When to use
+One item in a mutually-exclusive set of a few always-visible options, always rendered inside `RadioGroup` (it is a Radix RadioGroup.Item and cannot toggle on its own). For long option lists use `Select`; for a binary on/off setting use `Switch`; for standalone or multi-select choices use `Checkbox` / `CheckboxGroup`.
+
+## Gotchas
+- `Radio` and `RadioGroup` are separate registry items with separate import paths (`@/components/ui/radio` and `@/components/ui/radio-group`). There is no `RadioGroupItem` export; a shadcn-style `import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"` fails.
+- `Radio` renders its indicator dot internally and ignores children. Never nest a `RadioGroupPrimitive.Indicator`, a circle icon, or any content inside it.
+- Styling cascades from the group: `RadioGroup` publishes `variant`/`size` through `RadioContext`, so set them once on the group, not per child. A per-Radio prop overrides the context when one item must differ.
+- `RadioGroup` wraps its children in a horizontal `Field`, so labeled rows use `FieldLabel htmlFor` next to the radio (or `aria-label` when there is no visible label, as in `radio-demo`).
+- `RadioGroup`'s `invalid` and `disabled` props are passed only to the `Field` wrapper, never to the Radix root or the items: `invalid` colors the field footer but does not set `aria-invalid`, and `disabled` styles labels (cursor, pointer-events) while the radios stay interactive. The red outline needs `aria-invalid` on the `Radio` itself, and disabling needs `disabled` on each `Radio`.
+- `variant="danger"` only colors the checked/focus state; it does not mark the field invalid. The error outline comes solely from the item's `aria-invalid` attribute, on any variant.
+- `inverse` is built for dark surfaces: unchecked border and checked dot use light tokens, and focus-visible fills the control with static-black. `radio-example` shows it on a `bg-strongest` panel; on a light surface it is near-invisible.

package/dist/skills/createui/reference/scroll-area.md

@@ -0,0 +1,212 @@
+<!-- GENERATED FILE - do not edit. Source: registry/ui/scroll-area.tsx. Regenerate with `pnpm skill:build`. Curated notes: apps/v4/scripts/skill-reference/notes/scroll-area.md -->
+
+# scroll-area
+
+Custom-scrollbar viewport; vertical, horizontal or both, filled/ghost scrollbar styles and optional edge fade
+
+Install: `npx @create-ui/cli add scroll-area`
+
+## Import
+
+```tsx
+import { ScrollArea, ScrollBar } from "@/components/ui/scroll-area"
+```
+
+Also exported: `scrollBarVariants`
+
+## ScrollArea props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| appearance | `filled \| ghost` (filled adds a bg-weak track behind the thumb; ghost shows only the thumb; forwarded to all auto-rendered scrollbars) | `filled` |
+| size | `sm \| md \| lg` (Set once on ScrollArea; forwarded to every auto-rendered scrollbar) | `md` |
+| orientation | `vertical \| horizontal \| both` (Auto-renders the matching scrollbar(s); a Corner is always rendered, so 'both' needs no extra children) | `vertical` |
+| fade | `boolean` (End-of-scroll gradient only (bottom / right edge); hides at scroll end or when content fits, re-checked on scroll, resize, and DOM mutations) | `false` |
+
+Extends `React.ComponentProps<typeof ScrollAreaPrimitive.Root>`.
+
+## ScrollBar props
+
+| Prop | Type | Default |
+| --- | --- | --- |
+| appearance | `filled \| ghost` (filled adds a bg-weak track behind the thumb; ghost shows only the thumb; forwarded to all auto-rendered scrollbars) | `filled` |
+| size | `sm \| md \| lg` (Set once on ScrollArea; forwarded to every auto-rendered scrollbar) | `md` |
+
+Extends `React.ComponentProps<typeof ScrollAreaPrimitive.ScrollAreaScrollbar>`.
+
+## Examples
+
+From `scroll-area-demo`:
+
+```tsx
+import * as React from "react"
+
+import { ScrollArea } from "@/components/ui/scroll-area"
+import { Separator } from "@/components/ui/separator"
+
+const components = [
+  "Accordion",
+  "Alert Banner",
+  "App Store Badge",
+  "Aspect Ratio",
+  "Avatar",
+  "Badge",
+  "Breadcrumb",
+  "Button",
+  "Button Group",
+  "Checkbox",
+  "Checkbox Group",
+  "Chip",
+  "Close Button",
+  "Command",
+  "Country Flag",
+  "Credit Card Input",
+  "Date Input",
+  "Dialog",
+  "Dropdown Menu",
+  "Field",
+  "Info Tooltip",
+  "Inline Alert",
+  "Input",
+  "Input Group",
+  "Input OTP",
+  "Input Stepper",
+  "Label",
+  "Modal",
+  "Pagination",
+  "Password Strength",
+  "Phone Input",
+  "Popover",
+  "Progress",
+  "Radio",
+  "Radio Group",
+  "Scroll Area",
+  "Segmented Control",
+  "Select",
+  "Separator",
+  "Social Login Button",
+  "Spinner",
+  "Status Badge",
+  "Switch",
+  "Switch Group",
+  "Tab Menu",
+  "Text Link",
+  "Textarea",
+  "Toast",
+  "Tooltip",
+]
+
+export default function ScrollAreaDemo() {
+  return (
+    <ScrollArea className="bg-weakest text-strong h-72 w-48 rounded-md">
+      <div className="p-4">
+        <h4 className="mb-4 text-sm leading-none font-medium">Components</h4>
+        {components.map((component) => (
+          <React.Fragment key={component}>
+            <div className="text-sm">{component}</div>
+            <Separator className="my-2" />
+          </React.Fragment>
+        ))}
+      </div>
+    </ScrollArea>
+  )
+}
+```
+
+From `scroll-area-fade`:
+
+```tsx
+import * as React from "react"
+
+import { ScrollArea } from "@/components/ui/scroll-area"
+import { Separator } from "@/components/ui/separator"
+
+const components = [
+  "Accordion",
+  "Alert Banner",
+  "App Store Badge",
+  "Aspect Ratio",
+  "Avatar",
+  "Badge",
+  "Breadcrumb",
+  "Button",
+  "Button Group",
+  "Checkbox",
+  "Checkbox Group",
+  "Chip",
+  "Close Button",
+  "Command",
+  "Country Flag",
+  "Credit Card Input",
+  "Date Input",
+  "Dialog",
+  "Dropdown Menu",
+  "Field",
+  "Info Tooltip",
+  "Inline Alert",
+  "Input",
+  "Input Group",
+  "Input OTP",
+  "Input Stepper",
+  "Label",
+  "Modal",
+  "Pagination",
+  "Password Strength",
+  "Phone Input",
+  "Popover",
+  "Progress",
+  "Radio",
+  "Radio Group",
+  "Scroll Area",
+  "Segmented Control",
+  "Select",
+  "Separator",
+  "Social Login Button",
+  "Spinner",
+  "Status Badge",
+  "Switch",
+  "Switch Group",
+  "Tab Menu",
+  "Text Link",
+  "Textarea",
+  "Toast",
+  "Tooltip",
+]
+
+export default function ScrollAreaFade() {
+  return (
+    <ScrollArea fade className="bg-weakest text-strong h-72 w-48 rounded-md">
+      <div className="p-4">
+        <h4 className="mb-4 text-sm leading-none font-medium">Components</h4>
+        {components.map((component) => (
+          <React.Fragment key={component}>
+            <div className="text-sm">{component}</div>
+            <Separator className="my-2" />
+          </React.Fragment>
+        ))}
+      </div>
+    </ScrollArea>
+  )
+}
+```
+
+More: `npx @create-ui/cli view scroll-area` or MCP `get_item_examples_from_registries` with "scroll-area-demo" / "scroll-area-example".
+
+## When to use
+Styled overlay-scrollbar viewport for content that overflows a fixed-size surface: lists in panels, image rows, wide grids. Do not use it for full-page scrolling (let the browser handle that). DropdownMenu and Select content panels already scroll on their own; do not wrap them in ScrollArea.
+
+## Gotchas
+- Unlike shadcn, you never add a `<ScrollBar>` child. `ScrollArea` renders viewport, scrollbar(s), and corner itself from `orientation`; horizontal scrolling is `orientation="horizontal"`, not an extra child. A `<ScrollBar>` child would land inside the scrolled viewport content; the export exists only for fully custom setups.
+- Width/height constraints go on the root `className` (e.g. `h-72 w-48`); the internal viewport is `size-full` and inherits the root's radius. Without a fixed dimension on the enabled axis nothing scrolls.
+- Horizontal content must actually overflow: a non-wrapping flex row with `shrink-0` children inside a width-constrained root, e.g.
+
+```tsx
+<ScrollArea orientation="horizontal" className="w-full max-w-96 rounded-md p-4">
+  <div className="flex gap-4">{items /* each child shrink-0 */}</div>
+</ScrollArea>
+```
+
+- `fade` overlays mark only the scroll END of each enabled axis (bottom for vertical, right for horizontal); there is no top/left start fade. They are `aria-hidden` and `pointer-events-none`, and dynamic content is handled automatically (scroll listener + ResizeObserver + MutationObserver).
+- The fade gradient ends in the `static-white` token (white in light mode, black in dark), not the container's own background. On a tinted container (e.g. `bg-weakest`) the fade edge will not exactly match the surface color.
+- Scrollbars are `forceMount`ed and toggle via opacity (`data-[state=hidden/visible]`); show/hide timing comes from the Radix root's `type` and `scrollHideDelay` props, which pass through `ScrollArea` untouched.
+- The `cn-scroll-area*` classes are intentional style-less hooks for consumer CSS targeting; do not strip them as dead code.