canon-ds 0.1.0

package/lib/components/kanban.mjs

@@ -0,0 +1,179 @@
+import { TRANSITION_ALL, ex, typeStyle } from "./_shared.mjs";
+// a board in the reference's card language: transparent columns with a 14px semibold title, a
+// 22px count badge and an owner badge; cards as small white cards (radius 12, gray-200 ring,
+// shadow-xs, 16px padding) with a 14px medium title, a muted meta line and a status + avatar
+// footer; gray-50 drop zones.
+const HAIRLINE = '{border.width.thin} solid {color.border-default}';
+const ring = (color) => `inset 0 0 0 1px ${color}`;
+const badge = (text, tone, dot = false) => `<span class="cn-badge" data-tone="${tone}" data-variant="soft" data-size="sm">${dot ? '<span class="cn-badge__dot"></span>' : ''}${text}</span>`;
+const avatar = (t, name) => `<span class="cn-avatar" data-size="xs" data-shape="circle" data-tone="neutral" data-status="none" role="img" aria-label="${name}"><span class="cn-avatar__fallback" aria-hidden="true">${t}</span></span>`;
+const card = (title, meta, status, owner, extra = '') => `<article class="cn-kanban__card" tabindex="0"${extra}><h4 class="cn-kanban__card-title">${title}</h4><div class="cn-kanban__card-meta">${meta}</div><div class="cn-kanban__card-footer">${status}${avatar(owner[0], owner[1])}</div></article>`;
+const column = (owner, title, ownerLabel, cards, bodyExtra = '') => `<section class="cn-kanban__column" data-owner="${owner}" aria-label="${title}, ${cards.length} tasks"><header class="cn-kanban__column-header"><h3 class="cn-kanban__column-title">${title}</h3><span class="cn-kanban__column-count">${cards.length}</span><span class="cn-kanban__column-owner">${ownerLabel}</span></header><div class="cn-kanban__column-body"${bodyExtra}>${cards.join('')}</div></section>`;
+const MAYA = ['MC', 'Maya Chen'];
+const DANIEL = ['DC', 'Daniel Costa'];
+const SOFIA = ['SA', 'Sofia Almeida'];
+const LUCAS = ['LF', 'Lucas Ferreira'];
+const BOARD = (density, dragging = false) => `<div class="cn-kanban" data-density="${density}" role="list" aria-label="Q3 launch board">${column('agent', 'In progress', 'Engineering', [
+    card('Migrate billing to usage-based plans', 'LUM-241 · Due Sep 19', badge('In progress', 'accent', true), DANIEL),
+    card('Design the new onboarding checklist', 'LUM-233 · Due Sep 15', badge('In review', 'accent', true), SOFIA, dragging ? ' data-state="dragging"' : ''),
+    card('Rate-limit the public API', 'LUM-228 · Due Sep 22', badge('In progress', 'accent', true), LUCAS),
+])}${column('you', 'Waiting on you', 'Product', [
+    card('Approve pricing page copy', 'LUM-250 · Due today', badge('Needs approval', 'warning'), MAYA),
+    card('Review Q3 roadmap', 'LUM-247 · Due Sep 12', badge('Review', 'neutral'), MAYA),
+], dragging ? ' data-over' : '')}${column('action', 'Blocked', 'Needs action', [
+    card('SSO login fails for Okta tenants', 'LUM-252 · Reported 2h ago', badge('Blocked', 'danger'), DANIEL),
+    card('Invoice emails delayed', 'LUM-249 · Reported yesterday', badge('Overdue', 'warning'), LUCAS),
+])}</div>`;
+export const kanban = {
+    name: 'Kanban',
+    slug: 'kanban',
+    category: 'data-display',
+    description: 'A board of columns with draggable cards. Columns are transparent with a header that names the stage, its count badge and who owns it; cards are small white cards (radius 12, gray-200 ring, shadow-xs) with a 14px medium title, a muted meta line and a footer of status Badge + Avatar.',
+    usage: 'Work that moves through stages and is owned by someone at each stage: tasks, deals, tickets. When the stage does not matter, use a List; when people compare many fields, use a Table.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'Horizontal row of columns, 24px apart, scrolls sideways, columns aligned to the top.' },
+        { part: 'column', element: 'section', description: 'One stage: 320px wide (288 compact), transparent. data-owner="agent|you|action" colors the owner badge.' },
+        { part: 'column-header', element: 'header', description: 'Row with title, count and owner badge, 8px apart, 36px tall.' },
+        { part: 'column-title', element: 'h3', description: 'Stage name, 14px semibold in ink.' },
+        { part: 'column-count', element: 'span', description: 'Number of cards in a 22px gray badge (12px medium, gray-50, gray-200 ring).' },
+        { part: 'column-owner', element: 'span', description: 'Owner badge pushed to the right (12px medium, radius 6): "Engineering", "Product", "Needs action". Color follows data-owner on the column.' },
+        { part: 'column-body', element: 'div', description: 'Drop zone holding the cards 12px apart, min height 128px, radius 12. data-over shows a dashed gray-300 outline on gray-50 while a card hovers over it.' },
+        { part: 'card', element: 'article', description: 'One item: white, gray-200 ring, shadow-xs, radius 12, 16px padding, grab cursor, focusable. data-state="dragging" lifts it.' },
+        { part: 'card-title', element: 'h4', description: 'The thing\'s name, 14px medium in ink, up to two lines.' },
+        { part: 'card-meta', element: 'div', description: 'One line of context, 14px fg-muted ("LUM-241 · Due Sep 19").' },
+        { part: 'card-footer', element: 'div', description: 'Status (Badge sm) on the left, owner (Avatar xs) on the right, 8px above.' },
+    ],
+    props: {
+        density: {
+            values: ['compact', 'default'],
+            default: 'default',
+            description: 'default = 320px columns, 16px card padding, 12px between cards (boards with up to ~8 cards per column); compact = 288px columns, 12px card padding, 8px between cards, for boards with many cards.',
+        },
+    },
+    states: {
+        cardHover: { selector: ' > * > * > article:hover', description: 'On a card, not the root: the ring darkens to gray-300.', markup: 'native :hover on the card' },
+        cardFocus: { selector: ' > * > * > article:focus-visible', description: 'On a card: the 4px brand focus ring (cards are focusable for keyboard moves).', markup: 'tabindex="0" on the card; native :focus-visible' },
+        cardDragging: { selector: ' > * > * > [data-state="dragging"]', description: 'On a card while it is being dragged: shadow-lg, 1° tilt, grabbing cursor.', markup: 'data-state="dragging" on the card' },
+        columnOver: { selector: ' > * > [data-over]', description: 'On a column body while a card is dragged over it: dashed gray-300 border on a gray-50 fill.', markup: 'data-over on the column body' },
+    },
+    base: {
+        root: {
+            display: 'flex',
+            'align-items': 'flex-start',
+            gap: '{space.6}',
+            width: '100%',
+            'min-width': '0',
+            'overflow-x': 'auto',
+            'padding-bottom': '{space.2}',
+            color: '{color.fg-default}',
+        },
+        column: {
+            display: 'flex',
+            'flex-direction': 'column',
+            gap: '{space.3}',
+            flex: '0 0 calc({space.64} + {space.16})',
+            'min-width': '0',
+            'background-color': 'transparent',
+        },
+        'column-header': {
+            display: 'flex',
+            'align-items': 'center',
+            gap: '{space.2}',
+            padding: '0 {space.1}',
+            'min-height': '{space.9}',
+        },
+        'column-title': { ...typeStyle('label-md'), color: '{color.fg-default}', margin: '0' },
+        'column-count': {
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            height: '22px',
+            'min-width': '22px',
+            'padding-inline': '{space.2}',
+            'border-radius': '{radius.full}',
+            'background-color': '{color.bg-subtle}',
+            'box-shadow': ring('{color.border-default}'),
+            ...typeStyle('label-xs'),
+            color: '{color.fg-muted}',
+            'font-variant-numeric': 'tabular-nums',
+        },
+        'column-owner': {
+            ...typeStyle('label-xs'),
+            'margin-inline-start': 'auto',
+            height: '22px',
+            display: 'inline-flex',
+            'align-items': 'center',
+            padding: '0 {space.2}',
+            'border-radius': '{radius.md}',
+            'background-color': '{color.bg-subtle}',
+            'box-shadow': ring('{color.border-default}'),
+            color: '{color.fg-muted}',
+            'white-space': 'nowrap',
+        },
+        'column-body': {
+            display: 'flex',
+            'flex-direction': 'column',
+            gap: '{space.3}',
+            'min-height': '{space.32}',
+            'border-radius': '{radius.card}',
+            border: '{border.width.thin} dashed transparent',
+            ...TRANSITION_ALL,
+        },
+        card: {
+            display: 'flex',
+            'flex-direction': 'column',
+            gap: '{space.1}',
+            padding: '{space.4}',
+            'background-color': '{color.bg-surface}',
+            'box-shadow': `${ring('{color.border-default}')}, {shadow.xs}`,
+            'border-radius': '{radius.card}',
+            cursor: 'grab',
+            'min-width': '0',
+            ...TRANSITION_ALL,
+        },
+        'card-title': { ...typeStyle('label-sm'), color: '{color.fg-default}', margin: '0', 'overflow-wrap': 'anywhere' },
+        'card-meta': { display: 'flex', 'align-items': 'center', 'flex-wrap': 'wrap', gap: '{space.2}', ...typeStyle('body-md'), color: '{color.fg-muted}' },
+        'card-footer': { display: 'flex', 'align-items': 'center', 'justify-content': 'space-between', gap: '{space.2}', 'margin-top': '{space.2}' },
+    },
+    variants: {
+        density: {
+            compact: {
+                column: { flex: '0 0 calc({space.64} + {space.8})', gap: '{space.2}' },
+                'column-body': { gap: '{space.2}' },
+                card: { padding: '{space.3}', gap: '{space.0.5}' },
+                'card-footer': { 'margin-top': '{space.1.5}' },
+            },
+            default: { card: { padding: '{space.4}' } },
+        },
+    },
+    extraCss: `
+.cn-kanban__column[data-owner="agent"] .cn-kanban__column-owner { background-color: {brand.50}; box-shadow: ${ring('{brand.200}')}; color: {brand.700}; }
+.cn-kanban__column[data-owner="you"] .cn-kanban__column-owner { background-color: {color.bg-subtle}; box-shadow: ${ring('{color.border-default}')}; color: {color.fg-default}; }
+.cn-kanban__column[data-owner="action"] .cn-kanban__column-owner { background-color: {amber.50}; box-shadow: ${ring('{amber.200}')}; color: {amber.700}; }
+.cn-kanban__column-body[data-over] { border-color: {color.border-control}; background-color: {color.bg-subtle}; }
+.cn-kanban__card:hover { box-shadow: ${ring('{color.border-control}')}, {shadow.xs}; }
+.cn-kanban__card:focus-visible { outline: none; box-shadow: ${ring('{color.border-control}')}, {shadow.focus}; }
+.cn-kanban__card[data-state="dragging"] { box-shadow: ${ring('{color.border-control}')}, {shadow.lg}; transform: rotate(1deg); opacity: 0.9; cursor: grabbing; }
+.cn-kanban__card:active { cursor: grabbing; }`,
+    examples: [
+        ex('Board: in progress, waiting on you, blocked', BOARD('default'), 'Each column names its owner in a badge and shows its count. Cards carry a status Badge and the person responsible.'),
+        ex('Compact, mid-drag', BOARD('compact', true), 'The second card is being dragged; the "Waiting on you" column shows the drop zone.'),
+    ],
+    rules: [
+        'Every column names an owner with data-owner: agent (a team is working on it), you (waiting for the user) or action (something went wrong or is overdue). The owner badge is the reader\'s first question answered.',
+        'Column titles are stages or owners, 1–3 words; the count badge is always shown, even when zero.',
+        'Cards show exactly: title (14px medium), one meta line, one status Badge sm and one Avatar xs. No descriptions, no buttons, no menus on the card; open the record for details.',
+        'Card height comes from content only; do not force equal heights or add images.',
+        'Columns are 320px (288px compact) and never stretch; the board scrolls sideways. Keep it to 3–6 columns.',
+        'Drop feedback is the dashed column body (data-over) and the lifted card (data-state="dragging"); do not add insertion lines or ghost cards.',
+        'Empty columns keep their min-height so there is somewhere to drop; show "Nothing here" in fg-subtle 14px when a column is empty for a while.',
+        'Status tone follows the owner: brand (with dot) while a team works, warning when the user must act, danger for failures, neutral otherwise.',
+    ],
+    a11y: [
+        'The board is role="list" of columns; each column is a <section> with an aria-label that includes its title and count; each card is an <article> with a heading.',
+        'Cards are focusable (tabindex="0"). Provide a keyboard way to move a card (a "Move to…" action in the record or a menu on Enter); drag and drop is never the only way.',
+        'Announce moves with a polite live region ("Approve pricing page copy moved to In progress").',
+        'Owner and status are text (the owner badge, the status badge), never only a color; the dot is reinforcement.',
+    ],
+    related: ['badge', 'avatar', 'card', 'list', 'counter'],
+};

package/lib/components/kbd.mjs

@@ -0,0 +1,70 @@
+import { ex, typeStyle } from "./_shared.mjs";
+// the reference shortcut chip: 12px medium sans text in gray-600 on white, a 1px gray-300 inset
+// ring, radius 4, padding 1px 4px, at least 20×20. Flat — no keycap edge, no mono.
+const ring = (color) => `inset 0 0 0 1px ${color}`;
+const k = (key, size = 'md') => `<kbd class="cn-kbd" data-size="${size}">${key}</kbd>`;
+export const kbd = {
+    name: 'Kbd',
+    slug: 'kbd',
+    category: 'typography',
+    description: 'A keyboard key drawn as the reference shortcut chip: 12px medium text on white with a 1px gray-300 ring, radius 4, 20px tall. Several in a row spell a shortcut (⌘ K).',
+    usage: 'Show keyboard shortcuts in menus, tooltips, the command palette, input trailers and onboarding hints. Not for code (Code) and never as a button: a Kbd is not clickable.',
+    anatomy: [
+        { part: 'root', element: 'kbd', description: 'One key: a symbol (⌘ ⇧ ⌥) or a short word (Esc, Enter, K). One Kbd per key; put them side by side for a chord.' },
+    ],
+    props: {
+        size: { values: ['sm', 'md'], default: 'md', description: 'md = 20px tall with 12px text, for menus, inputs, docs and the command palette (the reference chip); sm = 18px tall with 11px text inside tooltips and table cells.' },
+    },
+    states: {},
+    base: {
+        root: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'box-sizing': 'border-box',
+            'min-width': '{space.5}',
+            height: '{space.5}',
+            padding: '{space.px} {space.1}',
+            ...typeStyle('label-xs'),
+            color: '{color.fg-muted}',
+            'background-color': '{color.bg-surface}',
+            'box-shadow': ring('{color.border-control}'),
+            'border-radius': '{radius.sm}',
+            'vertical-align': 'middle',
+            'white-space': 'nowrap',
+            'user-select': 'none',
+        },
+    },
+    variants: {
+        size: {
+            sm: { root: { height: '18px', 'min-width': '18px', padding: '{space.px} 3px', 'font-size': '{font.size.2xs}' } },
+            md: { root: {} },
+        },
+    },
+    extraCss: `
+.cn-kbd + .cn-kbd { margin-inline-start: {space.1}; }`,
+    examples: [
+        ex('Single key', k('⌘'), '20×20 minimum, 12px medium gray-600, 1px gray-300 ring, radius 4.'),
+        ex('Chord', `${k('⌘')}${k('K')}`, 'Modifiers first, then the key, 4px between them.'),
+        ex('Named keys', `<span style="display:inline-flex;gap:var(--cn-space-4);align-items:center">${k('Esc')}<span>${k('⇧')}${k('⌘')}${k('P')}</span>${k('Enter')}${k('Tab')}</span>`, 'Words stretch the chip; the padding stays 1px 4px.'),
+        ex('In a sentence', `<p class="cn-text-body-md" style="max-width:560px">Press ${k('⌘')}${k('K')} to open the command palette, ${k('/')} to search projects, or ${k('Esc')} to close any panel.</p>`),
+        ex('Small in a hint', `<span class="cn-text-body-sm" style="color:var(--cn-color-fg-muted)">Save ${k('⌘', 'sm')}${k('S', 'sm')}</span>`, '18px tall with 11px text for tooltips and table cells.'),
+    ],
+    recipes: [
+        ex('Menu item with shortcut', `<div style="width:240px;display:flex;flex-direction:column;gap:var(--cn-space-0-5)">${[['Duplicate', '⌘', 'D'], ['Archive', '⌘', 'E'], ['Delete', '⌘', '⌫']].map(([label, m, key], i) => `<div class="cn-text-body-md" style="display:flex;align-items:center;justify-content:space-between;gap:var(--cn-space-6);height:36px;padding:0 var(--cn-space-2-5);border-radius:var(--cn-radius-md);${i === 0 ? 'background:var(--cn-color-bg-subtle)' : ''}"><span>${label}</span><span>${k(m, 'sm')}${k(key, 'sm')}</span></div>`).join('')}</div>`, 'Shortcut right-aligned, size sm; the label stays the primary text.'),
+    ],
+    rules: [
+        'One key per Kbd. A shortcut is a row of Kbds 4px apart, in the order pressed: modifiers first (⌃ ⌥ ⇧ ⌘), then the key.',
+        'Use platform symbols on macOS (⌘ ⌥ ⇧ ⌃ ⏎ ⌫ ⎋) and words on Windows/Linux (Ctrl, Alt, Shift, Enter). Detect the platform; never show both.',
+        'Letters are uppercase (K, not k); named keys are capitalized words (Esc, Tab, Space, Enter), never abbreviations like "Ret".',
+        'Kbd sits at the end of a menu item, tooltip, palette row or input, right-aligned. It never appears inside a button label.',
+        'Never use Kbd for pointer input (clicks, gestures) or for code; that is Code.',
+        'md by default; sm where the surrounding text is 12px (tooltips, table cells, dense menu rows).',
+    ],
+    a11y: [
+        'Use the <kbd> element; screen readers read its text, so add aria-label on symbol keys ("Command", "Shift", "Escape").',
+        'A shortcut hint is supplementary: the same action must be reachable by pointer and through the menu.',
+        'Keep gray-600 on white; at 11–12px medium it meets AA. Do not lighten Kbd text to gray-500.',
+    ],
+    related: ['code', 'tooltip', 'menu', 'command-palette', 'input'],
+};

package/lib/components/kicker.mjs

@@ -0,0 +1,79 @@
+import { ex, typeStyle } from "./_shared.mjs";
+const MARK = {
+    neutral: '{color.fg-subtle}',
+    accent: '{color.bg-accent}',
+    success: '{color.bg-success}',
+    warning: '{color.bg-warning}',
+    danger: '{color.bg-danger}',
+};
+export const kicker = {
+    name: 'Kicker',
+    slug: 'kicker',
+    category: 'typography',
+    description: 'The signature eyebrow: mono, uppercase, letter-spaced, muted, with an optional 6×6 brand square before the text. It sits above a title and names the type of thing the title is.',
+    usage: 'Above a page title, a card title or a section title ("Prospect", "Step 2 of 4", "Agent report"). Not for status (Badge), not for counts (Counter), not for form labels (Field). Never clickable: if it filters it is a Tag, if it acts it is a Button.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'Inline-flex row carrying the kicker type style and the muted color. <div> above block titles, <span> when inline.' },
+        { part: 'mark', element: 'span', description: 'Optional 6×6px square before the text, radius 1.5px, filled with the tone color (brand accent by default). Empty, decorative.', optional: true },
+    ],
+    props: {
+        mark: { values: ['none', 'square', 'dot'], default: 'none', description: 'none = plain text (section subheading); square = 6px brand square before the text (Vero family signature); dot = round marker.' },
+        tone: {
+            values: ['neutral', 'accent', 'success', 'warning', 'danger'],
+            default: 'accent',
+            description: 'Color of the mark only; the text always stays fg-subtle. accent = the brand square (default: page and card titles); neutral = grey square for secondary sections; success/warning/danger = the section is about a state ("Verified", "Needs review", "Blocked").',
+        },
+        size: {
+            values: ['sm', 'md'],
+            default: 'sm',
+            description: 'sm = 11px, the canonical kicker above card titles and inside tables (equals the kicker type style, so markup without data-size renders sm); md = 12px for page-level eyebrows and marketing sections.',
+        },
+    },
+    states: {},
+    base: {
+        root: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            gap: '{space.2}',
+            ...typeStyle('kicker'),
+            'text-transform': 'uppercase',
+            color: '{color.fg-subtle}',
+            'max-width': '100%',
+        },
+        mark: { width: '6px', height: '6px', 'border-radius': '1.5px', 'background-color': '{color.bg-accent}', 'flex-shrink': '0' },
+    },
+    variants: {
+        mark: { none: { mark: { display: 'none' } }, square: { mark: { display: 'inline-block' } }, dot: { mark: { display: 'inline-block', 'border-radius': '{radius.full}' } } },
+        tone: Object.fromEntries(Object.entries(MARK).map(([t, c]) => [t, { mark: { 'background-color': c } }])),
+        size: {
+            sm: { root: { 'font-size': '{font.size.2xs}' } },
+            md: { root: { 'font-size': '{font.size.xs}', gap: '{space.2.5}' }, mark: { width: '7px', height: '7px' } },
+        },
+    },
+    examples: [
+        ex('With mark', `<div class="cn-kicker" data-tone="accent" data-size="sm"><span class="cn-kicker__mark"></span>Prospect</div>`),
+        ex('Text only', `<div class="cn-kicker" data-tone="accent" data-size="sm">Step 2 of 4 · Sourcing</div>`, 'No mark for secondary eyebrows and inline uses.'),
+        ex('Tones', `<div class="cn-kicker" data-tone="accent" data-size="sm"><span class="cn-kicker__mark"></span>Prospect</div> <div class="cn-kicker" data-tone="neutral" data-size="sm"><span class="cn-kicker__mark"></span>Archive</div> <div class="cn-kicker" data-tone="success" data-size="sm"><span class="cn-kicker__mark"></span>Verified</div> <div class="cn-kicker" data-tone="warning" data-size="sm"><span class="cn-kicker__mark"></span>Needs review</div> <div class="cn-kicker" data-tone="danger" data-size="sm"><span class="cn-kicker__mark"></span>Blocked</div>`, 'Only the mark changes color. The text is always muted.'),
+        ex('Page-level (md)', `<div class="cn-kicker" data-tone="accent" data-size="md"><span class="cn-kicker__mark"></span>Agent report</div>`),
+    ],
+    recipes: [
+        ex('Above a title', `<div><div class="cn-kicker" data-tone="accent" data-size="sm"><span class="cn-kicker__mark"></span>Prospect</div><h2 class="cn-text-heading-lg" style="margin-top:var(--cn-space-2)">Nakamura Trading Co.</h2><p class="cn-text-body-sm" style="color:var(--cn-color-fg-muted);margin-top:var(--cn-space-1)">Osaka, Japan · Importer of frozen seafood</p></div>`, 'Kicker names the type, the title names the thing. space.2 between them.'),
+    ],
+    rules: [
+        'One kicker per title, directly above it, with space.2 between them. Never two kickers stacked.',
+        'The kicker names the TYPE of thing; the title names the thing: "Prospect / Nakamura Trading Co.", never "Nakamura / Prospect".',
+        '1–3 words. Write the source in sentence case ("Needs review"); the CSS uppercases it.',
+        'The text is always fg-subtle. Never color the text; tone colors only the mark.',
+        'Never a badge: no background, no border, no pill. Never clickable.',
+        'The mark goes only on the primary kicker of a surface (page title, card title). Inline and table uses go without the mark.',
+        'Do not use the kicker as a form label; Field labels are label-md in sentence case.',
+        'Column headers, chart legends and stat labels already speak in this voice through their own parts; do not nest a Kicker inside them.',
+    ],
+    a11y: [
+        'The mark is an empty decorative span; screen readers skip it. Do not put text or an icon inside it.',
+        'The kicker is plain text, not a heading: no heading role, no aria-level. It is associated with the title by reading order.',
+        'Uppercasing is CSS, so assistive tech reads the source case ("Prospect", not letter by letter).',
+        'fg-subtle at 11px medium mono meets AA on canvas and surface; do not place kickers on tinted or dark backgrounds.',
+    ],
+    related: ['badge', 'card', 'stat', 'table', 'divider'],
+};

package/lib/components/link.mjs

@@ -0,0 +1,108 @@
+import { STATE, ex, ICON, typeStyle } from "./_shared.mjs";
+// Links: the "link-color" style (brand-700 semibold, underline appears on
+// hover in brand-500, icons brand-500) and the "link-gray" style (gray-600 → gray-700,
+// underline gray-400 on hover), radius 4, 100ms linear.
+const icon = (name) => ICON[name].replace('cn-icon', 'cn-link__icon');
+export const link = {
+    name: 'Link',
+    slug: 'link',
+    category: 'typography',
+    description: 'An anchor in the brand link color, semibold, with an underline that appears on hover (the reference link-color style). Three voices: inline (inside running text), standalone ("View all →" at the end of a list, with a trailing icon) and muted (the gray link-gray style for footers, legal, meta).',
+    usage: 'Use for navigation: to a page, a section, a document, an external site. Use Button (or Button variant="link"/"link-color") for actions that do not change the URL. Inline links only live inside sentences; anything that stands on its own line is standalone. Navigation lists (topbar, sidebar) are Tabs and SidebarNav, not rows of links.',
+    anatomy: [
+        { part: 'root', element: 'a', description: 'The anchor with a real href. Text names the destination ("Billing settings"), never "here" or "click".' },
+        { part: 'icon', element: 'svg', description: 'Optional trailing 20px icon (16px on small text): arrow when it goes somewhere in the app, external when it opens a new tab. Brand-500 at rest, brand-600 on hover. Decorative (aria-hidden); the text carries the meaning.', optional: true },
+    ],
+    props: {
+        variant: {
+            values: ['inline', 'standalone', 'muted'],
+            default: 'inline',
+            description: 'inline = brand link color, semibold, inherits the surrounding size; underline appears on hover; use only inside running text (the reference link-color). standalone = the same as an inline-flex row with a trailing icon, 14px semibold; for "View all", "Open in…", "Learn more" that sit on their own line (the reference link-color button md). muted = gray text that darkens on hover with a gray underline; footers, legal links, timestamps that link (the reference link-gray).',
+        },
+    },
+    states: {
+        hover: STATE.hover(),
+        focus: STATE.focus(),
+        current: STATE.current(),
+    },
+    base: {
+        root: {
+            color: '{color.fg-link}',
+            'font-weight': '{font.weight.semibold}',
+            'text-decoration-line': 'underline',
+            'text-decoration-thickness': '1px',
+            'text-underline-offset': '3px',
+            'text-decoration-color': 'transparent',
+            cursor: 'pointer',
+            'border-radius': '{radius.sm}',
+            'box-decoration-break': 'clone',
+            '-webkit-box-decoration-break': 'clone',
+            'transition-property': 'color, text-decoration-color, box-shadow',
+            'transition-duration': '{motion.duration.fast}',
+            'transition-timing-function': '{motion.easing.linear}',
+        },
+        icon: {
+            width: '1.25em',
+            height: '1.25em',
+            'flex-shrink': '0',
+            display: 'inline-block',
+            'vertical-align': '-0.25em',
+            'margin-inline-start': '{space.1}',
+            color: '{brand.500}',
+            'transition-property': 'color',
+            'transition-duration': '{motion.duration.fast}',
+            'transition-timing-function': '{motion.easing.linear}',
+        },
+        '@states': {
+            hover: { root: { color: '{color.fg-link-hover}', 'text-decoration-color': '{brand.500}' }, icon: { color: '{brand.600}' } },
+            focus: { root: { outline: 'none', 'box-shadow': '{shadow.focus}' } },
+            current: { root: { color: '{color.fg-default}', 'text-decoration-line': 'none', cursor: 'default' } },
+        },
+    },
+    variants: {
+        variant: {
+            inline: { root: {} },
+            standalone: {
+                root: {
+                    display: 'inline-flex',
+                    'align-items': 'center',
+                    gap: '{space.1}',
+                    ...typeStyle('label-md'),
+                    'text-decoration-line': 'underline',
+                    'text-decoration-color': 'transparent',
+                },
+                icon: { width: '{size.icon.md}', height: '{size.icon.md}', 'margin-inline-start': '0', 'vertical-align': 'baseline' },
+            },
+            muted: {
+                root: { color: '{color.fg-muted}' },
+                icon: { color: '{color.fg-subtle}' },
+                '@states': {
+                    hover: { root: { color: '{color.fg-default}', 'text-decoration-color': '{color.fg-subtle}' }, icon: { color: '{color.fg-muted}' } },
+                },
+            },
+        },
+    },
+    examples: [
+        ex('Inline, in running text', `<p class="cn-text-body-md" style="max-width:52ch">Interview notes are shared with the project by default. <a href="#" class="cn-link" data-variant="inline">Read how sharing works</a> before you change it, or <a href="#" class="cn-link" data-variant="inline">keep this study private</a>.</p>`, 'Brand-700 semibold; the brand-500 underline appears on hover.'),
+        ex('Standalone with arrow', `<a href="#" class="cn-link" data-variant="standalone">View all 24 studies${icon('arrow')}</a>`, '14px semibold with a 20px brand-500 trailing icon (the reference link-color button, size md).'),
+        ex('External (new tab)', `<a href="https://docs.lumen.app" target="_blank" rel="noopener noreferrer" class="cn-link" data-variant="standalone">Open the docs<span class="cn-sr-only"> (opens in a new tab)</span>${icon('external')}</a>`, 'The external icon replaces the arrow; the sr-only text announces the new tab.'),
+        ex('Muted footer row with current page', `<div class="cn-text-body-sm" style="display:flex;gap:var(--cn-space-4)"><a href="#" class="cn-link" data-variant="muted">Terms</a><a href="#" class="cn-link" data-variant="muted">Privacy</a><a href="#" class="cn-link" data-variant="muted" aria-current="page">Status</a><a href="#" class="cn-link" data-variant="muted">Contact</a></div>`, 'the reference link-gray: gray-600, gray-700 with a gray-400 underline on hover. aria-current="page" drops the underline and darkens the text.'),
+    ],
+    rules: [
+        'Links are semibold in the brand link color; the underline is a hover affordance, so keep link text short and distinct from the sentence around it.',
+        'Inline links live only inside sentences and inherit the surrounding size; anything on its own line is standalone: "View all →", "Open the docs ↗", "Learn more →". One standalone link per card or list region, placed last.',
+        'Link text names the destination: "Billing settings", "the Q3 report". Never "here", "click here", "this page", "Learn more" without a subject.',
+        'A link changes the URL. If it opens a dialog, submits, toggles or deletes, it is a Button (variant link or link-color).',
+        'External links get target="_blank", rel="noopener noreferrer", the external icon and an sr-only "(opens in a new tab)".',
+        'Trailing icon only: arrow (in-app), external (new tab), or none. Never a leading icon and never two icons.',
+        'Do not underline navigation lists (Tabs, SidebarNav, Breadcrumb have their own styles). Muted is for footers, legal and meta text.',
+    ],
+    a11y: [
+        'Always an <a> with a real href, so it works with middle-click, Enter, and the context menu; never a span with onClick.',
+        'Focus ring is the 4px box-shadow ring on :focus-visible (cloned across line breaks); never outline: none without replacement.',
+        'aria-current="page" on the link that points to the current page (footer, pagination-like lists).',
+        'New-tab links announce it via sr-only text; the icon is aria-hidden.',
+        'Links with the same text must go to the same place within a view; disambiguate with the subject ("Edit study", "Edit interview").',
+    ],
+    related: ['button', 'breadcrumb', 'tabs', 'prose'],
+};

package/lib/components/list.mjs

@@ -0,0 +1,117 @@
+import { ex, ICON, typeStyle } from "./_shared.mjs";
+// list rows in the reference's table rhythm: 16 × 24px padding (12 × 20 compact), 14px medium ink
+// titles over 14px muted descriptions, gray-200 hairlines, gray-50 hover and current rows, and the
+// card frame (radius 12, ring, shadow-xs) when the list stands alone.
+const HAIRLINE = '{border.width.thin} solid {color.border-default}';
+const ring = (color) => `inset 0 0 0 1px ${color}`;
+const TRUNCATE = { overflow: 'hidden', 'text-overflow': 'ellipsis', 'white-space': 'nowrap' };
+const SILHOUETTE = "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 person = (name, status = 'none') => `<span class="cn-avatar" data-size="md" data-shape="circle" data-tone="neutral" data-status="${status}" aria-hidden="true"><img class="cn-avatar__image" src="${SILHOUETTE}" alt="">${status !== 'none' ? '<span class="cn-avatar__status"></span>' : ''}</span>`;
+const company = (t, name) => `<span class="cn-avatar" data-size="md" data-shape="square" data-tone="neutral" data-status="none" role="img" aria-label="${name}"><span class="cn-avatar__fallback" aria-hidden="true">${t}</span></span>`;
+const badge = (text, tone, dot = false) => `<span class="cn-badge" data-tone="${tone}" data-variant="soft" data-size="sm">${dot ? '<span class="cn-badge__dot"></span>' : ''}${text}</span>`;
+const item = (leading, title, description, trailing, extra = '') => `<li class="cn-list__item"${extra}><span class="cn-list__leading">${leading}</span><span class="cn-list__content"><span class="cn-list__title">${title}</span><span class="cn-list__description">${description}</span></span><span class="cn-list__trailing">${trailing}</span></li>`;
+const link = (title, description, trailing, extra = '') => `<a href="#" class="cn-list__item"${extra}><span class="cn-list__content"><span class="cn-list__title">${title}</span>${description ? `<span class="cn-list__description">${description}</span>` : ''}</span><span class="cn-list__trailing">${trailing}</span>${ICON.chevronRight.replace('cn-icon', 'cn-list__chevron')}</a>`;
+const TEAM = `${item(person('Maya Chen', 'online'), 'Maya Chen', 'maya@lumen.co · Product Manager', badge('Admin', 'accent'))}${item(person('Daniel Costa', 'online'), 'Daniel Costa', 'daniel@lumen.co · Engineering', badge('Editor', 'neutral'))}${item(person('Sofia Almeida', 'offline'), 'Sofia Almeida', 'sofia@lumen.co · Design', badge('Editor', 'neutral'))}${item(person('Lucas Ferreira'), 'Lucas Ferreira', 'lucas@lumen.co · Frontend', badge('Invited', 'warning', true))}`;
+export const list = {
+    name: 'List',
+    slug: 'list',
+    category: 'data-display',
+    description: 'Stacked rows with a leading slot (avatar, icon, checkbox), a 14px medium ink title with an optional muted description, and a trailing slot (badge, meta, chevron). Gray-200 hairlines between rows, gray-50 hover and current rows; the same rhythm as a table row. Rows can be links or buttons.',
+    usage: 'Collections where each item is one thing with a name and a little context: team members, conversations, settings entries, files, integrations. When people compare several columns of values, use Table. For key/value pairs use DescriptionList.',
+    anatomy: [
+        { part: 'root', element: 'ul', description: 'Column of items. <ul> with <li> items for static lists, <nav>/<div> with <a>/<button> items for interactive lists. Items are direct children.' },
+        { part: 'item', element: 'li', description: 'One row: flex, centered, 16 × 24px padding (12 × 20 compact), min height 72px with an avatar (56 compact). Also an <a> or <button> when the whole row is one action.' },
+        { part: 'leading', element: 'span', description: 'Optional slot before the content: Avatar md (sm at compact), a 20px icon or a Checkbox. Does not shrink.', optional: true },
+        { part: 'content', element: 'span', description: 'Flexible middle: title over description, both truncating.' },
+        { part: 'title', element: 'span', description: '14px medium in ink, one line, truncates with an ellipsis.' },
+        { part: 'description', element: 'span', description: '14px fg-muted under the title, one line, truncates.', optional: true },
+        { part: 'trailing', element: 'span', description: 'Optional slot after the content: Badge sm, Counter, a timestamp, a Switch or a sm ghost Button. Does not shrink.', optional: true },
+        { part: 'chevron', element: 'svg', description: '20px chevron-right in fg-subtle for items that navigate. Last child of link items.', optional: true },
+    ],
+    props: {
+        density: {
+            values: ['compact', 'default'],
+            default: 'default',
+            description: 'default = 72px min rows with 16 × 24px padding (two-line items with a 40px avatar); compact = 56px min rows with 12 × 20px padding (single-line items, settings, sm avatars).',
+        },
+        variant: {
+            values: ['plain', 'card'],
+            default: 'plain',
+            description: 'plain = no frame, for lists inside a Card (padding none) or a drawer; card = the list draws its own frame (radius 12, gray-200 ring, shadow-xs) on a surface, for standalone lists on the canvas.',
+        },
+    },
+    states: {
+        hover: { selector: ' > a:hover, & > button:hover', description: 'On an interactive item (an <a> or <button> row), not the root: gray-50 fill.', markup: 'make the item an <a href> or <button>; native :hover' },
+        focus: { selector: ' > a:focus-visible, & > button:focus-visible', description: 'On an interactive item: inset 2px brand ring so it stays inside the frame.', markup: 'native :focus-visible on the item' },
+        current: { selector: ' > [aria-current="true"], & > [data-selected]', description: 'On an item: gray-50 fill for the current or selected row (the reference highlights like hover); the title stays ink.', markup: 'aria-current="true" (navigation) or data-selected (selection) on the item' },
+        disabled: { selector: ' > [aria-disabled="true"], & > button:disabled', description: 'On an item: 50% opacity, no pointer events.', markup: 'aria-disabled="true" on the item, or disabled on a button item' },
+    },
+    base: {
+        root: { display: 'flex', 'flex-direction': 'column', 'min-width': '0', color: '{color.fg-default}' },
+        item: {
+            display: 'flex',
+            'align-items': 'center',
+            gap: '{space.3}',
+            width: '100%',
+            'min-width': '0',
+            'min-height': 'calc({space.16} + {space.2})',
+            padding: '{space.4} {space.6}',
+            color: '{color.fg-default}',
+            'text-align': 'left',
+            'transition-property': 'background-color',
+            'transition-duration': '{motion.duration.fast}',
+            'transition-timing-function': '{motion.easing.linear}',
+        },
+        leading: { display: 'flex', 'align-items': 'center', 'flex-shrink': '0', color: '{color.fg-subtle}' },
+        content: { display: 'flex', 'flex-direction': 'column', 'min-width': '0', flex: '1 1 auto' },
+        title: { ...typeStyle('label-sm'), color: '{color.fg-default}', ...TRUNCATE },
+        description: { ...typeStyle('body-md'), color: '{color.fg-muted}', ...TRUNCATE },
+        trailing: { display: 'flex', 'align-items': 'center', gap: '{space.2}', 'flex-shrink': '0', ...typeStyle('body-md'), color: '{color.fg-muted}' },
+        chevron: { width: '{size.icon.md}', height: '{size.icon.md}', 'flex-shrink': '0', color: '{color.fg-subtle}' },
+    },
+    variants: {
+        density: {
+            compact: { item: { 'min-height': '{space.14}', padding: '{space.3} {space.5}', gap: '{space.3}' } },
+            default: { item: { 'min-height': 'calc({space.16} + {space.2})', padding: '{space.4} {space.6}' } },
+        },
+        variant: {
+            plain: { root: {} },
+            card: { root: { 'background-color': '{color.bg-surface}', 'box-shadow': `${ring('{color.border-default}')}, {shadow.xs}`, 'border-radius': '{radius.card}', overflow: 'hidden' } },
+        },
+    },
+    extraCss: `
+.cn-list > .cn-list__item + .cn-list__item { border-top: ${HAIRLINE}; }
+button.cn-list__item { appearance: none; border: 0; margin: 0; background: none; font: inherit; }
+a.cn-list__item, button.cn-list__item { cursor: pointer; }
+a.cn-list__item:hover, button.cn-list__item:hover { background-color: {color.bg-subtle}; }
+a.cn-list__item:focus-visible, button.cn-list__item:focus-visible { outline: none; box-shadow: inset 0 0 0 2px {brand.500}; }
+.cn-list > .cn-list__item[aria-current="true"], .cn-list > .cn-list__item[data-selected] { background-color: {color.bg-subtle}; }
+.cn-list > .cn-list__item[aria-disabled="true"], .cn-list > button.cn-list__item:disabled { opacity: {opacity.disabled}; pointer-events: none; }
+a.cn-list__item:hover .cn-list__chevron { color: {color.fg-muted}; }
+.cn-list__leading > .cn-icon { width: {size.icon.md}; height: {size.icon.md}; }`,
+    examples: [
+        ex('Team members with avatars and roles', `<ul class="cn-list" data-density="default" data-variant="card" style="width:100%;max-width:560px">${TEAM}</ul>`, '72px rows: Avatar md leading, ink medium name over the muted email, Badge sm trailing.'),
+        ex('Link items with chevron (compact)', `<nav class="cn-list" data-density="compact" data-variant="card" aria-label="Workspace settings" style="width:100%;max-width:560px">${link('General', '', 'Lumen · Lisbon', ' aria-current="true"')}${link('Members', '', badge('6', 'neutral'))}${link('Billing', '', 'Business plan')}${link('Integrations', '', badge('2 connected', 'success', true))}</nav>`, 'Whole row is the link; the current page is gray-50. Single-line 56px rows.'),
+        ex('Inside a Card with a header', `<section class="cn-card" data-variant="default" data-padding="none" style="width:100%;max-width:560px"><header class="cn-card-header" data-variant="default" data-size="md"><div class="cn-card-header__content"><h2 class="cn-card-header__title">Integrations</h2><p class="cn-card-header__description">Connect the tools your team already uses.</p></div></header><ul class="cn-list" data-density="default" data-variant="plain">${item(company('SL', 'Slack'), 'Slack', 'Notifications in #lumen-product', badge('Connected', 'success', true))}${item(company('GH', 'GitHub'), 'GitHub', 'Link pull requests to tasks', badge('Connected', 'success', true))}${item(company('FG', 'Figma'), 'Figma', 'Embed designs in projects', `<button type="button" class="cn-button" data-variant="outline" data-size="sm"><span class="cn-button__label">Connect</span></button>`)}</ul></section>`, 'plain variant: the Card supplies the frame and the CardHeader names the list.'),
+        ex('Selected and disabled items', `<ul class="cn-list" data-density="default" data-variant="card" style="width:100%;max-width:560px">${item(person('Aisha Khan', 'online'), 'Aisha Khan', 'aisha@lumen.co · Backend', badge('Owner', 'accent'), ' data-selected')}${item(person('Noah Berg'), 'Noah Berg', 'noah@lumen.co · Product design', '<span>2h ago</span>')}${item(person('Elena Rossi'), 'Elena Rossi', 'elena@lumen.co · Deactivated', badge('Deactivated', 'neutral'), ' aria-disabled="true"')}</ul>`),
+        ex('Button items (pick one)', `<div class="cn-list" data-density="compact" data-variant="card" role="listbox" aria-label="Choose a sender" style="width:100%;max-width:420px"><button type="button" class="cn-list__item" role="option" aria-selected="true" data-selected><span class="cn-list__content"><span class="cn-list__title">hello@lumen.co</span><span class="cn-list__description">Default · verified domain</span></span><span class="cn-list__trailing">${ICON.check}</span></button><button type="button" class="cn-list__item" role="option" aria-selected="false"><span class="cn-list__content"><span class="cn-list__title">maya@lumen.co</span><span class="cn-list__description">Personal</span></span></button></div>`),
+    ],
+    rules: [
+        'Every item has a title (14px medium ink); the description is optional, 14px muted and never longer than one line. Longer text belongs in the record, not the list.',
+        'One leading slot and one trailing slot per item at most. Leading = identity (Avatar md, a 20px icon, a Checkbox); trailing = state or meta (Badge sm, Counter, timestamp, Switch, one sm Button).',
+        'If the whole row is one action, the item is an <a> (navigate) or <button> (act) and shows the chevron only when it navigates to a page. Do not put buttons inside link rows.',
+        'Rows never change height on hover; hover, current and selected are the same gray-50 fill.',
+        'Use variant="card" only when the list stands alone on the canvas; inside a Card (padding none) or a drawer use plain so the Card supplies the frame.',
+        'compact (56px, sm avatars) for single-line items and settings; default (72px, md avatars) when items have two lines. One density per list.',
+        'Order by what the user is looking for (recency, priority), not alphabetically by default.',
+        'Long lists paginate or virtualize after ~50 items; do not stack hundreds of rows.',
+    ],
+    a11y: [
+        'Static lists are <ul>/<li>; navigation lists are <nav> with <a href> items; pick-one lists use role="listbox" with role="option" and aria-selected on button items.',
+        'aria-current="true" (or "page") marks the current navigation item; data-selected alone is only visual.',
+        'Interactive rows are one focus stop each with the inset ring; the title text is the accessible name, so it must be meaningful on its own.',
+        'Avatars in rows are decorative (aria-hidden or alt="") because the title names the person; presence must be in text when it matters.',
+        'Truncated titles keep the full text in the DOM (ellipsis is CSS); add a title attribute only when the truncation hides essential information.',
+    ],
+    related: ['table', 'description-list', 'avatar', 'badge', 'card', 'card-header', 'sidebar-nav', 'empty-state'],
+};