@adres/mgda-ui 0.0.0-stage → 0.0.1

package/knowledge/blockquote.md

@@ -0,0 +1,153 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: blockquote
+  sourceFile: packages/design-system/src/components/blockquote.tsx
+  client: true
+  category: web-app-core-primitives
+  categoryFromBarrel: web-app-core-primitives
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: Blockquote
+      kind: component
+      typeText: "ForwardRefExoticComponent<BlockquoteProps & RefAttributes<HTMLQuoteElement>>"
+    - name: BlockquoteCaption
+      kind: component
+      typeText: "ForwardRefExoticComponent<BlockquoteCaptionProps & RefAttributes<HTMLElement>>"
+    - name: BlockquoteCaptionProps
+      kind: type
+    - name: BlockquoteColor
+      kind: type
+    - name: BlockquoteFigure
+      kind: component
+      typeText: "ForwardRefExoticComponent<BlockquoteFigureProps & RefAttributes<HTMLElement>>"
+    - name: BlockquoteFigureProps
+      kind: type
+    - name: BlockquoteProps
+      kind: type
+    - name: BlockquoteSize
+      kind: type
+    - name: blockquoteVariants
+      kind: variants
+      typeText: "(props?: (ConfigVariants<{ size: { sm: string; md: string; lg: string; xl: string; }; color: { primary: string; neutral: string; }; }> & ClassProp) | undefined) => string"
+  primaryExport: Blockquote
+  subcomponents:
+    - BlockquoteCaption
+    - BlockquoteFigure
+  props:
+    Blockquote:
+      - name: color
+        type: "\"neutral\" | \"primary\""
+        required: false
+        declaredIn: self
+        variantKey: true
+      - name: size
+        type: "\"lg\" | \"md\" | \"sm\" | \"xl\""
+        required: false
+        declaredIn: self
+        variantKey: true
+  extendsProps:
+    - "Omit<React.BlockquoteHTMLAttributes<HTMLQuoteElement>, \"color\">"
+    - "VariantProps<typeof blockquoteVariants>"
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+        - xl
+      default: md
+      on: Blockquote
+    color:
+      kind: enum
+      options:
+        - primary
+        - neutral
+      default: primary
+      on: Blockquote
+  variantSource: cva
+  compoundVariants: []
+  sizeMaps: []
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - class-variance-authority
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-blockquote--default
+    - exportName: WithCaption
+      id: components-blockquote--with-caption
+  storybookTitle: Components/Blockquote
+  docsId: components-blockquote--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: c13962b650ce
+  factsHash: "6d095004c0a7"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A block-level extended quotation, with an optional figure/caption pairing for attribution."
+useWhen:
+  - "quoting a longer passage as its own block, especially editorial or testimonial content"
+  - "attributing the quote to a source (pair with BlockquoteFigure and BlockquoteCaption)"
+useInstead:
+  - id: quote
+    when: "the quotation is short and sits inline within a sentence, not as its own block"
+  - id: text
+    when: "the content is not actually a quotation - Text carries no semantic blockquote meaning"
+related:
+  - quote
+  - text
+a11y:
+  notes:
+    - "Renders a real <blockquote> element, so assistive tech recognizes it as a quotation without extra ARIA."
+    - "BlockquoteCaption renders <figcaption>, which is only valid HTML as a child of a <figure> - always wrap Blockquote and BlockquoteCaption in BlockquoteFigure when using a caption, never render BlockquoteCaption on its own."
+  radixHandles: false
+pitfalls:
+  - "BlockquoteCaption is invalid HTML outside a <figure> - use BlockquoteFigure as the wrapper any time a caption is present, not a plain div."
+  - "color's neutral/primary options only tint the left border accent - they say nothing about the quote's semantic importance and do not affect the text color itself."
+  - "size=\"xl\" does not follow the same t-body-* type token as sm/md/lg - it is a one-off text-xl override for hero or editorial quotes, so it will not track a future change to the t-body-lg token the way the other three sizes will."
+canonicalSnippet: |
+  import { Blockquote, BlockquoteCaption, BlockquoteFigure } from "@adres/mgda-ui"
+
+  <BlockquoteFigure>
+    <Blockquote size="lg">
+      Great design is as little design as possible.
+    </Blockquote>
+    <BlockquoteCaption>Dieter Rams</BlockquoteCaption>
+  </BlockquoteFigure>
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: c13962b650ce
+---
+
+## Usage
+
+`Blockquote` renders a real `<blockquote>` for a longer, standalone quotation
+- editorial pull-quotes, testimonials, cited passages. For a short quotation
+that sits inline within a sentence, reach for `Quote` instead; for content
+that is not actually a quotation, reach for `Text`.
+
+`color` only tints the left border accent (`primary` or `neutral`); it does
+not change the quote's text color or imply semantic importance. `size` scales
+the body type, with `xl` as a one-off larger override for hero or editorial
+use rather than following the normal `t-body-*` ramp the other three sizes
+use.
+
+Pair with `BlockquoteFigure` and `BlockquoteCaption` for attribution - the
+caption renders `<figcaption>`, which is only valid HTML inside a `<figure>`.
+
+## Anatomy
+
+| Part | Role |
+| --- | --- |
+| `Blockquote` | The quotation itself. Renders `<blockquote>`. |
+| `BlockquoteFigure` | Structural `<figure>` wrapper, required around `Blockquote` and `BlockquoteCaption` whenever a caption is used. |
+| `BlockquoteCaption` | The attribution. Renders `<figcaption>` - invalid HTML outside a `<figure>`. |

package/knowledge/box-list.md

@@ -0,0 +1,177 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: box-list
+  sourceFile: packages/design-system/src/components/box-list.tsx
+  client: false
+  category: web-app-layout-navigation
+  categoryFromBarrel: web-app-layout-navigation
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: BoxList
+      kind: component
+      typeText: "({ items, columns, size, textSize, vertical, bullet, check, numerical, muted, className, ...props }: BoxListProps) => Element"
+    - name: BoxListItem
+      kind: type
+    - name: BoxListProps
+      kind: type
+    - name: BoxListSize
+      kind: type
+  primaryExport: BoxList
+  subcomponents: []
+  props:
+    BoxList:
+      - name: bullet
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Show a leading bullet dot before each item's title."
+      - name: check
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Show a leading Check icon before each item's title - for \"included\" / affirmative sets. Takes precedence over `bullet` when both are set."
+      - name: columns
+        type: "1 | 2 | 3 | 4"
+        required: false
+        declaredIn: self
+        doc: "Columns at desktop (1-4). Default 3. Ignored when `vertical`."
+      - name: items
+        type: "BoxListItem[]"
+        required: true
+        declaredIn: self
+      - name: muted
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Sit each item on the muted surface (`bg-muted`) instead of the default card surface - a softer, lower-contrast fill for secondary lists."
+      - name: numerical
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Show a two-digit ordinal (01, 02, ...) as a t-overline eyebrow above each item. Takes precedence over `check` and `bullet` when several are set."
+      - name: size
+        type: BoxListSize
+        required: false
+        declaredIn: self
+        doc: "Box padding. Default \"lg\"."
+      - name: textSize
+        type: BoxListSize
+        required: false
+        declaredIn: self
+        doc: "Type scale for the title + description. Default \"md\"."
+      - name: vertical
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Stack items in a single vertical column instead of a grid. Overrides `columns`."
+  extendsProps:
+    - "React.HTMLAttributes<HTMLDivElement>"
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+      default: lg
+      on: BoxList
+    textSize:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+      default: md
+      on: BoxList
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps:
+    - COLUMNS
+    - SIZE
+    - TEXT
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - lucide-react
+      - react
+  contexts: []
+  stories:
+    - exportName: Default
+      id: components-boxlist--default
+    - exportName: WithChecks
+      id: components-boxlist--with-checks
+  storybookTitle: Components/BoxList
+  docsId: components-boxlist--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: da6243592924
+  factsHash: "961259e83400"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A responsive grid of bordered box cards, each a title with an optional supporting line - features, services, terms, or options."
+useWhen:
+  - "presenting a set of features, services, terms, or options as bordered cards without hand-rolling the card + grid each time"
+  - "an affirmative \"what's included\" list (turn on check) or an ordered sequence (turn on numerical)"
+useInstead:
+  - id: bullet-list
+    when: "the items are a short prose-adjacent list with no need for a bordered box or grid"
+  - id: cards-nav
+    when: "each box should actually navigate somewhere - BoxList items are static, not links"
+  - id: feature-grid
+    when: "each item needs its own icon plus richer marketing copy, not just a title/description pair"
+related:
+  - bullet-list
+  - feature-grid
+composesWith: []
+tokens:
+  - "--card"
+  - "--muted"
+  - "--foreground"
+  - "--foreground-strong"
+  - "--muted-foreground"
+  - "--primary"
+a11y:
+  notes:
+    - "BoxList is a server component (no \"use client\") - it renders plain divs with no interactivity, so it drops into a server component tree with no extra opt-in."
+    - "check and numerical icons/ordinals are decorative and rendered without their own accessible name; the item's title or description is what a screen reader announces."
+  requiredProps:
+    - "each item needs at least title or description - both may be set, but at least one carries the visible content"
+  keyboard: []
+  radixHandles: false
+pitfalls:
+  - "marker precedence is numerical, then check, then bullet - setting more than one only shows the highest-precedence marker, the others are silently ignored, not stacked."
+  - "vertical overrides columns entirely - setting both stacks items in one column regardless of the columns value, since vertical switches the container from grid to flex-col."
+  - "an item with only description (no title) renders that text at the title type scale, not the description scale - BoxList treats the first present field as the item's headline."
+canonicalSnippet: |
+  import { BoxList, type BoxListItem } from "@adres/mgda-ui"
+
+  const items: BoxListItem[] = [
+    { title: "Unlimited projects", description: "No caps on workspaces or seats." },
+    { title: "Priority support", description: "Same-day response on business plans." },
+    { title: "Custom domains", description: "Point your own domain at any project." },
+  ]
+
+  <BoxList items={items} check columns={3} />
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: da6243592924
+---
+
+## Usage
+
+BoxList turns a flat array of `{ title, description }` pairs into a
+responsive grid of bordered cards, so a features/services/terms section
+doesn't need its own hand-rolled grid + card markup. `vertical` collapses it
+to a single column regardless of `columns`, useful on narrow layouts or when
+the content itself reads better stacked.
+
+Choose at most one marker style: `numerical` (a "01, 02, ..." eyebrow, for
+ordered sequences), `check` (an affirmative "included" icon), or `bullet` (a
+plain dot for an unordered set). They take precedence in that order - setting
+more than one shows only the highest-precedence marker.

package/knowledge/bullet-list.md

@@ -0,0 +1,128 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: bullet-list
+  sourceFile: packages/design-system/src/components/bullet-list.tsx
+  client: true
+  category: web-app-layout-navigation
+  categoryFromBarrel: web-app-layout-navigation
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: BulletList
+      kind: component
+      typeText: "ForwardRefExoticComponent<BulletListProps & RefAttributes<HTMLUListElement>>"
+    - name: BulletListItem
+      kind: component
+      typeText: "ForwardRefExoticComponent<BulletListItemProps & RefAttributes<HTMLLIElement>>"
+    - name: BulletListItemProps
+      kind: type
+    - name: BulletListProps
+      kind: type
+    - name: BulletListSize
+      kind: type
+  primaryExport: BulletList
+  subcomponents:
+    - BulletListItem
+  props:
+    BulletList:
+      - name: size
+        type: BulletListSize
+        required: false
+        declaredIn: self
+  extendsProps:
+    - "React.HTMLAttributes<HTMLUListElement>"
+  variants:
+    size:
+      kind: enum
+      options:
+        - sm
+        - md
+        - lg
+      default: md
+      on: BulletList
+  variantSource: prop-union
+  compoundVariants: []
+  sizeMaps:
+    - BULLET_CLASS
+    - LIST_GAP_CLASS
+    - ROW_GAP_CLASS
+    - TEXT_CLASS
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - react
+  contexts:
+    - name: BulletListContext
+      type: BulletListContextValue
+      default: null
+  stories:
+    - exportName: Default
+      id: components-bulletlist--default
+  storybookTitle: Components/BulletList
+  docsId: components-bulletlist--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: "96c5ce6fa5fb"
+  factsHash: "5b52ebd7a9e8"
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A bulleted list of short related items - goals, features, qualities - with body-text rhythm and a small dot marker."
+useWhen:
+  - "a short unordered list of related items (features, benefits, requirements) where the surrounding heading already sets the context"
+  - "prose-adjacent content that should read as body text with bullets, not a card or box grid"
+useInstead:
+  - id: box-list
+    when: "each item deserves its own bordered box, a title + description pair, or a grid layout"
+  - id: data-list
+    when: "each row is a label/value pair rather than a single line of text"
+related:
+  - box-list
+composesWith: []
+tokens:
+  - "--foreground"
+  - "--foreground-strong"
+a11y:
+  notes:
+    - "Renders a real <ul>/<li> pair, so list semantics (list role, item count) are announced by screen readers with no extra markup."
+    - "The bullet dot is aria-hidden - the accessible content of each row is exactly the children text, not a rendered \"•\"."
+  requiredProps: []
+  keyboard: []
+  radixHandles: false
+pitfalls:
+  - "size only changes text scale, bullet diameter, and spacing - it does not add or remove structure, so mixing sizes across BulletLists on the same page is a purely visual choice with no other effect."
+  - "BulletListItem takes plain children, not a title/description pair - reach for BoxList when an item needs two lines."
+canonicalSnippet: |
+  import { BulletList, BulletListItem } from "@adres/mgda-ui"
+
+  <BulletList size="md">
+    <BulletListItem>Works across every brand theme</BulletListItem>
+    <BulletListItem>WCAG 2.1 AA accessible by default</BulletListItem>
+    <BulletListItem>No hardcoded colors anywhere in the component tree</BulletListItem>
+  </BulletList>
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: "96c5ce6fa5fb"
+---
+
+## Usage
+
+BulletList is a plain content list, not a navigation control - despite living
+in the `Layout & Navigation` barrel section alongside `Sidebar`/`ListNav`, it
+renders no links and carries no active/selected state. Reach for it when
+prose calls for a short bulleted list (a feature set, a set of qualities) and
+the default browser bullet doesn't match the type system.
+
+`size` cascades from `BulletList` to every `BulletListItem` via context,
+scaling text, bullet diameter, and row/list spacing together so the three
+stay proportional.
+
+## Anatomy
+
+- **BulletList** - the `<ul>` wrapper; sets `size` for its items via context.
+- **BulletListItem** - one `<li>`: a small foreground-strong dot marker
+  followed by plain children.

package/knowledge/button-group.md

@@ -0,0 +1,179 @@
+---
+# >>> DERIVED - regenerated by `npm run knowledge:sync`. Do not edit. <<<
+derived:
+  schemaVersion: 1
+  id: button-group
+  sourceFile: packages/design-system/src/components/button-group.tsx
+  client: true
+  category: web-app-core-primitives
+  categoryFromBarrel: web-app-core-primitives
+  barrelExported: true
+  importPath: "@adres/mgda-ui"
+  exports:
+    - name: ButtonGroup
+      kind: component
+      typeText: "ForwardRefExoticComponent<ButtonGroupProps & RefAttributes<HTMLDivElement>>"
+    - name: ButtonGroupItem
+      kind: component
+      typeText: "ForwardRefExoticComponent<ButtonGroupItemProps & RefAttributes<HTMLButtonElement>>"
+    - name: ButtonGroupItemProps
+      kind: type
+    - name: ButtonGroupProps
+      kind: type
+    - name: ButtonGroupSelected
+      kind: type
+    - name: ButtonGroupSize
+      kind: type
+    - name: ButtonGroupVariant
+      kind: type
+  primaryExport: ButtonGroup
+  subcomponents:
+    - ButtonGroupItem
+  props:
+    ButtonGroup:
+      - name: selected
+        type: ButtonGroupSelected
+        required: false
+        declaredIn: self
+        doc: "How an `active` item stands out (only relevant when variant=\"outline\"). `primary` - strong, brand-coloured active cell (view toggle). `muted` - quiet, neutral-grey active cell (filter group)."
+      - name: size
+        type: ButtonGroupSize
+        required: false
+        declaredIn: self
+        doc: "Item height + type metrics - mirrors Button at the same size."
+      - name: variant
+        type: ButtonGroupVariant
+        required: false
+        declaredIn: self
+        doc: "Visual mode. `outline` = bordered container with transparent items; `primary` = solid primary surface across all items (split-button look)."
+        variantKey: true
+    ButtonGroupItem:
+      - name: active
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Marks this item as the currently-selected cell (sets aria-pressed)."
+      - name: compact
+        type: boolean
+        required: false
+        declaredIn: self
+        doc: "Reduces horizontal padding - use for chevron/icon-only trailing buttons (the dropdown side of a split button)."
+  extendsProps:
+    - "React.HTMLAttributes<HTMLDivElement>"
+  variants:
+    variant:
+      kind: enum
+      options:
+        - outline
+        - primary
+      default: outline
+      on: ButtonGroup
+  variantSource: cva
+  compoundVariants: []
+  sizeMaps:
+    - PADDING
+  dataSlots: []
+  dependsOn:
+    internal: []
+    lib:
+      - cn
+    hooks: []
+    external:
+      - class-variance-authority
+      - react
+  contexts:
+    - name: ButtonGroupContext
+      type: ButtonGroupContextValue
+      default: null
+  stories:
+    - exportName: Default
+      id: components-buttongroup--default
+    - exportName: Primary
+      id: components-buttongroup--primary
+  storybookTitle: Components/ButtonGroup
+  docsId: components-buttongroup--documentation
+  argTypeOptions: {}
+  resolvedCleanly: true
+  contractHash: d6be2b861c20
+  factsHash: caf30b2341f3
+# >>> AUTHORED - humans own everything below this line. <<<
+status: stable
+summary: "A row of connected buttons sharing one container - view toggles, filter groups, toolbars, split-action buttons."
+useWhen:
+  - "several related actions or view options should read as one connected control, not separate buttons"
+  - "building a split-action button - a primary action plus a compact chevron or menu trigger"
+useInstead:
+  - id: tabs
+    when: "the row switches between content panels, not just visual buttons"
+  - id: segmented-control
+    when: "it is a single-selection view-mode switch that needs a sliding indicator"
+  - id: button
+    when: "the actions are unrelated and do not need to read as one connected group"
+related:
+  - button
+  - segmented-control
+tokens:
+  - "--primary-weaker"
+  - "--primary-weak"
+  - "--primary-strong"
+  - "--primary-foreground"
+  - "--border"
+  - "--muted"
+  - "--selected"
+  - "--foreground"
+  - "--background"
+  - "--ring"
+a11y:
+  notes:
+    - "The root carries role=\"group\", a visual grouping only - each ButtonGroupItem's own semantics (a real button, aria-pressed) are what a screen reader actually announces."
+    - "active sets aria-pressed, which only communicates a toggle-button state - if the group is really a single-select control, consider whether Tabs or SegmentedControl's stronger semantics fit better before reaching for ButtonGroup."
+  requiredProps:
+    - "None strictly, but every ButtonGroupItem should carry an accessible name (text or aria-label), the same as a bare Button."
+  keyboard:
+    - "Each ButtonGroupItem is a native button, so Tab moves between items individually - there is no arrow-key roving tabindex like a real radiogroup or tablist would provide."
+  radixHandles: false
+pitfalls:
+  - "variant, size, and selected only exist on ButtonGroup - they flow to items through ButtonGroupContext, so setting them on a ButtonGroupItem directly does nothing."
+  - "selected is ignored entirely when variant=\"primary\" - it only changes anything in outline mode, the same pattern as Button's elevated only affecting specific variants."
+  - "There is no roving-tabindex or arrow-key navigation between items, unlike a native radiogroup or Tabs - do not present ButtonGroup as a fully accessible single-select control without adding that keyboard handling yourself if it matters for the use case."
+canonicalSnippet: |
+  import { ButtonGroup, ButtonGroupItem } from "@adres/mgda-ui"
+
+  <ButtonGroup selected="muted">
+    <ButtonGroupItem active>List</ButtonGroupItem>
+    <ButtonGroupItem>Grid</ButtonGroupItem>
+  </ButtonGroup>
+reviewedAt: 2026-08-31
+reviewedAgainstContractHash: d6be2b861c20
+---
+
+## Usage
+
+`ButtonGroup` connects a row of buttons into one visual container - view
+toggles, filter chips, toolbars, and split-action buttons (a primary action
+plus a compact chevron or menu trigger). It is not a replacement for `Tabs`
+(which switches between content panels) or `SegmentedControl` (a single-select
+switch with a sliding indicator) - reach for those when the row's job is
+navigation or exclusive selection rather than a set of related actions.
+
+`variant="outline"` (default) draws a bordered container with transparent
+items and dividers between them. `variant="primary"` fills every item with the
+primary surface for a solid split-button look; in that mode `selected` has no
+effect, since every cell already reads as active.
+
+In outline mode, `selected` controls how an `active` item stands out:
+`primary` (default) for a strong, brand-coloured active cell, the right choice
+for a view toggle, and `muted` for a quiet, neutral active cell, better suited
+to a filter group where the active filter should not look like the primary
+action.
+
+## Anatomy
+
+| Part | Role |
+| --- | --- |
+| `ButtonGroup` | The container. Owns `size`, `variant`, and `selected`, and shares them with every item through context. Sets `role="group"`. |
+| `ButtonGroupItem` | A native `button`. Reads its visual state from context plus its own `active`/`compact` props - `active` sets `aria-pressed` and picks the selected styling; `compact` tightens padding for an icon/chevron-only cell. |
+
+`ButtonGroupContext` is why `size`/`variant`/`selected` only need to be set
+once, on the root - passing them to an individual `ButtonGroupItem` has no
+effect.