@adres/mgda-ui 0.0.0-stage → 0.0.1

package/knowledge/slideshow.md

@@ -0,0 +1,159 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: slideshow
+  sourceFile: packages/design-system/src/components/slideshow.tsx
+  client: true
+  category: web-app-media
+  categoryFromBarrel: web-app-media
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Slideshow
+      kind: component
+      typeText: "ForwardRefExoticComponent<SlideshowProps & RefAttributes<HTMLDivElement>>"
+    - name: SlideshowProps
+      kind: type
+    - name: SlideshowSlide
+      kind: component
+      typeText: "ForwardRefExoticComponent<SlideshowSlideProps & RefAttributes<HTMLDivElement>>"
+    - name: SlideshowSlideProps
+      kind: type
+    - name: SlideshowVariant
+      kind: type
+  primaryExport: Slideshow
+  subcomponents:
+    - SlideshowSlide
+  props:
+    Slideshow:
+      - name: autoplay
+        type: "false | number"
+        required: false
+        declaredIn: self
+        doc: "Auto-advance interval in ms. Pauses on hover / focus / explicit toggle. Pass `false` to disable (default). When enabled, a visible pause button appears in the top-right corner."
+      - name: index
+        type: number
+        required: false
+        declaredIn: self
+        doc: "Controlled active index."
+      - name: loop
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Wrap around at the edges (default true)."
+      - name: onIndexChange
+        type: "((index: number) => void)"
+        required: false
+        declaredIn: self
+        doc: "Callback fired when the active slide changes."
+      - name: showArrows
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Show prev/next arrow buttons (default true)."
+      - name: showDots
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Show dot indicators (default true)."
+      - name: variant
+        type: SlideshowVariant
+        required: false
+        declaredIn: self
+        doc: "Transition style - \"slide\" (default) or \"fade\"."
+  extendsProps:
+    - "React.HTMLAttributes<HTMLDivElement>"
+  variants:
+    variant:
+      kind: enum
+      options:
+        - slide
+        - fade
+      default: slide
+      on: Slideshow
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+      - motion
+    hooks:
+      - use-reduced-motion
+    external:
+      - lucide-react
+      - motion/react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-slideshow--default
+  storybookTitle: Components/Slideshow
+  docsId: components-slideshow--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "7c31eae3e85b"
+  factsHash: "3fd9118e5714"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A single-frame, one-at-a-time carousel with slide/fade transitions, drag-to-navigate, autoplay, and WCAG-compliant pause controls."
+useWhen:
+  - "presenting a sequence of slides one at a time in a single frame - a hero carousel, a testimonial rotator, a promo banner sequence"
+useInstead:
+  - id: media-gallery
+    when: "the images belong to one item and should be browsable as a grid with a separate fullscreen viewer, not rotate through one frame"
+related:
+  - media-gallery
+a11y:
+  notes:
+    - "Follows the WAI-ARIA carousel pattern: role=\"region\" and aria-roledescription=\"carousel\" on the root, role=\"group\" and aria-roledescription=\"slide\" on the active slide, and a live region announcing slide changes."
+    - "Autoplay pauses automatically on hover or keyboard focus (per WAI-ARIA carousel guidance) and always ships a visible pause/play button when enabled (per WCAG 2.2.2, a required control for auto-moving content) - both are already wired in, no extra setup needed."
+  keyboard:
+    - "ArrowLeft/ArrowRight change slides while the carousel has focus; the whole region is a single tab stop rather than each slide or control being separately tabbable in sequence."
+  radixHandles: false
+pitfalls:
+  - "Slideshow only ever renders the active slide - it does not mount all children at once, so a slide's own mount/unmount side effects (video autoplay, analytics) fire every time it becomes active, not once up front."
+  - "autoplay expects a number of milliseconds or false - there is no boolean true to just turn it on; passing true is a type error, and passing 0 disables it (falsy) rather than firing continuously."
+  - "loop=false disables wraparound, so the arrow buttons visually disable themselves at the ends - the dots remain clickable to jump anywhere regardless of loop."
+  - "index/onIndexChange make the active slide controllable, but there is no separate defaultIndex for an uncontrolled starting slide other than 0 - to start elsewhere without fully controlling it, pass index once on mount and stop passing it afterward."
+canonicalSnippet: |
+  import { Slideshow, SlideshowSlide } from "@adres/mgda-ui"
+
+  <Slideshow autoplay={5000} variant="fade">
+    <SlideshowSlide>Slide one</SlideshowSlide>
+    <SlideshowSlide>Slide two</SlideshowSlide>
+    <SlideshowSlide>Slide three</SlideshowSlide>
+  </Slideshow>
+reviewedAt: 2026-09-01
+reviewedAgainstContractHash: "7c31eae3e85b"
+---
+
+## Usage
+
+`Slideshow` rotates through slides one at a time in a single frame - a hero
+carousel, a testimonial rotator, a sequence of promo banners. Reach for
+`MediaGallery` instead when the images belong to one item and should be
+browsable as a grid with a separate fullscreen viewer, rather than rotating
+through one frame.
+
+`variant="slide"` (default) translates slides horizontally with drag support;
+`variant="fade"` cross-fades instead, useful when slides do not share the
+same visual weight or aspect ratio. Set `autoplay` to a millisecond interval
+to auto-advance - it pauses automatically on hover or focus and always shows
+a visible pause/play button, per the accessibility guidance the component
+already follows; there is no plain boolean form.
+
+`loop` (default true) controls whether the ends wrap around; `showArrows` and
+`showDots` toggle the two navigation affordances independently. Use
+`index`/`onIndexChange` to control the active slide externally, for example
+to sync it with another part of the page.
+
+## Anatomy
+
+| Part | Role |
+| --- | --- |
+| `Slideshow` | Root and viewport. Owns `variant`, `autoplay`, `loop`, `showArrows`, `showDots`, and the active index. Renders only the active slide. |
+| `SlideshowSlide` | One slide's content wrapper. Its children are whatever the slide should show - an image, a card, arbitrary content. |

package/knowledge/source.md

@@ -0,0 +1,156 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: source
+  sourceFile: packages/design-system/src/components/source.tsx
+  client: true
+  category: web-app-ai
+  categoryFromBarrel: web-app-ai
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Source
+      kind: component
+      typeText: "({ href, children }: SourceProps) => Element"
+    - name: SourceContent
+      kind: component
+      typeText: "({ title, description, favicon, className }: SourceContentProps) => Element"
+    - name: SourceContentProps
+      kind: type
+    - name: sourceDomain
+      kind: function
+      typeText: "(href: string) => string"
+    - name: SourceProps
+      kind: type
+    - name: SourceTrigger
+      kind: component
+      typeText: "ForwardRefExoticComponent<SourceTriggerProps & RefAttributes<HTMLAnchorElement>>"
+    - name: SourceTriggerProps
+      kind: type
+  primaryExport: Source
+  subcomponents:
+    - SourceContent
+    - SourceTrigger
+  props:
+    Source:
+      - name: children
+        type: ReactNode
+        required: true
+        declaredIn: self
+      - name: href
+        type: string
+        required: true
+        declaredIn: self
+    SourceContent:
+      - name: className
+        type: string
+        required: false
+        declaredIn: self
+      - name: description
+        type: string
+        required: false
+        declaredIn: self
+      - name: favicon
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Image URL for the site's icon; a link icon otherwise."
+      - name: title
+        type: string
+        required: true
+        declaredIn: self
+    SourceTrigger:
+      - name: favicon
+        type: "boolean | string"
+        required: false
+        declaredIn: self
+        doc: "Shows a favicon before the label. Pass an image URL to use it; otherwise a link icon."
+      - name: label
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Replaces the domain, e.g. a citation number."
+  extendsProps: []
+  variants: {}
+  variantSource: none
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots:
+    - source-trigger
+  dependsOn:
+    internal:
+      - popover
+      - text
+    lib:
+      - cn
+    hooks: []
+    external:
+      - lucide-react
+      - react
+  contexts:
+    - name: SourceContext
+      type: SourceContextValue
+      default: null
+  stories:
+    - exportName: InText
+      id: components-source--in-text
+  storybookTitle: Components/Source
+  docsId: components-source--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "68fe1400de6f"
+  factsHash: "961f531d3a9e"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: beta
+summary: "A link to where an answer came from: a small pill in running text labelled with the domain, previewing the page on hover and keyboard focus. Works from a URL alone."
+useWhen:
+  - "an answer cites web pages and you only have a URL, title and short description"
+  - "the citation should be a real link people can open straight from the text"
+useInstead:
+  - id: citations
+    when: "sources are numbered with a publisher, date and the passage used, and listed under the answer"
+related:
+  - citations
+  - chat-message
+a11y:
+  notes:
+    - "The pill is a real link; its name is the domain, or \"Source 2, domain\" with a custom label."
+    - "The preview opens on hover and on keyboard focus without moving focus, and closes on blur, pointer leave or Escape."
+    - "The preview repeats the pill's link, so it is skipped in the tab order; keyboard users lose nothing."
+    - "Favicons are decorative (empty alt); a link icon stands in when there is none or it fails to load."
+  radixHandles: true
+pitfalls:
+  - "No favicon service is called. Pass favicon with an image URL you trust; true shows a link icon."
+  - "Pass a full URL so the domain can be read; anything else is shown as given."
+  - "Keep label short: a number or a short name. The pill truncates at a small width."
+canonicalSnippet: |
+  import { Source, SourceTrigger, SourceContent } from "@adres/mgda-ui"
+
+  <Source href="https://www.propertyfinder.ae/en/yas-island">
+    <SourceTrigger favicon />
+    <SourceContent
+      title="Townhouses for sale in Yas Island"
+      description="42 townhouses under AED 5M, 11 with a private garden."
+    />
+  </Source>
+reviewedAt: 2026-10-06
+reviewedAgainstContractHash: "68fe1400de6f"
+---
+
+## Usage
+
+Put a `Source` inline after the claim it backs. `SourceTrigger` is the pill:
+a link to `href`, labelled with its domain (`propertyfinder.ae`) unless you
+pass `label`, such as a citation number. `favicon` adds an icon before the
+label: an image URL you provide, or `true` for a link icon.
+
+`SourceContent` is the preview that opens on hover and keyboard focus: the
+domain, a `title` and an optional `description`, all one link to the source.
+`sourceDomain` returns the label text for custom layouts.
+
+## Anatomy
+
+- `Source` - holds the URL and the hover state.
+- `SourceTrigger` - the inline link pill.
+- `SourceContent` - the hover preview with domain, title and description.

package/knowledge/spinner.md

@@ -0,0 +1,120 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: spinner
+  sourceFile: packages/design-system/src/components/spinner.tsx
+  client: true
+  category: web-app-feedback
+  categoryFromBarrel: web-app-feedback
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Spinner
+      kind: component
+      typeText: "ForwardRefExoticComponent<SpinnerProps & RefAttributes<SVGSVGElement>>"
+    - name: SpinnerProps
+      kind: type
+    - name: SpinnerSize
+      kind: type
+  primaryExport: Spinner
+  subcomponents: []
+  props:
+    Spinner:
+      - name: decorative
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Hide from assistive tech (`aria-hidden`, drops `role` and `aria-label`). Use when a sibling element already announces the loading state - e.g. inside a button with visible \"Saving...\" text - to avoid duplicate screen-reader announcements."
+      - name: label
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Accessible label announced by screen readers via the live region. Defaults to `\"Loading\"`. Use this for i18n or to be more specific (\"Saving\", \"Searching\", \"Fetching listings\"). Ignored when `decorative` is true."
+      - name: size
+        type: "\"lg\" | \"md\" | \"sm\" | \"xl\""
+        required: false
+        declaredIn: self
+        variantKey: true
+  extendsProps:
+    - "React.SVGAttributes<SVGSVGElement>"
+    - "VariantProps<typeof spinnerVariants>"
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+        - xl
+      default: md
+      on: Spinner
+  variantSource: cva
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - class-variance-authority
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-spinner--default
+    - exportName: Large
+      id: components-spinner--large
+  storybookTitle: Components/Spinner
+  docsId: components-spinner--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: e95dc7cdfd4a
+  factsHash: bb3a461c6eac
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "An indeterminate loading spinner, with a built-in accessible label and reduced-motion handling."
+useWhen:
+  - "indicating something is loading with no known duration or percentage - an inline button state, a data fetch, a page-level loading state"
+useInstead:
+  - id: progress
+    when: "there is a known value or percentage to show, not just an indeterminate wait"
+  - id: skeleton
+    when: "the shape of the content is already known while it loads - a placeholder that matches the eventual layout reduces perceived wait better than a spinner"
+related:
+  - progress
+  - skeleton
+a11y:
+  notes:
+    - "Sets role=\"status\" and aria-label (default \"Loading\") automatically - this is a live region, so screen readers announce it once on mount; it does not re-announce as time passes."
+    - "Set decorative when a sibling element already announces the loading state, e.g. a Button showing visible \"Saving...\" text - otherwise the visible message and the spinner's own announcement can double up for screen reader users."
+    - "Reduced motion does not stop the spin - a fully static spinner reads as a plain circle, not loading - it slows the animation to a 3-second cycle instead, keeping the semantic while respecting the preference."
+  radixHandles: false
+pitfalls:
+  - "label is ignored entirely when decorative is true - setting both has no effect, decorative wins."
+  - "There is no built-in text near the spinner - label only reaches assistive tech via aria-label; sighted users see no visible loading text unless it is added alongside the spinner."
+  - "size uses a wider four-step scale (sm/md/lg/xl) than most sized primitives' three-step sm/md/lg - a size=\"xl\" ported from another component's scale does not exist there."
+canonicalSnippet: |
+  import { Spinner } from "@adres/mgda-ui"
+
+  <Spinner size="md" label="Loading results" />
+reviewedAt: 2026-09-01
+reviewedAgainstContractHash: e95dc7cdfd4a
+---
+
+## Usage
+
+`Spinner` is for an indeterminate wait - no known duration or percentage,
+just an indication that something is happening. Reach for `Progress` instead
+once there is a real value to show, and `Skeleton` when the shape of the
+eventual content is already known, since a shape-matched placeholder reduces
+perceived wait better than a spinning glyph.
+
+`label` sets the accessible announcement (default `"Loading"`) - customize it
+to be specific ("Saving", "Searching") or for i18n; it has no visible
+on-screen text of its own, so add that separately if sighted users should see
+the message too. Set `decorative` when a sibling element already announces
+the loading state, such as a `Button` with visible "Saving..." text, to avoid
+a duplicate screen-reader announcement - this also ignores `label`.

package/knowledge/stat-strip.md

@@ -0,0 +1,128 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: stat-strip
+  sourceFile: packages/design-system/src/components/stat-strip.tsx
+  client: false
+  category: web-app-layout-navigation
+  categoryFromBarrel: web-app-layout-navigation
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: StatStrip
+      kind: component
+      typeText: "ForwardRefExoticComponent<StatStripProps & RefAttributes<HTMLDivElement>>"
+    - name: StatStripItem
+      kind: type
+    - name: StatStripProps
+      kind: type
+    - name: StatStripTone
+      kind: type
+    - name: statStripVariants
+      kind: variants
+      typeText: "TVReturnType<{ tone: { neutral: { root: string; item: string; }; primary: { root: string; item: string; }; secondary: { root: string; item: string; }; }; }, { root: string; label: string; list: string; item: string; }, u...[truncated]"
+  primaryExport: StatStrip
+  subcomponents: []
+  props:
+    StatStrip:
+      - name: items
+        type: "StatStripItem[]"
+        required: true
+        declaredIn: self
+      - name: label
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Leading caption naming the set, e.g. \"Madhmoun MLS global stats\"."
+      - name: tone
+        type: "\"neutral\" | \"primary\" | \"secondary\""
+        required: false
+        declaredIn: self
+        variantKey: true
+  extendsProps:
+    - "Omit<React.HTMLAttributes<HTMLDivElement>, \"children\">"
+    - "VariantProps<typeof statStripVariants>"
+  variants:
+    tone:
+      kind: enum
+      options:
+        - neutral
+        - primary
+        - secondary
+      default: neutral
+      on: StatStrip
+  variantSource: tv
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots:
+    - stat-strip
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - react
+      - tailwind-variants
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-statstrip--default
+    - exportName: Tones
+      id: components-statstrip--tones
+    - exportName: WithoutLabel
+      id: components-statstrip--without-label
+  storybookTitle: Components/StatStrip
+  docsId: components-statstrip--documentation
+  argTypeOptions:
+    tone:
+      - neutral
+      - primary
+      - secondary
+  resolvedCleanly: true
+  contractHash: e912832b643f
+  factsHash: a5acbbc99beb
+# >>> AUTHORED - humans own everything below this line. <<<
+status: beta
+summary: "A compact single-line bar of headline figures (icon, label, value) with an optional leading caption, for the top of a dashboard."
+useWhen:
+  - "a few platform-wide or account-wide totals sit above a dashboard, such as sold, on-market and deals"
+  - "figures need to be glanceable without taking a card row of their own"
+useInstead:
+  - id: kpi-card
+    when: "each figure needs a trend, an explanation or room to be the focus"
+  - id: stats
+    when: "the figures are a marketing section with large numbers and descriptions"
+  - id: data-list
+    when: "the values are facts such as licence numbers, not figures to compare"
+related:
+  - kpi-card
+  - stats
+a11y:
+  notes:
+    - "Renders a definition list, so each label is announced with its value; the caption labels the list via aria-labelledby."
+    - "Mark item icons aria-hidden; the label already names the figure."
+  radixHandles: false
+pitfalls:
+  - "Keep it to about four items; more wraps onto several lines from sm up and loses the strip's purpose."
+  - "Values are not formatted for you; pass them already formatted (\"1,086\")."
+canonicalSnippet: |
+  import { StatStrip } from "@adres/mgda-ui"
+
+  <StatStrip
+    tone="secondary"
+    label="Platform stats"
+    items={platformStats}
+  />
+reviewedAt: 2026-10-06
+reviewedAgainstContractHash: e912832b643f
+---
+
+## Usage
+
+`StatStrip` puts a handful of headline totals in one compact line. Each item
+is an optional icon, a label and a value, rendered as a definition list. The
+`tone` (`neutral`, `primary` or `secondary`) tints the whole strip using the
+mode-aware `weakest` fills, so it reads in light and dark without overrides.
+Below `sm` the items fall into two columns.

package/knowledge/stats.md

@@ -0,0 +1,117 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: stats
+  sourceFile: packages/design-system/src/components/stats.tsx
+  client: true
+  category: marketing
+  categoryFromBarrel: marketing
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Stat
+      kind: type
+    - name: Stats
+      kind: component
+      typeText: "({ className, eyebrow, title, description, stats, ...props }: StatsProps) => Element"
+    - name: StatsProps
+      kind: type
+  primaryExport: Stats
+  subcomponents: []
+  props:
+    Stats:
+      - name: description
+        type: ReactNode
+        required: false
+        declaredIn: self
+      - name: eyebrow
+        type: ReactNode
+        required: false
+        declaredIn: self
+      - name: stats
+        type: "Stat[]"
+        required: true
+        declaredIn: self
+      - name: title
+        type: ReactNode
+        required: false
+        declaredIn: self
+  extendsProps:
+    - "Omit<React.HTMLAttributes<HTMLElement>, \"title\">"
+  variants: {}
+  variantSource: none
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+      - motion
+    hooks:
+      - use-reduced-motion
+    external:
+      - motion/react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-stats--default
+  storybookTitle: Components/Stats
+  docsId: components-stats--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "78f9fd08f2ae"
+  factsHash: fb7c350dd8df
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A marketing stat block: an optional eyebrow/title/description header above a responsive grid of large numbers with labels, in a seamless bordered layout."
+useWhen:
+  - "showcasing a handful of headline numbers on a marketing or landing page - customers served, uptime, years in business"
+useInstead:
+  - id: kpi-card
+    when: "the metric belongs to a dashboard, not a marketing page, and needs its own bordered card, loading state, or trend delta"
+  - id: bar-graph
+    when: "the numbers need to be visually compared against each other, not just displayed side by side"
+related:
+  - kpi-card
+  - bar-graph
+a11y:
+  notes:
+    - "Renders a real dl/dt/dd structure - each stat's label and value are semantically paired the same way DataList's are, even though the visual layout is a grid of tiles rather than rows."
+  radixHandles: false
+pitfalls:
+  - "The grid's column count is derived entirely from stats.length (2/3/4/5+ each get their own breakpoint treatment) - there is no columns override prop, unlike FeatureGrid or Testimonials which do expose one."
+  - "value is ReactNode, not a number - the component does not format, animate-count, or add a unit or suffix on its own; pre-format the string (\"10k+\", \"99.9%\") before passing it."
+  - "The stagger entrance animation runs on scroll-into-view, the same as FeatureGrid and Testimonials - a Stats block already in the viewport on page load still needs to cross the configured viewport margin to trigger."
+canonicalSnippet: |
+  import { Stats } from "@adres/mgda-ui"
+
+  const sectionTitle = "Trusted at scale"
+  const metrics = [
+    { label: "Customers", value: "10k+" },
+    { label: "Uptime", value: "99.9%" },
+    { label: "Countries", value: "40+" },
+  ]
+
+  <Stats title={sectionTitle} stats={metrics} />
+reviewedAt: 2026-09-01
+reviewedAgainstContractHash: "78f9fd08f2ae"
+---
+
+## Usage
+
+`Stats` showcases a handful of headline numbers on a marketing or landing
+page - customers served, uptime, years in business - in a seamless bordered
+grid of label/value tiles. Reach for `KpiCard` instead when the metric
+belongs to a dashboard rather than a marketing page and needs its own card
+chrome, loading state, or trend delta, and `BarGraph` when the numbers need
+to be visually compared against each other rather than just displayed side
+by side.
+
+The grid's column count is derived entirely from how many `stats` are
+passed - there is no `columns` override, unlike `FeatureGrid` or
+`Testimonials`. `value` is `ReactNode`, not a number: pre-format it
+("10k+", "99.9%") before passing it in, since the component does not add
+units, suffixes, or count-up animation on its own.