@adres/mgda-ui 0.0.0-stage → 0.0.2

package/knowledge/inset.md

@@ -0,0 +1,177 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: inset
+  sourceFile: packages/design-system/src/components/inset.tsx
+  client: true
+  category: web-app-core-primitives
+  categoryFromBarrel: web-app-core-primitives
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Inset
+      kind: component
+      typeText: "ForwardRefExoticComponent<InsetProps & RefAttributes<HTMLDivElement>>"
+    - name: InsetClip
+      kind: type
+    - name: InsetProps
+      kind: type
+    - name: InsetSide
+      kind: type
+  primaryExport: Inset
+  subcomponents: []
+  props:
+    Inset:
+      - name: clip
+        type: InsetClip
+        required: false
+        declaredIn: self
+        doc: "Whether the content clips at the border or allows overflow. Default \"border-box\"."
+      - name: pb
+        type: "\"current\" | \"none\""
+        required: false
+        declaredIn: self
+        doc: "Add padding equal to the container's inset padding BELOW the element. Use with side=\"top\" to gap the inset away from siblings below it."
+      - name: pl
+        type: "\"current\" | \"none\""
+        required: false
+        declaredIn: self
+        doc: "Add padding equal to the container's inset padding LEFT of the element. Use with side=\"right\" to gap the inset away from siblings to its left."
+      - name: pr
+        type: "\"current\" | \"none\""
+        required: false
+        declaredIn: self
+        doc: "Add padding equal to the container's inset padding RIGHT of the element. Use with side=\"left\" to gap the inset away from siblings to its right."
+      - name: pt
+        type: "\"current\" | \"none\""
+        required: false
+        declaredIn: self
+        doc: "Add padding equal to the container's inset padding ABOVE the element. Use with side=\"bottom\" to gap the inset away from siblings above it."
+      - name: side
+        type: InsetSide
+        required: false
+        declaredIn: self
+        doc: "Which edges the content bleeds to. Named by the face of the container: \"top\" → bleeds to top, left, and right edges. \"left\" → bleeds to left, top, and bottom edges."
+  extendsProps:
+    - "React.HTMLAttributes<HTMLDivElement>"
+  variants:
+    side:
+      kind: enum
+      options:
+        - left
+        - right
+        - bottom
+        - top
+        - all
+        - x
+        - y
+      default: all
+      on: Inset
+    clip:
+      kind: enum
+      options:
+        - border-box
+        - padding-box
+      default: border-box
+      on: Inset
+    pt:
+      kind: enum
+      options:
+        - none
+        - current
+      default: none
+      on: Inset
+    pb:
+      kind: enum
+      options:
+        - none
+        - current
+      default: none
+      on: Inset
+    pl:
+      kind: enum
+      options:
+        - none
+        - current
+      default: none
+      on: Inset
+    pr:
+      kind: enum
+      options:
+        - none
+        - current
+      default: none
+      on: Inset
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-inset--default
+  storybookTitle: Components/Inset
+  docsId: components-inset--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "9ebe09dabae3"
+  factsHash: "2326dc7f0878"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A layout helper that lets a child bleed past its Card's padding via negative margin, for full-bleed media or dividers inside a padded Card."
+useWhen:
+  - "an image, banner, or divider inside a Card needs to visually touch the card's edges despite the card's own padding"
+useInstead:
+  - id: card
+    when: "you need the actual bordered or elevated surface, not just the bleed helper used inside one"
+related:
+  - card
+a11y:
+  notes:
+    - "Inset only affects layout via negative margins and padding, so it carries no semantic role - the accessibility of its children is unaffected by using it."
+  radixHandles: false
+pitfalls:
+  - "Inset reads --inset-padding from a Card ancestor's inline style - used outside a Card, or with no ancestor setting that variable, side has no visible effect because the negative margin falls back to var(--inset-padding, 0px), which resolves to 0."
+  - "side names the edges being bled TO, not the edge left alone - side=\"top\" bleeds the top, left, and right edges (all but the bottom), which reads backwards from what the name suggests."
+canonicalSnippet: |
+  import { Card, CardContent, CardHeader, CardTitle, Inset } from "@adres/mgda-ui"
+
+  <Card className="ax:max-w-sm">
+    <CardHeader>
+      <CardTitle>Media card</CardTitle>
+    </CardHeader>
+    <Inset side="x" clip="padding-box">
+      <img src="/banner.jpg" alt="" className="ax:h-32 ax:w-full ax:object-cover" />
+    </Inset>
+    <CardContent>
+      <p>Content below the inset.</p>
+    </CardContent>
+  </Card>
+reviewedAt: 2026-09-29
+reviewedAgainstContractHash: "9ebe09dabae3"
+---
+
+## Usage
+
+`Inset` is a layout helper, not a surface - it only exists to let content
+break out of its container's padding via negative margin. It reads
+`--inset-padding` from the nearest ancestor that sets it, currently only
+`Card` (keyed off `Card`'s own `padding` prop), so it only does anything
+meaningful nested inside a `Card`.
+
+Reach for it to make a media block, banner image, or divider touch the edges
+of an otherwise padded `Card`, without overriding the `Card`'s own padding for
+the whole surface. `side` names the edge or edges being bled to, not the edge
+being kept: `side="x"` bleeds left and right, `side="top"` bleeds top, left,
+and right - all edges except the bottom.
+
+Use `clip="padding-box"` (the default is `"border-box"`) when the bled content
+should be allowed to overflow rather than clip at the container's edge.

package/knowledge/kpi-card.md

@@ -0,0 +1,206 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: kpi-card
+  sourceFile: packages/design-system/src/components/kpi-card.tsx
+  client: true
+  category: web-app-patterns
+  categoryFromBarrel: web-app-patterns
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: KpiCard
+      kind: component
+      typeText: "ForwardRefExoticComponent<KpiCardProps & RefAttributes<HTMLDivElement>>"
+    - name: KpiCardGroup
+      kind: component
+      typeText: "ForwardRefExoticComponent<KpiCardGroupProps & RefAttributes<HTMLDivElement>>"
+    - name: KpiCardGroupProps
+      kind: type
+    - name: KpiCardProps
+      kind: type
+    - name: KpiCardSize
+      kind: type
+  primaryExport: KpiCard
+  subcomponents:
+    - KpiCardGroup
+  props:
+    KpiCard:
+      - name: change
+        type: number
+        required: false
+        declaredIn: self
+        doc: "Optional period-over-period delta as a percentage. Positive → success pill with an up-arrow; negative → destructive pill with a down-arrow. `0` and `undefined` both render no delta - zero isn't a trend."
+      - name: description
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Optional context line under the value (e.g. \"vs last 30 days\")."
+      - name: icon
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Optional topic icon - rendered muted, top-end of the card."
+      - name: loading
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "While true, swaps the title/value/delta for skeleton placeholders."
+      - name: size
+        type: KpiCardSize
+        required: false
+        declaredIn: self
+        doc: "Visual density. `md` is the default."
+      - name: suffix
+        type: string
+        required: false
+        declaredIn: self
+        doc: "Optional suffix appended to the value (e.g. \"%\", \"h\"). Rendered in a smaller muted style so it doesn't compete with the number."
+      - name: title
+        type: string
+        required: true
+        declaredIn: self
+        doc: "Overline label sitting above the value."
+      - name: value
+        type: "number | string"
+        required: true
+        declaredIn: self
+        doc: "The metric itself. Strings are useful for pre-formatted values (\"76 %\", \"1.2k\"). Numbers get a `0` fallback for the empty state."
+    KpiCardGroup:
+      - name: columns
+        type: "2 | 3 | 4"
+        required: false
+        declaredIn: self
+        doc: "Lay the cards out in a fixed N-column grid instead of a single flex row. With `compact`, the grid renders as a seamless bordered \"table\" - 1px hairline dividers between cells inside a rounded outer frame. Give a card `sm:col-span-*` to make a row span fewer, wider columns (e.g. a 4-column grid whose second row is two `col-span-2` cells)."
+      - name: compact
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Merge children into a borderless single-block layout."
+  extendsProps:
+    - "React.HTMLAttributes<HTMLDivElement>"
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+        - mini
+      default: md
+      on: KpiCard
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps:
+    - CARD_PADDING
+    - CONTENT_GAP
+    - GRID_COLS
+    - ICON_CLASS
+    - SKELETON_VALUE_HEIGHT
+    - SUFFIX_CLASS
+    - TREND_CLASS
+    - TREND_ICON_CLASS
+    - VALUE_CLASS
+  dataSlots: []
+  dependsOn:
+    internal:
+      - card
+      - skeleton
+    lib:
+      - cn
+    hooks: []
+    external:
+      - lucide-react
+      - react
+  contexts:
+    - name: KpiCardGroupContext
+      type: KpiCardGroupContextValue
+      default: null
+  stories:
+    - exportName: Default
+      id: components-kpicard--default
+    - exportName: Loading
+      id: components-kpicard--loading
+  storybookTitle: Components/KpiCard
+  docsId: components-kpicard--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: f7cb46ea7ce2
+  factsHash: "6fcc8d61857b"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A single-metric dashboard card - a big number, label, optional trend delta, icon, and description, with a built-in loading and empty state."
+useWhen:
+  - "showing one key metric on a dashboard, prominently, with an optional period-over-period trend"
+  - "several metrics need to read as one connected block, via KpiCardGroup, optionally compact and/or gridded"
+useInstead:
+  - id: card
+    when: "the content is not a single headline metric - use plain Card for general-purpose containers"
+  - id: data-list
+    when: "showing several label/value pairs together, not one prominent metric per card"
+  - id: stats
+    when: "presenting metrics in a marketing/landing-page context rather than a dashboard"
+related:
+  - card
+  - data-list
+  - stats
+tokens:
+  - "--success-foreground"
+  - "--destructive-foreground"
+  - "--muted-foreground"
+  - "--foreground"
+  - "--card"
+  - "--border"
+a11y:
+  notes:
+    - "loading swaps content for Skeleton placeholders (aria-hidden, per Skeleton's own contract) - pair a KpiCard's loading state with a real loading announcement elsewhere, e.g. an aria-live region on the dashboard, if the fetch itself needs to be announced."
+    - "Making the card clickable (passing onClick) only changes hover styling and cursor - it does not add button or link semantics or keyboard activation on its own. Wrap it in a real interactive element, or add role/tabIndex/keyboard handling directly, if it should truly be operable."
+  radixHandles: false
+pitfalls:
+  - "The empty state (\"No data yet\") triggers purely from value coercing to 0 - a metric that is legitimately zero (e.g. \"0 open incidents\", a good result) shows the empty-state message instead of \"0\" unless routed around with a formatted string value that does not coerce to exactly 0."
+  - "change of exactly 0 renders no trend at all, the same as change={undefined} - there is no neutral or flat trend indicator; a genuinely flat period-over-period reads identically to no data available for the trend row."
+  - "KpiCardGroup's compact and columns interact: compact alone merges cards into one flush row or column; compact plus columns renders a seamless bordered grid table instead, and cards inside drop essentially all their own chrome (border, radius, shadow) since the group draws it. Setting size or padding on an individual card inside a compact group has a smaller visual effect than expected."
+  - "The hover-lift interactive behavior is automatically suppressed for compact cards even if onClick is passed - compact cards never lift on hover, regardless of interactivity."
+canonicalSnippet: |
+  import { KpiCard, KpiCardGroup } from "@adres/mgda-ui"
+
+  const metricTitle = "Active users"
+  const periodLabel = "vs last 30 days"
+
+  <KpiCardGroup className="ax:max-w-xs">
+    <KpiCard title={metricTitle} value={1284} change={12} description={periodLabel} />
+  </KpiCardGroup>
+reviewedAt: 2026-09-01
+reviewedAgainstContractHash: f7cb46ea7ce2
+---
+
+## Usage
+
+`KpiCard` is a single-metric dashboard card - a big `value` under a `title`
+label, with an optional trend `change` (a success or destructive pill with
+an up or down arrow), a topic `icon`, and a `description` line. Reach for
+plain `Card` when the content is not one headline metric, `DataList` for
+several label/value pairs together rather than one prominent number per
+card, and `Stats` for a marketing or landing-page metrics context instead of
+a dashboard.
+
+Always wrap `KpiCard`s in `KpiCardGroup`, even for a single card - it
+supplies the responsive grid or row layout and the `compact`/`columns`
+context every card reads from. `compact` merges cards into one flush block
+with shared borders instead of separate cards; `compact` plus `columns` goes
+further, rendering a seamless bordered grid table where cards drop their own
+chrome entirely.
+
+Set `loading` to swap the title, value, and trend for `Skeleton`
+placeholders while data is in flight. The built-in empty state ("No data
+yet") triggers automatically whenever `value` coerces to exactly `0` and no
+`change` is given - a legitimately-zero metric needs a formatted string
+`value` to avoid reading as "no data."
+
+## Anatomy
+
+| Part | Role |
+| --- | --- |
+| `KpiCardGroup` | Layout wrapper. Owns `compact` and `columns`, shared with every `KpiCard` inside via context. |
+| `KpiCard` | One metric. Built on `Card` and `Skeleton` internally; owns `title`, `value`, `change`, `suffix`, `icon`, `description`, `size`, `loading`. |

package/knowledge/list-nav.md

@@ -0,0 +1,181 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: list-nav
+  sourceFile: packages/design-system/src/components/list-nav.tsx
+  client: true
+  category: web-app-layout-navigation
+  categoryFromBarrel: web-app-layout-navigation
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: ListNav
+      kind: component
+      typeText: "ForwardRefExoticComponent<ListNavProps & RefAttributes<HTMLElement>>"
+    - name: ListNavItem
+      kind: component
+      typeText: "ForwardRefExoticComponent<ListNavItemProps & RefAttributes<HTMLButtonElement>>"
+    - name: ListNavItemProps
+      kind: type
+    - name: ListNavProps
+      kind: type
+    - name: ListNavSize
+      kind: type
+  primaryExport: ListNav
+  subcomponents:
+    - ListNavItem
+  props:
+    ListNav:
+      - name: size
+        type: ListNavSize
+        required: false
+        declaredIn: self
+        doc: "Row density. `base` (default) is compact; `lg` adds padding for a larger, touch-friendly tap target. Cascades to all items via context."
+      - name: title
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Optional eyebrow-style title rendered above the list (uses `t-overline`)."
+    ListNavItem:
+      - name: active
+        type: boolean
+        required: false
+        declaredIn: self
+      - name: asChild
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Render as the child element (e.g. a Next.js `<Link>`). The child receives the className, ref, and event props so it behaves as a list-nav row while keeping its own navigation behaviour."
+      - name: icon
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Optional leading icon."
+      - name: inset
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Reserves the leading icon column even when no icon is provided. Use when mixing items with and without icons in the same list, so labels stay aligned. Has no effect if `icon` is set."
+      - name: size
+        type: ListNavSize
+        required: false
+        declaredIn: self
+        doc: "Overrides the row density inherited from `ListNav` for this item."
+      - name: trailing
+        type: ReactNode
+        required: false
+        declaredIn: self
+        doc: "Trailing slot - typically a Badge, count, or shortcut hint."
+  extendsProps:
+    - "Omit<React.HTMLAttributes<HTMLElement>, \"title\">"
+  variants:
+    size:
+      kind: enum
+      options:
+        - base
+        - lg
+      default: base
+      on: ListNav
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps:
+    - ICON_BOX
+    - ITEM_SIZE
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - "@radix-ui/react-slot"
+      - react
+  contexts:
+    - name: ListNavContext
+      type: ListNavContextValue
+      default: null
+  stories:
+    - exportName: Default
+      id: components-listnav--default
+  storybookTitle: Components/ListNav
+  docsId: components-listnav--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "9439cca1c18c"
+  factsHash: "0e2c0b22a60d"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A vertical list of selectable items, for in-page jumpers and dense filter lists without an icon-column app-shell nav."
+useWhen:
+  - "an in-page section jumper or table-of-contents style list"
+  - "a dense filter or facet list (categories, saved views, settings sections)"
+  - "a sidebar-adjacent list of selectable rows that doesn't need brand/collapse/tooltips"
+useInstead:
+  - id: sidebar
+    when: "you need the full app-shell chrome - brand slot, collapse-to-icon-rail, tooltips on collapse"
+  - id: nav-sidebar
+    when: "the list is a primary app nav driven by the current route, with nested children"
+  - id: cards-nav
+    when: "each destination deserves a bigger, card-style target with a description, not a compact row"
+related:
+  - sidebar
+  - cards-nav
+composesWith:
+  - badge
+tokens:
+  - "--input-radius"
+  - "--primary-muted"
+  - "--primary-foreground"
+  - "--primary-strong"
+  - "--muted"
+  - "--muted-foreground"
+  - "--ring"
+a11y:
+  notes:
+    - "ListNavItem renders a real <button type=\"button\"> by default, so it's keyboard-reachable and activatable without any extra wiring."
+    - "active sets aria-current=\"page\" - use it for the currently selected/viewed item, not just a visual highlight."
+    - "asChild switches the rendered element to the child (e.g. a router Link); type is correctly omitted in that case since type is invalid on a non-button element."
+  requiredProps: []
+  keyboard:
+    - "Native button semantics: Enter and Space activate, Tab order is automatic."
+    - "asChild hands semantics to the child - wrapping an anchor makes it a link, and Space no longer activates it."
+  radixHandles: false
+pitfalls:
+  - "size on ListNav only sets the default for items via context; an item can still override it with its own size prop, so an unexpectedly-sized row is usually an explicit override, not a bug in the list."
+  - "inset has no effect once icon is set - it only exists to reserve the icon column's width for rows that intentionally have no icon, so sibling labels stay aligned."
+  - "ListNav renders a title inside the same <nav>, not a separate landmark - stacking multiple ListNavs for grouped sections means multiple <nav> elements, which is intentional but worth knowing before adding a wrapping <nav> of your own."
+subcomponentNotes:
+  ListNavItem: "A single row. Reads its density from the parent ListNav's size via context unless overridden. trailing is typically a Badge, count, or keyboard shortcut hint."
+rtl: "Uses text-start and gap-based spacing throughout, so rows flip correctly under RTL with no extra work."
+canonicalSnippet: |
+  import { ListNav, ListNavItem } from "@adres/mgda-ui"
+  import { Home, Settings } from "lucide-react"
+
+  <ListNav title="Workspace">
+    <ListNavItem icon={<Home />} active>Overview</ListNavItem>
+    <ListNavItem icon={<Settings />}>Settings</ListNavItem>
+  </ListNav>
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: "9439cca1c18c"
+---
+
+## Usage
+
+ListNav is a lighter-weight alternative to `Sidebar`/`NavSidebar`: a vertical
+list of rows with an optional eyebrow title, no brand slot, no collapse
+behavior, no built-in routing. Reach for it when you need selectable rows -
+an in-page jumper, a filter list, a settings sub-nav - without the full
+app-shell machinery.
+
+`size` cascades from `ListNav` to every `ListNavItem` via context, so setting
+it once on the list sets the density for the whole group; an individual item
+can still opt out with its own `size`.
+
+## Anatomy
+
+- **ListNav** - the list wrapper: an optional overline `title`, then the
+  items in a flex column.
+- **ListNavItem** - a single row: optional leading icon, label, optional
+  trailing slot. `active` renders the tinted/bold selected state and sets
+  `aria-current="page"`.

package/knowledge/logo-cloud.md

@@ -0,0 +1,102 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: logo-cloud
+  sourceFile: packages/design-system/src/components/logo-cloud.tsx
+  client: false
+  category: marketing
+  categoryFromBarrel: marketing
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: LogoCloud
+      kind: component
+      typeText: "({ className, eyebrow, items, ...props }: LogoCloudProps) => Element"
+    - name: LogoCloudItem
+      kind: type
+    - name: LogoCloudProps
+      kind: type
+  primaryExport: LogoCloud
+  subcomponents: []
+  props:
+    LogoCloud:
+      - name: eyebrow
+        type: ReactNode
+        required: false
+        declaredIn: self
+      - name: items
+        type: "LogoCloudItem[]"
+        required: true
+        declaredIn: self
+  extendsProps:
+    - "React.HTMLAttributes<HTMLElement>"
+  variants: {}
+  variantSource: none
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-logocloud--default
+  storybookTitle: Components/LogoCloud
+  docsId: components-logocloud--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: b7598f5dedbe
+  factsHash: "783b49aab241"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A trust-signal strip of partner or customer logos in a responsive grid, each dimmed to grayscale until hovered."
+useWhen:
+  - "showing a set of partner, customer, or press logos as social proof - typically near a hero or footer"
+useInstead:
+  - id: footer
+    when: "the section is page navigation and legal content, not a logo trust-signal strip"
+related:
+  - footer
+a11y:
+  notes:
+    - "Each logo cell sets a title attribute on its wrapper div, which surfaces as a native hover tooltip in most browsers but is not read by most screen readers on a non-interactive div - if the logos need to be genuinely accessible rather than decorative, give item.logo itself proper alt text or an aria-label, do not rely on the wrapper's title."
+  radixHandles: false
+pitfalls:
+  - "Every logo renders at reduced opacity and grayscale until hover, by design - a logo passed as a colored image or SVG still visually reads as muted at rest, which is expected here, not a bug to fix by overriding the item's own styling."
+  - "The grid is a fixed responsive column count, 2 at mobile up through 6 at lg - there is no columns prop to override it, unlike FeatureGrid or KpiCardGroup which do expose one."
+  - "item.logo is fully caller-supplied content, usually an image or inline SVG - LogoCloud itself sets no width or height constraints on it beyond the grid cell, so an unconstrained logo image can render inconsistently sized next to its neighbors unless each logo is pre-sized similarly."
+canonicalSnippet: |
+  import { LogoCloud } from "@adres/mgda-ui"
+
+  const partners = [
+    { name: "Acme", logo: <img src="/logos/acme.svg" alt="Acme" /> },
+    { name: "Globex", logo: <img src="/logos/globex.svg" alt="Globex" /> },
+  ]
+  const eyebrowText = "Trusted by teams worldwide"
+
+  <LogoCloud items={partners} eyebrow={eyebrowText} />
+reviewedAt: 2026-09-01
+reviewedAgainstContractHash: b7598f5dedbe
+---
+
+## Usage
+
+`LogoCloud` shows a set of partner, customer, or press logos as social
+proof, typically near a hero section or a footer. Reach for `Footer`
+instead when the section is page navigation and legal content rather than a
+logo trust-signal strip.
+
+Every logo renders at reduced opacity and grayscale until hover, by design -
+this happens regardless of the logo's own colors, so a colored image will
+still read as muted at rest.
+
+The grid's column count is fixed and responsive (2 at mobile up through 6 at
+`lg`) with no override prop, unlike `FeatureGrid`'s `columns`. Pre-size each
+`item.logo` similarly, since the component itself sets no width or height
+constraint on the logo content beyond the grid cell.