canon-ds 0.1.0

package/lib/components/social-button.mjs

@@ -0,0 +1,119 @@
+import { CONTROL, FOCUS_RING, RESET_BUTTON, TRANSITION_COLORS, STATE, ex, typeStyle } from "./_shared.mjs";
+const outlineTheme = (icon) => ({ bg: '{color.bg-surface}', hoverBg: '{color.bg-subtle}', fg: '{color.fg-default}', border: '{color.border-control}', icon });
+const inverseTheme = { bg: '{color.bg-inverse}', hoverBg: 'color-mix(in srgb, {color.bg-inverse} 88%, {color.bg-surface})', fg: '{color.fg-inverse}', border: 'transparent', icon: 'currentColor' };
+const blueTheme = (step, hover) => ({ bg: `{blue.${step}}`, hoverBg: `{blue.${hover}}`, fg: '{white}', border: 'transparent', icon: 'currentColor' });
+const PAINT = {
+    google: { brand: blueTheme('600', '700'), gray: outlineTheme('{color.fg-default}'), color: outlineTheme('{blue.500}') },
+    apple: { brand: inverseTheme, gray: outlineTheme('{color.fg-default}'), color: outlineTheme('{color.fg-default}') },
+    github: { brand: inverseTheme, gray: outlineTheme('{color.fg-default}'), color: outlineTheme('{color.fg-default}') },
+    facebook: { brand: blueTheme('600', '700'), gray: outlineTheme('{color.fg-default}'), color: outlineTheme('{blue.600}') },
+};
+const compound = Object.entries(PAINT).flatMap(([social, themes]) => Object.entries(themes).map(([theme, t]) => ({
+    when: { social, theme },
+    block: {
+        root: { 'background-color': t.bg, color: t.fg, 'border-color': t.border },
+        icon: { color: t.icon },
+        '@states': { hover: { root: { 'background-color': t.hoverBg } }, active: { root: { 'background-color': t.hoverBg } } },
+    },
+})));
+const LG = new Set(['lg', 'xl']);
+const sizeBlock = (s) => ({
+    root: { height: CONTROL[s].height, 'padding-inline': CONTROL[s].px, 'font-size': CONTROL[s].font, gap: LG.has(s) ? '{space.3}' : '{space.2.5}' },
+});
+/** Monochrome glyphs: a G-shaped arc, a fruit outline with a stem, a circle with code brackets, a circle with an f. */
+const GLYPH = {
+    google: '<path d="M12 12h8.5a8.5 8.5 0 1 1-2.5-6"/>',
+    apple: '<circle cx="12" cy="13.5" r="6.5"/><path d="M12 7c0-2.2 1.3-3.5 3.5-3.5"/>',
+    github: '<circle cx="12" cy="12" r="9"/><path d="M9.5 9.5L7 12l2.5 2.5M14.5 9.5L17 12l-2.5 2.5"/>',
+    facebook: '<circle cx="12" cy="12" r="9"/><path d="M13.5 20v-6.5h2.2l.3-2.5h-2.5V9.6c0-.8.4-1.3 1.2-1.3h1.4V6.2h-2c-2 0-3.1 1.2-3.1 3.1V11H9v2.5h2V20"/>',
+};
+const NAME = { google: 'Google', apple: 'Apple', github: 'GitHub', facebook: 'Facebook' };
+const icon = (social) => `<svg class="cn-social-button__icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${GLYPH[social]}</svg>`;
+const btn = (social, theme = 'gray', size = 'md', attrs = '', verb = 'Sign in with') => `<button type="button" class="cn-social-button" data-social="${social}" data-theme="${theme}" data-size="${size}"${attrs}>${icon(social)}<span class="cn-social-button__label">${verb} ${NAME[social]}</span></button>`;
+const stack = (...items) => `<div style="display:flex;flex-direction:column;gap:var(--cn-space-3);max-width:360px">${items.join('')}</div>`;
+export const socialButton = {
+    name: 'SocialButton',
+    slug: 'social-button',
+    category: 'actions',
+    description: 'A sign-in button for an identity provider: the Button box with a 24px logo slot and a "Sign in with …" label. Three themes: the provider\'s brand fill, a white gray button with a monochrome logo, or a white button with the colored logo.',
+    usage: 'Auth screens only (sign in, sign up, connect an account). Stack the providers you support in a fixed order under the email form, all in the same theme and size. Never use it for sharing links or as a generic icon button.',
+    anatomy: [
+        { part: 'root', element: 'button', description: 'The button (or an <a> when the flow is a redirect). Full width in auth forms. Carries data-social, data-theme, data-size.' },
+        { part: 'icon', element: 'svg', description: '24px logo slot. Monochrome (currentColor) in brand and gray themes, the provider color in the color theme. aria-hidden.' },
+        { part: 'label', element: 'span', description: '"Sign in with Google" / "Continue with Apple": verb + provider name, sentence case.' },
+    ],
+    props: {
+        social: { values: ['google', 'apple', 'github', 'facebook'], default: 'google', description: 'The identity provider. It selects the brand fill (brand theme) and the logo color (color theme); the logo itself comes from the markup.' },
+        theme: { values: ['brand', 'gray', 'color'], default: 'gray', description: 'gray = white, hairline, monochrome logo: the default that sits quietly under an email form; brand = the provider\'s fill with a white logo, for a single prominent provider; color = white with the provider-colored logo, for a row of several providers on marketing-style auth pages.' },
+        size: { values: ['md', 'lg', 'xl'], default: 'md', description: 'Button heights md / lg / xl (40 / 44 / 48px in the reference scale). Match the size of the email form\'s submit button.' },
+    },
+    states: {
+        hover: STATE.hover(),
+        active: STATE.active(),
+        focus: STATE.focus(),
+        disabled: STATE.disabled(),
+    },
+    base: {
+        root: {
+            ...RESET_BUTTON,
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            gap: '{space.2.5}',
+            'flex-shrink': '0',
+            'white-space': 'nowrap',
+            ...typeStyle('label-md'),
+            'font-size': CONTROL.md.font,
+            height: CONTROL.md.height,
+            'padding-inline': CONTROL.md.px,
+            'border-radius': '{radius.control}',
+            border: '{border.width.thin} solid transparent',
+            'box-shadow': '{shadow.xs}',
+            ...TRANSITION_COLORS,
+        },
+        icon: { display: 'block', 'flex-shrink': '0', width: '{size.icon.xl}', height: '{size.icon.xl}', 'pointer-events': 'none', transition: 'inherit' },
+        label: { display: 'inline-block', 'padding-inline': '{space.0.5}' },
+        '@states': {
+            focus: { root: { ...FOCUS_RING, 'box-shadow': '{shadow.xs}, {shadow.focus}' } },
+            disabled: { root: { opacity: '{opacity.disabled}', cursor: 'not-allowed' } },
+        },
+    },
+    variants: {
+        social: { google: { root: {} }, apple: { root: {} }, github: { root: {} }, facebook: { root: {} } },
+        theme: {
+            brand: { root: {} },
+            gray: { root: {} },
+            color: { root: {} },
+        },
+        size: { md: sizeBlock('md'), lg: sizeBlock('lg'), xl: sizeBlock('xl') },
+    },
+    compound,
+    extraCss: `
+.cn-social-button[data-full] { width: 100%; }`,
+    examples: [
+        ex('Gray (default)', stack(btn('google'), btn('apple'), btn('github'), btn('facebook')), 'White with a hairline and a monochrome logo; the quiet default under an email form.'),
+        ex('Brand', stack(btn('google', 'brand'), btn('apple', 'brand'), btn('github', 'brand'), btn('facebook', 'brand')), 'The provider fill with a white logo, for one prominent provider.'),
+        ex('Color', stack(btn('google', 'color'), btn('apple', 'color'), btn('github', 'color'), btn('facebook', 'color')), 'White with the provider-colored logo, for a row of several providers.'),
+        ex('Sizes', stack(btn('google', 'gray', 'md', '', 'Continue with'), btn('google', 'gray', 'lg', '', 'Continue with'), btn('google', 'gray', 'xl', '', 'Continue with')), 'md / lg / xl follow the control heights; text grows to 16px on lg and xl.'),
+        ex('Full width and disabled', stack(btn('github', 'gray', 'md', ' data-full'), btn('google', 'gray', 'md', ' data-full disabled')), 'data-full stretches the button to the form width; disabled keeps the layout and dims it.'),
+    ],
+    recipes: [
+        ex('Under an email form', `<div style="display:flex;flex-direction:column;gap:var(--cn-space-3);max-width:360px"><button type="submit" class="cn-button" data-variant="primary" data-size="md" style="width:100%"><span class="cn-button__label">Sign in</span></button><div style="display:flex;align-items:center;gap:var(--cn-space-3);color:var(--cn-color-fg-subtle)" class="cn-text-body-xs"><span style="flex:1;height:1px;background:var(--cn-color-border-default)"></span>or<span style="flex:1;height:1px;background:var(--cn-color-border-default)"></span></div>${btn('google', 'gray', 'md', ' data-full')}${btn('apple', 'gray', 'md', ' data-full')}</div>`, 'Primary submit first, an "or" divider, then the providers in gray at the same size.'),
+    ],
+    rules: [
+        'Label = verb + provider: "Sign in with Google" on sign-in screens, "Continue with Google" when the same button signs up. Never the provider name alone, never "Login".',
+        'One theme and one size per screen. gray under an email form; color when providers stand alone in a row; brand only for a single provider that is the main way in.',
+        'Order providers by usage in your audience and keep that order on every screen; put the email form above them, never below.',
+        'Full width (data-full) inside auth forms; intrinsic width only in a horizontal row of icon-heavy color buttons.',
+        'The logo slot is 24px; use the provider\'s official monochrome or color asset in production and respect its clear-space rules. The example glyphs are placeholders.',
+        'Never add a trailing arrow or a second icon; the logo is the only icon.',
+        'While the provider popup is open set aria-busy="true" and disable the other providers to avoid two flows at once.',
+    ],
+    a11y: [
+        'It is a <button type="button"> (or an <a href> for redirect flows) with the visible label as its accessible name; the logo is aria-hidden.',
+        'Focus ring on :focus-visible only, stacked over the resting shadow so the ring is visible on filled brand buttons too.',
+        'Disabled providers stay visible and readable (opacity only); explain why when it matters ("Apple sign-in is not available in this region").',
+        'Contrast: brand fills use the 600 step with white text; gray and color themes use default ink on the surface.',
+    ],
+    related: ['button', 'app-store-button', 'divider', 'input'],
+};

package/lib/components/spinner.mjs

@@ -0,0 +1,69 @@
+import { ex } from "./_shared.mjs";
+const SIZE_ICON = { xs: '{size.icon.xs}', sm: '{size.icon.sm}', md: '{size.icon.md}', lg: '{size.icon.lg}', xl: '{size.icon.xl}' };
+const TONE_COLOR = { current: 'currentColor', muted: '{color.fg-subtle}', action: '{color.fg-action}', 'on-action': '{color.fg-on-action}' };
+export const spinner = {
+    name: 'Spinner',
+    slug: 'spinner',
+    category: 'feedback',
+    description: 'Small rotating ring for a wait without a known duration. A 2px current-color circle with one transparent quarter, spinning at 0.7s; it inherits the text color so it fits inside buttons, rows and empty states.',
+    usage: 'Use next to a short sentence while something loads and no layout is known yet ("Searching 212 companies…"), or inside a control that is busy. For loading content whose shape is known use Skeleton; for a measurable task use Progress. Never use more than one spinner in view.',
+    anatomy: [
+        { part: 'root', element: 'span', description: 'The ring. role="status"; contains a visually hidden label (.cn-sr-only) so screen readers announce what is happening.' },
+    ],
+    props: {
+        size: {
+            values: ['xs', 'sm', 'md', 'lg', 'xl'],
+            default: 'md',
+            description: 'Diameter from the icon scale: xs 12px (inside badges), sm 14px (inside sm buttons and table rows), md 16px (default, inline with body text), lg 20px (empty states), xl 24px (page-level loading).',
+        },
+        tone: {
+            values: ['current', 'muted', 'action', 'on-action'],
+            default: 'current',
+            description: 'current = inherits the text color (default, inside buttons and rows); muted = subtle grey for quiet loading; action = the action color for a primary wait; on-action = the text color used on filled action surfaces.',
+        },
+    },
+    states: {},
+    base: {
+        root: {
+            display: 'inline-block',
+            'flex-shrink': '0',
+            width: '{size.icon.md}',
+            height: '{size.icon.md}',
+            'border-radius': '{radius.full}',
+            border: '{border.width.medium} solid currentColor',
+            'border-right-color': 'transparent',
+            color: 'currentColor',
+            'vertical-align': 'middle',
+            animation: 'cn-spinner-spin 0.7s linear infinite',
+        },
+    },
+    variants: {
+        size: Object.fromEntries(Object.entries(SIZE_ICON).map(([s, v]) => [s, { root: { width: v, height: v, ...(s === 'xs' || s === 'sm' ? { 'border-width': '1.5px' } : {}) } }])),
+        tone: Object.fromEntries(Object.entries(TONE_COLOR).map(([t, c]) => [t, { root: { color: c } }])),
+    },
+    extraCss: `
+@keyframes cn-spinner-spin { to { transform: rotate(360deg); } }`,
+    examples: [
+        ex('Default (md, current color)', `<span class="cn-spinner" data-size="md" data-tone="current" role="status"><span class="cn-sr-only">Loading</span></span>`),
+        ex('Sizes', `<span class="cn-spinner" data-size="xs" data-tone="current" role="status"><span class="cn-sr-only">Loading</span></span> <span class="cn-spinner" data-size="sm" data-tone="current" role="status"><span class="cn-sr-only">Loading</span></span> <span class="cn-spinner" data-size="md" data-tone="current" role="status"><span class="cn-sr-only">Loading</span></span> <span class="cn-spinner" data-size="lg" data-tone="current" role="status"><span class="cn-sr-only">Loading</span></span> <span class="cn-spinner" data-size="xl" data-tone="current" role="status"><span class="cn-sr-only">Loading</span></span>`),
+        ex('Muted with a sentence', `<div style="display:inline-flex;align-items:center;gap:var(--cn-space-2);color:var(--cn-color-fg-muted)"><span class="cn-spinner" data-size="sm" data-tone="muted" role="status"><span class="cn-sr-only">Loading</span></span><span class="cn-text-body-sm">Searching 212 companies in Japan…</span></div>`),
+        ex('Action tone', `<span class="cn-spinner" data-size="lg" data-tone="action" role="status"><span class="cn-sr-only">Verifying</span></span>`),
+        ex('On a filled action surface', `<span style="display:inline-flex;align-items:center;gap:var(--cn-space-2);padding:var(--cn-space-2) var(--cn-space-3);border-radius:var(--cn-radius-md);background:var(--cn-color-bg-action);color:var(--cn-color-fg-on-action)"><span class="cn-spinner" data-size="sm" data-tone="on-action" role="status"><span class="cn-sr-only">Sending</span></span><span class="cn-text-label-md">Sending…</span></span>`, 'Inside a real Button use data-loading instead; the Button draws its own spinner.'),
+    ],
+    rules: [
+        'One spinner in view at a time. Several loading areas share one spinner at the top of the region, or use Skeleton.',
+        'Pair it with a sentence that names what is happening ("Searching 212 companies…"); a lone spinner is only acceptable inside a control.',
+        'Do not show it for waits under 300ms; flashing spinners feel slower than nothing.',
+        'Inside a Button use data-loading; the Button already has its own spinner sized to the control.',
+        'Size follows the text it sits next to: sm with body-sm, md with body-md, lg/xl only in empty states and page-level loading.',
+        'Tone current by default; muted for background loading; action only for a primary wait the user asked for.',
+        'Never place a spinner inside a Toast or a Badge.',
+    ],
+    a11y: [
+        'role="status" on the ring with a visually hidden text (.cn-sr-only) that says what is loading.',
+        'When the wait ends, update the same live region with the result ("38 companies found") so the change is announced.',
+        'The animation stops under prefers-reduced-motion (base.css); the static ring remains visible.',
+        'Do not put the spinner inside aria-hidden containers when it is the only feedback.',
+    ],
+    related: ['progress', 'skeleton', 'button'],
+};

package/lib/components/stat.mjs

@@ -0,0 +1,120 @@
+import { ex, ICON, typeStyle } from "./_shared.mjs";
+// A measured readout: a mono label, a clear value and a separate change indicator.
+const HAIRLINE = '{border.width.thin} solid {color.border-default}';
+const ring = (color) => `inset 0 0 0 1px ${color}`;
+const ARROW = {
+    up: '<svg class="cn-stat__icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M8 13V3M4 7l4-4 4 4"/></svg>',
+    down: '<svg class="cn-stat__icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M8 3v10M4 9l4 4 4-4"/></svg>',
+    flat: '<svg class="cn-stat__icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><path d="M3 8h10"/></svg>',
+};
+const tile = (o) => {
+    const trend = o.trend ?? 'flat';
+    return `<div class="cn-stat" data-size="${o.size ?? 'md'}" data-variant="${o.variant ?? 'card'}" data-trend="${trend}"${o.sentiment ? ` data-sentiment="${o.sentiment}"` : ''}${o.style ? ` style="${o.style}"` : ''}>${o.media ? `<div class="cn-stat__media">${o.media}</div>` : ''}<div class="cn-stat__label">${o.label}</div><div class="cn-stat__value">${o.value}</div>${o.delta ? `<div class="cn-stat__delta"${o.badge ? ' data-badge' : ''}>${ARROW[trend]}<span>${o.delta}</span></div>` : ''}${o.description ? `<div class="cn-stat__description">${o.description}</div>` : ''}${o.actions ? `<div class="cn-stat__actions">${o.actions}</div>` : ''}</div>`;
+};
+const FEATURED = (i) => `<span class="cn-featured-icon" data-theme="modern" data-tone="gray" data-size="md" data-shape="square">${ICON[i].replace('cn-icon', 'cn-featured-icon__icon')}</span>`;
+const VIEW = `<button type="button" class="cn-button" data-variant="link-color" data-size="sm"><span class="cn-button__label">View report</span>${ICON.arrow.replace('cn-icon', 'cn-button__icon')}</button>`;
+export const stat = {
+    name: 'Stat',
+    slug: 'stat',
+    category: 'data-display',
+    description: 'A metric readout with a compact mono label and one semibold tabular number, a change indicator with an arrow (green up, red down) or as a pill, a "vs last month" note, optionally a featured icon above and a "View report" footer. Direction is a fact; whether it is good is a separate attribute.',
+    usage: 'Dashboards and page headers that summarize a workspace ("Active users 2,420", "Conversion 4.2%"). Rows of 3–4 tiles. Not for counts inside navigation (Counter) or for a value inside a table (plain tabular text).',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'Column of media, label, value, delta + description, actions. Plain, or framed as the metric card (white, gray-200 ring, flat edge and token-defined corners, 20 × 24px padding).' },
+        { part: 'media', element: 'div', description: 'Optional 40px FeaturedIcon (modern, gray) above the label, 16px before it.', optional: true },
+        { part: 'label', element: 'div', description: 'What is measured, 14px medium fg-muted. 1–3 words ("Active users").' },
+        { part: 'value', element: 'div', description: 'The number, semibold, tabular figures: 24 / 30 / 36px by size. Include the unit in the string ("41%", "2.1h", "$412k").' },
+        { part: 'delta', element: 'div', description: 'Optional change vs the previous period: 16px arrow + 14px medium text ("12%"). Colored by trend and sentiment; data-badge renders it as a tinted pill.', optional: true },
+        { part: 'icon', element: 'svg', description: '16px arrow inside the delta: up, down or flat, matching data-trend.', optional: true },
+        { part: 'description', element: 'div', description: 'Optional 14px fg-muted note after the delta: period, source or definition ("vs last month").', optional: true },
+        { part: 'actions', element: 'div', description: 'Optional footer on a hairline (bleeds to the card edges, 16 × 24px padding) holding a link-color Button ("View report").', optional: true },
+    ],
+    props: {
+        size: {
+            values: ['sm', 'md', 'lg'],
+            default: 'md',
+            description: 'Size of the value: sm = 24/32 semibold (inside cards and drawers); md = 30/38 (the default readout, dashboard rows); lg = 36/44 (one hero number per page).',
+        },
+        variant: {
+            values: ['plain', 'card'],
+            default: 'card',
+            description: 'card = the metric card: white, gray-200 ring, flat edge and token-defined corners, 20 × 24px padding (standalone tiles on the canvas); plain = no frame, for stats inside a Card, a header or next to a chart.',
+        },
+        trend: {
+            values: ['up', 'down', 'flat'],
+            default: 'flat',
+            description: 'Direction of the delta: up = increased (green), down = decreased (red), flat = unchanged (muted). Direction only; add data-sentiment="good|bad" when up is bad or down is good.',
+        },
+    },
+    states: {},
+    base: {
+        // A wrapping row: media, label, value and actions span the full width; delta and description share one line.
+        root: { display: 'flex', 'flex-wrap': 'wrap', 'align-items': 'center', gap: '{space.2}', 'min-width': '0', color: '{color.fg-default}' },
+        media: { display: 'flex', width: '100%', 'margin-bottom': '{space.2}' },
+        label: { width: '100%', ...typeStyle('kicker'), color: '{color.fg-muted}' },
+        value: {
+            width: '100%',
+            ...typeStyle('heading-lg'),
+            'font-variant-numeric': 'tabular-nums',
+            color: '{color.fg-default}',
+            'overflow-wrap': 'anywhere',
+        },
+        delta: { display: 'inline-flex', 'align-items': 'center', gap: '{space.1}', ...typeStyle('label-sm'), color: '{color.fg-muted}', 'font-variant-numeric': 'tabular-nums' },
+        icon: { width: '{size.icon.sm}', height: '{size.icon.sm}', 'flex-shrink': '0' },
+        description: { ...typeStyle('body-md'), color: '{color.fg-muted}' },
+        actions: { display: 'flex', width: '100%', 'align-items': 'center', 'justify-content': 'flex-end', gap: '{space.3}', 'margin-top': '{space.2}', 'padding-top': '{space.4}', 'border-top': HAIRLINE },
+    },
+    variants: {
+        size: {
+            sm: { root: { gap: '{space.1.5}' }, value: { ...typeStyle('heading-md') }, delta: { ...typeStyle('label-xs') } },
+            md: { value: { ...typeStyle('heading-lg') } },
+            lg: { root: { gap: '{space.3}' }, value: { ...typeStyle('heading-xl') }, delta: { ...typeStyle('label-md') }, description: { ...typeStyle('body-lg') } },
+        },
+        variant: {
+            plain: { root: {} },
+            card: { root: { 'background-color': '{color.bg-surface}', 'box-shadow': `${ring('{color.border-default}')}, {shadow.xs}`, 'border-radius': '{radius.card}', padding: '{space.5} {space.6}' }, actions: { width: 'calc(100% + {space.6} * 2)', margin: '{space.4} calc({space.6} * -1) calc({space.5} * -1)', padding: '{space.4} {space.6}' } },
+        },
+        trend: {
+            up: { delta: { color: '{color.fg-success}' } },
+            down: { delta: { color: '{color.fg-danger}' } },
+            flat: { delta: { color: '{color.fg-muted}' } },
+        },
+    },
+    compound: [
+        { when: { variant: 'card', size: 'sm' }, block: { root: { padding: '{space.4} {space.5}' }, actions: { width: 'calc(100% + {space.5} * 2)', margin: '{space.3} calc({space.5} * -1) calc({space.4} * -1)', padding: '{space.3} {space.5}' } } },
+        { when: { variant: 'card', size: 'lg' }, block: { root: { padding: '{space.6}' }, actions: { margin: '{space.4} calc({space.6} * -1) calc({space.6} * -1)' } } },
+    ],
+    extraCss: `
+.cn-stat__delta[data-badge] { height: {space.6}; padding: 0 {space.2.5} 0 {space.2}; border-radius: {radius.full}; background-color: {color.bg-subtle}; box-shadow: ${ring('{color.border-default}')}; }
+.cn-stat[data-trend="up"] .cn-stat__delta[data-badge] { background-color: {green.50}; box-shadow: ${ring('{green.200}')}; color: {green.700}; }
+.cn-stat[data-trend="down"] .cn-stat__delta[data-badge] { background-color: {red.50}; box-shadow: ${ring('{red.200}')}; color: {red.700}; }
+.cn-stat[data-sentiment="good"] .cn-stat__delta { color: {color.fg-success}; }
+.cn-stat[data-sentiment="bad"] .cn-stat__delta { color: {color.fg-danger}; }
+.cn-stat[data-sentiment="good"] .cn-stat__delta[data-badge] { background-color: {green.50}; box-shadow: ${ring('{green.200}')}; color: {green.700}; }
+.cn-stat[data-sentiment="bad"] .cn-stat__delta[data-badge] { background-color: {red.50}; box-shadow: ${ring('{red.200}')}; color: {red.700}; }
+.cn-stat[data-sentiment="neutral"] .cn-stat__delta { color: {color.fg-muted}; }`,
+    examples: [
+        ex('Metric card (default)', tile({ label: 'Active users', value: '2,420', delta: '12%', trend: 'up', description: 'vs last month', style: 'width:280px' }), 'White card with a fine outline, 20 × 24px padding; 14px medium label, a token-sized semibold value, green arrow + "12%", muted "vs last month".'),
+        ex('Row of three', `<div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(200px,1fr));gap:var(--cn-space-6);width:100%">${tile({ label: 'Total users', value: '2,420', delta: '40%', trend: 'up', description: 'vs last month' })}${tile({ label: 'Active sessions', value: '1,210', delta: '10%', trend: 'down', description: 'vs last month' })}${tile({ label: 'Conversion rate', value: '4.2%', delta: '0.8 pts', trend: 'up', description: 'vs last month' })}</div>`, 'One row, equal widths, same size. The labels line up.'),
+        ex('With icon and actions', `<div style="display:grid;grid-template-columns:repeat(auto-fit,minmax(240px,1fr));gap:var(--cn-space-6);width:100%;max-width:560px">${tile({ label: 'Views 24h', value: '18,204', delta: '6%', trend: 'up', description: 'vs yesterday', media: FEATURED('user'), actions: VIEW })}${tile({ label: 'Revenue', value: '$32,480', delta: '2%', trend: 'down', description: 'vs last month', media: FEATURED('inbox'), actions: VIEW, badge: true })}</div>`, 'A 40px modern FeaturedIcon above the label; the delta as a tinted pill (data-badge); "View report" in a footer on a hairline.'),
+        ex('Sizes (plain)', `<div style="display:flex;gap:var(--cn-space-10);align-items:flex-end;flex-wrap:wrap">${tile({ label: 'Conversion', value: '4.2%', delta: '0.8 pts', trend: 'up', size: 'sm', variant: 'plain' })}${tile({ label: 'Conversion', value: '4.2%', delta: '0.8 pts', trend: 'up', size: 'md', variant: 'plain' })}${tile({ label: 'Conversion', value: '4.2%', delta: '0.8 pts', trend: 'up', size: 'lg', variant: 'plain', description: 'vs last month' })}</div>`, 'sm 24px · md 30px · lg 36px values.'),
+        ex('Direction is not sentiment', `<div style="display:flex;gap:var(--cn-space-6);flex-wrap:wrap">${tile({ label: 'Avg. response time', value: '2.1h', delta: '18%', trend: 'down', sentiment: 'good', description: 'vs last month', style: 'width:260px' })}${tile({ label: 'Bounce rate', value: '4.2%', delta: '0.8 pts', trend: 'up', sentiment: 'bad', description: 'vs last month', style: 'width:260px' })}</div>`, 'The arrow says which way it moved; data-sentiment says whether that is good.'),
+    ],
+    rules: [
+        'Label is 14px medium muted, 1–3 words, names the metric ("Active users"), never the value type ("Count").',
+        'The value carries its unit in the string ("41%", "2.1h", "$412k") and uses tabular figures; format with the locale, max 5 significant characters plus unit.',
+        'data-trend is the direction of change (the arrow), not a judgement. When up is bad (bounce rate, response time) or down is good, add data-sentiment="good|bad" so the color tells the truth.',
+        'The delta is the change ("12%", "0.8 pts") and the description names the period ("vs last month"); no delta at all beats a delta without a period.',
+        'Rows of stats: 3–4 tiles, equal width, same size and variant, 24px apart, labels aligned on one baseline. Never a grid of nine tiles.',
+        'One lg (hero) stat per page at most; md in dashboard rows; sm inside cards, drawers and comparisons.',
+        'Use variant="card" on the canvas; plain inside a Card, a page header or next to a chart (ChartFrame).',
+        'The only action is the "View report" link in the footer; no buttons inside the tile. If the whole tile opens a report, wrap it in a Link.',
+    ],
+    a11y: [
+        'Reading order is label, value, delta, description; the DOM must match so screen readers announce "Active users, 2,420, up 12% vs last month".',
+        'The arrow is decorative (aria-hidden); the delta text must state the direction in words or sign ("+12%", "−18%"), never rely on the arrow or color.',
+        'Use a real heading only when the stat is a section of its own; inside a row of tiles keep them as divs so the page outline stays clean.',
+        'Ensure the value text is selectable and not an image; no SVG numbers.',
+    ],
+    related: ['counter', 'chart-frame', 'card', 'featured-icon', 'badge', 'button'],
+};

package/lib/components/stepper.mjs

@@ -0,0 +1,228 @@
+import { ex, ICON, typeStyle } from "./_shared.mjs";
+// the reference progress steps: 24px (sm) or 32px (md) step icons — a number in a ringed circle,
+// a gray-50 disc with a gray-300 dot that turns brand-600 with a white dot (current, 4px brand-100
+// halo) or a white check (complete) — 8 / 10px minimal dots, or a 4px bar over the text; 2px
+// connectors, 14px semibold titles (brand-700 when current) with 14px supporting text.
+const TRANSITION_FAST = {
+    'transition-property': 'background-color, border-color, color, box-shadow',
+    'transition-duration': '{motion.duration.fast}',
+    'transition-timing-function': '{motion.easing.linear}',
+};
+const CHECK = ICON.check.replace('cn-icon', 'cn-stepper__check');
+const step = (n, state, label, description = '', variant = 'number') => {
+    const inner = variant === 'number' ? `${n}` : variant === 'icon' ? '<span class="cn-stepper__dot"></span>' : '';
+    const indicator = state === 'complete' && variant !== 'line' && variant !== 'dot' ? `${CHECK}<span class="cn-sr-only">Completed:</span>` : state === 'error' && variant === 'number' ? `${n}<span class="cn-sr-only">, needs attention:</span>` : inner;
+    const attrs = state === 'current' ? ' data-state="current" aria-current="step"' : state === 'upcoming' ? '' : ` data-state="${state}"`;
+    return `<li class="cn-stepper__step"${attrs}><span class="cn-stepper__indicator" aria-hidden="${state === 'complete' || state === 'error' ? 'false' : 'true'}">${indicator}</span>${label ? `<span class="cn-stepper__content"><span class="cn-stepper__label">${label}</span>${description ? `<span class="cn-stepper__description">${description}</span>` : ''}</span>` : ''}<span class="cn-stepper__connector" aria-hidden="true"></span></li>`;
+};
+const build = (variant, orientation, size, label, steps) => `<ol class="cn-stepper" data-variant="${variant}" data-orientation="${orientation}" data-size="${size}" aria-label="${label}">${steps}</ol>`;
+const SETUP = [['complete', 'Your details', 'Name and email'], ['current', 'Company details', 'Website and location'], ['upcoming', 'Invite your team', 'Start collaborating'], ['upcoming', 'Add your socials', 'Share posts to your accounts']];
+const steps = (variant, withDesc = true, list = SETUP) => list.map(([s, l, d], i) => step(i + 1, s, l, withDesc ? d : '', variant)).join('');
+export const stepper = {
+    name: 'Stepper',
+    slug: 'stepper',
+    category: 'navigation',
+    description: 'Progress through a sequence in the reference\'s four marker styles: numbered circles, step icons (disc with a dot, brand when current, check when complete), minimal dots, or a 4px bar over the text; 24 / 32px, joined by 2px connectors, horizontal or vertical, with a semibold title and supporting text per step.',
+    usage: 'Use above a multi-step form or wizard (onboarding, import, checkout) with 3–6 steps that happen in order, or as a vertical rail beside a long form. Not for switching between peer views (Tabs), not for percentage progress (Progress) and not for a timeline of past events (Timeline).',
+    anatomy: [
+        { part: 'root', element: 'ol', description: 'Ordered list of steps with aria-label. Flex row (horizontal) or column (vertical), 16px gaps.' },
+        { part: 'step', element: 'li', description: 'One step: indicator + content + connector. data-state="complete|current|error" (omit for upcoming); aria-current="step" on the current one.' },
+        { part: 'indicator', element: 'span', description: 'The marker: a 24 / 32px circle (number or icon), an 8 / 10px dot, or a 4px bar. Upcoming: gray-50 with a gray-300 ring or dot; current: brand-600 with a 4px brand-100 halo; complete: brand-600 with a white check; error: red.' },
+        { part: 'dot', element: 'span', description: 'The inner dot of the icon variant: 8 / 10px, gray-300 when upcoming, white when current.', optional: true },
+        { part: 'check', element: 'svg', description: '12 / 16px white check mark inside a complete indicator (number and icon variants).', optional: true },
+        { part: 'content', element: 'span', description: 'Column holding label and description, 2px apart, aligned to the indicator\'s center (under the bar in the line variant).' },
+        { part: 'label', element: 'span', description: 'Step title, 14px semibold: 1–3 words ("Company details"). Gray-700 when upcoming or complete, brand-700 when current.' },
+        { part: 'description', element: 'span', description: 'Optional 14px supporting text under the title, fg-muted: "Website and location". Carries the message in the error state.', optional: true },
+        { part: 'connector', element: 'span', description: '2px gray-200 line from this step to the next; fills the gap horizontally or runs down the indicator\'s axis vertically. Hidden on the last step and in the line variant; brand-600 after a complete step.' },
+    ],
+    props: {
+        variant: {
+            values: ['number', 'icon', 'dot', 'line'],
+            default: 'number',
+            description: 'number = the step number in a ringed circle (forms with many steps). icon = the reference step icon: a gray-50 disc with a gray-300 dot that turns brand with a white dot when current and a check when complete (onboarding, wizards). dot = minimal 8 / 10px dots joined by connectors, labels optional (compact progress under a dialog title). line = a 4px bar above each step\'s text, no connectors (the reference "text with line").',
+        },
+        orientation: {
+            values: ['horizontal', 'vertical'],
+            default: 'horizontal',
+            description: 'horizontal = a row across the top of a wizard, steps share the width and connectors fill the gaps; up to 5 steps. vertical = a column in a side rail or next to a long form (the reference 400px column); the connector runs down from each indicator, so descriptions can be longer.',
+        },
+        size: {
+            values: ['sm', 'md'],
+            default: 'md',
+            description: 'md = 32px circles (10px dots, 16px check), 14px titles; the default above a page-level form. sm = 24px circles (8px dots, 12px check), 14px titles; inside dialogs, drawers and cards.',
+        },
+    },
+    states: {
+        complete: { selector: ' .cn-stepper__step[data-state="complete"]', description: 'Done (on the STEP, not the root): indicator filled brand-600 with a white check (bar or dot turns brand); the connector after it turns brand-600; title stays gray-700.', markup: 'data-state="complete" on the li; put the check svg (and sr-only "Completed:") inside the indicator instead of the number' },
+        current: { selector: ' .cn-stepper__step[data-state="current"], & .cn-stepper__step[aria-current="step"]', description: 'The step the user is on: brand-600 indicator with a white dot (number variant: 2px brand ring and brand number) and a 4px brand-100 halo; title in brand-700. Exactly one.', markup: 'data-state="current" and aria-current="step" on the li' },
+        error: { selector: ' .cn-stepper__step[data-state="error"]', description: 'A visited step that failed validation: red-500 ring on a red-50 disc, red title; the description says what to fix.', markup: 'data-state="error" on the li, with the problem in the description' },
+        upcoming: { selector: ' .cn-stepper__step:not([data-state])', description: 'Not reached yet: gray-50 disc with a gray-300 ring or dot, gray-700 title. The default; no attribute needed.', markup: 'no data-state' },
+    },
+    base: {
+        root: {
+            display: 'flex',
+            'align-items': 'flex-start',
+            gap: '{space.4}',
+            width: '100%',
+            margin: '0',
+            padding: '0',
+            'list-style': 'none',
+        },
+        step: {
+            position: 'relative',
+            display: 'flex',
+            'align-items': 'flex-start',
+            gap: '{space.3}',
+            flex: '1 1 0',
+            'min-width': '0',
+        },
+        indicator: {
+            position: 'relative',
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            width: '{space.8}',
+            height: '{space.8}',
+            'border-radius': '{radius.full}',
+            'background-color': '{color.bg-subtle}',
+            'box-shadow': 'inset 0 0 0 1px {color.border-default}',
+            color: '{color.fg-muted}',
+            ...typeStyle('label-sm'),
+            'font-variant-numeric': 'tabular-nums',
+            ...TRANSITION_FAST,
+        },
+        dot: { display: 'block', width: '{space.2.5}', height: '{space.2.5}', 'border-radius': '{radius.full}', 'background-color': '{color.border-control}', transition: 'inherit' },
+        check: { width: '{size.icon.sm}', height: '{size.icon.sm}', display: 'block', 'stroke-width': '2.5' },
+        content: {
+            display: 'flex',
+            'flex-direction': 'column',
+            gap: '{space.0.5}',
+            'min-width': '0',
+            'padding-top': '{space.1.5}',
+        },
+        label: {
+            ...typeStyle('label-md'),
+            color: '{color.fg-muted}',
+            'white-space': 'nowrap',
+            overflow: 'hidden',
+            'text-overflow': 'ellipsis',
+            transition: 'inherit',
+        },
+        description: { ...typeStyle('body-md'), color: '{color.fg-muted}' },
+        connector: {
+            flex: '1 1 auto',
+            height: '{border.width.medium}',
+            'min-width': '{space.4}',
+            'margin-top': 'calc({space.8} / 2 - {border.width.thin})',
+            'border-radius': '{radius.full}',
+            'background-color': '{color.border-default}',
+        },
+    },
+    variants: {
+        variant: {
+            number: { root: {} },
+            icon: { root: {} },
+            dot: {
+                indicator: { width: '{space.2.5}', height: '{space.2.5}', 'background-color': '{color.border-default}', 'box-shadow': 'none', 'margin-top': 'calc({space.2.5} / 2)' },
+                content: { 'padding-top': '0' },
+                connector: { 'margin-top': 'calc({space.2.5} - {border.width.thin})' },
+            },
+            line: {
+                step: { 'flex-direction': 'column', gap: '{space.3}' },
+                indicator: { width: '100%', height: '{space.1}', 'border-radius': '{radius.full}', 'background-color': '{color.bg-muted}', 'box-shadow': 'none' },
+                content: { 'padding-top': '0' },
+                connector: { display: 'none' },
+            },
+        },
+        orientation: {
+            horizontal: { root: { 'flex-direction': 'row' } },
+            vertical: {
+                root: { 'flex-direction': 'column', gap: '0', width: 'auto', 'max-width': '{size.container.xs}' },
+                step: { flex: '0 0 auto', 'padding-bottom': '{space.6}' },
+                connector: {
+                    position: 'absolute',
+                    'inset-inline-start': 'calc({space.8} / 2 - {border.width.thin})',
+                    top: 'calc({space.8} + {space.1})',
+                    bottom: '{space.1}',
+                    width: '{border.width.medium}',
+                    height: 'auto',
+                    flex: 'none',
+                    'min-width': '0',
+                    'margin-top': '0',
+                },
+                label: { 'white-space': 'normal' },
+            },
+        },
+        size: {
+            sm: {
+                indicator: { width: '{space.6}', height: '{space.6}', 'font-size': '{font.size.xs}' },
+                dot: { width: '{space.2}', height: '{space.2}' },
+                check: { width: '{size.icon.xs}', height: '{size.icon.xs}' },
+                content: { 'padding-top': '{space.0.5}' },
+                connector: { 'margin-top': 'calc({space.6} / 2 - {border.width.thin})' },
+            },
+            md: { root: {} },
+        },
+    },
+    compound: [
+        { when: { orientation: 'vertical', size: 'sm' }, block: { connector: { 'inset-inline-start': 'calc({space.6} / 2 - {border.width.thin})', top: 'calc({space.6} + {space.1})', 'margin-top': '0' }, step: { 'padding-bottom': '{space.5}' } } },
+        { when: { variant: 'dot', size: 'sm' }, block: { indicator: { width: '{space.2}', height: '{space.2}', 'margin-top': '{space.1.5}' }, connector: { 'margin-top': 'calc({space.2.5} - {border.width.thin})' } } },
+        { when: { variant: 'dot', orientation: 'vertical' }, block: { connector: { 'inset-inline-start': 'calc({space.2.5} / 2 - {border.width.thin})', top: 'calc({space.2.5} * 2 + {space.1})', 'margin-top': '0' } } },
+        { when: { variant: 'line', orientation: 'vertical' }, block: { step: { 'flex-direction': 'row', 'padding-bottom': '0', 'margin-bottom': '{space.4}' }, indicator: { width: '{space.1}', height: 'auto', 'align-self': 'stretch', 'min-height': '{space.10}' } } },
+    ],
+    extraCss: `
+.cn-stepper__step:last-child .cn-stepper__connector { display: none; }
+.cn-stepper[data-orientation="horizontal"] .cn-stepper__step:last-child { flex: 0 0 auto; }
+.cn-stepper[data-orientation="horizontal"][data-variant="line"] .cn-stepper__step:last-child { flex: 1 1 0; }
+.cn-stepper[data-orientation="vertical"] .cn-stepper__step:last-child { padding-bottom: 0; margin-bottom: 0; }
+.cn-stepper[data-variant="number"] .cn-stepper__indicator { background-color: {color.bg-surface}; box-shadow: inset 0 0 0 1px {color.border-control}; }
+.cn-stepper__step[data-state="complete"] .cn-stepper__indicator { background-color: {color.bg-action}; box-shadow: none; color: {color.fg-on-action}; }
+.cn-stepper__step[data-state="complete"] .cn-stepper__dot { display: none; }
+.cn-stepper__step[data-state="complete"] .cn-stepper__connector { background-color: {color.bg-action}; }
+.cn-stepper__step[data-state="current"] .cn-stepper__indicator, .cn-stepper__step[aria-current="step"] .cn-stepper__indicator { background-color: {color.bg-action}; box-shadow: 0 0 0 4px {color.bg-action-subtle}; color: {color.fg-on-action}; }
+.cn-stepper[data-variant="number"] .cn-stepper__step[data-state="current"] .cn-stepper__indicator, .cn-stepper[data-variant="number"] .cn-stepper__step[aria-current="step"] .cn-stepper__indicator { background-color: {color.bg-surface}; box-shadow: inset 0 0 0 2px {color.bg-action}, 0 0 0 4px {color.bg-action-subtle}; color: {color.fg-action}; }
+.cn-stepper__step[data-state="current"] .cn-stepper__dot, .cn-stepper__step[aria-current="step"] .cn-stepper__dot { background-color: {color.fg-on-action}; }
+.cn-stepper__step[data-state="current"] .cn-stepper__label, .cn-stepper__step[aria-current="step"] .cn-stepper__label { color: {color.fg-action}; }
+.cn-stepper[data-variant="line"] .cn-stepper__step[data-state="current"] .cn-stepper__indicator, .cn-stepper[data-variant="line"] .cn-stepper__step[data-state="complete"] .cn-stepper__indicator, .cn-stepper[data-variant="dot"] .cn-stepper__step[data-state="complete"] .cn-stepper__indicator { box-shadow: none; }
+.cn-stepper[data-variant="dot"] .cn-stepper__step[data-state="current"] .cn-stepper__indicator { box-shadow: 0 0 0 4px {color.bg-action-subtle}; }
+.cn-stepper__step[data-state="error"] .cn-stepper__indicator { background-color: {color.bg-danger-subtle}; box-shadow: inset 0 0 0 1px {red.500}; color: {color.fg-danger}; }
+.cn-stepper__step[data-state="error"] .cn-stepper__dot { background-color: {red.500}; }
+.cn-stepper__step[data-state="error"] .cn-stepper__label, .cn-stepper__step[data-state="error"] .cn-stepper__description { color: {color.fg-danger}; }
+@media (max-width: {breakpoint.md}) {
+  .cn-stepper[data-orientation="horizontal"]:has(.cn-stepper__content) { flex-direction: column; gap: {space.5}; }
+  .cn-stepper[data-orientation="horizontal"]:has(.cn-stepper__content) .cn-stepper__step { flex: 0 0 auto; width: 100%; }
+  .cn-stepper[data-orientation="horizontal"]:has(.cn-stepper__content) .cn-stepper__content { flex: 1; }
+  .cn-stepper[data-orientation="horizontal"]:has(.cn-stepper__content) .cn-stepper__label { white-space: normal; overflow-wrap: anywhere; }
+  .cn-stepper[data-orientation="horizontal"]:has(.cn-stepper__content) .cn-stepper__connector { display: none; }
+}`,
+    examples: [
+        ex('Icon with text (default md)', build('icon', 'horizontal', 'md', 'Account setup', steps('icon')), 'The reference step icon: gray-50 disc with a gray-300 dot; current is brand-600 with a white dot and a 4px halo, complete is brand with a white check. 2px connectors turn brand after a complete step.'),
+        ex('Icon with number', build('number', 'horizontal', 'md', 'Account setup', steps('number')), 'Numbers in ringed 32px circles; the current one has a 2px brand ring, the complete one is filled with a check.'),
+        ex('Minimal dots and connected dots', `<div style="display:flex;flex-direction:column;gap:var(--cn-space-8);width:100%">${build('dot', 'horizontal', 'md', 'Onboarding', steps('dot', false))}<div style="max-width:480px">${build('dot', 'horizontal', 'sm', 'Onboarding', steps('dot', false, [['complete', '', ''], ['complete', '', ''], ['current', '', ''], ['upcoming', '', ''], ['upcoming', '', '']]))}</div></div>`, '10px (md) or 8px (sm) dots; labels are optional. Complete dots are brand, the current one has the halo.'),
+        ex('Text with line', build('line', 'horizontal', 'md', 'Account setup', steps('line')), 'A 4px bar over each step: gray-100 upcoming, brand-600 current and complete; no connectors, steps share the width.'),
+        ex('Vertical with an error', build('icon', 'vertical', 'md', 'CSV import', step(1, 'complete', 'Upload file', 'customers-q3.csv · 1,204 rows', 'icon') + step(2, 'error', 'Map columns', '2 columns are unmapped: “Phone”, “Owner”', 'icon') + step(3, 'upcoming', 'Validate', 'Check duplicates and formats', 'icon') + step(4, 'upcoming', 'Import', 'Add 1,204 customers to Lumen', 'icon')), 'The vertical rail (max 480px): the connector runs down from each 32px indicator; the error step turns red and says what to fix.'),
+        ex('Small, vertical line', build('line', 'vertical', 'sm', 'Send campaign', steps('line', true, [['complete', 'Details', 'Name and audience'], ['complete', 'Recipients', '1,204 customers'], ['current', 'Schedule', 'Thursday, 09:00'], ['upcoming', 'Send', 'Review and confirm']])), 'In the vertical line variant the 4px bar runs beside each step.'),
+        ex('Small numbers, labels only', build('number', 'horizontal', 'sm', 'Send campaign', step(1, 'complete', 'Details') + step(2, 'complete', 'Recipients') + step(3, 'current', 'Schedule') + step(4, 'upcoming', 'Send')), 'Inside a dialog or drawer: 24px indicators, no descriptions.'),
+    ],
+    rules: [
+        '3–6 steps. Two steps are a single form with a confirm; more than six means the flow needs to be split or some steps merged.',
+        'Titles are short and specific to the task. Labeled horizontal steps stack below 768px so titles and descriptions stay readable; unlabeled progress dots remain a row.',
+        'Exactly one current step at all times; everything before it is complete (or error), everything after it upcoming.',
+        'Complete steps may be clickable (wrap the label in a Link, or make the step a button) to go back; upcoming steps are never clickable.',
+        'Descriptions are optional and short (≤ 5 words); in the error state the description is the message that says what to fix.',
+        'Error only on a visited step and only with a message; never mark an upcoming step as error.',
+        'icon or number for wizards above a form; dot for compact progress under a dialog title; line when the steps are also section titles of a long page.',
+        'Horizontal for up to 5 steps above a wizard; vertical (max 480px wide) when there are 5–6 steps, when descriptions are needed, or in a side rail beside a long form.',
+        'Indicators are 32px (sm 24) with 2px connectors; the check appears only on complete steps. No custom icons, letters or emoji in the circles.',
+        'The stepper shows position, it does not save. Moving between steps is done by the form\'s Back / Continue buttons.',
+    ],
+    a11y: [
+        'Root is an <ol aria-label="…"> so the order is announced ("step 2 of 4"); each step is an <li>.',
+        'The current step carries aria-current="step" on the li in addition to data-state.',
+        'Status is not color alone: complete indicators contain the check plus sr-only "Completed:", error indicators keep the number plus sr-only ", needs attention:".',
+        'Connectors and decorative indicators are aria-hidden; the label text is the accessible name of the step. Dot steps without labels need an sr-only label each.',
+        'If steps are clickable, they are links or buttons with the step name as text, and upcoming steps are not focusable.',
+    ],
+    related: ['tabs', 'progress', 'timeline', 'button', 'featured-icon'],
+};