@atom63/cli 0.1.0-beta.2 → 0.1.0-beta.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -3438,15 +3438,18 @@
3438
3438
  "accordionIconVariants",
3439
3439
  "accordionPattern",
3440
3440
  "accordionSlots",
3441
+ "accordionStateAliases",
3441
3442
  "accordionStates",
3442
3443
  "accordionVisualArchetypes",
3443
3444
  "alertContract",
3444
3445
  "alertDialogContract",
3445
3446
  "alertDialogFooterVariants",
3446
3447
  "alertDialogPattern",
3448
+ "alertDialogSizeAliases",
3447
3449
  "alertDialogSizes",
3448
3450
  "alertDialogSlots",
3449
3451
  "alertDialogStates",
3452
+ "alertDialogVariantAliases",
3450
3453
  "alertDialogVariants",
3451
3454
  "alertDialogVisualArchetypes",
3452
3455
  "alertSlots",
@@ -3470,6 +3473,7 @@
3470
3473
  "appViewTopBarSpans",
3471
3474
  "appViewVisualArchetypes",
3472
3475
  "autocompleteContract",
3476
+ "autocompleteSizeAliases",
3473
3477
  "autocompleteSizes",
3474
3478
  "autocompleteSlots",
3475
3479
  "autocompleteStates",
@@ -3478,6 +3482,7 @@
3478
3482
  "avatarContract",
3479
3483
  "avatarRings",
3480
3484
  "avatarShapes",
3485
+ "avatarSizeAliases",
3481
3486
  "avatarSizes",
3482
3487
  "avatarSlots",
3483
3488
  "avatarStates",
@@ -3489,6 +3494,7 @@
3489
3494
  "badgeSizes",
3490
3495
  "badgeSlots",
3491
3496
  "badgeSolidVariants",
3497
+ "badgeStateAliases",
3492
3498
  "badgeStates",
3493
3499
  "badgeVariants",
3494
3500
  "badgeVisualArchetypes",
@@ -3496,11 +3502,13 @@
3496
3502
  "breadcrumbCompositions",
3497
3503
  "breadcrumbContract",
3498
3504
  "breadcrumbSlots",
3505
+ "breadcrumbStateAliases",
3499
3506
  "breadcrumbStates",
3500
3507
  "breadcrumbVisualArchetypes",
3501
3508
  "buttonContract",
3502
3509
  "buttonGroupContract",
3503
3510
  "buttonGroupOrientations",
3511
+ "buttonGroupSizeAliases",
3504
3512
  "buttonGroupSizes",
3505
3513
  "buttonGroupSlots",
3506
3514
  "buttonGroupStates",
@@ -3508,6 +3516,7 @@
3508
3516
  "buttonShapes",
3509
3517
  "buttonSizes",
3510
3518
  "buttonSlots",
3519
+ "buttonStateAliases",
3511
3520
  "buttonStates",
3512
3521
  "buttonTokenSlots",
3513
3522
  "buttonTones",
@@ -3599,6 +3608,7 @@
3599
3608
  "dialogFooterVariants",
3600
3609
  "dialogMobilePlacements",
3601
3610
  "dialogModalPattern",
3611
+ "dialogSizeAliases",
3602
3612
  "dialogSizes",
3603
3613
  "dialogSlots",
3604
3614
  "dialogStates",
@@ -3623,6 +3633,7 @@
3623
3633
  "feedbackStateKinds",
3624
3634
  "feedbackStateSizes",
3625
3635
  "feedbackStateSlots",
3636
+ "feedbackStateStateAliases",
3626
3637
  "feedbackStateStates",
3627
3638
  "feedbackStateVisualArchetypes",
3628
3639
  "fieldContract",
@@ -3634,6 +3645,7 @@
3634
3645
  "fonts",
3635
3646
  "formContract",
3636
3647
  "formSlots",
3648
+ "formStateAliases",
3637
3649
  "formStates",
3638
3650
  "formVisualArchetypes",
3639
3651
  "frameBorders",
@@ -3641,6 +3653,7 @@
3641
3653
  "framePanelSurfaces",
3642
3654
  "framePresets",
3643
3655
  "frameSlots",
3656
+ "frameStateAliases",
3644
3657
  "frameStates",
3645
3658
  "frameTrays",
3646
3659
  "frameVariants",
@@ -3659,6 +3672,7 @@
3659
3672
  "inputGroupVisualArchetypes",
3660
3673
  "inputOTPContract",
3661
3674
  "inputOTPSlots",
3675
+ "inputOTPStateAliases",
3662
3676
  "inputOTPStates",
3663
3677
  "inputOTPVisualArchetypes",
3664
3678
  "inputSizes",
@@ -3672,8 +3686,10 @@
3672
3686
  "itemGroupSurfaces",
3673
3687
  "itemGroupVariants",
3674
3688
  "itemMediaVariants",
3689
+ "itemSizeAliases",
3675
3690
  "itemSizes",
3676
3691
  "itemSlots",
3692
+ "itemStateAliases",
3677
3693
  "itemStates",
3678
3694
  "itemTones",
3679
3695
  "itemVariants",
@@ -3718,6 +3734,7 @@
3718
3734
  "modes",
3719
3735
  "navigationMenuContract",
3720
3736
  "navigationMenuSlots",
3737
+ "navigationMenuStateAliases",
3721
3738
  "navigationMenuStates",
3722
3739
  "navigationMenuVisualArchetypes",
3723
3740
  "osSystems",
@@ -3768,6 +3785,7 @@
3768
3785
  "resizableContract",
3769
3786
  "resizableOrientations",
3770
3787
  "resizableSlots",
3788
+ "resizableStateAliases",
3771
3789
  "resizableStates",
3772
3790
  "resizableVariants",
3773
3791
  "resizableVisualArchetypes",
@@ -3776,12 +3794,14 @@
3776
3794
  "scrollAreaOptions",
3777
3795
  "scrollAreaOrientations",
3778
3796
  "scrollAreaSlots",
3797
+ "scrollAreaStateAliases",
3779
3798
  "scrollAreaStates",
3780
3799
  "scrollAreaVisualArchetypes",
3781
3800
  "scrollableListContract",
3782
3801
  "scrollableListLayouts",
3783
3802
  "scrollableListOptions",
3784
3803
  "scrollableListSlots",
3804
+ "scrollableListStateAliases",
3785
3805
  "scrollableListStates",
3786
3806
  "scrollableListVisualArchetypes",
3787
3807
  "searchFieldContract",
@@ -3823,6 +3843,7 @@
3823
3843
  "sidebarMenuSubButtonSizes",
3824
3844
  "sidebarNavTreeContract",
3825
3845
  "sidebarNavTreeParts",
3846
+ "sidebarNavTreeStateAliases",
3826
3847
  "sidebarNavTreeStates",
3827
3848
  "sidebarNavTreeTones",
3828
3849
  "sidebarNavTreeVisualArchetypes",
@@ -3854,6 +3875,7 @@
3854
3875
  "switchStates",
3855
3876
  "switchVisualArchetypes",
3856
3877
  "tableContract",
3878
+ "tableSizeAliases",
3857
3879
  "tableSizes",
3858
3880
  "tableSlots",
3859
3881
  "tableStates",
@@ -3864,6 +3886,7 @@
3864
3886
  "tabsContract",
3865
3887
  "tabsOrientations",
3866
3888
  "tabsPattern",
3889
+ "tabsSizeAliases",
3867
3890
  "tabsSizes",
3868
3891
  "tabsSlots",
3869
3892
  "tabsStates",
@@ -3892,12 +3915,14 @@
3892
3915
  "toggleGroupOrientations",
3893
3916
  "toggleGroupSelectionModes",
3894
3917
  "toggleGroupSlots",
3918
+ "toggleGroupStateAliases",
3895
3919
  "toggleGroupStates",
3896
3920
  "toggleGroupTokenSlots",
3897
3921
  "toggleGroupVariants",
3898
3922
  "toggleGroupVisualArchetypes",
3899
3923
  "toggleSizes",
3900
3924
  "toggleSlots",
3925
+ "toggleStateAliases",
3901
3926
  "toggleStates",
3902
3927
  "toggleTokenSlots",
3903
3928
  "toggleTones",
@@ -4612,7 +4637,7 @@
4612
4637
  "StatCard": "One metric with a label and an optional change. `trend` colours the change: `up` and `down` use status colours, `neutral` stays muted.\n\n```tsx\n<StatCard change=\"+1 this quarter\" label=\"Themes\" trend=\"up\" value=\"4\" />\n```\n\nProps of `StatCard`:\n\n- `label`: `string` (required). Small muted caption above the value.\n- `value`: `ReactNode` (required). The prominent metric.\n- `change`: `ReactNode`. Optional secondary change indicator, colored by `trend`.\n- `className`: `string`\n- `trend`: `'neutral' | 'up' | 'down'` (default `'neutral'`). Semantic direction of `change`; drives the token color.",
4613
4638
  "StatGrid": "A responsive grid of `StatCard`s.\n\n```tsx\n<StatGrid>\n <StatCard label=\"Blocks\" value=\"30\" />\n <StatCard change=\"-5\" label=\"Open issues\" trend=\"down\" value=\"3\" />\n <StatCard label=\"Themes\" value=\"4\" />\n</StatGrid>\n```\n\nProps of `StatGrid`:\n\n- `children`: `ReactNode` (required)\n- `className`: `string`",
4614
4639
  "Steps": "Numbered steps for a procedure. Numbers and the connecting line come from document order; do not number titles by hand.\n\n```tsx\n<Steps>\n <Steps.Step title=\"Install the package\">Run pnpm add @atom63/mdx.</Steps.Step>\n <Steps.Step title=\"Load the styles\">Import @atom63/mdx/styles/a63.css once.</Steps.Step>\n <Steps.Step title=\"Wrap the page\">Render it inside MDXContentProvider.</Steps.Step>\n</Steps>\n```\n\nProps of `Steps`:\n\n- `children`: `ReactNode` (required)\n- `className`: `string`\n\nProps of `Steps.Step`:\n\n- `children`: `ReactNode` (required)\n- `title`: `ReactNode` (required). Bold heading for the step.\n- `className`: `string`\n- `index`: `number` (default `1`). Injected by `Steps` — the 1-indexed position in document order.",
4615
- "Tabs": "Tabbed panels in prose, such as the same step for npm and pnpm. It is the `Tabs` component of `@atom63/ui-react` with MDX spacing, and takes its props: `atom63 component tabs`.\n\n```tsx\n<Tabs defaultValue=\"pnpm\">\n <Tabs.List>\n <Tabs.Tab value=\"pnpm\">pnpm</Tabs.Tab>\n <Tabs.Tab value=\"npm\">npm</Tabs.Tab>\n </Tabs.List>\n <Tabs.Panel value=\"pnpm\">pnpm add @atom63/mdx</Tabs.Panel>\n <Tabs.Panel value=\"npm\">npm install @atom63/mdx</Tabs.Panel>\n</Tabs>\n```\n\n`Tabs` adds no props of its own.\n\nProps of `Tabs.List`:\n\n- `size`: `'sm' | 'default' | 'lg' | 'xs'` (default `tabsContract.defaultSize`)\n- `variant`: `'default' | 'underline' | 'attached'` (default `tabsContract.defaultVariant`)\n\nProps of `Tabs.Panel`:\n\n- `animated`: `boolean` (default `false`)\n\nProps of `Tabs.Tab`:\n\n- `size`: `'sm' | 'default' | 'lg' | 'xs'`",
4640
+ "Tabs": "Tabbed panels in prose, such as the same step for npm and pnpm. It is the `Tabs` component of `@atom63/ui-react` with MDX spacing, and takes its props: `atom63 component tabs`.\n\n```tsx\n<Tabs defaultValue=\"pnpm\">\n <Tabs.List>\n <Tabs.Tab value=\"pnpm\">pnpm</Tabs.Tab>\n <Tabs.Tab value=\"npm\">npm</Tabs.Tab>\n </Tabs.List>\n <Tabs.Panel value=\"pnpm\">pnpm add @atom63/mdx</Tabs.Panel>\n <Tabs.Panel value=\"npm\">npm install @atom63/mdx</Tabs.Panel>\n</Tabs>\n```\n\n`Tabs` adds no props of its own.\n\nProps of `Tabs.List`:\n\n- `size`: `'sm' | 'default' | 'lg' | 'xs' | 'md'` (default `tabsContract.defaultSize`). `'default'` is a deprecated alias of `'md'`.\n- `variant`: `'default' | 'underline' | 'attached'` (default `tabsContract.defaultVariant`)\n\nProps of `Tabs.Panel`:\n\n- `animated`: `boolean` (default `false`)\n\nProps of `Tabs.Tab`:\n\n- `size`: `'sm' | 'default' | 'lg' | 'xs' | 'md'`. `'default'` is a deprecated alias of `'md'`.",
4616
4641
  "Timeline": "Dated events in order: a release history, a project log. Each item has a date, a title and a short body.\n\n```tsx\n<Timeline>\n <Timeline.Item date=\"2025\" title=\"Primitive layer\">Colour ramps, type scale, spacing.</Timeline.Item>\n <Timeline.Item date=\"2026\" title=\"Semantic layer\">Tokens map primitives to intent.</Timeline.Item>\n</Timeline>\n```\n\nProps of `Timeline`:\n\n- `children`: `ReactNode` (required)\n- `className`: `string`\n\nProps of `Timeline.Item`:\n\n- `children`: `ReactNode` (required)\n- `date`: `ReactNode` (required). Date or label shown in the left column (e.g. a year).\n- `title`: `ReactNode` (required). Bold heading for the event.\n- `className`: `string`",
4617
4642
  "VideoBlock": "A video figure with native controls and an optional caption. A video with speech needs a caption track (`trackSrc`); mark a purely visual loop `captionPolicy=\"decorative\"` instead. With `autoPlay` and no `controls`, it draws its own pause button and stays still under reduced motion.\n\n```mdx\n<VideoBlock src=\"/media/talk.mp4\" title=\"Design tokens talk\" trackSrc=\"/media/talk.en.vtt\" />\n\n<VideoBlock\n autoPlay\n captionPolicy=\"decorative\"\n controls={false}\n loop\n muted\n src=\"/media/loop.mp4\"\n title=\"Theme switching loop\"\n/>\n```\n\nProps of `VideoBlock`:\n\n- `src`: `string` (required)\n- `title`: `string` (required)\n- `autoPlay`: `boolean` (default `false`). Start playing, muted, on load. Ignored when the reader prefers reduced motion. Without `controls`, a pause and play toggle sits over the video.\n- `caption`: `string`\n- `captionPolicy`: `'required' | 'decorative'`. Video has spoken or meaningful audio and must provide captions. Video is decorative or purely visual; no caption track is required.\n- `className`: `string`\n- `controls`: `boolean` (default `true`)\n- `fit`: `'contain' | 'cover'` (default `'contain'`)\n- `loop`: `boolean` (default `false`)\n- `muted`: `boolean` (default `false`)\n- `pauseLabel`: `string` (default `'Pause video'`). Name of the toggle while the video plays. Defaults to \"Pause video\".\n- `playLabel`: `string` (default `'Play video'`). Name of the toggle while the video is paused. Defaults to \"Play video\".\n- `showCaption`: `boolean` (default `false`)\n- `spacing`: `'none' | 'sm' | 'default' | 'lg'` (default `'default'`)\n- `trackLabel`: `string`. Name of the caption track in the player's caption menu. Defaults to the track language's own name, such as \"English\" or \"Deutsch\".\n- `trackLang`: `string` (default `'en'`). BCP 47 language of the caption track (`srclang`). Defaults to `en`.\n- `trackSrc`: `string`"
4618
4643
  }
@@ -4933,7 +4958,7 @@
4933
4958
  "rest": "Resting appearance.",
4934
4959
  "hover": "Pointer over an enabled button.",
4935
4960
  "pressed": "While pressed, or held with data-pressed.",
4936
- "focusVisible": "Keyboard focus only; drawn as an outline.",
4961
+ "focus-visible": "Keyboard focus only; drawn as an outline.",
4937
4962
  "disabled": "A neutral grey fill and muted label; ghost, link, overlay and glass fade only the label.",
4938
4963
  "loading": "Label keeps its width; the spinner overlays it."
4939
4964
  }
@@ -5032,18 +5057,20 @@
5032
5057
  },
5033
5058
  "exportName": "buttonContract",
5034
5059
  "slots": [
5035
- "root",
5036
- "label",
5037
- "icon",
5038
- "spinner",
5039
- "indicator"
5060
+ "button",
5061
+ "button-label",
5062
+ "button-spinner",
5063
+ "button-indicator"
5040
5064
  ],
5041
5065
  "source": "packages/ui-foundation/contracts/components/button.json",
5066
+ "stateAliases": {
5067
+ "focusVisible": "focus-visible"
5068
+ },
5042
5069
  "states": [
5043
5070
  "rest",
5044
5071
  "hover",
5045
5072
  "pressed",
5046
- "focusVisible",
5073
+ "focus-visible",
5047
5074
  "disabled",
5048
5075
  "loading"
5049
5076
  ],
@@ -5081,7 +5108,7 @@
5081
5108
  ],
5082
5109
  "importPath": "@atom63/ui-react",
5083
5110
  "label": "Button",
5084
- "markdown": "# Button\n\nButton is the shared action primitive and defaults to safe non-submit behavior.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Use it for an in-place action such as submitting, saving, confirming or changing state; use a link when the outcome is navigation. Choose emphasis from the action hierarchy rather than making every action primary, and give icon-only buttons an accessible name. Draw secondary actions in toolbars, rows and card headers as variant=\"ghost\" with tone=\"muted\". shape=\"round\" makes icon buttons circles (a play button) and labelled buttons pills.\n- Keep the semantic action or link element intact when composing custom content.\n- Make loading, disabled, and destructive behavior explicit in the product flow.\n\n## Variants, sizes and states\n\n| Axis | Value | Guidance |\n| --- | --- | --- |\n| Variant | `primary` | The one primary action per view, when the product's main action is in its brand colour. |\n| Variant | `default` | Neutral solid: high emphasis without the brand colour (a white play button on dark, a black Pay button). |\n| Variant | `secondary` | Muted neutral action for supporting tasks. |\n| Variant | `raised` | Light fill, soft shadow, no border; with shape=\"round\", the floating button over a map or a light photo. |\n| Variant | `outline` | Lower-emphasis alternative (Duplicate). |\n| Variant | `dashed` | Add or filter affordance drawn as a dashed pill (+ Status). |\n| Variant | `ghost` | Lowest emphasis; toolbars and dismissals, with tone=\"muted\" for quiet secondary actions. |\n| Variant | `link` | Inline action styled as text; navigation should use a real link. |\n| Variant | `destructive` | Only when the outcome destroys data. |\n| Variant | `destructive-outline` | Quieter destructive action, beside a safe default. |\n| Variant | `overlay` | Forced contrast over media and imagery; the floating button over dark media. |\n| Variant | `glass` | Compatibility alias of overlay; new work uses overlay. |\n| Size | `xs` | Dense UI. |\n| Size | `sm` | Compact rows and toolbars. |\n| Size | `md` | Default. |\n| Size | `lg` | Prominent calls to action. |\n| Size | `xl` | Hero and marketing surfaces. |\n| State | `rest` | Resting appearance. |\n| State | `hover` | Pointer over an enabled button. |\n| State | `pressed` | While pressed, or held with data-pressed. |\n| State | `focusVisible` | Keyboard focus only; drawn as an outline. |\n| State | `disabled` | A neutral grey fill and muted label; ghost, link, overlay and glass fade only the label. |\n| State | `loading` | Label keeps its width; the spinner overlays it. |\n\n## Usage\n\n```tsx\nimport { Button } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Button`\n\n**Types:** `ButtonProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/button.json` (`buttonContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `shapes` | `default`, `round` | `default` |\n| `tones` | `neutral`, `muted` | `neutral` |\n| `variants` | `default`, `primary`, `secondary`, `raised`, `destructive`, `destructive-outline`, `outline`, `dashed`, `ghost`, `link`, `overlay`, `glass` | `default` |\n| `sizes` | `xs`, `sm`, `md`, `lg`, `xl`, `tile`, `icon-xs`, `icon-sm`, `icon`, `icon-lg`, `icon-xl` | `md` |\n\n**Slots:** `root`, `label`, `icon`, `spinner`, `indicator`\n\n**States:** `rest`, `hover`, `pressed`, `focusVisible`, `disabled`, `loading`\n\n**Token slots:** `button.background`, `button.foreground`, `button.border.color`, `button.border.width`, `button.radius`, `button.shadow`, `button.focusRing`, `button.height`, `button.paddingInline`, `button.gap`, `button.iconSize`, `button.motion.press`\n\n**Visual archetype:** Action controls — Momentary controls that perform an action now.\n\n### Web and iOS\n\nTrigger a user-initiated action with explicit hierarchy and feedback. Rendered by `AtomButton` in SwiftUI, with `recipe` parity.\n\n**Required states:** `rest`, `pressed`, `disabled`, `loading`\n\n**Shared outcomes:**\n\n- Action fires once\n- Loading blocks repeat activation\n- Disabled prevents activation\n\n**Accessibility outcomes:**\n\n- Exposes label\n- Announces loading\n- Disabled while loading\n\n**Platform adaptations:**\n\n- React: Uses HTML button semantics with pointer and focus-visible feedback.\n- SwiftUI: Uses SwiftUI Button with native touch and keyboard activation.\n- SwiftUI: The round shape is a capsule: a circle at the icon size, a pill with a label.\n- SwiftUI: The raised emphasis uses the panel fill and a soft shadow with no border; muted tone only quiets ghost labels.\n\n## Related components\n\n- [Button Group](/components/component-button-group)\n- [Toggle](/components/component-toggle)\n- [Copy Button](/components/component-copy-button)\n",
5111
+ "markdown": "# Button\n\nButton is the shared action primitive and defaults to safe non-submit behavior.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Use it for an in-place action such as submitting, saving, confirming or changing state; use a link when the outcome is navigation. Choose emphasis from the action hierarchy rather than making every action primary, and give icon-only buttons an accessible name. Draw secondary actions in toolbars, rows and card headers as variant=\"ghost\" with tone=\"muted\". shape=\"round\" makes icon buttons circles (a play button) and labelled buttons pills.\n- Keep the semantic action or link element intact when composing custom content.\n- Make loading, disabled, and destructive behavior explicit in the product flow.\n\n## Variants, sizes and states\n\n| Axis | Value | Guidance |\n| --- | --- | --- |\n| Variant | `primary` | The one primary action per view, when the product's main action is in its brand colour. |\n| Variant | `default` | Neutral solid: high emphasis without the brand colour (a white play button on dark, a black Pay button). |\n| Variant | `secondary` | Muted neutral action for supporting tasks. |\n| Variant | `raised` | Light fill, soft shadow, no border; with shape=\"round\", the floating button over a map or a light photo. |\n| Variant | `outline` | Lower-emphasis alternative (Duplicate). |\n| Variant | `dashed` | Add or filter affordance drawn as a dashed pill (+ Status). |\n| Variant | `ghost` | Lowest emphasis; toolbars and dismissals, with tone=\"muted\" for quiet secondary actions. |\n| Variant | `link` | Inline action styled as text; navigation should use a real link. |\n| Variant | `destructive` | Only when the outcome destroys data. |\n| Variant | `destructive-outline` | Quieter destructive action, beside a safe default. |\n| Variant | `overlay` | Forced contrast over media and imagery; the floating button over dark media. |\n| Variant | `glass` | Compatibility alias of overlay; new work uses overlay. |\n| Size | `xs` | Dense UI. |\n| Size | `sm` | Compact rows and toolbars. |\n| Size | `md` | Default. |\n| Size | `lg` | Prominent calls to action. |\n| Size | `xl` | Hero and marketing surfaces. |\n| State | `rest` | Resting appearance. |\n| State | `hover` | Pointer over an enabled button. |\n| State | `pressed` | While pressed, or held with data-pressed. |\n| State | `focus-visible` | Keyboard focus only; drawn as an outline. |\n| State | `disabled` | A neutral grey fill and muted label; ghost, link, overlay and glass fade only the label. |\n| State | `loading` | Label keeps its width; the spinner overlays it. |\n\n## Usage\n\n```tsx\nimport { Button } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Button`\n\n**Types:** `ButtonProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/button.json` (`buttonContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `shapes` | `default`, `round` | `default` |\n| `tones` | `neutral`, `muted` | `neutral` |\n| `variants` | `default`, `primary`, `secondary`, `raised`, `destructive`, `destructive-outline`, `outline`, `dashed`, `ghost`, `link`, `overlay`, `glass` | `default` |\n| `sizes` | `xs`, `sm`, `md`, `lg`, `xl`, `tile`, `icon-xs`, `icon-sm`, `icon`, `icon-lg`, `icon-xl` | `md` |\n\n**Deprecated aliases:** `focusVisible` → `focus-visible` (states)\n\n**Slots:** `button`, `button-label`, `button-spinner`, `button-indicator`\n\n**States:** `rest`, `hover`, `pressed`, `focus-visible`, `disabled`, `loading`\n\n**Token slots:** `button.background`, `button.foreground`, `button.border.color`, `button.border.width`, `button.radius`, `button.shadow`, `button.focusRing`, `button.height`, `button.paddingInline`, `button.gap`, `button.iconSize`, `button.motion.press`\n\n**Visual archetype:** Action controls — Momentary controls that perform an action now.\n\n### Web and iOS\n\nTrigger a user-initiated action with explicit hierarchy and feedback. Rendered by `AtomButton` in SwiftUI, with `recipe` parity.\n\n**Required states:** `rest`, `pressed`, `disabled`, `loading`\n\n**Shared outcomes:**\n\n- Action fires once\n- Loading blocks repeat activation\n- Disabled prevents activation\n\n**Accessibility outcomes:**\n\n- Exposes label\n- Announces loading\n- Disabled while loading\n\n**Platform adaptations:**\n\n- React: Uses HTML button semantics with pointer and focus-visible feedback.\n- SwiftUI: Uses SwiftUI Button with native touch and keyboard activation.\n- SwiftUI: The round shape is a capsule: a circle at the icon size, a pill with a label.\n- SwiftUI: The raised emphasis uses the panel fill and a soft shadow with no border; muted tone only quiets ghost labels.\n\n## Related components\n\n- [Button Group](/components/component-button-group)\n- [Toggle](/components/component-toggle)\n- [Copy Button](/components/component-copy-button)\n",
5085
5112
  "related": [
5086
5113
  "button-group",
5087
5114
  "toggle",
@@ -5150,7 +5177,7 @@
5150
5177
  "values": [
5151
5178
  "xs",
5152
5179
  "sm",
5153
- "default",
5180
+ "md",
5154
5181
  "lg",
5155
5182
  "xl",
5156
5183
  "icon-xs",
@@ -5159,7 +5186,10 @@
5159
5186
  "icon-lg",
5160
5187
  "icon-xl"
5161
5188
  ],
5162
- "default": "default"
5189
+ "deprecatedAliases": {
5190
+ "default": "md"
5191
+ },
5192
+ "default": "md"
5163
5193
  }
5164
5194
  ],
5165
5195
  "exportName": "buttonGroupContract",
@@ -5199,7 +5229,7 @@
5199
5229
  ],
5200
5230
  "importPath": "@atom63/ui-react",
5201
5231
  "label": "Button Group",
5202
- "markdown": "# Button Group\n\nButton Group welds adjacent controls into one visual run without changing their semantics.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Use Toggle Group or Segmented Control when the group itself represents persistent selection.\n- Keep the semantic action or link element intact when composing custom content.\n- Make loading, disabled, and destructive behavior explicit in the product flow.\n\n## Usage\n\n```tsx\nimport { ButtonGroup, ButtonGroupText, ButtonGroupSeparator } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `ButtonGroup`, `ButtonGroupProvider`, `ButtonGroupSeparator`, `ButtonGroupText`, `useButtonGroupContext`\n\n**Types:** `ButtonGroupProps`, `ButtonGroupSeparatorProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/button-group.json` (`buttonGroupContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `orientations` | `horizontal`, `vertical` | `horizontal` |\n| `sizes` | `xs`, `sm`, `default`, `lg`, `xl`, `icon-xs`, `icon-sm`, `icon`, `icon-lg`, `icon-xl` | `default` |\n\n**Slots:** `button-group`, `button-group-text`, `button-group-separator`\n\n**States:** `rest`, `focus-within`\n\n**Visual archetype:** Action controls — Momentary controls that perform an action now.; Segmented selection — One-of-many peer selections presented as a shared track or grouped row.\n\n## Related components\n\n- [Button](/components/component-button)\n- [Toggle Group](/components/component-toggle-group)\n- [Segmented Control](/components/component-segmented-control)\n",
5232
+ "markdown": "# Button Group\n\nButton Group welds adjacent controls into one visual run without changing their semantics.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Use Toggle Group or Segmented Control when the group itself represents persistent selection.\n- Keep the semantic action or link element intact when composing custom content.\n- Make loading, disabled, and destructive behavior explicit in the product flow.\n\n## Usage\n\n```tsx\nimport { ButtonGroup, ButtonGroupText, ButtonGroupSeparator } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `ButtonGroup`, `ButtonGroupProvider`, `ButtonGroupSeparator`, `ButtonGroupText`, `useButtonGroupContext`\n\n**Types:** `ButtonGroupProps`, `ButtonGroupSeparatorProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/button-group.json` (`buttonGroupContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `orientations` | `horizontal`, `vertical` | `horizontal` |\n| `sizes` | `xs`, `sm`, `md`, `lg`, `xl`, `icon-xs`, `icon-sm`, `icon`, `icon-lg`, `icon-xl` | `md` |\n\n**Deprecated aliases:** `default` → `md` (sizes)\n\n**Slots:** `button-group`, `button-group-text`, `button-group-separator`\n\n**States:** `rest`, `focus-within`\n\n**Visual archetype:** Action controls — Momentary controls that perform an action now.; Segmented selection — One-of-many peer selections presented as a shared track or grouped row.\n\n## Related components\n\n- [Button](/components/component-button)\n- [Toggle Group](/components/component-toggle-group)\n- [Segmented Control](/components/component-segmented-control)\n",
5203
5233
  "related": [
5204
5234
  "button",
5205
5235
  "toggle-group",
@@ -5221,7 +5251,7 @@
5221
5251
  "Endpoints",
5222
5252
  "ContractMetadata"
5223
5253
  ],
5224
- "source": "import { buttonGroupContract, themes } from '@atom63/ui-foundation'\nimport {\n Button,\n ButtonGroup,\n ButtonGroupSeparator,\n ButtonGroupText,\n Input,\n UIProvider,\n} from '@atom63/ui-react'\nimport '@atom63/ui-react/styles.css'\nimport type { Meta, StoryObj } from '@storybook/react-vite'\n\nconst meta = {\n title: 'UI React/ButtonGroup',\n component: ButtonGroup,\n} satisfies Meta<typeof ButtonGroup>\n\nexport default meta\ntype Story = StoryObj<typeof meta>\n\nexport const Playground: Story = {\n render: () => (\n <ButtonGroup>\n <Button variant=\"secondary\">Left</Button>\n <Button variant=\"secondary\">Middle</Button>\n <Button variant=\"secondary\">Right</Button>\n </ButtonGroup>\n ),\n}\n\nexport const Vertical: Story = {\n render: () => (\n <ButtonGroup orientation=\"vertical\">\n <Button variant=\"secondary\">Top</Button>\n <Button variant=\"secondary\">Middle</Button>\n <Button variant=\"secondary\">Bottom</Button>\n </ButtonGroup>\n ),\n}\n\n/* A non-interactive text prefix welded to an action. */\nexport const WithText: Story = {\n render: () => (\n <ButtonGroup>\n <ButtonGroupText>https://</ButtonGroupText>\n <Button variant=\"secondary\">Copy</Button>\n </ButtonGroup>\n ),\n}\n\n/* A separator dividing two runs of actions. */\nexport const WithSeparator: Story = {\n render: () => (\n <ButtonGroup>\n <Button variant=\"secondary\">Cut</Button>\n <Button variant=\"secondary\">Copy</Button>\n <ButtonGroupSeparator />\n <Button variant=\"secondary\">Paste</Button>\n </ButtonGroup>\n ),\n}\n\nexport const Sizes: Story = {\n render: () => (\n <div style={{ alignItems: 'flex-start', display: 'grid', gap: 12 }}>\n {(['xs', 'sm', 'default', 'lg', 'xl'] as const).map(size => (\n <ButtonGroup key={size} size={size}>\n <Button variant=\"secondary\">One</Button>\n <Button variant=\"secondary\">Two</Button>\n <Button variant=\"secondary\">Three</Button>\n </ButtonGroup>\n ))}\n </div>\n ),\n}\n\nexport const Themes: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12 }}>\n {themes.map(theme =>\n (['light', 'dark'] as const).map(mode => (\n <UIProvider key={`${theme}-${mode}`} mode={mode} theme={theme}>\n <div\n style={{\n alignItems: 'center',\n background: 'var(--a63-surface-panel)',\n borderRadius: '0.75rem',\n color: 'var(--a63-text-primary)',\n display: 'flex',\n gap: 12,\n padding: '0.75rem',\n }}\n >\n <span style={{ fontSize: 12, color: 'var(--a63-text-secondary)', width: 96 }}>\n {theme} / {mode}\n </span>\n <ButtonGroup>\n <Button type=\"button\" variant=\"secondary\">\n Cut\n </Button>\n <Button type=\"button\" variant=\"secondary\">\n Copy\n </Button>\n <Button type=\"button\" variant=\"secondary\">\n Paste\n </Button>\n </ButtonGroup>\n <ButtonGroup size=\"icon-sm\">\n <Button aria-pressed type=\"button\" variant=\"ghost\">\n On\n </Button>\n <Button type=\"button\" variant=\"ghost\">\n Off\n </Button>\n <Button type=\"button\" variant=\"ghost\">\n Off\n </Button>\n </ButtonGroup>\n </div>\n </UIProvider>\n ))\n )}\n </div>\n ),\n}\n\n/* Height parity — a group sits next to an Input at the same size; both resolve\n the same --a63-control-height ramp x density, so their heights line up. */\nexport const WithInput: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 16 }}>\n {(['default', 'sm', 'lg'] as const).map(size => (\n <div key={size} style={{ display: 'flex', gap: 8, alignItems: 'center' }}>\n <span style={{ fontSize: 12, color: 'var(--a63-text-secondary)', width: 56 }}>\n {size}\n </span>\n <Input\n aria-label=\"Example text field\"\n placeholder=\"Search…\"\n size={size === 'default' ? 'md' : size}\n style={{ width: 180 }}\n />\n <ButtonGroup size={size}>\n <Button variant=\"secondary\">Cut</Button>\n <Button variant=\"secondary\">Copy</Button>\n <Button variant=\"secondary\">Paste</Button>\n </ButtonGroup>\n </div>\n ))}\n </div>\n ),\n}\n\n/* The same welded action run reviewed against target host contexts. */\nexport const Endpoints: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12 }}>\n {[\n {\n label: 'Web',\n props: { density: 'comfortable', designLanguage: 'web', input: 'pointer' } as const,\n },\n {\n label: 'iOS touch',\n props: { density: 'comfortable', designLanguage: 'ios', input: 'touch' } as const,\n },\n {\n label: 'Compact extension',\n props: {\n density: 'compact',\n designLanguage: 'web',\n input: 'pointer',\n surface: 'n2',\n } as const,\n },\n ].map(endpoint => (\n <UIProvider key={endpoint.label} {...endpoint.props}>\n <div\n style={{\n alignItems: 'center',\n background: 'var(--a63-surface-panel)',\n borderRadius: 'var(--radius-lg)',\n color: 'var(--a63-text-primary)',\n display: 'flex',\n gap: 12,\n padding: '0.75rem',\n }}\n >\n <span style={{ fontSize: 12, color: 'var(--a63-text-secondary)', width: 112 }}>\n {endpoint.label}\n </span>\n <ButtonGroup size={endpoint.label === 'Compact extension' ? 'sm' : 'default'}>\n <Button variant=\"secondary\">Cut</Button>\n <Button variant=\"secondary\">Copy</Button>\n <Button variant=\"secondary\">Paste</Button>\n </ButtonGroup>\n <ButtonGroup size={endpoint.label === 'Compact extension' ? 'sm' : 'default'}>\n <Button variant=\"ghost\">Bold</Button>\n <Button variant=\"ghost\">Italic</Button>\n <Button variant=\"ghost\">Under</Button>\n </ButtonGroup>\n </div>\n </UIProvider>\n ))}\n </div>\n ),\n}\n\nexport const ContractMetadata: Story = {\n render: () => (\n <pre style={{ fontSize: 12, margin: 0, whiteSpace: 'pre-wrap' }}>\n {JSON.stringify(buttonGroupContract, null, 2)}\n </pre>\n ),\n}\n"
5254
+ "source": "import { buttonGroupContract, themes } from '@atom63/ui-foundation'\nimport {\n Button,\n ButtonGroup,\n ButtonGroupSeparator,\n ButtonGroupText,\n Input,\n UIProvider,\n} from '@atom63/ui-react'\nimport '@atom63/ui-react/styles.css'\nimport type { Meta, StoryObj } from '@storybook/react-vite'\n\nconst meta = {\n title: 'UI React/ButtonGroup',\n component: ButtonGroup,\n} satisfies Meta<typeof ButtonGroup>\n\nexport default meta\ntype Story = StoryObj<typeof meta>\n\nexport const Playground: Story = {\n render: () => (\n <ButtonGroup>\n <Button variant=\"secondary\">Left</Button>\n <Button variant=\"secondary\">Middle</Button>\n <Button variant=\"secondary\">Right</Button>\n </ButtonGroup>\n ),\n}\n\nexport const Vertical: Story = {\n render: () => (\n <ButtonGroup orientation=\"vertical\">\n <Button variant=\"secondary\">Top</Button>\n <Button variant=\"secondary\">Middle</Button>\n <Button variant=\"secondary\">Bottom</Button>\n </ButtonGroup>\n ),\n}\n\n/* A non-interactive text prefix welded to an action. */\nexport const WithText: Story = {\n render: () => (\n <ButtonGroup>\n <ButtonGroupText>https://</ButtonGroupText>\n <Button variant=\"secondary\">Copy</Button>\n </ButtonGroup>\n ),\n}\n\n/* A separator dividing two runs of actions. */\nexport const WithSeparator: Story = {\n render: () => (\n <ButtonGroup>\n <Button variant=\"secondary\">Cut</Button>\n <Button variant=\"secondary\">Copy</Button>\n <ButtonGroupSeparator />\n <Button variant=\"secondary\">Paste</Button>\n </ButtonGroup>\n ),\n}\n\nexport const Sizes: Story = {\n render: () => (\n <div style={{ alignItems: 'flex-start', display: 'grid', gap: 12 }}>\n {(['xs', 'sm', 'md', 'lg', 'xl'] as const).map(size => (\n <ButtonGroup key={size} size={size}>\n <Button variant=\"secondary\">One</Button>\n <Button variant=\"secondary\">Two</Button>\n <Button variant=\"secondary\">Three</Button>\n </ButtonGroup>\n ))}\n </div>\n ),\n}\n\nexport const Themes: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12 }}>\n {themes.map(theme =>\n (['light', 'dark'] as const).map(mode => (\n <UIProvider key={`${theme}-${mode}`} mode={mode} theme={theme}>\n <div\n style={{\n alignItems: 'center',\n background: 'var(--a63-surface-panel)',\n borderRadius: '0.75rem',\n color: 'var(--a63-text-primary)',\n display: 'flex',\n gap: 12,\n padding: '0.75rem',\n }}\n >\n <span style={{ fontSize: 12, color: 'var(--a63-text-secondary)', width: 96 }}>\n {theme} / {mode}\n </span>\n <ButtonGroup>\n <Button type=\"button\" variant=\"secondary\">\n Cut\n </Button>\n <Button type=\"button\" variant=\"secondary\">\n Copy\n </Button>\n <Button type=\"button\" variant=\"secondary\">\n Paste\n </Button>\n </ButtonGroup>\n <ButtonGroup size=\"icon-sm\">\n <Button aria-pressed type=\"button\" variant=\"ghost\">\n On\n </Button>\n <Button type=\"button\" variant=\"ghost\">\n Off\n </Button>\n <Button type=\"button\" variant=\"ghost\">\n Off\n </Button>\n </ButtonGroup>\n </div>\n </UIProvider>\n ))\n )}\n </div>\n ),\n}\n\n/* Height parity — a group sits next to an Input at the same size; both resolve\n the same --a63-control-height ramp x density, so their heights line up. */\nexport const WithInput: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 16 }}>\n {(['md', 'sm', 'lg'] as const).map(size => (\n <div key={size} style={{ display: 'flex', gap: 8, alignItems: 'center' }}>\n <span style={{ fontSize: 12, color: 'var(--a63-text-secondary)', width: 56 }}>\n {size}\n </span>\n <Input\n aria-label=\"Example text field\"\n placeholder=\"Search…\"\n size={size}\n style={{ width: 180 }}\n />\n <ButtonGroup size={size}>\n <Button variant=\"secondary\">Cut</Button>\n <Button variant=\"secondary\">Copy</Button>\n <Button variant=\"secondary\">Paste</Button>\n </ButtonGroup>\n </div>\n ))}\n </div>\n ),\n}\n\n/* The same welded action run reviewed against target host contexts. */\nexport const Endpoints: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12 }}>\n {[\n {\n label: 'Web',\n props: { density: 'comfortable', designLanguage: 'web', input: 'pointer' } as const,\n },\n {\n label: 'iOS touch',\n props: { density: 'comfortable', designLanguage: 'ios', input: 'touch' } as const,\n },\n {\n label: 'Compact extension',\n props: {\n density: 'compact',\n designLanguage: 'web',\n input: 'pointer',\n surface: 'n2',\n } as const,\n },\n ].map(endpoint => (\n <UIProvider key={endpoint.label} {...endpoint.props}>\n <div\n style={{\n alignItems: 'center',\n background: 'var(--a63-surface-panel)',\n borderRadius: 'var(--radius-lg)',\n color: 'var(--a63-text-primary)',\n display: 'flex',\n gap: 12,\n padding: '0.75rem',\n }}\n >\n <span style={{ fontSize: 12, color: 'var(--a63-text-secondary)', width: 112 }}>\n {endpoint.label}\n </span>\n <ButtonGroup size={endpoint.label === 'Compact extension' ? 'sm' : 'md'}>\n <Button variant=\"secondary\">Cut</Button>\n <Button variant=\"secondary\">Copy</Button>\n <Button variant=\"secondary\">Paste</Button>\n </ButtonGroup>\n <ButtonGroup size={endpoint.label === 'Compact extension' ? 'sm' : 'md'}>\n <Button variant=\"ghost\">Bold</Button>\n <Button variant=\"ghost\">Italic</Button>\n <Button variant=\"ghost\">Under</Button>\n </ButtonGroup>\n </div>\n </UIProvider>\n ))}\n </div>\n ),\n}\n\nexport const ContractMetadata: Story = {\n render: () => (\n <pre style={{ fontSize: 12, margin: 0, whiteSpace: 'pre-wrap' }}>\n {JSON.stringify(buttonGroupContract, null, 2)}\n </pre>\n ),\n}\n"
5225
5255
  },
5226
5256
  "summary": "Button Group welds adjacent controls into one visual run without changing their semantics.",
5227
5257
  "usage": "Use Toggle Group or Segmented Control when the group itself represents persistent selection.",
@@ -5510,10 +5540,13 @@
5510
5540
  "name": "sizes",
5511
5541
  "values": [
5512
5542
  "sm",
5513
- "default",
5543
+ "md",
5514
5544
  "lg"
5515
5545
  ],
5516
- "default": "default"
5546
+ "deprecatedAliases": {
5547
+ "default": "md"
5548
+ },
5549
+ "default": "md"
5517
5550
  }
5518
5551
  ],
5519
5552
  "exportName": "autocompleteContract",
@@ -5587,7 +5620,7 @@
5587
5620
  ],
5588
5621
  "importPath": "@atom63/ui-react",
5589
5622
  "label": "Autocomplete",
5590
- "markdown": "# Autocomplete\n\nAutocomplete combines text entry with a filtered, keyboard-navigable collection.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Use it when typing should filter available values; use Select when scanning the list is enough.\n- Pair controls with persistent labels and explain errors beside the affected field.\n- Validate focus visibility, disabled state, invalid state, and touch input together.\n\n## Usage\n\n```tsx\nimport { Autocomplete, AutocompleteInput, AutocompletePopup, AutocompleteItem } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Autocomplete`, `AutocompleteClear`, `AutocompleteCollection`, `AutocompleteEmpty`, `AutocompleteGroup`, `AutocompleteGroupLabel`, `AutocompleteInput`, `AutocompleteItem`, `AutocompleteList`, `AutocompletePopup`, `AutocompletePrimitive`, `AutocompleteRow`, `AutocompleteSeparator`, `AutocompleteStatus`, `AutocompleteTrigger`, `AutocompleteValue`, `useAutocompleteFilter`\n\n**Types:** `AutocompleteInputProps`, `AutocompletePopupProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/autocomplete.json` (`autocompleteContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `sizes` | `sm`, `default`, `lg` | `default` |\n\n**Slots:** `autocomplete-input-group`, `autocomplete-start-addon`, `autocomplete-input`, `autocomplete-trigger`, `autocomplete-icon`, `autocomplete-clear`, `autocomplete-positioner`, `autocomplete-surface`, `autocomplete-popup`, `autocomplete-list`, `autocomplete-item`, `autocomplete-separator`, `autocomplete-group`, `autocomplete-group-label`, `autocomplete-empty`, `autocomplete-row`, `autocomplete-value`, `autocomplete-status`, `autocomplete-collection`\n\n**States:** `closed`, `open`, `highlighted`, `hover`, `disabled`, `empty`, `loading`, `invalid`\n\n**Visual archetype:** Field controls — Editable or field-like data-entry surfaces.; Triggers — Controls whose primary job is to open another surface.; Overlay surfaces — Floating material above the page or current surface.; Menus and option lists — Dense action or selection rows inside a floating or embedded list.\n\n## Related components\n\n- [Input](/components/component-input)\n- [Command](/components/component-command)\n- [Select](/components/component-select)\n",
5623
+ "markdown": "# Autocomplete\n\nAutocomplete combines text entry with a filtered, keyboard-navigable collection.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Use it when typing should filter available values; use Select when scanning the list is enough.\n- Pair controls with persistent labels and explain errors beside the affected field.\n- Validate focus visibility, disabled state, invalid state, and touch input together.\n\n## Usage\n\n```tsx\nimport { Autocomplete, AutocompleteInput, AutocompletePopup, AutocompleteItem } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Autocomplete`, `AutocompleteClear`, `AutocompleteCollection`, `AutocompleteEmpty`, `AutocompleteGroup`, `AutocompleteGroupLabel`, `AutocompleteInput`, `AutocompleteItem`, `AutocompleteList`, `AutocompletePopup`, `AutocompletePrimitive`, `AutocompleteRow`, `AutocompleteSeparator`, `AutocompleteStatus`, `AutocompleteTrigger`, `AutocompleteValue`, `useAutocompleteFilter`\n\n**Types:** `AutocompleteInputProps`, `AutocompletePopupProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/autocomplete.json` (`autocompleteContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `sizes` | `sm`, `md`, `lg` | `md` |\n\n**Deprecated aliases:** `default` → `md` (sizes)\n\n**Slots:** `autocomplete-input-group`, `autocomplete-start-addon`, `autocomplete-input`, `autocomplete-trigger`, `autocomplete-icon`, `autocomplete-clear`, `autocomplete-positioner`, `autocomplete-surface`, `autocomplete-popup`, `autocomplete-list`, `autocomplete-item`, `autocomplete-separator`, `autocomplete-group`, `autocomplete-group-label`, `autocomplete-empty`, `autocomplete-row`, `autocomplete-value`, `autocomplete-status`, `autocomplete-collection`\n\n**States:** `closed`, `open`, `highlighted`, `hover`, `disabled`, `empty`, `loading`, `invalid`\n\n**Visual archetype:** Field controls — Editable or field-like data-entry surfaces.; Triggers — Controls whose primary job is to open another surface.; Overlay surfaces — Floating material above the page or current surface.; Menus and option lists — Dense action or selection rows inside a floating or embedded list.\n\n## Related components\n\n- [Input](/components/component-input)\n- [Command](/components/component-command)\n- [Select](/components/component-select)\n",
5591
5624
  "related": [
5592
5625
  "input",
5593
5626
  "command",
@@ -5611,7 +5644,7 @@
5611
5644
  "Endpoints",
5612
5645
  "ContractMetadata"
5613
5646
  ],
5614
- "source": "import { autocompleteContract, themes } from '@atom63/ui-foundation'\nimport {\n Autocomplete,\n AutocompleteEmpty,\n AutocompleteGroup,\n AutocompleteGroupLabel,\n AutocompleteInput,\n AutocompleteItem,\n AutocompleteList,\n AutocompletePopup,\n AutocompleteSeparator,\n AutocompleteStatus,\n UIProvider,\n} from '@atom63/ui-react'\nimport '@atom63/ui-react/styles.css'\nimport type { Meta, StoryObj } from '@storybook/react-vite'\n\nconst meta = {\n title: 'UI React/Autocomplete',\n component: Autocomplete,\n decorators: [\n Story => (\n <div style={{ padding: 'clamp(12px, 8vw, 48px)', width: 'min(320px, 100%)' }}>\n <Story />\n </div>\n ),\n ],\n} satisfies Meta<typeof Autocomplete>\n\nexport default meta\ntype Story = StoryObj<typeof meta>\n\nconst fruits = [\n 'Apple',\n 'Apricot',\n 'Banana',\n 'Blackberry',\n 'Blueberry',\n 'Cherry',\n 'Grape',\n 'Mango',\n 'Orange',\n 'Peach',\n]\n\nconst groupedFruits = {\n Recent: ['Apple', 'Banana', 'Cherry'],\n Citrus: ['Grapefruit', 'Lemon', 'Orange'],\n Berries: ['Blackberry', 'Blueberry', 'Strawberry'],\n}\n\nfunction Demo({\n disabled,\n invalid,\n size,\n}: {\n disabled?: boolean\n invalid?: boolean\n size?: 'sm' | 'default' | 'lg' | number\n}) {\n return (\n <Autocomplete items={fruits}>\n <AutocompleteInput\n aria-label=\"Search fruit\"\n disabled={disabled}\n invalid={invalid}\n placeholder=\"Search fruit…\"\n showClear\n showTrigger\n size={size}\n />\n <AutocompletePopup>\n <AutocompleteEmpty>No fruit found.</AutocompleteEmpty>\n <AutocompleteList>\n {(fruit: string) => <AutocompleteItem key={fruit}>{fruit}</AutocompleteItem>}\n </AutocompleteList>\n </AutocompletePopup>\n </Autocomplete>\n )\n}\n\nfunction GroupedDemo({ open, size }: { open?: boolean; size?: 'sm' | 'default' | 'lg' }) {\n return (\n <Autocomplete\n autoHighlight={open ? 'always' : undefined}\n defaultOpen={open}\n items={Object.values(groupedFruits).flat()}\n >\n <AutocompleteInput placeholder=\"Search fruit…\" showClear showTrigger size={size} />\n <AutocompletePopup>\n <AutocompleteEmpty>No fruit found.</AutocompleteEmpty>\n <AutocompleteList>\n {Object.entries(groupedFruits).map(([group, values], index) => (\n <AutocompleteGroup key={group}>\n {index > 0 ? <AutocompleteSeparator /> : null}\n <AutocompleteGroupLabel>{group}</AutocompleteGroupLabel>\n {values.map(value => (\n <AutocompleteItem key={value} value={value}>\n {value}\n </AutocompleteItem>\n ))}\n </AutocompleteGroup>\n ))}\n </AutocompleteList>\n </AutocompletePopup>\n </Autocomplete>\n )\n}\n\nexport const Playground: Story = {\n render: () => <Demo />,\n}\n\n/** Open on load with the first item highlighted, so the visual and axe runs\n * capture the popup, its groups and the highlighted row. */\nexport const MenuAnatomy: Story = {\n render: () => <GroupedDemo open />,\n}\n\n/** A query with no match shows the empty message in the open popup. */\nexport const Empty: Story = {\n render: () => (\n <Autocomplete defaultOpen defaultValue=\"Kiwano\" items={fruits}>\n <AutocompleteInput aria-label=\"Search fruit\" placeholder=\"Search fruit…\" showClear />\n <AutocompletePopup>\n <AutocompleteEmpty>No fruit found.</AutocompleteEmpty>\n <AutocompleteList>\n {(fruit: string) => <AutocompleteItem key={fruit}>{fruit}</AutocompleteItem>}\n </AutocompleteList>\n </AutocompletePopup>\n </Autocomplete>\n ),\n}\n\n/** While results load, the popup shows the status line in place of the list. */\nexport const Loading: Story = {\n render: () => (\n <Autocomplete defaultOpen defaultValue=\"Ber\" items={[] as string[]}>\n <AutocompleteInput aria-label=\"Search fruit\" placeholder=\"Search fruit…\" />\n <AutocompletePopup>\n <AutocompleteStatus>Searching fruit…</AutocompleteStatus>\n <AutocompleteList>\n {(fruit: string) => <AutocompleteItem key={fruit}>{fruit}</AutocompleteItem>}\n </AutocompleteList>\n </AutocompletePopup>\n </Autocomplete>\n ),\n}\n\nexport const Disabled: Story = {\n render: () => <Demo disabled />,\n}\n\n/** `invalid` (or `aria-invalid`, which FormControl sets) draws the danger edge. */\nexport const Invalid: Story = {\n render: () => <Demo invalid />,\n}\n\n// The `size` prop on AutocompleteInput accepts named recipe sizes\n// ('sm' | 'default' | 'lg') OR a number. A numeric value is forwarded to the\n// native <input size> attribute for character-width sizing.\nexport const Sizes: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 16 }}>\n <div>\n <div style={{ fontSize: 12, color: 'var(--a63-text-secondary)', marginBottom: 6 }}>sm</div>\n <Demo size=\"sm\" />\n </div>\n <div>\n <div style={{ fontSize: 12, color: 'var(--a63-text-secondary)', marginBottom: 6 }}>\n default\n </div>\n <Demo size=\"default\" />\n </div>\n <div>\n <div style={{ fontSize: 12, color: 'var(--a63-text-secondary)', marginBottom: 6 }}>lg</div>\n <Demo size=\"lg\" />\n </div>\n <div>\n <div style={{ fontSize: 12, color: 'var(--a63-text-secondary)', marginBottom: 6 }}>\n size={'{'}12{'}'} (native char-width)\n </div>\n <Demo size={12} />\n </div>\n <div>\n <div style={{ fontSize: 12, color: 'var(--a63-text-secondary)', marginBottom: 6 }}>\n size={'{'}30{'}'} (native char-width)\n </div>\n <Demo size={30} />\n </div>\n </div>\n ),\n}\n\nexport const Themes: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12 }}>\n {themes.map(theme =>\n (['light', 'dark'] as const).map(mode => (\n <UIProvider key={`${theme}-${mode}`} mode={mode} theme={theme}>\n <div\n style={{\n alignItems: 'center',\n background: 'var(--a63-surface-panel)',\n borderRadius: '0.75rem',\n color: 'var(--a63-text-primary)',\n display: 'flex',\n gap: 12,\n padding: '0.75rem',\n }}\n >\n <span style={{ fontSize: 12, color: 'var(--a63-text-secondary)', width: 96 }}>\n {theme} / {mode}\n </span>\n <Demo />\n </div>\n </UIProvider>\n ))\n )}\n </div>\n ),\n}\n\nexport const RadiusSpacing: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12 }}>\n {[\n { label: 'Rounded items', radius: 'default' },\n { label: 'Flush square items', radius: 'none' },\n ].map(example => (\n <div\n key={example.radius}\n data-a63-radius={example.radius}\n style={{\n alignItems: 'center',\n background: 'var(--a63-surface-panel)',\n borderRadius: 'var(--radius-lg)',\n color: 'var(--a63-text-primary)',\n display: 'flex',\n gap: 12,\n padding: '0.75rem',\n }}\n >\n <span style={{ fontSize: 12, color: 'var(--a63-text-secondary)', width: 112 }}>\n {example.label}\n </span>\n <GroupedDemo />\n </div>\n ))}\n </div>\n ),\n}\n\n/* The same autocomplete reviewed against target host contexts. */\nexport const Endpoints: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12 }}>\n {[\n {\n label: 'Web',\n props: { density: 'comfortable', designLanguage: 'web', input: 'pointer' } as const,\n },\n {\n label: 'iOS touch',\n props: { density: 'comfortable', designLanguage: 'ios', input: 'touch' } as const,\n },\n {\n label: 'Compact extension',\n props: {\n density: 'compact',\n designLanguage: 'web',\n input: 'pointer',\n surface: 'n2',\n } as const,\n },\n ].map(endpoint => (\n <UIProvider key={endpoint.label} {...endpoint.props}>\n <div\n style={{\n alignItems: 'center',\n background: 'var(--a63-surface-panel)',\n borderRadius: 'var(--radius-lg)',\n color: 'var(--a63-text-primary)',\n display: 'flex',\n gap: 12,\n padding: '0.75rem',\n }}\n >\n <span style={{ fontSize: 12, color: 'var(--a63-text-secondary)', width: 112 }}>\n {endpoint.label}\n </span>\n <GroupedDemo size={endpoint.label === 'Compact extension' ? 'sm' : 'default'} />\n </div>\n </UIProvider>\n ))}\n </div>\n ),\n}\n\nexport const ContractMetadata: Story = {\n render: () => (\n <pre style={{ fontSize: 12, margin: 0, whiteSpace: 'pre-wrap' }}>\n {JSON.stringify(autocompleteContract, null, 2)}\n </pre>\n ),\n}\n"
5647
+ "source": "import { autocompleteContract, themes } from '@atom63/ui-foundation'\nimport {\n Autocomplete,\n AutocompleteEmpty,\n AutocompleteGroup,\n AutocompleteGroupLabel,\n AutocompleteInput,\n AutocompleteItem,\n AutocompleteList,\n AutocompletePopup,\n AutocompleteSeparator,\n AutocompleteStatus,\n UIProvider,\n} from '@atom63/ui-react'\nimport '@atom63/ui-react/styles.css'\nimport type { Meta, StoryObj } from '@storybook/react-vite'\n\nconst meta = {\n title: 'UI React/Autocomplete',\n component: Autocomplete,\n decorators: [\n Story => (\n <div style={{ padding: 'clamp(12px, 8vw, 48px)', width: 'min(320px, 100%)' }}>\n <Story />\n </div>\n ),\n ],\n} satisfies Meta<typeof Autocomplete>\n\nexport default meta\ntype Story = StoryObj<typeof meta>\n\nconst fruits = [\n 'Apple',\n 'Apricot',\n 'Banana',\n 'Blackberry',\n 'Blueberry',\n 'Cherry',\n 'Grape',\n 'Mango',\n 'Orange',\n 'Peach',\n]\n\nconst groupedFruits = {\n Recent: ['Apple', 'Banana', 'Cherry'],\n Citrus: ['Grapefruit', 'Lemon', 'Orange'],\n Berries: ['Blackberry', 'Blueberry', 'Strawberry'],\n}\n\nfunction Demo({\n disabled,\n invalid,\n size,\n}: {\n disabled?: boolean\n invalid?: boolean\n size?: 'sm' | 'md' | 'lg' | number\n}) {\n return (\n <Autocomplete items={fruits}>\n <AutocompleteInput\n aria-label=\"Search fruit\"\n disabled={disabled}\n invalid={invalid}\n placeholder=\"Search fruit…\"\n showClear\n showTrigger\n size={size}\n />\n <AutocompletePopup>\n <AutocompleteEmpty>No fruit found.</AutocompleteEmpty>\n <AutocompleteList>\n {(fruit: string) => <AutocompleteItem key={fruit}>{fruit}</AutocompleteItem>}\n </AutocompleteList>\n </AutocompletePopup>\n </Autocomplete>\n )\n}\n\nfunction GroupedDemo({ open, size }: { open?: boolean; size?: 'sm' | 'md' | 'lg' }) {\n return (\n <Autocomplete\n autoHighlight={open ? 'always' : undefined}\n defaultOpen={open}\n items={Object.values(groupedFruits).flat()}\n >\n <AutocompleteInput placeholder=\"Search fruit…\" showClear showTrigger size={size} />\n <AutocompletePopup>\n <AutocompleteEmpty>No fruit found.</AutocompleteEmpty>\n <AutocompleteList>\n {Object.entries(groupedFruits).map(([group, values], index) => (\n <AutocompleteGroup key={group}>\n {index > 0 ? <AutocompleteSeparator /> : null}\n <AutocompleteGroupLabel>{group}</AutocompleteGroupLabel>\n {values.map(value => (\n <AutocompleteItem key={value} value={value}>\n {value}\n </AutocompleteItem>\n ))}\n </AutocompleteGroup>\n ))}\n </AutocompleteList>\n </AutocompletePopup>\n </Autocomplete>\n )\n}\n\nexport const Playground: Story = {\n render: () => <Demo />,\n}\n\n/** Open on load with the first item highlighted, so the visual and axe runs\n * capture the popup, its groups and the highlighted row. */\nexport const MenuAnatomy: Story = {\n render: () => <GroupedDemo open />,\n}\n\n/** A query with no match shows the empty message in the open popup. */\nexport const Empty: Story = {\n render: () => (\n <Autocomplete defaultOpen defaultValue=\"Kiwano\" items={fruits}>\n <AutocompleteInput aria-label=\"Search fruit\" placeholder=\"Search fruit…\" showClear />\n <AutocompletePopup>\n <AutocompleteEmpty>No fruit found.</AutocompleteEmpty>\n <AutocompleteList>\n {(fruit: string) => <AutocompleteItem key={fruit}>{fruit}</AutocompleteItem>}\n </AutocompleteList>\n </AutocompletePopup>\n </Autocomplete>\n ),\n}\n\n/** While results load, the popup shows the status line in place of the list. */\nexport const Loading: Story = {\n render: () => (\n <Autocomplete defaultOpen defaultValue=\"Ber\" items={[] as string[]}>\n <AutocompleteInput aria-label=\"Search fruit\" placeholder=\"Search fruit…\" />\n <AutocompletePopup>\n <AutocompleteStatus>Searching fruit…</AutocompleteStatus>\n <AutocompleteList>\n {(fruit: string) => <AutocompleteItem key={fruit}>{fruit}</AutocompleteItem>}\n </AutocompleteList>\n </AutocompletePopup>\n </Autocomplete>\n ),\n}\n\nexport const Disabled: Story = {\n render: () => <Demo disabled />,\n}\n\n/** `invalid` (or `aria-invalid`, which FormControl sets) draws the danger edge. */\nexport const Invalid: Story = {\n render: () => <Demo invalid />,\n}\n\n// The `size` prop on AutocompleteInput accepts named recipe sizes\n// ('sm' | 'md' | 'lg') OR a number. A numeric value is forwarded to the\n// native <input size> attribute for character-width sizing.\nexport const Sizes: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 16 }}>\n <div>\n <div style={{ fontSize: 12, color: 'var(--a63-text-secondary)', marginBottom: 6 }}>sm</div>\n <Demo size=\"sm\" />\n </div>\n <div>\n <div style={{ fontSize: 12, color: 'var(--a63-text-secondary)', marginBottom: 6 }}>md</div>\n <Demo size=\"md\" />\n </div>\n <div>\n <div style={{ fontSize: 12, color: 'var(--a63-text-secondary)', marginBottom: 6 }}>lg</div>\n <Demo size=\"lg\" />\n </div>\n <div>\n <div style={{ fontSize: 12, color: 'var(--a63-text-secondary)', marginBottom: 6 }}>\n size={'{'}12{'}'} (native char-width)\n </div>\n <Demo size={12} />\n </div>\n <div>\n <div style={{ fontSize: 12, color: 'var(--a63-text-secondary)', marginBottom: 6 }}>\n size={'{'}30{'}'} (native char-width)\n </div>\n <Demo size={30} />\n </div>\n </div>\n ),\n}\n\nexport const Themes: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12 }}>\n {themes.map(theme =>\n (['light', 'dark'] as const).map(mode => (\n <UIProvider key={`${theme}-${mode}`} mode={mode} theme={theme}>\n <div\n style={{\n alignItems: 'center',\n background: 'var(--a63-surface-panel)',\n borderRadius: '0.75rem',\n color: 'var(--a63-text-primary)',\n display: 'flex',\n gap: 12,\n padding: '0.75rem',\n }}\n >\n <span style={{ fontSize: 12, color: 'var(--a63-text-secondary)', width: 96 }}>\n {theme} / {mode}\n </span>\n <Demo />\n </div>\n </UIProvider>\n ))\n )}\n </div>\n ),\n}\n\nexport const RadiusSpacing: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12 }}>\n {[\n { label: 'Rounded items', radius: 'default' },\n { label: 'Flush square items', radius: 'none' },\n ].map(example => (\n <div\n key={example.radius}\n data-a63-radius={example.radius}\n style={{\n alignItems: 'center',\n background: 'var(--a63-surface-panel)',\n borderRadius: 'var(--radius-lg)',\n color: 'var(--a63-text-primary)',\n display: 'flex',\n gap: 12,\n padding: '0.75rem',\n }}\n >\n <span style={{ fontSize: 12, color: 'var(--a63-text-secondary)', width: 112 }}>\n {example.label}\n </span>\n <GroupedDemo />\n </div>\n ))}\n </div>\n ),\n}\n\n/* The same autocomplete reviewed against target host contexts. */\nexport const Endpoints: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12 }}>\n {[\n {\n label: 'Web',\n props: { density: 'comfortable', designLanguage: 'web', input: 'pointer' } as const,\n },\n {\n label: 'iOS touch',\n props: { density: 'comfortable', designLanguage: 'ios', input: 'touch' } as const,\n },\n {\n label: 'Compact extension',\n props: {\n density: 'compact',\n designLanguage: 'web',\n input: 'pointer',\n surface: 'n2',\n } as const,\n },\n ].map(endpoint => (\n <UIProvider key={endpoint.label} {...endpoint.props}>\n <div\n style={{\n alignItems: 'center',\n background: 'var(--a63-surface-panel)',\n borderRadius: 'var(--radius-lg)',\n color: 'var(--a63-text-primary)',\n display: 'flex',\n gap: 12,\n padding: '0.75rem',\n }}\n >\n <span style={{ fontSize: 12, color: 'var(--a63-text-secondary)', width: 112 }}>\n {endpoint.label}\n </span>\n <GroupedDemo size={endpoint.label === 'Compact extension' ? 'sm' : 'md'} />\n </div>\n </UIProvider>\n ))}\n </div>\n ),\n}\n\nexport const ContractMetadata: Story = {\n render: () => (\n <pre style={{ fontSize: 12, margin: 0, whiteSpace: 'pre-wrap' }}>\n {JSON.stringify(autocompleteContract, null, 2)}\n </pre>\n ),\n}\n"
5615
5648
  },
5616
5649
  "summary": "Autocomplete combines text entry with a filtered, keyboard-navigable collection.",
5617
5650
  "usage": "Use it when typing should filter available values; use Select when scanning the list is enough.",
@@ -6128,8 +6161,11 @@
6128
6161
  "form-message"
6129
6162
  ],
6130
6163
  "source": "packages/ui-foundation/contracts/components/form.json",
6164
+ "stateAliases": {
6165
+ "default": "rest"
6166
+ },
6131
6167
  "states": [
6132
- "default",
6168
+ "rest",
6133
6169
  "invalid"
6134
6170
  ],
6135
6171
  "tokenSlots": []
@@ -6158,7 +6194,7 @@
6158
6194
  ],
6159
6195
  "importPath": "@atom63/ui-react",
6160
6196
  "label": "Form",
6161
- "markdown": "# Form\n\nForm connects React Hook Form state to shared labels, controls, descriptions, and messages.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Use it when React Hook Form owns validation; use Field for framework-neutral layout.\n- Pair controls with persistent labels and explain errors beside the affected field.\n- Validate focus visibility, disabled state, invalid state, and touch input together.\n\n## Usage\n\n```tsx\nimport { Form, FormField, FormItem, FormControl, FormMessage } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Form`, `FormControl`, `FormDescription`, `FormField`, `FormItem`, `FormLabel`, `FormMessage`, `useFormField`\n\n**Types:** None.\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/form.json` (`formContract` in `@atom63/ui-foundation`).\n\n**Slots:** `form-item`, `form-label`, `form-control`, `form-description`, `form-message`\n\n**States:** `default`, `invalid`\n\n**Visual archetype:** Field controls — Editable or field-like data-entry surfaces.\n\n## Related components\n\n- [Field](/components/component-field)\n- [Input](/components/component-input)\n- [Button](/components/component-button)\n",
6197
+ "markdown": "# Form\n\nForm connects React Hook Form state to shared labels, controls, descriptions, and messages.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Use it when React Hook Form owns validation; use Field for framework-neutral layout.\n- Pair controls with persistent labels and explain errors beside the affected field.\n- Validate focus visibility, disabled state, invalid state, and touch input together.\n\n## Usage\n\n```tsx\nimport { Form, FormField, FormItem, FormControl, FormMessage } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Form`, `FormControl`, `FormDescription`, `FormField`, `FormItem`, `FormLabel`, `FormMessage`, `useFormField`\n\n**Types:** None.\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/form.json` (`formContract` in `@atom63/ui-foundation`).\n\n**Deprecated aliases:** `default` → `rest` (states)\n\n**Slots:** `form-item`, `form-label`, `form-control`, `form-description`, `form-message`\n\n**States:** `rest`, `invalid`\n\n**Visual archetype:** Field controls — Editable or field-like data-entry surfaces.\n\n## Related components\n\n- [Field](/components/component-field)\n- [Input](/components/component-input)\n- [Button](/components/component-button)\n",
6162
6198
  "related": [
6163
6199
  "field",
6164
6200
  "input",
@@ -6360,9 +6396,12 @@
6360
6396
  "input-otp-separator"
6361
6397
  ],
6362
6398
  "source": "packages/ui-foundation/contracts/components/input-otp.json",
6399
+ "stateAliases": {
6400
+ "active": "current"
6401
+ },
6363
6402
  "states": [
6364
6403
  "rest",
6365
- "active",
6404
+ "current",
6366
6405
  "disabled",
6367
6406
  "invalid"
6368
6407
  ],
@@ -6388,7 +6427,7 @@
6388
6427
  ],
6389
6428
  "importPath": "@atom63/ui-react",
6390
6429
  "label": "Input OTP",
6391
- "markdown": "# Input OTP\n\nInput OTP composes accessible one-time-code slots over the input-otp primitive.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Label the complete code field and let the slot group express presentation, not separate inputs.\n- Pair controls with persistent labels and explain errors beside the affected field.\n- Validate focus visibility, disabled state, invalid state, and touch input together.\n\n## Usage\n\n```tsx\nimport { InputOTP, InputOTPGroup, InputOTPSlot, InputOTPSeparator } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `InputOTP`, `InputOTPGroup`, `InputOTPSeparator`, `InputOTPSlot`\n\n**Types:** None.\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/input-otp.json` (`inputOTPContract` in `@atom63/ui-foundation`).\n\n**Slots:** `input-otp`, `input-otp-group`, `input-otp-slot`, `input-otp-separator`\n\n**States:** `rest`, `active`, `disabled`, `invalid`\n\n**Visual archetype:** Field controls — Editable or field-like data-entry surfaces.\n\n## Related components\n\n- [Input](/components/component-input)\n- [Field](/components/component-field)\n",
6430
+ "markdown": "# Input OTP\n\nInput OTP composes accessible one-time-code slots over the input-otp primitive.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Label the complete code field and let the slot group express presentation, not separate inputs.\n- Pair controls with persistent labels and explain errors beside the affected field.\n- Validate focus visibility, disabled state, invalid state, and touch input together.\n\n## Usage\n\n```tsx\nimport { InputOTP, InputOTPGroup, InputOTPSlot, InputOTPSeparator } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `InputOTP`, `InputOTPGroup`, `InputOTPSeparator`, `InputOTPSlot`\n\n**Types:** None.\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/input-otp.json` (`inputOTPContract` in `@atom63/ui-foundation`).\n\n**Deprecated aliases:** `active` → `current` (states)\n\n**Slots:** `input-otp`, `input-otp-group`, `input-otp-slot`, `input-otp-separator`\n\n**States:** `rest`, `current`, `disabled`, `invalid`\n\n**Visual archetype:** Field controls — Editable or field-like data-entry surfaces.\n\n## Related components\n\n- [Input](/components/component-input)\n- [Field](/components/component-field)\n",
6392
6431
  "related": [
6393
6432
  "input",
6394
6433
  "field"
@@ -6839,7 +6878,7 @@
6839
6878
  "slots": [
6840
6879
  "search-field",
6841
6880
  "search-field-icon",
6842
- "search-field-input",
6881
+ "input",
6843
6882
  "search-field-clear",
6844
6883
  "search-field-end"
6845
6884
  ],
@@ -6871,7 +6910,7 @@
6871
6910
  ],
6872
6911
  "importPath": "@atom63/ui-react",
6873
6912
  "label": "Search Field",
6874
- "markdown": "# Search Field\n\nSearch Field provides a clearable search input with shared keyboard and form behavior.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Use it for text filtering and search queries; use Autocomplete when results also select a value.\n- Pair controls with persistent labels and explain errors beside the affected field.\n- Validate focus visibility, disabled state, invalid state, and touch input together.\n\n## Usage\n\n```tsx\nimport { SearchField } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `SearchField`\n\n**Types:** `SearchFieldProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/search-field.json` (`searchFieldContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `variants` | `default`, `filled`, `plain` | `default` |\n\n**Slots:** `search-field`, `search-field-icon`, `search-field-input`, `search-field-clear`, `search-field-end`\n\n**States:** `empty`, `query`, `focus`, `disabled`\n\n**Visual archetype:** Field controls — Editable or field-like data-entry surfaces.; Action controls — Momentary controls that perform an action now.\n\n### Web and iOS\n\nFind or filter relevant content by editing a query without leaving the current collection. Rendered by `searchable(text:prompt:)` in SwiftUI, with `platform-adaptive` parity.\n\n**Required states:** `empty`, `query`, `focus`, `disabled`\n\n**Shared outcomes:**\n\n- Editing updates the query\n- Clear empties the query and preserves input context\n- Submit commits the current query once\n- Disabled search prevents editing and clear\n\n**Accessibility outcomes:**\n\n- Exposes search input role and label\n- Clear action has an accessible label\n- Disabled state is exposed\n\n**Platform adaptations:**\n\n- React: Uses a labeled native search input with an explicit clear button and native form submission.\n- SwiftUI: Uses searchable so placement, cancel, clear, suggestions, keyboard, and focus presentation follow the active Apple platform.\n\n## Related components\n\n- [Input](/components/component-input)\n- [Autocomplete](/components/component-autocomplete)\n- [Command](/components/component-command)\n",
6913
+ "markdown": "# Search Field\n\nSearch Field provides a clearable search input with shared keyboard and form behavior.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Use it for text filtering and search queries; use Autocomplete when results also select a value.\n- Pair controls with persistent labels and explain errors beside the affected field.\n- Validate focus visibility, disabled state, invalid state, and touch input together.\n\n## Usage\n\n```tsx\nimport { SearchField } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `SearchField`\n\n**Types:** `SearchFieldProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/search-field.json` (`searchFieldContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `variants` | `default`, `filled`, `plain` | `default` |\n\n**Slots:** `search-field`, `search-field-icon`, `input`, `search-field-clear`, `search-field-end`\n\n**States:** `empty`, `query`, `focus`, `disabled`\n\n**Visual archetype:** Field controls — Editable or field-like data-entry surfaces.; Action controls — Momentary controls that perform an action now.\n\n### Web and iOS\n\nFind or filter relevant content by editing a query without leaving the current collection. Rendered by `searchable(text:prompt:)` in SwiftUI, with `platform-adaptive` parity.\n\n**Required states:** `empty`, `query`, `focus`, `disabled`\n\n**Shared outcomes:**\n\n- Editing updates the query\n- Clear empties the query and preserves input context\n- Submit commits the current query once\n- Disabled search prevents editing and clear\n\n**Accessibility outcomes:**\n\n- Exposes search input role and label\n- Clear action has an accessible label\n- Disabled state is exposed\n\n**Platform adaptations:**\n\n- React: Uses a labeled native search input with an explicit clear button and native form submission.\n- SwiftUI: Uses searchable so placement, cancel, clear, suggestions, keyboard, and focus presentation follow the active Apple platform.\n\n## Related components\n\n- [Input](/components/component-input)\n- [Autocomplete](/components/component-autocomplete)\n- [Command](/components/component-command)\n",
6875
6914
  "related": [
6876
6915
  "input",
6877
6916
  "autocomplete",
@@ -7686,6 +7725,9 @@
7686
7725
  "toggle-content"
7687
7726
  ],
7688
7727
  "source": "packages/ui-foundation/contracts/components/toggle.json",
7728
+ "stateAliases": {
7729
+ "focus": "focus-visible"
7730
+ },
7689
7731
  "states": [
7690
7732
  "off",
7691
7733
  "on",
@@ -7693,7 +7735,7 @@
7693
7735
  "hover",
7694
7736
  "pressed",
7695
7737
  "disabled",
7696
- "focus"
7738
+ "focus-visible"
7697
7739
  ],
7698
7740
  "tokenSlots": [
7699
7741
  "toggle.background",
@@ -7730,7 +7772,7 @@
7730
7772
  ],
7731
7773
  "importPath": "@atom63/ui-react",
7732
7774
  "label": "Toggle",
7733
- "markdown": "# Toggle\n\nToggle is a pressed control for one independently persistent option.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Expose pressed state with a clear label; use Button for one-shot actions.\n- Pair controls with persistent labels and explain errors beside the affected field.\n- Validate focus visibility, disabled state, invalid state, and touch input together.\n\n## Usage\n\n```tsx\nimport { Toggle } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Toggle`\n\n**Types:** `ToggleProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/toggle.json` (`toggleContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `sizes` | `sm`, `md`, `lg` | `md` |\n| `tones` | `neutral`, `accent`, `subtle` | `neutral` |\n\n**Slots:** `toggle`, `toggle-content`\n\n**States:** `off`, `on`, `rest`, `hover`, `pressed`, `disabled`, `focus`\n\n**Token slots:** `toggle.background`, `toggle.foreground`, `toggle.hoverBackground`, `toggle.onBackground`, `toggle.onForeground`, `toggle.primaryBackground`, `toggle.primaryForeground`, `toggle.borderWidth`, `toggle.radius`, `toggle.gloss`, `toggle.shadow`, `toggle.shadowActive`, `toggle.textShadow`\n\n**Visual archetype:** Toggle controls — Persistent on/off or pressed controls.\n\n### Web and iOS\n\nSelect or deselect a compact option without leaving the current context. Rendered by `AtomChip` in SwiftUI, with `platform-adaptive` parity.\n\n**Required states:** `off`, `on`, `disabled`\n\n**Shared outcomes:**\n\n- Selected state is visible\n- Activation toggles selection\n- Disabled prevents change\n\n**Accessibility outcomes:**\n\n- Exposes label\n- Announces selected state\n- Preserves button role\n\n**Platform adaptations:**\n\n- React: Uses a pressed-state web toggle with hover and focus-visible feedback.\n- React: The subtle tone (accent color, no fill) is web-only.\n- SwiftUI: Uses a touch-sized button-backed chip for compact filter selection.\n\n## Related components\n\n- [Toggle Group](/components/component-toggle-group)\n- [Button](/components/component-button)\n- [Checkbox](/components/component-checkbox)\n",
7775
+ "markdown": "# Toggle\n\nToggle is a pressed control for one independently persistent option.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Expose pressed state with a clear label; use Button for one-shot actions.\n- Pair controls with persistent labels and explain errors beside the affected field.\n- Validate focus visibility, disabled state, invalid state, and touch input together.\n\n## Usage\n\n```tsx\nimport { Toggle } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Toggle`\n\n**Types:** `ToggleProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/toggle.json` (`toggleContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `sizes` | `sm`, `md`, `lg` | `md` |\n| `tones` | `neutral`, `accent`, `subtle` | `neutral` |\n\n**Deprecated aliases:** `focus` → `focus-visible` (states)\n\n**Slots:** `toggle`, `toggle-content`\n\n**States:** `off`, `on`, `rest`, `hover`, `pressed`, `disabled`, `focus-visible`\n\n**Token slots:** `toggle.background`, `toggle.foreground`, `toggle.hoverBackground`, `toggle.onBackground`, `toggle.onForeground`, `toggle.primaryBackground`, `toggle.primaryForeground`, `toggle.borderWidth`, `toggle.radius`, `toggle.gloss`, `toggle.shadow`, `toggle.shadowActive`, `toggle.textShadow`\n\n**Visual archetype:** Toggle controls — Persistent on/off or pressed controls.\n\n### Web and iOS\n\nSelect or deselect a compact option without leaving the current context. Rendered by `AtomChip` in SwiftUI, with `platform-adaptive` parity.\n\n**Required states:** `off`, `on`, `disabled`\n\n**Shared outcomes:**\n\n- Selected state is visible\n- Activation toggles selection\n- Disabled prevents change\n\n**Accessibility outcomes:**\n\n- Exposes label\n- Announces selected state\n- Preserves button role\n\n**Platform adaptations:**\n\n- React: Uses a pressed-state web toggle with hover and focus-visible feedback.\n- React: The subtle tone (accent color, no fill) is web-only.\n- SwiftUI: Uses a touch-sized button-backed chip for compact filter selection.\n\n## Related components\n\n- [Toggle Group](/components/component-toggle-group)\n- [Button](/components/component-button)\n- [Checkbox](/components/component-checkbox)\n",
7734
7776
  "related": [
7735
7777
  "toggle-group",
7736
7778
  "button",
@@ -7843,10 +7885,13 @@
7843
7885
  "toggle-group-separator"
7844
7886
  ],
7845
7887
  "source": "packages/ui-foundation/contracts/components/toggle-group.json",
7888
+ "stateAliases": {
7889
+ "focus": "focus-visible"
7890
+ },
7846
7891
  "states": [
7847
7892
  "rest",
7848
7893
  "hover",
7849
- "focus",
7894
+ "focus-visible",
7850
7895
  "selected",
7851
7896
  "disabled"
7852
7897
  ],
@@ -7889,7 +7934,7 @@
7889
7934
  ],
7890
7935
  "importPath": "@atom63/ui-react",
7891
7936
  "label": "Toggle Group",
7892
- "markdown": "# Toggle Group\n\nToggle Group coordinates single or multiple pressed controls on a shared track.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Choose single or multiple selection deliberately and label icon-only items.\n- Pair controls with persistent labels and explain errors beside the affected field.\n- Validate focus visibility, disabled state, invalid state, and touch input together.\n\n## Variants, sizes and states\n\n| Axis | Value | Guidance |\n| --- | --- | --- |\n| Variant | `segmented` | One welded bar for a mode switch (Left / Center / Right). |\n| Variant | `pills` | Separate filled capsules, the selected one solid, for a prominent filter row (Playlists / Artists / Albums). |\n| Variant | `ghost` | Plain text items, only the selected one softly filled, for quiet filters in a toolbar (All / Read / Unread). |\n\n## Usage\n\n```tsx\nimport { ToggleGroup, ToggleGroupItem, ToggleGroupSeparator } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `ToggleGroup`, `ToggleGroupItem`, `ToggleGroupSeparator`\n\n**Types:** `ToggleGroupItemProps`, `ToggleGroupProps`, `ToggleGroupSeparatorProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/toggle-group.json` (`toggleGroupContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `variants` | `segmented`, `pills`, `ghost` | `segmented` |\n| `orientations` | `horizontal`, `vertical` | `horizontal` |\n| `selectionModes` | `single`, `multiple` | `single` |\n\n**Slots:** `toggle-group`, `toggle-group-item`, `toggle-group-separator`\n\n**States:** `rest`, `hover`, `focus`, `selected`, `disabled`\n\n**Token slots:** `segment.gap`, `segment.radius`, `segment.background`, `segment.gloss`, `segment.trackBorder`, `segment.seam`, `segment.selectedBackground`, `segment.selectedForeground`, `segment.selectedGloss`, `segment.selectedShadow`, `segment.primaryBackground`, `segment.primaryForeground`, `segment.primaryShadow`\n\n**Visual archetype:** Toggle controls — Persistent on/off or pressed controls.; Segmented selection — One-of-many peer selections presented as a shared track or grouped row.\n\n### Web and iOS\n\nChoose one or more options from a compact peer group. Rendered by `Picker(.segmented) / AtomGhostToggleGroup` in SwiftUI, with `platform-adaptive` parity.\n\n**Required states:** `rest`, `selected`, `disabled`\n\n**Shared outcomes:**\n\n- Selection state is visible\n- Disabled options cannot change selection\n\n**Accessibility outcomes:**\n\n- Exposes selection\n- Exposes disabled state\n\n**Platform adaptations:**\n\n- React: Supports segmented, pills, and ghost recipes with horizontal or vertical layout.\n- SwiftUI: Uses Picker with segmented style for the joined segmented variant.\n- SwiftUI: Uses AtomGhostToggleGroup with AtomGhostToggleGroupItem for quiet toolbar filters; each item remains a native Button with the selected trait.\n\n## Related components\n\n- [Toggle](/components/component-toggle)\n- [Segmented Control](/components/component-segmented-control)\n- [Button Group](/components/component-button-group)\n",
7937
+ "markdown": "# Toggle Group\n\nToggle Group coordinates single or multiple pressed controls on a shared track.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Choose single or multiple selection deliberately and label icon-only items.\n- Pair controls with persistent labels and explain errors beside the affected field.\n- Validate focus visibility, disabled state, invalid state, and touch input together.\n\n## Variants, sizes and states\n\n| Axis | Value | Guidance |\n| --- | --- | --- |\n| Variant | `segmented` | One welded bar for a mode switch (Left / Center / Right). |\n| Variant | `pills` | Separate filled capsules, the selected one solid, for a prominent filter row (Playlists / Artists / Albums). |\n| Variant | `ghost` | Plain text items, only the selected one softly filled, for quiet filters in a toolbar (All / Read / Unread). |\n\n## Usage\n\n```tsx\nimport { ToggleGroup, ToggleGroupItem, ToggleGroupSeparator } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `ToggleGroup`, `ToggleGroupItem`, `ToggleGroupSeparator`\n\n**Types:** `ToggleGroupItemProps`, `ToggleGroupProps`, `ToggleGroupSeparatorProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/toggle-group.json` (`toggleGroupContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `variants` | `segmented`, `pills`, `ghost` | `segmented` |\n| `orientations` | `horizontal`, `vertical` | `horizontal` |\n| `selectionModes` | `single`, `multiple` | `single` |\n\n**Deprecated aliases:** `focus` → `focus-visible` (states)\n\n**Slots:** `toggle-group`, `toggle-group-item`, `toggle-group-separator`\n\n**States:** `rest`, `hover`, `focus-visible`, `selected`, `disabled`\n\n**Token slots:** `segment.gap`, `segment.radius`, `segment.background`, `segment.gloss`, `segment.trackBorder`, `segment.seam`, `segment.selectedBackground`, `segment.selectedForeground`, `segment.selectedGloss`, `segment.selectedShadow`, `segment.primaryBackground`, `segment.primaryForeground`, `segment.primaryShadow`\n\n**Visual archetype:** Toggle controls — Persistent on/off or pressed controls.; Segmented selection — One-of-many peer selections presented as a shared track or grouped row.\n\n### Web and iOS\n\nChoose one or more options from a compact peer group. Rendered by `Picker(.segmented) / AtomGhostToggleGroup` in SwiftUI, with `platform-adaptive` parity.\n\n**Required states:** `rest`, `selected`, `disabled`\n\n**Shared outcomes:**\n\n- Selection state is visible\n- Disabled options cannot change selection\n\n**Accessibility outcomes:**\n\n- Exposes selection\n- Exposes disabled state\n\n**Platform adaptations:**\n\n- React: Supports segmented, pills, and ghost recipes with horizontal or vertical layout.\n- SwiftUI: Uses Picker with segmented style for the joined segmented variant.\n- SwiftUI: Uses AtomGhostToggleGroup with AtomGhostToggleGroupItem for quiet toolbar filters; each item remains a native Button with the selected trait.\n\n## Related components\n\n- [Toggle](/components/component-toggle)\n- [Segmented Control](/components/component-segmented-control)\n- [Button Group](/components/component-button-group)\n",
7893
7938
  "related": [
7894
7939
  "toggle",
7895
7940
  "segmented-control",
@@ -7951,10 +7996,13 @@
7951
7996
  "breadcrumb-ellipsis"
7952
7997
  ],
7953
7998
  "source": "packages/ui-foundation/contracts/components/breadcrumb.json",
7999
+ "stateAliases": {
8000
+ "focus": "focus-visible"
8001
+ },
7954
8002
  "states": [
7955
8003
  "rest",
7956
8004
  "hover",
7957
- "focus",
8005
+ "focus-visible",
7958
8006
  "current"
7959
8007
  ],
7960
8008
  "tokenSlots": []
@@ -7984,7 +8032,7 @@
7984
8032
  ],
7985
8033
  "importPath": "@atom63/ui-react",
7986
8034
  "label": "Breadcrumb",
7987
- "markdown": "# Breadcrumb\n\nBreadcrumb exposes the current page within a navigable hierarchy.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Mark the final item as the current page and collapse only intermediate levels.\n- Preserve link, menu, command, or selection semantics instead of styling generic containers.\n- Expose current location when applicable and verify alternate input paths at narrow widths.\n\n## Usage\n\n```tsx\nimport { Breadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Breadcrumb`, `BreadcrumbEllipsis`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbList`, `BreadcrumbPage`, `BreadcrumbSeparator`\n\n**Types:** `BreadcrumbLinkProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/breadcrumb.json` (`breadcrumbContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `compositions` | `full`, `collapsed`, `custom-separator` | — |\n\n**Slots:** `breadcrumb`, `breadcrumb-list`, `breadcrumb-item`, `breadcrumb-link`, `breadcrumb-page`, `breadcrumb-separator`, `breadcrumb-ellipsis`\n\n**States:** `rest`, `hover`, `focus`, `current`\n\n## Related components\n\n- [Pagination](/components/component-pagination)\n- [Navigation Menu](/components/component-navigation-menu)\n- [Sidebar Nav Tree](/components/component-sidebar-nav-tree)\n",
8035
+ "markdown": "# Breadcrumb\n\nBreadcrumb exposes the current page within a navigable hierarchy.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Mark the final item as the current page and collapse only intermediate levels.\n- Preserve link, menu, command, or selection semantics instead of styling generic containers.\n- Expose current location when applicable and verify alternate input paths at narrow widths.\n\n## Usage\n\n```tsx\nimport { Breadcrumb, BreadcrumbList, BreadcrumbItem, BreadcrumbLink, BreadcrumbPage } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Breadcrumb`, `BreadcrumbEllipsis`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbList`, `BreadcrumbPage`, `BreadcrumbSeparator`\n\n**Types:** `BreadcrumbLinkProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/breadcrumb.json` (`breadcrumbContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `compositions` | `full`, `collapsed`, `custom-separator` | — |\n\n**Deprecated aliases:** `focus` → `focus-visible` (states)\n\n**Slots:** `breadcrumb`, `breadcrumb-list`, `breadcrumb-item`, `breadcrumb-link`, `breadcrumb-page`, `breadcrumb-separator`, `breadcrumb-ellipsis`\n\n**States:** `rest`, `hover`, `focus-visible`, `current`\n\n## Related components\n\n- [Pagination](/components/component-pagination)\n- [Navigation Menu](/components/component-navigation-menu)\n- [Sidebar Nav Tree](/components/component-sidebar-nav-tree)\n",
7988
8036
  "related": [
7989
8037
  "pagination",
7990
8038
  "navigation-menu",
@@ -8596,10 +8644,13 @@
8596
8644
  "navigation-menu-indicator"
8597
8645
  ],
8598
8646
  "source": "packages/ui-foundation/contracts/components/navigation-menu.json",
8647
+ "stateAliases": {
8648
+ "active": "current"
8649
+ },
8599
8650
  "states": [
8600
8651
  "closed",
8601
8652
  "open",
8602
- "active",
8653
+ "current",
8603
8654
  "disabled",
8604
8655
  "starting",
8605
8656
  "ending"
@@ -8635,7 +8686,7 @@
8635
8686
  ],
8636
8687
  "importPath": "@atom63/ui-react",
8637
8688
  "label": "Navigation Menu",
8638
- "markdown": "# Navigation Menu\n\nNavigation Menu composes site links with optional positioned navigation panels.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Keep link semantics intact and avoid putting command-style actions in the navigation hierarchy.\n- Preserve link, menu, command, or selection semantics instead of styling generic containers.\n- Expose current location when applicable and verify alternate input paths at narrow widths.\n\n## Usage\n\n```tsx\nimport { NavigationMenu, NavigationMenuList, NavigationMenuItem, NavigationMenuTrigger, NavigationMenuContent } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `NavigationMenu`, `NavigationMenuContent`, `NavigationMenuIndicator`, `NavigationMenuItem`, `NavigationMenuLink`, `NavigationMenuList`, `NavigationMenuPositioner`, `NavigationMenuTrigger`, `NavigationMenuViewport`, `navigationMenuTriggerStyle`\n\n**Types:** `NavigationMenuPositionerProps`, `NavigationMenuProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/navigation-menu.json` (`navigationMenuContract` in `@atom63/ui-foundation`).\n\n**Slots:** `navigation-menu`, `navigation-menu-list`, `navigation-menu-item`, `navigation-menu-trigger`, `navigation-menu-content`, `navigation-menu-portal`, `navigation-menu-positioner`, `navigation-menu-popup`, `navigation-menu-viewport`, `navigation-menu-link`, `navigation-menu-indicator`\n\n**States:** `closed`, `open`, `active`, `disabled`, `starting`, `ending`\n\n**Visual archetype:** Triggers — Controls whose primary job is to open another surface.; Overlay surfaces — Floating material above the page or current surface.; Static content surfaces — In-flow containers and content surfaces that do not inherently manipulate state.\n\n## Related components\n\n- [Menubar](/components/component-menubar)\n- [Breadcrumb](/components/component-breadcrumb)\n- [Dropdown Menu](/components/component-dropdown-menu)\n",
8689
+ "markdown": "# Navigation Menu\n\nNavigation Menu composes site links with optional positioned navigation panels.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Keep link semantics intact and avoid putting command-style actions in the navigation hierarchy.\n- Preserve link, menu, command, or selection semantics instead of styling generic containers.\n- Expose current location when applicable and verify alternate input paths at narrow widths.\n\n## Usage\n\n```tsx\nimport { NavigationMenu, NavigationMenuList, NavigationMenuItem, NavigationMenuTrigger, NavigationMenuContent } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `NavigationMenu`, `NavigationMenuContent`, `NavigationMenuIndicator`, `NavigationMenuItem`, `NavigationMenuLink`, `NavigationMenuList`, `NavigationMenuPositioner`, `NavigationMenuTrigger`, `NavigationMenuViewport`, `navigationMenuTriggerStyle`\n\n**Types:** `NavigationMenuPositionerProps`, `NavigationMenuProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/navigation-menu.json` (`navigationMenuContract` in `@atom63/ui-foundation`).\n\n**Deprecated aliases:** `active` → `current` (states)\n\n**Slots:** `navigation-menu`, `navigation-menu-list`, `navigation-menu-item`, `navigation-menu-trigger`, `navigation-menu-content`, `navigation-menu-portal`, `navigation-menu-positioner`, `navigation-menu-popup`, `navigation-menu-viewport`, `navigation-menu-link`, `navigation-menu-indicator`\n\n**States:** `closed`, `open`, `current`, `disabled`, `starting`, `ending`\n\n**Visual archetype:** Triggers — Controls whose primary job is to open another surface.; Overlay surfaces — Floating material above the page or current surface.; Static content surfaces — In-flow containers and content surfaces that do not inherently manipulate state.\n\n## Related components\n\n- [Menubar](/components/component-menubar)\n- [Breadcrumb](/components/component-breadcrumb)\n- [Dropdown Menu](/components/component-dropdown-menu)\n",
8639
8690
  "related": [
8640
8691
  "menubar",
8641
8692
  "breadcrumb",
@@ -9014,10 +9065,13 @@
9014
9065
  "exportName": "sidebarNavTreeContract",
9015
9066
  "slots": [],
9016
9067
  "source": "packages/ui-foundation/contracts/components/sidebar-nav-tree.json",
9068
+ "stateAliases": {
9069
+ "active": "current"
9070
+ },
9017
9071
  "states": [
9018
9072
  "rest",
9019
9073
  "hover",
9020
- "active",
9074
+ "current",
9021
9075
  "expanded",
9022
9076
  "collapsed",
9023
9077
  "focus-visible"
@@ -9051,7 +9105,7 @@
9051
9105
  ],
9052
9106
  "importPath": "@atom63/ui-react",
9053
9107
  "label": "Sidebar Nav Tree",
9054
- "markdown": "# Sidebar Nav Tree\n\nSidebar Nav Tree composes labelled navigation groups that can fold, links, sublists, and collapsible sections with icons.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Preserve link semantics and expose the current route independently from expanded branch state. Give SidebarNavLinkItem href and icon (or a router link as render) instead of a child element; a link component you pass as the child or as render must spread the props it receives onto the element it renders and forward its ref.\n- Preserve link, menu, command, or selection semantics instead of styling generic containers.\n- Expose current location when applicable and verify alternate input paths at narrow widths.\n\n## Usage\n\n```tsx\nimport { SidebarNavGroup, SidebarNavLinkItem, SidebarNavCollapsibleItem } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `SidebarNavCollapsibleItem`, `SidebarNavGroup`, `SidebarNavLinkItem`, `SidebarNavSubLinkItem`, `SidebarNavSubList`\n\n**Types:** `SidebarNavCollapsibleItemProps`, `SidebarNavGroupProps`, `SidebarNavLinkItemProps`, `SidebarNavSubLinkItemProps`, `SidebarNavSubListProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/sidebar-nav-tree.json` (`sidebarNavTreeContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `parts` | `group`, `group-trigger`, `link-item`, `collapsible-item`, `toggle`, `sub-list`, `sub-link-item` | — |\n| `tones` | `neutral`, `accent` | `neutral` |\n\n**States:** `rest`, `hover`, `active`, `expanded`, `collapsed`, `focus-visible`\n\n**Visual archetype:** Action controls — Momentary controls that perform an action now.; Triggers — Controls whose primary job is to open another surface.\n\n## Related components\n\n- [Sidebar](/components/component-sidebar)\n- [Breadcrumb](/components/component-breadcrumb)\n- [Collapsible](/components/component-collapsible)\n",
9108
+ "markdown": "# Sidebar Nav Tree\n\nSidebar Nav Tree composes labelled navigation groups that can fold, links, sublists, and collapsible sections with icons.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Preserve link semantics and expose the current route independently from expanded branch state. Give SidebarNavLinkItem href and icon (or a router link as render) instead of a child element; a link component you pass as the child or as render must spread the props it receives onto the element it renders and forward its ref.\n- Preserve link, menu, command, or selection semantics instead of styling generic containers.\n- Expose current location when applicable and verify alternate input paths at narrow widths.\n\n## Usage\n\n```tsx\nimport { SidebarNavGroup, SidebarNavLinkItem, SidebarNavCollapsibleItem } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `SidebarNavCollapsibleItem`, `SidebarNavGroup`, `SidebarNavLinkItem`, `SidebarNavSubLinkItem`, `SidebarNavSubList`\n\n**Types:** `SidebarNavCollapsibleItemProps`, `SidebarNavGroupProps`, `SidebarNavLinkItemProps`, `SidebarNavSubLinkItemProps`, `SidebarNavSubListProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/sidebar-nav-tree.json` (`sidebarNavTreeContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `parts` | `group`, `group-trigger`, `link-item`, `collapsible-item`, `toggle`, `sub-list`, `sub-link-item` | — |\n| `tones` | `neutral`, `accent` | `neutral` |\n\n**Deprecated aliases:** `active` → `current` (states)\n\n**States:** `rest`, `hover`, `current`, `expanded`, `collapsed`, `focus-visible`\n\n**Visual archetype:** Action controls — Momentary controls that perform an action now.; Triggers — Controls whose primary job is to open another surface.\n\n## Related components\n\n- [Sidebar](/components/component-sidebar)\n- [Breadcrumb](/components/component-breadcrumb)\n- [Collapsible](/components/component-collapsible)\n",
9055
9109
  "related": [
9056
9110
  "sidebar",
9057
9111
  "breadcrumb",
@@ -9123,10 +9177,13 @@
9123
9177
  "values": [
9124
9178
  "xs",
9125
9179
  "sm",
9126
- "default",
9180
+ "md",
9127
9181
  "lg"
9128
9182
  ],
9129
- "default": "default"
9183
+ "deprecatedAliases": {
9184
+ "default": "md"
9185
+ },
9186
+ "default": "md"
9130
9187
  },
9131
9188
  {
9132
9189
  "name": "orientations",
@@ -9216,7 +9273,7 @@
9216
9273
  ],
9217
9274
  "importPath": "@atom63/ui-react",
9218
9275
  "label": "Tabs",
9219
- "markdown": "# Tabs\n\nTabs coordinate one active panel, its tab list, keyboard behavior, and indicator.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Use tabs for peer panels in one task; use navigation links when the destination has its own URL.\n- Preserve link, menu, command, or selection semantics instead of styling generic containers.\n- Expose current location when applicable and verify alternate input paths at narrow widths.\n\n## Usage\n\n```tsx\nimport { Tabs, TabsList, TabsTab, TabsPanel } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Tabs`, `TabsContent`, `TabsList`, `TabsPanel`, `TabsTab`, `TabsTrigger`\n\n**Types:** `TabsListProps`, `TabsPanelProps`, `TabsTabProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/tabs.json` (`tabsContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `variants` | `default`, `underline`, `attached` | `default` |\n| `sizes` | `xs`, `sm`, `default`, `lg` | `default` |\n| `orientations` | `horizontal`, `vertical` | — |\n\n**Slots:** `tabs`, `tabs-list`, `tabs-tab`, `tab-indicator`, `tabs-content`\n\n**States:** `rest`, `hover`, `selected`, `focus-visible`, `disabled`\n\n**Visual archetype:** Segmented selection — One-of-many peer selections presented as a shared track or grouped row.; Static content surfaces — In-flow containers and content surfaces that do not inherently manipulate state.\n\n**Accessibility pattern:** [Tabs](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/) (activation: manual)\n\n### Web and iOS\n\nSwitch between peer destinations or content views while keeping one selection active. Rendered by `Picker(.segmented) / AtomTabRow` in SwiftUI, with `platform-adaptive` parity.\n\n**SwiftUI renderer per variant:**\n\n- `default`: `Picker(.segmented)`\n- `underline`: `AtomTabRow`\n- `attached`: `AtomTabRow`\n\n**Required states:** `rest`, `selected`\n\n**Shared outcomes:**\n\n- One tab is selected at a time\n- Selection reveals the associated content\n- Selected tab remains visually distinguishable\n\n**Accessibility outcomes:**\n\n- Exposes tab labels\n- Exposes selected state\n- Associates selection with visible content\n\n**Platform adaptations:**\n\n- React: Uses tablist, tab, and tabpanel semantics with keyboard navigation and a visual indicator.\n- SwiftUI: The default variant is a segmented Picker above the content it selects, for a short second-level filter of two to four options.\n- SwiftUI: The underline variant is AtomTabRow, a row of text tabs over the content it selects: the selected tab reads text-primary over an accent bar, the others text-secondary. The row scrolls sideways when the tabs do not fit and keeps the selected tab in view. Each tab can show an SF Symbol over its label. The bar slides to the new tab, and jumps under Reduce Motion. Each tab is a named button with the selected trait inside a tab-bar container, and the row mirrors in right-to-left languages.\n- SwiftUI: The attached variant also renders as AtomTabRow: folder tabs are a pointer idiom with no iOS counterpart, and the underline row already sits flush on the content it selects.\n- SwiftUI: TabView stays the renderer for app-level sections such as a tab bar or sidebar.\n- SwiftUI: In a TabView, each tab's root is its ScrollView or List. From iOS 26 the glass tab bar floats over it: content scrolls under the bar at rest, and TabView insets the scroll content so the last row ends above the bar. Do not pad for the bar, draw content in a ZStack or overlay over the TabView, or apply ignoresSafeArea to the bottom edge; extra bottom chrome goes in safeAreaInset(edge: .bottom) on the tab's root.\n\n## Related components\n\n- [Segmented Control](/components/component-segmented-control)\n- [Collapsible](/components/component-collapsible)\n- [Navigation Menu](/components/component-navigation-menu)\n",
9276
+ "markdown": "# Tabs\n\nTabs coordinate one active panel, its tab list, keyboard behavior, and indicator.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Use tabs for peer panels in one task; use navigation links when the destination has its own URL.\n- Preserve link, menu, command, or selection semantics instead of styling generic containers.\n- Expose current location when applicable and verify alternate input paths at narrow widths.\n\n## Usage\n\n```tsx\nimport { Tabs, TabsList, TabsTab, TabsPanel } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Tabs`, `TabsContent`, `TabsList`, `TabsPanel`, `TabsTab`, `TabsTrigger`\n\n**Types:** `TabsListProps`, `TabsPanelProps`, `TabsTabProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/tabs.json` (`tabsContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `variants` | `default`, `underline`, `attached` | `default` |\n| `sizes` | `xs`, `sm`, `md`, `lg` | `md` |\n| `orientations` | `horizontal`, `vertical` | — |\n\n**Deprecated aliases:** `default` → `md` (sizes)\n\n**Slots:** `tabs`, `tabs-list`, `tabs-tab`, `tab-indicator`, `tabs-content`\n\n**States:** `rest`, `hover`, `selected`, `focus-visible`, `disabled`\n\n**Visual archetype:** Segmented selection — One-of-many peer selections presented as a shared track or grouped row.; Static content surfaces — In-flow containers and content surfaces that do not inherently manipulate state.\n\n**Accessibility pattern:** [Tabs](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/) (activation: manual)\n\n### Web and iOS\n\nSwitch between peer destinations or content views while keeping one selection active. Rendered by `Picker(.segmented) / AtomTabRow` in SwiftUI, with `platform-adaptive` parity.\n\n**SwiftUI renderer per variant:**\n\n- `default`: `Picker(.segmented)`\n- `underline`: `AtomTabRow`\n- `attached`: `AtomTabRow`\n\n**Required states:** `rest`, `selected`\n\n**Shared outcomes:**\n\n- One tab is selected at a time\n- Selection reveals the associated content\n- Selected tab remains visually distinguishable\n\n**Accessibility outcomes:**\n\n- Exposes tab labels\n- Exposes selected state\n- Associates selection with visible content\n\n**Platform adaptations:**\n\n- React: Uses tablist, tab, and tabpanel semantics with keyboard navigation and a visual indicator.\n- SwiftUI: The default variant is a segmented Picker above the content it selects, for a short second-level filter of two to four options.\n- SwiftUI: The underline variant is AtomTabRow, a row of text tabs over the content it selects: the selected tab reads text-primary over an accent bar, the others text-secondary. The row scrolls sideways when the tabs do not fit and keeps the selected tab in view. Each tab can show an SF Symbol over its label. The bar slides to the new tab, and jumps under Reduce Motion. Each tab is a named button with the selected trait inside a tab-bar container, and the row mirrors in right-to-left languages.\n- SwiftUI: The attached variant also renders as AtomTabRow: folder tabs are a pointer idiom with no iOS counterpart, and the underline row already sits flush on the content it selects.\n- SwiftUI: TabView stays the renderer for app-level sections such as a tab bar or sidebar.\n- SwiftUI: In a TabView, each tab's root is its ScrollView or List. From iOS 26 the glass tab bar floats over it: content scrolls under the bar at rest, and TabView insets the scroll content so the last row ends above the bar. Do not pad for the bar, draw content in a ZStack or overlay over the TabView, or apply ignoresSafeArea to the bottom edge; extra bottom chrome goes in safeAreaInset(edge: .bottom) on the tab's root.\n\n## Related components\n\n- [Segmented Control](/components/component-segmented-control)\n- [Collapsible](/components/component-collapsible)\n- [Navigation Menu](/components/component-navigation-menu)\n",
9220
9277
  "related": [
9221
9278
  "segmented-control",
9222
9279
  "collapsible",
@@ -9230,6 +9287,7 @@
9230
9287
  "names": [
9231
9288
  "Playground",
9232
9289
  "Variants",
9290
+ "Vertical",
9233
9291
  "ForcedColors",
9234
9292
  "Attached",
9235
9293
  "Sizes",
@@ -9238,7 +9296,7 @@
9238
9296
  "Endpoints",
9239
9297
  "ContractMetadata"
9240
9298
  ],
9241
- "source": "import { tabsContract, tabsSizes, tabsVariants, themes } from '@atom63/ui-foundation'\nimport { Tabs, TabsList, TabsPanel, TabsTab, UIProvider } from '@atom63/ui-react'\nimport '@atom63/ui-react/styles.css'\nimport type { Meta, StoryObj } from '@storybook/react-vite'\n\nconst meta = {\n title: 'UI React/Tabs',\n component: Tabs,\n} satisfies Meta<typeof Tabs>\n\nexport default meta\ntype Story = StoryObj<typeof meta>\n\nconst PANEL_STYLE = { color: 'var(--a63-text-secondary)', fontSize: 14, paddingTop: 8 }\n\nexport const Playground: Story = {\n render: () => (\n <Tabs defaultValue=\"overview\">\n <TabsList aria-label=\"Product details\">\n <TabsTab value=\"overview\">Overview</TabsTab>\n <TabsTab value=\"specs\">Specs</TabsTab>\n <TabsTab value=\"reviews\">Reviews</TabsTab>\n </TabsList>\n <TabsPanel style={PANEL_STYLE} value=\"overview\">\n Overview content\n </TabsPanel>\n <TabsPanel style={PANEL_STYLE} value=\"specs\">\n Specs content\n </TabsPanel>\n <TabsPanel style={PANEL_STYLE} value=\"reviews\">\n Reviews content\n </TabsPanel>\n </Tabs>\n ),\n}\n\nexport const Variants: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 24 }}>\n {tabsVariants.map(variant => (\n <div key={variant}>\n <p style={{ color: 'var(--a63-text-secondary)', fontSize: 12, marginBottom: 8 }}>\n {variant}\n </p>\n <Tabs defaultValue=\"one\">\n <TabsList variant={variant}>\n <TabsTab value=\"one\">First</TabsTab>\n <TabsTab value=\"two\">Second</TabsTab>\n <TabsTab value=\"three\">Third</TabsTab>\n </TabsList>\n </Tabs>\n </div>\n ))}\n </div>\n ),\n}\n\n/* Captured with forced colors on (Windows High Contrast): the selected tab of\n every variant takes the system selection colours. */\nexport const ForcedColors: Story = { render: Variants.render }\n\n/* attached — the connected \"folder\": the tab row sits flush on a card panel\n body, and the active tab merges into it (no bottom border, shares the panel\n surface). Only reads with a panel present, which Variants omits. */\nexport const Attached: Story = {\n render: () => (\n <Tabs defaultValue=\"overview\" style={{ maxWidth: 460 }}>\n <TabsList variant=\"attached\">\n <TabsTab value=\"overview\">Overview</TabsTab>\n <TabsTab value=\"specs\">Specs</TabsTab>\n <TabsTab value=\"reviews\">Reviews</TabsTab>\n </TabsList>\n <TabsPanel value=\"overview\">\n The active tab connects into this card panel — one continuous folder shape.\n </TabsPanel>\n <TabsPanel value=\"specs\">Specs content.</TabsPanel>\n <TabsPanel value=\"reviews\">Reviews content.</TabsPanel>\n </Tabs>\n ),\n}\n\nexport const Sizes: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 16 }}>\n {tabsSizes.map(size => (\n <Tabs defaultValue=\"one\" key={size}>\n <TabsList size={size}>\n <TabsTab value=\"one\">List</TabsTab>\n <TabsTab value=\"two\">Grid</TabsTab>\n </TabsList>\n </Tabs>\n ))}\n </div>\n ),\n}\n\nexport const MobileOverflow: Story = {\n tags: ['!manifest'],\n render: () => (\n <UIProvider input=\"touch\">\n <div style={{ maxWidth: 320, width: 'min(100%, calc(100vw - 2rem))' }}>\n <Tabs defaultValue=\"overview\">\n <TabsList>\n <TabsTab value=\"overview\">Project overview</TabsTab>\n <TabsTab value=\"activity\">Recent activity</TabsTab>\n <TabsTab value=\"permissions\">Access permissions</TabsTab>\n <TabsTab value=\"integrations\">Connected integrations</TabsTab>\n </TabsList>\n </Tabs>\n </div>\n </UIProvider>\n ),\n}\n\nexport const Themes: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12 }}>\n {themes.map(theme =>\n (['light', 'dark'] as const).map(mode => (\n <UIProvider key={`${theme}-${mode}`} mode={mode} theme={theme}>\n <div\n style={{\n alignItems: 'center',\n background: 'var(--a63-surface-panel)',\n borderRadius: 'var(--radius-lg)',\n color: 'var(--a63-text-primary)',\n display: 'flex',\n gap: 12,\n padding: '0.75rem',\n }}\n >\n <span style={{ fontSize: 12, color: 'var(--a63-text-secondary)', width: 96 }}>\n {theme} / {mode}\n </span>\n <Tabs defaultValue=\"one\">\n <TabsList variant=\"default\">\n <TabsTab value=\"one\">First</TabsTab>\n <TabsTab value=\"two\">Second</TabsTab>\n </TabsList>\n </Tabs>\n <Tabs defaultValue=\"one\">\n <TabsList variant=\"underline\">\n <TabsTab value=\"one\">First</TabsTab>\n <TabsTab value=\"two\">Second</TabsTab>\n </TabsList>\n </Tabs>\n </div>\n </UIProvider>\n ))\n )}\n </div>\n ),\n}\n\n/* Contract probe — remaps the control + surface + track contracts live. */\nexport const Endpoints: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12 }}>\n <UIProvider designLanguage=\"web\" input=\"pointer\">\n <EndpointTabs label=\"Web\" />\n </UIProvider>\n <UIProvider designLanguage=\"ios\" input=\"touch\">\n <EndpointTabs label=\"iOS touch\" />\n </UIProvider>\n <UIProvider density=\"compact\">\n <EndpointTabs label=\"Compact extension\" />\n </UIProvider>\n </div>\n ),\n}\n\nfunction EndpointTabs({ label }: { label: string }) {\n return (\n <div\n style={{\n background: 'var(--a63-surface-panel)',\n color: 'var(--a63-text-primary)',\n display: 'grid',\n gap: 8,\n padding: 12,\n }}\n >\n <span style={{ color: 'var(--a63-text-secondary)', fontSize: 12 }}>{label}</span>\n <Tabs defaultValue=\"one\">\n <TabsList>\n <TabsTab value=\"one\">First</TabsTab>\n <TabsTab value=\"two\">Second</TabsTab>\n </TabsList>\n </Tabs>\n </div>\n )\n}\n\nexport const ContractMetadata: Story = {\n render: () => (\n <pre style={{ fontSize: 12, margin: 0, whiteSpace: 'pre-wrap' }}>\n {JSON.stringify(tabsContract, null, 2)}\n </pre>\n ),\n}\n"
9299
+ "source": "import { tabsContract, tabsSizes, tabsVariants, themes } from '@atom63/ui-foundation'\nimport { Tabs, TabsList, TabsPanel, TabsTab, UIProvider } from '@atom63/ui-react'\nimport '@atom63/ui-react/styles.css'\nimport type { Meta, StoryObj } from '@storybook/react-vite'\n\nconst meta = {\n title: 'UI React/Tabs',\n component: Tabs,\n} satisfies Meta<typeof Tabs>\n\nexport default meta\ntype Story = StoryObj<typeof meta>\n\nconst PANEL_STYLE = { color: 'var(--a63-text-secondary)', fontSize: 14, paddingTop: 8 }\n\nexport const Playground: Story = {\n render: () => (\n <Tabs defaultValue=\"overview\">\n <TabsList aria-label=\"Product details\">\n <TabsTab value=\"overview\">Overview</TabsTab>\n <TabsTab value=\"specs\">Specs</TabsTab>\n <TabsTab value=\"reviews\">Reviews</TabsTab>\n </TabsList>\n <TabsPanel style={PANEL_STYLE} value=\"overview\">\n Overview content\n </TabsPanel>\n <TabsPanel style={PANEL_STYLE} value=\"specs\">\n Specs content\n </TabsPanel>\n <TabsPanel style={PANEL_STYLE} value=\"reviews\">\n Reviews content\n </TabsPanel>\n </Tabs>\n ),\n}\n\nexport const Variants: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 24 }}>\n {tabsVariants.map(variant => (\n <div key={variant}>\n <p style={{ color: 'var(--a63-text-secondary)', fontSize: 12, marginBottom: 8 }}>\n {variant}\n </p>\n <Tabs defaultValue=\"one\">\n <TabsList variant={variant}>\n <TabsTab value=\"one\">First</TabsTab>\n <TabsTab value=\"two\">Second</TabsTab>\n <TabsTab value=\"three\">Third</TabsTab>\n </TabsList>\n </Tabs>\n </div>\n ))}\n </div>\n ),\n}\n\n/* Vertical orientation: the default track grows with its stacked tabs and the\n raised plate slides vertically to the selected tab; the underline bar moves\n to the inline end. The play function checks the plate follows a click. */\nexport const Vertical: Story = {\n render: () => (\n <div style={{ display: 'flex', gap: 32, alignItems: 'flex-start' }}>\n {(['default', 'underline'] as const).map(variant => (\n <Tabs defaultValue=\"overview\" key={variant} orientation=\"vertical\">\n <TabsList aria-label={`Settings (${variant})`} variant={variant}>\n <TabsTab value=\"overview\">Overview</TabsTab>\n <TabsTab value=\"specs\">Specs</TabsTab>\n <TabsTab value=\"reviews\">Reviews</TabsTab>\n </TabsList>\n <TabsPanel style={PANEL_STYLE} value=\"overview\">\n Overview content\n </TabsPanel>\n <TabsPanel style={PANEL_STYLE} value=\"specs\">\n Specs content\n </TabsPanel>\n <TabsPanel style={PANEL_STYLE} value=\"reviews\">\n Reviews content\n </TabsPanel>\n </Tabs>\n ))}\n </div>\n ),\n play: async ({ canvasElement }) => {\n const list = canvasElement.querySelector<HTMLElement>('.a63-Tabs-list[data-variant=\"default\"]')\n if (!list) throw new Error('Expected the default vertical list')\n const tabs = list.querySelectorAll<HTMLElement>('.a63-Tabs-tab')\n const indicator = list.querySelector<HTMLElement>('.a63-Tabs-indicator')\n if (tabs.length !== 3 || !indicator) throw new Error('Expected three tabs and an indicator')\n const listRect = list.getBoundingClientRect()\n const lastRect = tabs[2].getBoundingClientRect()\n if (lastRect.bottom > listRect.bottom + 0.5) {\n throw new Error(\n `Expected the track to contain every tab (tab bottom ${lastRect.bottom}, track bottom ${listRect.bottom})`\n )\n }\n for (const index of [2, 1, 0]) {\n tabs[index].click()\n await new Promise(resolve => setTimeout(resolve, 50))\n await Promise.all(indicator.getAnimations().map(animation => animation.finished))\n const tab = tabs[index].getBoundingClientRect()\n const plate = indicator.getBoundingClientRect()\n if (Math.abs(plate.top - tab.top) > 1 || Math.abs(plate.height - tab.height) > 1) {\n throw new Error(\n `Expected the indicator to cover tab ${index} (tab top ${tab.top}, indicator top ${plate.top})`\n )\n }\n }\n },\n}\n\n/* Captured with forced colors on (Windows High Contrast): the selected tab of\n every variant takes the system selection colours. */\nexport const ForcedColors: Story = { render: Variants.render }\n\n/* attached — the connected \"folder\": the tab row sits flush on a card panel\n body, and the active tab merges into it (no bottom border, shares the panel\n surface). Only reads with a panel present, which Variants omits. */\nexport const Attached: Story = {\n render: () => (\n <Tabs defaultValue=\"overview\" style={{ maxWidth: 460 }}>\n <TabsList variant=\"attached\">\n <TabsTab value=\"overview\">Overview</TabsTab>\n <TabsTab value=\"specs\">Specs</TabsTab>\n <TabsTab value=\"reviews\">Reviews</TabsTab>\n </TabsList>\n <TabsPanel value=\"overview\">\n The active tab connects into this card panel — one continuous folder shape.\n </TabsPanel>\n <TabsPanel value=\"specs\">Specs content.</TabsPanel>\n <TabsPanel value=\"reviews\">Reviews content.</TabsPanel>\n </Tabs>\n ),\n}\n\nexport const Sizes: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 16 }}>\n {tabsSizes.map(size => (\n <Tabs defaultValue=\"one\" key={size}>\n <TabsList size={size}>\n <TabsTab value=\"one\">List</TabsTab>\n <TabsTab value=\"two\">Grid</TabsTab>\n </TabsList>\n </Tabs>\n ))}\n </div>\n ),\n}\n\nexport const MobileOverflow: Story = {\n tags: ['!manifest'],\n render: () => (\n <UIProvider input=\"touch\">\n <div style={{ maxWidth: 320, width: 'min(100%, calc(100vw - 2rem))' }}>\n <Tabs defaultValue=\"overview\">\n <TabsList>\n <TabsTab value=\"overview\">Project overview</TabsTab>\n <TabsTab value=\"activity\">Recent activity</TabsTab>\n <TabsTab value=\"permissions\">Access permissions</TabsTab>\n <TabsTab value=\"integrations\">Connected integrations</TabsTab>\n </TabsList>\n </Tabs>\n </div>\n </UIProvider>\n ),\n}\n\nexport const Themes: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12 }}>\n {themes.map(theme =>\n (['light', 'dark'] as const).map(mode => (\n <UIProvider key={`${theme}-${mode}`} mode={mode} theme={theme}>\n <div\n style={{\n alignItems: 'center',\n background: 'var(--a63-surface-panel)',\n borderRadius: 'var(--radius-lg)',\n color: 'var(--a63-text-primary)',\n display: 'flex',\n gap: 12,\n padding: '0.75rem',\n }}\n >\n <span style={{ fontSize: 12, color: 'var(--a63-text-secondary)', width: 96 }}>\n {theme} / {mode}\n </span>\n <Tabs defaultValue=\"one\">\n <TabsList variant=\"default\">\n <TabsTab value=\"one\">First</TabsTab>\n <TabsTab value=\"two\">Second</TabsTab>\n </TabsList>\n </Tabs>\n <Tabs defaultValue=\"one\">\n <TabsList variant=\"underline\">\n <TabsTab value=\"one\">First</TabsTab>\n <TabsTab value=\"two\">Second</TabsTab>\n </TabsList>\n </Tabs>\n <Tabs defaultValue=\"two\" orientation=\"vertical\">\n <TabsList variant=\"default\">\n <TabsTab value=\"one\">First</TabsTab>\n <TabsTab value=\"two\">Second</TabsTab>\n </TabsList>\n </Tabs>\n </div>\n </UIProvider>\n ))\n )}\n </div>\n ),\n}\n\n/* Contract probe — remaps the control + surface + track contracts live. */\nexport const Endpoints: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12 }}>\n <UIProvider designLanguage=\"web\" input=\"pointer\">\n <EndpointTabs label=\"Web\" />\n </UIProvider>\n <UIProvider designLanguage=\"ios\" input=\"touch\">\n <EndpointTabs label=\"iOS touch\" />\n </UIProvider>\n <UIProvider density=\"compact\">\n <EndpointTabs label=\"Compact extension\" />\n </UIProvider>\n </div>\n ),\n}\n\nfunction EndpointTabs({ label }: { label: string }) {\n return (\n <div\n style={{\n background: 'var(--a63-surface-panel)',\n color: 'var(--a63-text-primary)',\n display: 'grid',\n gap: 8,\n padding: 12,\n }}\n >\n <span style={{ color: 'var(--a63-text-secondary)', fontSize: 12 }}>{label}</span>\n <Tabs defaultValue=\"one\">\n <TabsList>\n <TabsTab value=\"one\">First</TabsTab>\n <TabsTab value=\"two\">Second</TabsTab>\n </TabsList>\n </Tabs>\n </div>\n )\n}\n\nexport const ContractMetadata: Story = {\n render: () => (\n <pre style={{ fontSize: 12, margin: 0, whiteSpace: 'pre-wrap' }}>\n {JSON.stringify(tabsContract, null, 2)}\n </pre>\n ),\n}\n"
9242
9300
  },
9243
9301
  "summary": "Tabs coordinate one active panel, its tab list, keyboard behavior, and indicator.",
9244
9302
  "usage": "Use tabs for peer panels in one task; use navigation links when the destination has its own URL.",
@@ -9292,20 +9350,26 @@
9292
9350
  {
9293
9351
  "name": "sizes",
9294
9352
  "values": [
9295
- "default",
9353
+ "md",
9296
9354
  "sm"
9297
9355
  ],
9298
- "default": "default"
9356
+ "deprecatedAliases": {
9357
+ "default": "md"
9358
+ },
9359
+ "default": "md"
9299
9360
  },
9300
9361
  {
9301
9362
  "name": "variants",
9302
9363
  "values": [
9303
9364
  "default",
9304
- "destructive",
9365
+ "error",
9305
9366
  "info",
9306
9367
  "success",
9307
9368
  "warning"
9308
9369
  ],
9370
+ "deprecatedAliases": {
9371
+ "destructive": "error"
9372
+ },
9309
9373
  "default": "default"
9310
9374
  }
9311
9375
  ],
@@ -9393,7 +9457,7 @@
9393
9457
  ],
9394
9458
  "importPath": "@atom63/ui-react",
9395
9459
  "label": "Alert Dialog",
9396
- "markdown": "# Alert Dialog\n\nAlert Dialog interrupts a flow to confirm a consequential decision.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Reserve it for decisions that need explicit acknowledgement, not routine information.\n- When the family opens a surface, preserve its focus, Escape, and dismissal semantics.\n- Check portal placement, stacking, and small-viewport containment in the consuming product.\n\n## Usage\n\n```tsx\nimport { AlertDialog, AlertDialogTrigger, AlertDialogContent, AlertDialogAction } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `AlertDialog`, `AlertDialogAction`, `AlertDialogBackdrop`, `AlertDialogCancel`, `AlertDialogClose`, `AlertDialogContent`, `AlertDialogCreateHandle`, `AlertDialogDescription`, `AlertDialogFooter`, `AlertDialogHeader`, `AlertDialogMedia`, `AlertDialogOverlay`, `AlertDialogPopup`, `AlertDialogPortal`, `AlertDialogPrimitive`, `AlertDialogTitle`, `AlertDialogTrigger`, `AlertDialogViewport`\n\n**Types:** None.\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/alert-dialog.json` (`alertDialogContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `footerVariants` | `default`, `bare` | `default` |\n| `sizes` | `default`, `sm` | `default` |\n| `variants` | `default`, `destructive`, `info`, `success`, `warning` | `default` |\n\n**Slots:** `alert-dialog-portal`, `alert-dialog-trigger`, `alert-dialog-backdrop`, `alert-dialog-viewport`, `alert-dialog-popup`, `alert-dialog-header`, `alert-dialog-footer`, `alert-dialog-media`, `alert-dialog-title`, `alert-dialog-description`, `alert-dialog-close`, `alert-dialog-action`, `alert-dialog-cancel`\n\n**States:** `closed`, `open`\n\n**Visual archetype:** Overlay surfaces — Floating material above the page or current surface.; Static content surfaces — In-flow containers and content surfaces that do not inherently manipulate state.; Triggers — Controls whose primary job is to open another surface.; Action controls — Momentary controls that perform an action now.\n\n**Accessibility pattern:** [Alert and Message Dialogs](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/)\n\n### Web and iOS\n\nRequire an explicit decision before committing or abandoning a consequential action. Rendered by `alert(_:isPresented:actions:message:)` in SwiftUI, with `platform-adaptive` parity.\n\n**Required states:** `closed`, `open`\n\n**Shared outcomes:**\n\n- Consequential action requires explicit confirmation\n- Cancel dismisses without performing the action\n- Confirmation performs the action once and dismisses\n\n**Accessibility outcomes:**\n\n- Exposes alert dialog title\n- Exposes consequence description\n- Identifies cancel and confirm actions\n\n**Platform adaptations:**\n\n- React: Uses an alertdialog portal with guarded outside and Escape dismissal plus explicit action and cancel controls.\n- SwiftUI: Uses a native alert or confirmationDialog with platform button roles, ordering, and compact presentation.\n\n## Related components\n\n- [Dialog](/components/component-dialog)\n- [Sheet](/components/component-sheet)\n- [Drawer](/components/component-drawer)\n",
9460
+ "markdown": "# Alert Dialog\n\nAlert Dialog interrupts a flow to confirm a consequential decision.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Reserve it for decisions that need explicit acknowledgement, not routine information.\n- When the family opens a surface, preserve its focus, Escape, and dismissal semantics.\n- Check portal placement, stacking, and small-viewport containment in the consuming product.\n\n## Usage\n\n```tsx\nimport { AlertDialog, AlertDialogTrigger, AlertDialogContent, AlertDialogAction } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `AlertDialog`, `AlertDialogAction`, `AlertDialogBackdrop`, `AlertDialogCancel`, `AlertDialogClose`, `AlertDialogContent`, `AlertDialogCreateHandle`, `AlertDialogDescription`, `AlertDialogFooter`, `AlertDialogHeader`, `AlertDialogMedia`, `AlertDialogOverlay`, `AlertDialogPopup`, `AlertDialogPortal`, `AlertDialogPrimitive`, `AlertDialogTitle`, `AlertDialogTrigger`, `AlertDialogViewport`\n\n**Types:** None.\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/alert-dialog.json` (`alertDialogContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `footerVariants` | `default`, `bare` | `default` |\n| `sizes` | `md`, `sm` | `md` |\n| `variants` | `default`, `error`, `info`, `success`, `warning` | `default` |\n\n**Deprecated aliases:** `default` → `md` (sizes), `destructive` → `error` (variants)\n\n**Slots:** `alert-dialog-portal`, `alert-dialog-trigger`, `alert-dialog-backdrop`, `alert-dialog-viewport`, `alert-dialog-popup`, `alert-dialog-header`, `alert-dialog-footer`, `alert-dialog-media`, `alert-dialog-title`, `alert-dialog-description`, `alert-dialog-close`, `alert-dialog-action`, `alert-dialog-cancel`\n\n**States:** `closed`, `open`\n\n**Visual archetype:** Overlay surfaces — Floating material above the page or current surface.; Static content surfaces — In-flow containers and content surfaces that do not inherently manipulate state.; Triggers — Controls whose primary job is to open another surface.; Action controls — Momentary controls that perform an action now.\n\n**Accessibility pattern:** [Alert and Message Dialogs](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/)\n\n### Web and iOS\n\nRequire an explicit decision before committing or abandoning a consequential action. Rendered by `alert(_:isPresented:actions:message:)` in SwiftUI, with `platform-adaptive` parity.\n\n**Required states:** `closed`, `open`\n\n**Shared outcomes:**\n\n- Consequential action requires explicit confirmation\n- Cancel dismisses without performing the action\n- Confirmation performs the action once and dismisses\n\n**Accessibility outcomes:**\n\n- Exposes alert dialog title\n- Exposes consequence description\n- Identifies cancel and confirm actions\n\n**Platform adaptations:**\n\n- React: Uses an alertdialog portal with guarded outside and Escape dismissal plus explicit action and cancel controls.\n- SwiftUI: Uses a native alert or confirmationDialog with platform button roles, ordering, and compact presentation.\n\n## Related components\n\n- [Dialog](/components/component-dialog)\n- [Sheet](/components/component-sheet)\n- [Drawer](/components/component-drawer)\n",
9397
9461
  "related": [
9398
9462
  "dialog",
9399
9463
  "sheet",
@@ -9412,7 +9476,7 @@
9412
9476
  "Endpoints",
9413
9477
  "ContractMetadata"
9414
9478
  ],
9415
- "source": "import { alertDialogContract, alertDialogVariants, themes } from '@atom63/ui-foundation'\nimport {\n AlertDialog,\n AlertDialogAction,\n AlertDialogCancel,\n AlertDialogDescription,\n AlertDialogFooter,\n AlertDialogHeader,\n AlertDialogMedia,\n AlertDialogPopup,\n AlertDialogTitle,\n AlertDialogTrigger,\n Button,\n Dialog,\n UIProvider,\n} from '@atom63/ui-react'\nimport '@atom63/ui-react/styles.css'\nimport { AlertTriangle, CheckCircle2, Info } from 'lucide-react'\nimport type { Meta, StoryObj } from '@storybook/react-vite'\nimport { type CSSProperties, type ReactNode, type RefObject, useRef } from 'react'\n\nconst meta = {\n title: 'UI React/AlertDialog',\n component: AlertDialog,\n decorators: [\n Story => (\n <div style={{ display: 'flex', gap: 24, padding: 48 }}>\n <Story />\n </div>\n ),\n ],\n} satisfies Meta<typeof AlertDialog>\n\nexport default meta\ntype Story = StoryObj<typeof meta>\n\nfunction VariantIcon({ variant }: { variant: (typeof alertDialogVariants)[number] }) {\n if (variant === 'success') {\n return <CheckCircle2 aria-hidden />\n }\n if (variant === 'default' || variant === 'info') {\n return <Info aria-hidden />\n }\n return <AlertTriangle aria-hidden />\n}\n\n/* A labelled stage cell. It paints its own panel surface so the label reads\n against the cell's theme and mode, not the light page behind the story. */\nconst cellStyle: CSSProperties = {\n background: 'var(--a63-surface-panel)',\n borderRadius: 'var(--radius-lg)',\n color: 'var(--a63-text-primary)',\n display: 'grid',\n gap: 6,\n padding: 12,\n}\n\n/*\n * A fixed-height box that holds one open overlay. The transform makes the box\n * the containing block of the popup's fixed-position backdrop and viewport, and\n * --a63-viewport-height sizes them to the box, so the overlay lays out as it\n * would over a short window.\n */\nfunction OverlayStage({\n children,\n height = 320,\n}: {\n children: (container: RefObject<HTMLDivElement | null>) => ReactNode\n height?: number\n}) {\n const containerRef = useRef<HTMLDivElement>(null)\n return (\n <div\n ref={containerRef}\n style={\n {\n '--a63-viewport-height': `${height}px`,\n background: 'var(--a63-surface-page)',\n blockSize: height,\n borderRadius: 'var(--radius-lg)',\n color: 'var(--a63-text-primary)',\n overflow: 'hidden',\n position: 'relative',\n transform: 'translateZ(0)',\n } as CSSProperties\n }\n >\n {children(containerRef)}\n </div>\n )\n}\n\n/*\n * One alert dialog popup, open on load inside a stage, for the matrix stories.\n * An alert dialog is always modal, and two open modal dialogs each hide the\n * other from assistive tech, so these cells mount the same AlertDialogPopup\n * under a non-modal Dialog root (the alert dialog root is a Dialog root with\n * `modal` forced on). The Confirm story shows the real modal alert dialog.\n */\nfunction StagedAlert({\n label,\n variant,\n}: {\n label: string\n variant: (typeof alertDialogVariants)[number]\n}) {\n return (\n <div style={cellStyle}>\n <span style={{ fontSize: 12, color: 'var(--a63-text-secondary)' }}>{label}</span>\n <OverlayStage>\n {container => (\n <Dialog defaultOpen modal={false}>\n <AlertDialogPopup initialFocus={false} portalProps={{ container }} variant={variant}>\n <AlertDialogHeader>\n <AlertDialogMedia>\n <VariantIcon variant={variant} />\n </AlertDialogMedia>\n <AlertDialogTitle>{variant} alert</AlertDialogTitle>\n <AlertDialogDescription>\n This popup uses the “{variant}” variant to carry its semantic tone.\n </AlertDialogDescription>\n </AlertDialogHeader>\n <AlertDialogFooter>\n <AlertDialogCancel>Cancel</AlertDialogCancel>\n <AlertDialogAction variant={variant === 'destructive' ? 'destructive' : 'primary'}>\n Continue\n </AlertDialogAction>\n </AlertDialogFooter>\n </AlertDialogPopup>\n </Dialog>\n )}\n </OverlayStage>\n </div>\n )\n}\n\nexport const Playground: Story = {\n render: () => (\n <AlertDialog>\n <AlertDialogTrigger render={<Button variant=\"outline\">Delete project</Button>} />\n <AlertDialogPopup variant=\"destructive\">\n <AlertDialogHeader>\n <AlertDialogMedia>\n <VariantIcon variant=\"destructive\" />\n </AlertDialogMedia>\n <AlertDialogTitle>Delete this project?</AlertDialogTitle>\n <AlertDialogDescription>\n This permanently removes the project and all of its files. This action cannot be undone.\n </AlertDialogDescription>\n </AlertDialogHeader>\n <AlertDialogFooter>\n <AlertDialogCancel>Cancel</AlertDialogCancel>\n <AlertDialogAction variant=\"destructive\">Delete</AlertDialogAction>\n </AlertDialogFooter>\n </AlertDialogPopup>\n </AlertDialog>\n ),\n}\n\nexport const Confirm: Story = {\n render: () => (\n <AlertDialog defaultOpen>\n <AlertDialogPopup size=\"sm\">\n <AlertDialogHeader>\n <AlertDialogMedia>\n <VariantIcon variant=\"default\" />\n </AlertDialogMedia>\n <AlertDialogTitle>Publish changes?</AlertDialogTitle>\n <AlertDialogDescription>Your changes will go live immediately.</AlertDialogDescription>\n </AlertDialogHeader>\n <AlertDialogFooter>\n <AlertDialogCancel>Not yet</AlertDialogCancel>\n <AlertDialogAction variant=\"primary\">Publish</AlertDialogAction>\n </AlertDialogFooter>\n </AlertDialogPopup>\n </AlertDialog>\n ),\n}\n\n/** Every semantic popup variant, open. */\nexport const Variants: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12, inlineSize: '100%' }}>\n {alertDialogVariants.map(variant => (\n <StagedAlert key={variant} label={variant} variant={variant} />\n ))}\n </div>\n ),\n}\n\nexport const Themes: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12, inlineSize: '100%' }}>\n {themes.map(theme =>\n (['light', 'dark'] as const).map(mode => (\n <UIProvider key={theme + mode} mode={mode} theme={theme}>\n <StagedAlert label={`${theme} / ${mode}`} variant=\"destructive\" />\n </UIProvider>\n ))\n )}\n </div>\n ),\n}\n\n/* The same confirmation pattern reviewed against target host contexts. */\nexport const Endpoints: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12, inlineSize: '100%' }}>\n {[\n {\n label: 'Web',\n props: { density: 'comfortable', designLanguage: 'web', input: 'pointer' } as const,\n },\n {\n label: 'iOS touch',\n props: { density: 'comfortable', designLanguage: 'ios', input: 'touch' } as const,\n },\n {\n label: 'Compact extension',\n props: {\n density: 'compact',\n designLanguage: 'web',\n input: 'pointer',\n surface: 'n2',\n } as const,\n },\n ].map(endpoint => (\n <UIProvider key={endpoint.label} {...endpoint.props}>\n <StagedAlert label={endpoint.label} variant=\"destructive\" />\n </UIProvider>\n ))}\n </div>\n ),\n}\n\nexport const ContractMetadata: Story = {\n render: () => (\n <pre style={{ fontSize: 12, margin: 0, whiteSpace: 'pre-wrap' }}>\n {JSON.stringify(alertDialogContract, null, 2)}\n </pre>\n ),\n}\n"
9479
+ "source": "import { alertDialogContract, alertDialogVariants, themes } from '@atom63/ui-foundation'\nimport {\n AlertDialog,\n AlertDialogAction,\n AlertDialogCancel,\n AlertDialogDescription,\n AlertDialogFooter,\n AlertDialogHeader,\n AlertDialogMedia,\n AlertDialogPopup,\n AlertDialogTitle,\n AlertDialogTrigger,\n Button,\n Dialog,\n UIProvider,\n} from '@atom63/ui-react'\nimport '@atom63/ui-react/styles.css'\nimport { AlertTriangle, CheckCircle2, Info } from 'lucide-react'\nimport type { Meta, StoryObj } from '@storybook/react-vite'\nimport { type CSSProperties, type ReactNode, type RefObject, useRef } from 'react'\n\nconst meta = {\n title: 'UI React/AlertDialog',\n component: AlertDialog,\n decorators: [\n Story => (\n <div style={{ display: 'flex', gap: 24, padding: 48 }}>\n <Story />\n </div>\n ),\n ],\n} satisfies Meta<typeof AlertDialog>\n\nexport default meta\ntype Story = StoryObj<typeof meta>\n\nfunction VariantIcon({ variant }: { variant: (typeof alertDialogVariants)[number] }) {\n if (variant === 'success') {\n return <CheckCircle2 aria-hidden />\n }\n if (variant === 'default' || variant === 'info') {\n return <Info aria-hidden />\n }\n return <AlertTriangle aria-hidden />\n}\n\n/* A labelled stage cell. It paints its own panel surface so the label reads\n against the cell's theme and mode, not the light page behind the story. */\nconst cellStyle: CSSProperties = {\n background: 'var(--a63-surface-panel)',\n borderRadius: 'var(--radius-lg)',\n color: 'var(--a63-text-primary)',\n display: 'grid',\n gap: 6,\n padding: 12,\n}\n\n/*\n * A fixed-height box that holds one open overlay. The transform makes the box\n * the containing block of the popup's fixed-position backdrop and viewport, and\n * --a63-viewport-height sizes them to the box, so the overlay lays out as it\n * would over a short window.\n */\nfunction OverlayStage({\n children,\n height = 320,\n}: {\n children: (container: RefObject<HTMLDivElement | null>) => ReactNode\n height?: number\n}) {\n const containerRef = useRef<HTMLDivElement>(null)\n return (\n <div\n ref={containerRef}\n style={\n {\n '--a63-viewport-height': `${height}px`,\n background: 'var(--a63-surface-page)',\n blockSize: height,\n borderRadius: 'var(--radius-lg)',\n color: 'var(--a63-text-primary)',\n overflow: 'hidden',\n position: 'relative',\n transform: 'translateZ(0)',\n } as CSSProperties\n }\n >\n {children(containerRef)}\n </div>\n )\n}\n\n/*\n * One alert dialog popup, open on load inside a stage, for the matrix stories.\n * An alert dialog is always modal, and two open modal dialogs each hide the\n * other from assistive tech, so these cells mount the same AlertDialogPopup\n * under a non-modal Dialog root (the alert dialog root is a Dialog root with\n * `modal` forced on). The Confirm story shows the real modal alert dialog.\n */\nfunction StagedAlert({\n label,\n variant,\n}: {\n label: string\n variant: (typeof alertDialogVariants)[number]\n}) {\n return (\n <div style={cellStyle}>\n <span style={{ fontSize: 12, color: 'var(--a63-text-secondary)' }}>{label}</span>\n <OverlayStage>\n {container => (\n <Dialog defaultOpen modal={false}>\n <AlertDialogPopup initialFocus={false} portalProps={{ container }} variant={variant}>\n <AlertDialogHeader>\n <AlertDialogMedia>\n <VariantIcon variant={variant} />\n </AlertDialogMedia>\n <AlertDialogTitle>{variant} alert</AlertDialogTitle>\n <AlertDialogDescription>\n This popup uses the “{variant}” variant to carry its semantic tone.\n </AlertDialogDescription>\n </AlertDialogHeader>\n <AlertDialogFooter>\n <AlertDialogCancel>Cancel</AlertDialogCancel>\n <AlertDialogAction variant={variant === 'error' ? 'destructive' : 'primary'}>\n Continue\n </AlertDialogAction>\n </AlertDialogFooter>\n </AlertDialogPopup>\n </Dialog>\n )}\n </OverlayStage>\n </div>\n )\n}\n\nexport const Playground: Story = {\n render: () => (\n <AlertDialog>\n <AlertDialogTrigger render={<Button variant=\"outline\">Delete project</Button>} />\n <AlertDialogPopup variant=\"error\">\n <AlertDialogHeader>\n <AlertDialogMedia>\n <VariantIcon variant=\"error\" />\n </AlertDialogMedia>\n <AlertDialogTitle>Delete this project?</AlertDialogTitle>\n <AlertDialogDescription>\n This permanently removes the project and all of its files. This action cannot be undone.\n </AlertDialogDescription>\n </AlertDialogHeader>\n <AlertDialogFooter>\n <AlertDialogCancel>Cancel</AlertDialogCancel>\n <AlertDialogAction variant=\"destructive\">Delete</AlertDialogAction>\n </AlertDialogFooter>\n </AlertDialogPopup>\n </AlertDialog>\n ),\n}\n\nexport const Confirm: Story = {\n render: () => (\n <AlertDialog defaultOpen>\n <AlertDialogPopup size=\"sm\">\n <AlertDialogHeader>\n <AlertDialogMedia>\n <VariantIcon variant=\"default\" />\n </AlertDialogMedia>\n <AlertDialogTitle>Publish changes?</AlertDialogTitle>\n <AlertDialogDescription>Your changes will go live immediately.</AlertDialogDescription>\n </AlertDialogHeader>\n <AlertDialogFooter>\n <AlertDialogCancel>Not yet</AlertDialogCancel>\n <AlertDialogAction variant=\"primary\">Publish</AlertDialogAction>\n </AlertDialogFooter>\n </AlertDialogPopup>\n </AlertDialog>\n ),\n}\n\n/** Every semantic popup variant, open. */\nexport const Variants: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12, inlineSize: '100%' }}>\n {alertDialogVariants.map(variant => (\n <StagedAlert key={variant} label={variant} variant={variant} />\n ))}\n </div>\n ),\n}\n\nexport const Themes: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12, inlineSize: '100%' }}>\n {themes.map(theme =>\n (['light', 'dark'] as const).map(mode => (\n <UIProvider key={theme + mode} mode={mode} theme={theme}>\n <StagedAlert label={`${theme} / ${mode}`} variant=\"error\" />\n </UIProvider>\n ))\n )}\n </div>\n ),\n}\n\n/* The same confirmation pattern reviewed against target host contexts. */\nexport const Endpoints: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12, inlineSize: '100%' }}>\n {[\n {\n label: 'Web',\n props: { density: 'comfortable', designLanguage: 'web', input: 'pointer' } as const,\n },\n {\n label: 'iOS touch',\n props: { density: 'comfortable', designLanguage: 'ios', input: 'touch' } as const,\n },\n {\n label: 'Compact extension',\n props: {\n density: 'compact',\n designLanguage: 'web',\n input: 'pointer',\n surface: 'n2',\n } as const,\n },\n ].map(endpoint => (\n <UIProvider key={endpoint.label} {...endpoint.props}>\n <StagedAlert label={endpoint.label} variant=\"error\" />\n </UIProvider>\n ))}\n </div>\n ),\n}\n\nexport const ContractMetadata: Story = {\n render: () => (\n <pre style={{ fontSize: 12, margin: 0, whiteSpace: 'pre-wrap' }}>\n {JSON.stringify(alertDialogContract, null, 2)}\n </pre>\n ),\n}\n"
9416
9480
  },
9417
9481
  "summary": "Alert Dialog interrupts a flow to confirm a consequential decision.",
9418
9482
  "usage": "Reserve it for decisions that need explicit acknowledgement, not routine information.",
@@ -9475,10 +9539,13 @@
9475
9539
  "name": "sizes",
9476
9540
  "values": [
9477
9541
  "sm",
9478
- "default",
9542
+ "md",
9479
9543
  "lg"
9480
9544
  ],
9481
- "default": "default"
9545
+ "deprecatedAliases": {
9546
+ "default": "md"
9547
+ },
9548
+ "default": "md"
9482
9549
  }
9483
9550
  ],
9484
9551
  "crossRenderer": {
@@ -9570,7 +9637,7 @@
9570
9637
  ],
9571
9638
  "importPath": "@atom63/ui-react",
9572
9639
  "label": "Dialog",
9573
- "markdown": "# Dialog\n\nDialog provides modal task structure, focus management, and responsive placement.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Give every dialog a title and a deliberate close path; use Alert Dialog for confirmation.\n- When the family opens a surface, preserve its focus, Escape, and dismissal semantics.\n- Check portal placement, stacking, and small-viewport containment in the consuming product.\n\n## Usage\n\n```tsx\nimport { Dialog, DialogTrigger, DialogContent } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Dialog`, `DialogBackdrop`, `DialogClose`, `DialogContent`, `DialogCreateHandle`, `DialogDescription`, `DialogFooter`, `DialogHeader`, `DialogOverlay`, `DialogPanel`, `DialogPopup`, `DialogPortal`, `DialogPrimitive`, `DialogTitle`, `DialogTrigger`, `DialogViewport`\n\n**Types:** `DialogFooterVariant`, `DialogMobilePlacement`, `DialogSize`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/dialog.json` (`dialogContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `footerVariants` | `default`, `bare` | `default` |\n| `mobilePlacements` | `bottom`, `center` | `bottom` |\n| `sizes` | `sm`, `default`, `lg` | `default` |\n\n**Slots:** `dialog-portal`, `dialog-trigger`, `dialog-backdrop`, `dialog-viewport`, `dialog-popup`, `dialog-close`, `dialog-close-button`, `dialog-header`, `dialog-title`, `dialog-description`, `dialog-panel`, `dialog-footer`\n\n**States:** `closed`, `open`, `starting`, `ending`, `focus-visible`\n\n**Visual archetype:** Overlay surfaces — Floating material above the page or current surface.; Static content surfaces — In-flow containers and content surfaces that do not inherently manipulate state.; Triggers — Controls whose primary job is to open another surface.; Action controls — Momentary controls that perform an action now.\n\n**Accessibility pattern:** [Dialog (Modal)](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)\n\n### Web and iOS\n\nTemporarily move the user into a focused modal task without losing the originating context. Rendered by `sheet(isPresented:) / presentationDetents(_:)` in SwiftUI, with `platform-adaptive` parity.\n\n**Required states:** `closed`, `open`, `focus-visible`\n\n**Shared outcomes:**\n\n- Opening presents a modal context\n- Background interaction is blocked while open\n- Dismissal returns to the originating context\n\n**Accessibility outcomes:**\n\n- Exposes modal title\n- Keeps assistive focus in the modal context\n- Restores access to the originating control\n\n**Platform adaptations:**\n\n- React: Uses a compound modal dialog with a portal, focus containment, Escape dismissal, and trigger focus restoration.\n- SwiftUI: Uses the native sheet presentation, adaptive detents, swipe dismissal, and a NavigationStack for modal task hierarchy.\n\n## Related components\n\n- [Alert Dialog](/components/component-alert-dialog)\n- [Sheet](/components/component-sheet)\n- [Drawer](/components/component-drawer)\n",
9640
+ "markdown": "# Dialog\n\nDialog provides modal task structure, focus management, and responsive placement.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Give every dialog a title and a deliberate close path; use Alert Dialog for confirmation.\n- When the family opens a surface, preserve its focus, Escape, and dismissal semantics.\n- Check portal placement, stacking, and small-viewport containment in the consuming product.\n\n## Usage\n\n```tsx\nimport { Dialog, DialogTrigger, DialogContent } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Dialog`, `DialogBackdrop`, `DialogClose`, `DialogContent`, `DialogCreateHandle`, `DialogDescription`, `DialogFooter`, `DialogHeader`, `DialogOverlay`, `DialogPanel`, `DialogPopup`, `DialogPortal`, `DialogPrimitive`, `DialogTitle`, `DialogTrigger`, `DialogViewport`\n\n**Types:** `DialogFooterVariant`, `DialogMobilePlacement`, `DialogSize`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/dialog.json` (`dialogContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `footerVariants` | `default`, `bare` | `default` |\n| `mobilePlacements` | `bottom`, `center` | `bottom` |\n| `sizes` | `sm`, `md`, `lg` | `md` |\n\n**Deprecated aliases:** `default` → `md` (sizes)\n\n**Slots:** `dialog-portal`, `dialog-trigger`, `dialog-backdrop`, `dialog-viewport`, `dialog-popup`, `dialog-close`, `dialog-close-button`, `dialog-header`, `dialog-title`, `dialog-description`, `dialog-panel`, `dialog-footer`\n\n**States:** `closed`, `open`, `starting`, `ending`, `focus-visible`\n\n**Visual archetype:** Overlay surfaces — Floating material above the page or current surface.; Static content surfaces — In-flow containers and content surfaces that do not inherently manipulate state.; Triggers — Controls whose primary job is to open another surface.; Action controls — Momentary controls that perform an action now.\n\n**Accessibility pattern:** [Dialog (Modal)](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)\n\n### Web and iOS\n\nTemporarily move the user into a focused modal task without losing the originating context. Rendered by `sheet(isPresented:) / presentationDetents(_:)` in SwiftUI, with `platform-adaptive` parity.\n\n**Required states:** `closed`, `open`, `focus-visible`\n\n**Shared outcomes:**\n\n- Opening presents a modal context\n- Background interaction is blocked while open\n- Dismissal returns to the originating context\n\n**Accessibility outcomes:**\n\n- Exposes modal title\n- Keeps assistive focus in the modal context\n- Restores access to the originating control\n\n**Platform adaptations:**\n\n- React: Uses a compound modal dialog with a portal, focus containment, Escape dismissal, and trigger focus restoration.\n- SwiftUI: Uses the native sheet presentation, adaptive detents, swipe dismissal, and a NavigationStack for modal task hierarchy.\n\n## Related components\n\n- [Alert Dialog](/components/component-alert-dialog)\n- [Sheet](/components/component-sheet)\n- [Drawer](/components/component-drawer)\n",
9574
9641
  "related": [
9575
9642
  "alert-dialog",
9576
9643
  "sheet",
@@ -9591,7 +9658,7 @@
9591
9658
  "Endpoints",
9592
9659
  "ContractMetadata"
9593
9660
  ],
9594
- "source": "import { dialogContract, dialogSizes, themes } from '@atom63/ui-foundation'\nimport {\n Button,\n Dialog,\n DialogClose,\n DialogDescription,\n DialogFooter,\n DialogHeader,\n DialogPanel,\n DialogPopup,\n DialogTitle,\n DialogTrigger,\n UIProvider,\n} from '@atom63/ui-react'\nimport '@atom63/ui-react/styles.css'\nimport type { Meta, StoryObj } from '@storybook/react-vite'\nimport {\n type CSSProperties,\n type ComponentProps,\n type ReactNode,\n type RefObject,\n useRef,\n} from 'react'\n\nconst meta = {\n title: 'UI React/Dialog',\n component: Dialog,\n decorators: [\n Story => (\n <div style={{ display: 'flex', gap: 24, padding: 48 }}>\n <Story />\n </div>\n ),\n ],\n} satisfies Meta<typeof Dialog>\n\nexport default meta\ntype Story = StoryObj<typeof meta>\n\n/*\n * `open` renders the dialog open on load so the visual and axe runs capture the\n * popup, not the trigger. `modal` is the dialog as an app shows it, over the\n * whole page (one per story). `inline` is non-modal and belongs inside an\n * OverlayStage, so several open dialogs can share one capture: two open modal\n * dialogs would each hide the other from assistive tech.\n */\ntype OpenMode = 'modal' | 'inline'\n\nfunction RenameDialog({\n open,\n portalContainerRef,\n size = 'default',\n triggerLabel = 'Rename project',\n}: {\n open?: OpenMode\n portalContainerRef?: RefObject<HTMLDivElement | null>\n size?: (typeof dialogSizes)[number]\n triggerLabel?: string\n}) {\n return (\n <Dialog defaultOpen={open !== undefined} modal={open === 'inline' ? false : undefined}>\n {open ? null : <DialogTrigger render={<Button variant=\"outline\">{triggerLabel}</Button>} />}\n <DialogPopup\n initialFocus={open === 'inline' ? false : undefined}\n portalProps={{ container: portalContainerRef }}\n size={size}\n >\n <DialogHeader>\n <DialogTitle>Rename project</DialogTitle>\n <DialogDescription>Give this project a new, memorable name.</DialogDescription>\n </DialogHeader>\n <DialogPanel>\n <p style={{ margin: 0 }}>Any content can live in the scrollable panel.</p>\n </DialogPanel>\n <DialogFooter>\n <DialogClose render={<Button variant=\"ghost\">Cancel</Button>} />\n <DialogClose render={<Button variant=\"primary\">Save</Button>} />\n </DialogFooter>\n </DialogPopup>\n </Dialog>\n )\n}\n\n/* A labelled stage cell. It paints its own panel surface so the label reads\n against the cell's theme and mode, not the light page behind the story. */\nconst cellStyle: CSSProperties = {\n background: 'var(--a63-surface-panel)',\n borderRadius: 'var(--radius-lg)',\n color: 'var(--a63-text-primary)',\n display: 'grid',\n gap: 6,\n padding: 12,\n}\n\n/*\n * A fixed-height box that holds one open overlay. The transform makes the box\n * the containing block of the popup's fixed-position backdrop and viewport, and\n * --a63-viewport-height sizes them to the box, so the overlay lays out as it\n * would over a short window.\n */\nfunction OverlayStage({\n children,\n height = 340,\n}: {\n children: (container: RefObject<HTMLDivElement | null>) => ReactNode\n height?: number\n}) {\n const containerRef = useRef<HTMLDivElement>(null)\n return (\n <div\n ref={containerRef}\n style={\n {\n '--a63-viewport-height': `${height}px`,\n background: 'var(--a63-surface-page)',\n blockSize: height,\n borderRadius: 'var(--radius-lg)',\n color: 'var(--a63-text-primary)',\n overflow: 'hidden',\n position: 'relative',\n transform: 'translateZ(0)',\n } as CSSProperties\n }\n >\n {children(containerRef)}\n </div>\n )\n}\n\ntype ProviderProps = Omit<ComponentProps<typeof UIProvider>, 'children'>\n\nfunction ReviewCell({ label, providerProps }: { label: string; providerProps: ProviderProps }) {\n return (\n <UIProvider {...providerProps}>\n <div style={cellStyle}>\n <span style={{ fontSize: 12, color: 'var(--a63-text-secondary)' }}>{label}</span>\n <OverlayStage>\n {container => <RenameDialog open=\"inline\" portalContainerRef={container} />}\n </OverlayStage>\n </div>\n </UIProvider>\n )\n}\n\nexport const Playground: Story = {\n render: () => <RenameDialog triggerLabel=\"Open dialog\" />,\n}\n\n/** The dialog open as an app shows it: modal, centred over the page. */\nexport const Open: Story = {\n render: () => <RenameDialog open=\"modal\" />,\n}\n\n/** Below `sm` the default popup sticks to the bottom edge. */\nexport const OpenPhone: Story = {\n render: () => <RenameDialog open=\"modal\" />,\n}\n\nexport const Sizes: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12, inlineSize: '100%' }}>\n {dialogSizes.map(size => (\n <div key={size} style={cellStyle}>\n <span style={{ fontSize: 12, color: 'var(--a63-text-secondary)' }}>{size}</span>\n <OverlayStage>\n {container => <RenameDialog open=\"inline\" portalContainerRef={container} size={size} />}\n </OverlayStage>\n </div>\n ))}\n </div>\n ),\n}\n\nexport const BareFooter: Story = {\n render: () => (\n <Dialog defaultOpen>\n <DialogPopup mobilePlacement=\"center\">\n <DialogHeader>\n <DialogTitle>Centered on mobile</DialogTitle>\n <DialogDescription>This popup stays centered at every breakpoint.</DialogDescription>\n </DialogHeader>\n <DialogFooter variant=\"bare\">\n <DialogClose render={<Button variant=\"primary\">Got it</Button>} />\n </DialogFooter>\n </DialogPopup>\n </Dialog>\n ),\n}\n\nexport const Themes: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12, inlineSize: '100%' }}>\n {themes.map(theme =>\n (['light', 'dark'] as const).map(mode => (\n <ReviewCell\n key={`${theme}-${mode}`}\n label={`${theme} / ${mode}`}\n providerProps={{ mode, theme }}\n />\n ))\n )}\n </div>\n ),\n}\n\nexport const Endpoints: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12, inlineSize: '100%' }}>\n <ReviewCell\n label=\"Web\"\n providerProps={{ density: 'comfortable', designLanguage: 'web', input: 'pointer' }}\n />\n <ReviewCell\n label=\"iOS touch\"\n providerProps={{ density: 'comfortable', designLanguage: 'ios', input: 'touch' }}\n />\n <ReviewCell\n label=\"Compact extension\"\n providerProps={{\n density: 'compact',\n designLanguage: 'web',\n input: 'pointer',\n surface: 'n2',\n }}\n />\n </div>\n ),\n}\n\nexport const ContractMetadata: Story = {\n render: () => (\n <pre style={{ fontSize: 12, margin: 0, whiteSpace: 'pre-wrap' }}>\n {JSON.stringify(dialogContract, null, 2)}\n </pre>\n ),\n}\n"
9661
+ "source": "import { dialogContract, dialogSizes, themes } from '@atom63/ui-foundation'\nimport {\n Button,\n Dialog,\n DialogClose,\n DialogDescription,\n DialogFooter,\n DialogHeader,\n DialogPanel,\n DialogPopup,\n DialogTitle,\n DialogTrigger,\n UIProvider,\n} from '@atom63/ui-react'\nimport '@atom63/ui-react/styles.css'\nimport type { Meta, StoryObj } from '@storybook/react-vite'\nimport {\n type CSSProperties,\n type ComponentProps,\n type ReactNode,\n type RefObject,\n useRef,\n} from 'react'\n\nconst meta = {\n title: 'UI React/Dialog',\n component: Dialog,\n decorators: [\n Story => (\n <div style={{ display: 'flex', gap: 24, padding: 48 }}>\n <Story />\n </div>\n ),\n ],\n} satisfies Meta<typeof Dialog>\n\nexport default meta\ntype Story = StoryObj<typeof meta>\n\n/*\n * `open` renders the dialog open on load so the visual and axe runs capture the\n * popup, not the trigger. `modal` is the dialog as an app shows it, over the\n * whole page (one per story). `inline` is non-modal and belongs inside an\n * OverlayStage, so several open dialogs can share one capture: two open modal\n * dialogs would each hide the other from assistive tech.\n */\ntype OpenMode = 'modal' | 'inline'\n\nfunction RenameDialog({\n open,\n portalContainerRef,\n size = 'md',\n triggerLabel = 'Rename project',\n}: {\n open?: OpenMode\n portalContainerRef?: RefObject<HTMLDivElement | null>\n size?: (typeof dialogSizes)[number]\n triggerLabel?: string\n}) {\n return (\n <Dialog defaultOpen={open !== undefined} modal={open === 'inline' ? false : undefined}>\n {open ? null : <DialogTrigger render={<Button variant=\"outline\">{triggerLabel}</Button>} />}\n <DialogPopup\n initialFocus={open === 'inline' ? false : undefined}\n portalProps={{ container: portalContainerRef }}\n size={size}\n >\n <DialogHeader>\n <DialogTitle>Rename project</DialogTitle>\n <DialogDescription>Give this project a new, memorable name.</DialogDescription>\n </DialogHeader>\n <DialogPanel>\n <p style={{ margin: 0 }}>Any content can live in the scrollable panel.</p>\n </DialogPanel>\n <DialogFooter>\n <DialogClose render={<Button variant=\"ghost\">Cancel</Button>} />\n <DialogClose render={<Button variant=\"primary\">Save</Button>} />\n </DialogFooter>\n </DialogPopup>\n </Dialog>\n )\n}\n\n/* A labelled stage cell. It paints its own panel surface so the label reads\n against the cell's theme and mode, not the light page behind the story. */\nconst cellStyle: CSSProperties = {\n background: 'var(--a63-surface-panel)',\n borderRadius: 'var(--radius-lg)',\n color: 'var(--a63-text-primary)',\n display: 'grid',\n gap: 6,\n padding: 12,\n}\n\n/*\n * A fixed-height box that holds one open overlay. The transform makes the box\n * the containing block of the popup's fixed-position backdrop and viewport, and\n * --a63-viewport-height sizes them to the box, so the overlay lays out as it\n * would over a short window.\n */\nfunction OverlayStage({\n children,\n height = 340,\n}: {\n children: (container: RefObject<HTMLDivElement | null>) => ReactNode\n height?: number\n}) {\n const containerRef = useRef<HTMLDivElement>(null)\n return (\n <div\n ref={containerRef}\n style={\n {\n '--a63-viewport-height': `${height}px`,\n background: 'var(--a63-surface-page)',\n blockSize: height,\n borderRadius: 'var(--radius-lg)',\n color: 'var(--a63-text-primary)',\n overflow: 'hidden',\n position: 'relative',\n transform: 'translateZ(0)',\n } as CSSProperties\n }\n >\n {children(containerRef)}\n </div>\n )\n}\n\ntype ProviderProps = Omit<ComponentProps<typeof UIProvider>, 'children'>\n\nfunction ReviewCell({ label, providerProps }: { label: string; providerProps: ProviderProps }) {\n return (\n <UIProvider {...providerProps}>\n <div style={cellStyle}>\n <span style={{ fontSize: 12, color: 'var(--a63-text-secondary)' }}>{label}</span>\n <OverlayStage>\n {container => <RenameDialog open=\"inline\" portalContainerRef={container} />}\n </OverlayStage>\n </div>\n </UIProvider>\n )\n}\n\nexport const Playground: Story = {\n render: () => <RenameDialog triggerLabel=\"Open dialog\" />,\n}\n\n/** The dialog open as an app shows it: modal, centred over the page. */\nexport const Open: Story = {\n render: () => <RenameDialog open=\"modal\" />,\n}\n\n/** Below `sm` the default popup sticks to the bottom edge. */\nexport const OpenPhone: Story = {\n render: () => <RenameDialog open=\"modal\" />,\n}\n\nexport const Sizes: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12, inlineSize: '100%' }}>\n {dialogSizes.map(size => (\n <div key={size} style={cellStyle}>\n <span style={{ fontSize: 12, color: 'var(--a63-text-secondary)' }}>{size}</span>\n <OverlayStage>\n {container => <RenameDialog open=\"inline\" portalContainerRef={container} size={size} />}\n </OverlayStage>\n </div>\n ))}\n </div>\n ),\n}\n\nexport const BareFooter: Story = {\n render: () => (\n <Dialog defaultOpen>\n <DialogPopup mobilePlacement=\"center\">\n <DialogHeader>\n <DialogTitle>Centered on mobile</DialogTitle>\n <DialogDescription>This popup stays centered at every breakpoint.</DialogDescription>\n </DialogHeader>\n <DialogFooter variant=\"bare\">\n <DialogClose render={<Button variant=\"primary\">Got it</Button>} />\n </DialogFooter>\n </DialogPopup>\n </Dialog>\n ),\n}\n\nexport const Themes: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12, inlineSize: '100%' }}>\n {themes.map(theme =>\n (['light', 'dark'] as const).map(mode => (\n <ReviewCell\n key={`${theme}-${mode}`}\n label={`${theme} / ${mode}`}\n providerProps={{ mode, theme }}\n />\n ))\n )}\n </div>\n ),\n}\n\nexport const Endpoints: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12, inlineSize: '100%' }}>\n <ReviewCell\n label=\"Web\"\n providerProps={{ density: 'comfortable', designLanguage: 'web', input: 'pointer' }}\n />\n <ReviewCell\n label=\"iOS touch\"\n providerProps={{ density: 'comfortable', designLanguage: 'ios', input: 'touch' }}\n />\n <ReviewCell\n label=\"Compact extension\"\n providerProps={{\n density: 'compact',\n designLanguage: 'web',\n input: 'pointer',\n surface: 'n2',\n }}\n />\n </div>\n ),\n}\n\nexport const ContractMetadata: Story = {\n render: () => (\n <pre style={{ fontSize: 12, margin: 0, whiteSpace: 'pre-wrap' }}>\n {JSON.stringify(dialogContract, null, 2)}\n </pre>\n ),\n}\n"
9595
9662
  },
9596
9663
  "summary": "Dialog provides modal task structure, focus management, and responsive placement.",
9597
9664
  "usage": "Give every dialog a title and a deliberate close path; use Alert Dialog for confirmation.",
@@ -10420,10 +10487,13 @@
10420
10487
  "accordion-content-inner"
10421
10488
  ],
10422
10489
  "source": "packages/ui-foundation/contracts/components/accordion.json",
10490
+ "stateAliases": {
10491
+ "focusVisible": "focus-visible"
10492
+ },
10423
10493
  "states": [
10424
10494
  "closed",
10425
10495
  "open",
10426
- "focusVisible",
10496
+ "focus-visible",
10427
10497
  "disabled"
10428
10498
  ],
10429
10499
  "tokenSlots": []
@@ -10451,7 +10521,7 @@
10451
10521
  ],
10452
10522
  "importPath": "@atom63/ui-react",
10453
10523
  "label": "Accordion",
10454
- "markdown": "# Accordion\n\nAccordion coordinates a set of disclosure sections with shared keyboard behavior.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Use it when several related sections may be collapsed; use Collapsible for one disclosure.\n- Keep product data and fetching outside the presentational component.\n- Test long, empty, and narrow content before adding local layout overrides.\n\n## Usage\n\n```tsx\nimport { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Accordion`, `AccordionContent`, `AccordionItem`, `AccordionTrigger`\n\n**Types:** `AccordionProps`, `AccordionTriggerProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/accordion.json` (`accordionContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `iconVariants` | `chevron`, `plus-minus` | `chevron` |\n\n**Slots:** `accordion`, `accordion-item`, `accordion-trigger`, `accordion-indicator`, `accordion-content`, `accordion-content-inner`\n\n**States:** `closed`, `open`, `focusVisible`, `disabled`\n\n**Visual archetype:** Static content surfaces — In-flow containers and content surfaces that do not inherently manipulate state.; Triggers — Controls whose primary job is to open another surface.\n\n**Accessibility pattern:** [Accordion](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/) (collapse: collapsible, expand: single)\n\n### Web and iOS\n\nReveal or hide supporting content in place while preserving the surrounding context. Rendered by `DisclosureGroup` in SwiftUI, with `platform-adaptive` parity.\n\n**Required states:** `closed`, `open`, `disabled`\n\n**Shared outcomes:**\n\n- Activation toggles associated content visibility\n- Expanded state matches content visibility\n- Disabled trigger prevents disclosure change\n\n**Accessibility outcomes:**\n\n- Trigger exposes expanded state\n- Trigger is associated with disclosed content\n- Disabled trigger exposes disabled state\n\n**Platform adaptations:**\n\n- React: Uses button and region disclosure semantics with optional single or multiple open sections.\n- SwiftUI: Uses DisclosureGroup with native indicator geometry, animation, and list integration.\n\n## Related components\n\n- [Collapsible](/components/component-collapsible)\n- [Tabs](/components/component-tabs)\n",
10524
+ "markdown": "# Accordion\n\nAccordion coordinates a set of disclosure sections with shared keyboard behavior.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Use it when several related sections may be collapsed; use Collapsible for one disclosure.\n- Keep product data and fetching outside the presentational component.\n- Test long, empty, and narrow content before adding local layout overrides.\n\n## Usage\n\n```tsx\nimport { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Accordion`, `AccordionContent`, `AccordionItem`, `AccordionTrigger`\n\n**Types:** `AccordionProps`, `AccordionTriggerProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/accordion.json` (`accordionContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `iconVariants` | `chevron`, `plus-minus` | `chevron` |\n\n**Deprecated aliases:** `focusVisible` → `focus-visible` (states)\n\n**Slots:** `accordion`, `accordion-item`, `accordion-trigger`, `accordion-indicator`, `accordion-content`, `accordion-content-inner`\n\n**States:** `closed`, `open`, `focus-visible`, `disabled`\n\n**Visual archetype:** Static content surfaces — In-flow containers and content surfaces that do not inherently manipulate state.; Triggers — Controls whose primary job is to open another surface.\n\n**Accessibility pattern:** [Accordion](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/) (collapse: collapsible, expand: single)\n\n### Web and iOS\n\nReveal or hide supporting content in place while preserving the surrounding context. Rendered by `DisclosureGroup` in SwiftUI, with `platform-adaptive` parity.\n\n**Required states:** `closed`, `open`, `disabled`\n\n**Shared outcomes:**\n\n- Activation toggles associated content visibility\n- Expanded state matches content visibility\n- Disabled trigger prevents disclosure change\n\n**Accessibility outcomes:**\n\n- Trigger exposes expanded state\n- Trigger is associated with disclosed content\n- Disabled trigger exposes disabled state\n\n**Platform adaptations:**\n\n- React: Uses button and region disclosure semantics with optional single or multiple open sections.\n- SwiftUI: Uses DisclosureGroup with native indicator geometry, animation, and list integration.\n\n## Related components\n\n- [Collapsible](/components/component-collapsible)\n- [Tabs](/components/component-tabs)\n",
10455
10525
  "related": [
10456
10526
  "collapsible",
10457
10527
  "tabs"
@@ -10823,10 +10893,13 @@
10823
10893
  "values": [
10824
10894
  "xs",
10825
10895
  "sm",
10826
- "default",
10896
+ "md",
10827
10897
  "lg"
10828
10898
  ],
10829
- "default": "default"
10899
+ "deprecatedAliases": {
10900
+ "default": "md"
10901
+ },
10902
+ "default": "md"
10830
10903
  }
10831
10904
  ],
10832
10905
  "crossRenderer": {
@@ -10901,7 +10974,7 @@
10901
10974
  ],
10902
10975
  "importPath": "@atom63/ui-react",
10903
10976
  "label": "Avatar",
10904
- "markdown": "# Avatar\n\nAvatar composes an image, fallback, badge, and grouped identity presentation.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Provide meaningful image alternative text and a stable fallback for failed or missing media.\n- Keep product data and fetching outside the presentational component.\n- Test long, empty, and narrow content before adding local layout overrides.\n\n## Usage\n\n```tsx\nimport { Avatar, AvatarImage, AvatarFallback } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Avatar`, `AvatarBadge`, `AvatarFallback`, `AvatarGroup`, `AvatarGroupCount`, `AvatarImage`, `AvatarPrimitive`\n\n**Types:** `AvatarProps`, `AvatarSize`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/avatar.json` (`avatarContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `compositions` | `standalone`, `badge`, `group` | — |\n| `rings` | `unseen`, `seen` | — |\n| `shapes` | `circle`, `square` | `circle` |\n| `sizes` | `xs`, `sm`, `default`, `lg` | `default` |\n\n**Slots:** `avatar`, `avatar-image`, `avatar-fallback`, `avatar-badge`, `avatar-group`, `avatar-group-count`\n\n**States:** `loading`, `loaded`, `fallback`\n\n**Visual archetype:** Markers and keycaps — Compact presentational labels, statuses, and keyboard hints.\n\n### Web and iOS\n\nRepresent a person or entity with an image and identity-preserving fallback. Rendered by `AtomAvatar` in SwiftUI, with `strict` parity.\n\n**Required states:** `loading`, `loaded`, `fallback`\n\n**Shared outcomes:**\n\n- Accessible name is preserved\n- Fallback preserves identity\n- Loading does not expose empty image\n\n**Accessibility outcomes:**\n\n- Exposes accessible name\n- Fallback preserves identity\n\n**Platform adaptations:**\n\n- React: Uses browser image loading and DOM fallback composition.\n- React: The square shape and the ring are web-only for now.\n- SwiftUI: Uses native image decoding and SwiftUI loading phases.\n- SwiftUI: AtomAvatar(badge:) pins a status dot (.dot) or a count (.count) to the corner, read after the name.\n\n## Related components\n\n- [Badge](/components/component-badge)\n- [Item](/components/component-item)\n",
10977
+ "markdown": "# Avatar\n\nAvatar composes an image, fallback, badge, and grouped identity presentation.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Provide meaningful image alternative text and a stable fallback for failed or missing media.\n- Keep product data and fetching outside the presentational component.\n- Test long, empty, and narrow content before adding local layout overrides.\n\n## Usage\n\n```tsx\nimport { Avatar, AvatarImage, AvatarFallback } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Avatar`, `AvatarBadge`, `AvatarFallback`, `AvatarGroup`, `AvatarGroupCount`, `AvatarImage`, `AvatarPrimitive`\n\n**Types:** `AvatarProps`, `AvatarSize`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/avatar.json` (`avatarContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `compositions` | `standalone`, `badge`, `group` | — |\n| `rings` | `unseen`, `seen` | — |\n| `shapes` | `circle`, `square` | `circle` |\n| `sizes` | `xs`, `sm`, `md`, `lg` | `md` |\n\n**Deprecated aliases:** `default` → `md` (sizes)\n\n**Slots:** `avatar`, `avatar-image`, `avatar-fallback`, `avatar-badge`, `avatar-group`, `avatar-group-count`\n\n**States:** `loading`, `loaded`, `fallback`\n\n**Visual archetype:** Markers and keycaps — Compact presentational labels, statuses, and keyboard hints.\n\n### Web and iOS\n\nRepresent a person or entity with an image and identity-preserving fallback. Rendered by `AtomAvatar` in SwiftUI, with `strict` parity.\n\n**Required states:** `loading`, `loaded`, `fallback`\n\n**Shared outcomes:**\n\n- Accessible name is preserved\n- Fallback preserves identity\n- Loading does not expose empty image\n\n**Accessibility outcomes:**\n\n- Exposes accessible name\n- Fallback preserves identity\n\n**Platform adaptations:**\n\n- React: Uses browser image loading and DOM fallback composition.\n- React: The square shape and the ring are web-only for now.\n- SwiftUI: Uses native image decoding and SwiftUI loading phases.\n- SwiftUI: AtomAvatar(badge:) pins a status dot (.dot) or a count (.count) to the corner, read after the name.\n\n## Related components\n\n- [Badge](/components/component-badge)\n- [Item](/components/component-item)\n",
10905
10978
  "related": [
10906
10979
  "badge",
10907
10980
  "item"
@@ -10925,7 +10998,7 @@
10925
10998
  "Endpoints",
10926
10999
  "ContractMetadata"
10927
11000
  ],
10928
- "source": "import { avatarContract, avatarSizes, themes } from '@atom63/ui-foundation'\nimport {\n Avatar,\n AvatarBadge,\n AvatarFallback,\n AvatarGroup,\n AvatarGroupCount,\n AvatarImage,\n UIProvider,\n} from '@atom63/ui-react'\nimport '@atom63/ui-react/styles.css'\nimport type { Meta, StoryObj } from '@storybook/react-vite'\nimport { Sparkles } from 'lucide-react'\nimport type { CSSProperties } from 'react'\n\nconst meta = {\n title: 'UI React/Avatar',\n component: Avatar,\n args: { size: 'default' },\n argTypes: { size: { control: 'inline-radio', options: avatarSizes } },\n} satisfies Meta<typeof Avatar>\n\nexport default meta\ntype Story = StoryObj<typeof meta>\n\nconst SRC = 'https://i.pravatar.cc/80?img=12'\n\nexport const Playground: Story = {\n render: args => (\n <Avatar {...args}>\n <AvatarImage src={SRC} alt=\"Ada\" />\n <AvatarFallback>AL</AvatarFallback>\n </Avatar>\n ),\n}\n\nexport const Sizes: Story = {\n render: () => (\n <div style={{ alignItems: 'center', display: 'flex', gap: 16 }}>\n <Avatar size=\"xs\">\n <AvatarImage src={SRC} alt=\"Ada\" />\n <AvatarFallback>AL</AvatarFallback>\n </Avatar>\n <Avatar size=\"sm\">\n <AvatarImage src={SRC} alt=\"Ada\" />\n <AvatarFallback>AL</AvatarFallback>\n </Avatar>\n <Avatar size=\"default\">\n <AvatarImage src={SRC} alt=\"Ada\" />\n <AvatarFallback>AL</AvatarFallback>\n </Avatar>\n <Avatar size=\"lg\">\n <AvatarImage src={SRC} alt=\"Ada\" />\n <AvatarFallback>AL</AvatarFallback>\n </Avatar>\n </div>\n ),\n}\n\n/* An icon fallback, such as an assistant's sparkle, sits in the filled circle at\n the control icon size for each size step. */\nexport const IconFallback: Story = {\n render: () => (\n <div style={{ alignItems: 'center', display: 'flex', gap: 16 }}>\n {avatarSizes.map(size => (\n <Avatar key={size} size={size}>\n <AvatarFallback>\n <Sparkles aria-hidden />\n </AvatarFallback>\n </Avatar>\n ))}\n </div>\n ),\n}\n\n/* A 76px avatar stays a circle: the default reads --a63-avatar-radius (50%), and\n without that contract the fallback is --radius-pill, not the soft --radius-full. */\nexport const LargeCircle: Story = {\n render: () => (\n <div style={{ alignItems: 'center', display: 'flex', gap: 16 }}>\n <Avatar data-testid=\"contract\" style={{ '--avatar-size': '76px' } as CSSProperties}>\n <AvatarFallback>AL</AvatarFallback>\n </Avatar>\n <Avatar\n data-testid=\"fallback\"\n style={{ '--avatar-size': '76px', '--a63-avatar-radius': 'initial' } as CSSProperties}\n >\n <AvatarFallback>YZ</AvatarFallback>\n </Avatar>\n </div>\n ),\n play: ({ canvasElement }) => {\n const radius = (testId: string) => {\n const avatar = canvasElement.querySelector<HTMLElement>(`[data-testid=\"${testId}\"]`)\n return avatar ? getComputedStyle(avatar).borderTopLeftRadius : null\n }\n const actual = [radius('contract'), radius('fallback')]\n if (actual[0] !== '50%' || actual[1] !== '9999px') {\n throw new Error(`Expected radii 50% and 9999px, got ${actual.join(' and ')}`)\n }\n },\n}\n\n/* shape=\"square\" for organisations and apps; ring marks new activity. */\nexport const ShapesAndRing: Story = {\n render: () => (\n <div style={{ alignItems: 'center', display: 'flex', gap: 16 }}>\n <Avatar>\n <AvatarFallback>AL</AvatarFallback>\n </Avatar>\n <Avatar shape=\"square\">\n <AvatarFallback>NW</AvatarFallback>\n </Avatar>\n <Avatar ring>\n <AvatarFallback>JL</AvatarFallback>\n </Avatar>\n <Avatar ring shape=\"square\" size=\"lg\">\n <AvatarFallback>PS</AvatarFallback>\n </Avatar>\n <Avatar shape=\"square\" size=\"xs\">\n <AvatarFallback>A</AvatarFallback>\n </Avatar>\n </div>\n ),\n}\n\n/*\n * Story rings: unseen draws --a63-avatar-ring-fill, which a product can set to a\n * gradient of the category palette (see the content-colors rule); seen is a\n * thin border-coloured ring.\n */\nexport const StoryRings: Story = {\n render: () => (\n <div\n style={\n {\n '--a63-avatar-ring-fill':\n 'conic-gradient(from 210deg, var(--a63-category-amber), var(--a63-category-orange), var(--a63-category-pink), var(--a63-category-purple), var(--a63-category-amber))',\n alignItems: 'flex-start',\n display: 'flex',\n gap: 20,\n padding: 8,\n } as CSSProperties\n }\n >\n {[\n { name: 'Your story', ring: 'unseen', initials: 'YZ' },\n { name: 'Ada', ring: 'unseen', initials: 'AD' },\n { name: 'Lin', ring: 'seen', initials: 'LI' },\n { name: 'Sam', ring: 'seen', initials: 'SA' },\n ].map(story => (\n <figure\n key={story.name}\n style={{\n alignItems: 'center',\n display: 'flex',\n flexDirection: 'column',\n gap: 8,\n margin: 0,\n }}\n >\n <Avatar ring={story.ring as 'unseen' | 'seen'} size=\"lg\">\n <AvatarFallback>{story.initials}</AvatarFallback>\n </Avatar>\n <figcaption style={{ fontSize: 12 }}>{story.name}</figcaption>\n </figure>\n ))}\n </div>\n ),\n}\n\n/* Fallback shows when no image resolves — the muted initials chip. */\nexport const Fallback: Story = {\n render: () => (\n <Avatar>\n <AvatarFallback>YZ</AvatarFallback>\n </Avatar>\n ),\n}\n\n/* A status Badge pinned to the corner, ringed against the page. */\nexport const WithBadge: Story = {\n render: () => (\n <Avatar>\n <AvatarImage src={SRC} alt=\"Ada\" />\n <AvatarFallback>AL</AvatarFallback>\n <AvatarBadge />\n </Avatar>\n ),\n}\n\n/* A stacked group with an overflow count. */\nexport const Group: Story = {\n render: () => (\n <AvatarGroup>\n <Avatar>\n <AvatarImage src=\"https://i.pravatar.cc/80?img=1\" alt=\"One\" />\n <AvatarFallback>1</AvatarFallback>\n </Avatar>\n <Avatar>\n <AvatarImage src=\"https://i.pravatar.cc/80?img=2\" alt=\"Two\" />\n <AvatarFallback>2</AvatarFallback>\n </Avatar>\n <Avatar>\n <AvatarImage src=\"https://i.pravatar.cc/80?img=3\" alt=\"Three\" />\n <AvatarFallback>3</AvatarFallback>\n </Avatar>\n <AvatarGroupCount>+5</AvatarGroupCount>\n </AvatarGroup>\n ),\n}\n\n/* The avatar frame, fallback chip and status badge across all 4 DS themes × light/dark. */\nexport const Themes: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12 }}>\n {themes.map(theme =>\n (['light', 'dark'] as const).map(mode => (\n <UIProvider key={theme + mode} mode={mode} theme={theme}>\n <div\n style={{\n alignItems: 'center',\n background: 'var(--a63-surface-panel)',\n borderRadius: 'var(--radius-lg)',\n color: 'var(--a63-text-primary)',\n display: 'flex',\n gap: 12,\n padding: '0.75rem',\n }}\n >\n <span style={{ fontSize: 12, color: 'var(--a63-text-secondary)', width: 96 }}>\n {theme} / {mode}\n </span>\n <Avatar>\n <AvatarImage src={SRC} alt=\"Ada\" />\n <AvatarFallback>AL</AvatarFallback>\n <AvatarBadge />\n </Avatar>\n <Avatar>\n <AvatarFallback>YZ</AvatarFallback>\n </Avatar>\n </div>\n </UIProvider>\n ))\n )}\n </div>\n ),\n}\n\nexport const Endpoints: Story = {\n render: () => (\n <div\n style={{\n display: 'grid',\n gap: '1rem',\n gridTemplateColumns: 'repeat(auto-fit, minmax(14rem, 1fr))',\n }}\n >\n {[\n { label: 'web / pointer', props: { designLanguage: 'web', input: 'pointer' } as const },\n { label: 'ios / touch', props: { designLanguage: 'ios', input: 'touch' } as const },\n {\n label: 'extension / compact',\n props: { density: 'compact', designLanguage: 'web', input: 'pointer' } as const,\n },\n ].map(({ label, props }) => (\n <UIProvider key={label} {...props}>\n <div\n style={{\n background: 'var(--a63-surface-panel)',\n border: '1px solid var(--a63-border-subtle)',\n borderRadius: 'var(--radius-lg)',\n color: 'var(--a63-text-primary)',\n display: 'grid',\n gap: '0.75rem',\n padding: '1rem',\n }}\n >\n <span style={{ color: 'var(--a63-text-secondary)', fontSize: 12 }}>{label}</span>\n <AvatarGroup>\n <Avatar>\n <AvatarImage alt=\"Ada\" src={SRC} />\n <AvatarFallback>AL</AvatarFallback>\n </Avatar>\n <Avatar>\n <AvatarFallback>YZ</AvatarFallback>\n </Avatar>\n <AvatarGroupCount>+3</AvatarGroupCount>\n </AvatarGroup>\n </div>\n </UIProvider>\n ))}\n </div>\n ),\n}\n\nexport const ContractMetadata: Story = {\n render: () => (\n <pre style={{ fontSize: 12, margin: 0, whiteSpace: 'pre-wrap' }}>\n {JSON.stringify(avatarContract, null, 2)}\n </pre>\n ),\n}\n"
11001
+ "source": "import { avatarContract, avatarSizes, themes } from '@atom63/ui-foundation'\nimport {\n Avatar,\n AvatarBadge,\n AvatarFallback,\n AvatarGroup,\n AvatarGroupCount,\n AvatarImage,\n UIProvider,\n} from '@atom63/ui-react'\nimport '@atom63/ui-react/styles.css'\nimport type { Meta, StoryObj } from '@storybook/react-vite'\nimport { Sparkles } from 'lucide-react'\nimport type { CSSProperties } from 'react'\n\nconst meta = {\n title: 'UI React/Avatar',\n component: Avatar,\n args: { size: 'md' },\n argTypes: { size: { control: 'inline-radio', options: avatarSizes } },\n} satisfies Meta<typeof Avatar>\n\nexport default meta\ntype Story = StoryObj<typeof meta>\n\nconst SRC = 'https://i.pravatar.cc/80?img=12'\n\nexport const Playground: Story = {\n render: args => (\n <Avatar {...args}>\n <AvatarImage src={SRC} alt=\"Ada\" />\n <AvatarFallback>AL</AvatarFallback>\n </Avatar>\n ),\n}\n\nexport const Sizes: Story = {\n render: () => (\n <div style={{ alignItems: 'center', display: 'flex', gap: 16 }}>\n <Avatar size=\"xs\">\n <AvatarImage src={SRC} alt=\"Ada\" />\n <AvatarFallback>AL</AvatarFallback>\n </Avatar>\n <Avatar size=\"sm\">\n <AvatarImage src={SRC} alt=\"Ada\" />\n <AvatarFallback>AL</AvatarFallback>\n </Avatar>\n <Avatar size=\"md\">\n <AvatarImage src={SRC} alt=\"Ada\" />\n <AvatarFallback>AL</AvatarFallback>\n </Avatar>\n <Avatar size=\"lg\">\n <AvatarImage src={SRC} alt=\"Ada\" />\n <AvatarFallback>AL</AvatarFallback>\n </Avatar>\n </div>\n ),\n}\n\n/* An icon fallback, such as an assistant's sparkle, sits in the filled circle at\n the control icon size for each size step. */\nexport const IconFallback: Story = {\n render: () => (\n <div style={{ alignItems: 'center', display: 'flex', gap: 16 }}>\n {avatarSizes.map(size => (\n <Avatar key={size} size={size}>\n <AvatarFallback>\n <Sparkles aria-hidden />\n </AvatarFallback>\n </Avatar>\n ))}\n </div>\n ),\n}\n\n/* A 76px avatar stays a circle: the default reads --a63-avatar-radius (50%), and\n without that contract the fallback is --radius-pill, not the soft --radius-full. */\nexport const LargeCircle: Story = {\n render: () => (\n <div style={{ alignItems: 'center', display: 'flex', gap: 16 }}>\n <Avatar data-testid=\"contract\" style={{ '--avatar-size': '76px' } as CSSProperties}>\n <AvatarFallback>AL</AvatarFallback>\n </Avatar>\n <Avatar\n data-testid=\"fallback\"\n style={{ '--avatar-size': '76px', '--a63-avatar-radius': 'initial' } as CSSProperties}\n >\n <AvatarFallback>YZ</AvatarFallback>\n </Avatar>\n </div>\n ),\n play: ({ canvasElement }) => {\n const radius = (testId: string) => {\n const avatar = canvasElement.querySelector<HTMLElement>(`[data-testid=\"${testId}\"]`)\n return avatar ? getComputedStyle(avatar).borderTopLeftRadius : null\n }\n const actual = [radius('contract'), radius('fallback')]\n if (actual[0] !== '50%' || actual[1] !== '9999px') {\n throw new Error(`Expected radii 50% and 9999px, got ${actual.join(' and ')}`)\n }\n },\n}\n\n/* shape=\"square\" for organisations and apps; ring marks new activity. */\nexport const ShapesAndRing: Story = {\n render: () => (\n <div style={{ alignItems: 'center', display: 'flex', gap: 16 }}>\n <Avatar>\n <AvatarFallback>AL</AvatarFallback>\n </Avatar>\n <Avatar shape=\"square\">\n <AvatarFallback>NW</AvatarFallback>\n </Avatar>\n <Avatar ring>\n <AvatarFallback>JL</AvatarFallback>\n </Avatar>\n <Avatar ring shape=\"square\" size=\"lg\">\n <AvatarFallback>PS</AvatarFallback>\n </Avatar>\n <Avatar shape=\"square\" size=\"xs\">\n <AvatarFallback>A</AvatarFallback>\n </Avatar>\n </div>\n ),\n}\n\n/*\n * Story rings: unseen draws --a63-avatar-ring-fill, which a product can set to a\n * gradient of the category palette (see the content-colors rule); seen is a\n * thin border-coloured ring.\n */\nexport const StoryRings: Story = {\n render: () => (\n <div\n style={\n {\n '--a63-avatar-ring-fill':\n 'conic-gradient(from 210deg, var(--a63-category-amber), var(--a63-category-orange), var(--a63-category-pink), var(--a63-category-purple), var(--a63-category-amber))',\n alignItems: 'flex-start',\n display: 'flex',\n gap: 20,\n padding: 8,\n } as CSSProperties\n }\n >\n {[\n { name: 'Your story', ring: 'unseen', initials: 'YZ' },\n { name: 'Ada', ring: 'unseen', initials: 'AD' },\n { name: 'Lin', ring: 'seen', initials: 'LI' },\n { name: 'Sam', ring: 'seen', initials: 'SA' },\n ].map(story => (\n <figure\n key={story.name}\n style={{\n alignItems: 'center',\n display: 'flex',\n flexDirection: 'column',\n gap: 8,\n margin: 0,\n }}\n >\n <Avatar ring={story.ring as 'unseen' | 'seen'} size=\"lg\">\n <AvatarFallback>{story.initials}</AvatarFallback>\n </Avatar>\n <figcaption style={{ fontSize: 12 }}>{story.name}</figcaption>\n </figure>\n ))}\n </div>\n ),\n}\n\n/* Fallback shows when no image resolves — the muted initials chip. */\nexport const Fallback: Story = {\n render: () => (\n <Avatar>\n <AvatarFallback>YZ</AvatarFallback>\n </Avatar>\n ),\n}\n\n/* A status Badge pinned to the corner, ringed against the page. */\nexport const WithBadge: Story = {\n render: () => (\n <Avatar>\n <AvatarImage src={SRC} alt=\"Ada\" />\n <AvatarFallback>AL</AvatarFallback>\n <AvatarBadge />\n </Avatar>\n ),\n}\n\n/* A stacked group with an overflow count. */\nexport const Group: Story = {\n render: () => (\n <AvatarGroup>\n <Avatar>\n <AvatarImage src=\"https://i.pravatar.cc/80?img=1\" alt=\"One\" />\n <AvatarFallback>1</AvatarFallback>\n </Avatar>\n <Avatar>\n <AvatarImage src=\"https://i.pravatar.cc/80?img=2\" alt=\"Two\" />\n <AvatarFallback>2</AvatarFallback>\n </Avatar>\n <Avatar>\n <AvatarImage src=\"https://i.pravatar.cc/80?img=3\" alt=\"Three\" />\n <AvatarFallback>3</AvatarFallback>\n </Avatar>\n <AvatarGroupCount>+5</AvatarGroupCount>\n </AvatarGroup>\n ),\n}\n\n/* The avatar frame, fallback chip and status badge across all 4 DS themes × light/dark. */\nexport const Themes: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12 }}>\n {themes.map(theme =>\n (['light', 'dark'] as const).map(mode => (\n <UIProvider key={theme + mode} mode={mode} theme={theme}>\n <div\n style={{\n alignItems: 'center',\n background: 'var(--a63-surface-panel)',\n borderRadius: 'var(--radius-lg)',\n color: 'var(--a63-text-primary)',\n display: 'flex',\n gap: 12,\n padding: '0.75rem',\n }}\n >\n <span style={{ fontSize: 12, color: 'var(--a63-text-secondary)', width: 96 }}>\n {theme} / {mode}\n </span>\n <Avatar>\n <AvatarImage src={SRC} alt=\"Ada\" />\n <AvatarFallback>AL</AvatarFallback>\n <AvatarBadge />\n </Avatar>\n <Avatar>\n <AvatarFallback>YZ</AvatarFallback>\n </Avatar>\n </div>\n </UIProvider>\n ))\n )}\n </div>\n ),\n}\n\nexport const Endpoints: Story = {\n render: () => (\n <div\n style={{\n display: 'grid',\n gap: '1rem',\n gridTemplateColumns: 'repeat(auto-fit, minmax(14rem, 1fr))',\n }}\n >\n {[\n { label: 'web / pointer', props: { designLanguage: 'web', input: 'pointer' } as const },\n { label: 'ios / touch', props: { designLanguage: 'ios', input: 'touch' } as const },\n {\n label: 'extension / compact',\n props: { density: 'compact', designLanguage: 'web', input: 'pointer' } as const,\n },\n ].map(({ label, props }) => (\n <UIProvider key={label} {...props}>\n <div\n style={{\n background: 'var(--a63-surface-panel)',\n border: '1px solid var(--a63-border-subtle)',\n borderRadius: 'var(--radius-lg)',\n color: 'var(--a63-text-primary)',\n display: 'grid',\n gap: '0.75rem',\n padding: '1rem',\n }}\n >\n <span style={{ color: 'var(--a63-text-secondary)', fontSize: 12 }}>{label}</span>\n <AvatarGroup>\n <Avatar>\n <AvatarImage alt=\"Ada\" src={SRC} />\n <AvatarFallback>AL</AvatarFallback>\n </Avatar>\n <Avatar>\n <AvatarFallback>YZ</AvatarFallback>\n </Avatar>\n <AvatarGroupCount>+3</AvatarGroupCount>\n </AvatarGroup>\n </div>\n </UIProvider>\n ))}\n </div>\n ),\n}\n\nexport const ContractMetadata: Story = {\n render: () => (\n <pre style={{ fontSize: 12, margin: 0, whiteSpace: 'pre-wrap' }}>\n {JSON.stringify(avatarContract, null, 2)}\n </pre>\n ),\n}\n"
10929
11002
  },
10930
11003
  "summary": "Avatar composes an image, fallback, badge, and grouped identity presentation.",
10931
11004
  "usage": "Provide meaningful image alternative text and a stable fallback for failed or missing media.",
@@ -11049,8 +11122,11 @@
11049
11122
  "badge-dot"
11050
11123
  ],
11051
11124
  "source": "packages/ui-foundation/contracts/components/badge.json",
11125
+ "stateAliases": {
11126
+ "resting": "rest"
11127
+ },
11052
11128
  "states": [
11053
- "resting",
11129
+ "rest",
11054
11130
  "interactive",
11055
11131
  "disabled",
11056
11132
  "focus-visible"
@@ -11076,7 +11152,7 @@
11076
11152
  ],
11077
11153
  "importPath": "@atom63/ui-react",
11078
11154
  "label": "Badge",
11079
- "markdown": "# Badge\n\nBadge carries compact status or classification metadata beside primary content.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Keep badges short and non-interactive unless the surrounding semantic element owns the action.\n- Keep product data and fetching outside the presentational component.\n- Test long, empty, and narrow content before adding local layout overrides.\n\n## Usage\n\n```tsx\nimport { Badge } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Badge`\n\n**Types:** `BadgeProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/badge.json` (`badgeContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `variants` | `default`, `primary`, `secondary`, `destructive`, `outline`, `glass`, `muted`, `accent`, `error`, `info`, `success`, `warning`, `red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`, `neutral` | `default` |\n| `sizes` | `sm`, `md`, `lg` | `md` |\n| `dotColors` | `red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`, `neutral` | — |\n\n**Slots:** `badge`, `badge-dot`\n\n**States:** `resting`, `interactive`, `disabled`, `focus-visible`\n\n**Visual archetype:** Markers and keycaps — Compact presentational labels, statuses, and keyboard hints.\n\n### Web and iOS\n\nCommunicate a compact label or semantic status alongside primary content. Rendered by `AtomBadge` in SwiftUI, with `strict` parity.\n\n**Required states:** `neutral`, `accent`, `success`, `warning`, `error`\n\n**Shared outcomes:**\n\n- Label remains readable without color\n- Semantic tone retains meaning\n\n**Accessibility outcomes:**\n\n- Text does not rely on color\n\n**Platform adaptations:**\n\n- React: May expose palette-only decorative variants outside the shared semantic subset.\n- React: May show a leading category dot (dot prop).\n- SwiftUI: Uses a compact capsule that expands for Dynamic Type.\n\n## Related components\n\n- [Avatar](/components/component-avatar)\n- [Kbd](/components/component-kbd)\n- [Alert](/components/component-alert)\n",
11155
+ "markdown": "# Badge\n\nBadge carries compact status or classification metadata beside primary content.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Keep badges short and non-interactive unless the surrounding semantic element owns the action.\n- Keep product data and fetching outside the presentational component.\n- Test long, empty, and narrow content before adding local layout overrides.\n\n## Usage\n\n```tsx\nimport { Badge } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Badge`\n\n**Types:** `BadgeProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/badge.json` (`badgeContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `variants` | `default`, `primary`, `secondary`, `destructive`, `outline`, `glass`, `muted`, `accent`, `error`, `info`, `success`, `warning`, `red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`, `neutral` | `default` |\n| `sizes` | `sm`, `md`, `lg` | `md` |\n| `dotColors` | `red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald`, `teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`, `neutral` | — |\n\n**Deprecated aliases:** `resting` → `rest` (states)\n\n**Slots:** `badge`, `badge-dot`\n\n**States:** `rest`, `interactive`, `disabled`, `focus-visible`\n\n**Visual archetype:** Markers and keycaps — Compact presentational labels, statuses, and keyboard hints.\n\n### Web and iOS\n\nCommunicate a compact label or semantic status alongside primary content. Rendered by `AtomBadge` in SwiftUI, with `strict` parity.\n\n**Required states:** `neutral`, `accent`, `success`, `warning`, `error`\n\n**Shared outcomes:**\n\n- Label remains readable without color\n- Semantic tone retains meaning\n\n**Accessibility outcomes:**\n\n- Text does not rely on color\n\n**Platform adaptations:**\n\n- React: May expose palette-only decorative variants outside the shared semantic subset.\n- React: May show a leading category dot (dot prop).\n- SwiftUI: Uses a compact capsule that expands for Dynamic Type.\n\n## Related components\n\n- [Avatar](/components/component-avatar)\n- [Kbd](/components/component-kbd)\n- [Alert](/components/component-alert)\n",
11080
11156
  "related": [
11081
11157
  "avatar",
11082
11158
  "kbd",
@@ -12002,8 +12078,11 @@
12002
12078
  "feedback-state-content"
12003
12079
  ],
12004
12080
  "source": "packages/ui-foundation/contracts/components/feedback-state.json",
12081
+ "stateAliases": {
12082
+ "idle": "rest"
12083
+ },
12005
12084
  "states": [
12006
- "idle",
12085
+ "rest",
12007
12086
  "busy",
12008
12087
  "actionable"
12009
12088
  ],
@@ -12033,7 +12112,7 @@
12033
12112
  ],
12034
12113
  "importPath": "@atom63/ui-react",
12035
12114
  "label": "Feedback State",
12036
- "markdown": "# Feedback State\n\nFeedback State packages common empty, error, and no-results messages with actions.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Choose the kind that matches the recovery path and keep technical detail secondary.\n- Keep product data and fetching outside the presentational component.\n- Test long, empty, and narrow content before adding local layout overrides.\n\n## Usage\n\n```tsx\nimport { FeedbackState } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `FeedbackState`\n\n**Types:** `FeedbackStateAction`, `FeedbackStateIcon`, `FeedbackStateIconName`, `FeedbackStateKind`, `FeedbackStateProps`, `FeedbackStateSize`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/feedback-state.json` (`feedbackStateContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `kinds` | `empty`, `error`, `loading`, `not-found`, `no-results`, `offline`, `stale` | `empty` |\n| `sizes` | `inline`, `panel`, `page`, `widget` | `panel` |\n\n**Slots:** `feedback-state`, `feedback-state-header`, `feedback-state-media`, `feedback-state-title`, `feedback-state-description`, `feedback-state-content`\n\n**States:** `idle`, `busy`, `actionable`\n\n**Visual archetype:** Action controls — Momentary controls that perform an action now.\n\n## Related components\n\n- [Empty](/components/component-empty)\n- [Alert](/components/component-alert)\n- [Toaster](/components/component-toaster)\n",
12115
+ "markdown": "# Feedback State\n\nFeedback State packages common empty, error, and no-results messages with actions.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Choose the kind that matches the recovery path and keep technical detail secondary.\n- Keep product data and fetching outside the presentational component.\n- Test long, empty, and narrow content before adding local layout overrides.\n\n## Usage\n\n```tsx\nimport { FeedbackState } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `FeedbackState`\n\n**Types:** `FeedbackStateAction`, `FeedbackStateIcon`, `FeedbackStateIconName`, `FeedbackStateKind`, `FeedbackStateProps`, `FeedbackStateSize`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/feedback-state.json` (`feedbackStateContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `kinds` | `empty`, `error`, `loading`, `not-found`, `no-results`, `offline`, `stale` | `empty` |\n| `sizes` | `inline`, `panel`, `page`, `widget` | `panel` |\n\n**Deprecated aliases:** `idle` → `rest` (states)\n\n**Slots:** `feedback-state`, `feedback-state-header`, `feedback-state-media`, `feedback-state-title`, `feedback-state-description`, `feedback-state-content`\n\n**States:** `rest`, `busy`, `actionable`\n\n**Visual archetype:** Action controls — Momentary controls that perform an action now.\n\n## Related components\n\n- [Empty](/components/component-empty)\n- [Alert](/components/component-alert)\n- [Toaster](/components/component-toaster)\n",
12037
12116
  "related": [
12038
12117
  "empty",
12039
12118
  "alert",
@@ -12117,8 +12196,11 @@
12117
12196
  "frame-panel-footer"
12118
12197
  ],
12119
12198
  "source": "packages/ui-foundation/contracts/components/frame.json",
12199
+ "stateAliases": {
12200
+ "default": "rest"
12201
+ },
12120
12202
  "states": [
12121
- "default",
12203
+ "rest",
12122
12204
  "border-off",
12123
12205
  "border-subtle",
12124
12206
  "border-strong"
@@ -12150,7 +12232,7 @@
12150
12232
  ],
12151
12233
  "importPath": "@atom63/ui-react",
12152
12234
  "label": "Frame",
12153
- "markdown": "# Frame\n\nFrame composes header, panel, description, and footer regions into a chrome-aware surface.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Use it for application chrome with distinct regions; use Card for content-first composition.\n- Keep product data and fetching outside the presentational component.\n- Test long, empty, and narrow content before adding local layout overrides.\n\n## Usage\n\n```tsx\nimport { Frame, FrameHeader, FrameTitle, FramePanel } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Frame`, `FrameDescription`, `FrameFooter`, `FrameHeader`, `FramePanel`, `FrameTitle`\n\n**Types:** `FramePanelProps`, `FrameProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/frame.json` (`frameContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `variants` | `muted-background`, `muted-card` | `muted-background` |\n| `trays` | `muted`, `card`, `background` | — |\n| `panelSurfaces` | `background`, `card`, `muted` | — |\n| `borders` | `off`, `subtle`, `strong` | `strong` |\n\n**Slots:** `frame`, `frame-panel`, `frame-panel-header`, `frame-panel-title`, `frame-panel-description`, `frame-panel-footer`\n\n**States:** `default`, `border-off`, `border-subtle`, `border-strong`\n\n**Visual archetype:** Static content surfaces — In-flow containers and content surfaces that do not inherently manipulate state.\n\n## Related components\n\n- [Card](/components/component-card)\n- [Connected Panel](/components/component-connected-panel)\n",
12235
+ "markdown": "# Frame\n\nFrame composes header, panel, description, and footer regions into a chrome-aware surface.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Use it for application chrome with distinct regions; use Card for content-first composition.\n- Keep product data and fetching outside the presentational component.\n- Test long, empty, and narrow content before adding local layout overrides.\n\n## Usage\n\n```tsx\nimport { Frame, FrameHeader, FrameTitle, FramePanel } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Frame`, `FrameDescription`, `FrameFooter`, `FrameHeader`, `FramePanel`, `FrameTitle`\n\n**Types:** `FramePanelProps`, `FrameProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/frame.json` (`frameContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `variants` | `muted-background`, `muted-card` | `muted-background` |\n| `trays` | `muted`, `card`, `background` | — |\n| `panelSurfaces` | `background`, `card`, `muted` | — |\n| `borders` | `off`, `subtle`, `strong` | `strong` |\n\n**Deprecated aliases:** `default` → `rest` (states)\n\n**Slots:** `frame`, `frame-panel`, `frame-panel-header`, `frame-panel-title`, `frame-panel-description`, `frame-panel-footer`\n\n**States:** `rest`, `border-off`, `border-subtle`, `border-strong`\n\n**Visual archetype:** Static content surfaces — In-flow containers and content surfaces that do not inherently manipulate state.\n\n## Related components\n\n- [Card](/components/component-card)\n- [Connected Panel](/components/component-connected-panel)\n",
12154
12236
  "related": [
12155
12237
  "card",
12156
12238
  "connected-panel"
@@ -12202,11 +12284,14 @@
12202
12284
  {
12203
12285
  "name": "sizes",
12204
12286
  "values": [
12205
- "default",
12287
+ "md",
12206
12288
  "sm",
12207
12289
  "xs"
12208
12290
  ],
12209
- "default": "default"
12291
+ "deprecatedAliases": {
12292
+ "default": "md"
12293
+ },
12294
+ "default": "md"
12210
12295
  },
12211
12296
  {
12212
12297
  "name": "mediaVariants",
@@ -12287,10 +12372,13 @@
12287
12372
  "item-separator"
12288
12373
  ],
12289
12374
  "source": "packages/ui-foundation/contracts/components/item.json",
12375
+ "stateAliases": {
12376
+ "focus": "focus-visible"
12377
+ },
12290
12378
  "states": [
12291
12379
  "rest",
12292
12380
  "hover",
12293
- "focus",
12381
+ "focus-visible",
12294
12382
  "selected",
12295
12383
  "current"
12296
12384
  ],
@@ -12327,7 +12415,7 @@
12327
12415
  ],
12328
12416
  "importPath": "@atom63/ui-react",
12329
12417
  "label": "Item",
12330
- "markdown": "# Item\n\nItem provides structured row regions for media, content, actions, and supporting detail.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Keep the row hierarchy predictable and avoid nesting unrelated actions inside a row-level link. For a dense list (an inbox, a message list), pass size=\"sm\" (12px block padding) or size=\"xs\" (8px); the default is 16px.\n- Keep product data and fetching outside the presentational component.\n- Test long, empty, and narrow content before adding local layout overrides.\n\n## Usage\n\n```tsx\nimport { Item, ItemContent, ItemTitle, ItemActions } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Item`, `ItemActions`, `ItemContent`, `ItemDescription`, `ItemFooter`, `ItemGroup`, `ItemHeader`, `ItemMedia`, `ItemSeparator`, `ItemTitle`\n\n**Types:** `ItemGroupProps`, `ItemMediaProps`, `ItemProps`, `ItemSeparatorProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/item.json` (`itemContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `variants` | `default`, `outline`, `muted` | `default` |\n| `sizes` | `default`, `sm`, `xs` | `default` |\n| `mediaVariants` | `default`, `icon`, `image` | `default` |\n| `groupVariants` | `default`, `inset` | `default` |\n| `groupSurfaces` | `card`, `muted` | `card` |\n| `tones` | `neutral`, `accent` | `neutral` |\n\n**Slots:** `item-group`, `item`, `item-media`, `item-content`, `item-title`, `item-description`, `item-actions`, `item-header`, `item-footer`, `item-separator`\n\n**States:** `rest`, `hover`, `focus`, `selected`, `current`\n\n**Visual archetype:** Static content surfaces — In-flow containers and content surfaces that do not inherently manipulate state.\n\n### Web and iOS\n\nGroup related rows on one inset surface with a divider between rows, as in a grouped settings list. Rendered by `AtomListSection` in SwiftUI, with `platform-adaptive` parity.\n\n**Required states:** `rest`\n\n**Shared outcomes:**\n\n- Rows keep reading order\n- Dividers are decorative\n\n**Accessibility outcomes:**\n\n- Preserves row order\n- Hides dividers from assistive technology\n\n**Platform adaptations:**\n\n- React: ItemGroup variant=\"inset\" draws the group; a heading above it and a note below it belong to the page.\n- React: ItemGroup surface=\"muted\" fills the inset group with the muted grey, for a white page (bg-card); the default card fill sits on the grey page.\n- React: A row that navigates is an Item rendered as a link, with its value in bold and a chevron in ItemActions.\n- React: In the phone form factor an inset group's default and sm rows are at least 52px tall (--a63-inset-row-min-size) and the card has the 2xl corner (--a63-inset-group-radius); elsewhere they keep the control-height floor and --radius-lg.\n- SwiftUI: AtomListSection draws the group inside a ScrollView and takes an optional header and footer; inside a List or Form, the native Section draws it.\n- SwiftUI: AtomListSection(surface: .muted) fills the section with surfaceMuted for a surfacePanel page; the default .card fill sits on surfacePage.\n- SwiftUI: AtomListSection rows are at least 52pt tall, scaled with Dynamic Type, and the section has an 18pt continuous corner.\n- SwiftUI: AtomValueRow(_:value:emphasizesValue:showsDisclosure:) is the label, value and chevron row.\n- SwiftUI: Rows pad themselves with atomListRowInsets() inside their tap area, so a NavigationLink or Button row is tappable edge to edge; Atom63 rows do it already, and a custom row takes the modifier inside its label.\n\n## Related components\n\n- [Card](/components/component-card)\n- [Separator](/components/component-separator)\n- [Avatar](/components/component-avatar)\n",
12418
+ "markdown": "# Item\n\nItem provides structured row regions for media, content, actions, and supporting detail.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Keep the row hierarchy predictable and avoid nesting unrelated actions inside a row-level link. For a dense list (an inbox, a message list), pass size=\"sm\" (12px block padding) or size=\"xs\" (8px); the default is 16px.\n- Keep product data and fetching outside the presentational component.\n- Test long, empty, and narrow content before adding local layout overrides.\n\n## Usage\n\n```tsx\nimport { Item, ItemContent, ItemTitle, ItemActions } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Item`, `ItemActions`, `ItemContent`, `ItemDescription`, `ItemFooter`, `ItemGroup`, `ItemHeader`, `ItemMedia`, `ItemSeparator`, `ItemTitle`\n\n**Types:** `ItemGroupProps`, `ItemMediaProps`, `ItemProps`, `ItemSeparatorProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/item.json` (`itemContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `variants` | `default`, `outline`, `muted` | `default` |\n| `sizes` | `md`, `sm`, `xs` | `md` |\n| `mediaVariants` | `default`, `icon`, `image` | `default` |\n| `groupVariants` | `default`, `inset` | `default` |\n| `groupSurfaces` | `card`, `muted` | `card` |\n| `tones` | `neutral`, `accent` | `neutral` |\n\n**Deprecated aliases:** `default` → `md` (sizes), `focus` → `focus-visible` (states)\n\n**Slots:** `item-group`, `item`, `item-media`, `item-content`, `item-title`, `item-description`, `item-actions`, `item-header`, `item-footer`, `item-separator`\n\n**States:** `rest`, `hover`, `focus-visible`, `selected`, `current`\n\n**Visual archetype:** Static content surfaces — In-flow containers and content surfaces that do not inherently manipulate state.\n\n### Web and iOS\n\nGroup related rows on one inset surface with a divider between rows, as in a grouped settings list. Rendered by `AtomListSection` in SwiftUI, with `platform-adaptive` parity.\n\n**Required states:** `rest`\n\n**Shared outcomes:**\n\n- Rows keep reading order\n- Dividers are decorative\n\n**Accessibility outcomes:**\n\n- Preserves row order\n- Hides dividers from assistive technology\n\n**Platform adaptations:**\n\n- React: ItemGroup variant=\"inset\" draws the group; a heading above it and a note below it belong to the page.\n- React: ItemGroup surface=\"muted\" fills the inset group with the muted grey, for a white page (bg-card); the default card fill sits on the grey page.\n- React: A row that navigates is an Item rendered as a link, with its value in bold and a chevron in ItemActions.\n- React: In the phone form factor an inset group's default and sm rows are at least 52px tall (--a63-inset-row-min-size) and the card has the 2xl corner (--a63-inset-group-radius); elsewhere they keep the control-height floor and --radius-lg.\n- SwiftUI: AtomListSection draws the group inside a ScrollView and takes an optional header and footer; inside a List or Form, the native Section draws it.\n- SwiftUI: AtomListSection(surface: .muted) fills the section with surfaceMuted for a surfacePanel page; the default .card fill sits on surfacePage.\n- SwiftUI: AtomListSection rows are at least 52pt tall, scaled with Dynamic Type, and the section has an 18pt continuous corner.\n- SwiftUI: AtomValueRow(_:value:emphasizesValue:showsDisclosure:) is the label, value and chevron row.\n- SwiftUI: Rows pad themselves with atomListRowInsets() inside their tap area, so a NavigationLink or Button row is tappable edge to edge; Atom63 rows do it already, and a custom row takes the modifier inside its label.\n\n## Related components\n\n- [Card](/components/component-card)\n- [Separator](/components/component-separator)\n- [Avatar](/components/component-avatar)\n",
12331
12419
  "related": [
12332
12420
  "card",
12333
12421
  "separator",
@@ -12352,7 +12440,7 @@
12352
12440
  "Endpoints",
12353
12441
  "ContractMetadata"
12354
12442
  ],
12355
- "source": "import { itemContract, itemTones, themes } from '@atom63/ui-foundation'\nimport { Bookmark, ChevronRight } from 'lucide-react'\nimport {\n Button,\n Item,\n ItemActions,\n ItemContent,\n ItemDescription,\n ItemGroup,\n ItemMedia,\n ItemSeparator,\n ItemTitle,\n Switch,\n UIProvider,\n} from '@atom63/ui-react'\nimport '@atom63/ui-react/styles.css'\nimport type { Meta, StoryObj } from '@storybook/react-vite'\n\nconst meta = {\n title: 'UI React/Item',\n component: Item,\n} satisfies Meta<typeof Item>\n\nexport default meta\ntype Story = StoryObj<typeof meta>\n\nexport const Playground: Story = {\n render: () => (\n <div style={{ width: 'min(360px, 100%)' }}>\n <Item variant=\"outline\">\n <ItemMedia variant=\"icon\">\n <Bookmark aria-hidden />\n </ItemMedia>\n <ItemContent>\n <ItemTitle>Starred project</ItemTitle>\n <ItemDescription>Last edited 2 hours ago by you.</ItemDescription>\n </ItemContent>\n <ItemActions>\n <Button size=\"sm\" type=\"button\" variant=\"secondary\">\n Open\n </Button>\n </ItemActions>\n </Item>\n </div>\n ),\n}\n\nexport const Variants: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12, width: 360 }}>\n {(['default', 'outline', 'muted'] as const).map(variant => (\n <Item key={variant} variant={variant}>\n <ItemContent>\n <ItemTitle>{variant}</ItemTitle>\n <ItemDescription>The {variant} chrome.</ItemDescription>\n </ItemContent>\n </Item>\n ))}\n </div>\n ),\n}\n\n/* A grouped list with separators; sizes tighten the row density. */\nexport const Group: Story = {\n render: () => (\n <div style={{ width: 360 }}>\n <ItemGroup>\n <Item size=\"sm\" variant=\"outline\">\n <ItemContent>\n <ItemTitle>First</ItemTitle>\n </ItemContent>\n </Item>\n <ItemSeparator />\n <Item size=\"sm\" variant=\"outline\">\n <ItemContent>\n <ItemTitle>Second</ItemTitle>\n </ItemContent>\n </Item>\n </ItemGroup>\n </div>\n ),\n}\n\n/* A clickable row via the render prop (renders an <a>, gets a muted hover). */\nexport const AsLink: Story = {\n render: () => (\n <div style={{ width: 360 }}>\n <Item\n render={\n <a href=\"#item-link\">\n <ItemContent>\n <ItemTitle>Clickable row</ItemTitle>\n <ItemDescription>Renders as an anchor.</ItemDescription>\n </ItemContent>\n </a>\n }\n variant=\"outline\"\n />\n </div>\n ),\n}\n\n/* aria-current marks the row for the page the user is on; data-selected marks\n a picked row that is not a link. Both take the selected surface. */\nexport const SelectedAndCurrent: Story = {\n render: () => (\n <ItemGroup style={{ width: 360 }}>\n {['Inbox', 'My issues', 'Projects'].map(label => (\n <Item\n key={label}\n render={\n <a aria-current={label === 'My issues' ? 'page' : undefined} href={`#${label}`}>\n <ItemContent>\n <ItemTitle>{label}</ItemTitle>\n </ItemContent>\n </a>\n }\n size=\"xs\"\n />\n ))}\n <Item data-selected=\"\" size=\"xs\" variant=\"muted\">\n <ItemContent>\n <ItemTitle>Selected row</ItemTitle>\n <ItemDescription>Not a link: data-selected.</ItemDescription>\n </ItemContent>\n </Item>\n </ItemGroup>\n ),\n}\n\n/* tone sets how a selected or current row is coloured: neutral (the default)\n is a muted fill with primary text, accent is the opt-in primary wash. */\nexport const Tones: Story = {\n render: () => (\n <div style={{ display: 'flex', flexWrap: 'wrap', gap: 24 }}>\n {itemTones.map(tone => (\n <ItemGroup key={tone} style={{ width: 240 }}>\n {['Inbox', 'My issues', 'Projects'].map(label => (\n <Item\n key={label}\n render={\n <a aria-current={label === 'My issues' ? 'page' : undefined} href={`#${label}`}>\n <ItemContent>\n <ItemTitle>{label}</ItemTitle>\n </ItemContent>\n </a>\n }\n size=\"xs\"\n tone={tone}\n />\n ))}\n <Item data-selected=\"\" size=\"xs\" tone={tone}>\n <ItemContent>\n <ItemTitle>Selected row</ItemTitle>\n <ItemDescription>tone=&quot;{tone}&quot;</ItemDescription>\n </ItemContent>\n </Item>\n </ItemGroup>\n ))}\n </div>\n ),\n}\n\n/* variant=\"inset\": the grouped settings list, each row a label with its value\n in bold and a chevron (the web side of iOS AtomValueRow). */\nexport const InsetGroup: Story = {\n render: () => (\n <div style={{ background: 'var(--a63-surface-page)', padding: 16, width: 360 }}>\n <ItemGroup variant=\"inset\">\n {[\n ['Units of measure', 'Imperial'],\n ['Active energy', 'kcal'],\n ['Start week on', 'Sunday'],\n ].map(([label, value]) => (\n <Item\n key={label}\n render={\n <a href={`#${label}`}>\n <ItemContent>\n <ItemTitle>{label}</ItemTitle>\n </ItemContent>\n <ItemActions>\n <strong>{value}</strong>\n <ChevronRight aria-hidden />\n </ItemActions>\n </a>\n }\n size=\"sm\"\n />\n ))}\n </ItemGroup>\n </div>\n ),\n}\n\n/* surface=\"muted\": grey cards on a white page (bg-card), the other common\n grouped-settings look. Inside the phone form factor, as AppView layout=\"phone\"\n draws it, the switch takes the iOS 26 shape, rows are 52px tall and the card\n has an 18px corner. */\nexport const InsetGroupMuted: Story = {\n render: () => (\n <div\n data-a63-form-factor=\"phone\"\n style={{\n background: 'var(--a63-surface-panel)',\n display: 'grid',\n gap: 24,\n padding: 16,\n width: 'min(390px, 100%)',\n }}\n >\n <ItemGroup surface=\"muted\" variant=\"inset\">\n {[\n ['Units of measure', 'Imperial'],\n ['Start week on', 'Sunday'],\n ].map(([label, value]) => (\n <Item\n key={label}\n render={\n <a href={`#${label}`}>\n <ItemContent>\n <ItemTitle>{label}</ItemTitle>\n </ItemContent>\n <ItemActions>\n <strong>{value}</strong>\n <ChevronRight aria-hidden />\n </ItemActions>\n </a>\n }\n size=\"sm\"\n />\n ))}\n </ItemGroup>\n <ItemGroup surface=\"muted\" variant=\"inset\">\n {(\n [\n ['Include steps', true],\n ['Sync with Health', false],\n ] as const\n ).map(([label, checked]) => (\n <Item key={label} size=\"sm\">\n <ItemContent>\n <ItemTitle>{label}</ItemTitle>\n </ItemContent>\n <ItemActions>\n <Switch aria-label={label} defaultChecked={checked} />\n </ItemActions>\n </Item>\n ))}\n </ItemGroup>\n </div>\n ),\n}\n\n/* Every size tightens the row density (default · sm · xs). */\nexport const Sizes: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12, width: 360 }}>\n {(['default', 'sm', 'xs'] as const).map(size => (\n <Item key={size} size={size} variant=\"outline\">\n <ItemMedia variant=\"icon\">\n <Bookmark aria-hidden />\n </ItemMedia>\n <ItemContent>\n <ItemTitle>{size}</ItemTitle>\n <ItemDescription>The {size} row density.</ItemDescription>\n </ItemContent>\n </Item>\n ))}\n </div>\n ),\n}\n\n/* Renders a representative Item across all 4 DS themes × light/dark. */\nexport const Themes: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12 }}>\n {themes.map(theme =>\n (['light', 'dark'] as const).map(mode => (\n <UIProvider key={`${theme}-${mode}`} mode={mode} theme={theme}>\n <div\n style={{\n display: 'flex',\n alignItems: 'center',\n gap: 12,\n padding: '0.75rem',\n background: 'var(--a63-surface-panel)',\n color: 'var(--a63-text-primary)',\n borderRadius: 'var(--a63-surface-radius, var(--radius-lg))',\n }}\n >\n <span style={{ fontSize: 12, color: 'var(--a63-text-secondary)', width: 96 }}>\n {theme} / {mode}\n </span>\n <div style={{ width: 320 }}>\n <Item variant=\"outline\">\n <ItemMedia variant=\"icon\">\n <Bookmark aria-hidden />\n </ItemMedia>\n <ItemContent>\n <ItemTitle>Starred project</ItemTitle>\n <ItemDescription>Last edited 2 hours ago.</ItemDescription>\n </ItemContent>\n <ItemActions>\n <Button size=\"sm\" type=\"button\" variant=\"secondary\">\n Open\n </Button>\n </ItemActions>\n </Item>\n </div>\n </div>\n </UIProvider>\n ))\n )}\n </div>\n ),\n}\n\nexport const Endpoints: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12 }}>\n <UIProvider designLanguage=\"web\" input=\"pointer\">\n <EndpointItem label=\"Web\" />\n </UIProvider>\n <UIProvider designLanguage=\"ios\" input=\"touch\">\n <EndpointItem label=\"iOS touch\" />\n </UIProvider>\n <UIProvider density=\"compact\" designLanguage=\"web\" input=\"pointer\">\n <EndpointItem label=\"Compact extension\" />\n </UIProvider>\n </div>\n ),\n}\n\nexport const ContractMetadata: Story = {\n render: () => (\n <pre style={{ fontSize: 12, margin: 0, whiteSpace: 'pre-wrap' }}>\n {JSON.stringify(itemContract, null, 2)}\n </pre>\n ),\n}\n\nfunction EndpointItem({ label }: { label: string }) {\n return (\n <div\n style={{\n alignItems: 'center',\n background: 'var(--a63-surface-panel)',\n color: 'var(--a63-text-primary)',\n display: 'flex',\n gap: 12,\n padding: 12,\n }}\n >\n <span style={{ fontSize: 12, color: 'var(--a63-text-secondary)', width: 112 }}>{label}</span>\n <div style={{ width: 320 }}>\n <Item variant=\"outline\">\n <ItemMedia variant=\"icon\">\n <Bookmark aria-hidden />\n </ItemMedia>\n <ItemContent>\n <ItemTitle>Starred project</ItemTitle>\n <ItemDescription>Last edited 2 hours ago.</ItemDescription>\n </ItemContent>\n <ItemActions>\n <Button size=\"sm\" type=\"button\" variant=\"secondary\">\n Open\n </Button>\n </ItemActions>\n </Item>\n </div>\n </div>\n )\n}\n"
12443
+ "source": "import { itemContract, itemTones, themes } from '@atom63/ui-foundation'\nimport { Bookmark, ChevronRight } from 'lucide-react'\nimport {\n Button,\n Item,\n ItemActions,\n ItemContent,\n ItemDescription,\n ItemGroup,\n ItemMedia,\n ItemSeparator,\n ItemTitle,\n Switch,\n UIProvider,\n} from '@atom63/ui-react'\nimport '@atom63/ui-react/styles.css'\nimport type { Meta, StoryObj } from '@storybook/react-vite'\n\nconst meta = {\n title: 'UI React/Item',\n component: Item,\n} satisfies Meta<typeof Item>\n\nexport default meta\ntype Story = StoryObj<typeof meta>\n\nexport const Playground: Story = {\n render: () => (\n <div style={{ width: 'min(360px, 100%)' }}>\n <Item variant=\"outline\">\n <ItemMedia variant=\"icon\">\n <Bookmark aria-hidden />\n </ItemMedia>\n <ItemContent>\n <ItemTitle>Starred project</ItemTitle>\n <ItemDescription>Last edited 2 hours ago by you.</ItemDescription>\n </ItemContent>\n <ItemActions>\n <Button size=\"sm\" type=\"button\" variant=\"secondary\">\n Open\n </Button>\n </ItemActions>\n </Item>\n </div>\n ),\n}\n\nexport const Variants: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12, width: 360 }}>\n {(['default', 'outline', 'muted'] as const).map(variant => (\n <Item key={variant} variant={variant}>\n <ItemContent>\n <ItemTitle>{variant}</ItemTitle>\n <ItemDescription>The {variant} chrome.</ItemDescription>\n </ItemContent>\n </Item>\n ))}\n </div>\n ),\n}\n\n/* A grouped list with separators; sizes tighten the row density. */\nexport const Group: Story = {\n render: () => (\n <div style={{ width: 360 }}>\n <ItemGroup>\n <Item size=\"sm\" variant=\"outline\">\n <ItemContent>\n <ItemTitle>First</ItemTitle>\n </ItemContent>\n </Item>\n <ItemSeparator />\n <Item size=\"sm\" variant=\"outline\">\n <ItemContent>\n <ItemTitle>Second</ItemTitle>\n </ItemContent>\n </Item>\n </ItemGroup>\n </div>\n ),\n}\n\n/* A clickable row via the render prop (renders an <a>, gets a muted hover). */\nexport const AsLink: Story = {\n render: () => (\n <div style={{ width: 360 }}>\n <Item\n render={\n <a href=\"#item-link\">\n <ItemContent>\n <ItemTitle>Clickable row</ItemTitle>\n <ItemDescription>Renders as an anchor.</ItemDescription>\n </ItemContent>\n </a>\n }\n variant=\"outline\"\n />\n </div>\n ),\n}\n\n/* aria-current marks the row for the page the user is on; data-selected marks\n a picked row that is not a link. Both take the selected surface. */\nexport const SelectedAndCurrent: Story = {\n render: () => (\n <ItemGroup style={{ width: 360 }}>\n {['Inbox', 'My issues', 'Projects'].map(label => (\n <Item\n key={label}\n render={\n <a aria-current={label === 'My issues' ? 'page' : undefined} href={`#${label}`}>\n <ItemContent>\n <ItemTitle>{label}</ItemTitle>\n </ItemContent>\n </a>\n }\n size=\"xs\"\n />\n ))}\n <Item data-selected=\"\" size=\"xs\" variant=\"muted\">\n <ItemContent>\n <ItemTitle>Selected row</ItemTitle>\n <ItemDescription>Not a link: data-selected.</ItemDescription>\n </ItemContent>\n </Item>\n </ItemGroup>\n ),\n}\n\n/* tone sets how a selected or current row is coloured: neutral (the default)\n is a muted fill with primary text, accent is the opt-in primary wash. */\nexport const Tones: Story = {\n render: () => (\n <div style={{ display: 'flex', flexWrap: 'wrap', gap: 24 }}>\n {itemTones.map(tone => (\n <ItemGroup key={tone} style={{ width: 240 }}>\n {['Inbox', 'My issues', 'Projects'].map(label => (\n <Item\n key={label}\n render={\n <a aria-current={label === 'My issues' ? 'page' : undefined} href={`#${label}`}>\n <ItemContent>\n <ItemTitle>{label}</ItemTitle>\n </ItemContent>\n </a>\n }\n size=\"xs\"\n tone={tone}\n />\n ))}\n <Item data-selected=\"\" size=\"xs\" tone={tone}>\n <ItemContent>\n <ItemTitle>Selected row</ItemTitle>\n <ItemDescription>tone=&quot;{tone}&quot;</ItemDescription>\n </ItemContent>\n </Item>\n </ItemGroup>\n ))}\n </div>\n ),\n}\n\n/* variant=\"inset\": the grouped settings list, each row a label with its value\n in bold and a chevron (the web side of iOS AtomValueRow). */\nexport const InsetGroup: Story = {\n render: () => (\n <div style={{ background: 'var(--a63-surface-page)', padding: 16, width: 360 }}>\n <ItemGroup variant=\"inset\">\n {[\n ['Units of measure', 'Imperial'],\n ['Active energy', 'kcal'],\n ['Start week on', 'Sunday'],\n ].map(([label, value]) => (\n <Item\n key={label}\n render={\n <a href={`#${label}`}>\n <ItemContent>\n <ItemTitle>{label}</ItemTitle>\n </ItemContent>\n <ItemActions>\n <strong>{value}</strong>\n <ChevronRight aria-hidden />\n </ItemActions>\n </a>\n }\n size=\"sm\"\n />\n ))}\n </ItemGroup>\n </div>\n ),\n}\n\n/* surface=\"muted\": grey cards on a white page (bg-card), the other common\n grouped-settings look. Inside the phone form factor, as AppView layout=\"phone\"\n draws it, the switch takes the iOS 26 shape, rows are 52px tall and the card\n has an 18px corner. */\nexport const InsetGroupMuted: Story = {\n render: () => (\n <div\n data-a63-form-factor=\"phone\"\n style={{\n background: 'var(--a63-surface-panel)',\n display: 'grid',\n gap: 24,\n padding: 16,\n width: 'min(390px, 100%)',\n }}\n >\n <ItemGroup surface=\"muted\" variant=\"inset\">\n {[\n ['Units of measure', 'Imperial'],\n ['Start week on', 'Sunday'],\n ].map(([label, value]) => (\n <Item\n key={label}\n render={\n <a href={`#${label}`}>\n <ItemContent>\n <ItemTitle>{label}</ItemTitle>\n </ItemContent>\n <ItemActions>\n <strong>{value}</strong>\n <ChevronRight aria-hidden />\n </ItemActions>\n </a>\n }\n size=\"sm\"\n />\n ))}\n </ItemGroup>\n <ItemGroup surface=\"muted\" variant=\"inset\">\n {(\n [\n ['Include steps', true],\n ['Sync with Health', false],\n ] as const\n ).map(([label, checked]) => (\n <Item key={label} size=\"sm\">\n <ItemContent>\n <ItemTitle>{label}</ItemTitle>\n </ItemContent>\n <ItemActions>\n <Switch aria-label={label} defaultChecked={checked} />\n </ItemActions>\n </Item>\n ))}\n </ItemGroup>\n </div>\n ),\n}\n\n/* Every size tightens the row density (md · sm · xs). */\nexport const Sizes: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12, width: 360 }}>\n {(['md', 'sm', 'xs'] as const).map(size => (\n <Item key={size} size={size} variant=\"outline\">\n <ItemMedia variant=\"icon\">\n <Bookmark aria-hidden />\n </ItemMedia>\n <ItemContent>\n <ItemTitle>{size}</ItemTitle>\n <ItemDescription>The {size} row density.</ItemDescription>\n </ItemContent>\n </Item>\n ))}\n </div>\n ),\n}\n\n/* Renders a representative Item across all 4 DS themes × light/dark. */\nexport const Themes: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12 }}>\n {themes.map(theme =>\n (['light', 'dark'] as const).map(mode => (\n <UIProvider key={`${theme}-${mode}`} mode={mode} theme={theme}>\n <div\n style={{\n display: 'flex',\n alignItems: 'center',\n gap: 12,\n padding: '0.75rem',\n background: 'var(--a63-surface-panel)',\n color: 'var(--a63-text-primary)',\n borderRadius: 'var(--a63-surface-radius, var(--radius-lg))',\n }}\n >\n <span style={{ fontSize: 12, color: 'var(--a63-text-secondary)', width: 96 }}>\n {theme} / {mode}\n </span>\n <div style={{ width: 320 }}>\n <Item variant=\"outline\">\n <ItemMedia variant=\"icon\">\n <Bookmark aria-hidden />\n </ItemMedia>\n <ItemContent>\n <ItemTitle>Starred project</ItemTitle>\n <ItemDescription>Last edited 2 hours ago.</ItemDescription>\n </ItemContent>\n <ItemActions>\n <Button size=\"sm\" type=\"button\" variant=\"secondary\">\n Open\n </Button>\n </ItemActions>\n </Item>\n </div>\n </div>\n </UIProvider>\n ))\n )}\n </div>\n ),\n}\n\nexport const Endpoints: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12 }}>\n <UIProvider designLanguage=\"web\" input=\"pointer\">\n <EndpointItem label=\"Web\" />\n </UIProvider>\n <UIProvider designLanguage=\"ios\" input=\"touch\">\n <EndpointItem label=\"iOS touch\" />\n </UIProvider>\n <UIProvider density=\"compact\" designLanguage=\"web\" input=\"pointer\">\n <EndpointItem label=\"Compact extension\" />\n </UIProvider>\n </div>\n ),\n}\n\nexport const ContractMetadata: Story = {\n render: () => (\n <pre style={{ fontSize: 12, margin: 0, whiteSpace: 'pre-wrap' }}>\n {JSON.stringify(itemContract, null, 2)}\n </pre>\n ),\n}\n\nfunction EndpointItem({ label }: { label: string }) {\n return (\n <div\n style={{\n alignItems: 'center',\n background: 'var(--a63-surface-panel)',\n color: 'var(--a63-text-primary)',\n display: 'flex',\n gap: 12,\n padding: 12,\n }}\n >\n <span style={{ fontSize: 12, color: 'var(--a63-text-secondary)', width: 112 }}>{label}</span>\n <div style={{ width: 320 }}>\n <Item variant=\"outline\">\n <ItemMedia variant=\"icon\">\n <Bookmark aria-hidden />\n </ItemMedia>\n <ItemContent>\n <ItemTitle>Starred project</ItemTitle>\n <ItemDescription>Last edited 2 hours ago.</ItemDescription>\n </ItemContent>\n <ItemActions>\n <Button size=\"sm\" type=\"button\" variant=\"secondary\">\n Open\n </Button>\n </ItemActions>\n </Item>\n </div>\n </div>\n )\n}\n"
12356
12444
  },
12357
12445
  "summary": "Item provides structured row regions for media, content, actions, and supporting detail.",
12358
12446
  "usage": "Keep the row hierarchy predictable and avoid nesting unrelated actions inside a row-level link. For a dense list (an inbox, a message list), pass size=\"sm\" (12px block padding) or size=\"xs\" (8px); the default is 16px.",
@@ -12537,9 +12625,13 @@
12537
12625
  "scroll-area-corner"
12538
12626
  ],
12539
12627
  "source": "packages/ui-foundation/contracts/components/scroll-area.json",
12628
+ "stateAliases": {
12629
+ "hovering": "hover",
12630
+ "idle": "rest"
12631
+ },
12540
12632
  "states": [
12541
- "idle",
12542
- "hovering",
12633
+ "rest",
12634
+ "hover",
12543
12635
  "scrolling",
12544
12636
  "focus-visible"
12545
12637
  ],
@@ -12565,7 +12657,7 @@
12565
12657
  ],
12566
12658
  "importPath": "@atom63/ui-react",
12567
12659
  "label": "Scroll Area",
12568
- "markdown": "# Scroll Area\n\nScroll Area supplies themed scrollbars while preserving native scrolling behavior.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Constrain its viewport explicitly and avoid hiding overflow that users still need to reach.\n- Keep product data and fetching outside the presentational component.\n- Test long, empty, and narrow content before adding local layout overrides.\n\n## Usage\n\n```tsx\nimport { ScrollArea, ScrollBar } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `ScrollArea`, `ScrollBar`\n\n**Types:** `ScrollAreaViewportProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/scroll-area.json` (`scrollAreaContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `orientations` | `vertical`, `horizontal`, `both` | `both` |\n| `options` | `scroll-fade`, `scrollbar-gutter`, `show-on-hover` | — |\n\n**Slots:** `scroll-area`, `scroll-area-viewport`, `scroll-area-scrollbar`, `scroll-area-thumb`, `scroll-area-corner`\n\n**States:** `idle`, `hovering`, `scrolling`, `focus-visible`\n\n**Visual archetype:** Range and track controls — Controls or indicators that represent a value along a rail.\n\n## Related components\n\n- [Scrollable List](/components/component-scrollable-list)\n- [Carousel](/components/component-carousel)\n",
12660
+ "markdown": "# Scroll Area\n\nScroll Area supplies themed scrollbars while preserving native scrolling behavior.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Constrain its viewport explicitly and avoid hiding overflow that users still need to reach.\n- Keep product data and fetching outside the presentational component.\n- Test long, empty, and narrow content before adding local layout overrides.\n\n## Usage\n\n```tsx\nimport { ScrollArea, ScrollBar } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `ScrollArea`, `ScrollBar`\n\n**Types:** `ScrollAreaViewportProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/scroll-area.json` (`scrollAreaContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `orientations` | `vertical`, `horizontal`, `both` | `both` |\n| `options` | `scroll-fade`, `scrollbar-gutter`, `show-on-hover` | — |\n\n**Deprecated aliases:** `hovering` → `hover` (states), `idle` → `rest` (states)\n\n**Slots:** `scroll-area`, `scroll-area-viewport`, `scroll-area-scrollbar`, `scroll-area-thumb`, `scroll-area-corner`\n\n**States:** `rest`, `hover`, `scrolling`, `focus-visible`\n\n**Visual archetype:** Range and track controls — Controls or indicators that represent a value along a rail.\n\n## Related components\n\n- [Scrollable List](/components/component-scrollable-list)\n- [Carousel](/components/component-carousel)\n",
12569
12661
  "related": [
12570
12662
  "scrollable-list",
12571
12663
  "carousel"
@@ -12634,8 +12726,11 @@
12634
12726
  "scrollable-list-control"
12635
12727
  ],
12636
12728
  "source": "packages/ui-foundation/contracts/components/scrollable-list.json",
12729
+ "stateAliases": {
12730
+ "idle": "rest"
12731
+ },
12637
12732
  "states": [
12638
- "idle",
12733
+ "rest",
12639
12734
  "can-scroll-start",
12640
12735
  "can-scroll-end",
12641
12736
  "dragging",
@@ -12663,7 +12758,7 @@
12663
12758
  ],
12664
12759
  "importPath": "@atom63/ui-react",
12665
12760
  "label": "Scrollable List",
12666
- "markdown": "# Scrollable List\n\nScrollable List adds edge masks and optional controls to overflowing row or column content.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Keep native scrolling available and use controls as an additional path, not the only one.\n- Keep product data and fetching outside the presentational component.\n- Test long, empty, and narrow content before adding local layout overrides.\n\n## Usage\n\n```tsx\nimport { ScrollableList } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `ScrollableList`, `scrollableListControlClassNames`\n\n**Types:** `ScrollableListProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/scrollable-list.json` (`scrollableListContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `layouts` | `scroll`, `wrap` | `scroll` |\n| `options` | `mask`, `chevrons`, `draggable`, `column-aligned` | — |\n\n**Slots:** `scrollable-list`, `scrollable-list-frame`, `scrollable-list-content`, `scrollable-list-control`\n\n**States:** `idle`, `can-scroll-start`, `can-scroll-end`, `dragging`, `disabled`\n\n**Visual archetype:** Action controls — Momentary controls that perform an action now.; Range and track controls — Controls or indicators that represent a value along a rail.\n\n## Related components\n\n- [Scroll Area](/components/component-scroll-area)\n- [Load More Trigger](/components/component-load-more-trigger)\n- [Carousel](/components/component-carousel)\n",
12761
+ "markdown": "# Scrollable List\n\nScrollable List adds edge masks and optional controls to overflowing row or column content.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Keep native scrolling available and use controls as an additional path, not the only one.\n- Keep product data and fetching outside the presentational component.\n- Test long, empty, and narrow content before adding local layout overrides.\n\n## Usage\n\n```tsx\nimport { ScrollableList } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `ScrollableList`, `scrollableListControlClassNames`\n\n**Types:** `ScrollableListProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/scrollable-list.json` (`scrollableListContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `layouts` | `scroll`, `wrap` | `scroll` |\n| `options` | `mask`, `chevrons`, `draggable`, `column-aligned` | — |\n\n**Deprecated aliases:** `idle` → `rest` (states)\n\n**Slots:** `scrollable-list`, `scrollable-list-frame`, `scrollable-list-content`, `scrollable-list-control`\n\n**States:** `rest`, `can-scroll-start`, `can-scroll-end`, `dragging`, `disabled`\n\n**Visual archetype:** Action controls — Momentary controls that perform an action now.; Range and track controls — Controls or indicators that represent a value along a rail.\n\n## Related components\n\n- [Scroll Area](/components/component-scroll-area)\n- [Load More Trigger](/components/component-load-more-trigger)\n- [Carousel](/components/component-carousel)\n",
12667
12762
  "related": [
12668
12763
  "scroll-area",
12669
12764
  "load-more-trigger",
@@ -12801,10 +12896,13 @@
12801
12896
  {
12802
12897
  "name": "sizes",
12803
12898
  "values": [
12804
- "default",
12899
+ "md",
12805
12900
  "sm"
12806
12901
  ],
12807
- "default": "default"
12902
+ "deprecatedAliases": {
12903
+ "default": "md"
12904
+ },
12905
+ "default": "md"
12808
12906
  },
12809
12907
  {
12810
12908
  "name": "stickyEdges",
@@ -12875,7 +12973,7 @@
12875
12973
  ],
12876
12974
  "importPath": "@atom63/ui-react",
12877
12975
  "label": "Table",
12878
- "markdown": "# Table\n\nTable provides semantic table regions with shared typography, spacing, and states.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Keep header relationships intact and add horizontal containment for genuinely wide data. For a dense table (admin, payments, issues), pass size=\"sm\": rows are 33px, and a row checkbox or a 24px row menu (size=\"icon-xs\") keeps its hit area without making the row taller.\n- Keep product data and fetching outside the presentational component.\n- Test long, empty, and narrow content before adding local layout overrides.\n\n## Usage\n\n```tsx\nimport { Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Table`, `TableBody`, `TableCaption`, `TableCell`, `TableFooter`, `TableHead`, `TableHeader`, `TableRow`\n\n**Types:** `TableBodyProps`, `TableCaptionProps`, `TableCellProps`, `TableFooterProps`, `TableHeadProps`, `TableHeaderProps`, `TableProps`, `TableRowProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/table.json` (`tableContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `variants` | `default`, `plain` | `default` |\n| `sizes` | `default`, `sm` | `default` |\n| `stickyEdges` | `start`, `end` | — |\n| `tones` | `neutral`, `accent` | `neutral` |\n\n**Slots:** `table-container`, `table`, `table-header`, `table-body`, `table-footer`, `table-row`, `table-head`, `table-cell`, `table-caption`\n\n**States:** `rest`, `row-hover`, `row-selected`\n\n**Visual archetype:** Static content surfaces — In-flow containers and content surfaces that do not inherently manipulate state.\n\n## Related components\n\n- [Pagination](/components/component-pagination)\n- [Scroll Area](/components/component-scroll-area)\n",
12976
+ "markdown": "# Table\n\nTable provides semantic table regions with shared typography, spacing, and states.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Keep header relationships intact and add horizontal containment for genuinely wide data. For a dense table (admin, payments, issues), pass size=\"sm\": rows are 33px, and a row checkbox or a 24px row menu (size=\"icon-xs\") keeps its hit area without making the row taller.\n- Keep product data and fetching outside the presentational component.\n- Test long, empty, and narrow content before adding local layout overrides.\n\n## Usage\n\n```tsx\nimport { Table, TableHeader, TableBody, TableRow, TableHead, TableCell } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Table`, `TableBody`, `TableCaption`, `TableCell`, `TableFooter`, `TableHead`, `TableHeader`, `TableRow`\n\n**Types:** `TableBodyProps`, `TableCaptionProps`, `TableCellProps`, `TableFooterProps`, `TableHeadProps`, `TableHeaderProps`, `TableProps`, `TableRowProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/table.json` (`tableContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `variants` | `default`, `plain` | `default` |\n| `sizes` | `md`, `sm` | `md` |\n| `stickyEdges` | `start`, `end` | — |\n| `tones` | `neutral`, `accent` | `neutral` |\n\n**Deprecated aliases:** `default` → `md` (sizes)\n\n**Slots:** `table-container`, `table`, `table-header`, `table-body`, `table-footer`, `table-row`, `table-head`, `table-cell`, `table-caption`\n\n**States:** `rest`, `row-hover`, `row-selected`\n\n**Visual archetype:** Static content surfaces — In-flow containers and content surfaces that do not inherently manipulate state.\n\n## Related components\n\n- [Pagination](/components/component-pagination)\n- [Scroll Area](/components/component-scroll-area)\n",
12879
12977
  "related": [
12880
12978
  "pagination",
12881
12979
  "scroll-area"
@@ -13561,8 +13659,11 @@
13561
13659
  "resizable-handle-grip"
13562
13660
  ],
13563
13661
  "source": "packages/ui-foundation/contracts/components/resizable.json",
13662
+ "stateAliases": {
13663
+ "idle": "rest"
13664
+ },
13564
13665
  "states": [
13565
- "idle",
13666
+ "rest",
13566
13667
  "hover",
13567
13668
  "focus-visible",
13568
13669
  "dragging",
@@ -13594,7 +13695,7 @@
13594
13695
  ],
13595
13696
  "importPath": "@atom63/ui-react",
13596
13697
  "label": "Resizable",
13597
- "markdown": "# Resizable\n\nResizable composes keyboard-operable panel groups, panels, and drag handles.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Horizontal` story maintained with the component.\n\n## Guidance\n\n- Give each panel usable minimums and make the handle visible when resizing is not otherwise obvious.\n- Keep the utility’s semantic purpose explicit instead of relying on visual treatment alone.\n- For animated or transient members, preserve reduced-motion behavior and surrounding layout.\n\n## Usage\n\n```tsx\nimport { ResizablePanelGroup, ResizablePanel, ResizableHandle } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `ResizableHandle`, `ResizablePanel`, `ResizablePanelGroup`\n\n**Types:** `ResizableHandleProps`, `ResizableOrientation`, `ResizablePanelGroupProps`, `ResizablePanelProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/resizable.json` (`resizableContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `orientations` | `horizontal`, `vertical` | `horizontal` |\n| `variants` | `line`, `grip` | — |\n\n**Slots:** `resizable-panel-group`, `resizable-panel`, `resizable-handle`, `resizable-handle-grip`\n\n**States:** `idle`, `hover`, `focus-visible`, `dragging`, `disabled`\n\n## Related components\n\n- [Separator](/components/component-separator)\n- [Sidebar](/components/component-sidebar)\n",
13698
+ "markdown": "# Resizable\n\nResizable composes keyboard-operable panel groups, panels, and drag handles.\n\n**Status:** Stable\n\n## Preview\n\nThe live documentation page renders the `Horizontal` story maintained with the component.\n\n## Guidance\n\n- Give each panel usable minimums and make the handle visible when resizing is not otherwise obvious.\n- Keep the utility’s semantic purpose explicit instead of relying on visual treatment alone.\n- For animated or transient members, preserve reduced-motion behavior and surrounding layout.\n\n## Usage\n\n```tsx\nimport { ResizablePanelGroup, ResizablePanel, ResizableHandle } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `ResizableHandle`, `ResizablePanel`, `ResizablePanelGroup`\n\n**Types:** `ResizableHandleProps`, `ResizableOrientation`, `ResizablePanelGroupProps`, `ResizablePanelProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/resizable.json` (`resizableContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `orientations` | `horizontal`, `vertical` | `horizontal` |\n| `variants` | `line`, `grip` | — |\n\n**Deprecated aliases:** `idle` → `rest` (states)\n\n**Slots:** `resizable-panel-group`, `resizable-panel`, `resizable-handle`, `resizable-handle-grip`\n\n**States:** `rest`, `hover`, `focus-visible`, `dragging`, `disabled`\n\n## Related components\n\n- [Separator](/components/component-separator)\n- [Sidebar](/components/component-sidebar)\n",
13598
13699
  "related": [
13599
13700
  "separator",
13600
13701
  "sidebar"
@@ -13834,7 +13935,7 @@
13834
13935
  "Endpoints",
13835
13936
  "ContractMetadata"
13836
13937
  ],
13837
- "source": "import { textTickerContract, themes } from '@atom63/ui-foundation'\nimport { TextTicker, UIProvider } from '@atom63/ui-react'\nimport '@atom63/ui-react/styles.css'\nimport type { Meta, StoryObj } from '@storybook/react-vite'\n\nconst meta = {\n title: 'UI React/TextTicker',\n component: TextTicker,\n args: {\n children: 'Now playing — A very long track title that will overflow its container',\n variant: 'marquee',\n autoPlay: false,\n marqueeSpeed: 24,\n marqueeDelay: 0,\n },\n argTypes: {\n variant: { control: 'inline-radio', options: ['truncate', 'marquee'] },\n autoPlay: { control: 'boolean' },\n marqueeSpeed: { control: { type: 'number', min: 4, max: 60 } },\n marqueeDelay: { control: { type: 'number', min: 0, max: 2000, step: 100 } },\n },\n} satisfies Meta<typeof TextTicker>\n\nexport default meta\ntype Story = StoryObj<typeof meta>\n\nconst frame = (child: React.ReactNode) => (\n <div\n style={{\n width: 220,\n padding: '0.5rem 0.75rem',\n border: '1px solid var(--a63-border-control)',\n borderRadius: 'var(--a63-control-radius)',\n background: 'var(--a63-surface-panel)',\n color: 'var(--a63-text-primary)',\n fontFamily: 'var(--a63-control-font-family)',\n fontSize: 14,\n }}\n >\n {child}\n </div>\n)\n\n/* Hover (or focus) the constrained frame to reveal the scrolling marquee. */\nexport const Playground: Story = {\n render: args => (\n <div style={{ display: 'grid', gap: 8 }}>\n {frame(<TextTicker {...args} tabIndex={0} />)}\n <span style={{ color: 'var(--a63-text-secondary)', fontSize: 12 }}>\n Hover or focus the title to reveal the full text\n </span>\n </div>\n ),\n}\n\n/* No overflow — the ticker simply renders the text (marquee never engages). */\nexport const FitsInContainer: Story = {\n args: { children: 'Short title' },\n render: args => frame(<TextTicker {...args} />),\n}\n\n/* autoPlay scrolls continuously once the content overflows, no hover needed. */\nexport const AutoPlay: Story = {\n args: { autoPlay: true },\n render: args => frame(<TextTicker {...args} />),\n}\n\n/* The default truncate variant is a plain truncating line. */\nexport const StaticTruncate: Story = {\n args: { variant: 'truncate' },\n render: args => frame(<TextTicker {...args} />),\n}\n\n/* The ticker across all 4 DS themes × light/dark. autoPlay so the marquee is\n visible without hover in the static grid. */\nexport const Themes: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12 }}>\n {themes.map(theme =>\n (['light', 'dark'] as const).map(mode => (\n <UIProvider key={`${theme}-${mode}`} mode={mode} theme={theme}>\n <div\n style={{\n alignItems: 'center',\n background: 'var(--a63-surface-panel)',\n borderRadius: 'var(--radius-lg)',\n color: 'var(--a63-text-primary)',\n display: 'flex',\n gap: 12,\n padding: '0.75rem',\n }}\n >\n <span style={{ fontSize: 12, color: 'var(--a63-text-secondary)', width: 96 }}>\n {theme} / {mode}\n </span>\n {frame(\n <TextTicker variant=\"marquee\" autoPlay marqueeSpeed={24}>\n Now playing — A very long track title that will overflow its container\n </TextTicker>\n )}\n </div>\n </UIProvider>\n ))\n )}\n </div>\n ),\n}\n\n/* Compare the same overflow behavior at the supported endpoint densities. */\nexport const Endpoints: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12 }}>\n <UIProvider designLanguage=\"web\" input=\"pointer\">\n {frame(\n <TextTicker variant=\"marquee\" autoPlay>\n Web — a long overflowing title for review\n </TextTicker>\n )}\n </UIProvider>\n <UIProvider designLanguage=\"ios\" input=\"touch\">\n {frame(\n <TextTicker variant=\"marquee\" autoPlay>\n iOS touch — a long overflowing title for review\n </TextTicker>\n )}\n </UIProvider>\n <UIProvider density=\"compact\">\n {frame(\n <TextTicker variant=\"marquee\" autoPlay>\n Compact extension — a long overflowing title\n </TextTicker>\n )}\n </UIProvider>\n </div>\n ),\n}\n\nexport const ContractMetadata: Story = {\n render: () => (\n <pre style={{ fontSize: 12, margin: 0, whiteSpace: 'pre-wrap' }}>\n {JSON.stringify(textTickerContract, null, 2)}\n </pre>\n ),\n}\n"
13938
+ "source": "import { textTickerContract, themes } from '@atom63/ui-foundation'\nimport { TextTicker, UIProvider } from '@atom63/ui-react'\nimport '@atom63/ui-react/styles.css'\nimport type { Meta, StoryObj } from '@storybook/react-vite'\n\nconst meta = {\n title: 'UI React/TextTicker',\n component: TextTicker,\n args: {\n children: 'Now playing — A very long track title that will overflow its container',\n variant: 'marquee',\n autoPlay: false,\n marqueeSpeed: 24,\n marqueeDelay: 0,\n },\n argTypes: {\n variant: { control: 'inline-radio', options: ['truncate', 'marquee'] },\n autoPlay: { control: 'boolean' },\n marqueeSpeed: { control: { type: 'number', min: 4, max: 60 } },\n marqueeDelay: { control: { type: 'number', min: 0, max: 2000, step: 100 } },\n },\n} satisfies Meta<typeof TextTicker>\n\nexport default meta\ntype Story = StoryObj<typeof meta>\n\nconst frame = (child: React.ReactNode) => (\n <div\n style={{\n width: 220,\n padding: '0.5rem 0.75rem',\n border: '1px solid var(--a63-border-control)',\n borderRadius: 'var(--a63-control-radius)',\n background: 'var(--a63-surface-panel)',\n color: 'var(--a63-text-primary)',\n fontFamily: 'var(--a63-control-font-family)',\n fontSize: 14,\n }}\n >\n {child}\n </div>\n)\n\n/* Hover (or focus) the constrained frame to reveal the scrolling marquee. */\nexport const Playground: Story = {\n render: args => (\n <div style={{ display: 'grid', gap: 8 }}>\n {frame(<TextTicker {...args} tabIndex={0} />)}\n <span style={{ color: 'var(--a63-text-secondary)', fontSize: 12 }}>\n Hover or focus the title to reveal the full text\n </span>\n </div>\n ),\n}\n\n/* No overflow — the ticker simply renders the text (marquee never engages). */\nexport const FitsInContainer: Story = {\n args: { children: 'Short title' },\n render: args => frame(<TextTicker {...args} />),\n}\n\n/* autoPlay scrolls continuously once the content overflows, no hover needed.\n It pauses on hover and focus and shows a pause toggle (WCAG 2.2.2). */\nexport const AutoPlay: Story = {\n args: { autoPlay: true },\n render: args => frame(<TextTicker {...args} />),\n play: async ({ canvasElement }) => {\n await new Promise(resolve => setTimeout(resolve, 50))\n const toggle = canvasElement.querySelector<HTMLButtonElement>('button[aria-label=\"Pause\"]')\n // Under reduced motion (the visual run sets it) the ticker stands still and shows no toggle.\n if (window.matchMedia('(prefers-reduced-motion: reduce)').matches) {\n if (toggle) throw new Error('Expected no pause toggle under reduced motion')\n return\n }\n if (!toggle) throw new Error('Expected the built-in pause toggle')\n toggle.click()\n await new Promise(resolve => setTimeout(resolve, 50))\n if (toggle.getAttribute('aria-pressed') !== 'true') {\n throw new Error('Expected the pause toggle to be pressed')\n }\n const track = canvasElement.querySelector('.a63-TextTicker-marqueeTrack')\n if (!track || getComputedStyle(track).animationPlayState !== 'paused') {\n throw new Error('Expected the marquee track to be paused')\n }\n toggle.click()\n await new Promise(resolve => setTimeout(resolve, 50))\n if (getComputedStyle(track).animationPlayState !== 'running') {\n throw new Error('Expected the marquee track to run again after resuming')\n }\n },\n}\n\n/* The default truncate variant is a plain truncating line. */\nexport const StaticTruncate: Story = {\n args: { variant: 'truncate' },\n render: args => frame(<TextTicker {...args} />),\n}\n\n/* The ticker across all 4 DS themes × light/dark. autoPlay so the marquee is\n visible without hover in the static grid. */\nexport const Themes: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12 }}>\n {themes.map(theme =>\n (['light', 'dark'] as const).map(mode => (\n <UIProvider key={`${theme}-${mode}`} mode={mode} theme={theme}>\n <div\n style={{\n alignItems: 'center',\n background: 'var(--a63-surface-panel)',\n borderRadius: 'var(--radius-lg)',\n color: 'var(--a63-text-primary)',\n display: 'flex',\n gap: 12,\n padding: '0.75rem',\n }}\n >\n <span style={{ fontSize: 12, color: 'var(--a63-text-secondary)', width: 96 }}>\n {theme} / {mode}\n </span>\n {frame(\n <TextTicker variant=\"marquee\" autoPlay marqueeSpeed={24}>\n Now playing — A very long track title that will overflow its container\n </TextTicker>\n )}\n </div>\n </UIProvider>\n ))\n )}\n </div>\n ),\n}\n\n/* Compare the same overflow behavior at the supported endpoint densities. */\nexport const Endpoints: Story = {\n render: () => (\n <div style={{ display: 'grid', gap: 12 }}>\n <UIProvider designLanguage=\"web\" input=\"pointer\">\n {frame(\n <TextTicker variant=\"marquee\" autoPlay>\n Web — a long overflowing title for review\n </TextTicker>\n )}\n </UIProvider>\n <UIProvider designLanguage=\"ios\" input=\"touch\">\n {frame(\n <TextTicker variant=\"marquee\" autoPlay>\n iOS touch — a long overflowing title for review\n </TextTicker>\n )}\n </UIProvider>\n <UIProvider density=\"compact\">\n {frame(\n <TextTicker variant=\"marquee\" autoPlay>\n Compact extension — a long overflowing title\n </TextTicker>\n )}\n </UIProvider>\n </div>\n ),\n}\n\nexport const ContractMetadata: Story = {\n render: () => (\n <pre style={{ fontSize: 12, margin: 0, whiteSpace: 'pre-wrap' }}>\n {JSON.stringify(textTickerContract, null, 2)}\n </pre>\n ),\n}\n"
13838
13939
  },
13839
13940
  "summary": "Text Ticker truncates text and can reveal overflow with a measured marquee.",
13840
13941
  "usage": "Keep the full text accessible elsewhere and avoid autoplay for essential reading.",
@@ -13992,14 +14093,14 @@
13992
14093
  {
13993
14094
  "area": "components",
13994
14095
  "label": "Button",
13995
- "markdown": "# Button\n\nButton is the reference action primitive for the current system: typed variants from `@atom63/ui-foundation`, Base UI-compatible rendering in `@atom63/ui-react`, and material values from the `control` and `action` contracts.\n\n```tsx\nimport { Button } from '@atom63/ui-react'\n\n<Button variant=\"primary\">Save changes</Button>\n<Button>Cancel</Button>\n<Button variant=\"outline\">Duplicate</Button>\n<Button variant=\"ghost\">Dismiss</Button>\n<Button variant=\"destructive\">Delete</Button>\n```\n\n## When to use\n\nUse it for an in-place action such as submitting, saving, confirming or changing state; use a link when the outcome is navigation. Choose emphasis from the action hierarchy rather than making every action primary, and give icon-only buttons an accessible name. Draw secondary actions in toolbars, rows and card headers as variant=\"ghost\" with tone=\"muted\". shape=\"round\" makes icon buttons circles (a play button) and labelled buttons pills.\n\n## Why it exists\n\nRaw buttons are easy until they need to survive themes, density, loading, icon-only sizing, pressed states, and form safety. The shared Button exists so every product surface gets those decisions once.\n\n## Contract shape\n\nThe root always renders `data-slot=\"button\"` and carries `data-variant` and `data-size`. Trigger-specific composition can mirror a different slot through `data-trigger-slot`, while the anatomy stays a button.\n\n| Layer | Examples |\n|-------|----------|\n| Public API | `variant`, `size`, `tone`, `shape`, `loading`, `disabled`, `render`, `type`. |\n| Stable metadata | `data-slot=\"button\"`, `data-size`, `data-variant`, `data-tone`, `data-loading`, `data-disabled`. |\n| Local recipe vars | `--button-background`, `--button-foreground`, `--button-shadow`, `--button-radius`. |\n| System vars | `--a63-action-*`, `--a63-control-*`, `--a63-density-scale`, `--a63-focus-ring`. |\n\n## Variants, sizes and states\n\n| Axis | Value | Guidance |\n| --- | --- | --- |\n| Variant | `primary` | The one primary action per view, when the product's main action is in its brand colour. |\n| Variant | `default` | Neutral solid: high emphasis without the brand colour (a white play button on dark, a black Pay button). |\n| Variant | `secondary` | Muted neutral action for supporting tasks. |\n| Variant | `raised` | Light fill, soft shadow, no border; with shape=\"round\", the floating button over a map or a light photo. |\n| Variant | `outline` | Lower-emphasis alternative (Duplicate). |\n| Variant | `dashed` | Add or filter affordance drawn as a dashed pill (+ Status). |\n| Variant | `ghost` | Lowest emphasis; toolbars and dismissals, with tone=\"muted\" for quiet secondary actions. |\n| Variant | `link` | Inline action styled as text; navigation should use a real link. |\n| Variant | `destructive` | Only when the outcome destroys data. |\n| Variant | `destructive-outline` | Quieter destructive action, beside a safe default. |\n| Variant | `overlay` | Forced contrast over media and imagery; the floating button over dark media. |\n| Variant | `glass` | Compatibility alias of overlay; new work uses overlay. |\n| Size | `xs` | Dense UI. |\n| Size | `sm` | Compact rows and toolbars. |\n| Size | `md` | Default. |\n| Size | `lg` | Prominent calls to action. |\n| Size | `xl` | Hero and marketing surfaces. |\n| State | `rest` | Resting appearance. |\n| State | `hover` | Pointer over an enabled button. |\n| State | `pressed` | While pressed, or held with data-pressed. |\n| State | `focusVisible` | Keyboard focus only; drawn as an outline. |\n| State | `disabled` | A neutral grey fill and muted label; ghost, link, overlay and glass fade only the label. |\n| State | `loading` | Label keeps its width; the spinner overlays it. |\n\n## Sizes and icons\n\nEach size step sets height, inline padding, gap and icon size together. Height, padding and gap are built on `--a63-space-unit`, so density scales them once (compact `md` is 28px, rounded to whole pixels); icon sizes stay the same. Icon-only buttons use the `icon-*` steps so the control stays square, and draw their glyph from `--a63-control-icon-only-size-*`, about 0.56 of the box (24/14, 28/16, 32/18). An icon beside a label stays on the smaller `--a63-control-icon-size-*` ramp. Button owns the icon gap — never add `mr-`/`ml-` margins to an icon inside one.\n\nHide decorative icons from assistive technology when the visible label already names the action.\n\n```tsx\n<Button size=\"xs\">Extra small</Button>\n<Button size=\"sm\">Small</Button>\n<Button size=\"md\">Medium</Button>\n<Button size=\"lg\">Large</Button>\n\n<Button variant=\"primary\">\n Continue\n <ArrowRight />\n</Button>\n<Button aria-label=\"Delete\" size=\"icon\" variant=\"destructive\">\n <Trash2 />\n</Button>\n```\n\n## Emphasis without the accent\n\n`default` is the neutral solid: high emphasis without the brand colour, such as a white play button on dark or a black Pay button. `primary` is the main action when the product's main action is in its brand colour. Use the accent for one or two cues per view; the main action may be neutral.\n\n## Quiet secondary actions\n\nSecondary actions in toolbars, list rows and card headers are ghost buttons with `tone=\"muted\"`. The glyph and label rest in the secondary text colour and go to full contrast on hover, keyboard focus and press, so the row reads calm and the action still answers the pointer. Only `ghost` reads the tone; keep the main action at full contrast.\n\n```tsx\n<Button aria-label=\"Notifications\" size=\"icon-sm\" tone=\"muted\" variant=\"ghost\">\n <Bell />\n</Button>\n<Button aria-label=\"More\" size=\"icon-sm\" tone=\"muted\" variant=\"ghost\">\n <Ellipsis />\n</Button>\n<Button size=\"sm\" tone=\"muted\" variant=\"ghost\">\n <Share />\n Share\n</Button>\n```\n\n## Floating buttons\n\n`raised` is a light button lifted off its ground: the panel fill, primary text and a soft shadow, with no border. With `shape=\"round\"` at an icon size it is the floating button maps and light heroes use for back, locate and layers. Over a dark photo or video use `overlay` instead.\n\n```tsx\n<Button aria-label=\"Back\" shape=\"round\" size=\"icon-lg\" variant=\"raised\">\n <ChevronLeft />\n</Button>\n<Button aria-label=\"Show my location\" shape=\"round\" size=\"icon-lg\" variant=\"raised\">\n <LocateFixed />\n</Button>\n<Button shape=\"round\" variant=\"raised\">Search this area</Button>\n```\n\n## Decisions worth knowing\n\n### Button sets `type=\"button\"`\n\nI make the safe form behavior explicit. A shared Button should not accidentally submit a form because it was mounted inside one.\n\n### Loading preserves layout\n\nLoading hides the label visually and overlays a spinner rather than swapping content. That keeps button width stable and avoids a small but very noticeable layout jump.\n\n```tsx\n<Button loading variant=\"primary\">Save changes</Button>\n<Button loading>Save changes</Button>\n<Button disabled variant=\"primary\">Save changes</Button>\n```\n\nCompare the loading and resting buttons above: the label reserves its width, so the row never reflows when a request starts.\n\n### Themes change material, not intent\n\nAqua adds gloss and tint through `--a63-control-gloss`, `--a63-control-highlight`, and `--a63-control-shadow`. Terminal can flatten those values. The Button recipe does not branch on `theme`; it consumes the same variables in every theme.\n\n## Usage\n\n```tsx\nimport { Button } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Button`\n\n**Types:** `ButtonProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/button.json` (`buttonContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `shapes` | `default`, `round` | `default` |\n| `tones` | `neutral`, `muted` | `neutral` |\n| `variants` | `default`, `primary`, `secondary`, `raised`, `destructive`, `destructive-outline`, `outline`, `dashed`, `ghost`, `link`, `overlay`, `glass` | `default` |\n| `sizes` | `xs`, `sm`, `md`, `lg`, `xl`, `tile`, `icon-xs`, `icon-sm`, `icon`, `icon-lg`, `icon-xl` | `md` |\n\n**Slots:** `root`, `label`, `icon`, `spinner`, `indicator`\n\n**States:** `rest`, `hover`, `pressed`, `focusVisible`, `disabled`, `loading`\n\n**Token slots:** `button.background`, `button.foreground`, `button.border.color`, `button.border.width`, `button.radius`, `button.shadow`, `button.focusRing`, `button.height`, `button.paddingInline`, `button.gap`, `button.iconSize`, `button.motion.press`\n\n**Visual archetype:** Action controls — Momentary controls that perform an action now.\n\n### Web and iOS\n\nTrigger a user-initiated action with explicit hierarchy and feedback. Rendered by `AtomButton` in SwiftUI, with `recipe` parity.\n\n**Required states:** `rest`, `pressed`, `disabled`, `loading`\n\n**Shared outcomes:**\n\n- Action fires once\n- Loading blocks repeat activation\n- Disabled prevents activation\n\n**Accessibility outcomes:**\n\n- Exposes label\n- Announces loading\n- Disabled while loading\n\n**Platform adaptations:**\n\n- React: Uses HTML button semantics with pointer and focus-visible feedback.\n- SwiftUI: Uses SwiftUI Button with native touch and keyboard activation.\n- SwiftUI: The round shape is a capsule: a circle at the icon size, a pill with a label.\n- SwiftUI: The raised emphasis uses the panel fill and a soft shadow with no border; muted tone only quiets ghost labels.\n\n## Related components\n\n- [Button Group](/components/component-button-group)\n- [Toggle](/components/component-toggle)\n- [Copy Button](/components/component-copy-button)",
14096
+ "markdown": "# Button\n\nButton is the reference action primitive for the current system: typed variants from `@atom63/ui-foundation`, Base UI-compatible rendering in `@atom63/ui-react`, and material values from the `control` and `action` contracts.\n\n```tsx\nimport { Button } from '@atom63/ui-react'\n\n<Button variant=\"primary\">Save changes</Button>\n<Button>Cancel</Button>\n<Button variant=\"outline\">Duplicate</Button>\n<Button variant=\"ghost\">Dismiss</Button>\n<Button variant=\"destructive\">Delete</Button>\n```\n\n## When to use\n\nUse it for an in-place action such as submitting, saving, confirming or changing state; use a link when the outcome is navigation. Choose emphasis from the action hierarchy rather than making every action primary, and give icon-only buttons an accessible name. Draw secondary actions in toolbars, rows and card headers as variant=\"ghost\" with tone=\"muted\". shape=\"round\" makes icon buttons circles (a play button) and labelled buttons pills.\n\n## Why it exists\n\nRaw buttons are easy until they need to survive themes, density, loading, icon-only sizing, pressed states, and form safety. The shared Button exists so every product surface gets those decisions once.\n\n## Contract shape\n\nThe root always renders `data-slot=\"button\"` and carries `data-variant` and `data-size`. Trigger-specific composition can mirror a different slot through `data-trigger-slot`, while the anatomy stays a button.\n\n| Layer | Examples |\n|-------|----------|\n| Public API | `variant`, `size`, `tone`, `shape`, `loading`, `disabled`, `render`, `type`. |\n| Stable metadata | `data-slot=\"button\"`, `data-size`, `data-variant`, `data-tone`, `data-loading`, `data-disabled`. |\n| Local recipe vars | `--button-background`, `--button-foreground`, `--button-shadow`, `--button-radius`. |\n| System vars | `--a63-action-*`, `--a63-control-*`, `--a63-density-scale`, `--a63-focus-ring`. |\n\n## Variants, sizes and states\n\n| Axis | Value | Guidance |\n| --- | --- | --- |\n| Variant | `primary` | The one primary action per view, when the product's main action is in its brand colour. |\n| Variant | `default` | Neutral solid: high emphasis without the brand colour (a white play button on dark, a black Pay button). |\n| Variant | `secondary` | Muted neutral action for supporting tasks. |\n| Variant | `raised` | Light fill, soft shadow, no border; with shape=\"round\", the floating button over a map or a light photo. |\n| Variant | `outline` | Lower-emphasis alternative (Duplicate). |\n| Variant | `dashed` | Add or filter affordance drawn as a dashed pill (+ Status). |\n| Variant | `ghost` | Lowest emphasis; toolbars and dismissals, with tone=\"muted\" for quiet secondary actions. |\n| Variant | `link` | Inline action styled as text; navigation should use a real link. |\n| Variant | `destructive` | Only when the outcome destroys data. |\n| Variant | `destructive-outline` | Quieter destructive action, beside a safe default. |\n| Variant | `overlay` | Forced contrast over media and imagery; the floating button over dark media. |\n| Variant | `glass` | Compatibility alias of overlay; new work uses overlay. |\n| Size | `xs` | Dense UI. |\n| Size | `sm` | Compact rows and toolbars. |\n| Size | `md` | Default. |\n| Size | `lg` | Prominent calls to action. |\n| Size | `xl` | Hero and marketing surfaces. |\n| State | `rest` | Resting appearance. |\n| State | `hover` | Pointer over an enabled button. |\n| State | `pressed` | While pressed, or held with data-pressed. |\n| State | `focus-visible` | Keyboard focus only; drawn as an outline. |\n| State | `disabled` | A neutral grey fill and muted label; ghost, link, overlay and glass fade only the label. |\n| State | `loading` | Label keeps its width; the spinner overlays it. |\n\n## Sizes and icons\n\nEach size step sets height, inline padding, gap and icon size together. Height, padding and gap are built on `--a63-space-unit`, so density scales them once (compact `md` is 28px, rounded to whole pixels); icon sizes stay the same. Icon-only buttons use the `icon-*` steps so the control stays square, and draw their glyph from `--a63-control-icon-only-size-*`, about 0.56 of the box (24/14, 28/16, 32/18). An icon beside a label stays on the smaller `--a63-control-icon-size-*` ramp. Button owns the icon gap — never add `mr-`/`ml-` margins to an icon inside one.\n\nHide decorative icons from assistive technology when the visible label already names the action.\n\n```tsx\n<Button size=\"xs\">Extra small</Button>\n<Button size=\"sm\">Small</Button>\n<Button size=\"md\">Medium</Button>\n<Button size=\"lg\">Large</Button>\n\n<Button variant=\"primary\">\n Continue\n <ArrowRight />\n</Button>\n<Button aria-label=\"Delete\" size=\"icon\" variant=\"destructive\">\n <Trash2 />\n</Button>\n```\n\n## Emphasis without the accent\n\n`default` is the neutral solid: high emphasis without the brand colour, such as a white play button on dark or a black Pay button. `primary` is the main action when the product's main action is in its brand colour. Use the accent for one or two cues per view; the main action may be neutral.\n\n## Quiet secondary actions\n\nSecondary actions in toolbars, list rows and card headers are ghost buttons with `tone=\"muted\"`. The glyph and label rest in the secondary text colour and go to full contrast on hover, keyboard focus and press, so the row reads calm and the action still answers the pointer. Only `ghost` reads the tone; keep the main action at full contrast.\n\n```tsx\n<Button aria-label=\"Notifications\" size=\"icon-sm\" tone=\"muted\" variant=\"ghost\">\n <Bell />\n</Button>\n<Button aria-label=\"More\" size=\"icon-sm\" tone=\"muted\" variant=\"ghost\">\n <Ellipsis />\n</Button>\n<Button size=\"sm\" tone=\"muted\" variant=\"ghost\">\n <Share />\n Share\n</Button>\n```\n\n## Floating buttons\n\n`raised` is a light button lifted off its ground: the panel fill, primary text and a soft shadow, with no border. With `shape=\"round\"` at an icon size it is the floating button maps and light heroes use for back, locate and layers. Over a dark photo or video use `overlay` instead.\n\n```tsx\n<Button aria-label=\"Back\" shape=\"round\" size=\"icon-lg\" variant=\"raised\">\n <ChevronLeft />\n</Button>\n<Button aria-label=\"Show my location\" shape=\"round\" size=\"icon-lg\" variant=\"raised\">\n <LocateFixed />\n</Button>\n<Button shape=\"round\" variant=\"raised\">Search this area</Button>\n```\n\n## Decisions worth knowing\n\n### Button sets `type=\"button\"`\n\nI make the safe form behavior explicit. A shared Button should not accidentally submit a form because it was mounted inside one.\n\n### Loading preserves layout\n\nLoading hides the label visually and overlays a spinner rather than swapping content. That keeps button width stable and avoids a small but very noticeable layout jump.\n\n```tsx\n<Button loading variant=\"primary\">Save changes</Button>\n<Button loading>Save changes</Button>\n<Button disabled variant=\"primary\">Save changes</Button>\n```\n\nCompare the loading and resting buttons above: the label reserves its width, so the row never reflows when a request starts.\n\n### Themes change material, not intent\n\nAqua adds gloss and tint through `--a63-control-gloss`, `--a63-control-highlight`, and `--a63-control-shadow`. Terminal can flatten those values. The Button recipe does not branch on `theme`; it consumes the same variables in every theme.\n\n## Usage\n\n```tsx\nimport { Button } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Button`\n\n**Types:** `ButtonProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/button.json` (`buttonContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `shapes` | `default`, `round` | `default` |\n| `tones` | `neutral`, `muted` | `neutral` |\n| `variants` | `default`, `primary`, `secondary`, `raised`, `destructive`, `destructive-outline`, `outline`, `dashed`, `ghost`, `link`, `overlay`, `glass` | `default` |\n| `sizes` | `xs`, `sm`, `md`, `lg`, `xl`, `tile`, `icon-xs`, `icon-sm`, `icon`, `icon-lg`, `icon-xl` | `md` |\n\n**Deprecated aliases:** `focusVisible` → `focus-visible` (states)\n\n**Slots:** `button`, `button-label`, `button-spinner`, `button-indicator`\n\n**States:** `rest`, `hover`, `pressed`, `focus-visible`, `disabled`, `loading`\n\n**Token slots:** `button.background`, `button.foreground`, `button.border.color`, `button.border.width`, `button.radius`, `button.shadow`, `button.focusRing`, `button.height`, `button.paddingInline`, `button.gap`, `button.iconSize`, `button.motion.press`\n\n**Visual archetype:** Action controls — Momentary controls that perform an action now.\n\n### Web and iOS\n\nTrigger a user-initiated action with explicit hierarchy and feedback. Rendered by `AtomButton` in SwiftUI, with `recipe` parity.\n\n**Required states:** `rest`, `pressed`, `disabled`, `loading`\n\n**Shared outcomes:**\n\n- Action fires once\n- Loading blocks repeat activation\n- Disabled prevents activation\n\n**Accessibility outcomes:**\n\n- Exposes label\n- Announces loading\n- Disabled while loading\n\n**Platform adaptations:**\n\n- React: Uses HTML button semantics with pointer and focus-visible feedback.\n- SwiftUI: Uses SwiftUI Button with native touch and keyboard activation.\n- SwiftUI: The round shape is a capsule: a circle at the icon size, a pill with a label.\n- SwiftUI: The raised emphasis uses the panel fill and a soft shadow with no border; muted tone only quiets ghost labels.\n\n## Related components\n\n- [Button Group](/components/component-button-group)\n- [Toggle](/components/component-toggle)\n- [Copy Button](/components/component-copy-button)",
13996
14097
  "route": "/components/component-button",
13997
14098
  "slug": "component-button"
13998
14099
  },
13999
14100
  {
14000
14101
  "area": "components",
14001
14102
  "label": "Button group",
14002
- "markdown": "# Button Group\n\nButton Group turns adjacent controls into one welded segment. It is not a row with smaller gaps; it is a composition contract for shared edges, seams, radius, and selected state.\n\n```tsx\nimport { Button, ButtonGroup, ButtonGroupSeparator, ButtonGroupText } from '@atom63/ui-react'\n\n<ButtonGroup aria-label=\"Time range\">\n <Button variant=\"outline\">Day</Button>\n <Button variant=\"outline\">Week</Button>\n <Button variant=\"outline\">Month</Button>\n</ButtonGroup>\n\n<ButtonGroup aria-label=\"Text alignment\" size=\"icon\">\n <Button aria-label=\"Align left\" variant=\"outline\"><AlignLeft /></Button>\n <Button aria-label=\"Align center\" variant=\"outline\"><AlignCenter /></Button>\n <Button aria-label=\"Align right\" variant=\"outline\"><AlignRight /></Button>\n</ButtonGroup>\n\n<ButtonGroup aria-label=\"Branch actions\">\n <ButtonGroupText>Branch</ButtonGroupText>\n <ButtonGroupSeparator />\n <Button variant=\"outline\">main <ChevronDown /></Button>\n</ButtonGroup>\n```\n\n## When to use\n\nUse Button Group for related adjacent actions that should read as one visual run. Use Toggle Group or Segmented Control when the group represents persistent selection instead of independent commands.\n\nThe group supplies `role=\"group\"` but cannot infer its name. Add `aria-label` or `aria-labelledby` when the surrounding context does not already identify the grouped controls.\n\n## How it works\n\nThe group owns adjacency. Child Buttons keep their semantic API, but inside the group they flatten standalone elevation and read the `segment` contract.\n\n| Concern | Owner |\n|---------|-------|\n| Orientation, member sizing, edge radius, seams | Button Group recipe. |\n| Button label, loading, variant, disabled state | Button. |\n| Welded material | `--a63-segment-*`. |\n| Control height, font, padding | `--a63-control-*` plus density. |\n\n## Key tokens\n\n| Token | Purpose |\n|-------|---------|\n| `--a63-segment-track-border` | Shared outer and seam border. |\n| `--a63-segment-background` | Resting member fill. |\n| `--a63-segment-gloss` | Optional member material sheen. |\n| `--a63-segment-selected-background` | Pressed or selected member fill. |\n| `--a63-segment-selected-foreground` | Text/icon color on selected member. |\n| `--a63-segment-selected-shadow` | Pressed-in or raised selected treatment. |\n| `--a63-segment-primary-background` | Brand selected state for primary emphasis. |\n\n## Design decision\n\nGrouped buttons deliberately suppress the standalone Button shadow and highlight. If every child kept its own button chrome, the group would read as several objects colliding. The segment contract makes the group one object with internal choices.\n\n```tsx\n{/* One object: shared edges, no member elevation. */}\n<ButtonGroup aria-label=\"Time range\">\n <Button variant=\"outline\">Day</Button>\n <Button variant=\"outline\">Week</Button>\n</ButtonGroup>\n\n{/* Several objects: each keeps its own chrome. */}\n<div className=\"flex gap-2\">\n <Button variant=\"outline\">Day</Button>\n <Button variant=\"outline\">Week</Button>\n</div>\n```\n\nThat is why Button Group shares material vocabulary with Segmented Control and Toggle Group instead of inventing `--button-group-theme-*` variables.\n\n## Usage\n\n```tsx\nimport { ButtonGroup, ButtonGroupText, ButtonGroupSeparator } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `ButtonGroup`, `ButtonGroupProvider`, `ButtonGroupSeparator`, `ButtonGroupText`, `useButtonGroupContext`\n\n**Types:** `ButtonGroupProps`, `ButtonGroupSeparatorProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/button-group.json` (`buttonGroupContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `orientations` | `horizontal`, `vertical` | `horizontal` |\n| `sizes` | `xs`, `sm`, `default`, `lg`, `xl`, `icon-xs`, `icon-sm`, `icon`, `icon-lg`, `icon-xl` | `default` |\n\n**Slots:** `button-group`, `button-group-text`, `button-group-separator`\n\n**States:** `rest`, `focus-within`\n\n**Visual archetype:** Action controls — Momentary controls that perform an action now.; Segmented selection — One-of-many peer selections presented as a shared track or grouped row.\n\n## Related components\n\n- [Button](/components/component-button)\n- [Toggle Group](/components/component-toggle-group)\n- [Segmented Control](/components/component-segmented-control)",
14103
+ "markdown": "# Button Group\n\nButton Group turns adjacent controls into one welded segment. It is not a row with smaller gaps; it is a composition contract for shared edges, seams, radius, and selected state.\n\n```tsx\nimport { Button, ButtonGroup, ButtonGroupSeparator, ButtonGroupText } from '@atom63/ui-react'\n\n<ButtonGroup aria-label=\"Time range\">\n <Button variant=\"outline\">Day</Button>\n <Button variant=\"outline\">Week</Button>\n <Button variant=\"outline\">Month</Button>\n</ButtonGroup>\n\n<ButtonGroup aria-label=\"Text alignment\" size=\"icon\">\n <Button aria-label=\"Align left\" variant=\"outline\"><AlignLeft /></Button>\n <Button aria-label=\"Align center\" variant=\"outline\"><AlignCenter /></Button>\n <Button aria-label=\"Align right\" variant=\"outline\"><AlignRight /></Button>\n</ButtonGroup>\n\n<ButtonGroup aria-label=\"Branch actions\">\n <ButtonGroupText>Branch</ButtonGroupText>\n <ButtonGroupSeparator />\n <Button variant=\"outline\">main <ChevronDown /></Button>\n</ButtonGroup>\n```\n\n## When to use\n\nUse Button Group for related adjacent actions that should read as one visual run. Use Toggle Group or Segmented Control when the group represents persistent selection instead of independent commands.\n\nThe group supplies `role=\"group\"` but cannot infer its name. Add `aria-label` or `aria-labelledby` when the surrounding context does not already identify the grouped controls.\n\n## How it works\n\nThe group owns adjacency. Child Buttons keep their semantic API, but inside the group they flatten standalone elevation and read the `segment` contract.\n\n| Concern | Owner |\n|---------|-------|\n| Orientation, member sizing, edge radius, seams | Button Group recipe. |\n| Button label, loading, variant, disabled state | Button. |\n| Welded material | `--a63-segment-*`. |\n| Control height, font, padding | `--a63-control-*` plus density. |\n\n## Key tokens\n\n| Token | Purpose |\n|-------|---------|\n| `--a63-segment-track-border` | Shared outer and seam border. |\n| `--a63-segment-background` | Resting member fill. |\n| `--a63-segment-gloss` | Optional member material sheen. |\n| `--a63-segment-selected-background` | Pressed or selected member fill. |\n| `--a63-segment-selected-foreground` | Text/icon color on selected member. |\n| `--a63-segment-selected-shadow` | Pressed-in or raised selected treatment. |\n| `--a63-segment-primary-background` | Brand selected state for primary emphasis. |\n\n## Design decision\n\nGrouped buttons deliberately suppress the standalone Button shadow and highlight. If every child kept its own button chrome, the group would read as several objects colliding. The segment contract makes the group one object with internal choices.\n\n```tsx\n{/* One object: shared edges, no member elevation. */}\n<ButtonGroup aria-label=\"Time range\">\n <Button variant=\"outline\">Day</Button>\n <Button variant=\"outline\">Week</Button>\n</ButtonGroup>\n\n{/* Several objects: each keeps its own chrome. */}\n<div className=\"flex gap-2\">\n <Button variant=\"outline\">Day</Button>\n <Button variant=\"outline\">Week</Button>\n</div>\n```\n\nThat is why Button Group shares material vocabulary with Segmented Control and Toggle Group instead of inventing `--button-group-theme-*` variables.\n\n## Usage\n\n```tsx\nimport { ButtonGroup, ButtonGroupText, ButtonGroupSeparator } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `ButtonGroup`, `ButtonGroupProvider`, `ButtonGroupSeparator`, `ButtonGroupText`, `useButtonGroupContext`\n\n**Types:** `ButtonGroupProps`, `ButtonGroupSeparatorProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/button-group.json` (`buttonGroupContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `orientations` | `horizontal`, `vertical` | `horizontal` |\n| `sizes` | `xs`, `sm`, `md`, `lg`, `xl`, `icon-xs`, `icon-sm`, `icon`, `icon-lg`, `icon-xl` | `md` |\n\n**Deprecated aliases:** `default` → `md` (sizes)\n\n**Slots:** `button-group`, `button-group-text`, `button-group-separator`\n\n**States:** `rest`, `focus-within`\n\n**Visual archetype:** Action controls — Momentary controls that perform an action now.; Segmented selection — One-of-many peer selections presented as a shared track or grouped row.\n\n## Related components\n\n- [Button](/components/component-button)\n- [Toggle Group](/components/component-toggle-group)\n- [Segmented Control](/components/component-segmented-control)",
14003
14104
  "route": "/components/component-button-group",
14004
14105
  "slug": "component-button-group"
14005
14106
  },
@@ -14041,7 +14142,7 @@
14041
14142
  {
14042
14143
  "area": "components",
14043
14144
  "label": "Tabs",
14044
- "markdown": "# Tabs\n\nTabs organize related panels without leaving the current task. The component owns orientation, keyboard behavior, indicator placement, and panel relationships; the theme owns the material values behind those states.\n\n## When to use\n\nUse Tabs for peer panels inside one task or surface. Use navigation links when each destination has its own URL, should appear in browser history, or needs to remain directly addressable.\n\nGive each `TabsList` an accessible name with `aria-label` or `aria-labelledby`; otherwise assistive technology announces an unnamed tab list. Base UI supplies keyboard movement and tab-panel relationships, but it cannot infer the group's purpose.\n\n## Variants\n\n| Variant | Intent |\n|---------|--------|\n| `default` | Contained switcher with a moving active plate. |\n| `underline` | Navigation-like tabs where active state is an edge marker. |\n| `attached` | Tabs and panel form one connected surface. |\n\n```tsx\nimport { Tabs, TabsList, TabsPanel, TabsTab } from '@atom63/ui-react'\n\n<Tabs defaultValue=\"tokens\">\n <TabsList aria-label=\"Implementation layer\" variant=\"default\">\n <TabsTab value=\"tokens\">Tokens</TabsTab>\n <TabsTab value=\"recipe\">Recipe</TabsTab>\n <TabsTab value=\"usage\">Usage</TabsTab>\n </TabsList>\n <TabsPanel value=\"tokens\">Semantic roles resolve here.</TabsPanel>\n <TabsPanel value=\"recipe\">The component recipe consumes them.</TabsPanel>\n <TabsPanel value=\"usage\">Product code sees only the API.</TabsPanel>\n</Tabs>\n```\n\n## Contract shape\n\nTabs combine several archetypes instead of inventing a theme namespace.\n\n| Part | Contract |\n|------|----------|\n| Default tab track | `--a63-surface-muted` plus `--a63-track-shadow`. |\n| Active plate | `--a63-surface-overlay`, `--a63-action-primary`, and `--a63-control-shadow`. |\n| Attached panel | `--a63-surface-*` and the surface contract. |\n| Text and focus | `--a63-text-*`, `--a63-control-focus-ring-*`. |\n\n## Design decisions\n\n### Attached tabs are one object\n\nAttached tabs are not a tab row sitting above a card. The selected tab and the panel need to visually merge, while inactive tabs remain lower-emphasis. The recipe handles that connection through panel surface tokens and active overlap.\n\n### Underline is intentionally restrained\n\nUnderline tabs are for content navigation. A full plate would compete with the page; an edge marker gives enough orientation without turning the control into a toolbar.\n\n### Orientation is component behavior\n\nHorizontal and vertical tabs use the same semantic contract. A theme should not patch orientation with bespoke spacing fixes; the recipe's size and indicator variables should keep the active marker aligned.\n\n## Review cues\n\nWhen reviewing Tabs, check that the active state is obvious in light and dark mode, the panel connection does not double its border, disabled tabs stay readable, and the active indicator remains aligned across density and radius axes.\n\n## Usage\n\n```tsx\nimport { Tabs, TabsList, TabsTab, TabsPanel } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Tabs`, `TabsContent`, `TabsList`, `TabsPanel`, `TabsTab`, `TabsTrigger`\n\n**Types:** `TabsListProps`, `TabsPanelProps`, `TabsTabProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/tabs.json` (`tabsContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `variants` | `default`, `underline`, `attached` | `default` |\n| `sizes` | `xs`, `sm`, `default`, `lg` | `default` |\n| `orientations` | `horizontal`, `vertical` | — |\n\n**Slots:** `tabs`, `tabs-list`, `tabs-tab`, `tab-indicator`, `tabs-content`\n\n**States:** `rest`, `hover`, `selected`, `focus-visible`, `disabled`\n\n**Visual archetype:** Segmented selection — One-of-many peer selections presented as a shared track or grouped row.; Static content surfaces — In-flow containers and content surfaces that do not inherently manipulate state.\n\n**Accessibility pattern:** [Tabs](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/) (activation: manual)\n\n### Web and iOS\n\nSwitch between peer destinations or content views while keeping one selection active. Rendered by `Picker(.segmented) / AtomTabRow` in SwiftUI, with `platform-adaptive` parity.\n\n**SwiftUI renderer per variant:**\n\n- `default`: `Picker(.segmented)`\n- `underline`: `AtomTabRow`\n- `attached`: `AtomTabRow`\n\n**Required states:** `rest`, `selected`\n\n**Shared outcomes:**\n\n- One tab is selected at a time\n- Selection reveals the associated content\n- Selected tab remains visually distinguishable\n\n**Accessibility outcomes:**\n\n- Exposes tab labels\n- Exposes selected state\n- Associates selection with visible content\n\n**Platform adaptations:**\n\n- React: Uses tablist, tab, and tabpanel semantics with keyboard navigation and a visual indicator.\n- SwiftUI: The default variant is a segmented Picker above the content it selects, for a short second-level filter of two to four options.\n- SwiftUI: The underline variant is AtomTabRow, a row of text tabs over the content it selects: the selected tab reads text-primary over an accent bar, the others text-secondary. The row scrolls sideways when the tabs do not fit and keeps the selected tab in view. Each tab can show an SF Symbol over its label. The bar slides to the new tab, and jumps under Reduce Motion. Each tab is a named button with the selected trait inside a tab-bar container, and the row mirrors in right-to-left languages.\n- SwiftUI: The attached variant also renders as AtomTabRow: folder tabs are a pointer idiom with no iOS counterpart, and the underline row already sits flush on the content it selects.\n- SwiftUI: TabView stays the renderer for app-level sections such as a tab bar or sidebar.\n- SwiftUI: In a TabView, each tab's root is its ScrollView or List. From iOS 26 the glass tab bar floats over it: content scrolls under the bar at rest, and TabView insets the scroll content so the last row ends above the bar. Do not pad for the bar, draw content in a ZStack or overlay over the TabView, or apply ignoresSafeArea to the bottom edge; extra bottom chrome goes in safeAreaInset(edge: .bottom) on the tab's root.\n\n## Related components\n\n- [Segmented Control](/components/component-segmented-control)\n- [Collapsible](/components/component-collapsible)\n- [Navigation Menu](/components/component-navigation-menu)",
14145
+ "markdown": "# Tabs\n\nTabs organize related panels without leaving the current task. The component owns orientation, keyboard behavior, indicator placement, and panel relationships; the theme owns the material values behind those states.\n\n## When to use\n\nUse Tabs for peer panels inside one task or surface. Use navigation links when each destination has its own URL, should appear in browser history, or needs to remain directly addressable.\n\nGive each `TabsList` an accessible name with `aria-label` or `aria-labelledby`; otherwise assistive technology announces an unnamed tab list. Base UI supplies keyboard movement and tab-panel relationships, but it cannot infer the group's purpose.\n\n## Variants\n\n| Variant | Intent |\n|---------|--------|\n| `default` | Contained switcher with a moving active plate. |\n| `underline` | Navigation-like tabs where active state is an edge marker. |\n| `attached` | Tabs and panel form one connected surface. |\n\n```tsx\nimport { Tabs, TabsList, TabsPanel, TabsTab } from '@atom63/ui-react'\n\n<Tabs defaultValue=\"tokens\">\n <TabsList aria-label=\"Implementation layer\" variant=\"default\">\n <TabsTab value=\"tokens\">Tokens</TabsTab>\n <TabsTab value=\"recipe\">Recipe</TabsTab>\n <TabsTab value=\"usage\">Usage</TabsTab>\n </TabsList>\n <TabsPanel value=\"tokens\">Semantic roles resolve here.</TabsPanel>\n <TabsPanel value=\"recipe\">The component recipe consumes them.</TabsPanel>\n <TabsPanel value=\"usage\">Product code sees only the API.</TabsPanel>\n</Tabs>\n```\n\n## Contract shape\n\nTabs combine several archetypes instead of inventing a theme namespace.\n\n| Part | Contract |\n|------|----------|\n| Default tab track | `--a63-surface-muted` plus `--a63-track-shadow`. |\n| Active plate | `--a63-surface-overlay`, `--a63-action-primary`, and `--a63-control-shadow`. |\n| Attached panel | `--a63-surface-*` and the surface contract. |\n| Text and focus | `--a63-text-*`, `--a63-control-focus-ring-*`. |\n\n## Design decisions\n\n### Attached tabs are one object\n\nAttached tabs are not a tab row sitting above a card. The selected tab and the panel need to visually merge, while inactive tabs remain lower-emphasis. The recipe handles that connection through panel surface tokens and active overlap.\n\n### Underline is intentionally restrained\n\nUnderline tabs are for content navigation. A full plate would compete with the page; an edge marker gives enough orientation without turning the control into a toolbar.\n\n### Orientation is component behavior\n\nHorizontal and vertical tabs use the same semantic contract. A theme should not patch orientation with bespoke spacing fixes; the recipe's size and indicator variables should keep the active marker aligned.\n\n## Review cues\n\nWhen reviewing Tabs, check that the active state is obvious in light and dark mode, the panel connection does not double its border, disabled tabs stay readable, and the active indicator remains aligned across density and radius axes.\n\n## Usage\n\n```tsx\nimport { Tabs, TabsList, TabsTab, TabsPanel } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Tabs`, `TabsContent`, `TabsList`, `TabsPanel`, `TabsTab`, `TabsTrigger`\n\n**Types:** `TabsListProps`, `TabsPanelProps`, `TabsTabProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/tabs.json` (`tabsContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `variants` | `default`, `underline`, `attached` | `default` |\n| `sizes` | `xs`, `sm`, `md`, `lg` | `md` |\n| `orientations` | `horizontal`, `vertical` | — |\n\n**Deprecated aliases:** `default` → `md` (sizes)\n\n**Slots:** `tabs`, `tabs-list`, `tabs-tab`, `tab-indicator`, `tabs-content`\n\n**States:** `rest`, `hover`, `selected`, `focus-visible`, `disabled`\n\n**Visual archetype:** Segmented selection — One-of-many peer selections presented as a shared track or grouped row.; Static content surfaces — In-flow containers and content surfaces that do not inherently manipulate state.\n\n**Accessibility pattern:** [Tabs](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/) (activation: manual)\n\n### Web and iOS\n\nSwitch between peer destinations or content views while keeping one selection active. Rendered by `Picker(.segmented) / AtomTabRow` in SwiftUI, with `platform-adaptive` parity.\n\n**SwiftUI renderer per variant:**\n\n- `default`: `Picker(.segmented)`\n- `underline`: `AtomTabRow`\n- `attached`: `AtomTabRow`\n\n**Required states:** `rest`, `selected`\n\n**Shared outcomes:**\n\n- One tab is selected at a time\n- Selection reveals the associated content\n- Selected tab remains visually distinguishable\n\n**Accessibility outcomes:**\n\n- Exposes tab labels\n- Exposes selected state\n- Associates selection with visible content\n\n**Platform adaptations:**\n\n- React: Uses tablist, tab, and tabpanel semantics with keyboard navigation and a visual indicator.\n- SwiftUI: The default variant is a segmented Picker above the content it selects, for a short second-level filter of two to four options.\n- SwiftUI: The underline variant is AtomTabRow, a row of text tabs over the content it selects: the selected tab reads text-primary over an accent bar, the others text-secondary. The row scrolls sideways when the tabs do not fit and keeps the selected tab in view. Each tab can show an SF Symbol over its label. The bar slides to the new tab, and jumps under Reduce Motion. Each tab is a named button with the selected trait inside a tab-bar container, and the row mirrors in right-to-left languages.\n- SwiftUI: The attached variant also renders as AtomTabRow: folder tabs are a pointer idiom with no iOS counterpart, and the underline row already sits flush on the content it selects.\n- SwiftUI: TabView stays the renderer for app-level sections such as a tab bar or sidebar.\n- SwiftUI: In a TabView, each tab's root is its ScrollView or List. From iOS 26 the glass tab bar floats over it: content scrolls under the bar at rest, and TabView insets the scroll content so the last row ends above the bar. Do not pad for the bar, draw content in a ZStack or overlay over the TabView, or apply ignoresSafeArea to the bottom edge; extra bottom chrome goes in safeAreaInset(edge: .bottom) on the tab's root.\n\n## Related components\n\n- [Segmented Control](/components/component-segmented-control)\n- [Collapsible](/components/component-collapsible)\n- [Navigation Menu](/components/component-navigation-menu)",
14045
14146
  "route": "/components/component-tabs",
14046
14147
  "slug": "component-tabs"
14047
14148
  },
@@ -14174,7 +14275,7 @@
14174
14275
  {
14175
14276
  "area": "patterns",
14176
14277
  "label": "MDX blocks",
14177
- "markdown": "# MDX blocks\n\nEvery block `@atom63/mdx/blocks` exports, with what it is for, a working example and its props. The props tables are read from each block's TypeScript types. For setup and the providers, see [MDX content](/patterns/pattern-mdx).\n\nInside a provider (`MDXContentProvider`, `DocsMDXContentProvider` or `ArticleMDXContentProvider`), most blocks need no import: the provider's component map registers them. `KeyIdea`, `Compare`, `ImageCompare`, `LayerStack`, `DocExample`, `DocExampleCode` and `DemoConfigPanel` are not in the map; import them from `@atom63/mdx/blocks`. In React, import any block from there.\n\nLook a block up from the terminal with `atom63 api <Block>`, for example `atom63 api KeyIdea`.\n\n## Notices\n\n### Callout\n\nA notice beside the text: a tip, a caveat, an error to avoid or a success state. Pick `type` by what the reader should feel; one callout per point.\n\n```tsx\n<Callout type=\"warning\">Releases need approval before they publish.</Callout>\n```\n\nProps of `Callout`:\n\n- `children`: `ReactNode` (required)\n- `className`: `string`\n- `type`: `'info' | 'warning' | 'error' | 'success'` (default `'info'`)\n\nSlots, each taking `children`: `Callout.Actions`, `Callout.Body`, `Callout.Icon`, `Callout.Title`.\n\n### KeyIdea\n\nThe one takeaway of a section, set apart with a label and an optional title. Use it once or twice per page; a page of key ideas has none.\n\n```tsx\n<KeyIdea title=\"One token architecture\">\n Every renderer reads the same tokens, so a theme change reaches web, iOS and Figma at once.\n</KeyIdea>\n```\n\nProps of `KeyIdea`:\n\n- `children`: `ReactNode` (required)\n- `className`: `string`\n- `label`: `ReactNode` (default `'Key idea'`)\n- `title`: `ReactNode`\n\n## Comparison\n\n### Compare\n\nTwo or more options side by side, each with an eyebrow, a title and a tone. Use it to explain a difference in words or code; for pictures use `ImageCompare`.\n\n```tsx\n<Compare title=\"Patch CSS vs system CSS\">\n <Compare.Item eyebrow=\"Before\" title=\"Local patch\" tone=\"negative\">\n Values are invented for the screen at hand.\n </Compare.Item>\n <Compare.Item eyebrow=\"After\" title=\"System contract\" tone=\"positive\">\n Values come from tokens that change together.\n </Compare.Item>\n</Compare>\n```\n\nProps of `Compare`:\n\n- `children`: `ReactNode` (required)\n- `className`: `string`\n- `description`: `ReactNode`\n- `title`: `ReactNode`\n\nProps of `Compare.Item`:\n\n- `children`: `ReactNode` (required)\n- `title`: `ReactNode` (required)\n- `className`: `string`\n- `eyebrow`: `ReactNode`\n- `tone`: `'warning' | 'neutral' | 'negative' | 'positive'` (default `'neutral'`)\n\nSlots, each taking `children`: `Compare.Description`, `Compare.Title`.\n\n### ComparisonPair\n\nTwo live panels, before and after, that the reader toggles between. Use it for interaction or motion differences; `speedControl` adds a slow-motion switch.\n\n```tsx\n<ComparisonPair label=\"Spacing\">\n <ComparisonPair.Before label=\"Before\">Cramped 4px gaps</ComparisonPair.Before>\n <ComparisonPair.After label=\"After\">Comfortable 16px gaps</ComparisonPair.After>\n</ComparisonPair>\n```\n\nProps of `ComparisonPair`:\n\n- `children`: `ReactNode` (required)\n- `className`: `string`\n- `label`: `string`\n- `slowMotionLabel`: `string` (default `'Slow motion'`)\n- `speedControl`: `boolean` (default `false`)\n\nProps of `ComparisonPair.After`:\n\n- `children`: `ReactNode` (required)\n- `className`: `string`\n- `label`: `string`\n\nProps of `ComparisonPair.Before`:\n\n- `children`: `ReactNode` (required)\n- `className`: `string`\n- `label`: `string`\n\n### ImageCompare\n\nTwo images in one frame with a draggable divider. Use it when the visual difference is the point; give both images real `alt` text. The slider loads on demand.\n\n```mdx\n<ImageCompare\n title=\"Ad hoc layout vs system layout\"\n before={{ src: '/images/before.webp', alt: 'Form with uneven spacing', label: 'Before' }}\n after={{ src: '/images/after.webp', alt: 'Form on the spacing scale', label: 'After' }}\n caption=\"Drag the divider to compare.\"\n/>\n```\n\nProps of `ImageCompare`:\n\n- `after`: `ImageCompareImage` (required)\n- `before`: `ImageCompareImage` (required)\n- `aspectRatio`: `string` (default `'16/9'`)\n- `bordered`: `boolean` (default `true`)\n- `caption`: `string`\n- `changePositionOnHover`: `boolean` (default `false`)\n- `description`: `string`\n- `handle`: `ReactNode`\n- `idleResetMs`: `number` (default `2500`). Idle ms before restoring to center when `resetAfterIdle` is on.\n- `objectFit`: `'none' | 'contain' | 'cover' | 'fill' | 'scale-down'` (default `'cover'`)\n- `onPositionChange`: `(position: number) => void`\n- `position`: `number` (default `50`). Initial slider position (0-100).\n- `resetAfterIdle`: `boolean` (default `false`). Restore to center after the user stops interacting.\n- `resetDelay`: `number` (default `500`)\n- `resetOnLeave`: `boolean` (default `false`)\n- `title`: `ReactNode`\n- `transition`: `string` (default `'0.25s cubic-bezier(.17,.67,.83,.67)'`)\n- `vertical`: `boolean` (default `false`)\n\n## Media\n\n### FigureBlock\n\nAn image with a caption. Clicking it opens the page's `MediaLightbox` gallery, which the provider hosts; set `enableLightbox={false}` to turn that off. Put rich captions in `FigureBlock.Caption` and a source line in `FigureBlock.Aside`.\n\n```tsx\n<FigureBlock\n alt=\"The Atom63 design system social card\"\n aspectRatio=\"16/9\"\n caption=\"Figure 1. The social card for this site.\"\n src=\"/og.png\"\n/>\n```\n\nProps of `FigureBlock`:\n\n- `alt`: `string` (required)\n- `src`: `string` (required)\n- `aspectRatio`: `'1/1' | '4/3' | '3/4' | '16/9' | '9/16'`\n- `bordered`: `boolean` (default `true`)\n- `caption`: `string`\n- `children`: `ReactNode`\n- `className`: `string`\n- `enableLightbox`: `boolean` (default `true`). Click-to-zoom; multiple figures on a page share one connected gallery.\n- `lightboxGalleryId`: `string` (default `MDX_FIGURE_LIGHTBOX_GALLERY_ID`). Gallery id for connected lightbox (default: all FigureBlocks on the page).\n- `loading`: `'eager' | 'lazy'` (default `'lazy'`)\n- `spacing`: `'none' | 'sm' | 'default' | 'lg'` (default `'default'`)\n\nSlots, each taking `children`: `FigureBlock.Aside`, `FigureBlock.Caption`.\n\n### VideoBlock\n\nA video figure with native controls and an optional caption. A video with speech needs a caption track (`trackSrc`); mark a purely visual loop `captionPolicy=\"decorative\"` instead. With `autoPlay` and no `controls`, it draws its own pause button and stays still under reduced motion.\n\n```mdx\n<VideoBlock src=\"/media/talk.mp4\" title=\"Design tokens talk\" trackSrc=\"/media/talk.en.vtt\" />\n\n<VideoBlock\n autoPlay\n captionPolicy=\"decorative\"\n controls={false}\n loop\n muted\n src=\"/media/loop.mp4\"\n title=\"Theme switching loop\"\n/>\n```\n\nProps of `VideoBlock`:\n\n- `src`: `string` (required)\n- `title`: `string` (required)\n- `autoPlay`: `boolean` (default `false`). Start playing, muted, on load. Ignored when the reader prefers reduced motion. Without `controls`, a pause and play toggle sits over the video.\n- `caption`: `string`\n- `captionPolicy`: `'required' | 'decorative'`. Video has spoken or meaningful audio and must provide captions. Video is decorative or purely visual; no caption track is required.\n- `className`: `string`\n- `controls`: `boolean` (default `true`)\n- `fit`: `'contain' | 'cover'` (default `'contain'`)\n- `loop`: `boolean` (default `false`)\n- `muted`: `boolean` (default `false`)\n- `pauseLabel`: `string` (default `'Pause video'`). Name of the toggle while the video plays. Defaults to \"Pause video\".\n- `playLabel`: `string` (default `'Play video'`). Name of the toggle while the video is paused. Defaults to \"Play video\".\n- `showCaption`: `boolean` (default `false`)\n- `spacing`: `'none' | 'sm' | 'default' | 'lg'` (default `'default'`)\n- `trackLabel`: `string`. Name of the caption track in the player's caption menu. Defaults to the track language's own name, such as \"English\" or \"Deutsch\".\n- `trackLang`: `string` (default `'en'`). BCP 47 language of the caption track (`srclang`). Defaults to `en`.\n- `trackSrc`: `string`\n\n### MediaCaption\n\nThe caption line the media blocks use, on its own: for a custom figure, an embed or a chart.\n\n```tsx\n<MediaCaption>Figure 2. Token layers, from primitive to product.</MediaCaption>\n```\n\nProps of `MediaCaption`:\n\n- `children`: `ReactNode` (required)\n- `className`: `string`\n\n### MediaPlaceholder\n\nA labelled frame that stands in for an image, video or diagram that is not made yet. The label says what the real asset should show.\n\n```tsx\n<MediaPlaceholder kind=\"diagram\" label=\"Token flow from DTCG source to each renderer\" />\n```\n\nProps of `MediaPlaceholder`:\n\n- `aspectRatio`: `string` (default `'16 / 9'`). CSS aspect-ratio for the frame (e.g. `16 / 9`, `4 / 3`, `1 / 1`).\n- `className`: `string`\n- `kind`: `'video' | 'image' | 'diagram'` (default `'image'`). Picks the icon + kind tag. Defaults to `image`.\n- `label`: `string`. What the real asset should show — surfaced as the frame's caption.\n\n## Demos\n\n### DocExample\n\nA live example with Preview and Code tabs and a copy button. Every example on this page is one. Pass the source as `code` and render the same thing as children.\n\n```mdx\n<DocExample title=\"Primary button\" code={`<Button variant=\"primary\">Save</Button>`}>\n <Button variant=\"primary\">Save</Button>\n</DocExample>\n```\n\nProps of `DocExample`:\n\n- `children`: `ReactNode` (required)\n- `code`: `string` (required)\n- `align`: `'center' | 'left'` (default `'center'`)\n- `className`: `string`\n- `codeLabel`: `string` (default `'Code'`). Label for the code tab (default: \"Code\").\n- `copiedAnnouncement`: `string` (default `'Example code copied'`). Visually-hidden live-region text announced after copying (default: \"Example code copied\").\n- `copiedLabel`: `string` (default `'Copied to clipboard'`). aria-label for the copy control right after copying (default: \"Copied to clipboard\").\n- `copyCodeLabel`: `string` (default `'Copy example code'`). aria-label for the copy control when idle (default: \"Copy example code\").\n- `lang`: `string`\n- `previewLabel`: `string` (default `'Preview'`). Label for the preview tab (default: \"Preview\").\n- `title`: `string`\n- `wide`: `boolean` (default `false`)\n\nSlots, each taking `children`: `DocExample.Code`, `DocExample.Preview`, `DocExample.Title`.\n\n### DocExampleCode\n\nThe highlighted code panel of `DocExample`, on its own, for showing code that has no preview.\n\n```tsx\nimport { DocExampleCode } from '@atom63/mdx/blocks'\n\n<DocExampleCode code={`pnpm add @atom63/mdx`} lang=\"bash\" />\n```\n\nProps of `DocExampleCode`:\n\n- `code`: `string` (required)\n- `lang`: `string` (default `'tsx'`)\n\n### ExampleContainer\n\nA plain demo frame on a dot grid, with an optional title, description and spec line. Use it for a preview without a code tab.\n\n```mdx\n<ExampleContainer description=\"The main action of a view.\" title=\"Primary variant\">\n <Button variant=\"primary\">Save</Button>\n</ExampleContainer>\n```\n\nProps of `ExampleContainer`:\n\n- `children`: `React.ReactNode` (required)\n- `align`: `'center' | 'left'` (default `'center'`)\n- `className`: `string`\n- `description`: `string`\n- `embedded`: `boolean` (default `false`). Nested inside DocExample — drops outer margin and border (parent supplies chrome).\n- `spec`: `React.ReactNode`\n- `title`: `string`\n- `wide`: `boolean` (default `false`). Use wide layout to break out of narrow prose constraints\n\n### DemoStage\n\nA framed stage for a centrepiece demo or visual, with header slots for a title (`headerStart`) and controls (`headerEnd`).\n\n```tsx\n<DemoStage headerStart=\"Live demo\">\n <Button>Try me</Button>\n</DemoStage>\n```\n\nProps of `DemoStage`:\n\n- `children`: `ReactNode` (required)\n- `className`: `string`\n- `headerEnd`: `ReactNode`\n- `headerStart`: `ReactNode`\n- `panelClassName`: `string`\n\n### DemoConfigPanel\n\nThe controls panel for a `DemoStage`: a popover beside the stage, a sheet on small screens. Put it in `headerEnd` and pass the stage's ref.\n\n```tsx\nimport { DemoConfigPanel, DemoStage } from '@atom63/mdx/blocks'\nimport { Switch } from '@atom63/ui-react'\nimport { useRef, useState } from 'react'\n\nfunction TunableDemo() {\n const stageRef = useRef<HTMLElement>(null)\n const [dense, setDense] = useState(false)\n\n return (\n <DemoStage\n ref={stageRef}\n headerEnd={\n <DemoConfigPanel stageRef={stageRef} title=\"Demo controls\">\n <label>\n <Switch checked={dense} onCheckedChange={setDense} /> Dense\n </label>\n </DemoConfigPanel>\n }\n >\n <p>{dense ? 'Dense' : 'Comfortable'}</p>\n </DemoStage>\n )\n}\n```\n\nProps of `DemoConfigPanel`:\n\n- `children`: `ReactNode` (required)\n- `stageRef`: `RefObject<HTMLElement | null>` (required)\n- `defaultOpen`: `boolean`\n- `label`: `ReactNode` (default `'Tune'`)\n- `mobileQuery`: `string` (default `'(max-width: 767px)'`)\n- `onOpenChange`: `(open: boolean) => void`\n- `open`: `boolean`\n- `panelClassName`: `string`\n- `panelInset`: `number` (default `16`)\n- `panelWidth`: `number` (default `320`)\n- `sheetClassName`: `string`\n- `sheetPanelClassName`: `string`\n- `title`: `string` (default `'Demo controls'`)\n\n## Sequences\n\n### Steps\n\nNumbered steps for a procedure. Numbers and the connecting line come from document order; do not number titles by hand.\n\n```tsx\n<Steps>\n <Steps.Step title=\"Install the package\">Run pnpm add @atom63/mdx.</Steps.Step>\n <Steps.Step title=\"Load the styles\">Import @atom63/mdx/styles/a63.css once.</Steps.Step>\n <Steps.Step title=\"Wrap the page\">Render it inside MDXContentProvider.</Steps.Step>\n</Steps>\n```\n\nProps of `Steps`:\n\n- `children`: `ReactNode` (required)\n- `className`: `string`\n\nProps of `Steps.Step`:\n\n- `children`: `ReactNode` (required)\n- `title`: `ReactNode` (required). Bold heading for the step.\n- `className`: `string`\n- `index`: `number` (default `1`). Injected by `Steps` — the 1-indexed position in document order.\n\n### Timeline\n\nDated events in order: a release history, a project log. Each item has a date, a title and a short body.\n\n```tsx\n<Timeline>\n <Timeline.Item date=\"2025\" title=\"Primitive layer\">Colour ramps, type scale, spacing.</Timeline.Item>\n <Timeline.Item date=\"2026\" title=\"Semantic layer\">Tokens map primitives to intent.</Timeline.Item>\n</Timeline>\n```\n\nProps of `Timeline`:\n\n- `children`: `ReactNode` (required)\n- `className`: `string`\n\nProps of `Timeline.Item`:\n\n- `children`: `ReactNode` (required)\n- `date`: `ReactNode` (required). Date or label shown in the left column (e.g. a year).\n- `title`: `ReactNode` (required). Bold heading for the event.\n- `className`: `string`\n\n### ScrollStage\n\nScroll-driven storytelling: text steps scroll past while each step's `media` stays pinned beside them, and the media changes with the step in view. On narrow screens the media sits above its text.\n\n```mdx\n<ScrollStage>\n <ScrollStage.Step media={<img alt=\"Primitive tokens\" src=\"/images/primitives.webp\" />}>\n ### Primitive layer\n\n Raw values: colour ramps, the type scale, spacing and radius.\n </ScrollStage.Step>\n <ScrollStage.Step media={<img alt=\"Semantic tokens\" src=\"/images/semantic.webp\" />}>\n ### Semantic layer\n\n Tokens that name intent, so one theme change restyles everything.\n </ScrollStage.Step>\n</ScrollStage>\n```\n\nProps of `ScrollStage`:\n\n- `children`: `ReactNode` (required)\n- `className`: `string`\n\nProps of `ScrollStage.Step`:\n\n- `children`: `ReactNode` (required)\n- `media`: `ReactNode` (required). The visual (image, diagram, JSX) shown for this step. Keep it cheap — in the pinned path it re-renders whenever the active step changes, so prefer static images/JSX over heavy live components. Avoid putting anchor `id`s inside `media` or the prose: both the pinned (`lg+`) and stacked (below `lg`) copies render into the DOM, so an `id` would be duplicated.\n- `className`: `string`\n\n## Figures and links\n\n### StatCard\n\nOne metric with a label and an optional change. `trend` colours the change: `up` and `down` use status colours, `neutral` stays muted.\n\n```tsx\n<StatCard change=\"+1 this quarter\" label=\"Themes\" trend=\"up\" value=\"4\" />\n```\n\nProps of `StatCard`:\n\n- `label`: `string` (required). Small muted caption above the value.\n- `value`: `ReactNode` (required). The prominent metric.\n- `change`: `ReactNode`. Optional secondary change indicator, colored by `trend`.\n- `className`: `string`\n- `trend`: `'neutral' | 'up' | 'down'` (default `'neutral'`). Semantic direction of `change`; drives the token color.\n\n### StatGrid\n\nA responsive grid of `StatCard`s.\n\n```tsx\n<StatGrid>\n <StatCard label=\"Blocks\" value=\"30\" />\n <StatCard change=\"-5\" label=\"Open issues\" trend=\"down\" value=\"3\" />\n <StatCard label=\"Themes\" value=\"4\" />\n</StatGrid>\n```\n\nProps of `StatGrid`:\n\n- `children`: `ReactNode` (required)\n- `className`: `string`\n\n### ResourceList\n\nA list of outside links, each with a name and an optional note. Links open in a new tab.\n\n```tsx\n<ResourceList\n items={[\n { name: 'DTCG format', url: 'https://www.designtokens.org', note: 'The token file format' },\n { name: 'WCAG 2.2', url: 'https://www.w3.org/TR/WCAG22/', note: 'Accessibility criteria' },\n ]}\n/>\n```\n\nProps of `ResourceList`:\n\n- `items`: `ResourceItem[]` (required)\n- `className`: `string`\n\n## Diagrams\n\n### MermaidDiagram\n\nA Mermaid chart drawn in the theme's colours, with zoom controls. A fenced `mermaid` code block in MDX renders as one too.\n\n```tsx\n<MermaidDiagram\n chart=\"flowchart LR\n Tokens --> Contracts --> Components\"\n title=\"Build order\"\n/>\n```\n\nProps of `MermaidDiagram`:\n\n- `chart`: `string` (required)\n- `animated`: `boolean` (default `false`). When true, animate the diagram's paths with a stroke draw-on-reveal. Off by default.\n- `labels`: `Partial<MermaidDiagramLabels>`\n- `title`: `string`\n\n### LayerStack\n\nA layered model, top to bottom, with a label, title and optional metaphor, description and constraint per layer. Use it to explain an architecture in layers.\n\n```tsx\n<LayerStack\n title=\"Primitive / Procedure / Product\"\n layers={[\n { label: 'Primitive', title: 'Stable materials', description: 'Raw tokens and scales.' },\n { label: 'Procedure', title: 'Semantic rules', description: 'Semantic tokens and states.' },\n { label: 'Product', title: 'Rendered experience', description: 'Pages and flows.' },\n ]}\n/>\n```\n\nProps of `LayerStack`:\n\n- `layers`: `LayerStackItem[]` (required)\n- `className`: `string`\n- `description`: `ReactNode`\n- `labels`: `Partial<LayerStackLabels>`\n- `title`: `ReactNode`\n\n### ColorSwatchItem\n\nA colour swatch for a CSS variable, with its name and variable. Use it on token and theme pages.\n\n```tsx\n<ColorSwatchItem name=\"Page surface\" variable=\"--a63-surface-page\" />\n<ColorSwatchItem name=\"Primary text\" variable=\"--a63-text-primary\" />\n```\n\nProps of `ColorSwatchItem`:\n\n- `name`: `string` (required)\n- `variable`: `string` (required)\n\n## Code\n\n### CodeBlock\n\nHighlighted code with a copy button and a language label. A fenced code block in MDX renders as one; use the component for code held in a variable.\n\n```tsx\n<CodeBlock code=\"pnpm add @atom63/mdx\" lang=\"bash\" />\n```\n\nProps of `CodeBlock`:\n\n- `code`: `string` (required)\n- `children`: `ReactNode`\n- `className`: `string`\n- `copyLabel`: `string`\n- `fallbackLangLabel`: `string`. Label shown in place of an unknown language in the article header.\n- `lang`: `string` (default `'tsx'`)\n- `loadingLabel`: `string` (default `'Highlighting code'`). Visually-hidden status text announced while syntax highlighting runs.\n- `maxHeight`: `string`\n- `showCopyButton`: `boolean`\n- `showLineNumbers`: `boolean`. Show a numbered gutter. Defaults to a smart heuristic: on for `article` blocks longer than 6 lines, off for short snippets and embedded blocks.\n- `spacing`: `'component' | 'none'`\n- `variant`: `'article' | 'embedded'`\n\n### Tabs\n\nTabbed panels in prose, such as the same step for npm and pnpm. It is the `Tabs` component of `@atom63/ui-react` with MDX spacing, and takes its props: `atom63 component tabs`.\n\n```tsx\n<Tabs defaultValue=\"pnpm\">\n <Tabs.List>\n <Tabs.Tab value=\"pnpm\">pnpm</Tabs.Tab>\n <Tabs.Tab value=\"npm\">npm</Tabs.Tab>\n </Tabs.List>\n <Tabs.Panel value=\"pnpm\">pnpm add @atom63/mdx</Tabs.Panel>\n <Tabs.Panel value=\"npm\">npm install @atom63/mdx</Tabs.Panel>\n</Tabs>\n```\n\n`Tabs` adds no props of its own.\n\nProps of `Tabs.List`:\n\n- `size`: `'sm' | 'default' | 'lg' | 'xs'` (default `tabsContract.defaultSize`)\n- `variant`: `'default' | 'underline' | 'attached'` (default `tabsContract.defaultVariant`)\n\nProps of `Tabs.Panel`:\n\n- `animated`: `boolean` (default `false`)\n\nProps of `Tabs.Tab`:\n\n- `size`: `'sm' | 'default' | 'lg' | 'xs'`\n\n## Page furniture\n\n### Accordion\n\nCollapsible questions and answers, such as an FAQ. It is the `Accordion` component of `@atom63/ui-react` with MDX spacing, and takes its props: `atom63 component accordion`.\n\n```tsx\n<Accordion collapsible type=\"single\">\n <Accordion.Item value=\"token\">\n <Accordion.Trigger>What is a design token?</Accordion.Trigger>\n <Accordion.Content>A named value that components read instead of a literal.</Accordion.Content>\n </Accordion.Item>\n</Accordion>\n```\n\nProps of `Accordion`:\n\n- `collapsible`: `boolean`\n- `defaultValue`: `string | string[]`\n- `onValueChange`: `(value: string | string[]) => void`\n- `type`: `'multiple' | 'single'`\n- `value`: `string | string[]`\n\nProps of `Accordion.Trigger`:\n\n- `icon`: `'chevron' | 'plus-minus'` (default `'chevron'`)\n\n### PageMeta\n\nThe header of an article or lesson: eyebrow, title, description and a meta line such as the reading time.\n\n```tsx\n<PageMeta\n description=\"How semantic tokens keep colour and spacing consistent.\"\n eyebrow=\"Guide\"\n meta=\"8 min read\"\n title=\"Designing with tokens\"\n/>\n```\n\nProps of `PageMeta`:\n\n- `title`: `ReactNode` (required)\n- `children`: `ReactNode`\n- `className`: `string`\n- `description`: `ReactNode`\n- `eyebrow`: `ReactNode`\n- `meta`: `ReactNode`\n\n### PageTableOfContents\n\nThe page's table of contents, built from its `h2` and `h3` headings, with the current section highlighted. `rail` sits beside the text; `inline`, `menu` and `embedded` fit narrow layouts.\n\n```tsx\nimport { PageTableOfContents } from '@atom63/mdx/blocks'\n\n<aside>\n <PageTableOfContents label=\"On this page\" variant=\"rail\" />\n</aside>\n```\n\nProps of `PageTableOfContents`:\n\n- `activeOffset`: `number` (default `120`)\n- `className`: `string`\n- `containerSelector`: `string` (default `'[data-mdx-scroll-root], #learn-main, main'`)\n- `headingSelector`: `string` (default `'[data-mdx-content] h2, [data-mdx-content] h3, article h2, article h3'`)\n- `inlinePositionClassName`: `string` (default `'fixed top-[calc(--spacing(14)+--spacing(3))] right-4 z-30 xl:hidden'`)\n- `label`: `string` (default `'On this page'`)\n- `onActiveLabelChange`: `(label: string) => void`\n- `onNavigate`: `() => void`\n- `scrollOffset`: `number` (default `96`)\n- `showProgress`: `boolean` (default `true`)\n- `smoothScrollDuration`: `number` (default `420`)\n- `variant`: `'menu' | 'embedded' | 'inline' | 'rail'` (default `'rail'`)\n\n### MdxPageSkeleton\n\nThe loading state of an MDX page while its content loads, in the `docs` or `lesson` layout.\n\n```tsx\n<MdxPageSkeleton showRail={false} variant=\"docs\" />\n```\n\nProps of `MdxPageSkeleton`:\n\n- `className`: `string`\n- `showInlineToc`: `boolean` (default `true`)\n- `showRail`: `boolean` (default `true`)\n- `variant`: `'docs' | 'lesson'` (default `'docs'`)\n\n### CreditsBlock\n\nA collapsible list of credits, one role per row, at the end of an article or project page.\n\n```tsx\n<CreditsBlock\n credits={[\n { role: 'Design', credits: 'ATOM63' },\n { role: 'Photography', credits: 'Unsplash contributors' },\n ]}\n/>\n```\n\nProps of `CreditsBlock`:\n\n- `credits`: `CreditEntry[]` (required)\n- `className`: `string`\n- `label`: `string` (default `'Credits'`)\n\n## Prose elements\n\nThe provider's component map also styles plain Markdown, so most of a page needs no blocks:\n\n| Markdown | Renders as |\n|----------|------------|\n| `#` to `######` | Headings on the type scale; `h2` and `h3` feed `PageTableOfContents` |\n| Paragraphs, `**strong**`, `*em*`, `<kbd>` | Body text at prose measure |\n| `[link](url)` | A link; an external one opens in a new tab |\n| `` `code` `` | Inline code |\n| Fenced code | `CodeBlock`; a `mermaid` fence renders `MermaidDiagram` |\n| Lists, `>` quotes, `---` | Lists, a quote, a rule |\n| Tables | The `Table` of `@atom63/ui-react`, scrolling when wide |",
14278
+ "markdown": "# MDX blocks\n\nEvery block `@atom63/mdx/blocks` exports, with what it is for, a working example and its props. The props tables are read from each block's TypeScript types. For setup and the providers, see [MDX content](/patterns/pattern-mdx).\n\nInside a provider (`MDXContentProvider`, `DocsMDXContentProvider` or `ArticleMDXContentProvider`), most blocks need no import: the provider's component map registers them. `KeyIdea`, `Compare`, `ImageCompare`, `LayerStack`, `DocExample`, `DocExampleCode` and `DemoConfigPanel` are not in the map; import them from `@atom63/mdx/blocks`. In React, import any block from there.\n\nLook a block up from the terminal with `atom63 api <Block>`, for example `atom63 api KeyIdea`.\n\n## Notices\n\n### Callout\n\nA notice beside the text: a tip, a caveat, an error to avoid or a success state. Pick `type` by what the reader should feel; one callout per point.\n\n```tsx\n<Callout type=\"warning\">Releases need approval before they publish.</Callout>\n```\n\nProps of `Callout`:\n\n- `children`: `ReactNode` (required)\n- `className`: `string`\n- `type`: `'info' | 'warning' | 'error' | 'success'` (default `'info'`)\n\nSlots, each taking `children`: `Callout.Actions`, `Callout.Body`, `Callout.Icon`, `Callout.Title`.\n\n### KeyIdea\n\nThe one takeaway of a section, set apart with a label and an optional title. Use it once or twice per page; a page of key ideas has none.\n\n```tsx\n<KeyIdea title=\"One token architecture\">\n Every renderer reads the same tokens, so a theme change reaches web, iOS and Figma at once.\n</KeyIdea>\n```\n\nProps of `KeyIdea`:\n\n- `children`: `ReactNode` (required)\n- `className`: `string`\n- `label`: `ReactNode` (default `'Key idea'`)\n- `title`: `ReactNode`\n\n## Comparison\n\n### Compare\n\nTwo or more options side by side, each with an eyebrow, a title and a tone. Use it to explain a difference in words or code; for pictures use `ImageCompare`.\n\n```tsx\n<Compare title=\"Patch CSS vs system CSS\">\n <Compare.Item eyebrow=\"Before\" title=\"Local patch\" tone=\"negative\">\n Values are invented for the screen at hand.\n </Compare.Item>\n <Compare.Item eyebrow=\"After\" title=\"System contract\" tone=\"positive\">\n Values come from tokens that change together.\n </Compare.Item>\n</Compare>\n```\n\nProps of `Compare`:\n\n- `children`: `ReactNode` (required)\n- `className`: `string`\n- `description`: `ReactNode`\n- `title`: `ReactNode`\n\nProps of `Compare.Item`:\n\n- `children`: `ReactNode` (required)\n- `title`: `ReactNode` (required)\n- `className`: `string`\n- `eyebrow`: `ReactNode`\n- `tone`: `'warning' | 'neutral' | 'negative' | 'positive'` (default `'neutral'`)\n\nSlots, each taking `children`: `Compare.Description`, `Compare.Title`.\n\n### ComparisonPair\n\nTwo live panels, before and after, that the reader toggles between. Use it for interaction or motion differences; `speedControl` adds a slow-motion switch.\n\n```tsx\n<ComparisonPair label=\"Spacing\">\n <ComparisonPair.Before label=\"Before\">Cramped 4px gaps</ComparisonPair.Before>\n <ComparisonPair.After label=\"After\">Comfortable 16px gaps</ComparisonPair.After>\n</ComparisonPair>\n```\n\nProps of `ComparisonPair`:\n\n- `children`: `ReactNode` (required)\n- `className`: `string`\n- `label`: `string`\n- `slowMotionLabel`: `string` (default `'Slow motion'`)\n- `speedControl`: `boolean` (default `false`)\n\nProps of `ComparisonPair.After`:\n\n- `children`: `ReactNode` (required)\n- `className`: `string`\n- `label`: `string`\n\nProps of `ComparisonPair.Before`:\n\n- `children`: `ReactNode` (required)\n- `className`: `string`\n- `label`: `string`\n\n### ImageCompare\n\nTwo images in one frame with a draggable divider. Use it when the visual difference is the point; give both images real `alt` text. The slider loads on demand.\n\n```mdx\n<ImageCompare\n title=\"Ad hoc layout vs system layout\"\n before={{ src: '/images/before.webp', alt: 'Form with uneven spacing', label: 'Before' }}\n after={{ src: '/images/after.webp', alt: 'Form on the spacing scale', label: 'After' }}\n caption=\"Drag the divider to compare.\"\n/>\n```\n\nProps of `ImageCompare`:\n\n- `after`: `ImageCompareImage` (required)\n- `before`: `ImageCompareImage` (required)\n- `aspectRatio`: `string` (default `'16/9'`)\n- `bordered`: `boolean` (default `true`)\n- `caption`: `string`\n- `changePositionOnHover`: `boolean` (default `false`)\n- `description`: `string`\n- `handle`: `ReactNode`\n- `idleResetMs`: `number` (default `2500`). Idle ms before restoring to center when `resetAfterIdle` is on.\n- `objectFit`: `'none' | 'contain' | 'cover' | 'fill' | 'scale-down'` (default `'cover'`)\n- `onPositionChange`: `(position: number) => void`\n- `position`: `number` (default `50`). Initial slider position (0-100).\n- `resetAfterIdle`: `boolean` (default `false`). Restore to center after the user stops interacting.\n- `resetDelay`: `number` (default `500`)\n- `resetOnLeave`: `boolean` (default `false`)\n- `title`: `ReactNode`\n- `transition`: `string` (default `'0.25s cubic-bezier(.17,.67,.83,.67)'`)\n- `vertical`: `boolean` (default `false`)\n\n## Media\n\n### FigureBlock\n\nAn image with a caption. Clicking it opens the page's `MediaLightbox` gallery, which the provider hosts; set `enableLightbox={false}` to turn that off. Put rich captions in `FigureBlock.Caption` and a source line in `FigureBlock.Aside`.\n\n```tsx\n<FigureBlock\n alt=\"The Atom63 design system social card\"\n aspectRatio=\"16/9\"\n caption=\"Figure 1. The social card for this site.\"\n src=\"/og.png\"\n/>\n```\n\nProps of `FigureBlock`:\n\n- `alt`: `string` (required)\n- `src`: `string` (required)\n- `aspectRatio`: `'1/1' | '4/3' | '3/4' | '16/9' | '9/16'`\n- `bordered`: `boolean` (default `true`)\n- `caption`: `string`\n- `children`: `ReactNode`\n- `className`: `string`\n- `enableLightbox`: `boolean` (default `true`). Click-to-zoom; multiple figures on a page share one connected gallery.\n- `lightboxGalleryId`: `string` (default `MDX_FIGURE_LIGHTBOX_GALLERY_ID`). Gallery id for connected lightbox (default: all FigureBlocks on the page).\n- `loading`: `'eager' | 'lazy'` (default `'lazy'`)\n- `spacing`: `'none' | 'sm' | 'default' | 'lg'` (default `'default'`)\n\nSlots, each taking `children`: `FigureBlock.Aside`, `FigureBlock.Caption`.\n\n### VideoBlock\n\nA video figure with native controls and an optional caption. A video with speech needs a caption track (`trackSrc`); mark a purely visual loop `captionPolicy=\"decorative\"` instead. With `autoPlay` and no `controls`, it draws its own pause button and stays still under reduced motion.\n\n```mdx\n<VideoBlock src=\"/media/talk.mp4\" title=\"Design tokens talk\" trackSrc=\"/media/talk.en.vtt\" />\n\n<VideoBlock\n autoPlay\n captionPolicy=\"decorative\"\n controls={false}\n loop\n muted\n src=\"/media/loop.mp4\"\n title=\"Theme switching loop\"\n/>\n```\n\nProps of `VideoBlock`:\n\n- `src`: `string` (required)\n- `title`: `string` (required)\n- `autoPlay`: `boolean` (default `false`). Start playing, muted, on load. Ignored when the reader prefers reduced motion. Without `controls`, a pause and play toggle sits over the video.\n- `caption`: `string`\n- `captionPolicy`: `'required' | 'decorative'`. Video has spoken or meaningful audio and must provide captions. Video is decorative or purely visual; no caption track is required.\n- `className`: `string`\n- `controls`: `boolean` (default `true`)\n- `fit`: `'contain' | 'cover'` (default `'contain'`)\n- `loop`: `boolean` (default `false`)\n- `muted`: `boolean` (default `false`)\n- `pauseLabel`: `string` (default `'Pause video'`). Name of the toggle while the video plays. Defaults to \"Pause video\".\n- `playLabel`: `string` (default `'Play video'`). Name of the toggle while the video is paused. Defaults to \"Play video\".\n- `showCaption`: `boolean` (default `false`)\n- `spacing`: `'none' | 'sm' | 'default' | 'lg'` (default `'default'`)\n- `trackLabel`: `string`. Name of the caption track in the player's caption menu. Defaults to the track language's own name, such as \"English\" or \"Deutsch\".\n- `trackLang`: `string` (default `'en'`). BCP 47 language of the caption track (`srclang`). Defaults to `en`.\n- `trackSrc`: `string`\n\n### MediaCaption\n\nThe caption line the media blocks use, on its own: for a custom figure, an embed or a chart.\n\n```tsx\n<MediaCaption>Figure 2. Token layers, from primitive to product.</MediaCaption>\n```\n\nProps of `MediaCaption`:\n\n- `children`: `ReactNode` (required)\n- `className`: `string`\n\n### MediaPlaceholder\n\nA labelled frame that stands in for an image, video or diagram that is not made yet. The label says what the real asset should show.\n\n```tsx\n<MediaPlaceholder kind=\"diagram\" label=\"Token flow from DTCG source to each renderer\" />\n```\n\nProps of `MediaPlaceholder`:\n\n- `aspectRatio`: `string` (default `'16 / 9'`). CSS aspect-ratio for the frame (e.g. `16 / 9`, `4 / 3`, `1 / 1`).\n- `className`: `string`\n- `kind`: `'video' | 'image' | 'diagram'` (default `'image'`). Picks the icon + kind tag. Defaults to `image`.\n- `label`: `string`. What the real asset should show — surfaced as the frame's caption.\n\n## Demos\n\n### DocExample\n\nA live example with Preview and Code tabs and a copy button. Every example on this page is one. Pass the source as `code` and render the same thing as children.\n\n```mdx\n<DocExample title=\"Primary button\" code={`<Button variant=\"primary\">Save</Button>`}>\n <Button variant=\"primary\">Save</Button>\n</DocExample>\n```\n\nProps of `DocExample`:\n\n- `children`: `ReactNode` (required)\n- `code`: `string` (required)\n- `align`: `'center' | 'left'` (default `'center'`)\n- `className`: `string`\n- `codeLabel`: `string` (default `'Code'`). Label for the code tab (default: \"Code\").\n- `copiedAnnouncement`: `string` (default `'Example code copied'`). Visually-hidden live-region text announced after copying (default: \"Example code copied\").\n- `copiedLabel`: `string` (default `'Copied to clipboard'`). aria-label for the copy control right after copying (default: \"Copied to clipboard\").\n- `copyCodeLabel`: `string` (default `'Copy example code'`). aria-label for the copy control when idle (default: \"Copy example code\").\n- `lang`: `string`\n- `previewLabel`: `string` (default `'Preview'`). Label for the preview tab (default: \"Preview\").\n- `title`: `string`\n- `wide`: `boolean` (default `false`)\n\nSlots, each taking `children`: `DocExample.Code`, `DocExample.Preview`, `DocExample.Title`.\n\n### DocExampleCode\n\nThe highlighted code panel of `DocExample`, on its own, for showing code that has no preview.\n\n```tsx\nimport { DocExampleCode } from '@atom63/mdx/blocks'\n\n<DocExampleCode code={`pnpm add @atom63/mdx`} lang=\"bash\" />\n```\n\nProps of `DocExampleCode`:\n\n- `code`: `string` (required)\n- `lang`: `string` (default `'tsx'`)\n\n### ExampleContainer\n\nA plain demo frame on a dot grid, with an optional title, description and spec line. Use it for a preview without a code tab.\n\n```mdx\n<ExampleContainer description=\"The main action of a view.\" title=\"Primary variant\">\n <Button variant=\"primary\">Save</Button>\n</ExampleContainer>\n```\n\nProps of `ExampleContainer`:\n\n- `children`: `React.ReactNode` (required)\n- `align`: `'center' | 'left'` (default `'center'`)\n- `className`: `string`\n- `description`: `string`\n- `embedded`: `boolean` (default `false`). Nested inside DocExample — drops outer margin and border (parent supplies chrome).\n- `spec`: `React.ReactNode`\n- `title`: `string`\n- `wide`: `boolean` (default `false`). Use wide layout to break out of narrow prose constraints\n\n### DemoStage\n\nA framed stage for a centrepiece demo or visual, with header slots for a title (`headerStart`) and controls (`headerEnd`).\n\n```tsx\n<DemoStage headerStart=\"Live demo\">\n <Button>Try me</Button>\n</DemoStage>\n```\n\nProps of `DemoStage`:\n\n- `children`: `ReactNode` (required)\n- `className`: `string`\n- `headerEnd`: `ReactNode`\n- `headerStart`: `ReactNode`\n- `panelClassName`: `string`\n\n### DemoConfigPanel\n\nThe controls panel for a `DemoStage`: a popover beside the stage, a sheet on small screens. Put it in `headerEnd` and pass the stage's ref.\n\n```tsx\nimport { DemoConfigPanel, DemoStage } from '@atom63/mdx/blocks'\nimport { Switch } from '@atom63/ui-react'\nimport { useRef, useState } from 'react'\n\nfunction TunableDemo() {\n const stageRef = useRef<HTMLElement>(null)\n const [dense, setDense] = useState(false)\n\n return (\n <DemoStage\n ref={stageRef}\n headerEnd={\n <DemoConfigPanel stageRef={stageRef} title=\"Demo controls\">\n <label>\n <Switch checked={dense} onCheckedChange={setDense} /> Dense\n </label>\n </DemoConfigPanel>\n }\n >\n <p>{dense ? 'Dense' : 'Comfortable'}</p>\n </DemoStage>\n )\n}\n```\n\nProps of `DemoConfigPanel`:\n\n- `children`: `ReactNode` (required)\n- `stageRef`: `RefObject<HTMLElement | null>` (required)\n- `defaultOpen`: `boolean`\n- `label`: `ReactNode` (default `'Tune'`)\n- `mobileQuery`: `string` (default `'(max-width: 767px)'`)\n- `onOpenChange`: `(open: boolean) => void`\n- `open`: `boolean`\n- `panelClassName`: `string`\n- `panelInset`: `number` (default `16`)\n- `panelWidth`: `number` (default `320`)\n- `sheetClassName`: `string`\n- `sheetPanelClassName`: `string`\n- `title`: `string` (default `'Demo controls'`)\n\n## Sequences\n\n### Steps\n\nNumbered steps for a procedure. Numbers and the connecting line come from document order; do not number titles by hand.\n\n```tsx\n<Steps>\n <Steps.Step title=\"Install the package\">Run pnpm add @atom63/mdx.</Steps.Step>\n <Steps.Step title=\"Load the styles\">Import @atom63/mdx/styles/a63.css once.</Steps.Step>\n <Steps.Step title=\"Wrap the page\">Render it inside MDXContentProvider.</Steps.Step>\n</Steps>\n```\n\nProps of `Steps`:\n\n- `children`: `ReactNode` (required)\n- `className`: `string`\n\nProps of `Steps.Step`:\n\n- `children`: `ReactNode` (required)\n- `title`: `ReactNode` (required). Bold heading for the step.\n- `className`: `string`\n- `index`: `number` (default `1`). Injected by `Steps` — the 1-indexed position in document order.\n\n### Timeline\n\nDated events in order: a release history, a project log. Each item has a date, a title and a short body.\n\n```tsx\n<Timeline>\n <Timeline.Item date=\"2025\" title=\"Primitive layer\">Colour ramps, type scale, spacing.</Timeline.Item>\n <Timeline.Item date=\"2026\" title=\"Semantic layer\">Tokens map primitives to intent.</Timeline.Item>\n</Timeline>\n```\n\nProps of `Timeline`:\n\n- `children`: `ReactNode` (required)\n- `className`: `string`\n\nProps of `Timeline.Item`:\n\n- `children`: `ReactNode` (required)\n- `date`: `ReactNode` (required). Date or label shown in the left column (e.g. a year).\n- `title`: `ReactNode` (required). Bold heading for the event.\n- `className`: `string`\n\n### ScrollStage\n\nScroll-driven storytelling: text steps scroll past while each step's `media` stays pinned beside them, and the media changes with the step in view. On narrow screens the media sits above its text.\n\n```mdx\n<ScrollStage>\n <ScrollStage.Step media={<img alt=\"Primitive tokens\" src=\"/images/primitives.webp\" />}>\n ### Primitive layer\n\n Raw values: colour ramps, the type scale, spacing and radius.\n </ScrollStage.Step>\n <ScrollStage.Step media={<img alt=\"Semantic tokens\" src=\"/images/semantic.webp\" />}>\n ### Semantic layer\n\n Tokens that name intent, so one theme change restyles everything.\n </ScrollStage.Step>\n</ScrollStage>\n```\n\nProps of `ScrollStage`:\n\n- `children`: `ReactNode` (required)\n- `className`: `string`\n\nProps of `ScrollStage.Step`:\n\n- `children`: `ReactNode` (required)\n- `media`: `ReactNode` (required). The visual (image, diagram, JSX) shown for this step. Keep it cheap — in the pinned path it re-renders whenever the active step changes, so prefer static images/JSX over heavy live components. Avoid putting anchor `id`s inside `media` or the prose: both the pinned (`lg+`) and stacked (below `lg`) copies render into the DOM, so an `id` would be duplicated.\n- `className`: `string`\n\n## Figures and links\n\n### StatCard\n\nOne metric with a label and an optional change. `trend` colours the change: `up` and `down` use status colours, `neutral` stays muted.\n\n```tsx\n<StatCard change=\"+1 this quarter\" label=\"Themes\" trend=\"up\" value=\"4\" />\n```\n\nProps of `StatCard`:\n\n- `label`: `string` (required). Small muted caption above the value.\n- `value`: `ReactNode` (required). The prominent metric.\n- `change`: `ReactNode`. Optional secondary change indicator, colored by `trend`.\n- `className`: `string`\n- `trend`: `'neutral' | 'up' | 'down'` (default `'neutral'`). Semantic direction of `change`; drives the token color.\n\n### StatGrid\n\nA responsive grid of `StatCard`s.\n\n```tsx\n<StatGrid>\n <StatCard label=\"Blocks\" value=\"30\" />\n <StatCard change=\"-5\" label=\"Open issues\" trend=\"down\" value=\"3\" />\n <StatCard label=\"Themes\" value=\"4\" />\n</StatGrid>\n```\n\nProps of `StatGrid`:\n\n- `children`: `ReactNode` (required)\n- `className`: `string`\n\n### ResourceList\n\nA list of outside links, each with a name and an optional note. Links open in a new tab.\n\n```tsx\n<ResourceList\n items={[\n { name: 'DTCG format', url: 'https://www.designtokens.org', note: 'The token file format' },\n { name: 'WCAG 2.2', url: 'https://www.w3.org/TR/WCAG22/', note: 'Accessibility criteria' },\n ]}\n/>\n```\n\nProps of `ResourceList`:\n\n- `items`: `ResourceItem[]` (required)\n- `className`: `string`\n\n## Diagrams\n\n### MermaidDiagram\n\nA Mermaid chart drawn in the theme's colours, with zoom controls. A fenced `mermaid` code block in MDX renders as one too.\n\n```tsx\n<MermaidDiagram\n chart=\"flowchart LR\n Tokens --> Contracts --> Components\"\n title=\"Build order\"\n/>\n```\n\nProps of `MermaidDiagram`:\n\n- `chart`: `string` (required)\n- `animated`: `boolean` (default `false`). When true, animate the diagram's paths with a stroke draw-on-reveal. Off by default.\n- `labels`: `Partial<MermaidDiagramLabels>`\n- `title`: `string`\n\n### LayerStack\n\nA layered model, top to bottom, with a label, title and optional metaphor, description and constraint per layer. Use it to explain an architecture in layers.\n\n```tsx\n<LayerStack\n title=\"Primitive / Procedure / Product\"\n layers={[\n { label: 'Primitive', title: 'Stable materials', description: 'Raw tokens and scales.' },\n { label: 'Procedure', title: 'Semantic rules', description: 'Semantic tokens and states.' },\n { label: 'Product', title: 'Rendered experience', description: 'Pages and flows.' },\n ]}\n/>\n```\n\nProps of `LayerStack`:\n\n- `layers`: `LayerStackItem[]` (required)\n- `className`: `string`\n- `description`: `ReactNode`\n- `labels`: `Partial<LayerStackLabels>`\n- `title`: `ReactNode`\n\n### ColorSwatchItem\n\nA colour swatch for a CSS variable, with its name and variable. Use it on token and theme pages.\n\n```tsx\n<ColorSwatchItem name=\"Page surface\" variable=\"--a63-surface-page\" />\n<ColorSwatchItem name=\"Primary text\" variable=\"--a63-text-primary\" />\n```\n\nProps of `ColorSwatchItem`:\n\n- `name`: `string` (required)\n- `variable`: `string` (required)\n\n## Code\n\n### CodeBlock\n\nHighlighted code with a copy button and a language label. A fenced code block in MDX renders as one; use the component for code held in a variable.\n\n```tsx\n<CodeBlock code=\"pnpm add @atom63/mdx\" lang=\"bash\" />\n```\n\nProps of `CodeBlock`:\n\n- `code`: `string` (required)\n- `children`: `ReactNode`\n- `className`: `string`\n- `copyLabel`: `string`\n- `fallbackLangLabel`: `string`. Label shown in place of an unknown language in the article header.\n- `lang`: `string` (default `'tsx'`)\n- `loadingLabel`: `string` (default `'Highlighting code'`). Visually-hidden status text announced while syntax highlighting runs.\n- `maxHeight`: `string`\n- `showCopyButton`: `boolean`\n- `showLineNumbers`: `boolean`. Show a numbered gutter. Defaults to a smart heuristic: on for `article` blocks longer than 6 lines, off for short snippets and embedded blocks.\n- `spacing`: `'component' | 'none'`\n- `variant`: `'article' | 'embedded'`\n\n### Tabs\n\nTabbed panels in prose, such as the same step for npm and pnpm. It is the `Tabs` component of `@atom63/ui-react` with MDX spacing, and takes its props: `atom63 component tabs`.\n\n```tsx\n<Tabs defaultValue=\"pnpm\">\n <Tabs.List>\n <Tabs.Tab value=\"pnpm\">pnpm</Tabs.Tab>\n <Tabs.Tab value=\"npm\">npm</Tabs.Tab>\n </Tabs.List>\n <Tabs.Panel value=\"pnpm\">pnpm add @atom63/mdx</Tabs.Panel>\n <Tabs.Panel value=\"npm\">npm install @atom63/mdx</Tabs.Panel>\n</Tabs>\n```\n\n`Tabs` adds no props of its own.\n\nProps of `Tabs.List`:\n\n- `size`: `'sm' | 'default' | 'lg' | 'xs' | 'md'` (default `tabsContract.defaultSize`). `'default'` is a deprecated alias of `'md'`.\n- `variant`: `'default' | 'underline' | 'attached'` (default `tabsContract.defaultVariant`)\n\nProps of `Tabs.Panel`:\n\n- `animated`: `boolean` (default `false`)\n\nProps of `Tabs.Tab`:\n\n- `size`: `'sm' | 'default' | 'lg' | 'xs' | 'md'`. `'default'` is a deprecated alias of `'md'`.\n\n## Page furniture\n\n### Accordion\n\nCollapsible questions and answers, such as an FAQ. It is the `Accordion` component of `@atom63/ui-react` with MDX spacing, and takes its props: `atom63 component accordion`.\n\n```tsx\n<Accordion collapsible type=\"single\">\n <Accordion.Item value=\"token\">\n <Accordion.Trigger>What is a design token?</Accordion.Trigger>\n <Accordion.Content>A named value that components read instead of a literal.</Accordion.Content>\n </Accordion.Item>\n</Accordion>\n```\n\nProps of `Accordion`:\n\n- `collapsible`: `boolean`\n- `defaultValue`: `string | string[]`\n- `onValueChange`: `(value: string | string[]) => void`\n- `type`: `'multiple' | 'single'`\n- `value`: `string | string[]`\n\nProps of `Accordion.Trigger`:\n\n- `icon`: `'chevron' | 'plus-minus'` (default `'chevron'`)\n\n### PageMeta\n\nThe header of an article or lesson: eyebrow, title, description and a meta line such as the reading time.\n\n```tsx\n<PageMeta\n description=\"How semantic tokens keep colour and spacing consistent.\"\n eyebrow=\"Guide\"\n meta=\"8 min read\"\n title=\"Designing with tokens\"\n/>\n```\n\nProps of `PageMeta`:\n\n- `title`: `ReactNode` (required)\n- `children`: `ReactNode`\n- `className`: `string`\n- `description`: `ReactNode`\n- `eyebrow`: `ReactNode`\n- `meta`: `ReactNode`\n\n### PageTableOfContents\n\nThe page's table of contents, built from its `h2` and `h3` headings, with the current section highlighted. `rail` sits beside the text; `inline`, `menu` and `embedded` fit narrow layouts.\n\n```tsx\nimport { PageTableOfContents } from '@atom63/mdx/blocks'\n\n<aside>\n <PageTableOfContents label=\"On this page\" variant=\"rail\" />\n</aside>\n```\n\nProps of `PageTableOfContents`:\n\n- `activeOffset`: `number` (default `120`)\n- `className`: `string`\n- `containerSelector`: `string` (default `'[data-mdx-scroll-root], #learn-main, main'`)\n- `headingSelector`: `string` (default `'[data-mdx-content] h2, [data-mdx-content] h3, article h2, article h3'`)\n- `inlinePositionClassName`: `string` (default `'fixed top-[calc(--spacing(14)+--spacing(3))] right-4 z-30 xl:hidden'`)\n- `label`: `string` (default `'On this page'`)\n- `onActiveLabelChange`: `(label: string) => void`\n- `onNavigate`: `() => void`\n- `scrollOffset`: `number` (default `96`)\n- `showProgress`: `boolean` (default `true`)\n- `smoothScrollDuration`: `number` (default `420`)\n- `variant`: `'menu' | 'embedded' | 'inline' | 'rail'` (default `'rail'`)\n\n### MdxPageSkeleton\n\nThe loading state of an MDX page while its content loads, in the `docs` or `lesson` layout.\n\n```tsx\n<MdxPageSkeleton showRail={false} variant=\"docs\" />\n```\n\nProps of `MdxPageSkeleton`:\n\n- `className`: `string`\n- `showInlineToc`: `boolean` (default `true`)\n- `showRail`: `boolean` (default `true`)\n- `variant`: `'docs' | 'lesson'` (default `'docs'`)\n\n### CreditsBlock\n\nA collapsible list of credits, one role per row, at the end of an article or project page.\n\n```tsx\n<CreditsBlock\n credits={[\n { role: 'Design', credits: 'ATOM63' },\n { role: 'Photography', credits: 'Unsplash contributors' },\n ]}\n/>\n```\n\nProps of `CreditsBlock`:\n\n- `credits`: `CreditEntry[]` (required)\n- `className`: `string`\n- `label`: `string` (default `'Credits'`)\n\n## Prose elements\n\nThe provider's component map also styles plain Markdown, so most of a page needs no blocks:\n\n| Markdown | Renders as |\n|----------|------------|\n| `#` to `######` | Headings on the type scale; `h2` and `h3` feed `PageTableOfContents` |\n| Paragraphs, `**strong**`, `*em*`, `<kbd>` | Body text at prose measure |\n| `[link](url)` | A link; an external one opens in a new tab |\n| `` `code` `` | Inline code |\n| Fenced code | `CodeBlock`; a `mermaid` fence renders `MermaidDiagram` |\n| Lists, `>` quotes, `---` | Lists, a quote, a rule |\n| Tables | The `Table` of `@atom63/ui-react`, scrolling when wide |",
14178
14279
  "route": "/patterns/pattern-mdx-blocks",
14179
14280
  "slug": "pattern-mdx-blocks"
14180
14281
  },