canon-ds 0.1.0

package/lib/components/breadcrumb.mjs

@@ -0,0 +1,170 @@
+import { RESET_BUTTON, ex, ICON, typeStyle } from "./_shared.mjs";
+// the reference breadcrumbs: 14px medium gray-600 links, the current page one step darker,
+// 16px gray-300 chevrons (or a "/" divider), an optional 20px home icon; three trail types:
+// text (20px), text with a hairline under it (36px) and button chips (28px, gray-50 when current).
+const TRANSITION_FAST = {
+    'transition-property': 'background-color, color, box-shadow',
+    'transition-duration': '{motion.duration.fast}',
+    'transition-timing-function': '{motion.easing.linear}',
+};
+const HAIRLINE = '{border.width.thin} solid {color.border-default}';
+const chevron = ICON.chevronRight.replace('cn-icon', 'cn-breadcrumb__separator');
+const SLASH = '<span class="cn-breadcrumb__separator" aria-hidden="true">/</span>';
+const HOME = ICON.home.replace('cn-icon', 'cn-breadcrumb__icon');
+const li = (inner) => `<li class="cn-breadcrumb__item">${inner}</li>`;
+const lnk = (label, icon = '') => `<a href="#" class="cn-breadcrumb__link"${icon ? ` aria-label="${label}"` : ''}>${icon || label}</a>`;
+const cur = (label) => `<span class="cn-breadcrumb__current" aria-current="page">${label}</span>`;
+const crumbs = (variant, divider, size, parts, extra = '') => `<nav class="cn-breadcrumb" data-variant="${variant}" data-divider="${divider}" data-size="${size}" aria-label="Breadcrumb"${extra}><ol class="cn-breadcrumb__list">${parts.map((p, i) => li((i ? (divider === 'slash' ? SLASH : chevron) : '') + p)).join('')}</ol></nav>`;
+export const breadcrumb = {
+    name: 'Breadcrumb',
+    slug: 'breadcrumb',
+    category: 'navigation',
+    description: 'The path to the current page in the reference\'s three trail types: 14px medium links separated by 16px gray-300 chevrons (or slashes), ending in the current page one step darker; plain text (20px), text on a hairline (36px) or 28px button chips. Sits above the page title.',
+    usage: 'Use on pages three or more levels deep (Settings → Team → Roles) so the user can go up one level with one click. Not for top-level pages, not for wizard progress (Stepper), never inside the Topbar.',
+    anatomy: [
+        { part: 'root', element: 'nav', description: 'The landmark: <nav aria-label="Breadcrumb">, 14px medium, fg-muted.' },
+        { part: 'list', element: 'ol', description: 'Ordered list of levels, root first. Flex row, 8px gaps, wraps on narrow screens.' },
+        { part: 'item', element: 'li', description: 'One level: an optional separator followed by a link, the ellipsis button, or the current page.' },
+        { part: 'link', element: 'a', description: 'An ancestor page, fg-muted; ink on hover (gray-50 chip in the button type). Truncates at 24 characters.' },
+        { part: 'icon', element: 'svg', description: 'Optional 20px home icon as the first link (with aria-label="Home"), fg-subtle.', optional: true },
+        { part: 'separator', element: 'svg', description: '16px gray-300 chevron (or a "/" span) before every item except the first. aria-hidden.' },
+        { part: 'ellipsis', element: 'button', description: 'The "…" that stands in for collapsed middle levels; opens a Menu listing them.', optional: true },
+        { part: 'current', element: 'span', description: 'The page the user is on: one step darker than the links, medium, aria-current="page". Not a link.' },
+    ],
+    props: {
+        variant: {
+            values: ['text', 'line', 'button'],
+            default: 'text',
+            description: 'text = plain 20px trail (page headers, the default). line = the trail sits on a full-width gray-200 hairline, 36px tall (above a page title without its own divider). button = each level is a 28px chip (radius 6, padding 4 × 8); the current one is filled gray-50 (record headers, drawers).',
+        },
+        divider: {
+            values: ['chevron', 'slash'],
+            default: 'chevron',
+            description: 'chevron = 16px gray-300 chevron-right (default). slash = a "/" in gray-300 (denser, developer-facing paths).',
+        },
+        size: {
+            values: ['sm', 'md'],
+            default: 'md',
+            description: 'md = 14px medium (text-sm); the page-header default. sm = 12px medium for drawers, dialogs and card headers.',
+        },
+    },
+    states: {
+        hover: { selector: ' .cn-breadcrumb__link:hover', description: 'Pointer over an ancestor link (on the LINK, not the root): ink text; in the button type also a gray-50 chip.', markup: 'native :hover on the link' },
+        focus: { selector: ' .cn-breadcrumb__link:focus-visible, & .cn-breadcrumb__ellipsis:focus-visible', description: 'Keyboard focus on a link or the ellipsis: the 4px brand ring.', markup: 'native :focus-visible' },
+        current: { selector: ' [aria-current="page"]', description: 'The last item: one step darker, medium, no hover, not a link (button type: gray-50 chip).', markup: 'aria-current="page" on the current span' },
+    },
+    base: {
+        root: {
+            display: 'flex',
+            'align-items': 'center',
+            'min-width': '0',
+            ...typeStyle('label-sm'),
+            color: '{color.fg-muted}',
+        },
+        list: {
+            display: 'flex',
+            'align-items': 'center',
+            'flex-wrap': 'wrap',
+            gap: '{space.2}',
+            'min-width': '0',
+            margin: '0',
+            padding: '0',
+            'list-style': 'none',
+        },
+        item: { display: 'inline-flex', 'align-items': 'center', gap: '{space.2}', 'min-width': '0' },
+        link: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            color: '{color.fg-muted}',
+            'text-decoration': 'none',
+            'border-radius': '{radius.sm}',
+            'white-space': 'nowrap',
+            'max-width': '24ch',
+            overflow: 'hidden',
+            'text-overflow': 'ellipsis',
+            ...TRANSITION_FAST,
+        },
+        icon: { width: '{size.icon.md}', height: '{size.icon.md}', 'flex-shrink': '0', color: '{color.fg-subtle}', transition: 'inherit' },
+        separator: { display: 'inline-flex', 'align-items': 'center', 'justify-content': 'center', width: '{size.icon.sm}', height: '{size.icon.sm}', 'flex-shrink': '0', color: '{color.border-control}', 'user-select': 'none' },
+        ellipsis: {
+            ...RESET_BUTTON,
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            height: '{space.5}',
+            'padding-inline': '{space.1}',
+            'border-radius': '{radius.sm}',
+            color: '{color.fg-subtle}',
+            'letter-spacing': '{font.letterSpacing.wide}',
+            ...TRANSITION_FAST,
+        },
+        current: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            color: '{color.fg-default}',
+            'white-space': 'nowrap',
+            'min-width': '0',
+            'max-width': '32ch',
+            overflow: 'hidden',
+            'text-overflow': 'ellipsis',
+        },
+    },
+    variants: {
+        variant: {
+            text: { root: {} },
+            line: { root: { width: '100%', 'padding-block': '{space.2} calc({space.2} - {border.width.thin})', 'border-bottom': HAIRLINE } },
+            button: {
+                list: { gap: '{space.1}' },
+                item: { gap: '{space.1}' },
+                link: { height: '{space.7}', padding: '{space.1} {space.2}', 'border-radius': '{radius.md}' },
+                current: { height: '{space.7}', padding: '{space.1} {space.2}', 'border-radius': '{radius.md}', 'background-color': '{color.bg-subtle}' },
+                ellipsis: { height: '{space.7}', padding: '{space.1} {space.2}', 'border-radius': '{radius.md}' },
+            },
+        },
+        divider: { chevron: { root: {} }, slash: { separator: { ...typeStyle('label-sm'), width: 'auto', 'padding-inline': '{space.0.5}' } } },
+        size: {
+            sm: {
+                root: { 'font-size': '{font.size.xs}' },
+                list: { gap: '{space.1.5}' },
+                item: { gap: '{space.1.5}' },
+                icon: { width: '{size.icon.sm}', height: '{size.icon.sm}' },
+            },
+            md: { root: {} },
+        },
+    },
+    extraCss: `
+.cn-breadcrumb__link:hover { color: {color.fg-default}; }
+.cn-breadcrumb__link:hover .cn-breadcrumb__icon { color: {color.fg-muted}; }
+.cn-breadcrumb[data-variant="button"] .cn-breadcrumb__link:hover, .cn-breadcrumb__ellipsis:hover { color: {color.fg-default}; background-color: {color.bg-subtle}; }
+.cn-breadcrumb__link:focus-visible, .cn-breadcrumb__ellipsis:focus-visible { outline: none; box-shadow: {shadow.focus}; }`,
+    examples: [
+        ex('Text (default)', crumbs('text', 'chevron', 'md', [lnk('Settings'), lnk('Team'), cur('Roles and permissions')]), 'Ancestors gray-600, the current page one step darker; 16px gray-300 chevrons.'),
+        ex('With home icon', crumbs('text', 'chevron', 'md', [lnk('Home', HOME), lnk('Projects'), lnk('Lumen website'), cur('Design')]), 'A 20px home icon replaces the first label (aria-label="Home").'),
+        ex('Slash divider', crumbs('text', 'slash', 'md', [lnk('Home', HOME), lnk('Projects'), cur('Lumen website')]), 'data-divider="slash" for denser, path-like trails.'),
+        ex('Text with line', `<div style="width:100%;max-width:560px">${crumbs('line', 'chevron', 'md', [lnk('Home', HOME), lnk('Customers'), cur('Sofia Almeida')])}</div>`, '36px tall on a full-width hairline; use above a title that has no divider of its own.'),
+        ex('Button chips', crumbs('button', 'chevron', 'md', [lnk('Home', HOME), lnk('Invoices'), cur('INV-0042')]), '28px chips, radius 6; the current page is a gray-50 chip and hovered ancestors light up.'),
+        ex('Collapsed middle', crumbs('text', 'chevron', 'md', [lnk('Home', HOME), `<button type="button" class="cn-breadcrumb__ellipsis" aria-label="Show 2 hidden levels" aria-haspopup="menu" aria-expanded="false">…</button>`, lnk('Q3 launch'), cur('Design review')]), 'Deeper than four levels: keep root, the parent and the current page; the ellipsis opens a Menu with the rest.'),
+        ex('Small, inside a drawer header', crumbs('text', 'chevron', 'sm', [lnk('Settings'), lnk('Team'), cur('Roles and permissions')])),
+        ex('Long names truncate', crumbs('text', 'chevron', 'md', [lnk('Home', HOME), lnk('Enterprise procurement pipeline for the northern region'), cur('Annual supply agreement 2026 with Daniel Costa\'s team')]), 'Links cut at 24ch, the current page at 32ch; the full text goes in a title attribute.'),
+    ],
+    rules: [
+        'Max 4 visible levels. Deeper paths collapse the middle into an ellipsis that opens a Menu of the hidden levels.',
+        'Labels are the exact page titles of the ancestors (same text as their h1), not shortened synonyms.',
+        'The last item is the current page: darker, not a link, aria-current="page". Never end with a separator.',
+        'Never show a one-level breadcrumb ("Home" alone). Below three levels, skip the breadcrumb entirely.',
+        'Place it in the page header directly above the title, 8px apart. Never in the Topbar and never at the bottom of the page.',
+        'Separators are the 16px gray-300 chevron, or the slash for path-like trails; never arrows, dots or both in one app.',
+        'text in page headers; line when the header has no divider of its own; button in record headers and drawers where the trail is also a filter.',
+        'sm only inside drawers, dialogs and card headers; md everywhere else.',
+        'Truncate long names with an ellipsis and provide the full name in a title; never wrap a single label across lines.',
+    ],
+    a11y: [
+        'Root is <nav aria-label="Breadcrumb"> containing an <ol>; order conveys hierarchy.',
+        'The current page has aria-current="page" and is not a link (or is a link only if it reloads the same page).',
+        'Separators are aria-hidden="true"; the chevron or slash is decoration, the list order is the semantics.',
+        'A home icon link carries aria-label="Home"; the icon itself is aria-hidden.',
+        'The ellipsis is a <button aria-label="Show N hidden levels" aria-haspopup="menu" aria-expanded>, not plain text.',
+        'Truncated labels keep their full text in a title attribute and in the accessible name.',
+    ],
+    related: ['link', 'menu', 'page-header', 'topbar', 'sidebar-nav'],
+};

package/lib/components/button-group.mjs

@@ -0,0 +1,114 @@
+import { CONTROL, ex, ICON } from "./_shared.mjs";
+// the system ButtonGroup: attached secondary-gray buttons (36/40/44px) whose 1px
+// rings overlap by 1px, outer corners 8px, inner corners square, shadow-xs on the
+// container, selected item (aria-pressed) in the gray-50 hover fill.
+const outline = (label, attrs = '', leading = '', size = 'md') => `<button type="button" class="cn-button" data-variant="outline" data-size="${size}"${attrs}>${leading}<span class="cn-button__label">${label}</span></button>`;
+const iconBtn = (label, i, variant = 'outline', attrs = '') => `<button type="button" class="cn-icon-button" data-variant="${variant}" data-size="md" data-shape="square" aria-label="${label}"${attrs}>${ICON[i].replace('cn-icon', 'cn-icon-button__icon')}</button>`;
+const group = (attrs, children) => `<div class="cn-button-group" data-variant="attached" data-orientation="horizontal" ${attrs}>${children}</div>`;
+export const buttonGroup = {
+    name: 'ButtonGroup',
+    slug: 'button-group',
+    category: 'actions',
+    description: 'A row (or column) of related Buttons. Attached groups fuse into one control by squaring the inner corners and overlapping the 1px rings (the reference button group); spaced groups just keep a consistent gap.',
+    usage: 'Use attached for actions that belong to one object (Assign · Snooze · Archive), for split buttons (action + chevron menu) and for a toggle group where one option is on (aria-pressed on the selected child). Use spaced for a row of independent toolbar actions. For a rail-style single choice use SegmentedControl.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'Inline-flex container with role="group" and an aria-label. Children are outline Buttons or IconButtons of the same size; attached groups carry the shadow-xs and the 8px outer radius.' },
+    ],
+    props: {
+        variant: {
+            values: ['attached', 'spaced'],
+            default: 'attached',
+            description: 'attached = no gap, inner corners squared, rings overlap by 1px so the group reads as one control (the reference ButtonGroup); spaced = 12px gap, every button keeps its own radius and shadow.',
+        },
+        orientation: {
+            values: ['horizontal', 'vertical'],
+            default: 'horizontal',
+            description: 'horizontal = a row (toolbars, headers, split buttons); vertical = a stacked column (zoom controls, ordering, side rails). Vertical attached groups stretch children to the same width.',
+        },
+    },
+    states: {},
+    base: {
+        root: {
+            position: 'relative',
+            'z-index': '{z.base}',
+            display: 'inline-flex',
+            'align-items': 'stretch',
+            'flex-wrap': 'nowrap',
+            'vertical-align': 'middle',
+            'max-width': '100%',
+        },
+    },
+    variants: {
+        variant: {
+            attached: { root: { gap: '0', 'border-radius': '{radius.control}', 'box-shadow': '{shadow.xs}' } },
+            spaced: { root: { gap: '{space.3}', 'flex-wrap': 'wrap' } },
+        },
+        orientation: {
+            horizontal: { root: { 'flex-direction': 'row' } },
+            vertical: { root: { 'flex-direction': 'column', 'align-items': 'stretch' } },
+        },
+    },
+    extraCss: `
+.cn-button-group > .cn-button { flex-shrink: 1; min-width: 0; height: auto; min-height: {size.control.md}; white-space: normal; }
+.cn-button-group > .cn-button > .cn-button__label { min-width: 0; overflow-wrap: anywhere; }
+${Object.entries(CONTROL).map(([size, control]) => `.cn-button-group > .cn-button[data-size="${size}"] { min-height: ${control.height}; }`).join('\n')}
+.cn-button-group[data-variant="attached"][data-orientation="horizontal"] > .cn-button:not(:first-child),
+.cn-button-group[data-variant="attached"][data-orientation="horizontal"] > .cn-icon-button:not(:first-child) { border-start-start-radius: 0; border-end-start-radius: 0; margin-inline-start: -1px; }
+.cn-button-group[data-variant="attached"][data-orientation="horizontal"] > .cn-button:not(:last-child),
+.cn-button-group[data-variant="attached"][data-orientation="horizontal"] > .cn-icon-button:not(:last-child) { border-start-end-radius: 0; border-end-end-radius: 0; }
+.cn-button-group[data-variant="attached"][data-orientation="vertical"] > .cn-button:not(:first-child),
+.cn-button-group[data-variant="attached"][data-orientation="vertical"] > .cn-icon-button:not(:first-child) { border-start-start-radius: 0; border-start-end-radius: 0; margin-block-start: -1px; }
+.cn-button-group[data-variant="attached"][data-orientation="vertical"] > .cn-button:not(:last-child),
+.cn-button-group[data-variant="attached"][data-orientation="vertical"] > .cn-icon-button:not(:last-child) { border-end-start-radius: 0; border-end-end-radius: 0; }
+.cn-button-group[data-variant="attached"] > .cn-button::before,
+.cn-button-group[data-variant="attached"] > .cn-icon-button::before { border-radius: inherit; }
+.cn-button-group[data-variant="attached"] > .cn-button:hover,
+.cn-button-group[data-variant="attached"] > .cn-button:focus-visible,
+.cn-button-group[data-variant="attached"] > .cn-button[aria-pressed="true"],
+.cn-button-group[data-variant="attached"] > .cn-icon-button:hover,
+.cn-button-group[data-variant="attached"] > .cn-icon-button:focus-visible,
+.cn-button-group[data-variant="attached"] > .cn-icon-button[aria-pressed="true"] { z-index: {z.raised}; }
+/* the reference: items carry the ring + skeuomorphic pair only; the container carries the single shadow-xs. */
+.cn-button-group[data-variant="attached"] > .cn-button[data-variant="outline"],
+.cn-button-group[data-variant="attached"] > .cn-icon-button[data-variant="outline"] { box-shadow: inset 0 0 0 1px {color.border-control}, {shadow.control}; }
+.cn-button-group[data-variant="attached"] > .cn-button[data-variant="outline"]:focus-visible,
+.cn-button-group[data-variant="attached"] > .cn-icon-button[data-variant="outline"]:focus-visible { box-shadow: inset 0 0 0 1px {color.border-control}, {shadow.control}, {shadow.focus}; }
+.cn-button-group[data-variant="attached"] > .cn-button[data-variant="primary"],
+.cn-button-group[data-variant="attached"] > .cn-icon-button[data-variant="primary"] { box-shadow: {shadow.control}; }
+.cn-button-group[data-variant="attached"] > .cn-button[data-variant="primary"]:focus-visible,
+.cn-button-group[data-variant="attached"] > .cn-icon-button[data-variant="primary"]:focus-visible { box-shadow: {shadow.control}, {shadow.focus}; }
+.cn-button-group[data-variant="attached"] > .cn-button[aria-pressed="true"],
+.cn-button-group[data-variant="attached"] > .cn-icon-button[aria-pressed="true"] { background-color: {color.bg-subtle}; color: {color.fg-default}; }
+.cn-button-group[data-variant="attached"] > .cn-button[aria-pressed="true"] .cn-button__icon,
+.cn-button-group[data-variant="attached"] > .cn-icon-button[aria-pressed="true"] .cn-icon-button__icon { color: {color.fg-muted}; }
+.cn-button-group[data-variant="attached"] > .cn-button:disabled { opacity: 1; color: color-mix(in srgb, {color.fg-muted} 50%, transparent); }
+.cn-button-group[data-variant="attached"] > .cn-button:disabled > * { opacity: {opacity.disabled}; }
+.cn-button-group[data-orientation="vertical"] > .cn-button { justify-content: flex-start; }`,
+    examples: [
+        ex('Attached (actions on one object)', group('role="group" aria-label="Conversation actions"', outline('Assign') + outline('Snooze') + outline('Archive')), 'Outline buttons fuse into one control: inner corners squared, rings overlap by 1px, shadow-xs on the group.'),
+        ex('Toggle group (one option on)', group('role="group" aria-label="Range"', outline('12 months', ' aria-pressed="true"') + outline('30 days', ' aria-pressed="false"') + outline('7 days', ' aria-pressed="false"') + outline('24 hours', ' aria-pressed="false"')), 'The reference ButtonGroup: the selected child (aria-pressed="true") sits in the gray-50 fill with default ink.'),
+        ex('With leading icons', group('role="group" aria-label="View"', outline('Text', '', ICON.menu.replace('cn-icon', 'cn-button__icon')) + outline('Grid', ' aria-pressed="true"', ICON.home.replace('cn-icon', 'cn-button__icon')) + outline('Calendar', '', ICON.calendar.replace('cn-icon', 'cn-button__icon'))), 'Icons are gray-400 at rest and gray-500 on the selected item.'),
+        ex('Split button', group('role="group" aria-label="Send invite"', `<button type="button" class="cn-button" data-variant="primary" data-size="md"><span class="cn-button__label">Send invite</span></button>` + iconBtn('More send options', 'chevronDown', 'primary', ' aria-haspopup="menu" aria-expanded="false"')), 'The only case where an attached group is primary: the main action plus a chevron that opens a Menu.'),
+        ex('Attached icon buttons', group('role="group" aria-label="Row actions"', iconBtn('Copy ID', 'copy') + iconBtn('Open in new tab', 'external') + iconBtn('Delete', 'trash'))),
+        ex('Sizes', `<div style="display:flex;flex-wrap:wrap;align-items:center;gap:var(--cn-space-4)">${group('role="group" aria-label="Range small"', outline('Day', ' aria-pressed="true"', '', 'sm') + outline('Week', '', '', 'sm') + outline('Month', '', '', 'sm'))}${group('role="group" aria-label="Range medium"', outline('Day', ' aria-pressed="true"') + outline('Week') + outline('Month'))}${group('role="group" aria-label="Range large"', outline('Day', ' aria-pressed="true"', '', 'lg') + outline('Week', '', '', 'lg') + outline('Month', '', '', 'lg'))}</div>`, '36 / 40 / 44px, from the children\'s size.'),
+        ex('Spaced', `<div class="cn-button-group" data-variant="spaced" data-orientation="horizontal" role="group" aria-label="List tools">${outline('Filter', '', ICON.menu.replace('cn-icon', 'cn-button__icon'))}${outline('Sort')}${outline('Export', '', ICON.external.replace('cn-icon', 'cn-button__icon'))}</div>`, 'Independent tools keep their own radius; 12px apart.'),
+        ex('Vertical attached with a disabled child', `<div class="cn-button-group" data-variant="attached" data-orientation="vertical" role="group" aria-label="Reorder">${outline('Move up')}${outline('Move down')}${outline('Remove', ' disabled')}</div>`, 'Children stretch to the widest label; text aligns to the start. A disabled child fades its content, not its ring.'),
+    ],
+    rules: [
+        'Group only actions that act on the same object or belong to the same tool. Cancel and Save are not a group; they are an action row.',
+        'All children share one size and the outline variant. The single exception is the split button: primary action + primary chevron.',
+        'Attached groups hold 2–5 children. Beyond that, use a toolbar of spaced groups or move the rest into a Menu.',
+        'Attached = one control (the corners say so). Spaced = several controls. Do not attach unrelated tools just to save space.',
+        'A toggle group marks exactly one child with aria-pressed="true" (a range, a view). For a rail with a lifted white item use SegmentedControl instead.',
+        'Vertical groups are rare: zoom controls, reorder handles, a rail of icon actions. Never a vertical group of text actions in a form.',
+        'Do not mix Button and IconButton sizes inside one group; the heights must match exactly for the rings to overlap cleanly.',
+        'Disabled children stay in the group (the layout must not jump); the reason shows in a Tooltip.',
+    ],
+    a11y: [
+        'The root has role="group" and an aria-label naming what the actions act on ("Conversation actions").',
+        'Every child is a real <button>; IconButtons keep their aria-label. The group adds no keyboard behavior (Tab moves between children).',
+        'Toggle children expose aria-pressed="true|false"; a split button chevron exposes aria-haspopup="menu" and aria-expanded with its own aria-label.',
+        'Focus rings are raised above neighbours (z-index) so the ring is never clipped by the next button.',
+    ],
+    related: ['button', 'icon-button', 'segmented-control', 'menu'],
+};

package/lib/components/button.mjs

@@ -0,0 +1,197 @@
+import { CONTROL, RESET_BUTTON, STATE, SIZE_PROP, ex, ICON, typeStyle } from "./_shared.mjs";
+// Flat controls with an explicit hierarchy; all dimensions follow the active tokens.
+const TRANSITION_FAST = {
+    'transition-property': 'background-color, border-color, color, box-shadow, opacity, text-decoration-color',
+    'transition-duration': '{motion.duration.fast}',
+    'transition-timing-function': '{motion.easing.linear}',
+};
+/** Inset borders preserve dimensions across states. */
+const ring = (color) => `inset 0 0 0 1px ${color}`;
+/** Optional token-defined depth; the Canon preset keeps both layers flat. */
+const SHADOW_SOLID = '{shadow.control}, {shadow.xs}';
+/** Bordered controls share the same optional depth tokens. */
+const shadowRinged = (color) => `${ring(color)}, ${SHADOW_SOLID}`;
+/** Icons keep the label contrast on both light and dark action fills. */
+const ICON_ON_SOLID = 'currentColor';
+const ICON_ON_SOLID_HOVER = 'currentColor';
+/** Filled button (primary / primary-destructive). Loading = hover fill, for continuity. */
+const solid = (bg, hoverBg, fg, focus) => ({
+    root: { 'background-color': bg, color: fg, 'box-shadow': SHADOW_SOLID },
+    icon: { color: ICON_ON_SOLID },
+    '@states': {
+        hover: { root: { 'background-color': hoverBg }, icon: { color: ICON_ON_SOLID_HOVER } },
+        loading: { root: { 'background-color': hoverBg } },
+        focus: { root: { 'box-shadow': `${SHADOW_SOLID}, ${focus}` } },
+    },
+});
+/** Ringed button (secondary gray / secondary color / secondary destructive). */
+const bordered = (o) => ({
+    root: { 'background-color': o.bg, color: o.fg, 'box-shadow': shadowRinged(o.ringColor) },
+    icon: { color: o.icon },
+    '@states': {
+        hover: { root: { 'background-color': o.hoverBg, color: o.hoverFg }, icon: { color: o.hoverIcon } },
+        loading: { root: { 'background-color': o.hoverBg } },
+        focus: { root: { 'box-shadow': `${shadowRinged(o.ringColor)}, ${o.focus}` } },
+    },
+});
+/** Transparent button (tertiary gray / tertiary destructive). */
+const plain = (o) => ({
+    root: { 'background-color': 'transparent', color: o.fg, 'box-shadow': 'none' },
+    icon: { color: o.icon },
+    '@states': {
+        hover: { root: { 'background-color': o.hoverBg, color: o.hoverFg }, icon: { color: o.hoverIcon } },
+        loading: { root: { 'background-color': o.hoverBg } },
+        focus: { root: { 'box-shadow': o.focus } },
+    },
+});
+/** Link-styled button (link-color / link-gray / link-destructive): no padding, height = line-height, radius 4, underline only on hover. */
+const linkLike = (o) => ({
+    root: { 'background-color': 'transparent', color: o.fg, 'box-shadow': 'none', height: 'auto', 'padding-inline': '0', 'justify-content': 'normal', 'border-radius': '{radius.sm}' },
+    label: { 'padding-inline': '0', 'text-decoration-line': 'underline', 'text-decoration-color': 'transparent', 'text-underline-offset': '3px' },
+    icon: { color: o.icon },
+    '@states': {
+        hover: { root: { color: o.hoverFg }, label: { 'text-decoration-color': o.decoration }, icon: { color: o.hoverIcon } },
+        focus: { root: { 'box-shadow': o.focus } },
+    },
+});
+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: '{space.2}',
+        ...(LG.has(s) ? { 'line-height': '{font.lineHeight.normal}' } : {}),
+    },
+    label: LG.has(s) ? { 'text-underline-offset': '4px' } : {},
+    icon: { width: CONTROL[s].icon, height: CONTROL[s].icon },
+    spinner: { width: CONTROL[s].icon, height: CONTROL[s].icon },
+});
+const btn = (variant, label, attrs = '', leading = '', trailing = '', size = 'md') => `<button type="button" class="cn-button" data-variant="${variant}" data-size="${size}"${attrs}>${leading}<span class="cn-button__label">${label}</span>${trailing}</button>`;
+const icon = (name) => ICON[name].replace('cn-icon', 'cn-button__icon');
+const row = (...items) => `<div style="display:flex;flex-wrap:wrap;align-items:center;gap:var(--cn-space-3)">${items.join('')}</div>`;
+export const button = {
+    name: 'Button',
+    slug: 'button',
+    category: 'actions',
+    description: 'Triggers an action. Eleven intents share one shape (the system button): flat filled primary with a clear pressed state, ringed secondaries, transparent tertiaries and link styles, each in gray, brand and destructive voices. The intent is a data attribute, never a different component.',
+    usage: 'Use for actions (save, send, open a dialog). Use Link for navigation inside text. One primary button per view region; put it last (right) in a row of actions. Destructive actions use the danger* variants and always confirm.',
+    anatomy: [
+        { part: 'root', element: 'button', description: 'The interactive element. Always a <button type="button|submit"> or an <a role="button"> when it navigates. Add data-icon-only when it holds a single icon and a visually hidden label.' },
+        { part: 'icon', element: 'svg', description: 'Optional leading or trailing icon, 20px (16px on xs). Decorative: aria-hidden. Matches the label on filled buttons; secondary icons use semantic foreground tokens.', optional: true },
+        { part: 'label', element: 'span', description: 'The action label. Verb first ("Save changes"), sentence case, no trailing period.' },
+        { part: 'spinner', element: 'span', description: 'Shown only while data-loading; replaces the icon slot, the label becomes invisible but keeps its width.', optional: true },
+    ],
+    props: {
+        variant: {
+            values: ['primary', 'secondary', 'outline', 'ghost', 'danger', 'link', 'secondary-color', 'link-color', 'danger-outline', 'danger-ghost', 'danger-link'],
+            default: 'primary',
+            description: 'primary = the main filled action; outline = a single neutral edge; secondary = a quiet filled alternative; secondary-color = an action-colored outline; ghost = a transparent toolbar action. link and link-color align with text. The danger variants apply the same hierarchy to destructive actions.',
+        },
+        size: SIZE_PROP(),
+        icon: { values: ['default', 'only'], default: 'default', description: 'only = square icon-only button (padding equals the vertical padding); requires aria-label.' },
+    },
+    states: {
+        hover: STATE.hover(),
+        active: { selector: ':active:not(:disabled):not([aria-disabled="true"])', description: 'While pressed: the primary action deepens to bg-action-active.', markup: 'native :active' },
+        focus: { selector: ':focus-visible', description: 'Keyboard focus. The token-defined focus ring (red for danger*) is added under the existing ring and shadow; never on mouse click.', markup: 'native :focus-visible' },
+        disabled: { selector: ':disabled, &[aria-disabled="true"]', description: 'Not interactive. Whole button at 50% opacity, cursor not-allowed, no hover.', markup: 'disabled attribute (or aria-disabled="true")' },
+        loading: STATE.loading(),
+    },
+    base: {
+        root: {
+            ...RESET_BUTTON,
+            position: 'relative',
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            'white-space': 'nowrap',
+            ...typeStyle('label-md'),
+            'font-size': CONTROL.md.font,
+            'border-radius': '{radius.control}',
+            ...TRANSITION_FAST,
+        },
+        icon: { 'flex-shrink': '0', display: 'block', 'pointer-events': 'none', transition: 'inherit' },
+        label: { display: 'inline-block', transition: 'inherit' },
+        spinner: {
+            display: 'none',
+            position: 'absolute',
+            inset: '0',
+            margin: 'auto',
+            'border-radius': '{radius.full}',
+            border: '2px solid currentColor',
+            'border-right-color': 'transparent',
+            animation: 'cn-spin 0.7s linear infinite',
+        },
+        '@states': {
+            focus: { root: { outline: 'none', 'box-shadow': '{shadow.focus}' } },
+            disabled: { root: { opacity: '{opacity.disabled}', cursor: 'not-allowed' } },
+            loading: {
+                root: { cursor: 'progress', 'pointer-events': 'none' },
+                label: { visibility: 'hidden' },
+                icon: { visibility: 'hidden' },
+                spinner: { display: 'block' },
+            },
+        },
+    },
+    // `size` is emitted before `variant` on purpose: link variants override height/padding
+    // of the size rules without needing a compound per size.
+    variants: {
+        size: {
+            xs: sizeBlock('xs'),
+            sm: sizeBlock('sm'),
+            md: sizeBlock('md'),
+            lg: sizeBlock('lg'),
+            xl: sizeBlock('xl'),
+        },
+        variant: {
+            primary: solid('{color.bg-action}', '{color.bg-action-hover}', '{color.fg-on-action}', '{shadow.focus}'),
+            secondary: bordered({ bg: '{color.bg-subtle}', ringColor: '{color.border-control}', fg: '{color.fg-muted}', hoverBg: '{color.bg-muted}', hoverFg: '{color.fg-default}', icon: '{color.fg-subtle}', hoverIcon: '{color.fg-muted}', focus: '{shadow.focus}' }),
+            outline: bordered({ bg: '{color.bg-surface}', ringColor: '{color.border-control}', fg: '{color.fg-muted}', hoverBg: '{color.bg-subtle}', hoverFg: '{color.fg-default}', icon: '{color.fg-subtle}', hoverIcon: '{color.fg-muted}', focus: '{shadow.focus}' }),
+            'secondary-color': bordered({ bg: '{color.bg-surface}', ringColor: '{color.border-action}', fg: '{color.fg-action}', hoverBg: '{color.bg-action-subtle}', hoverFg: '{color.fg-link-hover}', icon: '{brand.500}', hoverIcon: '{brand.600}', focus: '{shadow.focus}' }),
+            ghost: plain({ fg: '{color.fg-muted}', hoverBg: '{color.bg-subtle}', hoverFg: '{color.fg-default}', icon: '{color.fg-subtle}', hoverIcon: '{color.fg-muted}', focus: '{shadow.focus}' }),
+            link: linkLike({ fg: '{color.fg-muted}', hoverFg: '{color.fg-default}', decoration: '{color.fg-subtle}', icon: '{color.fg-subtle}', hoverIcon: '{color.fg-muted}', focus: '{shadow.focus}' }),
+            'link-color': linkLike({ fg: '{color.fg-action}', hoverFg: '{color.fg-link-hover}', decoration: '{brand.500}', icon: '{brand.500}', hoverIcon: '{brand.600}', focus: '{shadow.focus}' }),
+            danger: solid('{color.bg-danger}', '{color.bg-danger-hover}', '{white}', '{shadow.focus-danger}'),
+            'danger-outline': bordered({ bg: '{color.bg-surface}', ringColor: '{color.border-danger}', fg: '{color.fg-danger}', hoverBg: '{color.bg-danger-subtle}', hoverFg: '{color.fg-danger}', icon: '{red.500}', hoverIcon: '{red.600}', focus: '{shadow.focus-danger}' }),
+            'danger-ghost': plain({ fg: '{color.fg-danger}', hoverBg: '{color.bg-danger-subtle}', hoverFg: '{color.fg-danger}', icon: '{red.500}', hoverIcon: '{red.600}', focus: '{shadow.focus-danger}' }),
+            'danger-link': linkLike({ fg: '{color.fg-danger}', hoverFg: '{color.fg-danger}', decoration: 'currentColor', icon: '{red.500}', hoverIcon: '{red.600}', focus: '{shadow.focus-danger}' }),
+        },
+    },
+    extraCss: `
+.cn-button[data-variant="primary"]:active:not(:disabled):not([aria-disabled="true"]) { background-color: {color.bg-action-active}; }
+@keyframes cn-spin { to { transform: rotate(360deg); } }
+.cn-button[data-icon-only] { padding-inline: 0; aspect-ratio: 1 / 1; }
+.cn-button[data-icon-only] .cn-button__label:not(.cn-sr-only) { display: none; }`,
+    examples: [
+        ex('Primary', btn('primary', 'Save changes'), 'Flat action fill with a contrasting label. One primary action per view region.'),
+        ex('Gray and brand hierarchy', row(btn('outline', 'Save changes'), btn('secondary-color', 'Save changes'), btn('ghost', 'Save changes'), btn('link', 'Save changes'), btn('link-color', 'Save changes')), 'outline = Secondary gray, secondary-color = Secondary color, ghost = Tertiary, link = Link gray, link-color = Link color.'),
+        ex('Secondary (subtle fill)', btn('secondary', 'Save changes'), 'The secondary hover fill at rest. For dense toolbars where a white button would disappear.'),
+        ex('Destructive', row(btn('danger', 'Delete'), btn('danger-outline', 'Delete'), btn('danger-ghost', 'Delete'), btn('danger-link', 'Delete')), 'Primary, secondary, tertiary and link destructive. Every one of them confirms before acting.'),
+        ex('Sizes', row(btn('outline', 'Save changes', '', icon('plus'), '', 'xs'), btn('outline', 'Save changes', '', icon('plus'), '', 'sm'), btn('outline', 'Save changes', '', icon('plus'), '', 'md'), btn('outline', 'Save changes', '', icon('plus'), '', 'lg'), btn('outline', 'Save changes', '', icon('plus'), '', 'xl')), '32 / 36 / 40 / 44 / 48px. Text stays 14px up to md and becomes 16px on lg and xl; icons are 20px (16px on xs).'),
+        ex('With icons and icon-only', row(btn('primary', 'Save changes', '', icon('plus')), btn('outline', 'Save changes', '', '', icon('arrow')), btn('outline', '<span class="cn-sr-only">Copy link</span>', ' data-icon-only aria-label="Copy link"', icon('copy')), btn('ghost', '<span class="cn-sr-only">More</span>', ' data-icon-only aria-label="More"', icon('dots'))), 'Leading icon = what the action is; trailing = where it goes. data-icon-only squares the padding (40×40 on md).'),
+        ex('Loading', row(`<button type="button" class="cn-button" data-variant="primary" data-size="md" data-loading aria-busy="true"><span class="cn-button__spinner" aria-hidden="true"></span><span class="cn-button__label">Saving…</span></button>`, `<button type="button" class="cn-button" data-variant="outline" data-size="md" data-loading aria-busy="true"><span class="cn-button__spinner" aria-hidden="true"></span><span class="cn-button__label">Exporting…</span></button>`), 'The fill switches to the hover color, the label hides but keeps its width.'),
+        ex('Disabled', row(btn('primary', 'Save changes', ' disabled'), btn('outline', 'Save changes', ' disabled'), btn('ghost', 'Save changes', ' disabled'), btn('danger', 'Delete', ' disabled')), 'Whole button at 50% opacity, cursor not-allowed.'),
+    ],
+    recipes: [
+        ex('Action row (dialog footer)', `<div style="display:flex;gap:var(--cn-space-3);justify-content:flex-end">${btn('outline', 'Cancel')}${btn('primary', 'Confirm')}</div>`, 'Secondary gray first, primary last, 12px apart. Never two filled buttons.'),
+    ],
+    rules: [
+        'Exactly one primary button per view region (a dialog, a page header, a form). If two actions feel primary, one of them is not.',
+        'Labels are verbs in sentence case: "Save changes", "Send invite", "Delete". Never "OK", "Submit", "Click here".',
+        'Icons are optional and decorative. Leading icon = what the action is (plus, upload); trailing icon = where it goes (arrow, external). Icon-only buttons set data-icon-only plus aria-label (or use IconButton).',
+        'Never change the height by adding padding. Height comes only from size: 32 / 36 / 40 / 44 / 48px, padding 10 / 12 / 14 / 16 / 18px.',
+        'Link variants (link, link-color, danger-link) have no padding and no height: they align with text. Use them for a low-emphasis action in a row of controls, never inside running text (that is Link).',
+        'Loading: set data-loading and aria-busy="true"; keep the label in the DOM so width does not jump. The fill becomes the hover fill.',
+        'Do not put two filled (primary + danger) buttons side by side. Danger actions live behind a confirm dialog.',
+        'Full-width buttons only on mobile sheets and auth forms.',
+    ],
+    a11y: [
+        'Use <button>. Only use <a> when the action navigates, and then it is a Link or a button-styled anchor with a real href.',
+        'Icon-only buttons need an accessible name: aria-label on the button (or a cn-sr-only label inside), plus data-icon-only for the square padding.',
+        'disabled removes it from the tab order; if the user needs to know why, keep it enabled and show the reason on click.',
+        'Focus ring is shown on :focus-visible only, as a 4px box-shadow ring; never outline: none without replacement.',
+    ],
+    related: ['icon-button', 'button-group', 'link'],
+};