canon-ds 0.1.0

package/lib/components/tabs.mjs

@@ -0,0 +1,207 @@
+import { RESET_BUTTON, ex, ICON, typeStyle } from "./_shared.mjs";
+// Selection persists as a rule or solid segment; hover stays a quieter surface change.
+const TRANSITION_FAST = {
+    'transition-property': 'background-color, border-color, color, box-shadow',
+    'transition-duration': '{motion.duration.fast}',
+    'transition-timing-function': '{motion.easing.linear}',
+};
+// Draw the baseline inside the row so tabs never overhang its scroll area.
+const BASELINE = 'inset 0 calc(-1 * {border.width.thin}) 0 {color.border-default}';
+const ring = (color) => `inset 0 0 0 1px ${color}`;
+/** Persistent selection only; hover must not impersonate the current view. */
+const on = (variant, tail = '') => [`[aria-selected="true"]`, `[aria-current="page"]`]
+    .map((s) => `.cn-tabs[data-variant="${variant}"] .cn-tabs__tab${s}${tail}`)
+    .join(', ');
+/** A gray-50 track holding white pills (button-border, and its older name "pill"). */
+const track = (radius, padding) => ({
+    root: { display: 'inline-flex', 'align-self': 'flex-start', gap: '{space.1}', padding, 'border-radius': radius, 'background-color': '{color.bg-subtle}', 'box-shadow': ring('{color.border-default}') },
+});
+const icon = (name) => ICON[name].replace('cn-icon', 'cn-tabs__icon');
+const tab = (label, selected, id, extra = '') => `<button type="button" role="tab" class="cn-tabs__tab" id="tab-${id}" aria-controls="panel-${id}" aria-selected="${selected}" tabindex="${selected ? '0' : '-1'}"${extra}>${label}</button>`;
+const count = (n) => `<span class="cn-tabs__count">${n}</span>`;
+const SETTINGS = ['My details', 'Profile', 'Password', 'Team', 'Plan', 'Billing'];
+const list = (variant, size, id, labels = SETTINGS, current = 0, orientation = variant === 'line' ? 'vertical' : 'horizontal', width = 'hug') => `<div class="cn-tabs" data-variant="${variant}" data-size="${size}" data-orientation="${orientation}" data-width="${width}" role="tablist" aria-label="Settings"${orientation === 'vertical' ? ' aria-orientation="vertical"' : ''}>${labels.map((l, i) => tab(l, i === current, `${id}-${i}`)).join('')}</div>`;
+export const tabs = {
+    name: 'Tabs',
+    slug: 'tabs',
+    category: 'navigation',
+    description: 'A tablist that switches between views of the same object, in several emphasis levels: underline (2px brand bar on a hairline), button-brand (solid action segment), button-gray (gray-50 pill), button-border (white pill in a gray track) and button-minimal (ringed white pill in a gray track); line is the vertical underline. Labels are semibold, 14px (sm, 36 / 32px) or 16px (md, 44 / 36px), with optional icons and count badges.',
+    usage: 'Use to switch between peer views of one thing: sections of a settings page, panes of a record, views of a card. Route-level tabs are links with aria-current="page"; in-page tabs are buttons with aria-selected. Not for sequential steps (Stepper), not for filters (Tag / SegmentedControl), not for more than about eight options (SidebarNav or a Select).',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'The tablist (role="tablist", aria-label). Flex row of tabs (column when data-orientation="vertical"); carries the bottom hairline for underline, or the gray-50 track for button-border / button-minimal / pill.' },
+        { part: 'tab', element: 'button', description: 'One tab: <button role="tab"> for in-page views, <a aria-current="page"> for routes. Semibold text-quaternary label, radius 6, gap 8; holds text, optional icon, optional count badge.' },
+        { part: 'icon', element: 'svg', description: 'Optional leading icon, 16px (sm) or 20px (md), fg-subtle. If one tab has an icon, all tabs in the list do. Decorative.', optional: true },
+        { part: 'count', element: 'span', description: 'Optional count after the label: a 22px badge (12px medium) in gray; turns brand-tinted on the selected tab of underline / line / button-brand, stays a white "modern" badge elsewhere. Hidden under 768px. Only for numbers that call for action.', optional: true },
+        { part: 'panel', element: 'div', description: 'The tabpanel (role="tabpanel", aria-labelledby the tab). A sibling AFTER the tablist, never inside it; padding-top separates it from the list.', optional: true },
+    ],
+    props: {
+        variant: {
+            values: ['underline', 'pill', 'enclosed', 'button-brand', 'button-gray', 'button-border', 'button-minimal', 'line'],
+            default: 'underline',
+            description: 'underline = the page-section default: 2px brand-600 bar under the selected tab on a full-width gray-200 hairline, brand-700 text when selected . button-brand = solid action segment with brand-700 text (settings sub-navigation, filters in a card). button-gray = gray-50 pill with gray-700 text (quiet toolbars). button-border = white pill with a fine outline inside a gray-50 track with a gray-200 ring (view switch in a card header). button-minimal = white pill with a control outline inside a gray-50 track, radius 8 (dense toolbars). line = vertical list with a 2px brand bar on the left (settings side navigation; set data-orientation="vertical"). pill = the older name of button-border, kept for existing markup. enclosed = folder tabs that merge into the panel below (editor panes only).',
+        },
+        size: {
+            values: ['sm', 'md'],
+            default: 'md',
+            description: 'md = 16px medium labels: 44px button tabs, 36px underline tabs, 32px line tabs; the default for page sections and settings. sm = 14px medium labels: 36px button tabs, 32px underline tabs, 24px line tabs; inside cards, drawers and dense toolbars.',
+        },
+        orientation: {
+            values: ['horizontal', 'vertical'],
+            default: 'horizontal',
+            description: 'horizontal = a row (every variant except line). vertical = a column, 8px between tabs, labels aligned to the start; use with line, button-brand, button-gray, button-border or button-minimal for a settings side navigation.',
+        },
+        width: {
+            values: ['hug', 'full'],
+            default: 'hug',
+            description: 'hug = tabs take the width of their labels (default). full = the list spans its container and every tab takes an equal share (mobile, card headers with 2–4 tabs); underline gaps grow from 12 to 16px.',
+        },
+    },
+    states: {
+        current: { selector: ' .cn-tabs__tab[aria-selected="true"], & .cn-tabs__tab[aria-current="page"]', description: 'The selected tab (lives on the TAB, not the root). underline / line: brand-700 text and the 2px brand-600 bar; button-brand: action fill and on-action text; button-gray: gray-50 fill; button-border: white pill with a fine outline; button-minimal: white pill with a control outline; enclosed: surface fill with an open bottom.', markup: 'aria-selected="true" on a role="tab" button, or aria-current="page" on a link tab' },
+        hover: { selector: ' .cn-tabs__tab:hover', description: 'Pointer over a tab: a subtle surface change; the selection bar stays on the current tab.', markup: 'native :hover on the tab' },
+        focus: { selector: ' .cn-tabs__tab:focus-visible', description: 'Keyboard focus on a tab: the token-defined focus ring around that tab.', markup: 'native :focus-visible on the tab' },
+        disabled: { selector: ' .cn-tabs__tab:disabled, & .cn-tabs__tab[aria-disabled="true"]', description: 'Tab cannot be chosen (feature off, no data yet). 50% opacity, no hover; keep the label so users know the view exists.', markup: 'disabled or aria-disabled="true" on the tab' },
+    },
+    base: {
+        root: {
+            display: 'flex',
+            'align-items': 'center',
+            gap: '{space.1}',
+            'min-width': '0',
+            'max-width': '100%',
+        },
+        tab: {
+            ...RESET_BUTTON,
+            position: 'relative',
+            'z-index': '{z.raised}',
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            gap: '{space.2}',
+            'flex-shrink': '0',
+            padding: '{space.2.5}',
+            'border-radius': '{radius.md}',
+            ...typeStyle('label-lg'),
+            color: '{color.fg-subtle}',
+            'white-space': 'nowrap',
+            ...TRANSITION_FAST,
+        },
+        icon: { width: '{size.icon.md}', height: '{size.icon.md}', 'flex-shrink': '0', display: 'block', color: '{color.fg-subtle}', transition: 'inherit' },
+        count: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            height: '22px',
+            'padding-inline': '{space.2}',
+            'border-radius': '{radius.sm}',
+            'background-color': '{color.bg-subtle}',
+            'box-shadow': ring('{color.border-default}'),
+            color: '{color.fg-muted}',
+            ...typeStyle('label-xs'),
+            'font-variant-numeric': 'tabular-nums',
+            transition: 'inherit',
+        },
+    },
+    variants: {
+        variant: {
+            underline: {
+                root: { gap: '{space.3}', 'align-items': 'stretch', 'box-shadow': BASELINE },
+                tab: { padding: '0 {space.0.5} {space.2.5}', 'border-radius': '0', 'border-bottom': '{border.width.medium} solid transparent' },
+            },
+            pill: track('{radius.control}', '{space.0.5}'),
+            enclosed: {
+                root: { 'box-shadow': BASELINE, 'align-items': 'flex-end', gap: '{space.1}' },
+                tab: { 'border-width': '{border.width.thin}', 'border-style': 'solid', 'border-color': 'transparent', 'border-bottom-width': '0', 'border-radius': '{radius.control} {radius.control} 0 0' },
+            },
+            'button-brand': { root: { gap: '{space.1}' } },
+            'button-gray': { root: { gap: '{space.1}' } },
+            'button-border': track('{radius.control}', '{space.0.5}'),
+            'button-minimal': { root: { display: 'inline-flex', 'align-self': 'flex-start', gap: '{space.0.5}', 'border-radius': '{radius.control}', 'background-color': '{color.bg-subtle}', 'box-shadow': ring('{color.border-default}') }, tab: { 'border-radius': '{radius.control}' } },
+            line: {
+                root: { 'flex-direction': 'column', 'align-items': 'stretch', gap: '{space.2}', width: 'max-content' },
+                tab: { 'justify-content': 'flex-start', padding: '{space.1} {space.3.5} {space.1} {space.3}', 'border-radius': '0', 'border-inline-start': '{border.width.medium} solid transparent' },
+            },
+        },
+        size: {
+            sm: {
+                tab: { padding: '{space.2} {space.2.5}', ...typeStyle('label-md'), gap: '{space.1.5}' },
+                icon: { width: '{size.icon.sm}', height: '{size.icon.sm}' },
+            },
+            md: { root: {} },
+        },
+        orientation: {
+            horizontal: { root: {} },
+            vertical: { root: { 'flex-direction': 'column', 'align-items': 'stretch', gap: '{space.2}', width: 'max-content' }, tab: { 'justify-content': 'flex-start' } },
+        },
+        width: {
+            hug: { root: {} },
+            full: { root: { width: '100%', display: 'flex', 'align-self': 'stretch' }, tab: { flex: '1 1 0', 'min-width': '0' } },
+        },
+    },
+    compound: [
+        { when: { variant: 'underline', size: 'sm' }, block: { tab: { padding: '0 {space.0.5} {space.2.5}' } } },
+        { when: { variant: 'line', size: 'sm' }, block: { tab: { padding: '{space.0.5} {space.3} {space.0.5} {space.2.5}' } } },
+        { when: { variant: 'underline', width: 'full' }, block: { root: { gap: '{space.4}' } } },
+        { when: { variant: 'pill', size: 'sm' }, block: { root: { 'border-radius': '{radius.control}', padding: '{space.0.5}' } } },
+        { when: { variant: 'button-border', size: 'sm' }, block: { root: { 'border-radius': '{radius.control}', padding: '{space.0.5}' } } },
+        { when: { variant: 'button-brand', orientation: 'vertical' }, block: { root: { gap: '{space.1}' } } },
+        { when: { variant: 'button-gray', orientation: 'vertical' }, block: { root: { gap: '{space.1}' } } },
+    ],
+    extraCss: `
+.cn-tabs__tab:hover:not(:disabled):not([aria-disabled="true"]):not([aria-selected="true"]):not([aria-current="page"]) { background-color: {color.bg-subtle}; color: {color.fg-default}; }
+.cn-tabs:not([data-orientation="vertical"]):not([data-variant="line"]) { overflow-x: auto; }
+.cn-tabs__panel { padding-top: {space.6}; outline: none; }
+.cn-tabs__panel:focus-visible { box-shadow: {shadow.focus}; border-radius: {radius.sm}; }
+${on('underline')} { color: {color.fg-action}; border-bottom-color: {color.bg-action}; }
+${on('line')} { color: {color.fg-action}; border-inline-start-color: {color.bg-action}; }
+${on('button-brand')} { color: {color.fg-on-action}; background-color: {color.bg-action}; }
+${on('button-gray')} { color: {color.fg-muted}; background-color: {color.bg-subtle}; }
+${on('button-border')}, ${on('pill')} { color: {color.fg-default}; background-color: {color.bg-surface}; box-shadow: ${ring('{color.border-control}')}; }
+${on('button-minimal')} { color: {color.fg-muted}; background-color: {color.bg-surface}; box-shadow: ${ring('{color.border-control}')}, {shadow.xs}; }
+${on('enclosed')} { color: {color.fg-muted}; background-color: {color.bg-surface}; border-color: {color.border-default}; }
+${on('underline', ' .cn-tabs__icon')}, ${on('line', ' .cn-tabs__icon')} { color: {color.fg-action}; }
+${on('button-brand', ' .cn-tabs__icon')} { color: inherit; }
+${on('button-gray', ' .cn-tabs__icon')}, ${on('button-border', ' .cn-tabs__icon')}, ${on('pill', ' .cn-tabs__icon')}, ${on('button-minimal', ' .cn-tabs__icon')}, ${on('enclosed', ' .cn-tabs__icon')} { color: {color.fg-default}; }
+${on('underline', ' .cn-tabs__count')}, ${on('line', ' .cn-tabs__count')} { background-color: {color.bg-action-subtle}; box-shadow: none; color: {color.fg-action}; }
+${on('button-brand', ' .cn-tabs__count')} { background-color: transparent; box-shadow: none; color: inherit; }
+.cn-tabs[data-variant="button-gray"] .cn-tabs__count, .cn-tabs[data-variant="button-border"] .cn-tabs__count, .cn-tabs[data-variant="pill"] .cn-tabs__count, .cn-tabs[data-variant="button-minimal"] .cn-tabs__count, .cn-tabs[data-variant="enclosed"] .cn-tabs__count { background-color: {color.bg-surface}; box-shadow: ${ring('{color.border-control}')}, {shadow.xs}; }
+.cn-tabs__tab:focus-visible { outline: 2px solid {color.border-action}; outline-offset: -2px; }
+.cn-tabs[data-variant="underline"] .cn-tabs__tab:focus-visible, .cn-tabs[data-variant="line"] .cn-tabs__tab:focus-visible { border-radius: {radius.sm}; }
+.cn-tabs__tab:disabled, .cn-tabs__tab[aria-disabled="true"] { opacity: {opacity.disabled}; cursor: not-allowed; pointer-events: none; }
+@media (max-width: {breakpoint.md}) { .cn-tabs .cn-tabs__count { display: none; } }`,
+    examples: [
+        ex('Underline (default)', list('underline', 'md', 'u'), '16px medium labels, 36px tall; the selected tab is brand-700 with a 2px brand-600 bar on the gray-200 hairline.'),
+        ex('Underline sm with icons and counts', `<div class="cn-tabs" data-variant="underline" data-size="sm" data-orientation="horizontal" data-width="hug" role="tablist" aria-label="Inbox">${tab(`${icon('inbox')}Unread${count('12')}`, true, 'in-0')}${tab(`${icon('user')}Mentions${count('3')}`, false, 'in-1')}${tab(`${icon('check')}Done`, false, 'in-2')}</div>`, '14px labels, 32px tall, 16px icons. The count of the selected tab turns brand-tinted; it hides below 768px.'),
+        ex('Button brand', list('button-brand', 'sm', 'bb'), 'A solid action-colored segment marks selection; hover stays neutral.'),
+        ex('Button gray', list('button-gray', 'sm', 'bg'), 'Same pill in gray-50 with gray-700 text.'),
+        ex('Button border', list('button-border', 'sm', 'bo', ['All', 'Active', 'Archived']), 'A quiet track with 2px inset spacing holds a flat, outlined selected segment.'),
+        ex('Button minimal', list('button-minimal', 'sm', 'bm', ['Day', 'Week', 'Month']), 'A compact neutral track; the selected segment uses the surface fill and a control outline.'),
+        ex('Line (vertical)', `<div style="display:flex;gap:var(--cn-space-8);align-items:flex-start">${list('line', 'md', 'ln')}${list('button-brand', 'sm', 'lv', SETTINGS, 2, 'vertical')}</div>`, 'line = 2px brand bar on the left, 32px rows; any button variant becomes a column with data-orientation="vertical".'),
+        ex('Full width', `<div style="width:100%;max-width:480px">${list('underline', 'sm', 'fw', ['Overview', 'Activity', 'Files', 'Notes'], 1, 'horizontal', 'full')}</div>`, 'data-width="full": every tab takes an equal share and the underline gaps grow to 16px.'),
+        ex('Pill and enclosed (kept for existing markup)', `<div style="display:flex;flex-direction:column;gap:var(--cn-space-6);align-items:flex-start">${list('pill', 'md', 'pl', ['Overview', 'Activity', 'Files'])}${list('enclosed', 'md', 'en', ['Preview', 'HTML', 'CSS', 'React'], 1)}</div>`, 'pill is the same look as button-border, with token-defined corners and 2px inset spacing. enclosed is the folder tab for editor panes.'),
+        ex('With panel', `<div style="width:100%;max-width:560px">${list('underline', 'md', 'pn', ['Steps', 'Replies', 'Settings'])}<div class="cn-tabs__panel" role="tabpanel" id="panel-pn-0" aria-labelledby="tab-pn-0" tabindex="0"><p class="cn-text-body-md">4 steps over 9 days. The next email goes out Thursday at 09:00 to 38 customers.</p></div></div>`, 'The panel is a sibling after the tablist with padding-top 24px.'),
+        ex('Route tabs with a disabled tab', `<div class="cn-tabs" data-variant="underline" data-size="md" data-orientation="horizontal" data-width="hug" aria-label="Reports"><a href="#" class="cn-tabs__tab" aria-current="page">Customers</a><a href="#" class="cn-tabs__tab">Invoices</a><a href="#" class="cn-tabs__tab">Files</a><a class="cn-tabs__tab" aria-disabled="true" title="Available on the Business plan">Attribution</a></div>`, 'Links with aria-current="page" when each tab is a URL; no tablist role. The disabled tab keeps its label at 50% opacity.'),
+    ],
+    rules: [
+        '2–8 tabs. With one there is nothing to switch; beyond eight use SidebarNav or a Select.',
+        'Labels are 1–3 words in sentence case, nouns ("My details", "Billing"). Never verbs, never trailing punctuation.',
+        'Exactly one tab is selected at all times; the first one by default. Never start with nothing selected.',
+        'Heights come only from size: md = 44px button tabs / 36px underline / 32px line; sm = 36 / 32 / 24. Never add padding to change them.',
+        'Counts are the 22px badge (count part); only for numbers that ask for action (unread, waiting, failed). Totals belong in the panel.',
+        'Icons are all-or-none within one list, leading, 16px at sm and 20px at md, fg-subtle at rest and brand or ink when selected.',
+        'underline for page sections and settings pages; button-brand or button-gray for a sub-navigation inside a page; button-border / button-minimal for a view switch inside a card header or toolbar; line (vertical) for a settings side navigation; enclosed only for editor panes with a visible panel border.',
+        'Hover uses a quiet fill. The selection rule or solid segment appears only on the current tab.',
+        'Tabs switch views of the same object. Different pages are links with aria-current="page"; a sequential flow is a Stepper.',
+        'Never nest a tablist inside a tabpanel. A second level of navigation is a SidebarNav or a button-* Tabs inside the card, not tabs under tabs.',
+        'Tabs never wrap onto a second line. On narrow screens use data-width="full" with ≤ 4 tabs, or let the tablist scroll horizontally. Focus stays inside the tab so it remains visible in the scroll area.',
+    ],
+    a11y: [
+        'In-page tabs: root role="tablist" with aria-label, tabs are <button role="tab" aria-selected aria-controls>, panels are role="tabpanel" aria-labelledby, tabindex="0".',
+        'Roving tabindex: only the selected tab is in the tab order (tabindex="0"); Left/Right (Up/Down when vertical) move focus, Home/End jump, Enter/Space or automatic activation selects.',
+        'Route tabs are plain <a href> with aria-current="page" inside a <nav>; do NOT add role="tab" to links that navigate.',
+        'Disabled tabs use aria-disabled="true" (stay perceivable) and a title or Tooltip with the reason.',
+        'Selection is conveyed by text color and the bar or pill, never by color alone; the count keeps its number in text and hides only visually on mobile.',
+        'Vertical lists set aria-orientation="vertical" on the tablist so arrow-key direction matches.',
+    ],
+    related: ['topbar', 'sidebar-nav', 'segmented-control', 'stepper', 'badge'],
+};

package/lib/components/tag.mjs

@@ -0,0 +1,196 @@
+import { RESET_BUTTON, STATE, ex, ICON, typeStyle } from "./_shared.mjs";
+// the reference tag: a white chip with a gray-300 ring, radius 6 and 14px medium gray-700 text
+// (12px at sm); sm 24 · md 28 · lg 32px tall; a leading checkbox (14 / 16 / 18), avatar (16)
+// or 8px dot; a trailing count chip (radius 3, gray-100) or a close × (radius 3, gray-400);
+// 50ms transitions, 4px focus ring.
+const TRANSITION_TAG = {
+    'transition-property': 'background-color, box-shadow, color',
+    'transition-duration': '{motion.duration.fast}',
+    'transition-timing-function': '{motion.easing.linear}',
+};
+const ring = (color) => `inset 0 0 0 1px ${color}`;
+const SELECTED = { 'background-color': '{color.bg-action-subtle}', 'box-shadow': ring('{color.border-action}'), color: '{color.fg-action}' };
+/** Rest paint per tone × variant. */
+const PAINT = {
+    'neutral:outline': { bg: '{color.bg-surface}', fg: '{color.fg-muted}', ring: '{color.border-control}' },
+    'neutral:soft': { bg: '{color.bg-subtle}', fg: '{color.fg-muted}', ring: 'transparent' },
+    'accent:outline': { bg: '{color.bg-surface}', fg: '{color.fg-accent}', ring: '{brand.300}' },
+    'accent:soft': { bg: '{color.bg-accent-subtle}', fg: '{color.fg-accent}', ring: 'transparent' },
+};
+const compound = Object.entries(PAINT).map(([key, p]) => {
+    const [tone, variant] = key.split(':');
+    return {
+        when: { tone, variant },
+        block: {
+            root: { 'background-color': p.bg, color: p.fg, 'box-shadow': ring(p.ring) },
+            '@states': { selected: { root: SELECTED } },
+        },
+    };
+});
+const AVATAR_SRC = "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Crect width='64' height='64' fill='%23CDCED1'/%3E%3Ccircle cx='32' cy='25' r='11' fill='%23FAFAFA'/%3E%3Cpath d='M10 64c2-13 11-21 22-21s20 8 22 21z' fill='%23FAFAFA'/%3E%3C/svg%3E";
+const X = '<svg class="cn-icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><path d="M4 4l8 8M12 4l-8 8"/></svg>';
+const CHECK = '<svg class="cn-tag__check" viewBox="0 0 14 14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M11.67 3.5L5.25 9.92 2.33 7"/></svg>';
+const mk = (label, o = {}) => `<${o.tag ?? 'span'}${o.tag === 'button' ? ' type="button"' : ''} class="cn-tag" data-tone="${o.tone ?? 'neutral'}" data-variant="${o.variant ?? 'outline'}" data-size="${o.size ?? 'md'}"${o.attrs ?? ''}>${o.before ?? ''}<span class="cn-tag__label">${label}</span>${o.after ?? ''}</${o.tag ?? 'span'}>`;
+const chip = (label, pressed, extra = '') => mk(label, { tag: 'button', attrs: ` aria-pressed="${pressed}"${extra}` });
+const removable = (label, size = 'md', tone = 'neutral', variant = 'outline') => mk(label, { size, tone, variant, after: `<button type="button" class="cn-tag__remove" aria-label="Remove ${label}">${X}</button>` });
+const counted = (label, n, size = 'md') => mk(label, { size, after: `<span class="cn-tag__count">${n}</span>` });
+const checkbox = (label, checked, size = 'md', extra = '') => mk(label, { size, tag: 'button', attrs: ` role="checkbox" aria-checked="${checked}"${extra}`, before: `<span class="cn-tag__checkbox" aria-hidden="true">${CHECK}</span>` });
+const withAvatar = (label, size = 'md') => mk(label, { size, before: `<img class="cn-tag__avatar" src="${AVATAR_SRC}" alt="">`, after: `<button type="button" class="cn-tag__remove" aria-label="Remove ${label}">${X}</button>` });
+const withDot = (label, size = 'md') => mk(label, { size, before: '<span class="cn-tag__dot"></span>' });
+export const tag = {
+    name: 'Tag',
+    slug: 'tag',
+    category: 'data-display',
+    description: 'The reference tag: a white chip with a gray-300 ring, radius 6 and 14px medium text (sm 24 · md 28 · lg 32px) that you can toggle or remove; leading checkbox, avatar or dot, trailing count chip or close ×. Unlike Badge it responds to focus and selection.',
+    usage: 'Filter bars (toggle or checkbox tags), token fields and applied-filter rows (removable tags), multi-select values, keyword lists with counts. Not for statuses or categories that only inform (Badge), and not for actions with a verb (Button).',
+    anatomy: [
+        { part: 'root', element: 'span', description: 'A <span> for a value; a <button aria-pressed> (or role="checkbox" aria-checked with the checkbox part) when selectable. White, gray-300 ring, radius 6.' },
+        { part: 'checkbox', element: 'span', description: 'Leading 14 / 16 / 18px checkbox (radius 4, gray-300 ring); brand-600 with a white check when the tag is checked.', optional: true },
+        { part: 'check', element: 'svg', description: 'The 10 / 12 / 14px check inside the checkbox; hidden until checked.', optional: true },
+        { part: 'avatar', element: 'img', description: 'Leading 16px round avatar with the 0.5px contrast ring.', optional: true },
+        { part: 'dot', element: 'span', description: 'Leading 8px status dot, green-500 by default (override the color inline for other states).', optional: true },
+        { part: 'icon', element: 'svg', description: 'Optional 12px leading icon (a flag, a spark for suggested values). Decorative.', optional: true },
+        { part: 'label', element: 'span', description: 'The value text, sentence case, 1–3 words. Never truncated.' },
+        { part: 'count', element: 'span', description: 'Trailing count chip: radius 3, gray-100, 12px medium (14px at lg), padding 0 × 4–6.', optional: true },
+        { part: 'remove', element: 'button', description: 'Trailing close ×: radius 3, gray-400, 14 / 16 / 20px box with a 10 / 12 / 14px icon; gray-50 on hover. Its own focus target with aria-label "Remove {label}".', optional: true },
+    ],
+    props: {
+        tone: { values: ['neutral', 'accent'], default: 'neutral', description: 'neutral = user-chosen values and filters (the reference); accent = values suggested by the assistant or tied to the brand (use sparingly, a few per view).' },
+        variant: { values: ['outline', 'soft'], default: 'outline', description: 'outline = white with the gray-300 ring (the reference tag, on surfaces); soft = gray-50 fill with no ring (on the canvas, inside inputs, in dense rows).' },
+        size: { values: ['sm', 'md', 'lg'], default: 'md', description: 'sm 24px with 12px text (table cells, dense filter rows); md 28px with 14px text (default); lg 32px with 14px text (filter bars next to 32px controls).' },
+    },
+    states: {
+        hover: STATE.hover(),
+        selected: { selector: '[data-selected], &[aria-pressed="true"], &[aria-checked="true"]', description: 'Toggled on. A pressed chip gets the brand tint; a checkbox tag fills its checkbox brand-600 with the white check.', markup: 'aria-pressed="true" on a button tag, aria-checked="true" on a role="checkbox" tag, or data-selected' },
+        focus: STATE.focus(),
+        disabled: STATE.disabled(),
+    },
+    base: {
+        root: {
+            ...RESET_BUTTON,
+            display: 'inline-flex',
+            'align-items': 'center',
+            gap: '5px',
+            height: '{space.7}',
+            'padding-inline': '9px',
+            'padding-block': '0',
+            'border-radius': '{radius.md}',
+            ...typeStyle('label-sm'),
+            'background-color': '{color.bg-surface}',
+            'box-shadow': ring('{color.border-control}'),
+            color: '{color.fg-muted}',
+            'white-space': 'nowrap',
+            'vertical-align': 'middle',
+            'max-width': '100%',
+            cursor: 'default',
+            ...TRANSITION_TAG,
+        },
+        checkbox: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            width: '{space.4}',
+            height: '{space.4}',
+            'border-radius': '{radius.sm}',
+            'background-color': '{color.bg-surface}',
+            'box-shadow': ring('{color.border-control}'),
+            color: '{color.fg-on-action}',
+            'margin-inline-start': '-5px',
+            ...TRANSITION_TAG,
+        },
+        check: { width: '{size.icon.xs}', height: '{size.icon.xs}', display: 'block', opacity: '0', transition: 'inherit' },
+        avatar: { width: '{space.4}', height: '{space.4}', 'border-radius': '{radius.full}', 'object-fit': 'cover', 'flex-shrink': '0', 'max-width': 'none', 'background-color': '{color.bg-muted}', 'box-shadow': 'inset 0 0 0 0.5px color-mix(in srgb, {black} 16%, transparent)', 'margin-inline-start': '-4px' },
+        dot: { width: '{space.2}', height: '{space.2}', 'border-radius': '{radius.full}', 'flex-shrink': '0', 'background-color': '{green.500}', 'margin-inline-start': '-2px' },
+        icon: { width: '{size.icon.xs}', height: '{size.icon.xs}', 'flex-shrink': '0', color: '{color.fg-subtle}' },
+        label: { display: 'inline-block', 'min-width': '0' },
+        count: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            'padding-inline': '5px',
+            'border-radius': '3px',
+            'background-color': '{color.bg-muted}',
+            ...typeStyle('label-xs'),
+            color: '{color.fg-muted}',
+            'font-variant-numeric': 'tabular-nums',
+            'margin-inline-end': '-6px',
+        },
+        remove: {
+            ...RESET_BUTTON,
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            width: '{space.4}',
+            height: '{space.4}',
+            padding: '0',
+            'margin-inline-start': '-2px',
+            'margin-inline-end': '-5px',
+            'border-radius': '3px',
+            color: '{color.fg-subtle}',
+            ...TRANSITION_TAG,
+        },
+        '@states': {
+            selected: { root: SELECTED, icon: { color: '{color.fg-action}' } },
+            focus: { root: { outline: 'none', 'box-shadow': `${ring('{color.border-control}')}, {shadow.focus}` } },
+            disabled: { root: { opacity: '{opacity.disabled}', cursor: 'not-allowed', 'pointer-events': 'none' } },
+        },
+    },
+    variants: {
+        tone: { neutral: { root: {} }, accent: { root: {} } },
+        variant: { outline: { root: {} }, soft: { root: {} } },
+        size: {
+            sm: { root: { height: '{space.6}', 'padding-inline': '{space.2}', gap: '{space.1}', ...typeStyle('label-xs') }, checkbox: { width: '{space.3.5}', height: '{space.3.5}', 'margin-inline-start': '-3px' }, check: { width: '{space.2.5}', height: '{space.2.5}' }, avatar: { 'margin-inline-start': '-4px' }, count: { 'padding-inline': '{space.1}', 'margin-inline-end': '-4px' }, remove: { width: '{space.3.5}', height: '{space.3.5}', 'margin-inline-end': '-4px' }, icon: { width: '{space.2.5}', height: '{space.2.5}' } },
+            md: { root: { height: '{space.7}', 'padding-inline': '9px' } },
+            lg: { root: { height: '{space.8}', 'padding-inline': '{space.2.5}', gap: '{space.1.5}' }, checkbox: { width: '18px', height: '18px', 'margin-inline-start': '-5px' }, check: { width: '{space.3.5}', height: '{space.3.5}' }, avatar: { 'margin-inline-start': '-3px' }, count: { 'padding-inline': '{space.1.5}', ...typeStyle('label-sm'), 'margin-inline-end': '-6px' }, remove: { width: '{space.5}', height: '{space.5}', 'margin-inline-end': '-6px' } },
+        },
+    },
+    compound,
+    extraCss: `
+button.cn-tag, a.cn-tag { cursor: pointer; }
+button.cn-tag:hover:not(:disabled):not([aria-pressed="true"]):not([aria-checked="true"]) { background-color: {color.bg-subtle}; }
+.cn-tag[aria-checked="true"] { background-color: {color.bg-surface}; box-shadow: ${ring('{color.border-control}')}; color: {color.fg-muted}; }
+.cn-tag[aria-checked="true"] .cn-tag__checkbox, .cn-tag[data-selected] .cn-tag__checkbox { background-color: {color.bg-action}; box-shadow: ${ring('{color.bg-action}')}; }
+.cn-tag[aria-checked="true"] .cn-tag__check, .cn-tag[data-selected] .cn-tag__check { opacity: 1; }
+.cn-tag[aria-checked="true"]:focus-visible, .cn-tag[aria-checked="true"]:hover:not(:disabled) { background-color: {color.bg-surface}; }
+.cn-tag[aria-checked="true"]:focus-visible { box-shadow: ${ring('{color.border-control}')}, {shadow.focus}; }
+.cn-tag__remove .cn-icon { width: {size.icon.xs}; height: {size.icon.xs}; }
+.cn-tag[data-size="sm"] .cn-tag__remove .cn-icon { width: {space.2.5}; height: {space.2.5}; }
+.cn-tag[data-size="lg"] .cn-tag__remove .cn-icon { width: {space.3.5}; height: {space.3.5}; }
+.cn-tag__remove:hover { background-color: {color.bg-subtle}; color: {color.fg-muted}; }
+.cn-tag__remove:focus-visible { outline: none; box-shadow: {shadow.focus}; }
+.cn-tag[data-selected] .cn-tag__remove, .cn-tag[aria-pressed="true"] .cn-tag__remove { color: {color.fg-action}; }
+.cn-tag:disabled .cn-tag__remove, .cn-tag[aria-disabled="true"] .cn-tag__remove { pointer-events: none; }
+.cn-tag[data-variant="soft"] .cn-tag__checkbox, .cn-tag[data-variant="soft"][aria-checked="true"] { box-shadow: ${ring('{color.border-control}')}; }`,
+    examples: [
+        ex('Sizes', `<div style="display:flex;align-items:center;gap:var(--cn-space-3)">${mk('Design', { size: 'sm' })}${mk('Design', { size: 'md' })}${mk('Design', { size: 'lg' })}</div>`, 'sm 24px (12px text) · md 28px · lg 32px (14px text). White, gray-300 ring, radius 6.'),
+        ex('Removable values', `<div style="display:flex;flex-wrap:wrap;gap:var(--cn-space-2)">${removable('Design')}${removable('Product')}${removable('Marketing')}${removable('Engineering', 'sm')}${removable('Sales', 'lg')}</div>`, 'The close × is a 16px (14 / 20) radius-3 button with its own focus ring; gray-50 on hover.'),
+        ex('With count', `<div style="display:flex;flex-wrap:wrap;gap:var(--cn-space-2)">${counted('Design', '5', 'sm')}${counted('Design', '5')}${counted('Design', '5', 'lg')}</div>`, 'The count chip: radius 3, gray-100, 12px medium (14px at lg).'),
+        ex('Checkbox tags', `<div role="group" aria-label="Teams" style="display:flex;flex-wrap:wrap;gap:var(--cn-space-2)">${checkbox('Design', true)}${checkbox('Product', false)}${checkbox('Engineering', true)}${checkbox('Sales', false, 'md', ' disabled')}</div>`, 'A leading 16px checkbox (14 / 18 at sm / lg); checked = brand-600 with the white check. The tag stays white.'),
+        ex('With avatar and with dot', `<div style="display:flex;flex-wrap:wrap;gap:var(--cn-space-2)">${withAvatar('Maya Chen')}${withAvatar('Daniel Costa', 'lg')}${withDot('Online')}${withDot('Available', 'sm')}</div>`, 'A 16px avatar with the contrast ring; an 8px green dot for live states.'),
+        ex('Selectable filter chips', `<div style="display:flex;flex-wrap:wrap;gap:var(--cn-space-2)">${chip('All', true)}${chip('Active', false)}${chip('Archived', false)}${chip('Shared with me', false)}</div>`, 'aria-pressed="true" is the selected state: brand tint, brand ring and text.'),
+        ex('Soft and accent', `<div style="display:flex;flex-wrap:wrap;gap:var(--cn-space-2)">${removable('Draft', 'md', 'neutral', 'soft')}${mk('Suggested: Q3 launch', { tone: 'accent', variant: 'soft', before: ICON.spark.replace('cn-icon', 'cn-tag__icon'), after: `<button type="button" class="cn-tag__remove" aria-label="Remove Suggested: Q3 launch">${X}</button>` })}${mk('Lumen', { tone: 'accent' })}</div>`, 'soft = gray-50 fill, no ring; accent for assistant suggestions and brand-linked values.'),
+        ex('Disabled', `<div style="display:flex;flex-wrap:wrap;gap:var(--cn-space-2)">${chip('Archived', false, ' disabled')}${mk('Locked filter', { attrs: ' aria-disabled="true"', after: `<button type="button" class="cn-tag__remove" aria-label="Remove Locked filter" disabled>${X}</button>` })}</div>`, '50% opacity, cursor not-allowed.'),
+    ],
+    rules: [
+        'Tag is interactive or removable; Badge is not. If it cannot be toggled or removed, it is a Badge.',
+        'Labels are nouns in sentence case, 1–3 words, never uppercase and never truncated.',
+        'Heights come only from size: 24 / 28 / 32px with 8 / 9 / 10px side padding; the leading and trailing parts pull in by their margins, never by extra padding.',
+        'Selectable tags are <button aria-pressed> (brand tint) or role="checkbox" with the checkbox part (white tag, brand checkbox); removable tags are a <span> with a remove <button> inside. A tag is never both selectable and removable.',
+        'The remove button is always last, always has aria-label "Remove {label}", and is the only element with hover feedback inside a span tag.',
+        'One leading part at most (checkbox, avatar, dot or icon) and one trailing part at most (count or ×).',
+        'outline on surfaces (filter bars over white); soft on the canvas, inside inputs and in dense rows where rings would pile up.',
+        'accent only for assistant-suggested or brand-linked values, and only a few per view. Never as decoration.',
+        'Rows of tags wrap with an 8px gap and align to the start; do not right-align or justify them. One size per row.',
+    ],
+    a11y: [
+        'Selectable: <button type="button" aria-pressed="true|false">, or role="checkbox" aria-checked with the checkbox part. Toggle the aria attribute, not only the data attribute.',
+        'Removable: the remove button announces "Remove {label}"; after removing, move focus to the next tag or back to the input.',
+        'Both the tag and its remove button are separate Tab stops with their own :focus-visible ring.',
+        'Avatars inside tags are decorative (alt=""); the label names the person. A dot needs its meaning in the label ("Online").',
+        'Disabled tags stay readable (opacity only). Use disabled on buttons and aria-disabled="true" on span tags.',
+    ],
+    related: ['badge', 'counter', 'input', 'checkbox', 'button', 'combobox'],
+};

package/lib/components/tags-input.mjs

@@ -0,0 +1,146 @@
+import { CONTROL, FOCUS_RING, RESET_BUTTON, TRANSITION_COLORS, SIZE_PROP, ex, ICON, typeStyle } from "./_shared.mjs";
+// Token field: chips wrap inside one bordered box, followed by a bare input that grows to fill
+// the last line. Enter / comma turns the text into a chip; Backspace on an empty input removes the last one.
+const sizeBlock = (s, o) => ({
+    root: { 'min-height': CONTROL[s].height, padding: o.pad, gap: o.gap, 'border-radius': CONTROL[s].radius },
+    tag: { height: o.chip, 'font-size': o.chipFont },
+    field: { height: o.chip, 'font-size': CONTROL[s].font },
+});
+const chip = (label, attrs = '') => `<span class="cn-tags-input__tag">${label}<button type="button" class="cn-tags-input__tag-remove" aria-label="Remove ${label}"${attrs}>${ICON.x}</button></span>`;
+const box = (o) => `<div class="cn-tags-input" data-size="${o.size ?? 'md'}"${o.root ?? ''} style="max-width:420px">${o.tags.map((t) => chip(t, o.removeAttrs)).join('')}<input class="cn-tags-input__field" type="text" ${o.input}></div>`;
+export const tagsInput = {
+    name: 'TagsInput',
+    slug: 'tags-input',
+    category: 'forms',
+    description: 'An Input that holds many values as chips: emails, keywords, labels. One hairline box with the control height as its minimum; chips wrap, and a bare text field grows into the remaining space of the last line.',
+    usage: 'Free-form lists typed by the user: invite emails, keywords, tags, domains. When the values must come from a known list use MultiSelect; for a single value use Input; for filters you toggle use Tag. Pair with Field for the label and helper ("Press Enter to add").',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'The bordered box (flex, wrap, align center, gap space.1, padding space.1.5, min-height = control height). Draws background, hairline, radius, shadow-xs and the focus ring on :focus-within. Clicking anywhere focuses the field.' },
+        { part: 'tag', element: 'span', description: 'One value chip: surface fill, hairline, radius md, 24px tall, body-sm text, followed by its remove button.' },
+        { part: 'tag-remove', element: 'button', description: '16px button with an × icon at the end of a chip. aria-label "Remove {value}".' },
+        { part: 'field', element: 'input', description: 'The bare text input (flex 1, min-width 80px): no border, no outline. Enter or comma commits the text as a chip.' },
+    ],
+    props: {
+        size: SIZE_PROP(['sm', 'md', 'lg']),
+    },
+    states: {
+        hover: { selector: ':hover:not([data-disabled])', description: 'Border strengthens.', markup: 'native :hover' },
+        focus: { selector: ':focus-within', description: 'Border becomes the action color and the ring appears around the whole box.', markup: 'native :focus-within on the box' },
+        invalid: { selector: '[data-invalid], &:has([aria-invalid="true"])', description: 'A value failed validation (bad email, duplicate, too many): danger border, danger ring on focus. Pair with a Field error.', markup: 'aria-invalid="true" on the input, or data-invalid on the box' },
+        disabled: { selector: '[data-disabled], &:has(input:disabled)', description: 'Grey fill, chips and text in the disabled color, remove buttons inert.', markup: 'disabled on the input (and on the remove buttons)' },
+        removeHover: { selector: ' .cn-tags-input__tag-remove:hover', description: 'On the __tag-remove button: subtle fill and default ink. Styled in extraCss because it lives on a child.', markup: 'native :hover on the remove button' },
+        removeFocus: { selector: ' .cn-tags-input__tag-remove:focus-visible', description: 'On the __tag-remove button: its own focus ring. Styled in extraCss.', markup: 'native :focus-visible on the remove button' },
+    },
+    base: {
+        root: {
+            display: 'flex',
+            'flex-wrap': 'wrap',
+            'align-items': 'center',
+            gap: '{space.1}',
+            width: '100%',
+            'min-width': '0',
+            'min-height': CONTROL.md.height,
+            padding: '{space.1.5}',
+            'background-color': '{color.bg-surface}',
+            border: '{border.width.thin} solid {color.border-control}',
+            'border-radius': '{radius.control}',
+            color: '{color.fg-default}',
+            'box-shadow': '{shadow.xs}',
+            cursor: 'text',
+            ...TRANSITION_COLORS,
+        },
+        tag: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            gap: '{space.1}',
+            height: '{space.6}',
+            'max-width': '100%',
+            'padding-inline': '{space.2}',
+            'background-color': '{color.bg-surface}',
+            border: '{border.width.thin} solid {color.border-default}',
+            'border-radius': '{radius.md}',
+            ...typeStyle('body-sm'),
+            'line-height': '{font.lineHeight.none}',
+            color: '{color.fg-default}',
+            'white-space': 'nowrap',
+            cursor: 'default',
+        },
+        'tag-remove': {
+            ...RESET_BUTTON,
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            width: '{space.4}',
+            height: '{space.4}',
+            'margin-inline-end': 'calc({space.1} * -1)',
+            'border-radius': '{radius.sm}',
+            'font-size': '{size.icon.xs}',
+            color: '{color.fg-subtle}',
+            ...TRANSITION_COLORS,
+        },
+        field: {
+            flex: '1 1 {space.20}',
+            'min-width': '{space.20}',
+            height: '{space.6}',
+            margin: '0',
+            padding: '0 {space.1}',
+            border: '0',
+            outline: 'none',
+            background: 'transparent',
+            ...typeStyle('body-md'),
+            'line-height': '{font.lineHeight.none}',
+            color: 'inherit',
+        },
+        '@states': {
+            hover: { root: { 'border-color': '{color.border-control-hover}' } },
+            focus: { root: { ...FOCUS_RING, 'border-color': '{color.border-action}' } },
+            invalid: { root: { 'border-color': '{color.border-danger}' } },
+            disabled: {
+                root: { 'background-color': '{color.bg-disabled}', color: '{color.fg-disabled}', 'border-color': '{color.border-disabled}', 'box-shadow': 'none', cursor: 'not-allowed' },
+                tag: { color: '{color.fg-disabled}', 'background-color': 'transparent', 'border-color': '{color.border-disabled}' },
+                'tag-remove': { color: '{color.fg-disabled}', cursor: 'not-allowed', 'pointer-events': 'none' },
+                field: { cursor: 'not-allowed' },
+            },
+        },
+    },
+    variants: {
+        size: {
+            sm: sizeBlock('sm', { pad: '{space.1}', chip: '{space.5}', chipFont: '{font.size.xs}', gap: '{space.1}' }),
+            md: sizeBlock('md', { pad: '{space.1.5}', chip: '{space.6}', chipFont: '{font.size.sm}', gap: '{space.1}' }),
+            lg: sizeBlock('lg', { pad: '{space.2}', chip: '{space.7}', chipFont: '{font.size.md}', gap: '{space.1.5}' }),
+        },
+    },
+    extraCss: `
+.cn-tags-input .cn-tags-input__field::placeholder { color: {color.fg-placeholder}; opacity: 1; }
+.cn-tags-input:has([aria-invalid="true"]):focus-within, .cn-tags-input[data-invalid]:focus-within { box-shadow: {shadow.focus-danger}; border-color: {color.border-danger}; }
+.cn-tags-input .cn-tags-input__tag-remove .cn-icon { stroke-width: 2; }
+.cn-tags-input .cn-tags-input__tag-remove:hover { background-color: {color.bg-subtle}; color: {color.fg-default}; }
+.cn-tags-input .cn-tags-input__tag-remove:focus-visible { outline: none; box-shadow: {shadow.focus}; color: {color.fg-default}; }
+.cn-tags-input .cn-tags-input__tag[data-invalid] { border-color: {color.border-danger}; color: {color.fg-danger}; }`,
+    examples: [
+        ex('Invite by email', box({ tags: ['maya.chen@lumen.co', 'daniel.costa@lumen.co', 'sofia.almeida@lumen.co'], input: 'placeholder="Add teammate…" aria-label="Invite by email" inputmode="email"' }), 'Chips wrap inside the box; the field grows into the rest of the last line.'),
+        ex('Keywords', box({ tags: ['Frozen seafood', 'Importer', 'Japan'], input: 'placeholder="Add a keyword and press Enter" aria-label="Keywords"' })),
+        ex('Empty', box({ tags: [], input: 'placeholder="Add domains, comma separated" aria-label="Allowed domains"' }), 'With no chips it looks exactly like an Input of the same size.'),
+        ex('Sizes', `<div style="display:flex;flex-direction:column;gap:var(--cn-space-3);max-width:420px">${box({ size: 'sm', tags: ['Osaka', 'Tokyo'], input: 'placeholder="Add a city…" aria-label="Cities (small)"' })}${box({ size: 'md', tags: ['Osaka', 'Tokyo'], input: 'placeholder="Add a city…" aria-label="Cities (medium)"' })}${box({ size: 'lg', tags: ['Osaka', 'Tokyo'], input: 'placeholder="Add a city…" aria-label="Cities (large)"' })}</div>`, 'Chips are 20 / 24 / 28px tall and the box keeps the control height as its minimum.'),
+        ex('Invalid', box({ tags: ['aisha.khan@lumen.co'], input: 'value="noah.berg@lumen" aria-invalid="true" aria-label="Invite by email"', root: ' data-invalid' }) + `<p class="cn-text-body-sm" style="color:var(--cn-color-fg-danger);margin:var(--cn-space-1-5) 0 0">"noah.berg@lumen" is not a valid email address.</p>`, 'The box takes the danger border; the message names the bad value.'),
+        ex('Disabled', box({ tags: ['lumen.co', 'lumen.dev'], input: 'disabled aria-label="Allowed domains"', removeAttrs: ' disabled' })),
+    ],
+    rules: [
+        'Enter, comma and blur commit the typed text as a chip; Backspace on an empty field removes the last chip; pasting "a, b, c" creates three chips.',
+        'Validate at commit time, not per keystroke: a bad value stays as text in the field with the invalid state and a message that quotes it.',
+        'Chips show the value as typed (an email, a keyword), 1–4 words, never truncated; long values wrap to a new line instead.',
+        'Clicking anywhere in the box focuses the field; the box, not the field, shows the focus ring.',
+        'Set a maximum where one exists (seats, recipients) and say it in the helper text ("Up to 20 emails"); disable the field, not the remove buttons, when it is reached.',
+        'Sizes: md in forms; sm in filter bars and dense panels; lg on onboarding screens.',
+        'Never mix a TagsInput with a dropdown of suggestions in the same box; that is a MultiSelect.',
+        'Width comes from the layout; never set a fixed width, and let the box grow in height as chips wrap.',
+    ],
+    a11y: [
+        'The field has an accessible name (label for / aria-label); announce additions and removals in a visually hidden live region ("Added maya.chen@lumen.co, 4 recipients").',
+        'Each remove button is a real <button> with aria-label "Remove {value}"; after removing, focus returns to the field.',
+        'Chips themselves are not focusable; the keyboard interacts through the field (Backspace) and the remove buttons (Tab).',
+        'When invalid, aria-invalid="true" on the field and aria-describedby pointing at the message id.',
+    ],
+    related: ['input', 'tag', 'multi-select', 'field', 'input-group'],
+};