@adres/mgda-ui 0.0.0-stage → 0.0.1

package/src/components/card.tsx

@@ -0,0 +1,392 @@
+"use client"
+
+import * as React from "react"
+import { motion, type HTMLMotionProps } from "motion/react"
+import { cn } from "../lib/cn"
+import { useReducedMotion } from "../hooks/use-reduced-motion"
+import { hover, transitions } from "../lib/motion"
+
+export type CardVariant   = "default" | "surface" | "ghost"
+export type CardPadding   = "none" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl" | "4xl"
+export type CardGap       = "sm" | "md" | "lg" | "xl"
+export type CardElevation = "none" | "xs" | "sm" | "level0" | "level1" | "level2" | "level3"
+
+export interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Visual treatment of the card surface. */
+  variant?: CardVariant
+  /** 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) */
+  padding?: CardPadding
+  /** When set, makes the card a vertical flex column with the given gap between children.
+   *  sm=12px  md=16px  lg=20px  xl=24px */
+  gap?: CardGap
+  /** 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. */
+  elevation?: CardElevation
+  /** When true, the card zooms subtly on hover. Disabled by reduced-motion preference. */
+  interactive?: boolean
+  /** Hover animation style when `interactive` is true.
+   *  "scale" (default) - a light zoom (1.03×) that raises the shadow one level ·
+   *  "lift" - translates up 4px */
+  hoverEffect?: "lift" | "scale"
+  /** When true, removes the border and shadow from the card. */
+  borderless?: boolean
+  /** 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. */
+  sectioned?: boolean
+}
+
+// When `sectioned`, the card goes padding-less and hands the padding scale to its
+// sub-components via context so the muted header band can run full-bleed to the
+// rounded edges while each section keeps consistent interior padding.
+// `headerSize` mirrors the sectioned header's `size` (when set) so the content
+// and footer can match the header's padding scale.
+interface CardSectionContextValue { padding: CardPadding; headerSize?: CardHeaderSize }
+const CardSectionContext = React.createContext<CardSectionContextValue | null>(null)
+
+const CARD_BASE = "ax:rounded-md ax:text-card-foreground ax:overflow-hidden"
+
+const CARD_VARIANT: Record<CardVariant, string> = {
+  default: "ax:border ax:bg-card ax:shadow-sm",
+  surface: "ax:border ax:border-border ax:bg-background",
+  ghost:   "ax:bg-transparent",
+}
+
+// Just the border treatment of each variant, with no background or shadow. Used
+// when `elevation` is set: the level supplies the surface (bg + shadow), so the
+// variant's own bg/shadow are dropped rather than fighting the level's utilities.
+const CARD_VARIANT_BORDER: Record<CardVariant, string> = {
+  default: "ax:border",
+  surface: "ax:border ax:border-border",
+  ghost:   "",
+}
+
+const CARD_PADDING: Record<CardPadding, string> = {
+  none:  "",
+  sm:    "ax:p-sm",                                               // 12px - fixed
+  md:    "ax:p-md",                                               // 16px - fixed
+  lg:    "ax:p-md ax:md:p-lg",                                       // 16 → 20px
+  xl:    "ax:p-md ax:sm:p-lg ax:xl:p-xl",                               // 16 → 20 → 24px
+  "2xl": "ax:p-sm ax:sm:p-md ax:md:p-lg ax:lg:p-xl ax:xl:p-2xl",             // 12 → 16 → 20 → 24 → 32px
+  "3xl": "ax:p-md ax:sm:p-lg ax:md:p-xl ax:lg:p-2xl ax:xl:p-3xl",            // 16 → 20 → 24 → 32 → 40px
+  "4xl": "ax:p-lg ax:sm:p-xl ax:md:p-2xl ax:lg:p-3xl ax:xl:p-4xl",           // 20 → 24 → 32 → 40 → 48px
+}
+
+const CARD_GAP: Record<CardGap, string> = {
+  sm: "ax:flex ax:flex-col ax:gap-sm",
+  md: "ax:flex ax:flex-col ax:gap-md",
+  lg: "ax:flex ax:flex-col ax:gap-lg",
+  xl: "ax:flex ax:flex-col ax:gap-xl",
+}
+
+// Surface elevation - fill + shadow per level, read from the brand-themeable
+// --elevation-* tokens. Applied AFTER the variant classes in cn() so tailwind-merge
+// lets the level win on background-color and box-shadow while the variant's border
+// (if any) survives.
+const CARD_ELEVATION: Record<CardElevation, string> = {
+  none:   "ax:bg-card ax:shadow-none",
+  xs:     "ax:bg-card ax:shadow-xs",
+  sm:     "ax:bg-card ax:shadow-sm",
+  level0: "ax:bg-[var(--elevation-0-surface)] ax:shadow-[var(--elevation-0-shadow)]",
+  level1: "ax:bg-[var(--elevation-1-surface)] ax:shadow-[var(--elevation-1-shadow)]",
+  level2: "ax:bg-[var(--elevation-2-surface)] ax:shadow-[var(--elevation-2-shadow)]",
+  level3: "ax:bg-[var(--elevation-3-surface)] ax:shadow-[var(--elevation-3-shadow)]",
+}
+
+// Exposes the active padding value to Inset children so they can break out via negative margin.
+const INSET_STYLE: Record<CardPadding, React.CSSProperties> = {
+  none:  {},
+  sm:    { "--inset-padding": "var(--space-sm)" }  as React.CSSProperties,
+  md:    { "--inset-padding": "var(--space-md)" }  as React.CSSProperties,
+  lg:    { "--inset-padding": "var(--space-lg)" }  as React.CSSProperties,
+  xl:    { "--inset-padding": "var(--space-xl)" }  as React.CSSProperties,
+  "2xl": { "--inset-padding": "var(--space-2xl)" } as React.CSSProperties,
+  "3xl": { "--inset-padding": "var(--space-3xl)" } as React.CSSProperties,
+  "4xl": { "--inset-padding": "var(--space-4xl)" } as React.CSSProperties,
+}
+
+/** Utility for applying Card surface classes to non-div elements (e.g. motion.figure, a). */
+export function cardCn(variant: CardVariant = "default", padding: CardPadding = "xl", extra?: string) {
+  return cn(CARD_BASE, CARD_VARIANT[variant], CARD_PADDING[padding], extra)
+}
+
+export const Card = React.forwardRef<HTMLDivElement, CardProps>(
+  ({ className, variant = "default", padding = "xl", gap, elevation, interactive, hoverEffect = "scale", borderless, sectioned, style, children, ...props }, ref) => {
+    const reduce = useReducedMotion()
+
+    // For non-interactive default cards, defer border-color and shadow to brand CSS variables
+    // so themes can control card chrome without touching Tailwind utilities.
+    // Interactive cards are excluded because hover:shadow-md (class) can't beat inline styles.
+    const cardBrandStyle: React.CSSProperties =
+      variant === "default" && !borderless && !elevation && !interactive
+        ? { borderColor: "var(--card-border-color)", boxShadow: "var(--card-shadow)" }
+        : {}
+
+    const mergedStyle = { ...INSET_STYLE[padding], ...cardBrandStyle, ...style }
+    const borderlessClass = borderless
+      ? elevation ? "ax:border-0" : "ax:border-0 ax:shadow-none"
+      : undefined
+    // Sectioned cards go padding-less: the header/content sections own their padding.
+    const paddingClass    = sectioned ? "" : CARD_PADDING[padding]
+    const gapClass        = sectioned ? undefined : (gap ? CARD_GAP[gap] : undefined)
+    // Mirror the sectioned CardBanner's `size` so content/footer match its padding.
+    let headerSize: CardHeaderSize | undefined
+    if (sectioned) {
+      React.Children.forEach(children, (child) => {
+        if (React.isValidElement(child) && (child.type as { displayName?: string })?.displayName === "CardBanner") {
+          headerSize = (child.props as CardBannerProps).size ?? "lg"
+        }
+      })
+    }
+    const renderChildren  = sectioned
+      ? <CardSectionContext.Provider value={{ padding, headerSize }}>{children}</CardSectionContext.Provider>
+      : children
+    // When elevation is set it owns the surface (bg + shadow); keep only the
+    // variant's border so the level's utilities aren't fighting the variant's own
+    // background/shadow. Unset → the variant's full default chrome.
+    const surfaceClass    = cn(
+      elevation
+        ? cn(CARD_VARIANT_BORDER[variant], CARD_ELEVATION[elevation])
+        : CARD_VARIANT[variant],
+      // Sectioned: paint the header surface on the card root so the card's
+      // rounded top corners read as the header, AND so the content container's
+      // rounded top corners reveal the header colour behind them.
+      sectioned && "ax:bg-neutral-weakest",
+    )
+
+    if (interactive && !reduce) {
+      // "scale" - card chrome grows, content stays at natural size via counter-scale.
+      // The outer div scales up (overlapping siblings); the inner div scales back down
+      // so text and icons remain visually unchanged.
+      if (hoverEffect === "scale") {
+        const SCALE = 1.03
+        return (
+          <motion.div
+            ref={ref as React.Ref<HTMLDivElement>}
+            style={mergedStyle}
+            className={cn(
+              CARD_BASE, surfaceClass, borderlessClass,
+              "ax:hover:shadow-md ax:transition-shadow ax:transition-snappy ax:cursor-pointer ax:relative ax:hover:z-10",
+              className
+            )}
+            whileHover={{ scale: SCALE }}
+            transition={transitions.spring}
+            {...(props as HTMLMotionProps<"div">)}
+          >
+            <motion.div
+              className={cn(paddingClass, gapClass, "ax:h-full ax:flex ax:flex-col")}
+              whileHover={{ scale: 1 / SCALE }}
+              transition={transitions.spring}
+            >
+              {renderChildren}
+            </motion.div>
+          </motion.div>
+        )
+      }
+
+      return (
+        <motion.div
+          ref={ref as React.Ref<HTMLDivElement>}
+          style={mergedStyle}
+          className={cn(
+            CARD_BASE, surfaceClass, paddingClass, gapClass, borderlessClass,
+            sectioned && "ax:flex ax:flex-col",
+            "ax:hover:shadow-md ax:transition-shadow ax:transition-snappy ax:cursor-pointer",
+            className
+          )}
+          whileHover={hover.lift}
+          transition={transitions.spring}
+          {...(props as HTMLMotionProps<"div">)}
+        >
+          {renderChildren}
+        </motion.div>
+      )
+    }
+
+    return (
+      <div
+        ref={ref}
+        style={mergedStyle}
+        className={cn(
+          CARD_BASE, surfaceClass, paddingClass, gapClass, borderlessClass,
+          sectioned && "ax:flex ax:flex-col",
+          interactive && "ax:cursor-pointer",
+          className
+        )}
+        {...props}
+      >
+        {renderChildren}
+      </div>
+    )
+  }
+)
+Card.displayName = "Card"
+
+// ── CardHeader sizing ──────────────────────────────────────────────────────
+export type CardHeaderSize = "xs" | "sm" | "md" | "lg" | "xl"
+
+// Title type token per size - the header's `size` drives its CardTitle.
+const HEADER_TITLE: Record<CardHeaderSize, string> = {
+  xs: "ax:t-h6", sm: "ax:t-h5", md: "ax:t-h4", lg: "ax:t-h3", xl: "ax:t-h2",
+}
+// Description type token per size - drives a nested CardDescription.
+const HEADER_DESC: Record<CardHeaderSize, string> = {
+  xs: "ax:t-body-xs", sm: "ax:t-body-sm", md: "ax:t-body-sm", lg: "ax:t-body-md", xl: "ax:t-body-md",
+}
+// Padding when the header owns its box (a `sectioned` band): horizontal on the
+// p-* scale, vertical on the tighter py-* scale.
+const HEADER_PADDING: Record<CardHeaderSize, string> = {
+  xs: "ax:px-sm ax:py-xs", sm: "ax:px-md ax:py-sm", md: "ax:px-lg ax:py-md", lg: "ax:px-xl ax:py-lg", xl: "ax:px-2xl ax:py-xl",
+}
+// Bottom-only padding (non-sectioned: root handles top/sides, header adds the
+// gap before the content).
+const HEADER_PADDING_BOTTOM: Record<CardHeaderSize, string> = {
+  xs: "ax:pb-sm", sm: "ax:pb-md", md: "ax:pb-lg", lg: "ax:pb-xl", xl: "ax:pb-2xl",
+}
+// Content/footer padding when the sectioned header carries a `size`: all-sides
+// on the header's horizontal scale so the sections line up under the header.
+const SECTION_PADDING: Record<CardHeaderSize, string> = {
+  xs: "ax:p-sm", sm: "ax:p-md", md: "ax:p-lg", lg: "ax:p-xl", xl: "ax:p-2xl",
+}
+
+// Lets CardHeader's `size` drive the type tokens of a nested CardTitle /
+// CardDescription. Defaults match the legacy (unsized) header.
+interface CardHeaderType { title: string; description: string }
+const CardHeaderTypeContext = React.createContext<CardHeaderType>({ title: "ax:t-h3", description: "ax:t-body-sm" })
+
+export interface CardHeaderProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** 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). */
+  size?: CardHeaderSize
+}
+
+// CardHeader - the default header: title + description stacked with a small gap,
+// bottom padding before the content (root padding handles top/sides). For the
+// darker full-bleed band of a `sectioned` card, use CardBanner instead.
+export const CardHeader = React.forwardRef<HTMLDivElement, CardHeaderProps>(
+  ({ className, size, ...props }, ref) => {
+    // Explicit `size` drives the title/description type tokens; unset keeps the
+    // legacy defaults (t-h3 / t-body-sm).
+    const type = React.useMemo<CardHeaderType>(
+      () => size
+        ? { title: HEADER_TITLE[size], description: HEADER_DESC[size] }
+        : { title: "ax:t-h3", description: "ax:t-body-sm" },
+      [size],
+    )
+    return (
+      <CardHeaderTypeContext.Provider value={type}>
+        <div
+          ref={ref}
+          className={cn("ax:flex ax:flex-col ax:gap-sm", size ? HEADER_PADDING_BOTTOM[size] : "ax:pb-xl", className)}
+          {...props}
+        />
+      </CardHeaderTypeContext.Provider>
+    )
+  }
+)
+CardHeader.displayName = "CardHeader"
+
+export interface CardBannerProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** 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. */
+  size?: CardHeaderSize
+}
+
+// CardBanner - the darker, full-bleed header band for a `sectioned` card. Its top
+// corners are rounded by the card's radius; the CardContent below tucks under it
+// with rounded top corners that reveal this band's colour.
+export const CardBanner = React.forwardRef<HTMLDivElement, CardBannerProps>(
+  ({ className, size = "lg", ...props }, ref) => {
+    const type = React.useMemo<CardHeaderType>(
+      () => ({ title: HEADER_TITLE[size], description: HEADER_DESC[size] }),
+      [size],
+    )
+    return (
+      <CardHeaderTypeContext.Provider value={type}>
+        <div
+          ref={ref}
+          className={cn(
+            "ax:flex ax:flex-col ax:bg-neutral-weakest/50 ax:dark:bg-neutral-weaker/50",
+            HEADER_PADDING[size],
+            className,
+          )}
+          {...props}
+        />
+      </CardHeaderTypeContext.Provider>
+    )
+  }
+)
+CardBanner.displayName = "CardBanner"
+
+export const CardTitle = React.forwardRef<HTMLHeadingElement, React.HTMLAttributes<HTMLHeadingElement>>(
+  ({ className, ...props }, ref) => {
+    const { title } = React.useContext(CardHeaderTypeContext)
+    return (
+      <h3
+        ref={ref}
+        className={cn(title, "ax:text-foreground", className)}
+        {...props}
+      />
+    )
+  }
+)
+CardTitle.displayName = "CardTitle"
+
+export const CardDescription = React.forwardRef<HTMLParagraphElement, React.HTMLAttributes<HTMLParagraphElement>>(
+  ({ className, ...props }, ref) => {
+    const { description } = React.useContext(CardHeaderTypeContext)
+    return (
+      <p ref={ref} className={cn(description, "ax:text-muted-foreground", className)} {...props} />
+    )
+  }
+)
+CardDescription.displayName = "CardDescription"
+
+// CardContent - root padding handles all spacing; in a `sectioned` card it
+// supplies its own padding instead.
+export const CardContent = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  ({ className, ...props }, ref) => {
+    const section = React.useContext(CardSectionContext)
+    return (
+      <div
+        ref={ref}
+        className={cn("ax:t-body-sm ax:text-foreground", section && cn("ax:bg-card ax:rounded-t-lg ax:flex-1", section.headerSize ? SECTION_PADDING[section.headerSize] : CARD_PADDING[section.padding]), className)}
+        {...props}
+      />
+    )
+  }
+)
+CardContent.displayName = "CardContent"
+
+// CardFooter - top padding separates it from CardContent above. In a `sectioned`
+// card it becomes a divided band with its own padding.
+export const CardFooter = React.forwardRef<HTMLDivElement, React.HTMLAttributes<HTMLDivElement>>(
+  ({ className, ...props }, ref) => {
+    const section = React.useContext(CardSectionContext)
+    return (
+      <div
+        ref={ref}
+        className={cn(
+          "ax:flex ax:items-center",
+          section ? cn("ax:bg-card ax:border-t ax:border-border", section.headerSize ? SECTION_PADDING[section.headerSize] : CARD_PADDING[section.padding]) : "ax:pt-xl",
+          className,
+        )}
+        {...props}
+      />
+    )
+  }
+)
+CardFooter.displayName = "CardFooter"

package/src/components/cards-nav.stories.tsx

@@ -0,0 +1,35 @@
+import React from "react"
+import type { Meta, StoryObj } from "@storybook/react"
+import { CardsNav } from "./cards-nav"
+
+const items = [
+  { title: "Documentation", description: "Guides and API references.", href: "#docs" },
+  { title: "Playground", description: "Try components live.", href: "#playground" },
+  { title: "Brands", description: "Explore brand themes.", href: "#brands" },
+]
+
+const meta: Meta<typeof CardsNav> = {
+  title: "Components/CardsNav",
+  component: CardsNav,
+  tags: ["autodocs"],
+  args: { items },
+}
+
+export default meta
+type Story = StoryObj<typeof CardsNav>
+
+export const Default: Story = {
+  render: (args) => (
+    <div className="ax:grid ax:gap-md ax:sm:grid-cols-3 ax:max-w-3xl">
+      <CardsNav {...args} />
+    </div>
+  ),
+}
+
+export const WithOverline: Story = {
+  render: (args) => (
+    <div className="ax:grid ax:gap-md ax:sm:grid-cols-3 ax:max-w-3xl">
+      <CardsNav {...args} overline />
+    </div>
+  ),
+}

package/src/components/cards-nav.tsx

@@ -0,0 +1,115 @@
+import * as React from "react"
+import { ArrowUpRight } from "lucide-react"
+import { cn } from "../lib/cn"
+
+export interface CardsNavItem {
+  /** Card heading. */
+  title: React.ReactNode
+  /** Optional supporting line under the title. */
+  description?: React.ReactNode
+  /** Destination passed to the link element (`as`). */
+  href: string
+  /** Custom overline content; falls back to a two-digit ordinal (01, 02, …)
+   *  when the `overline` prop is on and this is omitted. */
+  overline?: React.ReactNode
+  /** Optional accent colour for the overline, as any CSS colour string (e.g.
+   *  `"hsl(198 100% 44%)"`). Tints just the overline; leaves the rest neutral. */
+  accent?: string
+}
+
+export type CardsNavSize = "sm" | "md" | "lg"
+
+/** Card padding per size. */
+const SIZE: Record<CardsNavSize, string> = {
+  sm: "ax:p-lg",
+  md: "ax:p-xl",
+  lg: "ax:p-2xl",
+}
+
+/** Title + description type scale per text size. */
+const TEXT: Record<CardsNavSize, { title: string; desc: string }> = {
+  sm: { title: "ax:t-h5", desc: "ax:t-body-sm" },
+  md: { title: "ax:t-h4", desc: "ax:t-body-sm" },
+  lg: { title: "ax:t-h3", desc: "ax:t-body-md" },
+}
+
+export interface CardsNavProps {
+  items: CardsNavItem[]
+  /** Element rendered for each card. Default `"a"`; pass a router `Link` (e.g.
+   *  Next.js) for client-side navigation. */
+  as?: React.ElementType
+  /** Card padding. Default "md". */
+  size?: CardsNavSize
+  /** Title + description type scale. Default "md". */
+  textSize?: CardsNavSize
+  /** Show the top overline row - a per-item `overline` or, failing that, a
+   *  two-digit ordinal. Default false. */
+  overline?: boolean
+  /** Open links in a new tab (adds `target="_blank"` + safe `rel`). Use for
+   *  external destinations. Default false. */
+  newTab?: boolean
+  /** Extra classes applied to each card. */
+  className?: string
+}
+
+/**
+ * CardsNav - a set of navigational cards, each a title, optional supporting
+ * line and a trailing up-right arrow that leans on hover. Renders the cards as
+ * a fragment (no wrapper): place them in your own grid or flex container so the
+ * column count and gap stay with the layout.
+ *
+ * Framework-agnostic: cards render as `<a>` by default; pass `as={Link}` to use
+ * a router link. Turn on `overline` for a numbered / eyebrow'd set.
+ */
+export function CardsNav({ items, as, size = "md", textSize = "md", overline = false, newTab = false, className }: CardsNavProps) {
+  const Comp = as ?? "a"
+  const text = TEXT[textSize]
+  const newTabProps = newTab ? { target: "_blank", rel: "noopener noreferrer" } : {}
+  return (
+    <>
+      {items.map((item, i) => {
+        // The arrow shares a row with whichever element leads the card (the
+        // overline when it's shown, otherwise the title) rather than floating
+        // alone in a top row.
+        const arrow = (
+          <ArrowUpRight className="ax:size-4 ax:shrink-0 ax:text-neutral-weaker ax:transition-[color,transform] ax:group-hover:-translate-y-0.5 ax:group-hover:translate-x-0.5 ax:group-hover:text-primary ax:rtl:-scale-x-100" />
+        )
+        return (
+          <Comp
+            key={i}
+            href={item.href}
+            {...newTabProps}
+            className={cn(
+              "ax:group ax:flex ax:flex-col ax:rounded-sm ax:border ax:border-border ax:bg-card ax:transition-colors ax:dark:bg-card/50 ax:hover:border-primary ax:hover:bg-card",
+              SIZE[size],
+              className,
+            )}
+          >
+            {overline ? (
+              <>
+                <div className="ax:flex ax:items-center ax:justify-between ax:gap-md">
+                  <span
+                    className="ax:t-eyebrow-small ax:tabular-nums ax:text-muted-foreground"
+                    style={item.accent ? { color: item.accent } : undefined}
+                  >
+                    {item.overline ?? String(i + 1).padStart(2, "0")}
+                  </span>
+                  {arrow}
+                </div>
+                <span className={cn("ax:mt-xs ax:text-foreground ax:transition-colors ax:group-hover:text-primary-foreground", text.title)}>{item.title}</span>
+              </>
+            ) : (
+              <div className="ax:flex ax:items-start ax:justify-between ax:gap-md">
+                <span className={cn("ax:text-foreground ax:transition-colors ax:group-hover:text-primary-foreground", text.title)}>{item.title}</span>
+                {arrow}
+              </div>
+            )}
+            {item.description != null && (
+              <span className={cn("ax:mt-2xs ax:max-w-prose ax:text-muted-foreground", text.desc)}>{item.description}</span>
+            )}
+          </Comp>
+        )
+      })}
+    </>
+  )
+}

package/src/components/chain-of-thought.stories.tsx

@@ -0,0 +1,67 @@
+import React from "react"
+import type { Meta, StoryObj } from "@storybook/react"
+import { Calculator, Lightbulb, Search } from "lucide-react"
+import {
+  ChainOfThought, ChainOfThoughtContent, ChainOfThoughtItem, ChainOfThoughtStep, ChainOfThoughtTrigger,
+} from "./chain-of-thought"
+
+const meta: Meta<typeof ChainOfThought> = {
+  title: "Components/ChainOfThought",
+  component: ChainOfThought,
+  tags: ["autodocs"],
+  decorators: [(Story) => <div style={{ maxWidth: 560 }}><Story /></div>],
+}
+
+export default meta
+type Story = StoryObj<typeof ChainOfThought>
+
+export const Basic: Story = {
+  render: () => (
+    <ChainOfThought>
+      <ChainOfThoughtStep defaultOpen>
+        <ChainOfThoughtTrigger>Understanding the request</ChainOfThoughtTrigger>
+        <ChainOfThoughtContent>
+          <ChainOfThoughtItem>Townhouse on Yas Island, under AED 5M, with a private garden.</ChainOfThoughtItem>
+        </ChainOfThoughtContent>
+      </ChainOfThoughtStep>
+      <ChainOfThoughtStep>
+        <ChainOfThoughtTrigger>Searching listings</ChainOfThoughtTrigger>
+        <ChainOfThoughtContent>
+          <ChainOfThoughtItem>Found 42 townhouses in Yas Acres and Noya.</ChainOfThoughtItem>
+          <ChainOfThoughtItem>11 have a private garden.</ChainOfThoughtItem>
+        </ChainOfThoughtContent>
+      </ChainOfThoughtStep>
+      <ChainOfThoughtStep>
+        <ChainOfThoughtTrigger>Comparing prices</ChainOfThoughtTrigger>
+        <ChainOfThoughtContent>
+          <ChainOfThoughtItem>Lowest asking price is AED 4.2M in Yas Acres.</ChainOfThoughtItem>
+        </ChainOfThoughtContent>
+      </ChainOfThoughtStep>
+    </ChainOfThought>
+  ),
+}
+
+export const WithIcons: Story = {
+  render: () => (
+    <ChainOfThought>
+      <ChainOfThoughtStep>
+        <ChainOfThoughtTrigger icon={<Search />}>Searched 128 listings on Yas Island</ChainOfThoughtTrigger>
+        <ChainOfThoughtContent>
+          <ChainOfThoughtItem>42 townhouses under AED 5M, 11 with a private garden.</ChainOfThoughtItem>
+        </ChainOfThoughtContent>
+      </ChainOfThoughtStep>
+      <ChainOfThoughtStep>
+        <ChainOfThoughtTrigger icon={<Calculator />}>Compared registered sales</ChainOfThoughtTrigger>
+        <ChainOfThoughtContent>
+          <ChainOfThoughtItem>Median sale price in Yas Acres is AED 4.6M over the last 12 months.</ChainOfThoughtItem>
+        </ChainOfThoughtContent>
+      </ChainOfThoughtStep>
+      <ChainOfThoughtStep>
+        <ChainOfThoughtTrigger icon={<Lightbulb />}>Drew a conclusion</ChainOfThoughtTrigger>
+        <ChainOfThoughtContent>
+          <ChainOfThoughtItem>The AED 4.2M listing is priced below recent sales.</ChainOfThoughtItem>
+        </ChainOfThoughtContent>
+      </ChainOfThoughtStep>
+    </ChainOfThought>
+  ),
+}

package/src/components/chain-of-thought.test.tsx

@@ -0,0 +1,50 @@
+import { describe, expect, it } from "vitest"
+import * as React from "react"
+import { renderToStaticMarkup } from "react-dom/server"
+import {
+  ChainOfThought, ChainOfThoughtContent, ChainOfThoughtItem, ChainOfThoughtStep, ChainOfThoughtTrigger,
+} from "./chain-of-thought"
+
+function step(props: React.ComponentProps<typeof ChainOfThoughtStep>, icon?: React.ReactNode) {
+  return (
+    <ChainOfThoughtStep {...props}>
+      <ChainOfThoughtTrigger icon={icon}>Searching listings</ChainOfThoughtTrigger>
+      <ChainOfThoughtContent>
+        <ChainOfThoughtItem>Found 42 townhouses</ChainOfThoughtItem>
+      </ChainOfThoughtContent>
+    </ChainOfThoughtStep>
+  )
+}
+
+describe("ChainOfThought", () => {
+  it("keeps a step closed by default", () => {
+    const html = renderToStaticMarkup(<ChainOfThought>{step({})}</ChainOfThought>)
+    expect(html).toContain('aria-expanded="false"')
+    expect(html).not.toContain("Found 42 townhouses")
+  })
+
+  it("opens with defaultOpen and points the trigger at its content", () => {
+    const html = renderToStaticMarkup(<ChainOfThought>{step({ defaultOpen: true })}</ChainOfThought>)
+    expect(html).toContain('aria-expanded="true"')
+    expect(html).toContain("Found 42 townhouses")
+    const controls = html.match(/aria-controls="([^"]+)"/)?.[1]
+    expect(controls).toBeTruthy()
+    expect(html).toContain(`id="${controls}"`)
+  })
+
+  it("lets a controlled open win over defaultOpen", () => {
+    const html = renderToStaticMarkup(<ChainOfThought>{step({ open: false, defaultOpen: true })}</ChainOfThought>)
+    expect(html).toContain('aria-expanded="false"')
+  })
+
+  it("shows a trailing chevron only when there is no icon to swap", () => {
+    const chevrons = (html: string) => html.match(/lucide-chevron-down/g)?.length ?? 0
+    expect(chevrons(renderToStaticMarkup(step({})))).toBe(1)
+    expect(chevrons(renderToStaticMarkup(step({}, <svg />)))).toBe(1)
+    expect(renderToStaticMarkup(step({}, <svg />))).toContain("ax:absolute")
+  })
+
+  it("throws when a trigger is used outside a step", () => {
+    expect(() => renderToStaticMarkup(<ChainOfThoughtTrigger>Orphan</ChainOfThoughtTrigger>)).toThrow(/ChainOfThoughtStep/)
+  })
+})