@atom63/cli 0.1.0-beta.0 → 0.1.0-beta.1

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.
@@ -209,7 +209,7 @@
209
209
  "Themes",
210
210
  "ContractMetadata"
211
211
  ],
212
- "source": "import {\n brands,\n buttonContract,\n buttonShapes,\n buttonSizes,\n buttonVariants,\n densities,\n designLanguages,\n inputs,\n} from '@atom63/ui-foundation'\nimport { Button, UIProvider } from '@atom63/ui-react'\nimport '@atom63/ui-react/styles.css'\nimport type { Meta, StoryObj } from '@storybook/react-vite'\nimport {\n ArrowRightLeft,\n Bell,\n ChevronLeft,\n Ellipsis,\n Inbox,\n Layers,\n LocateFixed,\n Plus,\n Send,\n} from 'lucide-react'\nimport type { CSSProperties } from 'react'\nimport { EnvironmentShell, PreviewCard, ThemeMatrix } from '../story-probes'\n\nconst meta = {\n title: 'UI React/Button',\n component: Button,\n argTypes: {\n variant: {\n control: 'select',\n options: buttonVariants,\n },\n size: {\n control: 'select',\n options: buttonSizes,\n },\n loading: { control: 'boolean' },\n disabled: { control: 'boolean' },\n children: { control: 'text' },\n },\n args: {\n children: 'Continue',\n disabled: false,\n loading: false,\n size: 'md',\n variant: 'default',\n },\n} satisfies Meta<typeof Button>\n\nexport default meta\n\ntype Story = StoryObj<typeof meta>\n\nfunction PlusIcon() {\n return (\n <svg aria-hidden=\"true\" viewBox=\"0 0 16 16\">\n <path\n d=\"M8 3.25v9.5M3.25 8h9.5\"\n fill=\"none\"\n stroke=\"currentColor\"\n strokeLinecap=\"round\"\n strokeWidth=\"1.7\"\n />\n </svg>\n )\n}\n\nexport const Playground: Story = {\n render: args => (\n <EnvironmentShell>\n <Button {...args} />\n </EnvironmentShell>\n ),\n}\n\nexport const Variants: Story = {\n render: () => (\n <EnvironmentShell>\n <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.75rem' }}>\n {buttonVariants.map(variant => (\n <Button key={variant} variant={variant}>\n {variant}\n </Button>\n ))}\n </div>\n </EnvironmentShell>\n ),\n}\n\n/* Secondary actions in a toolbar, a row or a card header: ghost with\n tone=\"muted\" rests in the secondary text colour and goes to full contrast on\n hover, focus and press. The pressed one shows that state. The top row is the\n plain ghost for comparison. */\nexport const QuietSecondaryActions: Story = {\n render: () => (\n <EnvironmentShell>\n <div style={{ display: 'grid', gap: '0.75rem' }}>\n {(['neutral', 'muted'] as const).map(tone => (\n <div\n data-testid={`tone-${tone}`}\n key={tone}\n style={{ alignItems: 'center', display: 'flex', gap: '0.25rem' }}\n >\n <Button aria-label=\"Add\" size=\"icon-xs\" tone={tone} variant=\"ghost\">\n <Plus aria-hidden />\n </Button>\n <Button aria-label=\"Notifications\" size=\"icon-sm\" tone={tone} variant=\"ghost\">\n <Bell aria-hidden />\n </Button>\n <Button aria-label=\"Inbox\" size=\"icon-sm\" tone={tone} variant=\"ghost\">\n <Inbox aria-hidden />\n </Button>\n <Button\n aria-label=\"More\"\n data-pressed={tone === 'muted' ? '' : undefined}\n size=\"icon\"\n tone={tone}\n variant=\"ghost\"\n >\n <Ellipsis aria-hidden />\n </Button>\n <Button size=\"sm\" tone={tone} variant=\"ghost\">\n <Send aria-hidden />\n Share\n </Button>\n </div>\n ))}\n </div>\n </EnvironmentShell>\n ),\n play: ({ canvasElement }) => {\n const row = canvasElement.querySelector('[data-testid=\"tone-muted\"]')\n const buttons = [...(row?.querySelectorAll<HTMLElement>('.a63-Button') ?? [])]\n const foreground = (el: HTMLElement) =>\n getComputedStyle(el).getPropertyValue('--button-foreground').trim()\n const token = (el: HTMLElement, name: string) =>\n getComputedStyle(el).getPropertyValue(name).trim()\n const [add, bell, , more] = buttons\n if (!add || !bell || !more) throw new Error('Expected the muted toolbar buttons')\n if (foreground(bell) !== token(bell, '--a63-text-secondary')) {\n throw new Error('A resting muted ghost should use the secondary text colour')\n }\n if (foreground(more) !== token(more, '--a63-text-primary')) {\n throw new Error('A pressed muted ghost should go to full contrast')\n }\n const glyphs = [add, bell, more].map(\n el => el.querySelector('svg')?.getBoundingClientRect().width\n )\n if (glyphs.join() !== '14,16,18') {\n throw new Error(`Expected 14/16/18px glyphs in icon-xs/icon-sm/icon, got ${glyphs.join('/')}`)\n }\n },\n}\n\n/* The parity sweep added two media-facing variants — `overlay` (frosted, sits\n on light imagery) and `glass` (dark-glass, sits on busy or bright imagery).\n Both are meant to float over media, so they only read correctly against a\n backdrop; render them over an image scrim rather than a flat panel. */\nexport const OverMedia: Story = {\n render: () => (\n <EnvironmentShell>\n <div\n style={{\n alignItems: 'center',\n backgroundImage:\n 'linear-gradient(135deg, oklch(72% 0.16 250), oklch(64% 0.2 320) 55%, oklch(58% 0.18 30))',\n borderRadius: '0.875rem',\n display: 'flex',\n flexWrap: 'wrap',\n gap: '0.75rem',\n minHeight: '7rem',\n padding: '1.5rem',\n }}\n >\n <Button variant=\"overlay\">Overlay</Button>\n <Button variant=\"glass\">Glass</Button>\n <Button aria-label=\"Add\" size=\"icon\" variant=\"glass\">\n <PlusIcon />\n </Button>\n </div>\n </EnvironmentShell>\n ),\n}\n\n/* shape=\"round\": circles for icon sizes, pills for labelled sizes, as for a\n player's play button or a pill-shaped call to action. */\n/* Controls over a photo: the overlay variant reads on any image, and\n shape=\"round\" makes the circular play and close buttons media UIs use. */\nexport const RoundOverMedia: Story = {\n render: () => (\n <div\n style={{\n alignItems: 'center',\n backgroundImage:\n 'linear-gradient(135deg, oklch(72% 0.16 250), oklch(64% 0.2 320) 55%, oklch(58% 0.18 30))',\n borderRadius: '0.875rem',\n display: 'flex',\n gap: '0.75rem',\n minHeight: '7rem',\n padding: '1.5rem',\n }}\n >\n <Button aria-label=\"Close\" shape=\"round\" size=\"icon-sm\" variant=\"overlay\">\n <PlusIcon />\n </Button>\n <Button aria-label=\"Play\" shape=\"round\" size=\"icon-lg\" variant=\"overlay\">\n <PlusIcon />\n </Button>\n <Button shape=\"round\" variant=\"overlay\">\n Follow\n </Button>\n </div>\n ),\n}\n\n/* Floating over a map: variant=\"raised\" with shape=\"round\" is the light\n floating button maps and light heroes use (back, locate, layers). The panel\n fill and a soft shadow lift it off a light picture; over dark media use\n overlay. The map is a placeholder with fixed light-map colors, as a real\n map tile would be. */\nexport const FloatingOverMap: Story = {\n render: () => (\n <div\n style={{\n backgroundColor: 'oklch(95% 0.02 95)',\n backgroundImage: [\n 'radial-gradient(circle at 72% 68%, oklch(88% 0.07 150) 0 18%, transparent 18.5%)',\n 'radial-gradient(ellipse at 12% 90%, oklch(86% 0.06 230) 0 22%, transparent 22.5%)',\n 'linear-gradient(28deg, transparent 47%, oklch(99% 0 0) 47% 51%, transparent 51%)',\n 'linear-gradient(118deg, transparent 58%, oklch(99% 0 0) 58% 60.5%, transparent 60.5%)',\n 'linear-gradient(90deg, transparent 30%, oklch(92% 0.06 85) 30% 32.5%, transparent 32.5%)',\n ].join(', '),\n borderRadius: '0.875rem',\n height: '22rem',\n maxWidth: '24rem',\n position: 'relative',\n }}\n >\n <div style={{ insetInlineStart: '1rem', position: 'absolute', top: '1rem' }}>\n <Button aria-label=\"Back\" shape=\"round\" size=\"icon-lg\" variant=\"raised\">\n <ChevronLeft />\n </Button>\n </div>\n <div\n style={{\n display: 'grid',\n gap: '0.75rem',\n insetInlineEnd: '1rem',\n position: 'absolute',\n top: '1rem',\n }}\n >\n <Button aria-label=\"Map layers\" shape=\"round\" size=\"icon-lg\" variant=\"raised\">\n <Layers />\n </Button>\n <Button aria-label=\"Show my location\" shape=\"round\" size=\"icon-lg\" variant=\"raised\">\n <LocateFixed />\n </Button>\n </div>\n <div\n style={{\n bottom: '1rem',\n display: 'flex',\n gap: '0.5rem',\n insetInlineStart: '1rem',\n position: 'absolute',\n }}\n >\n <Button shape=\"round\" variant=\"raised\">\n Search this area\n </Button>\n <Button disabled shape=\"round\" variant=\"raised\">\n Directions\n </Button>\n </div>\n </div>\n ),\n play: ({ canvasElement }) => {\n const button = canvasElement.querySelector<HTMLElement>('[aria-label=\"Back\"]')\n if (!button) throw new Error('Expected the Back button')\n const style = getComputedStyle(button)\n const { width, height } = button.getBoundingClientRect()\n if (Math.abs(width - height) > 0.5 || style.borderTopLeftRadius !== '9999px') {\n throw new Error(`Expected a circle, got ${width}x${height} / ${style.borderTopLeftRadius}`)\n }\n if (style.boxShadow === 'none' || !/\\dpx/.test(style.boxShadow)) {\n throw new Error(`Expected a soft shadow, got ${style.boxShadow}`)\n }\n if (style.borderTopColor !== 'rgba(0, 0, 0, 0)') {\n throw new Error(`Expected no visible border, got ${style.borderTopColor}`)\n }\n },\n}\n\nconst heroActions = [\n { icon: Plus, label: 'Add money' },\n { icon: ArrowRightLeft, label: 'Move' },\n { icon: Send, label: 'Send' },\n { icon: Ellipsis, label: 'More' },\n]\n\n/* A hero on --a63-gradient-brand-fade, which runs from the brand into the page.\n Overlay buttons and their on-media labels sit in the dark zone, the top\n --a63-gradient-brand-fade-dark-zone of the hero, where white keeps WCAG AA\n on every brand. Below it the hero fades into the page, so the content\n there uses the page tokens and the default button variants, on its own\n panel while the fade is still running. */\nexport const RoundOnBrandFade: Story = {\n render: () => (\n <div\n style={{\n backgroundImage: 'var(--a63-gradient-brand-fade)',\n borderRadius: '0.875rem',\n display: 'grid',\n gridTemplateRows: 'var(--a63-gradient-brand-fade-dark-zone) 1fr',\n height: '26rem',\n maxWidth: '24rem',\n }}\n >\n <div\n style={{\n alignContent: 'space-between',\n color: 'var(--a63-on-media-foreground)',\n display: 'grid',\n gap: 'var(--a63-space-4)',\n padding: 'var(--a63-space-5)',\n }}\n >\n <div>\n <div style={{ fontSize: 'var(--a63-type-footnote-font-size)' }}>Main account</div>\n <div\n style={{\n fontSize: 'var(--a63-type-large-title-font-size)',\n fontWeight: 'var(--a63-type-large-title-font-weight)',\n }}\n >\n £2,480.15\n </div>\n </div>\n <div style={{ display: 'flex', justifyContent: 'space-between' }}>\n {heroActions.map(({ icon: Icon, label }) => (\n <div\n key={label}\n style={{\n alignItems: 'center',\n display: 'grid',\n fontSize: 'var(--a63-type-footnote-font-size)',\n gap: 'var(--a63-space-1_5)',\n justifyItems: 'center',\n }}\n >\n <Button aria-label={label} shape=\"round\" size=\"icon-lg\" variant=\"overlay\">\n <Icon aria-hidden />\n </Button>\n <span aria-hidden>{label}</span>\n </div>\n ))}\n </div>\n </div>\n <div style={{ alignContent: 'end', display: 'grid', padding: 'var(--a63-space-3)' }}>\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: 'var(--a63-space-3)',\n padding: 'var(--a63-space-4)',\n }}\n >\n <p style={{ color: 'var(--a63-text-secondary)', margin: 0 }}>\n Below the dark zone the hero fades into the page. Content here uses the page tokens on\n its own panel, never overlay buttons or on-media text, which vanish as the hero fades.\n </p>\n <Button variant=\"outline\">See all transactions</Button>\n </div>\n </div>\n </div>\n ),\n}\n\n/* indicator: an unread dot (true) or a count, added to the accessible name. */\nexport const Indicator: Story = {\n render: () => (\n <EnvironmentShell>\n <div style={{ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '1rem' }}>\n <Button aria-label=\"Notifications\" indicator size=\"icon\" variant=\"ghost\">\n <Bell aria-hidden />\n </Button>\n <Button\n aria-label=\"Notifications\"\n indicator={3}\n shape=\"round\"\n size=\"icon\"\n variant=\"outline\"\n >\n <Bell aria-hidden />\n </Button>\n <Button aria-label=\"Notifications\" indicator={120} size=\"icon\">\n <Bell aria-hidden />\n </Button>\n <Button indicator={4} variant=\"outline\">\n <Inbox aria-hidden />\n Inbox\n </Button>\n </div>\n </EnvironmentShell>\n ),\n}\n\nexport const Shapes: Story = {\n render: () => (\n <EnvironmentShell>\n <div style={{ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '0.75rem' }}>\n {buttonShapes.map(shape => (\n <Button key={shape} shape={shape} variant=\"outline\">\n {shape}\n </Button>\n ))}\n <Button aria-label=\"Play\" shape=\"round\" size=\"icon\" variant=\"primary\">\n <PlusIcon />\n </Button>\n <Button aria-label=\"Add\" shape=\"round\" size=\"icon-sm\">\n <PlusIcon />\n </Button>\n <Button shape=\"round\" size=\"lg\" variant=\"primary\">\n Get started\n </Button>\n </div>\n </EnvironmentShell>\n ),\n}\n\n/* shape=\"round\" stays a circle at any size: an 88px play button, larger than\n the 56px where the soft --radius-full corner stops looking round. */\nexport const RoundLarge: Story = {\n render: () => (\n <EnvironmentShell>\n <Button\n aria-label=\"Play\"\n shape=\"round\"\n size=\"icon-xl\"\n style={{ '--button-height': '88px' } as CSSProperties}\n variant=\"primary\"\n >\n <PlusIcon />\n </Button>\n </EnvironmentShell>\n ),\n play: ({ canvasElement }) => {\n const button = canvasElement.querySelector<HTMLElement>('[data-shape=\"round\"]')\n const width = button?.getBoundingClientRect().width\n const radius = button && getComputedStyle(button).borderTopLeftRadius\n if (width !== 88 || radius !== '9999px') {\n throw new Error(`Expected an 88px button with a 9999px radius, got ${width}px / ${radius}`)\n }\n },\n}\n\nexport const Sizes: Story = {\n render: () => (\n <EnvironmentShell>\n <div style={{ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '0.75rem' }}>\n {buttonSizes.map(size => (\n <Button aria-label={size.startsWith('icon') ? 'Add' : undefined} key={size} size={size}>\n {size.startsWith('icon') ? <PlusIcon /> : size}\n </Button>\n ))}\n </div>\n </EnvironmentShell>\n ),\n}\n\n/* Tile size — full-width, icon-over-label; the launcher / app-grid shape ported\n from the legacy @atom63/ui button. Composes with any variant, and the caption\n wraps + stays centered. */\nexport const Tile: Story = {\n render: () => (\n <EnvironmentShell>\n <div style={{ display: 'grid', gap: '0.75rem', gridTemplateColumns: 'repeat(3, 1fr)' }}>\n <Button size=\"tile\" variant=\"outline\">\n <PlusIcon />\n New\n </Button>\n <Button size=\"tile\" variant=\"outline\">\n <PlusIcon />\n Import\n </Button>\n <Button size=\"tile\" variant=\"ghost\">\n <PlusIcon />A longer tile caption that wraps\n </Button>\n </div>\n </EnvironmentShell>\n ),\n}\n\nexport const States: Story = {\n render: () => (\n <EnvironmentShell>\n <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.75rem' }}>\n <Button>Default</Button>\n <Button loading>Loading</Button>\n <Button disabled>Disabled</Button>\n <Button disabled variant=\"primary\">\n Disabled primary\n </Button>\n <Button data-pressed=\"\">Pressed</Button>\n <Button variant=\"outline\">\n <PlusIcon />\n With icon\n </Button>\n </div>\n </EnvironmentShell>\n ),\n play: async ({ canvas, canvasElement }) => {\n // A disabled primary is a neutral fill with muted text, not a paler accent,\n // in every environment the shell renders.\n for (const button of canvas.getAllByRole('button', { name: 'Disabled primary' })) {\n // Paint a value next to the button, so it resolves in the button's environment.\n const paint = (property: 'backgroundColor' | 'color', value: string) => {\n const probe = canvasElement.ownerDocument.createElement('span')\n probe.style[property] = value\n button.after(probe)\n const painted = getComputedStyle(probe)[property]\n probe.remove()\n return painted\n }\n const style = getComputedStyle(button)\n // ui-react does not depend on storybook, so the checks throw plain errors.\n const background = paint('backgroundColor', 'var(--a63-action-disabled-background)')\n if (style.backgroundColor !== background) {\n throw new Error(`Disabled background ${style.backgroundColor}, expected ${background}`)\n }\n const color = paint('color', 'var(--a63-action-disabled-foreground)')\n if (style.color !== color) {\n throw new Error(`Disabled foreground ${style.color}, expected ${color}`)\n }\n if (style.backgroundColor === paint('backgroundColor', 'var(--a63-action-primary)')) {\n throw new Error('Disabled primary still uses the action-primary fill')\n }\n }\n },\n}\n\n/* Loading treatment across every variant. */\nexport const Loading: Story = {\n render: () => (\n <EnvironmentShell>\n <div style={{ display: 'grid', gap: '0.875rem' }}>\n <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.75rem' }}>\n {buttonVariants\n .filter(variant => variant !== 'overlay' && variant !== 'glass')\n .map(variant => (\n <Button key={variant} loading variant={variant}>\n {variant}\n </Button>\n ))}\n </div>\n <div\n style={{\n backgroundImage:\n 'linear-gradient(135deg, oklch(72% 0.16 250), oklch(64% 0.2 320) 55%, oklch(58% 0.18 30))',\n borderRadius: '0.875rem',\n display: 'flex',\n flexWrap: 'wrap',\n gap: '0.75rem',\n padding: '1.25rem',\n }}\n >\n <Button loading variant=\"overlay\">\n Overlay\n </Button>\n <Button loading variant=\"glass\">\n Glass\n </Button>\n <Button aria-label=\"Add\" loading size=\"icon\" variant=\"glass\">\n <PlusIcon />\n </Button>\n </div>\n </div>\n </EnvironmentShell>\n ),\n}\n\nexport const EnvironmentMatrix: Story = {\n parameters: {\n layout: 'fullscreen',\n },\n render: () => (\n <div\n style={{\n display: 'grid',\n gap: '1rem',\n gridTemplateColumns: 'repeat(auto-fit, minmax(19rem, 1fr))',\n padding: '1rem',\n }}\n >\n {designLanguages.map(designLanguage =>\n densities.map(density =>\n inputs.map(input => (\n <UIProvider\n density={density}\n designLanguage={designLanguage}\n input={input}\n key={`${designLanguage}-${density}-${input}`}\n mode=\"light\"\n >\n <PreviewCard label={`${designLanguage} / ${density} / ${input}`}>\n <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.75rem' }}>\n <Button>Continue</Button>\n <Button variant=\"ghost\">Maybe</Button>\n <Button variant=\"ghost\">Cancel</Button>\n </div>\n </PreviewCard>\n </UIProvider>\n ))\n )\n )}\n </div>\n ),\n}\n\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 flexWrap: 'wrap',\n gap: '0.5rem',\n padding: '0.75rem',\n }}\n >\n <span style={{ color: 'var(--a63-text-secondary)', fontSize: 12, width: 112 }}>\n {endpoint.label}\n </span>\n <Button variant=\"primary\">Primary</Button>\n <Button>Default</Button>\n <Button variant=\"outline\">Outline</Button>\n <Button variant=\"ghost\">Ghost</Button>\n <Button aria-label=\"Add\" size=\"icon\">\n <PlusIcon />\n </Button>\n </div>\n </UIProvider>\n ))}\n </div>\n ),\n}\n\nexport const BrandRamps: Story = {\n render: () => (\n <div\n style={{\n display: 'grid',\n gap: '1rem',\n gridTemplateColumns: 'repeat(auto-fit, minmax(11rem, 1fr))',\n }}\n >\n {brands.map(brand => (\n <UIProvider brand={brand} key={brand} mode=\"light\">\n <PreviewCard label={`brand / ${brand}`}>\n <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.5rem' }}>\n <Button variant=\"primary\">Primary</Button>\n <Button variant=\"outline\">Outline</Button>\n </div>\n </PreviewCard>\n </UIProvider>\n ))}\n </div>\n ),\n}\n\n/* Theme probe — the four skins x light/dark via the shared ThemeMatrix. */\nexport const Themes: Story = {\n parameters: { layout: 'fullscreen' },\n render: () => (\n <ThemeMatrix>\n <div style={{ display: 'grid', gap: '0.5rem' }}>\n <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.5rem' }}>\n <Button variant=\"primary\">Primary</Button>\n <Button>Default</Button>\n <Button variant=\"destructive\">Delete</Button>\n <Button variant=\"outline\">Outline</Button>\n <Button variant=\"ghost\">Ghost</Button>\n </div>\n <div\n style={{\n backgroundImage: 'linear-gradient(135deg, oklch(70% 0.16 250), oklch(60% 0.2 320))',\n borderRadius: '0.625rem',\n display: 'flex',\n flexWrap: 'wrap',\n gap: '0.5rem',\n padding: '0.75rem',\n }}\n >\n <Button variant=\"overlay\">Overlay</Button>\n <Button variant=\"glass\">Glass</Button>\n </div>\n </div>\n </ThemeMatrix>\n ),\n}\n\nexport const ContractMetadata: Story = {\n render: () => (\n <pre style={{ fontSize: 12, margin: 0, whiteSpace: 'pre-wrap' }}>\n {JSON.stringify(buttonContract, null, 2)}\n </pre>\n ),\n}\n"
212
+ "source": "import {\n brands,\n buttonContract,\n buttonShapes,\n buttonSizes,\n buttonVariants,\n densities,\n designLanguages,\n inputs,\n} from '@atom63/ui-foundation'\nimport { Button, UIProvider } from '@atom63/ui-react'\nimport '@atom63/ui-react/styles.css'\nimport type { Meta, StoryObj } from '@storybook/react-vite'\nimport {\n ArrowRightLeft,\n Bell,\n ChevronLeft,\n Ellipsis,\n Inbox,\n Layers,\n LocateFixed,\n Plus,\n Send,\n} from 'lucide-react'\nimport type { CSSProperties } from 'react'\nimport { EnvironmentShell, PreviewCard, ThemeMatrix } from '../story-probes'\n\nconst meta = {\n title: 'UI React/Button',\n component: Button,\n argTypes: {\n variant: {\n control: 'select',\n options: buttonVariants,\n },\n size: {\n control: 'select',\n options: buttonSizes,\n },\n loading: { control: 'boolean' },\n disabled: { control: 'boolean' },\n children: { control: 'text' },\n },\n args: {\n children: 'Continue',\n disabled: false,\n loading: false,\n size: 'md',\n variant: 'default',\n },\n} satisfies Meta<typeof Button>\n\nexport default meta\n\ntype Story = StoryObj<typeof meta>\n\nfunction PlusIcon() {\n return (\n <svg aria-hidden=\"true\" viewBox=\"0 0 16 16\">\n <path\n d=\"M8 3.25v9.5M3.25 8h9.5\"\n fill=\"none\"\n stroke=\"currentColor\"\n strokeLinecap=\"round\"\n strokeWidth=\"1.7\"\n />\n </svg>\n )\n}\n\nexport const Playground: Story = {\n render: args => (\n <EnvironmentShell>\n <Button {...args} />\n </EnvironmentShell>\n ),\n}\n\n/* The media-facing variants (overlay, glass) only read over a backdrop; OverMedia shows them. */\nconst flatVariants = buttonVariants.filter(variant => variant !== 'overlay' && variant !== 'glass')\n\nexport const Variants: Story = {\n render: () => (\n <EnvironmentShell>\n <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.75rem' }}>\n {flatVariants.map(variant => (\n <Button key={variant} variant={variant}>\n {variant}\n </Button>\n ))}\n </div>\n </EnvironmentShell>\n ),\n}\n\n/* Secondary actions in a toolbar, a row or a card header: ghost with\n tone=\"muted\" rests in the secondary text colour and goes to full contrast on\n hover, focus and press. The pressed one shows that state. The top row is the\n plain ghost for comparison. */\nexport const QuietSecondaryActions: Story = {\n render: () => (\n <EnvironmentShell>\n <div style={{ display: 'grid', gap: '0.75rem' }}>\n {(['neutral', 'muted'] as const).map(tone => (\n <div\n data-testid={`tone-${tone}`}\n key={tone}\n style={{ alignItems: 'center', display: 'flex', gap: '0.25rem' }}\n >\n <Button aria-label=\"Add\" size=\"icon-xs\" tone={tone} variant=\"ghost\">\n <Plus aria-hidden />\n </Button>\n <Button aria-label=\"Notifications\" size=\"icon-sm\" tone={tone} variant=\"ghost\">\n <Bell aria-hidden />\n </Button>\n <Button aria-label=\"Inbox\" size=\"icon-sm\" tone={tone} variant=\"ghost\">\n <Inbox aria-hidden />\n </Button>\n <Button\n aria-label=\"More\"\n data-pressed={tone === 'muted' ? '' : undefined}\n size=\"icon\"\n tone={tone}\n variant=\"ghost\"\n >\n <Ellipsis aria-hidden />\n </Button>\n <Button size=\"sm\" tone={tone} variant=\"ghost\">\n <Send aria-hidden />\n Share\n </Button>\n </div>\n ))}\n </div>\n </EnvironmentShell>\n ),\n play: ({ canvasElement }) => {\n const row = canvasElement.querySelector('[data-testid=\"tone-muted\"]')\n const buttons = [...(row?.querySelectorAll<HTMLElement>('.a63-Button') ?? [])]\n const foreground = (el: HTMLElement) =>\n getComputedStyle(el).getPropertyValue('--button-foreground').trim()\n const token = (el: HTMLElement, name: string) =>\n getComputedStyle(el).getPropertyValue(name).trim()\n const [add, bell, , more] = buttons\n if (!add || !bell || !more) throw new Error('Expected the muted toolbar buttons')\n if (foreground(bell) !== token(bell, '--a63-text-secondary')) {\n throw new Error('A resting muted ghost should use the secondary text colour')\n }\n if (foreground(more) !== token(more, '--a63-text-primary')) {\n throw new Error('A pressed muted ghost should go to full contrast')\n }\n const glyphs = [add, bell, more].map(\n el => el.querySelector('svg')?.getBoundingClientRect().width\n )\n if (glyphs.join() !== '14,16,18') {\n throw new Error(`Expected 14/16/18px glyphs in icon-xs/icon-sm/icon, got ${glyphs.join('/')}`)\n }\n },\n}\n\n/* The parity sweep added two media-facing variants — `overlay` (frosted, sits\n on light imagery) and `glass` (dark-glass, sits on busy or bright imagery).\n Both are meant to float over media, so they only read correctly against a\n backdrop; render them over an image scrim rather than a flat panel. */\nexport const OverMedia: Story = {\n render: () => (\n <EnvironmentShell>\n <div\n style={{\n alignItems: 'center',\n backgroundImage:\n 'linear-gradient(135deg, oklch(72% 0.16 250), oklch(64% 0.2 320) 55%, oklch(58% 0.18 30))',\n borderRadius: '0.875rem',\n display: 'flex',\n flexWrap: 'wrap',\n gap: '0.75rem',\n minHeight: '7rem',\n padding: '1.5rem',\n }}\n >\n <Button variant=\"overlay\">Overlay</Button>\n <Button variant=\"glass\">Glass</Button>\n <Button aria-label=\"Add\" size=\"icon\" variant=\"glass\">\n <PlusIcon />\n </Button>\n </div>\n </EnvironmentShell>\n ),\n}\n\n/* shape=\"round\": circles for icon sizes, pills for labelled sizes, as for a\n player's play button or a pill-shaped call to action. */\n/* Controls over a photo: the overlay variant reads on any image, and\n shape=\"round\" makes the circular play and close buttons media UIs use. */\nexport const RoundOverMedia: Story = {\n render: () => (\n <div\n style={{\n alignItems: 'center',\n backgroundImage:\n 'linear-gradient(135deg, oklch(72% 0.16 250), oklch(64% 0.2 320) 55%, oklch(58% 0.18 30))',\n borderRadius: '0.875rem',\n display: 'flex',\n gap: '0.75rem',\n minHeight: '7rem',\n padding: '1.5rem',\n }}\n >\n <Button aria-label=\"Close\" shape=\"round\" size=\"icon-sm\" variant=\"overlay\">\n <PlusIcon />\n </Button>\n <Button aria-label=\"Play\" shape=\"round\" size=\"icon-lg\" variant=\"overlay\">\n <PlusIcon />\n </Button>\n <Button shape=\"round\" variant=\"overlay\">\n Follow\n </Button>\n </div>\n ),\n}\n\n/* Floating over a map: variant=\"raised\" with shape=\"round\" is the light\n floating button maps and light heroes use (back, locate, layers). The panel\n fill and a soft shadow lift it off a light picture; over dark media use\n overlay. The map is a placeholder with fixed light-map colors, as a real\n map tile would be. */\nexport const FloatingOverMap: Story = {\n render: () => (\n <div\n style={{\n backgroundColor: 'oklch(95% 0.02 95)',\n backgroundImage: [\n 'radial-gradient(circle at 72% 68%, oklch(88% 0.07 150) 0 18%, transparent 18.5%)',\n 'radial-gradient(ellipse at 12% 90%, oklch(86% 0.06 230) 0 22%, transparent 22.5%)',\n 'linear-gradient(28deg, transparent 47%, oklch(99% 0 0) 47% 51%, transparent 51%)',\n 'linear-gradient(118deg, transparent 58%, oklch(99% 0 0) 58% 60.5%, transparent 60.5%)',\n 'linear-gradient(90deg, transparent 30%, oklch(92% 0.06 85) 30% 32.5%, transparent 32.5%)',\n ].join(', '),\n borderRadius: '0.875rem',\n height: '22rem',\n maxWidth: '24rem',\n position: 'relative',\n }}\n >\n <div style={{ insetInlineStart: '1rem', position: 'absolute', top: '1rem' }}>\n <Button aria-label=\"Back\" shape=\"round\" size=\"icon-lg\" variant=\"raised\">\n <ChevronLeft />\n </Button>\n </div>\n <div\n style={{\n display: 'grid',\n gap: '0.75rem',\n insetInlineEnd: '1rem',\n position: 'absolute',\n top: '1rem',\n }}\n >\n <Button aria-label=\"Map layers\" shape=\"round\" size=\"icon-lg\" variant=\"raised\">\n <Layers />\n </Button>\n <Button aria-label=\"Show my location\" shape=\"round\" size=\"icon-lg\" variant=\"raised\">\n <LocateFixed />\n </Button>\n </div>\n <div\n style={{\n bottom: '1rem',\n display: 'flex',\n gap: '0.5rem',\n insetInlineStart: '1rem',\n position: 'absolute',\n }}\n >\n <Button shape=\"round\" variant=\"raised\">\n Search this area\n </Button>\n <Button disabled shape=\"round\" variant=\"raised\">\n Directions\n </Button>\n </div>\n </div>\n ),\n play: ({ canvasElement }) => {\n const button = canvasElement.querySelector<HTMLElement>('[aria-label=\"Back\"]')\n if (!button) throw new Error('Expected the Back button')\n const style = getComputedStyle(button)\n const { width, height } = button.getBoundingClientRect()\n if (Math.abs(width - height) > 0.5 || style.borderTopLeftRadius !== '9999px') {\n throw new Error(`Expected a circle, got ${width}x${height} / ${style.borderTopLeftRadius}`)\n }\n if (style.boxShadow === 'none' || !/\\dpx/.test(style.boxShadow)) {\n throw new Error(`Expected a soft shadow, got ${style.boxShadow}`)\n }\n if (style.borderTopColor !== 'rgba(0, 0, 0, 0)') {\n throw new Error(`Expected no visible border, got ${style.borderTopColor}`)\n }\n },\n}\n\nconst heroActions = [\n { icon: Plus, label: 'Add money' },\n { icon: ArrowRightLeft, label: 'Move' },\n { icon: Send, label: 'Send' },\n { icon: Ellipsis, label: 'More' },\n]\n\n/* A hero on --a63-gradient-brand-fade, which runs from the brand into the page.\n Overlay buttons and their on-media labels sit in the dark zone, the top\n --a63-gradient-brand-fade-dark-zone of the hero, where white keeps WCAG AA\n on every brand. Below it the hero fades into the page, so the content\n there uses the page tokens and the default button variants, on its own\n panel while the fade is still running. */\nexport const RoundOnBrandFade: Story = {\n render: () => (\n <div\n style={{\n backgroundImage: 'var(--a63-gradient-brand-fade)',\n borderRadius: '0.875rem',\n display: 'grid',\n gridTemplateRows: 'var(--a63-gradient-brand-fade-dark-zone) 1fr',\n height: '26rem',\n maxWidth: '24rem',\n }}\n >\n <div\n style={{\n alignContent: 'space-between',\n color: 'var(--a63-on-media-foreground)',\n display: 'grid',\n gap: 'var(--a63-space-4)',\n padding: 'var(--a63-space-5)',\n }}\n >\n <div>\n <div style={{ fontSize: 'var(--a63-type-footnote-font-size)' }}>Main account</div>\n <div\n style={{\n fontSize: 'var(--a63-type-large-title-font-size)',\n fontWeight: 'var(--a63-type-large-title-font-weight)',\n }}\n >\n £2,480.15\n </div>\n </div>\n <div style={{ display: 'flex', justifyContent: 'space-between' }}>\n {heroActions.map(({ icon: Icon, label }) => (\n <div\n key={label}\n style={{\n alignItems: 'center',\n display: 'grid',\n fontSize: 'var(--a63-type-footnote-font-size)',\n gap: 'var(--a63-space-1_5)',\n justifyItems: 'center',\n }}\n >\n <Button aria-label={label} shape=\"round\" size=\"icon-lg\" variant=\"overlay\">\n <Icon aria-hidden />\n </Button>\n <span aria-hidden>{label}</span>\n </div>\n ))}\n </div>\n </div>\n <div style={{ alignContent: 'end', display: 'grid', padding: 'var(--a63-space-3)' }}>\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: 'var(--a63-space-3)',\n padding: 'var(--a63-space-4)',\n }}\n >\n <p style={{ color: 'var(--a63-text-secondary)', margin: 0 }}>\n Below the dark zone the hero fades into the page. Content here uses the page tokens on\n its own panel, never overlay buttons or on-media text, which vanish as the hero fades.\n </p>\n <Button variant=\"outline\">See all transactions</Button>\n </div>\n </div>\n </div>\n ),\n}\n\n/* indicator: an unread dot (true) or a count, added to the accessible name. */\nexport const Indicator: Story = {\n render: () => (\n <EnvironmentShell>\n <div style={{ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '1rem' }}>\n <Button aria-label=\"Notifications\" indicator size=\"icon\" variant=\"ghost\">\n <Bell aria-hidden />\n </Button>\n <Button\n aria-label=\"Notifications\"\n indicator={3}\n shape=\"round\"\n size=\"icon\"\n variant=\"outline\"\n >\n <Bell aria-hidden />\n </Button>\n <Button aria-label=\"Notifications\" indicator={120} size=\"icon\">\n <Bell aria-hidden />\n </Button>\n <Button indicator={4} variant=\"outline\">\n <Inbox aria-hidden />\n Inbox\n </Button>\n </div>\n </EnvironmentShell>\n ),\n}\n\nexport const Shapes: Story = {\n render: () => (\n <EnvironmentShell>\n <div style={{ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '0.75rem' }}>\n {buttonShapes.map(shape => (\n <Button key={shape} shape={shape} variant=\"outline\">\n {shape}\n </Button>\n ))}\n <Button aria-label=\"Play\" shape=\"round\" size=\"icon\" variant=\"primary\">\n <PlusIcon />\n </Button>\n <Button aria-label=\"Add\" shape=\"round\" size=\"icon-sm\">\n <PlusIcon />\n </Button>\n <Button shape=\"round\" size=\"lg\" variant=\"primary\">\n Get started\n </Button>\n </div>\n </EnvironmentShell>\n ),\n}\n\n/* shape=\"round\" stays a circle at any size: an 88px play button, larger than\n the 56px where the soft --radius-full corner stops looking round. */\nexport const RoundLarge: Story = {\n render: () => (\n <EnvironmentShell>\n <Button\n aria-label=\"Play\"\n shape=\"round\"\n size=\"icon-xl\"\n style={{ '--button-height': '88px' } as CSSProperties}\n variant=\"primary\"\n >\n <PlusIcon />\n </Button>\n </EnvironmentShell>\n ),\n play: ({ canvasElement }) => {\n const button = canvasElement.querySelector<HTMLElement>('[data-shape=\"round\"]')\n const width = button?.getBoundingClientRect().width\n const radius = button && getComputedStyle(button).borderTopLeftRadius\n if (width !== 88 || radius !== '9999px') {\n throw new Error(`Expected an 88px button with a 9999px radius, got ${width}px / ${radius}`)\n }\n },\n}\n\nexport const Sizes: Story = {\n render: () => (\n <EnvironmentShell>\n <div style={{ alignItems: 'center', display: 'flex', flexWrap: 'wrap', gap: '0.75rem' }}>\n {buttonSizes.map(size => (\n <Button aria-label={size.startsWith('icon') ? 'Add' : undefined} key={size} size={size}>\n {size.startsWith('icon') ? <PlusIcon /> : size}\n </Button>\n ))}\n </div>\n </EnvironmentShell>\n ),\n}\n\n/* Tile size — full-width, icon-over-label; the launcher / app-grid shape ported\n from the legacy @atom63/ui button. Composes with any variant, and the caption\n wraps + stays centered. */\nexport const Tile: Story = {\n render: () => (\n <EnvironmentShell>\n <div style={{ display: 'grid', gap: '0.75rem', gridTemplateColumns: 'repeat(3, 1fr)' }}>\n <Button size=\"tile\" variant=\"outline\">\n <PlusIcon />\n New\n </Button>\n <Button size=\"tile\" variant=\"outline\">\n <PlusIcon />\n Import\n </Button>\n <Button size=\"tile\" variant=\"ghost\">\n <PlusIcon />A longer tile caption that wraps\n </Button>\n </div>\n </EnvironmentShell>\n ),\n}\n\nexport const States: Story = {\n render: () => (\n <EnvironmentShell>\n <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.75rem' }}>\n <Button>Default</Button>\n <Button loading>Loading</Button>\n <Button disabled>Disabled</Button>\n <Button disabled variant=\"primary\">\n Disabled primary\n </Button>\n <Button data-pressed=\"\">Pressed</Button>\n <Button variant=\"outline\">\n <PlusIcon />\n With icon\n </Button>\n </div>\n </EnvironmentShell>\n ),\n play: async ({ canvas, canvasElement }) => {\n // A disabled primary is a neutral fill with muted text, not a paler accent,\n // in every environment the shell renders.\n for (const button of canvas.getAllByRole('button', { name: 'Disabled primary' })) {\n // Paint a value next to the button, so it resolves in the button's environment.\n const paint = (property: 'backgroundColor' | 'color', value: string) => {\n const probe = canvasElement.ownerDocument.createElement('span')\n probe.style[property] = value\n button.after(probe)\n const painted = getComputedStyle(probe)[property]\n probe.remove()\n return painted\n }\n const style = getComputedStyle(button)\n // ui-react does not depend on storybook, so the checks throw plain errors.\n const background = paint('backgroundColor', 'var(--a63-action-disabled-background)')\n if (style.backgroundColor !== background) {\n throw new Error(`Disabled background ${style.backgroundColor}, expected ${background}`)\n }\n const color = paint('color', 'var(--a63-action-disabled-foreground)')\n if (style.color !== color) {\n throw new Error(`Disabled foreground ${style.color}, expected ${color}`)\n }\n if (style.backgroundColor === paint('backgroundColor', 'var(--a63-action-primary)')) {\n throw new Error('Disabled primary still uses the action-primary fill')\n }\n }\n },\n}\n\n/* Loading treatment across every variant. */\nexport const Loading: Story = {\n render: () => (\n <EnvironmentShell>\n <div style={{ display: 'grid', gap: '0.875rem' }}>\n <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.75rem' }}>\n {buttonVariants\n .filter(variant => variant !== 'overlay' && variant !== 'glass')\n .map(variant => (\n <Button key={variant} loading variant={variant}>\n {variant}\n </Button>\n ))}\n </div>\n <div\n style={{\n backgroundImage:\n 'linear-gradient(135deg, oklch(72% 0.16 250), oklch(64% 0.2 320) 55%, oklch(58% 0.18 30))',\n borderRadius: '0.875rem',\n display: 'flex',\n flexWrap: 'wrap',\n gap: '0.75rem',\n padding: '1.25rem',\n }}\n >\n <Button loading variant=\"overlay\">\n Overlay\n </Button>\n <Button loading variant=\"glass\">\n Glass\n </Button>\n <Button aria-label=\"Add\" loading size=\"icon\" variant=\"glass\">\n <PlusIcon />\n </Button>\n </div>\n </div>\n </EnvironmentShell>\n ),\n}\n\nexport const EnvironmentMatrix: Story = {\n parameters: {\n layout: 'fullscreen',\n },\n render: () => (\n <div\n style={{\n display: 'grid',\n gap: '1rem',\n gridTemplateColumns: 'repeat(auto-fit, minmax(19rem, 1fr))',\n padding: '1rem',\n }}\n >\n {designLanguages.map(designLanguage =>\n densities.map(density =>\n inputs.map(input => (\n <UIProvider\n density={density}\n designLanguage={designLanguage}\n input={input}\n key={`${designLanguage}-${density}-${input}`}\n mode=\"light\"\n >\n <PreviewCard label={`${designLanguage} / ${density} / ${input}`}>\n <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.75rem' }}>\n <Button>Continue</Button>\n <Button variant=\"ghost\">Maybe</Button>\n <Button variant=\"ghost\">Cancel</Button>\n </div>\n </PreviewCard>\n </UIProvider>\n ))\n )\n )}\n </div>\n ),\n}\n\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 flexWrap: 'wrap',\n gap: '0.5rem',\n padding: '0.75rem',\n }}\n >\n <span style={{ color: 'var(--a63-text-secondary)', fontSize: 12, width: 112 }}>\n {endpoint.label}\n </span>\n <Button variant=\"primary\">Primary</Button>\n <Button>Default</Button>\n <Button variant=\"outline\">Outline</Button>\n <Button variant=\"ghost\">Ghost</Button>\n <Button aria-label=\"Add\" size=\"icon\">\n <PlusIcon />\n </Button>\n </div>\n </UIProvider>\n ))}\n </div>\n ),\n}\n\nexport const BrandRamps: Story = {\n render: () => (\n <div\n style={{\n display: 'grid',\n gap: '1rem',\n gridTemplateColumns: 'repeat(auto-fit, minmax(11rem, 1fr))',\n }}\n >\n {brands.map(brand => (\n <UIProvider brand={brand} key={brand} mode=\"light\">\n <PreviewCard label={`brand / ${brand}`}>\n <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.5rem' }}>\n <Button variant=\"primary\">Primary</Button>\n <Button variant=\"outline\">Outline</Button>\n </div>\n </PreviewCard>\n </UIProvider>\n ))}\n </div>\n ),\n}\n\n/* Theme probe — the four skins x light/dark via the shared ThemeMatrix. */\nexport const Themes: Story = {\n parameters: { layout: 'fullscreen' },\n render: () => (\n <ThemeMatrix>\n <div style={{ display: 'grid', gap: '0.5rem' }}>\n <div style={{ display: 'flex', flexWrap: 'wrap', gap: '0.5rem' }}>\n <Button variant=\"primary\">Primary</Button>\n <Button>Default</Button>\n <Button variant=\"destructive\">Delete</Button>\n <Button variant=\"outline\">Outline</Button>\n <Button variant=\"ghost\">Ghost</Button>\n </div>\n <div\n style={{\n backgroundImage: 'linear-gradient(135deg, oklch(70% 0.16 250), oklch(60% 0.2 320))',\n borderRadius: '0.625rem',\n display: 'flex',\n flexWrap: 'wrap',\n gap: '0.5rem',\n padding: '0.75rem',\n }}\n >\n <Button variant=\"overlay\">Overlay</Button>\n <Button variant=\"glass\">Glass</Button>\n </div>\n </div>\n </ThemeMatrix>\n ),\n}\n\nexport const ContractMetadata: Story = {\n render: () => (\n <pre style={{ fontSize: 12, margin: 0, whiteSpace: 'pre-wrap' }}>\n {JSON.stringify(buttonContract, null, 2)}\n </pre>\n ),\n}\n"
213
213
  },
214
214
  "summary": "Button is the shared action primitive and defaults to safe non-submit behavior.",
215
215
  "usage": "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.",
@@ -5746,6 +5746,108 @@
5746
5746
  "Amount"
5747
5747
  ]
5748
5748
  },
5749
+ {
5750
+ "axisGuidance": null,
5751
+ "contract": {
5752
+ "archetypes": [
5753
+ {
5754
+ "description": "In-flow containers and content surfaces that do not inherently manipulate state.",
5755
+ "id": "surface",
5756
+ "label": "Static content surfaces"
5757
+ }
5758
+ ],
5759
+ "axes": [
5760
+ {
5761
+ "name": "layouts",
5762
+ "values": [
5763
+ "window",
5764
+ "phone"
5765
+ ],
5766
+ "default": "window"
5767
+ },
5768
+ {
5769
+ "name": "chromes",
5770
+ "values": [
5771
+ "inset",
5772
+ "flush"
5773
+ ],
5774
+ "default": "inset"
5775
+ },
5776
+ {
5777
+ "name": "topBarSpans",
5778
+ "values": [
5779
+ "window",
5780
+ "main"
5781
+ ],
5782
+ "default": "window"
5783
+ }
5784
+ ],
5785
+ "exportName": "appViewContract",
5786
+ "slots": [
5787
+ "app-view",
5788
+ "app-view-top-bar",
5789
+ "app-view-body",
5790
+ "app-view-rail",
5791
+ "app-view-panel",
5792
+ "app-view-content",
5793
+ "app-view-main",
5794
+ "app-view-overlay",
5795
+ "app-view-aside",
5796
+ "app-view-bottom-bar",
5797
+ "app-view-tab-bar"
5798
+ ],
5799
+ "source": "packages/ui-foundation/contracts/components/app-view.json",
5800
+ "states": [],
5801
+ "tokenSlots": []
5802
+ },
5803
+ "exports": {
5804
+ "types": [
5805
+ "AppViewProps"
5806
+ ],
5807
+ "values": [
5808
+ "AppView"
5809
+ ]
5810
+ },
5811
+ "group": {
5812
+ "id": "content-and-surfaces",
5813
+ "title": "Content and surfaces"
5814
+ },
5815
+ "guidance": [
5816
+ "Wrap a product view that has no site header or footer; pass layout=\"phone\" for a phone app screen. A window takes chrome=\"flush\" for columns to its edges, panelWidth for the side panel (18rem by default), and overlay for a control floating over the main region. For a multi-pane app, add rail (an icon column before the panel), aside (a thread or details pane after the main region, from lg up) and topBarSpan=\"main\" (the top bar starts after the panel, which runs full height).",
5817
+ "Keep product data and fetching outside the presentational component.",
5818
+ "Test long, empty, and narrow content before adding local layout overrides."
5819
+ ],
5820
+ "importPath": "@atom63/ui-react/layout",
5821
+ "label": "App View",
5822
+ "markdown": "# App View\n\nA full-window app frame: a top bar, an icon rail, a side panel, the scrolling main region, a details aside and docked bars, for a window or a phone screen.\n\n**Status:** Preview\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Wrap a product view that has no site header or footer; pass layout=\"phone\" for a phone app screen. A window takes chrome=\"flush\" for columns to its edges, panelWidth for the side panel (18rem by default), and overlay for a control floating over the main region. For a multi-pane app, add rail (an icon column before the panel), aside (a thread or details pane after the main region, from lg up) and topBarSpan=\"main\" (the top bar starts after the panel, which runs full height).\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 { AppView } from '@atom63/ui-react/layout'\n```\n\n## API surface\n\n**Values:** `AppView`\n\n**Types:** `AppViewProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/app-view.json` (`appViewContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `layouts` | `window`, `phone` | `window` |\n| `chromes` | `inset`, `flush` | `inset` |\n| `topBarSpans` | `window`, `main` | `window` |\n\n**Slots:** `app-view`, `app-view-top-bar`, `app-view-body`, `app-view-rail`, `app-view-panel`, `app-view-content`, `app-view-main`, `app-view-overlay`, `app-view-aside`, `app-view-bottom-bar`, `app-view-tab-bar`\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- [Sidebar](/components/component-sidebar)\n- [Tabs](/components/component-tabs)\n",
5823
+ "related": [
5824
+ "sidebar",
5825
+ "tabs"
5826
+ ],
5827
+ "route": "/components/component-app-view",
5828
+ "slug": "app-view",
5829
+ "status": "preview",
5830
+ "stories": {
5831
+ "file": "packages/ui-react/src/components/app-view/app-view.stories.tsx",
5832
+ "names": [
5833
+ "Playground",
5834
+ "Flush",
5835
+ "PhoneWithTabBar",
5836
+ "PhoneWithDockedBar",
5837
+ "PhoneWithOverlay",
5838
+ "WithRail",
5839
+ "WithAside",
5840
+ "TopBarOverMain",
5841
+ "RailPanelAndAside"
5842
+ ],
5843
+ "source": "import { Button, Item, ItemContent, ItemDescription, ItemGroup, ItemTitle } from '@atom63/ui-react'\nimport { AppView } from '@atom63/ui-react/layout'\nimport '@atom63/ui-react/styles.css'\nimport type { Meta, StoryObj } from '@storybook/react-vite'\nimport {\n ArrowDown,\n Bell,\n Hash,\n House,\n Inbox,\n Library,\n Play,\n Search,\n Settings,\n SkipForward,\n} from 'lucide-react'\n\nconst meta = {\n title: 'UI React/AppView',\n component: AppView,\n parameters: { layout: 'fullscreen' },\n} satisfies Meta<typeof AppView>\n\nexport default meta\ntype Story = StoryObj<typeof meta>\n\nconst tracks = Array.from({ length: 24 }, (_, index) => ({\n length: `${2 + (index % 3)}:${String(10 + ((index * 7) % 50)).padStart(2, '0')}`,\n title: `Track ${index + 1}`,\n}))\n\nfunction TrackList() {\n return (\n <ItemGroup>\n {tracks.map(track => (\n <Item key={track.title} size=\"sm\">\n <ItemContent>\n <ItemTitle>{track.title}</ItemTitle>\n <ItemDescription>{track.length}</ItemDescription>\n </ItemContent>\n </Item>\n ))}\n </ItemGroup>\n )\n}\n\nfunction TopBar() {\n return (\n <>\n <Button aria-label=\"Home\" size=\"icon\" tone=\"muted\" variant=\"ghost\">\n <House aria-hidden />\n </Button>\n <span className=\"font-semibold\">Library</span>\n <Button\n aria-label=\"Notifications\"\n className=\"ms-auto\"\n size=\"icon\"\n tone=\"muted\"\n variant=\"ghost\"\n >\n <Bell aria-hidden />\n </Button>\n </>\n )\n}\n\nfunction Player() {\n return (\n <>\n <div className=\"min-w-0 flex-1\">\n <p className=\"truncate text-sm font-medium\">First light</p>\n <p className=\"truncate text-xs text-muted-foreground\">Mara Vale</p>\n </div>\n <Button aria-label=\"Play\" size=\"icon\" variant=\"primary\">\n <Play aria-hidden />\n </Button>\n <Button aria-label=\"Next track\" size=\"icon\" tone=\"muted\" variant=\"ghost\">\n <SkipForward aria-hidden />\n </Button>\n </>\n )\n}\n\nfunction TabBar() {\n const tabs = [\n { icon: <House aria-hidden />, label: 'Home' },\n { icon: <Search aria-hidden />, label: 'Search' },\n { icon: <Library aria-hidden />, label: 'Library' },\n ]\n return (\n <nav aria-label=\"Main\" className=\"border-t border-border\">\n <ul className=\"flex\">\n {tabs.map(tab => (\n <li className=\"flex-1\" key={tab.label}>\n <a\n aria-current={tab.label === 'Library' ? 'page' : undefined}\n className=\"flex min-h-14 flex-col items-center justify-center gap-0.5 text-xs font-medium focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-ring\"\n href={`#${tab.label.toLowerCase()}`}\n >\n {tab.icon}\n {tab.label}\n </a>\n </li>\n ))}\n </ul>\n </nav>\n )\n}\n\nconst panel = (\n <ItemGroup>\n {['Morning rotation', 'Quiet hours', 'Late drive'].map(title => (\n <Item key={title} size=\"xs\">\n <ItemContent>\n <ItemTitle>{title}</ItemTitle>\n </ItemContent>\n </Item>\n ))}\n </ItemGroup>\n)\n\n/*\n * The frame's two promises, checked with emulated safe-area insets: the main\n * region scrolls and the frame around it does not, and each inset lands on\n * exactly one owner.\n */\nfunction checkFrame(\n canvasElement: HTMLElement,\n expected: { bottom: 'tab-bar' | 'bottom-bar' | 'main'; top: 'top-bar' | null }\n) {\n const root = canvasElement.querySelector<HTMLElement>('[data-slot=\"app-view\"]')\n if (!root) throw new Error('Expected the AppView root')\n const part = (slot: string) => root.querySelector<HTMLElement>(`[data-slot=\"app-view-${slot}\"]`)\n const insets = { bottom: '31px', inline: '13px', top: '29px' }\n root.style.setProperty('--a63-safe-area-top', insets.top)\n root.style.setProperty('--a63-safe-area-bottom', insets.bottom)\n root.style.setProperty('--a63-safe-area-left', insets.inline)\n root.style.setProperty('--a63-safe-area-right', insets.inline)\n try {\n const main = part('main')\n if (!main || main.scrollHeight <= main.clientHeight) {\n throw new Error('Expected the main region to overflow and scroll')\n }\n const scrollers = [root, ...root.querySelectorAll<HTMLElement>('*')].filter(element =>\n ['auto', 'scroll'].includes(getComputedStyle(element).overflowY)\n )\n const allowed = new Set([main, part('rail'), part('panel'), part('aside')])\n if (scrollers.some(element => !allowed.has(element)) || !scrollers.includes(main)) {\n throw new Error(`Expected only the main region (and the rail, panel and aside) to scroll`)\n }\n if (root.scrollHeight > root.clientHeight) throw new Error('Expected the frame not to scroll')\n\n const edges = ['top-bar', 'main', 'bottom-bar', 'tab-bar'] as const\n const owners = (property: 'paddingTop' | 'paddingBottom', value: string) =>\n edges.filter(slot => {\n const element = part(slot)\n return element ? getComputedStyle(element)[property] === value : false\n })\n const top = owners('paddingTop', insets.top)\n if (top.join() !== (expected.top ?? '')) {\n throw new Error(`Expected the top inset on ${expected.top ?? 'nothing'}, got ${top.join()}`)\n }\n const bottom = owners('paddingBottom', insets.bottom)\n if (bottom.join() !== expected.bottom) {\n throw new Error(`Expected the bottom inset on ${expected.bottom}, got ${bottom.join()}`)\n }\n const style = getComputedStyle(root)\n if (style.paddingInlineStart !== insets.inline || style.paddingInlineEnd !== insets.inline) {\n throw new Error('Expected the root to take the inline insets')\n }\n } finally {\n for (const edge of ['top', 'bottom', 'left', 'right']) {\n root.style.removeProperty(`--a63-safe-area-${edge}`)\n }\n }\n}\n\nfunction Rail() {\n const items = [\n { icon: <House aria-hidden />, label: 'Home' },\n { icon: <Inbox aria-hidden />, label: 'Inbox' },\n { icon: <Hash aria-hidden />, label: 'Channels' },\n { icon: <Settings aria-hidden />, label: 'Settings' },\n ]\n return (\n <nav aria-label=\"Workspace\" className=\"flex flex-col items-center gap-1\">\n {items.map(item => (\n <Button aria-label={item.label} key={item.label} size=\"icon\" tone=\"muted\" variant=\"ghost\">\n {item.icon}\n </Button>\n ))}\n </nav>\n )\n}\n\nconst thread = (\n <ItemGroup>\n {['Reply from Ada', 'Reply from Lin', 'Reply from Sam'].map(title => (\n <Item key={title} size=\"sm\">\n <ItemContent>\n <ItemTitle>{title}</ItemTitle>\n <ItemDescription>Sounds good, shipping it today.</ItemDescription>\n </ItemContent>\n </Item>\n ))}\n </ItemGroup>\n)\n\n/* A desktop window: a top bar, a side panel and the main region on rounded cards, and a docked player. */\nexport const Playground: Story = {\n args: {\n bottomBar: <Player />,\n children: <TrackList />,\n panel,\n topBar: <TopBar />,\n },\n play: ({ canvasElement }) => checkFrame(canvasElement, { bottom: 'bottom-bar', top: 'top-bar' }),\n}\n\n/* chrome=\"flush\": the columns run to the window edges, split by borders. */\nexport const Flush: Story = {\n args: { ...Playground.args, chrome: 'flush' },\n play: ({ canvasElement }) => checkFrame(canvasElement, { bottom: 'bottom-bar', top: 'top-bar' }),\n}\n\n/* A phone screen with a top bar and the tab bar: the tab bar takes the bottom inset. */\nexport const PhoneWithTabBar: Story = {\n args: {\n children: <TrackList />,\n layout: 'phone',\n tabBar: <TabBar />,\n topBar: <TopBar />,\n },\n play: ({ canvasElement }) => checkFrame(canvasElement, { bottom: 'tab-bar', top: 'top-bar' }),\n}\n\n/*\n * A phone screen with no top bar and a docked bar: the content reaches the top\n * edge (its first block pads itself), and the docked bar takes the bottom inset.\n */\nexport const PhoneWithDockedBar: Story = {\n args: {\n bottomBar: <Player />,\n children: <TrackList />,\n layout: 'phone',\n },\n play: ({ canvasElement }) => checkFrame(canvasElement, { bottom: 'bottom-bar', top: null }),\n}\n\n/*\n * A phone screen with a docked bar, the tab bar and an overlay: the overlay\n * floats over the end of the main region, above the docked bar, and does not scroll.\n */\nexport const PhoneWithOverlay: Story = {\n args: {\n bottomBar: <Player />,\n children: <TrackList />,\n layout: 'phone',\n overlay: (\n <Button aria-label=\"Scroll to the bottom\" shape=\"round\" size=\"icon\" variant=\"raised\">\n <ArrowDown aria-hidden />\n </Button>\n ),\n tabBar: <TabBar />,\n topBar: <TopBar />,\n },\n play: ({ canvasElement }) => checkFrame(canvasElement, { bottom: 'tab-bar', top: 'top-bar' }),\n}\n\n/* rail: an icon column before the side panel, from md up. */\nexport const WithRail: Story = {\n args: { ...Playground.args, rail: <Rail /> },\n play: ({ canvasElement }) => checkFrame(canvasElement, { bottom: 'bottom-bar', top: 'top-bar' }),\n}\n\n/* aside: a details pane after the main region, from lg up. */\nexport const WithAside: Story = {\n args: { ...Playground.args, aside: thread, asideLabel: 'Thread' },\n play: ({ canvasElement }) => checkFrame(canvasElement, { bottom: 'bottom-bar', top: 'top-bar' }),\n}\n\n/* topBarSpan=\"main\": the top bar starts after the panel, which runs the full height. */\nexport const TopBarOverMain: Story = {\n args: { ...Playground.args, chrome: 'flush', topBarSpan: 'main' },\n play: ({ canvasElement }) => checkFrame(canvasElement, { bottom: 'bottom-bar', top: 'top-bar' }),\n}\n\n/* All of it, as in a team chat: a workspace rail, channels, the conversation and a thread. */\nexport const RailPanelAndAside: Story = {\n args: {\n aside: thread,\n asideLabel: 'Thread',\n chrome: 'flush',\n children: <TrackList />,\n panel,\n panelLabel: 'Channels',\n rail: <Rail />,\n topBar: <TopBar />,\n topBarSpan: 'main',\n },\n play: ({ canvasElement }) => checkFrame(canvasElement, { bottom: 'main', top: 'top-bar' }),\n}\n"
5844
+ },
5845
+ "summary": "A full-window app frame: a top bar, an icon rail, a side panel, the scrolling main region, a details aside and docked bars, for a window or a phone screen.",
5846
+ "usage": "Wrap a product view that has no site header or footer; pass layout=\"phone\" for a phone app screen. A window takes chrome=\"flush\" for columns to its edges, panelWidth for the side panel (18rem by default), and overlay for a control floating over the main region. For a multi-pane app, add rail (an icon column before the panel), aside (a thread or details pane after the main region, from lg up) and topBarSpan=\"main\" (the top bar starts after the panel, which runs full height).",
5847
+ "usageExports": [
5848
+ "AppView"
5849
+ ]
5850
+ },
5749
5851
  {
5750
5852
  "axisGuidance": null,
5751
5853
  "contract": {
@@ -5765,6 +5867,13 @@
5765
5867
  "group"
5766
5868
  ]
5767
5869
  },
5870
+ {
5871
+ "name": "rings",
5872
+ "values": [
5873
+ "unseen",
5874
+ "seen"
5875
+ ]
5876
+ },
5768
5877
  {
5769
5878
  "name": "shapes",
5770
5879
  "values": [
@@ -5856,7 +5965,7 @@
5856
5965
  ],
5857
5966
  "importPath": "@atom63/ui-react",
5858
5967
  "label": "Avatar",
5859
- "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| `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",
5968
+ "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",
5860
5969
  "related": [
5861
5970
  "badge",
5862
5971
  "item"
@@ -5872,6 +5981,7 @@
5872
5981
  "IconFallback",
5873
5982
  "LargeCircle",
5874
5983
  "ShapesAndRing",
5984
+ "StoryRings",
5875
5985
  "Fallback",
5876
5986
  "WithBadge",
5877
5987
  "Group",
@@ -5879,7 +5989,7 @@
5879
5989
  "Endpoints",
5880
5990
  "ContractMetadata"
5881
5991
  ],
5882
- "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/* 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"
5992
+ "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"
5883
5993
  },
5884
5994
  "summary": "Avatar composes an image, fallback, badge, and grouped identity presentation.",
5885
5995
  "usage": "Provide meaningful image alternative text and a stable fallback for failed or missing media.",
@@ -7316,6 +7426,142 @@
7316
7426
  "ItemActions"
7317
7427
  ]
7318
7428
  },
7429
+ {
7430
+ "axisGuidance": null,
7431
+ "contract": {
7432
+ "archetypes": [
7433
+ {
7434
+ "description": "In-flow containers and content surfaces that do not inherently manipulate state.",
7435
+ "id": "surface",
7436
+ "label": "Static content surfaces"
7437
+ }
7438
+ ],
7439
+ "axes": [
7440
+ {
7441
+ "name": "directions",
7442
+ "values": [
7443
+ "incoming",
7444
+ "outgoing"
7445
+ ],
7446
+ "default": "incoming"
7447
+ },
7448
+ {
7449
+ "name": "positions",
7450
+ "values": [
7451
+ "single",
7452
+ "first",
7453
+ "middle",
7454
+ "last"
7455
+ ],
7456
+ "default": "single"
7457
+ },
7458
+ {
7459
+ "name": "deliveryStates",
7460
+ "values": [
7461
+ "sending",
7462
+ "sent",
7463
+ "delivered",
7464
+ "read",
7465
+ "failed"
7466
+ ]
7467
+ }
7468
+ ],
7469
+ "crossRenderer": {
7470
+ "accessibilityOutcomes": [
7471
+ "names-the-sender",
7472
+ "names-the-delivery-status"
7473
+ ],
7474
+ "intent": "Show one message between people as a bubble on its sender's side, joined to the messages around it from the same sender, with its time and delivery status.",
7475
+ "parity": "strict",
7476
+ "platformAdaptations": {
7477
+ "react": [
7478
+ "MessageList is a log region; Message is an article named by label (the sender), with logical corner radii so a thread mirrors in right-to-left scripts.",
7479
+ "Outgoing bubbles read --a63-message-outgoing-background and -foreground, which default to the accent; a theme or a product can set them."
7480
+ ],
7481
+ "swiftUI": [
7482
+ "AtomMessage takes direction, position, time and status; AtomMessageEvent is the centred row. The bubble uses UnevenRoundedRectangle for the joined corners.",
7483
+ "The status icon is an SF Symbol with an accessibility label; the bubble combines its children into one VoiceOver element."
7484
+ ]
7485
+ },
7486
+ "requiredStates": [
7487
+ "rest"
7488
+ ],
7489
+ "sharedOutcomes": [
7490
+ "direction-sets-side-and-fill",
7491
+ "runs-join-at-shared-corners",
7492
+ "status-is-named"
7493
+ ],
7494
+ "swiftUIRenderer": "AtomMessage"
7495
+ },
7496
+ "exportName": "messageContract",
7497
+ "slots": [
7498
+ "message-list",
7499
+ "message",
7500
+ "message-avatar",
7501
+ "message-bubble",
7502
+ "message-media",
7503
+ "message-content",
7504
+ "message-meta",
7505
+ "message-status",
7506
+ "message-event"
7507
+ ],
7508
+ "source": "packages/ui-foundation/contracts/components/message.json",
7509
+ "states": [
7510
+ "rest"
7511
+ ],
7512
+ "tokenSlots": []
7513
+ },
7514
+ "exports": {
7515
+ "types": [
7516
+ "MessageEventProps",
7517
+ "MessageListProps",
7518
+ "MessageProps"
7519
+ ],
7520
+ "values": [
7521
+ "Message",
7522
+ "MessageEvent",
7523
+ "MessageList"
7524
+ ]
7525
+ },
7526
+ "group": {
7527
+ "id": "content-and-surfaces",
7528
+ "title": "Content and surfaces"
7529
+ },
7530
+ "guidance": [
7531
+ "Wrap the thread in MessageList (a named log region). Pass direction (incoming or outgoing), position in the run of one sender (single, first, middle, last), time and, for your own messages, status. Use MessageEvent for calls and dates, Avatar ring for stories, and ChatMessage instead for an AI assistant.",
7532
+ "Keep product data and fetching outside the presentational component.",
7533
+ "Test long, empty, and narrow content before adding local layout overrides."
7534
+ ],
7535
+ "importPath": "@atom63/ui-react",
7536
+ "label": "Message",
7537
+ "markdown": "# Message\n\nMessage shows one message in a thread between people: a bubble on its sender's side, joined to the messages around it, with its time and delivery status. For an AI assistant, use ChatMessage.\n\n**Status:** Preview\n\n## Preview\n\nThe live documentation page renders the `Playground` story maintained with the component.\n\n## Guidance\n\n- Wrap the thread in MessageList (a named log region). Pass direction (incoming or outgoing), position in the run of one sender (single, first, middle, last), time and, for your own messages, status. Use MessageEvent for calls and dates, Avatar ring for stories, and ChatMessage instead for an AI assistant.\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 { Message, MessageList, MessageEvent } from '@atom63/ui-react'\n```\n\n## API surface\n\n**Values:** `Message`, `MessageEvent`, `MessageList`\n\n**Types:** `MessageEventProps`, `MessageListProps`, `MessageProps`\n\nTypeScript remains the source of truth for complete prop contracts.\n\n## Contract\n\nSource: `packages/ui-foundation/contracts/components/message.json` (`messageContract` in `@atom63/ui-foundation`).\n\n| Axis | Values | Default |\n| --- | --- | --- |\n| `directions` | `incoming`, `outgoing` | `incoming` |\n| `positions` | `single`, `first`, `middle`, `last` | `single` |\n| `deliveryStates` | `sending`, `sent`, `delivered`, `read`, `failed` | — |\n\n**Slots:** `message-list`, `message`, `message-avatar`, `message-bubble`, `message-media`, `message-content`, `message-meta`, `message-status`, `message-event`\n\n**States:** `rest`\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\nShow one message between people as a bubble on its sender's side, joined to the messages around it from the same sender, with its time and delivery status. Rendered by `AtomMessage` in SwiftUI, with `strict` parity.\n\n**Required states:** `rest`\n\n**Shared outcomes:**\n\n- Direction sets side and fill\n- Runs join at shared corners\n- Status is named\n\n**Accessibility outcomes:**\n\n- Names the sender\n- Names the delivery status\n\n**Platform adaptations:**\n\n- React: MessageList is a log region; Message is an article named by label (the sender), with logical corner radii so a thread mirrors in right-to-left scripts.\n- React: Outgoing bubbles read --a63-message-outgoing-background and -foreground, which default to the accent; a theme or a product can set them.\n- SwiftUI: AtomMessage takes direction, position, time and status; AtomMessageEvent is the centred row. The bubble uses UnevenRoundedRectangle for the joined corners.\n- SwiftUI: The status icon is an SF Symbol with an accessibility label; the bubble combines its children into one VoiceOver element.\n\n## Related components\n\n- [Chat Message](/components/component-chat-message)\n- [Avatar](/components/component-avatar)\n",
7538
+ "related": [
7539
+ "chat-message",
7540
+ "avatar"
7541
+ ],
7542
+ "route": "/components/component-message",
7543
+ "slug": "message",
7544
+ "status": "preview",
7545
+ "stories": {
7546
+ "file": "packages/ui-react/src/components/message/message.stories.tsx",
7547
+ "names": [
7548
+ "Playground",
7549
+ "Thread",
7550
+ "DeliveryStates",
7551
+ "Media",
7552
+ "LongContent",
7553
+ "Themes"
7554
+ ],
7555
+ "source": "import {\n messageDeliveryStates,\n messageDirections,\n messagePositions,\n themes,\n} from '@atom63/ui-foundation'\nimport {\n Avatar,\n AvatarFallback,\n Message,\n MessageEvent,\n MessageList,\n UIProvider,\n} from '@atom63/ui-react'\nimport '@atom63/ui-react/styles.css'\nimport type { Meta, StoryObj } from '@storybook/react-vite'\nimport { PhoneMissed } from 'lucide-react'\n\nconst meta = {\n title: 'UI React/Message',\n component: Message,\n argTypes: {\n direction: { control: 'inline-radio', options: messageDirections },\n position: { control: 'inline-radio', options: messagePositions },\n status: { control: 'select', options: [undefined, ...messageDeliveryStates] },\n },\n args: {\n children: 'Are we still on for Saturday?',\n direction: 'incoming',\n label: 'Ada',\n position: 'single',\n time: '12:04',\n },\n} satisfies Meta<typeof Message>\n\nexport default meta\ntype Story = StoryObj<typeof meta>\n\nconst ada = (\n <Avatar size=\"sm\">\n <AvatarFallback>AD</AvatarFallback>\n </Avatar>\n)\n\nconst Frame = ({ children }: { children: React.ReactNode }) => (\n <div style={{ maxWidth: 390, margin: '0 auto' }}>{children}</div>\n)\n\nexport const Playground: Story = {\n render: args => (\n <Frame>\n <MessageList aria-label=\"Messages with Ada\">\n <Message {...args} />\n </MessageList>\n </Frame>\n ),\n}\n\n/* A thread: runs of consecutive messages join at their shared corners, and only the last shows the avatar and the tail. */\nexport const Thread: Story = {\n render: () => (\n <Frame>\n <MessageList aria-label=\"Messages with Ada\">\n <MessageEvent>Today</MessageEvent>\n <Message avatar={ada} label=\"Ada\" position=\"first\" time=\"12:01\">\n Hey!\n </Message>\n <Message avatar={ada} label=\"Ada\" position=\"middle\" time=\"12:01\">\n Are we still on for Saturday?\n </Message>\n <Message avatar={ada} label=\"Ada\" position=\"last\" time=\"12:02\">\n I can bring the tent.\n </Message>\n <Message direction=\"outgoing\" label=\"You\" position=\"first\" status=\"read\" time=\"12:04\">\n Yes, 9am at the station\n </Message>\n <Message direction=\"outgoing\" label=\"You\" position=\"last\" status=\"delivered\" time=\"12:04\">\n Bring snacks too 🙂\n </Message>\n <MessageEvent icon={<PhoneMissed />}>Missed voice call · 12:10</MessageEvent>\n <Message avatar={ada} label=\"Ada\" time=\"12:12\">\n Sorry, was driving. Call you later?\n </Message>\n <Message direction=\"outgoing\" label=\"You\" status=\"sending\" time=\"12:13\">\n Sure\n </Message>\n </MessageList>\n </Frame>\n ),\n}\n\n/* Every delivery status of an outgoing message, each named for assistive technology. */\nexport const DeliveryStates: Story = {\n render: () => (\n <Frame>\n <MessageList aria-label=\"Delivery states\">\n {messageDeliveryStates.map(status => (\n <Message direction=\"outgoing\" key={status} label=\"You\" status={status} time=\"12:04\">\n {status}\n </Message>\n ))}\n </MessageList>\n </Frame>\n ),\n}\n\n/* A photo message: the media takes the bubble's corners, with an optional caption. */\nexport const Media: Story = {\n render: () => (\n <Frame>\n <MessageList aria-label=\"Photos\">\n <Message\n avatar={ada}\n label=\"Ada\"\n media={\n <div\n aria-label=\"Photo of the campsite\"\n role=\"img\"\n style={{ aspectRatio: '4 / 3', background: 'var(--a63-category-teal)' }}\n />\n }\n time=\"12:20\"\n >\n The view from the campsite\n </Message>\n <Message\n direction=\"outgoing\"\n label=\"You\"\n media={\n <div\n aria-label=\"Photo of the trail\"\n role=\"img\"\n style={{ aspectRatio: '1', background: 'var(--a63-category-green)' }}\n />\n }\n status=\"read\"\n time=\"12:21\"\n />\n </MessageList>\n </Frame>\n ),\n}\n\n/* A long word or link wraps inside the bubble instead of widening the thread. */\nexport const LongContent: Story = {\n render: () => (\n <Frame>\n <MessageList aria-label=\"Long content\">\n <Message label=\"Ada\" time=\"12:30\">\n https://example.com/a/very/long/link/that/should/wrap/inside/the/bubble/without/overflowing\n </Message>\n <Message direction=\"outgoing\" label=\"You\" status=\"read\" time=\"12:31\">\n Got it — I will read the whole thing tonight and send you my notes before we leave on\n Saturday morning.\n </Message>\n </MessageList>\n </Frame>\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 style={{ background: 'var(--a63-surface-page)', padding: '0.75rem' }}>\n <MessageList aria-label={`${theme} ${mode}`}>\n <Message label=\"Ada\" time=\"12:04\">\n {theme} / {mode}\n </Message>\n <Message direction=\"outgoing\" label=\"You\" status=\"read\" time=\"12:05\">\n Outgoing in the accent\n </Message>\n </MessageList>\n </div>\n </UIProvider>\n ))\n )}\n </div>\n ),\n}\n"
7556
+ },
7557
+ "summary": "Message shows one message in a thread between people: a bubble on its sender's side, joined to the messages around it, with its time and delivery status. For an AI assistant, use ChatMessage.",
7558
+ "usage": "Wrap the thread in MessageList (a named log region). Pass direction (incoming or outgoing), position in the run of one sender (single, first, middle, last), time and, for your own messages, status. Use MessageEvent for calls and dates, Avatar ring for stories, and ChatMessage instead for an AI assistant.",
7559
+ "usageExports": [
7560
+ "Message",
7561
+ "MessageList",
7562
+ "MessageEvent"
7563
+ ]
7564
+ },
7319
7565
  {
7320
7566
  "axisGuidance": null,
7321
7567
  "contract": {
@@ -8889,7 +9135,7 @@
8889
9135
  {
8890
9136
  "area": "foundations",
8891
9137
  "label": "Typography",
8892
- "markdown": "# Typography\n\nThe type system targets dense information interfaces rather than marketing pages. Body text starts at 15px—between compact 14px UI conventions and the browser's 16px default—to balance information density with sustained reading.\n\n## Design intent\n\nI wanted a scale that serves three very different surfaces from the same tokens: portfolio pages with expressive display type, documentation with dense readable prose, and app panels with compact controls. The solution is one responsive scale plus an independent `--typography-scale` multiplier that any subtree can adjust.\n\nThe shipped scale is deliberately not fluid. It uses viewport breakpoints for pages and `data-window-size` overrides for OS windows, so a constrained window can use its own size band even on a wide viewport. The separate `data-a63-type-scale` axis adjusts the whole ramp for user preference.\n\n## Font families\n\n| CSS variable | Tailwind | Stack |\n|--------------|----------|-------|\n| `--font-family-sans` | `font-sans` | Geist, system UI |\n| `--font-family-serif` | `font-serif` | Brawler, Georgia |\n| `--font-family-mono` | `font-mono` | Geist Mono, monospace |\n\nI chose Geist because it's optimized for interfaces — generous x-height, clear at small sizes, and a mono companion that shares the same metrics. Brawler is reserved for rare editorial moments in the portfolio; the system defaults to sans everywhere.\n\n## How the scale works\n\nSixteen steps from `2xs` (11px) to `11xl` (56px). Up to `9xl` (39px at mobile, 49px at `768px+`) the scale grows at `640px` and `768px`, and `[data-window-size='xs'|'sm'|'md'|'lg'|'xl']` applies the same bands inside OS windows; the two display steps, `10xl` (40px) and `11xl` (56px), stay the same at every width.\n\n## Mental model\n\nTypography has three separate jobs:\n\n| Job | What it controls | Examples |\n|-----|------------------|----------|\n| Reading | Long-form comfort | Prose, docs, descriptions |\n| Hierarchy | Relative importance | Page titles, section headers, labels |\n| Density | How much interface fits | Sidebars, tables, controls, OS windows |\n\nDo not solve all three with one heading scale. A docs page, a compact sidebar, and a portfolio hero need different hierarchy even when they share the same tokens.\n\n### Line-height strategy\n\nBody text (`xs` through `lg`) uses a ~1.5× ratio for comfortable reading. Display sizes (`xl` and above) compress to ~1.25× — tighter line-height at large sizes prevents headings from floating away from their content.\n\n### The scale multiplier\n\n`--typography-scale` defaults to `1`. The shipped `data-a63-type-scale` values map to `0.9` (`compact`), `1` (`normal`), `1.1` (`comfortable`), and `1.2` (`large`). OS window width is handled separately by `data-window-size`; the multiplier is a personalization control, not the window breakpoint mechanism.\n\n## Decisions worth knowing\n\n### 15px base, not 16px\n\nMost systems use 16px because browsers default to it. I chose 15px after testing information-dense layouts — docs tables, prop references, sidebar navigation. At 16px, content felt loose and wasted space. At 14px, extended reading got fatiguing. 15px is the sweet spot for my use cases: dense enough for tool interfaces, comfortable enough for documentation prose.\n\nText without a size class takes the body role too, not the browser's 16px. `@atom63/styles` sets `--a63-type-body-font-size` and `--a63-type-body-line-height` (15/23) on `body` and on a phone scope (17/22 there), and the `@atom63/ui-react` reset sets them on `Atom63Theme` and `UIProvider`. `html` keeps the browser size, so `1rem` stays 16px and every rem-based token is unchanged. Set a size class or a text role where text should be smaller, such as `text-sm` in a dense table.\n\n### Breakpoints over fluid\n\nFluid typography (`clamp()`) assumes the viewport is the right proxy for text size. In the OS metaphor, multiple windows have arbitrary widths on one screen. Breakpoint jumps plus `data-window-size` attributes let window content follow its container band instead of the outer viewport.\n\n### No heading-element-to-scale mapping in CSS\n\nI don't automatically map `h1` to `9xl` or `h2` to `8xl` in the base tokens. Different surfaces need different heading scales — a docs `h2` should be smaller than a portfolio `h2`. The MDX variants handle heading sizing per context, and the raw scale stays available for explicit use via `text-*` utilities.\n\n### Visual hierarchy and semantics are separate\n\nA semantic `h2` does not always need to look like the second-largest text on the page. The `SectionHeader` pattern follows this rule: `variant` controls visual scale, while `level` can control document outline. That keeps accessibility and visual rhythm from fighting each other.\n\n## Text roles\n\nText roles name what text is for, after the Apple HIG text styles, so one intent works on every platform. Each role picks a step of the scale on the web and a `Font.TextStyle` (with Dynamic Type) on iOS. The source is `packages/styles/src/tokens/type-roles.resolver.json`; each role has `--a63-type-<role>-font-size`, `-line-height`, `-font-weight` and `-font-weight-strong`, and the Tailwind utilities `text-<role>` and `text-<role>-strong` set all three at once.\n\n| Role | Web step | iOS text style |\n|------|----------|----------------|\n| `display-large` | `11xl`, weight 600 | 56pt, scaled like `largeTitle` |\n| `display` | `10xl`, weight 600 | 40pt, scaled like `largeTitle` |\n| `large-title` | `6xl` | `largeTitle` |\n| `title-1` | `5xl` | `title` |\n| `title-2` | `3xl` | `title2` |\n| `title-3` | `2xl` | `title3` |\n| `headline` | `base`, weight 600 | `headline` |\n| `body` | `base` | `body` |\n| `callout` | `base` | `callout` |\n| `subhead` | `sm` | `subheadline` |\n| `footnote` | `xs` | `footnote` |\n| `caption-1` | `xs` | `caption` |\n| `caption-2` | `2xs` | `caption2` |\n\n`-strong` is the emphasized weight: bold for the display roles, `large-title`, `title-1` and `title-2`, semibold for the rest. The display roles are for balances, prices and hero headlines; iOS has no larger text style, so `AtomDisplayRole` draws them at the web size and scales it with Dynamic Type like `largeTitle`. For an amount such as `$13.25`, use `Amount` from `@atom63/ui-react` (`<Amount value={13.25} currency=\"USD\" />`, `size=\"lg\"` for `display-large`): it formats the value for the locale with `Intl.NumberFormat`, draws the fraction at half size and raised with tabular figures, and reads as one label. `fraction=\"baseline\"` keeps the half-size fraction on the baseline of the integer digits instead, as some banking apps draw a balance; `raised` is the default. Without the component, put the whole number in one `text-display tabular-nums` span and wrap the fraction in `amount-fraction`, which sets it at half size and raises it, or in `amount-fraction-baseline`, which sets it at half size on the baseline. On iOS, `AtomAmountText(13.25, currencyCode: \"USD\", role: .display)` formats the amount for the locale, draws the fraction the same way with monospaced digits and reads as one VoiceOver label, and `fraction: .baseline` keeps it on the baseline; `.atomDisplayFont()` sets a display role on any other text. Web sizes follow web conventions (body is 15px; iOS body is 17pt); the role is what stays the same. Size steps are fine while exploring; settled UI should use roles.\n\n## Phone screens\n\nThe web scale is set for pages and desktop apps: body is 15px and compact control labels are 12–13px. A phone app screen reads at the iOS sizes instead, so `[data-a63-form-factor=\"phone\"]` gives a subtree the type steps and control sizing of a phone. `AppView layout=\"phone\"` (the app-view page template) stamps it on the screen; stamp it yourself on the root of a phone-only web app. Viewport width does not apply it, so a docs page or a marketing page on a phone keeps the web sizes.\n\n| Role | Web, under 640px | Phone (`data-a63-form-factor=\"phone\"`) | iOS text style |\n|------|------------------|-----------------------------------------|----------------|\n| `body`, `headline`, `callout` | 15px | 17px | `body` 17pt |\n| `subhead` | 13px | 15px | `subheadline` 15pt |\n| `footnote`, `caption-1` | 12px | 13px | `footnote` 13pt |\n| `caption-2` | 11px | 11px | `caption2` 11pt |\n| `title-3` | 19px | 20px | `title3` 20pt |\n| `title-2` | 21px | 22px | `title2` 22pt |\n| `title-1` | 26px | 28px | `title` 28pt |\n| `large-title` | 28px | 34px | `largeTitle` 34pt |\n| `display`, `display-large` | 40px, 56px | 40px, 56px | `AtomDisplayRole` |\n\nThe scope sets the steps themselves (`text-sm` is 15px and `text-base` 17px inside it), redeclares the text roles, and sizes controls the iOS way: heights of 36, 40, 44, 48 and 52px, and every standard control label (buttons, rows, fields, menus) at body size, with `xs` at footnote size for badges, shortcuts and initials. A Switch takes the iOS 26 shape: a pill knob 1.6 times as wide as it is tall (`--a63-switch-thumb-aspect`) on a track of about 63 by 28px. A grouped list (`ItemGroup variant=\"inset\"`) takes the iOS 26 Settings rows: its default and `sm` rows, static or interactive, are at least 52px tall (`--a63-inset-row-min-size`), so a 17px label sits in about 15px of space above and below, and the card has the `2xl` corner, 18px at defaults (`--a63-inset-group-radius`). Outside the phone scope neither variable is declared, and the group keeps its control-height rows and `--radius-lg` corner. The secondary line under a title or label (an Item, Field or Form description, a Frame or ConnectedPanel description) reads `--a63-control-font-size-secondary`, which the phone scope sets to subhead size (15px) so it stays below its 17px title; elsewhere it falls back to the control `sm` size. The type scale preference still multiplies the phone steps. Inside a phone screen, keep rows and labels on the component defaults or the text roles; shrinking them with `text-sm` or `text-xs` brings back the desktop sizes.\n\n## Usage guidance\n\n| Surface | Typical range | Scale multiplier |\n|---------|---------------|------------------|\n| Portfolio hero | `4xl`–`9xl` | Usually `normal`; user preference still applies |\n| Documentation prose | `sm`–`xl` | `1` |\n| App panels / OS windows | `xs`–`lg` | Window-size band + active type-scale axis |\n| Code blocks | `sm` mono | `1` |\n\n## Anti-patterns\n\n```tsx\n// Avoid: viewport-sized type inside a constrained panel.\n```\n\nThe panel is narrow even if the viewport is wide. The text should respond to the container's role, not the browser width.\n\n```tsx\n// Prefer: choose a scale for the surface.\n```\n\n## Review checklist\n\nWhen reviewing typography, ask:\n\n1. Is this text sized for its container, not only the viewport?\n2. Does the hierarchy still work if the content wraps?\n3. Is the line-height comfortable for the amount of reading?\n4. Are semantic heading levels valid independent of visual size?\n5. Is display type reserved for display moments?",
9138
+ "markdown": "# Typography\n\nThe type system targets dense information interfaces rather than marketing pages. Body text starts at 15px—between compact 14px UI conventions and the browser's 16px default—to balance information density with sustained reading.\n\n## Design intent\n\nI wanted a scale that serves three very different surfaces from the same tokens: portfolio pages with expressive display type, documentation with dense readable prose, and app panels with compact controls. The solution is one responsive scale plus an independent `--typography-scale` multiplier that any subtree can adjust.\n\nThe shipped scale is deliberately not fluid. It uses viewport breakpoints for pages and `data-window-size` overrides for OS windows, so a constrained window can use its own size band even on a wide viewport. The separate `data-a63-type-scale` axis adjusts the whole ramp for user preference.\n\n## Font families\n\n| CSS variable | Tailwind | Stack |\n|--------------|----------|-------|\n| `--font-family-sans` | `font-sans` | Geist, system UI |\n| `--font-family-serif` | `font-serif` | Brawler, Georgia |\n| `--font-family-mono` | `font-mono` | Geist Mono, monospace |\n\nI chose Geist because it's optimized for interfaces — generous x-height, clear at small sizes, and a mono companion that shares the same metrics. Brawler is reserved for rare editorial moments in the portfolio; the system defaults to sans everywhere.\n\n## How the scale works\n\nSixteen steps from `2xs` (11px) to `11xl` (56px). Up to `9xl` (39px at mobile, 49px at `768px+`) the scale grows at `640px` and `768px`, and `[data-window-size='xs'|'sm'|'md'|'lg'|'xl']` applies the same bands inside OS windows; the two display steps, `10xl` (40px) and `11xl` (56px), stay the same at every width.\n\n## Mental model\n\nTypography has three separate jobs:\n\n| Job | What it controls | Examples |\n|-----|------------------|----------|\n| Reading | Long-form comfort | Prose, docs, descriptions |\n| Hierarchy | Relative importance | Page titles, section headers, labels |\n| Density | How much interface fits | Sidebars, tables, controls, OS windows |\n\nDo not solve all three with one heading scale. A docs page, a compact sidebar, and a portfolio hero need different hierarchy even when they share the same tokens.\n\n### Line-height strategy\n\nBody text (`xs` through `lg`) uses a ~1.5× ratio for comfortable reading. Display sizes (`xl` and above) compress to ~1.25× — tighter line-height at large sizes prevents headings from floating away from their content.\n\n### The scale multiplier\n\n`--typography-scale` defaults to `1`. The shipped `data-a63-type-scale` values map to `0.9` (`compact`), `1` (`normal`), `1.1` (`comfortable`), and `1.2` (`large`). OS window width is handled separately by `data-window-size`; the multiplier is a personalization control, not the window breakpoint mechanism.\n\n## Decisions worth knowing\n\n### 15px base, not 16px\n\nMost systems use 16px because browsers default to it. I chose 15px after testing information-dense layouts — docs tables, prop references, sidebar navigation. At 16px, content felt loose and wasted space. At 14px, extended reading got fatiguing. 15px is the sweet spot for my use cases: dense enough for tool interfaces, comfortable enough for documentation prose.\n\nText without a size class takes the body role too, not the browser's 16px. `@atom63/styles` sets `--a63-type-body-font-size` and `--a63-type-body-line-height` (15/23) on `body` and on a phone scope (17/22 there), and the `@atom63/ui-react` reset sets them on `Atom63Theme` and `UIProvider`. `html` keeps the browser size, so `1rem` stays 16px and every rem-based token is unchanged. Set a size class or a text role where text should be smaller, such as `text-sm` in a dense table.\n\n### Breakpoints over fluid\n\nFluid typography (`clamp()`) assumes the viewport is the right proxy for text size. In the OS metaphor, multiple windows have arbitrary widths on one screen. Breakpoint jumps plus `data-window-size` attributes let window content follow its container band instead of the outer viewport.\n\n### No heading-element-to-scale mapping in CSS\n\nI don't automatically map `h1` to `9xl` or `h2` to `8xl` in the base tokens. Different surfaces need different heading scales — a docs `h2` should be smaller than a portfolio `h2`. The MDX variants handle heading sizing per context, and the raw scale stays available for explicit use via `text-*` utilities.\n\n### Visual hierarchy and semantics are separate\n\nA semantic `h2` does not always need to look like the second-largest text on the page. The `SectionHeader` pattern follows this rule: `variant` controls visual scale, while `level` can control document outline. That keeps accessibility and visual rhythm from fighting each other.\n\n## Text roles\n\nText roles name what text is for, after the Apple HIG text styles, so one intent works on every platform. Each role picks a step of the scale on the web and a `Font.TextStyle` (with Dynamic Type) on iOS. The source is `packages/styles/src/tokens/type-roles.resolver.json`; each role has `--a63-type-<role>-font-size`, `-line-height`, `-font-weight` and `-font-weight-strong`, and the Tailwind utilities `text-<role>` and `text-<role>-strong` set all three at once.\n\n| Role | Web step | iOS text style |\n|------|----------|----------------|\n| `display-large` | `11xl`, weight 600 | 56pt, scaled like `largeTitle` |\n| `display` | `10xl`, weight 600 | 40pt, scaled like `largeTitle` |\n| `large-title` | `6xl` | `largeTitle` |\n| `title-1` | `5xl` | `title` |\n| `title-2` | `3xl` | `title2` |\n| `title-3` | `2xl` | `title3` |\n| `headline` | `base`, weight 600 | `headline` |\n| `body` | `base` | `body` |\n| `callout` | `base` | `callout` |\n| `subhead` | `sm` | `subheadline` |\n| `footnote` | `xs` | `footnote` |\n| `caption-1` | `xs` | `caption` |\n| `caption-2` | `2xs` | `caption2` |\n\n`-strong` is the emphasized weight: bold for the display roles, `large-title`, `title-1` and `title-2`, semibold for the rest. The display roles are for balances, prices and hero headlines; iOS has no larger text style, so `AtomDisplayRole` draws them at the web size and scales it with Dynamic Type like `largeTitle`. For an amount such as `$13.25`, use `Amount` from `@atom63/ui-react` (`<Amount value={13.25} currency=\"USD\" />`, `size=\"lg\"` for `display-large`): it formats the value for the locale with `Intl.NumberFormat`, draws the fraction at half size and raised with tabular figures, and reads as one label. `fraction=\"baseline\"` keeps the half-size fraction on the baseline of the integer digits instead, as some banking apps draw a balance; `raised` is the default. Without the component, put the whole number in one `text-display tabular-nums` span and wrap the fraction in `amount-fraction`, which sets it at half size and raises it, or in `amount-fraction-baseline`, which sets it at half size on the baseline. On iOS, `AtomAmountText(13.25, currencyCode: \"USD\", role: .display)` formats the amount for the locale, draws the fraction the same way with monospaced digits and reads as one VoiceOver label, and `fraction: .baseline` keeps it on the baseline; `.atomDisplayFont()` sets a display role on any other text. Web sizes follow web conventions (body is 15px; iOS body is 17pt); the role is what stays the same. Size steps are fine while exploring; settled UI should use roles.\n\n## Phone screens\n\nThe web scale is set for pages and desktop apps: body is 15px and compact control labels are 12–13px. A phone app screen reads at the iOS sizes instead, so `[data-a63-form-factor=\"phone\"]` gives a subtree the type steps and control sizing of a phone. `AppView layout=\"phone\"` (from `@atom63/ui-react/layout`) stamps it on the screen; stamp it yourself on the root of a phone-only web app. Viewport width does not apply it, so a docs page or a marketing page on a phone keeps the web sizes.\n\n| Role | Web, under 640px | Phone (`data-a63-form-factor=\"phone\"`) | iOS text style |\n|------|------------------|-----------------------------------------|----------------|\n| `body`, `headline`, `callout` | 15px | 17px | `body` 17pt |\n| `subhead` | 13px | 15px | `subheadline` 15pt |\n| `footnote`, `caption-1` | 12px | 13px | `footnote` 13pt |\n| `caption-2` | 11px | 11px | `caption2` 11pt |\n| `title-3` | 19px | 20px | `title3` 20pt |\n| `title-2` | 21px | 22px | `title2` 22pt |\n| `title-1` | 26px | 28px | `title` 28pt |\n| `large-title` | 28px | 34px | `largeTitle` 34pt |\n| `display`, `display-large` | 40px, 56px | 40px, 56px | `AtomDisplayRole` |\n\nThe scope sets the steps themselves (`text-sm` is 15px and `text-base` 17px inside it), redeclares the text roles, and sizes controls the iOS way: heights of 36, 40, 44, 48 and 52px, and every standard control label (buttons, rows, fields, menus) at body size, with `xs` at footnote size for badges, shortcuts and initials. A Switch takes the iOS 26 shape: a pill knob 1.6 times as wide as it is tall (`--a63-switch-thumb-aspect`) on a track of about 63 by 28px. A grouped list (`ItemGroup variant=\"inset\"`) takes the iOS 26 Settings rows: its default and `sm` rows, static or interactive, are at least 52px tall (`--a63-inset-row-min-size`), so a 17px label sits in about 15px of space above and below, and the card has the `2xl` corner, 18px at defaults (`--a63-inset-group-radius`). Outside the phone scope neither variable is declared, and the group keeps its control-height rows and `--radius-lg` corner. The secondary line under a title or label (an Item, Field or Form description, a Frame or ConnectedPanel description) reads `--a63-control-font-size-secondary`, which the phone scope sets to subhead size (15px) so it stays below its 17px title; elsewhere it falls back to the control `sm` size. The type scale preference still multiplies the phone steps. Inside a phone screen, keep rows and labels on the component defaults or the text roles; shrinking them with `text-sm` or `text-xs` brings back the desktop sizes.\n\n## Usage guidance\n\n| Surface | Typical range | Scale multiplier |\n|---------|---------------|------------------|\n| Portfolio hero | `4xl`–`9xl` | Usually `normal`; user preference still applies |\n| Documentation prose | `sm`–`xl` | `1` |\n| App panels / OS windows | `xs`–`lg` | Window-size band + active type-scale axis |\n| Code blocks | `sm` mono | `1` |\n\n## Anti-patterns\n\n```tsx\n// Avoid: viewport-sized type inside a constrained panel.\n```\n\nThe panel is narrow even if the viewport is wide. The text should respond to the container's role, not the browser width.\n\n```tsx\n// Prefer: choose a scale for the surface.\n```\n\n## Review checklist\n\nWhen reviewing typography, ask:\n\n1. Is this text sized for its container, not only the viewport?\n2. Does the hierarchy still work if the content wraps?\n3. Is the line-height comfortable for the amount of reading?\n4. Are semantic heading levels valid independent of visual size?\n5. Is display type reserved for display moments?",
8893
9139
  "route": "/foundations/foundation-typography",
8894
9140
  "slug": "foundation-typography"
8895
9141
  },
@@ -8976,7 +9222,7 @@
8976
9222
  "id": "app-view",
8977
9223
  "kind": "page",
8978
9224
  "title": "App view",
8979
- "description": "A full-window product view with no site header or footer: a top bar across the window, a side panel and the main region below it, and an optional bar docked at the bottom, such as a media player or a status bar. layout=\"phone\" makes it a phone app screen: edge to edge with no card or inset, the top bar optional, safe-area aware, phone-sized type and controls (body 17px, 44px controls), and the tab-bar block docked at the bottom. For a dense product view (a table, an inbox, an issue tracker, an admin dashboard, a file list), wrap it in <UIProvider density=\"compact\">: spacing and control heights scale once by 0.875 (32px controls become 28px) and text keeps its size. Copy-only: paste the files `atom63 template app-view` prints.",
9225
+ "description": "A full-window product view with no site header or footer, built on the AppView frame from @atom63/ui-react/layout: a top bar across the window, a side panel and the main region below it, and an optional bar docked at the bottom, such as a media player or a status bar. chrome=\"flush\" runs the columns to the window edges, split by borders, instead of rounded cards. layout=\"phone\" makes it a phone app screen: edge to edge, the top bar optional, safe-area aware, phone-sized type and controls (body 17px, 44px controls), and the tab-bar block docked at the bottom. overlay floats content over the main region, such as a scroll-to-bottom button. For a dense product view (a table, an inbox, an issue tracker, an admin dashboard, a file list), wrap it in <UIProvider density=\"compact\">. Import AppView; copy only the sample pages to adapt them.",
8980
9226
  "category": "layout",
8981
9227
  "tags": [
8982
9228
  "app",
@@ -8999,6 +9245,7 @@
8999
9245
  ],
9000
9246
  "readiness": "draft",
9001
9247
  "componentsUsed": [
9248
+ "app-view",
9002
9249
  "avatar",
9003
9250
  "button",
9004
9251
  "item",
@@ -9018,7 +9265,7 @@
9018
9265
  "files": [
9019
9266
  {
9020
9267
  "path": "pages/app-view/app-view.tsx",
9021
- "source": "import {\n Avatar,\n AvatarFallback,\n Button,\n Item,\n ItemContent,\n ItemDescription,\n ItemGroup,\n ItemTitle,\n SearchField,\n Slider,\n Table,\n TableBody,\n TableCell,\n TableHead,\n TableHeader,\n TableRow,\n Toggle,\n} from '@atom63/ui-react'\nimport {\n Bell,\n House,\n Library,\n ListMusic,\n Pause,\n Play,\n Repeat,\n Search,\n Shuffle,\n SkipBack,\n SkipForward,\n Volume2,\n} from 'lucide-react'\nimport { type ReactNode, useState } from 'react'\n\nimport { TabBar } from '../../blocks/tab-bar/tab-bar'\n\nexport const template = {\n id: 'app-view',\n kind: 'page',\n title: 'App view',\n description:\n 'A full-window product view with no site header or footer: a top bar across the window, a side panel and the main region below it, and an optional bar docked at the bottom, such as a media player or a status bar. layout=\"phone\" makes it a phone app screen: edge to edge with no card or inset, the top bar optional, safe-area aware, phone-sized type and controls (body 17px, 44px controls), and the tab-bar block docked at the bottom. For a dense product view (a table, an inbox, an issue tracker, an admin dashboard, a file list), wrap it in <UIProvider density=\"compact\">: spacing and control heights scale once by 0.875 (32px controls become 28px) and text keeps its size. Copy-only: paste the files `atom63 template app-view` prints.',\n category: 'layout',\n tags: [\n 'app',\n 'full window',\n 'workspace',\n 'library',\n 'player',\n 'media',\n 'docked bar',\n 'side panel',\n 'top bar',\n 'layout',\n 'phone',\n 'mobile',\n 'phone app',\n 'edge to edge',\n 'tab bar',\n 'bottom navigation',\n 'safe area',\n ],\n readiness: 'draft',\n} as const\n\nexport interface AppViewProps {\n /** The main region; it scrolls on its own. */\n children: ReactNode\n /**\n * `window` (the default): a padded window with the main region on a rounded\n * card, the side panel from `md` up and the tab bar on phones only.\n * `phone`: a phone app screen. The main region runs edge to edge with no\n * card or inset, the side panel is not drawn, and the tab bar always shows.\n * It stamps `data-a63-form-factor=\"phone\"`, which sets phone-sized type and\n * controls inside it (the iOS text sizes: body 17px, subhead 15px, footnote\n * 13px, and 44px controls), so text-* utilities, text roles and components\n * all follow without extra classes.\n * The top bar is optional and takes the top safe-area inset; without one the\n * content reaches the top edge (under the status bar with\n * `viewport-fit=cover`), so give its first block `pt-[env(safe-area-inset-top)]`.\n */\n layout?: 'phone' | 'window'\n /** A bar docked at the bottom of the window, such as a player or a status bar. */\n bottomBar?: ReactNode\n /** The accessible name of the bottom bar's region. */\n bottomBarLabel?: string\n /** A side panel next to the main region, hidden on phones. */\n panel?: ReactNode\n /** The accessible name of the side panel. */\n panelLabel?: string\n /** Bottom navigation shown on phones only, under the docked bar, such as the tab-bar block. */\n tabBar?: ReactNode\n /** The bar across the top of the window. Optional with `layout=\"phone\"`. */\n topBar?: ReactNode\n}\n\n/*\n * The window is a three-row grid: the top bar, the body (side panel and main,\n * each scrolling on its own) and the docked bar. Both bars span the full width,\n * which the app shell's sidebar layout cannot do.\n * For a dense product view (a table, an inbox, an issue tracker, an admin\n * dashboard, a file list), wrap it in <UIProvider density=\"compact\"> from\n * @atom63/ui-react: the space steps, gaps, paddings and control heights scale\n * once by 0.875 and text keeps its size.\n */\nexport function AppView({\n bottomBar,\n bottomBarLabel = 'Player',\n children,\n layout = 'window',\n panel,\n panelLabel = 'Library',\n tabBar,\n topBar,\n}: AppViewProps) {\n if (layout === 'phone') {\n /*\n * A column, no gaps or radius: the top bar, the main region (the only part\n * that scrolls), the docked bar, then the tab bar, which pads itself for\n * the home indicator. Without a tab bar the docked bar takes that inset.\n * data-a63-form-factor=\"phone\" sets the phone type steps and control sizes\n * for everything inside; text-base sets the body size the screen inherits.\n */\n return (\n <div\n className=\"bg-background text-foreground flex h-dvh flex-col text-base\"\n data-a63-form-factor=\"phone\"\n >\n {topBar ? (\n <header className=\"border-border flex min-h-14 shrink-0 items-center gap-2 border-b px-4 pt-[env(safe-area-inset-top)]\">\n {topBar}\n </header>\n ) : null}\n <main className=\"min-h-0 flex-1 overflow-y-auto\">{children}</main>\n {bottomBar ? (\n <section\n aria-label={bottomBarLabel}\n className={`border-border flex shrink-0 items-center gap-3 border-t px-4 py-2 ${tabBar ? '' : 'pb-[max(env(safe-area-inset-bottom),--spacing(2))]'}`}\n >\n {bottomBar}\n </section>\n ) : null}\n {tabBar ? <div className=\"shrink-0\">{tabBar}</div> : null}\n </div>\n )\n }\n return (\n <div className=\"bg-background text-foreground grid h-dvh grid-rows-[auto_minmax(0,1fr)_auto_auto] gap-2 p-2\">\n <header className=\"flex items-center gap-2\">{topBar}</header>\n <div className=\"flex min-h-0 gap-2\">\n {panel ? (\n <aside\n aria-label={panelLabel}\n className=\"bg-card hidden w-72 shrink-0 flex-col overflow-y-auto rounded-xl p-2 md:flex\"\n >\n {panel}\n </aside>\n ) : null}\n <main className=\"bg-card min-w-0 flex-1 overflow-y-auto rounded-xl\">{children}</main>\n </div>\n {bottomBar ? (\n <section aria-label={bottomBarLabel} className=\"flex items-center gap-4 px-2\">\n {bottomBar}\n </section>\n ) : null}\n {tabBar ? <div className=\"-mx-2 -mb-2 md:hidden\">{tabBar}</div> : null}\n </div>\n )\n}\n\nconst library = [\n { current: false, kind: 'Playlist', title: 'Morning rotation' },\n { current: true, kind: 'Album', title: 'Quiet hours' },\n { current: false, kind: 'Playlist', title: 'Late drive' },\n { current: false, kind: 'Artist', title: 'Mara Vale' },\n { current: false, kind: 'Album', title: 'Paper lanterns' },\n]\n\nconst tracks = [\n { length: '3:12', title: 'First light' },\n { length: '2:48', title: 'Low tide' },\n { length: '4:05', title: 'Window seat' },\n { length: '3:31', title: 'Long way home' },\n { length: '2:57', title: 'Afterglow' },\n]\n\n/* A sample app view: a music library with a docked player. */\nexport function AppViewPage() {\n const [query, setQuery] = useState('')\n const [playing, setPlaying] = useState(false)\n const [position, setPosition] = useState(35)\n const [volume, setVolume] = useState(70)\n\n return (\n <AppView\n bottomBar={\n <>\n <div className=\"hidden min-w-0 flex-1 sm:block\">\n <p className=\"truncate text-sm font-medium\">First light</p>\n <p className=\"text-muted-foreground truncate text-xs\">Mara Vale</p>\n </div>\n <div className=\"flex flex-[2] flex-col items-center gap-1\">\n <div className=\"flex items-center gap-1\">\n <Toggle aria-label=\"Shuffle\" size=\"sm\">\n <Shuffle aria-hidden />\n </Toggle>\n <Button aria-label=\"Previous track\" size=\"icon-sm\" variant=\"ghost\">\n <SkipBack aria-hidden />\n </Button>\n <Button\n aria-label={playing ? 'Pause' : 'Play'}\n onClick={() => setPlaying(!playing)}\n size=\"icon\"\n variant=\"primary\"\n >\n {playing ? <Pause aria-hidden /> : <Play aria-hidden />}\n </Button>\n <Button aria-label=\"Next track\" size=\"icon-sm\" variant=\"ghost\">\n <SkipForward aria-hidden />\n </Button>\n <Toggle aria-label=\"Repeat\" size=\"sm\">\n <Repeat aria-hidden />\n </Toggle>\n </div>\n <Slider\n aria-label=\"Position\"\n className=\"w-full max-w-md\"\n max={100}\n min={0}\n onValueChange={value => setPosition(Number(value))}\n value={position}\n />\n </div>\n <div className=\"hidden flex-1 items-center justify-end gap-2 md:flex\">\n <Volume2 aria-hidden className=\"text-muted-foreground size-4\" />\n <Slider\n aria-label=\"Volume\"\n className=\"w-28\"\n max={100}\n min={0}\n onValueChange={value => setVolume(Number(value))}\n value={volume}\n />\n </div>\n </>\n }\n panel={\n <>\n <h2 className=\"flex items-center gap-2 px-2 py-1 text-sm font-semibold\">\n <ListMusic aria-hidden className=\"size-4\" />\n Your library\n </h2>\n <ItemGroup>\n {library.map(entry => (\n <Item\n key={entry.title}\n render={\n <a aria-current={entry.current ? 'page' : undefined} href={`#${entry.title}`}>\n <ItemContent>\n <ItemTitle>{entry.title}</ItemTitle>\n <ItemDescription>{entry.kind}</ItemDescription>\n </ItemContent>\n </a>\n }\n size=\"xs\"\n />\n ))}\n </ItemGroup>\n </>\n }\n tabBar={\n <TabBar\n items={[\n { href: '#home', icon: <House aria-hidden />, label: 'Home' },\n { href: '#search', icon: <Search aria-hidden />, label: 'Search' },\n { current: true, href: '#library', icon: <Library aria-hidden />, label: 'Library' },\n ]}\n />\n }\n topBar={\n <>\n <Button aria-label=\"Home\" size=\"icon\" variant=\"ghost\">\n <House aria-hidden />\n </Button>\n <form\n className=\"max-w-md flex-1\"\n onSubmit={event => event.preventDefault()}\n role=\"search\"\n >\n <SearchField\n aria-label=\"Search the library\"\n onValueChange={setQuery}\n placeholder=\"What do you want to play?\"\n value={query}\n />\n </form>\n <div className=\"ms-auto flex items-center gap-2\">\n <Button aria-label=\"Notifications\" size=\"icon\" variant=\"ghost\">\n <Bell aria-hidden />\n </Button>\n <Avatar>\n <AvatarFallback>JL</AvatarFallback>\n </Avatar>\n </div>\n </>\n }\n >\n <div className=\"flex flex-col gap-6 p-6\">\n <div>\n <p className=\"text-muted-foreground text-sm\">Album · 2024 · 5 songs</p>\n <h1 className=\"font-heading text-3xl font-semibold\">Quiet hours</h1>\n </div>\n <Table>\n <TableHeader>\n <TableRow>\n <TableHead>#</TableHead>\n <TableHead>Title</TableHead>\n <TableHead className=\"text-end\">Length</TableHead>\n </TableRow>\n </TableHeader>\n <TableBody>\n {tracks.map((track, index) => (\n <TableRow key={track.title}>\n <TableCell className=\"text-muted-foreground\">{index + 1}</TableCell>\n <TableCell>{track.title}</TableCell>\n <TableCell className=\"text-muted-foreground text-end tabular-nums\">\n {track.length}\n </TableCell>\n </TableRow>\n ))}\n </TableBody>\n </Table>\n </div>\n </AppView>\n )\n}\n\n/*\n * The same app as a phone screen: layout=\"phone\" with no top bar, so the album\n * header reaches the top edge and pads itself for the status bar; a mini\n * player and the tab bar dock at the bottom.\n */\nexport function AppViewPhonePage() {\n const [playing, setPlaying] = useState(false)\n\n return (\n <AppView\n bottomBar={\n <>\n <div className=\"min-w-0 flex-1\">\n <p className=\"truncate text-sm font-medium\">First light</p>\n <p className=\"text-muted-foreground truncate text-xs\">Mara Vale</p>\n </div>\n <Button\n aria-label={playing ? 'Pause' : 'Play'}\n onClick={() => setPlaying(!playing)}\n size=\"icon\"\n variant=\"primary\"\n >\n {playing ? <Pause aria-hidden /> : <Play aria-hidden />}\n </Button>\n <Button aria-label=\"Next track\" size=\"icon\" variant=\"ghost\">\n <SkipForward aria-hidden />\n </Button>\n </>\n }\n layout=\"phone\"\n tabBar={\n <TabBar\n items={[\n { href: '#home', icon: <House aria-hidden />, label: 'Home' },\n { href: '#search', icon: <Search aria-hidden />, label: 'Search' },\n { current: true, href: '#library', icon: <Library aria-hidden />, label: 'Library' },\n ]}\n />\n }\n >\n <div className=\"flex flex-col gap-2 pt-[env(safe-area-inset-top)]\">\n <div className=\"px-4 pt-6\">\n <p className=\"text-muted-foreground text-sm\">Album · 2024 · 5 songs</p>\n <h1 className=\"font-heading text-3xl font-semibold\">Quiet hours</h1>\n </div>\n <ItemGroup>\n {tracks.map((track, index) => (\n <Item\n key={track.title}\n render={\n <a href={`#${track.title}`}>\n <ItemContent>\n <ItemTitle>{track.title}</ItemTitle>\n <ItemDescription>\n {index + 1} · {track.length}\n </ItemDescription>\n </ItemContent>\n </a>\n }\n size=\"sm\"\n />\n ))}\n </ItemGroup>\n </div>\n </AppView>\n )\n}\n"
9268
+ "source": "import {\n Avatar,\n AvatarFallback,\n Button,\n Item,\n ItemContent,\n ItemDescription,\n ItemGroup,\n ItemTitle,\n SearchField,\n Slider,\n Table,\n TableBody,\n TableCell,\n TableHead,\n TableHeader,\n TableRow,\n Toggle,\n} from '@atom63/ui-react'\nimport { AppView } from '@atom63/ui-react/layout'\nimport {\n Bell,\n House,\n Library,\n ListMusic,\n Pause,\n Play,\n Repeat,\n Search,\n Shuffle,\n SkipBack,\n SkipForward,\n Volume2,\n} from 'lucide-react'\nimport { useState } from 'react'\n\nimport { TabBar } from '../../blocks/tab-bar/tab-bar'\n\nexport const template = {\n id: 'app-view',\n kind: 'page',\n title: 'App view',\n description:\n 'A full-window product view with no site header or footer, built on the AppView frame from @atom63/ui-react/layout: a top bar across the window, a side panel and the main region below it, and an optional bar docked at the bottom, such as a media player or a status bar. chrome=\"flush\" runs the columns to the window edges, split by borders, instead of rounded cards. layout=\"phone\" makes it a phone app screen: edge to edge, the top bar optional, safe-area aware, phone-sized type and controls (body 17px, 44px controls), and the tab-bar block docked at the bottom. overlay floats content over the main region, such as a scroll-to-bottom button. For a dense product view (a table, an inbox, an issue tracker, an admin dashboard, a file list), wrap it in <UIProvider density=\"compact\">. Import AppView; copy only the sample pages to adapt them.',\n category: 'layout',\n tags: [\n 'app',\n 'full window',\n 'workspace',\n 'library',\n 'player',\n 'media',\n 'docked bar',\n 'side panel',\n 'top bar',\n 'layout',\n 'phone',\n 'mobile',\n 'phone app',\n 'edge to edge',\n 'tab bar',\n 'bottom navigation',\n 'safe area',\n ],\n readiness: 'draft',\n} as const\n\nconst library = [\n { current: false, kind: 'Playlist', title: 'Morning rotation' },\n { current: true, kind: 'Album', title: 'Quiet hours' },\n { current: false, kind: 'Playlist', title: 'Late drive' },\n { current: false, kind: 'Artist', title: 'Mara Vale' },\n { current: false, kind: 'Album', title: 'Paper lanterns' },\n]\n\nconst tracks = [\n { length: '3:12', title: 'First light' },\n { length: '2:48', title: 'Low tide' },\n { length: '4:05', title: 'Window seat' },\n { length: '3:31', title: 'Long way home' },\n { length: '2:57', title: 'Afterglow' },\n]\n\n/* A sample app view: a music library with a docked player. */\nexport function AppViewPage() {\n const [query, setQuery] = useState('')\n const [playing, setPlaying] = useState(false)\n const [position, setPosition] = useState(35)\n const [volume, setVolume] = useState(70)\n\n return (\n <AppView\n bottomBar={\n <>\n <div className=\"hidden min-w-0 flex-1 sm:block\">\n <p className=\"truncate text-sm font-medium\">First light</p>\n <p className=\"text-muted-foreground truncate text-xs\">Mara Vale</p>\n </div>\n <div className=\"flex flex-[2] flex-col items-center gap-1\">\n <div className=\"flex items-center gap-1\">\n <Toggle aria-label=\"Shuffle\" size=\"sm\">\n <Shuffle aria-hidden />\n </Toggle>\n <Button aria-label=\"Previous track\" size=\"icon-sm\" variant=\"ghost\">\n <SkipBack aria-hidden />\n </Button>\n <Button\n aria-label={playing ? 'Pause' : 'Play'}\n onClick={() => setPlaying(!playing)}\n size=\"icon\"\n variant=\"primary\"\n >\n {playing ? <Pause aria-hidden /> : <Play aria-hidden />}\n </Button>\n <Button aria-label=\"Next track\" size=\"icon-sm\" variant=\"ghost\">\n <SkipForward aria-hidden />\n </Button>\n <Toggle aria-label=\"Repeat\" size=\"sm\">\n <Repeat aria-hidden />\n </Toggle>\n </div>\n <Slider\n aria-label=\"Position\"\n className=\"w-full max-w-md\"\n max={100}\n min={0}\n onValueChange={value => setPosition(Number(value))}\n value={position}\n />\n </div>\n <div className=\"hidden flex-1 items-center justify-end gap-2 md:flex\">\n <Volume2 aria-hidden className=\"text-muted-foreground size-4\" />\n <Slider\n aria-label=\"Volume\"\n className=\"w-28\"\n max={100}\n min={0}\n onValueChange={value => setVolume(Number(value))}\n value={volume}\n />\n </div>\n </>\n }\n panel={\n <>\n <h2 className=\"flex items-center gap-2 px-2 py-1 text-sm font-semibold\">\n <ListMusic aria-hidden className=\"size-4\" />\n Your library\n </h2>\n <ItemGroup>\n {library.map(entry => (\n <Item\n key={entry.title}\n render={\n <a aria-current={entry.current ? 'page' : undefined} href={`#${entry.title}`}>\n <ItemContent>\n <ItemTitle>{entry.title}</ItemTitle>\n <ItemDescription>{entry.kind}</ItemDescription>\n </ItemContent>\n </a>\n }\n size=\"xs\"\n />\n ))}\n </ItemGroup>\n </>\n }\n tabBar={\n <TabBar\n items={[\n { href: '#home', icon: <House aria-hidden />, label: 'Home' },\n { href: '#search', icon: <Search aria-hidden />, label: 'Search' },\n { current: true, href: '#library', icon: <Library aria-hidden />, label: 'Library' },\n ]}\n />\n }\n topBar={\n <>\n <Button aria-label=\"Home\" size=\"icon\" variant=\"ghost\">\n <House aria-hidden />\n </Button>\n <form\n className=\"max-w-md flex-1\"\n onSubmit={event => event.preventDefault()}\n role=\"search\"\n >\n <SearchField\n aria-label=\"Search the library\"\n onValueChange={setQuery}\n placeholder=\"What do you want to play?\"\n value={query}\n />\n </form>\n <div className=\"ms-auto flex items-center gap-2\">\n <Button aria-label=\"Notifications\" size=\"icon\" variant=\"ghost\">\n <Bell aria-hidden />\n </Button>\n <Avatar>\n <AvatarFallback>JL</AvatarFallback>\n </Avatar>\n </div>\n </>\n }\n >\n <div className=\"flex flex-col gap-6 p-6\">\n <div>\n <p className=\"text-muted-foreground text-sm\">Album · 2024 · 5 songs</p>\n <h1 className=\"font-heading text-3xl font-semibold\">Quiet hours</h1>\n </div>\n <Table>\n <TableHeader>\n <TableRow>\n <TableHead>#</TableHead>\n <TableHead>Title</TableHead>\n <TableHead className=\"text-end\">Length</TableHead>\n </TableRow>\n </TableHeader>\n <TableBody>\n {tracks.map((track, index) => (\n <TableRow key={track.title}>\n <TableCell className=\"text-muted-foreground\">{index + 1}</TableCell>\n <TableCell>{track.title}</TableCell>\n <TableCell className=\"text-muted-foreground text-end tabular-nums\">\n {track.length}\n </TableCell>\n </TableRow>\n ))}\n </TableBody>\n </Table>\n </div>\n </AppView>\n )\n}\n\n/*\n * The same app as a phone screen: layout=\"phone\" with no top bar, so the album\n * header reaches the top edge and pads itself for the status bar; a mini\n * player and the tab bar dock at the bottom.\n */\nexport function AppViewPhonePage() {\n const [playing, setPlaying] = useState(false)\n\n return (\n <AppView\n bottomBar={\n <>\n <div className=\"min-w-0 flex-1\">\n <p className=\"truncate text-sm font-medium\">First light</p>\n <p className=\"text-muted-foreground truncate text-xs\">Mara Vale</p>\n </div>\n <Button\n aria-label={playing ? 'Pause' : 'Play'}\n onClick={() => setPlaying(!playing)}\n size=\"icon\"\n variant=\"primary\"\n >\n {playing ? <Pause aria-hidden /> : <Play aria-hidden />}\n </Button>\n <Button aria-label=\"Next track\" size=\"icon\" variant=\"ghost\">\n <SkipForward aria-hidden />\n </Button>\n </>\n }\n layout=\"phone\"\n tabBar={\n <TabBar\n items={[\n { href: '#home', icon: <House aria-hidden />, label: 'Home' },\n { href: '#search', icon: <Search aria-hidden />, label: 'Search' },\n { current: true, href: '#library', icon: <Library aria-hidden />, label: 'Library' },\n ]}\n />\n }\n >\n <div className=\"flex flex-col gap-2 pt-[env(safe-area-inset-top)]\">\n <div className=\"px-4 pt-6\">\n <p className=\"text-muted-foreground text-sm\">Album · 2024 · 5 songs</p>\n <h1 className=\"font-heading text-3xl font-semibold\">Quiet hours</h1>\n </div>\n <ItemGroup>\n {tracks.map((track, index) => (\n <Item\n key={track.title}\n render={\n <a href={`#${track.title}`}>\n <ItemContent>\n <ItemTitle>{track.title}</ItemTitle>\n <ItemDescription>\n {index + 1} · {track.length}\n </ItemDescription>\n </ItemContent>\n </a>\n }\n size=\"sm\"\n />\n ))}\n </ItemGroup>\n </div>\n </AppView>\n )\n}\n"
9022
9269
  }
9023
9270
  ]
9024
9271
  },
@@ -9124,7 +9371,8 @@
9124
9371
  "Container",
9125
9372
  "badge",
9126
9373
  "button",
9127
- "dropdown-menu"
9374
+ "dropdown-menu",
9375
+ "item"
9128
9376
  ],
9129
9377
  "blocksUsed": [
9130
9378
  "app-shell",
@@ -9145,7 +9393,7 @@
9145
9393
  },
9146
9394
  {
9147
9395
  "path": "pages/list-page/list-page.tsx",
9148
- "source": "import {\n Badge,\n Button,\n DropdownMenu,\n DropdownMenuContent,\n DropdownMenuItem,\n DropdownMenuSeparator,\n DropdownMenuTrigger,\n} from '@atom63/ui-react'\nimport { Container } from '@atom63/ui-react/layout'\nimport { Ellipsis, FileText, LayoutDashboard, Plus, Settings } from 'lucide-react'\nimport { useState } from 'react'\n\nimport { AppShell } from '../../blocks/app-shell/app-shell'\nimport {\n type DataTableColumn,\n DataTableSection,\n} from '../../blocks/data-table-section/data-table-section'\nimport { DetailPanel } from '../../blocks/detail-panel/detail-panel'\nimport { FilterBar } from '../../blocks/filter-bar/filter-bar'\nimport { PageHeader } from '../../blocks/page-header/page-header'\nimport { type Invoice, type InvoiceStatus, invoices as sampleInvoices } from './list-page-data'\n\nexport const template = {\n id: 'list-page',\n kind: 'page',\n title: 'List page',\n description:\n 'A filterable collection page inside the app shell: a header with one primary action, a search and status filter, a table that becomes stacked rows on phones, and a detail sheet for one row.',\n category: 'collections',\n tags: ['list', 'detail', 'table', 'index', 'invoice', 'invoices', 'orders', 'filter', 'search'],\n readiness: 'ready',\n} as const\n\nconst nav = [\n { href: '#overview', icon: <LayoutDashboard aria-hidden />, label: 'Overview' },\n { current: true, href: '#invoices', icon: <FileText aria-hidden />, label: 'Invoices' },\n { href: '#settings', icon: <Settings aria-hidden />, label: 'Settings' },\n]\n\nconst statusOptions = [\n { label: 'All statuses', value: 'all' },\n { label: 'Paid', value: 'paid' },\n { label: 'Open', value: 'open' },\n { label: 'Overdue', value: 'overdue' },\n] as const\n\nconst statusBadge: Record<InvoiceStatus, { label: string; variant: 'success' | 'info' | 'error' }> =\n {\n paid: { label: 'Paid', variant: 'success' },\n open: { label: 'Open', variant: 'info' },\n overdue: { label: 'Overdue', variant: 'error' },\n }\n\nconst currency = new Intl.NumberFormat('en-US', { currency: 'USD', style: 'currency' })\nconst date = new Intl.DateTimeFormat('en-US', { dateStyle: 'medium', timeZone: 'UTC' })\n\nfunction StatusBadge({ status }: { status: InvoiceStatus }) {\n return <Badge variant={statusBadge[status].variant}>{statusBadge[status].label}</Badge>\n}\n\nconst columns: readonly DataTableColumn<Invoice>[] = [\n { cell: invoice => invoice.id, header: 'Invoice', key: 'id' },\n { cell: invoice => invoice.customer, header: 'Customer', key: 'customer' },\n { cell: invoice => <StatusBadge status={invoice.status} />, header: 'Status', key: 'status' },\n { cell: invoice => date.format(new Date(invoice.issued)), header: 'Issued', key: 'issued' },\n {\n align: 'end',\n cell: invoice => currency.format(invoice.amount),\n header: 'Amount',\n key: 'amount',\n },\n]\n\nexport interface ListPageProps {\n /** The rows to list; the page filters them in memory. */\n invoices?: readonly Invoice[]\n}\n\nexport function ListContent({ invoices = sampleInvoices }: ListPageProps) {\n const [query, setQuery] = useState('')\n const [status, setStatus] = useState('all')\n const [openId, setOpenId] = useState<string | null>(null)\n const open = invoices.find(invoice => invoice.id === openId)\n\n const needle = query.trim().toLowerCase()\n const visible = invoices.filter(\n invoice =>\n (status === 'all' || invoice.status === status) &&\n (needle === '' ||\n invoice.id.toLowerCase().includes(needle) ||\n invoice.customer.toLowerCase().includes(needle))\n )\n const filtered = needle !== '' || status !== 'all'\n const clear = () => {\n setQuery('')\n setStatus('all')\n }\n\n return (\n <>\n <Container maxWidth=\"wide\" padding=\"none\">\n <PageHeader\n actions={\n <Button variant=\"primary\">\n <Plus aria-hidden />\n New invoice\n </Button>\n }\n description=\"Track what customers owe and what has been paid.\"\n title=\"Invoices\"\n />\n <FilterBar\n filterLabel=\"Status\"\n filterOptions={statusOptions}\n filterValue={status}\n onClear={clear}\n onFilterChange={setStatus}\n onQueryChange={setQuery}\n query={query}\n searchLabel=\"Search invoices\"\n searchPlaceholder=\"Invoice number or customer\"\n showClear={filtered}\n />\n <DataTableSection\n columns={columns}\n empty={\n invoices.length === 0\n ? {\n action: <Button variant=\"primary\">New invoice</Button>,\n description: 'Invoices you create appear here, with their status and amount.',\n title: 'No invoices yet',\n }\n : {\n action: (\n <Button onClick={clear} variant=\"outline\">\n Clear filters\n </Button>\n ),\n description:\n 'No invoice matches this search and status. Clear the filters to see every invoice.',\n title: 'No matching invoices',\n }\n }\n getRowKey={invoice => invoice.id}\n label=\"Invoices\"\n rowActions={invoice => (\n <DropdownMenu>\n <DropdownMenuTrigger\n render={\n <Button aria-label={`Actions for ${invoice.id}`} size=\"icon-sm\" variant=\"ghost\">\n <Ellipsis aria-hidden />\n </Button>\n }\n />\n <DropdownMenuContent align=\"end\">\n <DropdownMenuItem onClick={() => setOpenId(invoice.id)}>\n View invoice\n </DropdownMenuItem>\n <DropdownMenuItem>Download PDF</DropdownMenuItem>\n {invoice.status === 'paid' ? null : (\n <DropdownMenuItem>Mark as paid</DropdownMenuItem>\n )}\n <DropdownMenuSeparator />\n <DropdownMenuItem variant=\"destructive\">Void invoice</DropdownMenuItem>\n </DropdownMenuContent>\n </DropdownMenu>\n )}\n rows={visible}\n summary={\n filtered\n ? `${visible.length} of ${invoices.length} invoices`\n : `${invoices.length} invoices`\n }\n />\n </Container>\n <DetailPanel\n actions={\n <>\n <Button variant=\"outline\">Download PDF</Button>\n {open?.status === 'paid' ? null : <Button variant=\"primary\">Mark as paid</Button>}\n </>\n }\n description={open?.customer}\n fields={\n open\n ? [\n { label: 'Status', value: <StatusBadge status={open.status} /> },\n { label: 'Issued', value: date.format(new Date(open.issued)) },\n { label: 'Amount', value: currency.format(open.amount) },\n ]\n : []\n }\n onOpenChange={next => {\n if (!next) setOpenId(null)\n }}\n open={open !== undefined}\n title={open?.id ?? ''}\n />\n </>\n )\n}\n\n/* The page in its app shell. An app that renders the shell once, around its\n routes, renders `ListContent` inside it instead. */\nexport function ListPage(props: ListPageProps) {\n return (\n <AppShell navItems={nav} productName=\"Tally\">\n <ListContent {...props} />\n </AppShell>\n )\n}\n"
9396
+ "source": "import {\n Badge,\n Button,\n DropdownMenu,\n DropdownMenuContent,\n DropdownMenuItem,\n DropdownMenuSeparator,\n DropdownMenuTrigger,\n Item,\n ItemActions,\n ItemContent,\n ItemDescription,\n ItemTitle,\n} from '@atom63/ui-react'\nimport { Container } from '@atom63/ui-react/layout'\nimport { ChevronRight, Ellipsis, FileText, LayoutDashboard, Plus, Settings } from 'lucide-react'\nimport { useState, type ReactNode } from 'react'\n\nimport { AppShell } from '../../blocks/app-shell/app-shell'\nimport {\n type DataTableColumn,\n DataTableSection,\n} from '../../blocks/data-table-section/data-table-section'\nimport { DetailPanel } from '../../blocks/detail-panel/detail-panel'\nimport { FilterBar } from '../../blocks/filter-bar/filter-bar'\nimport { PageHeader } from '../../blocks/page-header/page-header'\nimport { type Invoice, type InvoiceStatus, invoices as sampleInvoices } from './list-page-data'\n\nexport const template = {\n id: 'list-page',\n kind: 'page',\n title: 'List page',\n description:\n 'A filterable collection page inside the app shell: a header with one primary action, a search and status filter, a table that becomes stacked rows on phones, and a detail sheet for one row.',\n category: 'collections',\n tags: ['list', 'detail', 'table', 'index', 'invoice', 'invoices', 'orders', 'filter', 'search'],\n readiness: 'ready',\n} as const\n\nconst nav = [\n { href: '#overview', icon: <LayoutDashboard aria-hidden />, label: 'Overview' },\n { current: true, href: '#invoices', icon: <FileText aria-hidden />, label: 'Invoices' },\n { href: '#settings', icon: <Settings aria-hidden />, label: 'Settings' },\n]\n\nconst statusOptions = [\n { label: 'All statuses', value: 'all' },\n { label: 'Paid', value: 'paid' },\n { label: 'Open', value: 'open' },\n { label: 'Overdue', value: 'overdue' },\n] as const\n\nconst statusBadge: Record<InvoiceStatus, { label: string; variant: 'success' | 'info' | 'error' }> =\n {\n paid: { label: 'Paid', variant: 'success' },\n open: { label: 'Open', variant: 'info' },\n overdue: { label: 'Overdue', variant: 'error' },\n }\n\nconst currency = new Intl.NumberFormat('en-US', { currency: 'USD', style: 'currency' })\nconst date = new Intl.DateTimeFormat('en-US', { dateStyle: 'medium', timeZone: 'UTC' })\n\nfunction StatusBadge({ status }: { status: InvoiceStatus }) {\n return <Badge variant={statusBadge[status].variant}>{statusBadge[status].label}</Badge>\n}\n\nconst columns: readonly DataTableColumn<Invoice>[] = [\n { cell: invoice => invoice.id, header: 'Invoice', key: 'id' },\n { cell: invoice => invoice.customer, header: 'Customer', key: 'customer' },\n { cell: invoice => <StatusBadge status={invoice.status} />, header: 'Status', key: 'status' },\n {\n cell: invoice => date.format(new Date(invoice.issued)),\n header: 'Issued',\n key: 'issued',\n showFrom: 'md',\n },\n {\n align: 'end',\n cell: invoice => currency.format(invoice.amount),\n header: 'Amount',\n key: 'amount',\n showFrom: 'lg',\n },\n]\n\nexport interface ListPageProps {\n /** Initial record shown in the detail sheet, useful for a routed selection. */\n defaultOpenId?: string\n /** Initial search text, useful when the URL restores filter state. */\n defaultQuery?: string\n /** The rows to list; the page filters them in memory. */\n invoices?: readonly Invoice[]\n /** A transient operation surface such as import progress or completion. */\n operationStatus?: ReactNode\n}\n\nexport function ListContent({\n defaultOpenId,\n defaultQuery = '',\n invoices = sampleInvoices,\n operationStatus,\n}: ListPageProps) {\n const [query, setQuery] = useState(defaultQuery)\n const [status, setStatus] = useState('all')\n const [openId, setOpenId] = useState<string | null>(defaultOpenId ?? null)\n const open = invoices.find(invoice => invoice.id === openId)\n\n const needle = query.trim().toLowerCase()\n const visible = invoices.filter(\n invoice =>\n (status === 'all' || invoice.status === status) &&\n (needle === '' ||\n invoice.id.toLowerCase().includes(needle) ||\n invoice.customer.toLowerCase().includes(needle))\n )\n const filtered = needle !== '' || status !== 'all'\n const clear = () => {\n setQuery('')\n setStatus('all')\n }\n const rowMenu = (invoice: Invoice) => (\n <DropdownMenu>\n <DropdownMenuTrigger\n render={\n <Button aria-label={`Actions for ${invoice.id}`} size=\"icon-sm\" variant=\"ghost\">\n <Ellipsis aria-hidden />\n </Button>\n }\n />\n <DropdownMenuContent align=\"end\">\n <DropdownMenuItem onClick={() => setOpenId(invoice.id)}>View invoice</DropdownMenuItem>\n <DropdownMenuItem>Download PDF</DropdownMenuItem>\n {invoice.status === 'paid' ? null : <DropdownMenuItem>Mark as paid</DropdownMenuItem>}\n <DropdownMenuSeparator />\n <DropdownMenuItem variant=\"destructive\">Void invoice</DropdownMenuItem>\n </DropdownMenuContent>\n </DropdownMenu>\n )\n\n return (\n <>\n <Container maxWidth=\"wide\" padding=\"none\">\n <PageHeader\n actions={\n <Button variant=\"primary\">\n <Plus aria-hidden />\n New invoice\n </Button>\n }\n description=\"Track what customers owe and what has been paid.\"\n title=\"Invoices\"\n />\n <FilterBar\n filterLabel=\"Status\"\n filterOptions={statusOptions}\n filterValue={status}\n onClear={clear}\n onFilterChange={setStatus}\n onQueryChange={setQuery}\n query={query}\n searchLabel=\"Search invoices\"\n searchPlaceholder=\"Invoice number or customer\"\n showClear={filtered}\n />\n <DataTableSection\n columns={columns}\n empty={\n invoices.length === 0\n ? {\n action: <Button variant=\"primary\">New invoice</Button>,\n description: 'Invoices you create appear here, with their status and amount.',\n title: 'No invoices yet',\n }\n : {\n action: (\n <Button onClick={clear} variant=\"outline\">\n Clear filters\n </Button>\n ),\n description:\n 'No invoice matches this search and status. Clear the filters to see every invoice.',\n title: 'No matching invoices',\n }\n }\n getRowKey={invoice => invoice.id}\n label=\"Invoices\"\n renderPhoneRow={invoice => (\n <Item\n className=\"rounded-none\"\n data-selected={openId === invoice.id ? '' : undefined}\n size=\"sm\"\n >\n <ItemContent>\n <ItemTitle>{invoice.customer}</ItemTitle>\n <ItemDescription>\n {invoice.id} · {date.format(new Date(invoice.issued))}\n </ItemDescription>\n </ItemContent>\n <ItemActions className=\"gap-1\">\n <StatusBadge status={invoice.status} />\n <Button\n aria-label={`View ${invoice.id}`}\n onClick={() => setOpenId(invoice.id)}\n size=\"icon-sm\"\n variant=\"ghost\"\n >\n <ChevronRight aria-hidden />\n </Button>\n {rowMenu(invoice)}\n </ItemActions>\n </Item>\n )}\n rowActions={rowMenu}\n rows={visible}\n selectedRowKey={openId ?? undefined}\n summary={\n filtered\n ? `${visible.length} of ${invoices.length} invoices`\n : `${invoices.length} invoices`\n }\n />\n </Container>\n <DetailPanel\n actions={\n <>\n <Button variant=\"outline\">Download PDF</Button>\n {open?.status === 'paid' ? null : <Button variant=\"primary\">Mark as paid</Button>}\n </>\n }\n description={open?.customer}\n fields={\n open\n ? [\n { label: 'Status', value: <StatusBadge status={open.status} /> },\n { label: 'Issued', value: date.format(new Date(open.issued)) },\n { label: 'Amount', value: currency.format(open.amount) },\n ]\n : []\n }\n onOpenChange={next => {\n if (!next) setOpenId(null)\n }}\n open={open !== undefined}\n title={open?.id ?? ''}\n />\n {operationStatus}\n </>\n )\n}\n\n/* The page in its app shell. An app that renders the shell once, around its\n routes, renders `ListContent` inside it instead. */\nexport function ListPage(props: ListPageProps) {\n return (\n <AppShell navItems={nav} productName=\"Tally\">\n <ListContent {...props} />\n </AppShell>\n )\n}\n"
9149
9397
  }
9150
9398
  ]
9151
9399
  },
@@ -9424,7 +9672,7 @@
9424
9672
  "files": [
9425
9673
  {
9426
9674
  "path": "blocks/data-table-section/data-table-section.tsx",
9427
- "source": "import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@atom63/ui-react'\nimport { SearchX } from 'lucide-react'\nimport type { ReactNode } from 'react'\n\nimport { EmptyState } from '../empty-state/empty-state'\n\nexport const template = {\n id: 'data-table-section',\n kind: 'block',\n title: 'Data table section',\n description:\n 'A collection shown as a table on wide screens and as stacked rows on phones, with a live result count, per-row actions and an empty state that offers a way out.',\n category: 'collections',\n tags: ['table', 'list', 'rows', 'responsive', 'empty state', 'results'],\n readiness: 'ready',\n} as const\n\nexport interface DataTableColumn<Row> {\n /** `end` for numbers and amounts, so digits line up. */\n align?: 'start' | 'end'\n cell: (row: Row) => ReactNode\n header: string\n key: string\n}\n\nexport interface DataTableEmpty {\n /** The next step, usually a button that clears the filters. */\n action?: ReactNode\n description: string\n title: string\n}\n\nexport interface DataTableSectionProps<Row> {\n /** Names the table and the phone list for assistive technology. */\n label: string\n /** The first column is the row's title in the phone layout. */\n columns: readonly DataTableColumn<Row>[]\n empty: DataTableEmpty\n getRowKey: (row: Row) => string\n /** Heading level of the empty state's title: one below the heading above the section. */\n headingLevel?: 2 | 3 | 4\n rowActions?: (row: Row) => ReactNode\n rows: readonly Row[]\n /** A short count such as \"12 of 25 invoices\", announced when it changes. */\n summary: string\n}\n\nconst alignClass = (align: DataTableColumn<unknown>['align']) =>\n align === 'end' ? 'text-end tabular-nums' : 'text-start'\n\n/*\n * A wide table does not fit a phone, so below `sm` each row becomes a stacked\n * item: the first column is its title and the rest are label and value pairs.\n * Only one layout is displayed at a time; the hidden one is out of the\n * accessibility tree.\n */\nexport function DataTableSection<Row>({\n columns,\n empty,\n getRowKey,\n headingLevel = 2,\n label,\n rowActions,\n rows,\n summary,\n}: DataTableSectionProps<Row>) {\n const [titleColumn, ...detailColumns] = columns\n return (\n <div className=\"flex flex-col gap-3\">\n <p aria-live=\"polite\" className=\"text-muted-foreground text-sm\">\n {summary}\n </p>\n {rows.length === 0 ? (\n <EmptyState\n action={empty.action}\n description={empty.description}\n headingLevel={headingLevel}\n icon={<SearchX aria-hidden />}\n title={empty.title}\n />\n ) : (\n <>\n {/* A `frame` ancestor draws the table as a bordered card, like the phone list. */}\n <div className=\"hidden sm:block\" data-slot=\"frame\">\n <Table aria-label={label}>\n <TableHeader>\n <TableRow>\n {columns.map(column => (\n <TableHead className={alignClass(column.align)} key={column.key}>\n {column.header}\n </TableHead>\n ))}\n {rowActions ? (\n <TableHead className=\"w-0\">\n <span className=\"sr-only\">Actions</span>\n </TableHead>\n ) : null}\n </TableRow>\n </TableHeader>\n <TableBody>\n {rows.map(row => (\n <TableRow key={getRowKey(row)}>\n {columns.map(column => (\n <TableCell className={alignClass(column.align)} key={column.key}>\n {column.cell(row)}\n </TableCell>\n ))}\n {rowActions ? (\n <TableCell className=\"text-end\">{rowActions(row)}</TableCell>\n ) : null}\n </TableRow>\n ))}\n </TableBody>\n </Table>\n </div>\n <ul\n aria-label={label}\n className=\"divide-border border-border flex flex-col divide-y rounded-lg border sm:hidden\"\n >\n {rows.map(row => (\n <li className=\"flex items-start gap-3 p-4\" key={getRowKey(row)}>\n <div className=\"flex min-w-0 flex-1 flex-col gap-2\">\n {titleColumn ? (\n <div className=\"text-foreground font-medium\">{titleColumn.cell(row)}</div>\n ) : null}\n <dl className=\"grid grid-cols-[auto_minmax(0,1fr)] gap-x-4 gap-y-1 text-sm\">\n {detailColumns.map(column => (\n <div className=\"contents\" key={column.key}>\n <dt className=\"text-muted-foreground\">{column.header}</dt>\n <dd className={column.align === 'end' ? 'tabular-nums' : undefined}>\n {column.cell(row)}\n </dd>\n </div>\n ))}\n </dl>\n </div>\n {rowActions ? rowActions(row) : null}\n </li>\n ))}\n </ul>\n </>\n )}\n </div>\n )\n}\n"
9675
+ "source": "import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from '@atom63/ui-react'\nimport { SearchX } from 'lucide-react'\nimport type { ReactNode } from 'react'\n\nimport { EmptyState } from '../empty-state/empty-state'\n\nexport const template = {\n id: 'data-table-section',\n kind: 'block',\n title: 'Data table section',\n description:\n 'A collection shown as a table on wide screens and as stacked rows on phones, with a live result count, per-row actions and an empty state that offers a way out.',\n category: 'collections',\n tags: ['table', 'list', 'rows', 'responsive', 'empty state', 'results'],\n readiness: 'ready',\n} as const\n\nexport interface DataTableColumn<Row> {\n /** `end` for numbers and amounts, so digits line up. */\n align?: 'start' | 'end'\n cell: (row: Row) => ReactNode\n header: string\n key: string\n /** The table width at which this column first appears. */\n showFrom?: 'sm' | 'md' | 'lg'\n}\n\nexport interface DataTableEmpty {\n /** The next step, usually a button that clears the filters. */\n action?: ReactNode\n description: string\n title: string\n}\n\nexport interface DataTableSectionProps<Row> {\n /** Names the table and the phone list for assistive technology. */\n label: string\n /** The first column is the row's title in the phone layout. */\n columns: readonly DataTableColumn<Row>[]\n empty: DataTableEmpty\n getRowKey: (row: Row) => string\n /** Heading level of the empty state's title: one below the heading above the section. */\n headingLevel?: 2 | 3 | 4\n /** Product-specific phone composition; the table remains column-driven. */\n renderPhoneRow?: (row: Row) => ReactNode\n rowActions?: (row: Row) => ReactNode\n rows: readonly Row[]\n /** Highlights the open record without making the row itself interactive. */\n selectedRowKey?: string\n /** A short count such as \"12 of 25 invoices\", announced when it changes. */\n summary: string\n}\n\nconst alignClass = (align: DataTableColumn<unknown>['align']) =>\n align === 'end' ? 'text-end tabular-nums' : 'text-start'\n\nconst showFromClass = {\n sm: '',\n md: 'hidden md:table-cell',\n lg: 'hidden lg:table-cell',\n} as const\n\nconst columnClass = <Row,>(column: DataTableColumn<Row>) =>\n `${alignClass(column.align)} ${showFromClass[column.showFrom ?? 'sm']}`.trim()\n\n/*\n * A wide table does not fit a phone, so below `sm` each row becomes a stacked\n * item: the first column is its title and the rest are label and value pairs.\n * Only one layout is displayed at a time; the hidden one is out of the\n * accessibility tree.\n */\nexport function DataTableSection<Row>({\n columns,\n empty,\n getRowKey,\n headingLevel = 2,\n label,\n renderPhoneRow,\n rowActions,\n rows,\n selectedRowKey,\n summary,\n}: DataTableSectionProps<Row>) {\n const [titleColumn, ...detailColumns] = columns\n return (\n <div className=\"flex flex-col gap-3\">\n <p aria-live=\"polite\" className=\"text-muted-foreground text-sm\">\n {summary}\n </p>\n {rows.length === 0 ? (\n <EmptyState\n action={empty.action}\n description={empty.description}\n headingLevel={headingLevel}\n icon={<SearchX aria-hidden />}\n title={empty.title}\n />\n ) : (\n <>\n {/* A `frame` ancestor draws the table as a bordered card, like the phone list. */}\n <div className=\"hidden sm:block\" data-slot=\"frame\">\n <Table aria-label={label}>\n <TableHeader>\n <TableRow>\n {columns.map(column => (\n <TableHead className={columnClass(column)} key={column.key}>\n {column.header}\n </TableHead>\n ))}\n {rowActions ? (\n <TableHead className=\"w-0\">\n <span className=\"sr-only\">Actions</span>\n </TableHead>\n ) : null}\n </TableRow>\n </TableHeader>\n <TableBody>\n {rows.map(row => (\n <TableRow\n data-selected={getRowKey(row) === selectedRowKey ? '' : undefined}\n key={getRowKey(row)}\n >\n {columns.map(column => (\n <TableCell className={columnClass(column)} key={column.key}>\n {column.cell(row)}\n </TableCell>\n ))}\n {rowActions ? (\n <TableCell className=\"text-end\">{rowActions(row)}</TableCell>\n ) : null}\n </TableRow>\n ))}\n </TableBody>\n </Table>\n </div>\n <ul\n aria-label={label}\n className=\"divide-border border-border flex flex-col divide-y rounded-lg border sm:hidden\"\n >\n {rows.map(row => (\n <li\n className={renderPhoneRow ? undefined : 'flex items-start gap-3 p-4'}\n key={getRowKey(row)}\n >\n {renderPhoneRow ? (\n renderPhoneRow(row)\n ) : (\n <>\n <div className=\"flex min-w-0 flex-1 flex-col gap-2\">\n {titleColumn ? (\n <div className=\"text-foreground font-medium\">{titleColumn.cell(row)}</div>\n ) : null}\n <dl className=\"grid grid-cols-[auto_minmax(0,1fr)] gap-x-4 gap-y-1 text-sm\">\n {detailColumns.map(column => (\n <div className=\"contents\" key={column.key}>\n <dt className=\"text-muted-foreground\">{column.header}</dt>\n <dd className={column.align === 'end' ? 'tabular-nums' : undefined}>\n {column.cell(row)}\n </dd>\n </div>\n ))}\n </dl>\n </div>\n {rowActions ? rowActions(row) : null}\n </>\n )}\n </li>\n ))}\n </ul>\n </>\n )}\n </div>\n )\n}\n"
9428
9676
  }
9429
9677
  ]
9430
9678
  },
@@ -9454,7 +9702,7 @@
9454
9702
  "files": [
9455
9703
  {
9456
9704
  "path": "blocks/detail-panel/detail-panel.tsx",
9457
- "source": "import {\n Sheet,\n SheetContent,\n SheetDescription,\n SheetFooter,\n SheetHeader,\n SheetPanel,\n SheetTitle,\n} from '@atom63/ui-react'\nimport type { ReactNode } from 'react'\n\nexport const template = {\n id: 'detail-panel',\n kind: 'block',\n title: 'Detail panel',\n description:\n \"One record's fields in a side sheet over its list, with the record's actions in the footer, so people inspect a row without losing their place.\",\n category: 'collections',\n tags: ['detail', 'inspector', 'side panel', 'sheet', 'record', 'view'],\n readiness: 'ready',\n} as const\n\nexport interface DetailField {\n label: string\n value: ReactNode\n}\n\nexport interface DetailPanelProps {\n /** The record's actions; one `primary`, the rest `outline`. */\n actions?: ReactNode\n description?: string\n fields: readonly DetailField[]\n onOpenChange: (open: boolean) => void\n open: boolean\n title: string\n}\n\n/* Controlled by the list: the page owns which row is open. */\nexport function DetailPanel({\n actions,\n description,\n fields,\n onOpenChange,\n open,\n title,\n}: DetailPanelProps) {\n return (\n <Sheet onOpenChange={onOpenChange} open={open}>\n <SheetContent side=\"right\">\n <SheetHeader>\n <SheetTitle>{title}</SheetTitle>\n {description ? <SheetDescription>{description}</SheetDescription> : null}\n </SheetHeader>\n <SheetPanel>\n <dl className=\"grid grid-cols-[auto_minmax(0,1fr)] gap-x-6 gap-y-3 text-sm\">\n {fields.map(field => (\n <div className=\"contents\" key={field.label}>\n <dt className=\"text-muted-foreground\">{field.label}</dt>\n <dd className=\"text-foreground\">{field.value}</dd>\n </div>\n ))}\n </dl>\n </SheetPanel>\n {actions ? <SheetFooter>{actions}</SheetFooter> : null}\n </SheetContent>\n </Sheet>\n )\n}\n"
9705
+ "source": "import {\n Sheet,\n SheetContent,\n SheetDescription,\n SheetFooter,\n SheetHeader,\n SheetPanel,\n SheetTitle,\n} from '@atom63/ui-react'\nimport type { ReactNode } from 'react'\n\nexport const template = {\n id: 'detail-panel',\n kind: 'block',\n title: 'Detail panel',\n description:\n \"One record's fields in a side sheet over its list, with the record's actions in the footer, so people inspect a row without losing their place.\",\n category: 'collections',\n tags: ['detail', 'inspector', 'side panel', 'sheet', 'record', 'view'],\n readiness: 'ready',\n} as const\n\nexport interface DetailField {\n label: string\n value: ReactNode\n}\n\nexport interface DetailPanelProps {\n /** The record's actions; one `primary`, the rest `outline`. */\n actions?: ReactNode\n description?: string\n fields: readonly DetailField[]\n onOpenChange: (open: boolean) => void\n open: boolean\n title: string\n}\n\n/* Controlled by the list: the page owns which row is open. */\nexport function DetailPanel({\n actions,\n description,\n fields,\n onOpenChange,\n open,\n title,\n}: DetailPanelProps) {\n return (\n <Sheet onOpenChange={onOpenChange} open={open}>\n <SheetContent className=\"max-sm:w-full max-sm:max-w-none\" side=\"right\">\n <SheetHeader>\n <SheetTitle>{title}</SheetTitle>\n {description ? <SheetDescription>{description}</SheetDescription> : null}\n </SheetHeader>\n <SheetPanel>\n <dl className=\"grid grid-cols-[auto_minmax(0,1fr)] gap-x-6 gap-y-3 text-sm\">\n {fields.map(field => (\n <div className=\"contents\" key={field.label}>\n <dt className=\"text-muted-foreground\">{field.label}</dt>\n <dd className=\"text-foreground\">{field.value}</dd>\n </div>\n ))}\n </dl>\n </SheetPanel>\n {actions ? <SheetFooter>{actions}</SheetFooter> : null}\n </SheetContent>\n </Sheet>\n )\n}\n"
9458
9706
  }
9459
9707
  ]
9460
9708
  },
@@ -9647,7 +9895,7 @@
9647
9895
  "id": "tab-bar",
9648
9896
  "kind": "block",
9649
9897
  "title": "Tab bar",
9650
- "description": "The bottom navigation of a phone app: four or five destinations as an icon over a label, with the safe-area inset, the current one marked with aria-current. The app-view page places it last on phones.",
9898
+ "description": "The bottom navigation of a phone app: four or five destinations as an icon over a label, the current one marked with aria-current. Pass it to the AppView tabBar slot, which gives it the bottom safe-area inset.",
9651
9899
  "category": "layout",
9652
9900
  "tags": [
9653
9901
  "tab bar",
@@ -9667,7 +9915,7 @@
9667
9915
  "files": [
9668
9916
  {
9669
9917
  "path": "blocks/tab-bar/tab-bar.tsx",
9670
- "source": "import type { AnchorHTMLAttributes, ReactElement, ReactNode } from 'react'\n\nexport const template = {\n id: 'tab-bar',\n kind: 'block',\n title: 'Tab bar',\n description:\n 'The bottom navigation of a phone app: four or five destinations as an icon over a label, with the safe-area inset, the current one marked with aria-current. The app-view page places it last on phones.',\n category: 'layout',\n tags: ['tab bar', 'bottom navigation', 'mobile', 'phone', 'app', 'navigation', 'bottom bar'],\n readiness: 'draft',\n} as const\n\nexport interface TabBarItem {\n current?: boolean\n href: string\n /** A lucide icon element, marked `aria-hidden`. */\n icon: ReactNode\n label: string\n}\n\nexport type TabBarLinkProps = AnchorHTMLAttributes<HTMLAnchorElement> & { href: string }\n\nexport interface TabBarProps {\n /** The navigation landmark's name. */\n label?: string\n items: readonly TabBarItem[]\n /**\n * Renders a destination link, for a router's own link component; a plain\n * anchor by default. It receives the anchor's props, `href` included.\n */\n renderLink?: (props: TabBarLinkProps) => ReactElement\n}\n\nconst anchor = ({ children, ...props }: TabBarLinkProps) => <a {...props}>{children}</a>\n\n/*\n * A navigation landmark for the bottom of a phone layout. The layout places it\n * (the app-view page's tabBar slot puts it last on phones); it is not fixed, so\n * it never covers content. On iOS the same intent is SwiftUI's TabView; this\n * block is the web side. Each destination is a link at least 56px tall, and the\n * current one carries aria-current, not only the accent color.\n */\nexport function TabBar({ items, label = 'Main', renderLink = anchor }: TabBarProps) {\n return (\n <nav\n aria-label={label}\n className=\"border-border bg-background border-t pb-[env(safe-area-inset-bottom)]\"\n >\n <ul className=\"mx-auto flex max-w-lg\">\n {items.map(item => (\n <li className=\"flex-1\" key={item.href}>\n {renderLink({\n 'aria-current': item.current ? 'page' : undefined,\n children: (\n <>\n <span className=\"[&>svg]:size-6\">{item.icon}</span>\n <span>{item.label}</span>\n </>\n ),\n className: `flex min-h-14 flex-col items-center justify-center gap-0.5 text-[0.6875rem] font-medium focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-ring ${\n item.current ? 'text-selected-foreground' : 'text-muted-foreground'\n }`,\n href: item.href,\n })}\n </li>\n ))}\n </ul>\n </nav>\n )\n}\n"
9918
+ "source": "import type { AnchorHTMLAttributes, ReactElement, ReactNode } from 'react'\n\nexport const template = {\n id: 'tab-bar',\n kind: 'block',\n title: 'Tab bar',\n description:\n 'The bottom navigation of a phone app: four or five destinations as an icon over a label, the current one marked with aria-current. Pass it to the AppView tabBar slot, which gives it the bottom safe-area inset.',\n category: 'layout',\n tags: ['tab bar', 'bottom navigation', 'mobile', 'phone', 'app', 'navigation', 'bottom bar'],\n readiness: 'draft',\n} as const\n\nexport interface TabBarItem {\n current?: boolean\n href: string\n /** A lucide icon element, marked `aria-hidden`. */\n icon: ReactNode\n label: string\n}\n\nexport type TabBarLinkProps = AnchorHTMLAttributes<HTMLAnchorElement> & { href: string }\n\nexport interface TabBarProps {\n /** The navigation landmark's name. */\n label?: string\n items: readonly TabBarItem[]\n /**\n * Renders a destination link, for a router's own link component; a plain\n * anchor by default. It receives the anchor's props, `href` included.\n */\n renderLink?: (props: TabBarLinkProps) => ReactElement\n}\n\nconst anchor = ({ children, ...props }: TabBarLinkProps) => <a {...props}>{children}</a>\n\n/*\n * A navigation landmark for the bottom of a phone layout. The layout places it\n * (the app-view page's tabBar slot puts it last on phones); it is not fixed, so\n * it never covers content. On iOS the same intent is SwiftUI's TabView; this\n * block is the web side. Each destination is a link at least 56px tall, and the\n * current one carries aria-current, not only the accent color.\n */\nexport function TabBar({ items, label = 'Main', renderLink = anchor }: TabBarProps) {\n return (\n <nav aria-label={label} className=\"border-border bg-background border-t\">\n <ul className=\"mx-auto flex max-w-lg\">\n {items.map(item => (\n <li className=\"flex-1\" key={item.href}>\n {renderLink({\n 'aria-current': item.current ? 'page' : undefined,\n children: (\n <>\n <span className=\"[&>svg]:size-6\">{item.icon}</span>\n <span>{item.label}</span>\n </>\n ),\n className: `flex min-h-14 flex-col items-center justify-center gap-0.5 text-[0.6875rem] font-medium focus-visible:outline-2 focus-visible:-outline-offset-2 focus-visible:outline-ring ${\n item.current ? 'text-selected-foreground' : 'text-muted-foreground'\n }`,\n href: item.href,\n })}\n </li>\n ))}\n </ul>\n </nav>\n )\n}\n"
9671
9919
  }
9672
9920
  ]
9673
9921
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@atom63/cli",
3
- "version": "0.1.0-beta.0",
3
+ "version": "0.1.0-beta.1",
4
4
  "description": "Query the Atom63 design system from the command line or an MCP host: components, contracts, tokens, examples and docs",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -26,12 +26,12 @@
26
26
  "access": "public"
27
27
  },
28
28
  "devDependencies": {
29
- "@modelcontextprotocol/client": "2.3.1",
30
- "vite": "8.3.4"
29
+ "@modelcontextprotocol/client": "2.4.0",
30
+ "vite": "8.3.7"
31
31
  },
32
32
  "dependencies": {
33
- "@modelcontextprotocol/server": "2.3.0",
34
- "zod": "^4.6.5"
33
+ "@modelcontextprotocol/server": "2.4.0",
34
+ "zod": "^4.6.7"
35
35
  },
36
36
  "scripts": {
37
37
  "generate:index": "node scripts/build-index.mjs",
package/src/bin.mjs CHANGED
@@ -145,7 +145,8 @@ const invoked = process.argv[1] ? realpathSync(process.argv[1]) : ''
145
145
  if (invoked === fileURLToPath(import.meta.url) && process.argv[2] === 'mcp') {
146
146
  // Loaded only here, so plain queries never pay for the MCP SDK.
147
147
  const { serve } = await import('./mcp.mjs')
148
- serve()
148
+ const tools = process.env.ATOM63_MCP_TOOLS?.split(',').filter(Boolean)
149
+ serve({ tools })
149
150
  } else if (invoked === fileURLToPath(import.meta.url)) {
150
151
  const { exitCode, json, output } = runCli(process.argv.slice(2))
151
152
  ;(exitCode === 0 || json ? process.stdout : process.stderr).write(`${output}\n`)
package/src/mcp.mjs CHANGED
@@ -41,10 +41,13 @@ const result = (envelope, isError = false) => ({
41
41
  ...(isError ? { isError: true } : {}),
42
42
  })
43
43
 
44
- /** A new server instance with one read-only tool per query command. */
45
- export function createAtomServer(index = loadIndex()) {
44
+ /** A new server instance with the selected read-only query tools. */
45
+ export function createAtomServer(index = loadIndex(), { tools } = {}) {
46
46
  const server = new McpServer({ name: 'atom63', version: packageVersion })
47
- for (const command of commands.filter(candidate => !candidate.writes)) {
47
+ const allowed = tools ? new Set(tools) : null
48
+ for (const command of commands.filter(
49
+ candidate => !candidate.writes && (!allowed || allowed.has(candidate.name))
50
+ )) {
48
51
  server.registerTool(
49
52
  command.name,
50
53
  {
@@ -67,6 +70,6 @@ export function createAtomServer(index = loadIndex()) {
67
70
  }
68
71
 
69
72
  /** Serve over stdio until the host closes the connection. */
70
- export function serve() {
71
- return serveStdio(() => createAtomServer())
73
+ export function serve({ tools } = {}) {
74
+ return serveStdio(() => createAtomServer(undefined, { tools }))
72
75
  }
package/src/rules.mjs CHANGED
@@ -46,6 +46,12 @@ export const rules = [
46
46
  rule: 'Controls drawn over photos or video use the `--a63-on-media-*` and `--a63-media-*` tokens.',
47
47
  why: 'Theme colors are meaningless on an unknown picture; these hold contrast on any image.',
48
48
  },
49
+ {
50
+ id: 'content-colors',
51
+ rule: 'Draw content that carries its own colours (illustrations, game pieces, map and chart series, story rings, category marks) with the `--a63-category-{hue}` palette: 18 hues, each with `-subtle` and `-subtle-foreground`, as utilities such as `bg-category-green` and `text-category-green-subtle-foreground`. For another shade, mix two tokens with `color-mix(in oklch, var(--a63-category-green) 75%, var(--a63-text-primary))`, never a colour keyword or value.',
52
+ why: 'The palette follows the theme and the mode, so content stays legible in dark mode. A literal colour, or a keyword such as `black` inside `color-mix()`, fails `raw-color` and makes a vibe case invalid.',
53
+ check: ['raw-color'],
54
+ },
49
55
  {
50
56
  id: 'logical-directions',
51
57
  rule: 'Use logical properties and utilities (`margin-inline-start`, `ps-4`, `text-start`, `border-s`), not left and right.',
package/src/synonyms.mjs CHANGED
@@ -7,7 +7,7 @@
7
7
  */
8
8
  export const synonyms = {
9
9
  bar: ['progress'],
10
- bubble: ['chat-message'],
10
+ bubble: ['message', 'chat-message'],
11
11
  chatbot: ['chat-message', 'chat-composer'],
12
12
  checkmark: ['animated-check', 'checkbox'],
13
13
  chip: ['toggle-group', 'toggle', 'button', 'badge'],
@@ -210,6 +210,24 @@ const chatSurfaces = [
210
210
  },
211
211
  ]
212
212
 
213
+ // A thread between people, not an assistant: Message, not ChatMessage.
214
+ const peopleThread = [
215
+ {
216
+ id: 'component:message',
217
+ note: 'Person-to-person thread: MessageList (log) and Message with direction incoming or outgoing, position in a run (single, first, middle, last), time and delivery status; MessageEvent for calls and dates. ChatMessage is for an AI assistant.',
218
+ },
219
+ { id: 'example:message/Thread' },
220
+ { id: 'component:avatar' },
221
+ ]
222
+
223
+ const storyRings = [
224
+ {
225
+ id: 'component:avatar',
226
+ note: 'Story ring: Avatar ring="unseen" or "seen"; set --a63-avatar-ring-fill to a gradient of --a63-category-* for a multicolour ring. iOS: AtomAvatar(ring:ringStyle:).',
227
+ },
228
+ { id: 'example:avatar/StoryRings' },
229
+ ]
230
+
213
231
  const chatComposer = [
214
232
  {
215
233
  id: 'component:chat-composer',
@@ -445,6 +463,22 @@ export const topics = {
445
463
  copilot: chatSurfaces,
446
464
  'chat bubble': [{ id: 'component:chat-message' }],
447
465
  'chat message': [{ id: 'component:chat-message' }, chatSurfaces[0]],
466
+ messaging: peopleThread,
467
+ messenger: peopleThread,
468
+ 'messages app': peopleThread,
469
+ 'direct message': peopleThread,
470
+ 'direct messages': peopleThread,
471
+ dm: peopleThread,
472
+ 'text message': peopleThread,
473
+ 'chat thread': peopleThread,
474
+ 'message thread': peopleThread,
475
+ 'read receipt': peopleThread,
476
+ 'delivery status': peopleThread,
477
+ 'missed call': peopleThread,
478
+ 'group chat': peopleThread,
479
+ story: storyRings,
480
+ stories: storyRings,
481
+ 'story ring': storyRings,
448
482
  'chat composer': chatComposer,
449
483
  'message bubble': [{ id: 'component:chat-message' }],
450
484
  'chat input': chatComposer,
package/src/templates.mjs CHANGED
@@ -5,7 +5,7 @@
5
5
  import { existsSync, mkdirSync, writeFileSync } from 'node:fs'
6
6
  import path from 'node:path'
7
7
 
8
- import { AtomError, closest, groundFor, queryTerms, score, search } from './core.mjs'
8
+ import { AtomError, closest, groundFor, queryTerms, score, search, topicHits } from './core.mjs'
9
9
  import { rules } from './rules.mjs'
10
10
 
11
11
  export const templateKinds = ['page', 'block']
@@ -162,15 +162,15 @@ export function isPhoneIdea(idea) {
162
162
  return terms.some(term => phoneWords.has(term)) || /\b(3[2-9]\d|4[0-3]\d) ?px\b/i.test(idea)
163
163
  }
164
164
 
165
- /* What a phone idea is told to build on: the app-view template's phone layout. */
165
+ /* What a phone idea is told to build on: AppView's phone layout. */
166
166
  const phoneScreen = {
167
167
  template: 'app-view',
168
- use: 'Use AppView layout="phone" for the screen: edge to edge with no card or inset, safe-area aware, the top bar optional, and the tab bar docked at the bottom. It sets phone-sized type and controls inside it (data-a63-form-factor="phone": body 17px, subhead 15px, footnote 13px, 44px controls), so keep rows and labels on the defaults or the text roles (text-body, text-subhead, text-footnote) instead of shrinking them with text-sm or text-xs. Only the main region scrolls, so its last row stays visible above the tab bar. On a screen with no tab bar (a chat, a detail or a checkout step), leave tabBar out and dock the composer or action bar as bottomBar. The default layout ("window") is a padded desktop window with a rounded main card; do not use it on a phone.',
168
+ use: 'Use AppView layout="phone" for the screen: edge to edge with no card or inset, safe-area aware, the top bar optional, and the tab bar docked at the bottom. It sets phone-sized type and controls inside it (data-a63-form-factor="phone": body 17px, subhead 15px, footnote 13px, 44px controls), so keep rows and labels on the defaults or the text roles (text-body, text-subhead, text-footnote) instead of shrinking them with text-sm or text-xs. Only the main region scrolls, so its last row stays visible above the tab bar. On a screen with no tab bar (a chat, a detail or a checkout step), leave tabBar out and dock the composer or action bar as bottomBar. Put a control that floats over the content, such as a scroll-to-bottom button, in overlay. The default layout ("window") is a padded desktop window with a rounded main card; do not use it on a phone.',
169
169
  files:
170
- 'AppView ships in no package: it is the app-view page template. Paste pages/app-view/app-view.tsx and blocks/tab-bar/tab-bar.tsx, which `atom63 template app-view` prints in full (or run `atom63 copy app-view src`). Its AppViewPhonePage is the phone sample to start from.',
170
+ 'Import AppView from @atom63/ui-react/layout. The tab bar is the tab-bar block: paste blocks/tab-bar/tab-bar.tsx, which `atom63 template app-view` prints with the sample pages (or run `atom63 copy app-view src`). Its AppViewPhonePage is the phone sample to start from.',
171
171
  imports: [
172
172
  "import { House, Search } from 'lucide-react'",
173
- "import { AppView } from './pages/app-view/app-view'",
173
+ "import { AppView } from '@atom63/ui-react/layout'",
174
174
  "import { TabBar } from './blocks/tab-bar/tab-bar'",
175
175
  ],
176
176
  snippet: [
@@ -318,7 +318,12 @@ export function build(index, idea) {
318
318
  const named = found.map(result => result.id)
319
319
  // A topic note ("track list" → Table variant="plain") replaces the summary.
320
320
  const summaries = new Map(found.map(result => [result.id, result.summary]))
321
- const components = [...new Set([...used, ...named])].slice(0, 8).map(slug => ({
321
+ // A component a topic names for this idea ("messaging" → Message) leads, so the
322
+ // templates' own components cannot crowd it out of the nine.
323
+ const hits = topicHits(idea)
324
+ const curated = named.filter(slug => hits.has(`component:${slug}`))
325
+ // Nine: the app-view page brings eight, with its AppView frame, and the idea's own pick still fits.
326
+ const components = [...new Set([...curated, ...used, ...named])].slice(0, 9).map(slug => ({
322
327
  slug,
323
328
  summary: summaries.get(slug) ?? bySlug.get(slug).summary,
324
329
  next: `atom63 component ${slug}`,