@adres/mgda-ui 0.0.0-stage → 0.0.1

package/knowledge/card.md

@@ -0,0 +1,321 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: card
+  sourceFile: packages/design-system/src/components/card.tsx
+  client: true
+  category: web-app-core-primitives
+  categoryFromBarrel: web-app-core-primitives
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Card
+      kind: component
+      typeText: "ForwardRefExoticComponent<CardProps & RefAttributes<HTMLDivElement>>"
+    - name: CardBanner
+      kind: component
+      typeText: "ForwardRefExoticComponent<CardBannerProps & RefAttributes<HTMLDivElement>>"
+    - name: CardBannerProps
+      kind: type
+    - name: cardCn
+      kind: function
+      typeText: "(variant?: CardVariant, padding?: CardPadding, extra?: string | undefined) => string"
+    - name: CardContent
+      kind: component
+      typeText: "ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement>>"
+    - name: CardDescription
+      kind: component
+      typeText: "ForwardRefExoticComponent<HTMLAttributes<HTMLParagraphElement> & RefAttributes<HTMLParagraphElement>>"
+    - name: CardElevation
+      kind: type
+    - name: CardFooter
+      kind: component
+      typeText: "ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & RefAttributes<HTMLDivElement>>"
+    - name: CardGap
+      kind: type
+    - name: CardHeader
+      kind: component
+      typeText: "ForwardRefExoticComponent<CardHeaderProps & RefAttributes<HTMLDivElement>>"
+    - name: CardHeaderProps
+      kind: type
+    - name: CardHeaderSize
+      kind: type
+    - name: CardPadding
+      kind: type
+    - name: CardProps
+      kind: type
+    - name: CardTitle
+      kind: component
+      typeText: "ForwardRefExoticComponent<HTMLAttributes<HTMLHeadingElement> & RefAttributes<HTMLHeadingElement>>"
+    - name: CardVariant
+      kind: type
+  primaryExport: Card
+  subcomponents:
+    - CardBanner
+    - CardContent
+    - CardDescription
+    - CardFooter
+    - CardHeader
+    - CardTitle
+  props:
+    Card:
+      - name: borderless
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "When true, removes the border and shadow from the card."
+      - name: elevation
+        type: CardElevation
+        required: false
+        declaredIn: self
+        doc: "Surface elevation - bundles a background fill with a shadow into one level, overriding the variant's own background and shadow (the variant's border, if any, is kept). Reads the brand-themeable --elevation-* tokens. level0 - transparent, flat level1 - translucent surface (50%), flat level2 - solid surface + subtle shadow level3 - solid surface + stronger shadow Left unset, the card keeps its variant's default (brand-themeable) chrome."
+      - name: gap
+        type: CardGap
+        required: false
+        declaredIn: self
+        doc: "When set, makes the card a vertical flex column with the given gap between children. sm=12px md=16px lg=20px xl=24px"
+      - name: hoverEffect
+        type: "\"lift\" | \"scale\""
+        required: false
+        declaredIn: self
+        doc: "Hover animation style when `interactive` is true. \"scale\" (default) - a light zoom (1.03×) that raises the shadow one level · \"lift\" - translates up 4px"
+      - name: interactive
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "When true, the card zooms subtly on hover. Disabled by reduced-motion preference."
+      - name: padding
+        type: CardPadding
+        required: false
+        declaredIn: self
+        doc: "Padding inside the card. All responsive variants scale from their mobile floor up to the named size at XL (1280px+), one step per breakpoint. Fixed: none · sm(12px) · md(16px) Responsive: lg(→20px) · xl(→24px) · 2xl(→32px) · 3xl(→40px) · 4xl(→48px)"
+      - name: sectioned
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Split the card into a muted header band with a content section beneath it. The card's own padding is dropped and each sub-component (CardHeader / CardContent / CardFooter) supplies its own padding instead; the header runs full-bleed with `bg-muted` + a bottom divider, its top corners rounded by the card's own radius."
+      - name: variant
+        type: CardVariant
+        required: false
+        declaredIn: self
+        doc: "Visual treatment of the card surface."
+    CardBanner:
+      - name: size
+        type: CardHeaderSize
+        required: false
+        declaredIn: self
+        doc: "Sizes the band - its padding and the nested CardTitle / CardDescription type tokens (and the matching CardContent/CardFooter padding). xs=t-h6 · sm=t-h5 · md=t-h4 · lg=t-h3 (default) · xl=t-h2."
+    CardHeader:
+      - name: size
+        type: CardHeaderSize
+        required: false
+        declaredIn: self
+        doc: "Sizes the header - its bottom padding and the nested CardTitle / CardDescription type tokens. xs=t-h6 · sm=t-h5 · md=t-h4 · lg=t-h3 (default) · xl=t-h2. Leave unset to keep the legacy defaults (t-h3 / t-body-sm)."
+  extendsProps:
+    - "React.HTMLAttributes<HTMLDivElement>"
+  variants:
+    variant:
+      kind: enum
+      options:
+        - default
+        - ghost
+        - surface
+      default: default
+      on: Card
+    padding:
+      kind: enum
+      options:
+        - none
+        - sm
+        - md
+        - lg
+        - xl
+        - "2xl"
+        - "3xl"
+        - "4xl"
+      default: xl
+      on: Card
+    gap:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+        - xl
+      default: null
+      on: Card
+    elevation:
+      kind: enum
+      options:
+        - none
+        - sm
+        - xs
+        - level0
+        - level1
+        - level2
+        - level3
+      default: null
+      on: Card
+    hoverEffect:
+      kind: enum
+      options:
+        - lift
+        - scale
+      default: scale
+      on: Card
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - xs
+        - lg
+        - xl
+      default: lg
+      on: CardBanner
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps:
+    - CARD_ELEVATION
+    - CARD_GAP
+    - CARD_PADDING
+    - CARD_VARIANT
+    - CARD_VARIANT_BORDER
+    - HEADER_DESC
+    - HEADER_PADDING
+    - HEADER_PADDING_BOTTOM
+    - HEADER_TITLE
+    - INSET_STYLE
+    - SECTION_PADDING
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+      - motion
+    hooks:
+      - use-reduced-motion
+    external:
+      - motion/react
+      - react
+  contexts:
+    - name: CardSectionContext
+      type: CardSectionContextValue
+      default: null
+    - name: CardHeaderTypeContext
+      type: CardHeaderType
+      default: null
+  stories:
+    - exportName: Default
+      id: components-card--default
+    - exportName: Sectioned
+      id: components-card--sectioned
+  storybookTitle: Components/Card
+  docsId: components-card--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "1f3bd733ecba"
+  factsHash: f2c41c7738d2
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "The general-purpose surface container: a bordered or elevated box with optional header, content, and footer sections."
+useWhen:
+  - "grouping related content into a discrete, bordered surface - a list item, a dashboard tile, a settings row"
+  - "building a structured content block with a title, body, and an optional footer action (CardHeader/CardContent/CardFooter)"
+  - "the card itself should react to hover as a clickable unit (interactive)"
+useInstead:
+  - id: dialog
+    when: "the content should interrupt the page as a focused, blocking task rather than sit inline"
+related:
+  - inset
+composesWith:
+  - button
+  - badge
+tokens:
+  - "--card"
+  - "--card-foreground"
+  - "--card-border-color"
+  - "--card-shadow"
+  - "--border"
+  - "--elevation-0-surface"
+  - "--elevation-1-surface"
+  - "--elevation-2-surface"
+  - "--elevation-3-surface"
+a11y:
+  notes:
+    - "Card renders a plain div (or motion.div when interactive) with no implicit role - if it is genuinely clickable, wrap the surface in a real button or link, or add your own role and keyboard handler. interactive only adds a hover animation, not semantics or a click handler."
+    - "interactive is automatically disabled under the OS reduced-motion preference, but the card still needs its own real click affordance regardless of that preference."
+  keyboard:
+    - "No built-in keyboard handling - interactive is purely a hover/motion effect, not a focusable control."
+  radixHandles: false
+pitfalls:
+  - "elevation overrides the variant's background and shadow entirely, keeping only its border - setting both variant=\"surface\" and elevation=\"level2\" does not blend; elevation always wins for surface and shadow."
+  - "sectioned drops the card's own padding and hands it to CardHeader/CardBanner/CardContent/CardFooter instead - adding padding via className on the Card root under sectioned does nothing, since the padding class is stripped."
+  - "gap only affects Card's own direct children and does nothing when sectioned, since sectioned switches Card to a plain flex column without the gap utility."
+  - "hoverEffect is read even when interactive is false, but has no visible effect until interactive is true - setting it alone does nothing."
+canonicalSnippet: |
+  import { Button, Card, CardContent, CardDescription, CardFooter, CardHeader, CardTitle } from "@adres/mgda-ui"
+
+  <Card className="ax:max-w-sm">
+    <CardHeader>
+      <CardTitle>Project overview</CardTitle>
+      <CardDescription>Track progress across your team.</CardDescription>
+    </CardHeader>
+    <CardContent>
+      <p>12 tasks completed this week.</p>
+    </CardContent>
+    <CardFooter>
+      <Button size="sm">View details</Button>
+    </CardFooter>
+  </Card>
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: "1f3bd733ecba"
+---
+
+## Usage
+
+`Card` is the default surface for grouping related content - `variant` picks
+the chrome (`default` bordered-with-shadow, `surface` a flatter bordered
+background, `ghost` no chrome at all), and `padding` scales the interior
+space, most sizes growing responsively up to a fixed value at the `xl`
+breakpoint.
+
+Reach for `elevation` instead of `variant` when the surface needs to read as
+sitting at a specific depth (a popover-like tile, a raised dashboard card) -
+it bundles a background and shadow into one brand-themeable level and takes
+over from the variant's own background/shadow.
+
+Set `interactive` when the whole card is a single clickable unit (e.g. it
+navigates on click) - it adds a subtle hover animation (`hoverEffect="scale"`
+by default, or `"lift"`), automatically disabled under reduced-motion. It does
+not add any semantics or a click handler by itself.
+
+Set `sectioned` to split the card into a full-bleed header band
+(`CardHeader` or `CardBanner`) and separately-padded `CardContent`/
+`CardFooter` sections - use this when the header needs a different background
+than the body, rather than the default single-padding-box layout.
+
+### Sizes and structure
+
+`CardHeader`'s and `CardBanner`'s `size` prop scales their own padding and the
+type of a nested `CardTitle`/`CardDescription` together, so pick a `size` once
+per header rather than styling the title text directly.
+
+## Anatomy
+
+`Card` is a compound component: the root plus six section parts.
+
+| Part | Role |
+| --- | --- |
+| `Card` | The surface. Owns `variant`, `padding`, `gap`, `elevation`, `interactive`, and `sectioned`. |
+| `CardHeader` | The default header: title + description stacked, with bottom padding before the content. Use inside a non-`sectioned` card, or a `sectioned` one that doesn't need a distinct band background. |
+| `CardBanner` | The full-bleed, muted header band for a `sectioned` card. Its `size` drives the matching `CardContent`/`CardFooter` padding. |
+| `CardTitle` | An `h3` by default; its type scale comes from the nearest `CardHeader`/`CardBanner`'s `size` via context. |
+| `CardDescription` | Supporting text; same context-driven type scale as `CardTitle`. |
+| `CardContent` | The body. Picks up section padding automatically when the card is `sectioned`. |
+| `CardFooter` | The action row. Divided from the content with a top border when `sectioned`. |
+
+`CardHeaderTypeContext` and `CardSectionContext` are why `CardTitle` and
+`CardContent` never need their own `size`/padding props - both read them from
+the nearest header ancestor.

package/knowledge/cards-nav.md

@@ -0,0 +1,170 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: cards-nav
+  sourceFile: packages/design-system/src/components/cards-nav.tsx
+  client: false
+  category: web-app-layout-navigation
+  categoryFromBarrel: web-app-layout-navigation
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: CardsNav
+      kind: component
+      typeText: "({ items, as, size, textSize, overline, newTab, className }: CardsNavProps) => Element"
+    - name: CardsNavItem
+      kind: type
+    - name: CardsNavProps
+      kind: type
+    - name: CardsNavSize
+      kind: type
+  primaryExport: CardsNav
+  subcomponents: []
+  props:
+    CardsNav:
+      - name: as
+        type: "ElementType<any, keyof IntrinsicElements>"
+        required: false
+        declaredIn: self
+        doc: "Element rendered for each card. Default `\"a\"`; pass a router `Link` (e.g. Next.js) for client-side navigation."
+      - name: className
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Extra classes applied to each card."
+      - name: items
+        type: "CardsNavItem[]"
+        required: true
+        declaredIn: self
+      - name: newTab
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Open links in a new tab (adds `target=\"_blank\"` + safe `rel`). Use for external destinations. Default false."
+      - name: overline
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Show the top overline row - a per-item `overline` or, failing that, a two-digit ordinal. Default false."
+      - name: size
+        type: CardsNavSize
+        required: false
+        declaredIn: self
+        doc: "Card padding. Default \"md\"."
+      - name: textSize
+        type: CardsNavSize
+        required: false
+        declaredIn: self
+        doc: "Title + description type scale. Default \"md\"."
+  extendsProps: []
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+      default: md
+      on: CardsNav
+    textSize:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+      default: md
+      on: CardsNav
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps:
+    - SIZE
+    - TEXT
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - lucide-react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-cardsnav--default
+    - exportName: WithOverline
+      id: components-cardsnav--with-overline
+  storybookTitle: Components/CardsNav
+  docsId: components-cardsnav--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "250c6ed200bc"
+  factsHash: "1dd2c9e70be1"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A set of navigational cards - title, optional description, hover arrow - for a small set of prominent destinations."
+useWhen:
+  - "a handful of top-level destinations that deserve a bigger, more prominent target than a list row (e.g. a docs landing page's sections)"
+  - "each destination benefits from a short supporting description, not just a label"
+  - "a numbered/eyebrow'd set of steps or categories (turn on overline)"
+useInstead:
+  - id: list-nav
+    when: "the destinations are numerous or dense - a compact row list reads better than a grid of cards"
+  - id: kpi-card
+    when: "the cards report a metric rather than link somewhere"
+related:
+  - list-nav
+  - sidebar
+composesWith: []
+tokens:
+  - "--border"
+  - "--card"
+  - "--primary"
+  - "--primary-foreground"
+  - "--muted-foreground"
+  - "--neutral-weaker"
+a11y:
+  notes:
+    - "CardsNav is a server component (no \"use client\") - it renders a fragment of plain anchors with no client-side state, so it drops into a server component tree with no extra opt-in."
+    - "Renders no wrapping element - place the returned cards inside your own grid or flex container so focus order follows your intended reading order, not the array order alone."
+    - "The trailing arrow icon is aria-hidden implicitly (decorative), so the accessible name of each card comes entirely from title (and description is not read as part of the link name)."
+  requiredProps:
+    - "each item needs title and href; description, overline, and accent are optional"
+  keyboard:
+    - "Renders a real <a> (or the element passed via as) per item, so it's reachable and activatable via native link semantics with no extra wiring."
+  radixHandles: false
+pitfalls:
+  - "CardsNav renders a fragment, not a grid - forgetting to wrap it in a grid/flex container with your own gap and column count leaves the cards stacked with no layout at all."
+  - "overline falls back to a zero-padded index (01, 02, ...) only when the prop is true and an item's own overline is unset - leaving overline off entirely means per-item overline/accent are silently unused."
+  - "accent only tints the overline text color - it has no effect when overline is false, since the overline row isn't rendered at all."
+rtl: "The trailing arrow has an explicit rtl:-scale-x-100 to point the correct direction; the rest of the layout uses flex with gap, which mirrors automatically."
+canonicalSnippet: |
+  import { CardsNav, type CardsNavItem } from "@adres/mgda-ui"
+
+  const sections: CardsNavItem[] = [
+    { title: "Getting started", description: "Install and configure the SDK.", href: "/docs/start" },
+    { title: "Components", description: "Browse the full component library.", href: "/docs/components" },
+    { title: "Theming", description: "Customize tokens for your brand.", href: "/docs/theming" },
+  ]
+
+  <div className="ax:grid ax:grid-cols-1 ax:gap-md ax:sm:grid-cols-3">
+    <CardsNav overline items={sections} />
+  </div>
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: "250c6ed200bc"
+---
+
+## Usage
+
+CardsNav renders a set of navigational cards from a plain `items` array -
+title, optional description, and a trailing arrow that leans toward the
+inline-end on hover. It deliberately renders no wrapper element (just a
+fragment), so the grid or flex layout - column count, gap, responsive
+breakpoints - stays entirely with the consumer.
+
+Turn on `overline` to show a numbered or per-item eyebrow line above the
+title, useful for a "01 / 02 / 03" step or category feel; per-item `accent`
+tints just that overline color. Pass `as={Link}` (or any router link
+component) instead of the default `<a>` for client-side navigation, and
+`newTab` when a destination is external.

package/knowledge/chain-of-thought.md

@@ -0,0 +1,164 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: chain-of-thought
+  sourceFile: packages/design-system/src/components/chain-of-thought.tsx
+  client: true
+  category: web-app-ai
+  categoryFromBarrel: web-app-ai
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: ChainOfThought
+      kind: component
+      typeText: "ForwardRefExoticComponent<ChainOfThoughtProps & RefAttributes<HTMLDivElement>>"
+    - name: ChainOfThoughtContent
+      kind: component
+      typeText: "ForwardRefExoticComponent<ChainOfThoughtContentProps & RefAttributes<HTMLDivElement>>"
+    - name: ChainOfThoughtContentProps
+      kind: type
+    - name: ChainOfThoughtItem
+      kind: component
+      typeText: "ForwardRefExoticComponent<ChainOfThoughtItemProps & RefAttributes<HTMLDivElement>>"
+    - name: ChainOfThoughtItemProps
+      kind: type
+    - name: ChainOfThoughtProps
+      kind: type
+    - name: ChainOfThoughtStep
+      kind: component
+      typeText: "ForwardRefExoticComponent<ChainOfThoughtStepProps & RefAttributes<HTMLDivElement>>"
+    - name: ChainOfThoughtStepProps
+      kind: type
+    - name: ChainOfThoughtTrigger
+      kind: component
+      typeText: "ForwardRefExoticComponent<ChainOfThoughtTriggerProps & RefAttributes<HTMLButtonElement>>"
+    - name: ChainOfThoughtTriggerProps
+      kind: type
+  primaryExport: ChainOfThought
+  subcomponents:
+    - ChainOfThoughtContent
+    - ChainOfThoughtItem
+    - ChainOfThoughtStep
+    - ChainOfThoughtTrigger
+  props:
+    ChainOfThoughtStep:
+      - name: defaultOpen
+        type: boolean
+        required: false
+        declaredIn: self
+      - name: onOpenChange
+        type: "((open: boolean) => void)"
+        required: false
+        declaredIn: self
+      - name: open
+        type: boolean
+        required: false
+        declaredIn: self
+    ChainOfThoughtTrigger:
+      - name: icon
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Replaces the default dot. Swaps to a chevron on hover and focus unless `swapIconOnHover` is false."
+      - name: swapIconOnHover
+        type: boolean
+        required: false
+        declaredIn: self
+  extendsProps: []
+  variants: {}
+  variantSource: none
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots:
+    - chain-of-thought
+    - chain-of-thought-content
+    - chain-of-thought-item
+    - chain-of-thought-step
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - lucide-react
+      - react
+  contexts:
+    - name: StepContext
+      type: StepContextValue
+      default: null
+  stories:
+    - exportName: Basic
+      id: components-chainofthought--basic
+    - exportName: WithIcons
+      id: components-chainofthought--with-icons
+  storybookTitle: Components/ChainOfThought
+  docsId: components-chainofthought--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: a5581b2b9569
+  factsHash: "06ef4463d8b2"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: beta
+summary: "The reasoning behind an assistant answer as a vertical chain of collapsible steps, joined by a thin rule, each expanding to its detail."
+useWhen:
+  - "an assistant answer should show how it got there, step by step, with detail behind each step"
+  - "each reasoning step has findings, sources or notes worth reading on demand"
+useInstead:
+  - id: thinking-steps
+    when: "only live progress matters: a running summary over a flat list of step labels"
+  - id: accordion
+    when: "the sections are content, not the steps of a line of reasoning"
+related:
+  - chat-message
+  - citations
+a11y:
+  notes:
+    - "Each trigger is a button with aria-expanded and aria-controls, so a step toggles with Enter or Space."
+    - "The dot, icon, chevron and connecting rules are decorative and aria-hidden; the trigger text names the step."
+    - "With an icon, the chevron appears on hover and on keyboard focus, so the expand cue is never mouse-only."
+  radixHandles: false
+pitfalls:
+  - "ChainOfThoughtTrigger and ChainOfThoughtContent must sit inside a ChainOfThoughtStep; they throw otherwise."
+  - "Content renders only while open, so do not rely on it being in the DOM for search or anchors."
+  - "Keep each trigger to one line naming the step; put findings in ChainOfThoughtItem, not the trigger."
+canonicalSnippet: |
+  import {
+    ChainOfThought, ChainOfThoughtStep, ChainOfThoughtTrigger,
+    ChainOfThoughtContent, ChainOfThoughtItem,
+  } from "@adres/mgda-ui"
+  import { Search } from "lucide-react"
+
+  <ChainOfThought>
+    <ChainOfThoughtStep>
+      <ChainOfThoughtTrigger icon={<Search />}>Searched 128 listings</ChainOfThoughtTrigger>
+      <ChainOfThoughtContent>
+        <ChainOfThoughtItem>42 townhouses under AED 5M, 11 with a garden.</ChainOfThoughtItem>
+      </ChainOfThoughtContent>
+    </ChainOfThoughtStep>
+  </ChainOfThought>
+reviewedAt: 2026-10-06
+reviewedAgainstContractHash: a5581b2b9569
+---
+
+## Usage
+
+`ChainOfThought` lays out the reasoning behind an answer as a vertical chain.
+Each `ChainOfThoughtStep` has a one-line `ChainOfThoughtTrigger` and a
+`ChainOfThoughtContent` that expands below it, holding `ChainOfThoughtItem`
+lines of detail. A thin rule joins each step to the next and runs beside open
+content; the last step ends the rule.
+
+Steps start closed. Pass `defaultOpen` to start one open, or control it with
+`open` and `onOpenChange`. The trigger shows a dot and a trailing chevron by
+default. Pass `icon` to replace the dot; the icon then swaps to a chevron on
+hover and focus, and `swapIconOnHover={false}` keeps the icon with a trailing
+chevron instead.
+
+## Anatomy
+
+- `ChainOfThought` - the vertical chain of steps.
+- `ChainOfThoughtStep` - one step; holds the open state and the rule to the next step.
+- `ChainOfThoughtTrigger` - the one-line label with a dot or icon; toggles the step.
+- `ChainOfThoughtContent` - the step's detail beside the continuing rule; rendered only while open.
+- `ChainOfThoughtItem` - one muted line of detail.