canon-ds 0.1.0

package/lib/components/counter.mjs

@@ -0,0 +1,86 @@
+import { ex, typeStyle } from "./_shared.mjs";
+// the reference count chips: the 22px badge (12px medium, tinted fill with a ring one step darker)
+// next to tabs and nav items, and the 14px red disc (10px bold white) on notification icons.
+const ring = (color) => `inset 0 0 0 1px ${color}`;
+const PAINT = {
+    neutral: { solid: ['{color.bg-inverse}', '{color.fg-inverse}'], soft: ['{color.bg-subtle}', '{color.fg-muted}', '{color.border-default}'] },
+    accent: { solid: ['{color.bg-accent}', '{color.fg-on-accent}'], soft: ['{color.bg-accent-subtle}', '{color.fg-accent}', '{brand.200}'] },
+    danger: { solid: ['{color.bg-danger}', '{white}'], soft: ['{color.bg-danger-subtle}', '{color.fg-danger}', '{red.200}'] },
+    action: { solid: ['{color.bg-action}', '{color.fg-on-action}'], soft: ['{brand.50}', '{brand.700}', '{brand.200}'] },
+};
+const compound = Object.entries(PAINT).flatMap(([tone, p]) => [
+    { when: { tone, variant: 'solid' }, block: { root: { 'background-color': p.solid[0], color: p.solid[1], 'box-shadow': 'none' } } },
+    { when: { tone, variant: 'soft' }, block: { root: { 'background-color': p.soft[0], color: p.soft[1], 'box-shadow': ring(p.soft[2]) } } },
+]);
+const c = (n, tone = 'neutral', variant = 'soft', size = 'md') => `<span class="cn-counter" data-tone="${tone}" data-variant="${variant}" data-size="${size}">${n}</span>`;
+export const counter = {
+    name: 'Counter',
+    slug: 'counter',
+    category: 'data-display',
+    description: 'A small round pill with a number: the reference\'s 22px count badge (12px medium, tinted with a ring) after tabs and nav items, or the 14px red disc on a notification icon. Tabular figures, capped at "99+". Numbers only.',
+    usage: 'After a label that it counts: a tab, a nav item, a section title, a filter; or on the corner of an icon button for unread notifications. Not for words (Badge), not for large KPIs (Stat), never as a button.',
+    anatomy: [
+        { part: 'root', element: 'span', description: 'The pill. Contains only the number (or "99+").' },
+    ],
+    props: {
+        tone: { values: ['neutral', 'accent', 'danger', 'action'], default: 'neutral', description: 'Urgency, not decoration. neutral (gray) = totals and result counts; action (brand) = things waiting for the user, and the selected tab\'s count; danger (red) = failures, overdue items and unread notifications; accent = items produced by the assistant.' },
+        variant: { values: ['solid', 'soft'], default: 'soft', description: 'soft = tinted fill with a 1px ring one step darker (the reference badge); solid = filled, at most one per row or nav to mark the count that matters (and always for the xs notification disc).' },
+        size: { values: ['xs', 'sm', 'md'], default: 'md', description: 'md 22px tall with 12px medium text (the badge next to tabs and nav items); sm 18px inside buttons and dense rows; xs 14px with 10px bold text, the notification disc on an icon corner.' },
+    },
+    states: {},
+    base: {
+        root: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'min-width': '22px',
+            height: '22px',
+            'padding-inline': '{space.2}',
+            'border-radius': '{radius.full}',
+            ...typeStyle('label-xs'),
+            'font-variant-numeric': 'tabular-nums',
+            'flex-shrink': '0',
+            'white-space': 'nowrap',
+            'vertical-align': 'middle',
+        },
+    },
+    variants: {
+        tone: { neutral: { root: {} }, accent: { root: {} }, danger: { root: {} }, action: { root: {} } },
+        variant: { solid: { root: {} }, soft: { root: {} } },
+        size: {
+            xs: { root: { 'min-width': '{space.3.5}', height: '{space.3.5}', 'padding-inline': '3px', 'font-size': '10px', 'font-weight': '{font.weight.bold}', 'line-height': '1' } },
+            sm: { root: { 'min-width': '18px', height: '18px', 'padding-inline': '{space.1.5}', 'font-size': '{font.size.2xs}', 'line-height': '1' } },
+            md: { root: { 'min-width': '22px', height: '22px', 'padding-inline': '{space.2}' } },
+        },
+    },
+    compound,
+    extraCss: `
+.cn-counter[data-size="xs"] { box-shadow: 0 0 0 1.5px {color.bg-surface}; }
+.cn-counter[data-anchored] { position: absolute; top: -1px; right: -1px; }`,
+    examples: [
+        ex('Soft (default)', c('12'), '22px, gray-50 with a gray-200 ring, 12px medium gray-700.'),
+        ex('Tones, soft', `${c('128', 'neutral')} ${c('7', 'accent')} ${c('2', 'danger')} ${c('3', 'action')}`, 'neutral · accent · danger · action; each with the ring one step darker than its fill.'),
+        ex('Tones, solid', `${c('128', 'neutral', 'solid')} ${c('7', 'accent', 'solid')} ${c('2', 'danger', 'solid')} ${c('3', 'action', 'solid')}`, 'One solid counter per row at most.'),
+        ex('Sizes and cap', `<div style="display:flex;align-items:center;gap:var(--cn-space-3)">${c('3', 'danger', 'solid', 'xs')} ${c('45', 'neutral', 'soft', 'sm')} ${c('99+', 'neutral', 'soft', 'md')}</div>`, 'xs 14px (the notification disc) · sm 18px · md 22px. Never more than two digits; cap at 99+.'),
+    ],
+    recipes: [
+        ex('In a nav item, a tab and on an icon', `<div style="display:flex;flex-wrap:wrap;gap:var(--cn-space-3);align-items:center"><button type="button" class="cn-button" data-variant="ghost" data-size="sm"><span class="cn-button__label">Waiting for you</span>${c('3', 'action', 'soft', 'md')}</button><button type="button" class="cn-button" data-variant="ghost" data-size="sm"><span class="cn-button__label">In review</span>${c('12', 'neutral', 'soft', 'md')}</button><span style="position:relative;display:inline-flex"><button type="button" class="cn-icon-button" data-variant="ghost" data-size="sm" data-shape="square" aria-label="Notifications, 3 unread"><svg class="cn-icon-button__icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M2.5 9.5h3l1 2h3l1-2h3M2.5 9.5V4a1 1 0 011-1h9a1 1 0 011 1v5.5M2.5 9.5V12a1 1 0 001 1h9a1 1 0 001-1V9.5"/></svg></button>${c('3', 'danger', 'solid', 'xs').replace('data-size="xs"', 'data-size="xs" data-anchored')}</span></div>`, 'The counter follows the label it counts; only the "needs you" count is action-tinted. data-anchored pins the xs disc to the icon corner.'),
+    ],
+    rules: [
+        'Numbers only. A word ("New", "Beta", "Live") is a Badge.',
+        'Cap at "99+". Never show three or more digits.',
+        'Hide the counter at zero; "0" is noise. If the zero is the content ("0 results"), write it as text.',
+        'Tone is urgency: neutral for totals, action for what waits for the user, danger for failures and unread notifications, accent for assistant output. Never pick a tone for looks.',
+        'At most one solid counter per row, nav or tab bar; the rest are soft. The xs disc is always solid danger.',
+        'The counter comes after the label it counts ("Inbox 12"), separated by the parent\'s gap, never before it.',
+        'Stays round at one digit and widens with two; never squash it into a fixed width.',
+        'Do not animate count changes (no bounce, no flash). Update the number; announce with aria-live on the region if it matters.',
+    ],
+    a11y: [
+        'The number is plain text and is read as such; give it context with the adjacent label or a visually hidden suffix ("12 unread").',
+        'On an icon button, put the count in the button\'s aria-label ("Notifications, 3 unread") and keep the disc aria-hidden.',
+        'Live counts: aria-live="polite" on the containing region (the nav item or tab), not on the counter itself.',
+        'Color is reinforcement only; the label next to the counter carries the meaning.',
+    ],
+    related: ['badge', 'tag', 'stat', 'tabs', 'sidebar-nav', 'topbar'],
+};

package/lib/components/credit-card.mjs

@@ -0,0 +1,126 @@
+import { ex, typeStyle } from "./_shared.mjs";
+// Credit card: a decorative 316px card at the standard 1.586 ratio with a logo,
+// a chip, a masked number, holder name, expiry and a generic network mark. It
+// represents a saved payment method; it never shows a full card number.
+const CHIP = '<svg class="cn-credit-card__chip" viewBox="0 0 32 24" fill="none" stroke="currentColor" stroke-width="1.25" stroke-linejoin="round" aria-hidden="true"><rect x="1" y="1" width="30" height="22" rx="4" style="fill:currentColor;fill-opacity:.18"/><path d="M1 9h9a3 3 0 013 3v0a3 3 0 01-3 3H1M31 9h-9a3 3 0 00-3 3v0a3 3 0 003 3h9M13 1v8M19 1v8M13 15v8M19 15v8"/></svg>';
+const MARK = '<svg class="cn-credit-card__brand" viewBox="0 0 40 24" aria-hidden="true"><circle cx="14" cy="12" r="11" style="fill:currentColor;fill-opacity:.55"/><circle cx="26" cy="12" r="11" style="fill:currentColor;fill-opacity:.35"/></svg>';
+const LOGO = '<span class="cn-credit-card__logo"><svg viewBox="0 0 20 20" fill="currentColor" aria-hidden="true"><path d="M10 1.5l2.4 6.1 6.1 2.4-6.1 2.4L10 18.5l-2.4-6.1L1.5 10l6.1-2.4z"/></svg>Lumen</span>';
+const card = (variant, size, o) => `<div class="cn-credit-card" data-variant="${variant}" data-size="${size}" role="img" aria-label="Lumen card ending in ${o.last4}, ${o.name}, expires ${o.expiry}"><div class="cn-credit-card__header">${LOGO}${CHIP}</div><div class="cn-credit-card__number">•••• •••• •••• ${o.last4}</div><div class="cn-credit-card__footer"><div class="cn-credit-card__holder"><span><span class="cn-credit-card__caption">Card holder</span><span class="cn-credit-card__name">${o.name}</span></span><span><span class="cn-credit-card__caption">Expires</span><span class="cn-credit-card__expiry">${o.expiry}</span></span></div>${MARK}</div></div>`;
+const row = (...items) => `<div style="display:flex;flex-wrap:wrap;gap:var(--cn-space-4);align-items:flex-start">${items.join('')}</div>`;
+export const creditCard = {
+    name: 'CreditCard',
+    slug: 'credit-card',
+    category: 'media',
+    description: 'A decorative payment card at the real 1.586 ratio: logo and chip on top, a masked number in the middle, holder and expiry at the bottom next to a generic network mark. Four finishes (brand, dark, light, outline) and two sizes.',
+    usage: 'Use in billing settings, checkout summaries and the payment-method picker to show which saved card is in use. It is an illustration of a record, not a form: editing happens in a Dialog with real Inputs. Never render a full card number.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'The card: 316px wide (256 in sm), aspect-ratio 1.586, radius 2xl, 24px padding, flex column with the number centered vertically. role="img" with an aria-label that names the card.' },
+        { part: 'header', element: 'div', description: 'Top row: logo on the left, chip on the right.' },
+        { part: 'logo', element: 'span', description: 'Issuer or product wordmark, label-md semibold with a 20px mark.' },
+        { part: 'chip', element: 'svg', description: 'The 32px contact chip drawn in currentColor at reduced opacity.' },
+        { part: 'number', element: 'div', description: 'The masked number "•••• •••• •••• 4242" in numeric-md, tabular figures and wider tracking.' },
+        { part: 'footer', element: 'div', description: 'Bottom row: holder block on the left, network mark on the right.' },
+        { part: 'holder', element: 'div', description: 'Name and expiry side by side, each under a tiny caption.' },
+        { part: 'caption', element: 'span', description: 'Kicker-voice caption above name and expiry ("Card holder", "Expires").' },
+        { part: 'name', element: 'span', description: 'Cardholder name in label-sm, wide tracking, truncated.' },
+        { part: 'expiry', element: 'span', description: 'MM/YY in numeric-md.' },
+        { part: 'brand', element: 'svg', description: 'A generic 40px network mark (two overlapping circles in currentColor). Replace with the real network logo when known.' },
+    ],
+    props: {
+        variant: {
+            values: ['brand', 'dark', 'light', 'outline'],
+            default: 'brand',
+            description: 'brand = action-colored card with on-action text, the default card of the product. dark = inverse surface (ink in light theme, near-white in dark theme). light = surface with a hairline and shadow-xs, for lists of several cards. outline = transparent with a strong hairline, the "add a card" or placeholder look.',
+        },
+        size: {
+            values: ['sm', 'md'],
+            default: 'md',
+            description: 'md = 316px wide, 24px padding, 16px number (settings pages, checkout). sm = 256px, 16px padding, 13px number for pickers, drawers and mobile.',
+        },
+    },
+    states: {
+        selected: { selector: '[aria-selected="true"], &[data-selected]', description: 'The chosen card in a picker: a 2px action-colored ring outside the card.', markup: 'aria-selected="true" (inside a listbox) or data-selected on the root' },
+    },
+    base: {
+        root: {
+            position: 'relative',
+            display: 'flex',
+            'flex-direction': 'column',
+            'justify-content': 'space-between',
+            width: '316px',
+            'max-width': '100%',
+            'aspect-ratio': '1.586',
+            padding: '{space.6}',
+            'border-radius': '{radius.2xl}',
+            overflow: 'hidden',
+            isolation: 'isolate',
+            'background-color': '{color.bg-action}',
+            color: '{color.fg-on-action}',
+            'user-select': 'none',
+            'flex-shrink': '0',
+        },
+        header: { display: 'flex', 'align-items': 'flex-start', 'justify-content': 'space-between', gap: '{space.4}' },
+        logo: { display: 'inline-flex', 'align-items': 'center', gap: '{space.2}', ...typeStyle('label-md'), 'font-weight': '{font.weight.semibold}', 'letter-spacing': '{font.letterSpacing.tight}' },
+        chip: { display: 'block', width: '{size.icon.2xl}', height: 'auto', 'flex-shrink': '0' },
+        number: { ...typeStyle('numeric-md'), 'font-size': '{font.size.lg}', 'letter-spacing': '{font.letterSpacing.wider}', 'font-variant-numeric': 'tabular-nums', 'white-space': 'nowrap' },
+        footer: { display: 'flex', 'align-items': 'flex-end', 'justify-content': 'space-between', gap: '{space.4}', 'min-width': '0' },
+        holder: { display: 'flex', 'align-items': 'flex-end', gap: '{space.6}', 'min-width': '0' },
+        caption: { display: 'block', ...typeStyle('kicker'), opacity: '{opacity.muted}', 'margin-bottom': '{space.1.5}' },
+        name: { display: 'block', ...typeStyle('label-sm'), 'letter-spacing': '{font.letterSpacing.wide}', 'white-space': 'nowrap', overflow: 'hidden', 'text-overflow': 'ellipsis', 'max-width': '160px' },
+        expiry: { display: 'block', ...typeStyle('numeric-md'), 'font-variant-numeric': 'tabular-nums' },
+        brand: { display: 'block', width: '{space.10}', height: 'auto', 'flex-shrink': '0' },
+        '@states': {
+            selected: { root: { 'box-shadow': '0 0 0 {border.width.medium} {color.border-action}' } },
+        },
+    },
+    variants: {
+        variant: {
+            brand: { root: { 'background-color': '{color.bg-action}', color: '{color.fg-on-action}' } },
+            dark: { root: { 'background-color': '{color.bg-inverse}', color: '{color.fg-inverse}' } },
+            light: { root: { 'background-color': '{color.bg-surface}', color: '{color.fg-default}', border: '{border.width.thin} solid {color.border-default}', 'box-shadow': '{shadow.xs}' } },
+            outline: { root: { 'background-color': 'transparent', color: '{color.fg-default}', border: '{border.width.thin} solid {color.border-strong}' } },
+        },
+        size: {
+            md: { root: { width: '316px', padding: '{space.6}' } },
+            sm: {
+                root: { width: '256px', padding: '{space.4}', 'border-radius': '{radius.xl}' },
+                number: { 'font-size': '{font.size.sm}', 'letter-spacing': '{font.letterSpacing.wide}' },
+                chip: { width: '{size.icon.xl}' },
+                brand: { width: '{space.8}' },
+                header: { gap: '{space.3}' },
+                holder: { gap: '{space.4}' },
+                caption: { 'margin-bottom': '{space.1}' },
+            },
+        },
+    },
+    extraCss: `
+.cn-credit-card::before { content: ''; position: absolute; width: 240px; height: 240px; border-radius: {radius.full}; inset-inline-end: -88px; top: -128px; background-color: color-mix(in srgb, currentColor 8%, transparent); pointer-events: none; z-index: -1; }
+.cn-credit-card[data-variant="outline"]::before { display: none; }
+.cn-credit-card__logo > svg { width: {size.icon.lg}; height: {size.icon.lg}; flex-shrink: 0; }
+.cn-credit-card[data-size="sm"] .cn-credit-card__logo { font-size: {font.size.sm}; }
+.cn-credit-card[data-size="sm"] .cn-credit-card__logo > svg { width: {size.icon.md}; height: {size.icon.md}; }`,
+    examples: [
+        ex('Brand (default)', card('brand', 'md', { last4: '4242', name: 'Maya Chen', expiry: '09/29' }), 'The product card: action fill, on-action text, a quiet circle in the corner.'),
+        ex('Dark', card('dark', 'md', { last4: '8210', name: 'Daniel Costa', expiry: '03/28' }), 'Inverse surface; flips to near-white in the dark theme.'),
+        ex('Light', card('light', 'md', { last4: '1187', name: 'Sofia Almeida', expiry: '11/27' }), 'Surface with a hairline, for lists of several saved cards.'),
+        ex('Outline', card('outline', 'md', { last4: '0093', name: 'Aisha Khan', expiry: '06/30' }), 'Transparent placeholder look for "add a card" states and disabled methods.'),
+        ex('Small, selected in a picker', row(card('brand', 'sm', { last4: '4242', name: 'Maya Chen', expiry: '09/29' }).replace('role="img"', 'role="img" data-selected'), card('light', 'sm', { last4: '1187', name: 'Maya Chen', expiry: '11/27' })), '256px cards for pickers and mobile; data-selected adds the action-colored ring.'),
+    ],
+    rules: [
+        'Decorative: the card is a picture of a saved payment method, never a form. Editing and adding cards happen in a Dialog with Inputs.',
+        'Always mask the number as "•••• •••• •••• 4242": the last four digits only, never more, never the CVC, never an expiry that is not needed on screen.',
+        'One brand card per screen; other saved cards use light or outline so the default method stands out.',
+        'Keep the 1.586 ratio and the 316/256 widths; never stretch the card to a column. Center it or align it with the form above.',
+        'The network mark is generic until the network is known; then use the real mark at 40px, never a colored badge.',
+        'Names are shown as stored, truncated with an ellipsis after 160px; expiry is MM/YY.',
+        'No gradients, foils or photos; the only decoration is the 8% circle in the corner.',
+        'The card never opens anything on click by itself. In a picker, wrap it in a listbox option and use data-selected for the ring.',
+    ],
+    a11y: [
+        'The root has role="img" and an aria-label that says it all: "Lumen card ending in 4242, Maya Chen, expires 09/29". The inner text is then decorative.',
+        'When the card is an option in a picker, the option element carries the name and aria-selected; the card inside stays role="img".',
+        'Contrast: on-action text on the action fill and fg-inverse on bg-inverse are AA by token design; the light and outline variants use fg-default.',
+        'Do not expose the number as a table of digits; screen readers read the masked string with the last four digits.',
+    ],
+    related: ['card', 'description-list', 'dialog', 'input', 'badge'],
+};

package/lib/components/date-picker.mjs

@@ -0,0 +1,202 @@
+import { RESET_BUTTON, TRANSITION_COLORS, ex, ICON, typeStyle } from "./_shared.mjs";
+// Calendar panel: header (month + 32px ghost nav), a 7-column weekday row and a 7-column grid of
+// 40px round day buttons (36px on sm), a footer with the date input and Cancel / Apply, and an
+// optional presets column on the left. Panel width = 7 days + 2 × space.6 = 328px on md.
+const DAY = { sm: '{space.9}', md: '{space.10}' };
+const WEEKDAYS = ['Mo', 'Tu', 'We', 'Th', 'Fr', 'Sa', 'Su'];
+const day = (n, o = {}) => `<button type="button" class="cn-date-picker__day"${o.selected ? ' aria-selected="true"' : ''}${o.range ? ` data-range="${o.range}"` : ''}${o.today ? ' data-today aria-current="date"' : ''}${o.outside ? ' data-outside' : ''}${o.disabled ? ' disabled' : ''}>${n}</button>`;
+/** September 2026 starts on a Tuesday and has 30 days; weeks start on Monday. Today is Sep 11. */
+function september(sel) {
+    const cells = [day(31, { outside: true })];
+    for (let n = 1; n <= 30; n++)
+        cells.push(day(n, { ...sel(n), today: n === 11 }));
+    for (let n = 1; n <= 4; n++)
+        cells.push(day(n, { outside: true }));
+    return cells.join('');
+}
+const single = (selected) => september((n) => ({ selected: n === selected }));
+const range = (start, end) => september((n) => (n === start ? { selected: true, range: 'start' } : n === end ? { selected: true, range: 'end' } : n > start && n < end ? { range: 'middle' } : {}));
+const prev = ICON.chevronRight.replace('cn-icon', 'cn-icon" style="transform:scaleX(-1)');
+const nav = `<button type="button" class="cn-date-picker__nav" aria-label="Previous month">${prev}</button><div class="cn-date-picker__month" aria-live="polite">September 2026</div><button type="button" class="cn-date-picker__nav" aria-label="Next month">${ICON.chevronRight}</button>`;
+const weekdays = `<div class="cn-date-picker__weekdays" aria-hidden="true">${WEEKDAYS.map((d) => `<span>${d}</span>`).join('')}</div>`;
+const footer = (value, label) => `<div class="cn-date-picker__footer"><div class="cn-input" data-variant="default" data-size="sm">${ICON.calendar.replace('cn-icon', 'cn-input__icon')}<input class="cn-input__field" type="text" value="${value}" aria-label="${label}"></div><button type="button" class="cn-button" data-variant="outline" data-size="sm"><span class="cn-button__label">Cancel</span></button><button type="button" class="cn-button" data-variant="primary" data-size="sm"><span class="cn-button__label">Apply</span></button></div>`;
+const calendar = (days, value, label) => `<div class="cn-date-picker__calendar"><div class="cn-date-picker__header">${nav}</div>${weekdays}<div class="cn-date-picker__grid" role="group" aria-label="September 2026">${days}</div>${footer(value, label)}</div>`;
+const PRESETS = ['Today', 'Yesterday', 'This week', 'Last week', 'This month', 'Last month'];
+const presets = (current) => `<div class="cn-date-picker__presets">${PRESETS.map((p) => `<button type="button" class="cn-date-picker__preset"${p === current ? ' aria-current="true"' : ''}>${p}</button>`).join('')}</div>`;
+const panel = (attrs, inner) => `<div class="cn-date-picker" ${attrs} role="dialog" aria-label="Choose a date">${inner}</div>`;
+export const datePicker = {
+    name: 'DatePicker',
+    slug: 'date-picker',
+    category: 'forms',
+    description: 'A calendar panel: month header with ghost prev/next buttons, a weekday row, a 7-column grid of round day buttons, and a footer with the typed date and Cancel / Apply. Selected days fill with the action color, ranges tint the days between, today carries a dot. An optional presets column offers shortcuts.',
+    usage: 'Pick one date or a start–end range: due dates, report periods, filters by period. The panel opens from a Button (calendar icon + the formatted date) or from an Input with a leading calendar icon. For a time or a date-time use an Input with the right type; for recurring rules use a form.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'The floating panel (row): surface-raised, hairline, radius panel, shadow-lg. role="dialog" with an aria-label. Holds an optional presets column and the calendar column. Carries data-variant and data-size.' },
+        { part: 'presets', element: 'div', description: 'Left column of shortcut buttons (Today, Yesterday, This week, Last week, This month, Last month), separated from the calendar by a hairline. Only in the with-presets variant.', optional: true },
+        { part: 'preset', element: 'button', description: 'One shortcut row, 36px, body-sm, radius md; aria-current="true" on the active one.', optional: true },
+        { part: 'calendar', element: 'div', description: 'The calendar column (flex column) wrapping header, weekdays, grid and footer. Width = 7 days + 2 × space.6 (328px on md, 300px on sm).' },
+        { part: 'header', element: 'div', description: 'Row with the previous button, the month name and the next button.' },
+        { part: 'month', element: 'div', description: 'The month and year ("September 2026"), label-md, aria-live="polite".' },
+        { part: 'nav', element: 'button', description: '32px ghost icon button with a chevron; aria-label "Previous month" / "Next month".' },
+        { part: 'weekdays', element: 'div', description: '7-column row of two-letter weekday names, label-sm muted, aria-hidden.' },
+        { part: 'grid', element: 'div', description: '7-column grid of day buttons with a 4px row gap. role="group" named after the month (or a real role="grid" with rows when built with JS).' },
+        { part: 'day', element: 'button', description: 'One day: 40×40 (36 on sm), body-sm, radius full. Attributes: aria-selected="true" (chosen), data-range="start|middle|end", data-today, data-outside (previous/next month), disabled.' },
+        { part: 'footer', element: 'div', description: 'Top hairline; the typed date in a small Input with a calendar icon, then Cancel (outline) and Apply (primary), size sm.' },
+    ],
+    props: {
+        variant: {
+            values: ['single', 'range', 'with-presets'],
+            default: 'single',
+            description: 'single = one date, one Apply; range = a start and an end day with the days between tinted, the footer input shows "Sep 8 – Sep 14, 2026"; with-presets = a range picker with a left column of shortcuts (Today … Last month) for filters by period.',
+        },
+        size: { values: ['sm', 'md'], default: 'md', description: 'md = 40px days, 328px panel (default); sm = 36px days, 300px panel for popovers inside dense toolbars.' },
+    },
+    states: {
+        dayHover: { selector: ' .cn-date-picker__day:hover:not(:disabled):not([aria-selected="true"])', description: 'On the __day: subtle fill under the pointer. Styled in extraCss because it lives on a child.', markup: 'native :hover on a day' },
+        dayFocus: { selector: ' .cn-date-picker__day:focus-visible', description: 'On the __day: the focus ring (roving tabindex, arrow keys move it). Styled in extraCss.', markup: 'native :focus-visible on a day' },
+        today: { selector: ' .cn-date-picker__day[data-today]', description: 'On the __day: semibold with a 4px action-colored dot under the number. Styled in extraCss.', markup: 'data-today and aria-current="date" on the day' },
+        selected: { selector: ' .cn-date-picker__day[aria-selected="true"]', description: 'On the __day: action fill, on-action text, medium weight. The start and end of a range are also selected. Styled in extraCss.', markup: 'aria-selected="true" on the day' },
+        range: { selector: ' .cn-date-picker__day[data-range]', description: 'On the __day: days inside a range take the subtle action tint and lose their radius; data-range="start" keeps the left radius, "end" the right one. Styled in extraCss.', markup: 'data-range="start|middle|end" on the day' },
+        outside: { selector: ' .cn-date-picker__day[data-outside]', description: 'On the __day: days of the previous/next month in fg-subtle. Styled in extraCss.', markup: 'data-outside on the day' },
+        dayDisabled: { selector: ' .cn-date-picker__day:disabled', description: 'On the __day: outside the allowed period, disabled ink, no hover. Styled in extraCss.', markup: 'disabled on the day' },
+        presetCurrent: { selector: ' .cn-date-picker__preset[aria-current="true"]', description: 'On the __preset: the active shortcut, subtle fill and medium weight. Styled in extraCss.', markup: 'aria-current="true" on the preset' },
+    },
+    base: {
+        root: {
+            display: 'inline-flex',
+            'flex-direction': 'row',
+            'align-items': 'stretch',
+            'max-width': '100%',
+            'background-color': '{color.bg-surface-raised}',
+            border: '{border.width.thin} solid {color.border-default}',
+            'border-radius': '{radius.panel}',
+            'box-shadow': '{shadow.lg}',
+            color: '{color.fg-default}',
+            overflow: 'hidden',
+            'z-index': '{z.popover}',
+        },
+        presets: {
+            display: 'flex',
+            'flex-direction': 'column',
+            gap: '{space.0.5}',
+            'flex-shrink': '0',
+            'min-width': '{space.40}',
+            padding: '{space.3}',
+            'border-inline-end': '{border.width.thin} solid {color.border-default}',
+        },
+        preset: {
+            ...RESET_BUTTON,
+            display: 'flex',
+            'align-items': 'center',
+            height: '{space.9}',
+            'padding-inline': '{space.3}',
+            'border-radius': '{radius.md}',
+            ...typeStyle('body-sm'),
+            'line-height': '{font.lineHeight.none}',
+            color: '{color.fg-muted}',
+            'text-align': 'start',
+            'white-space': 'nowrap',
+            ...TRANSITION_COLORS,
+        },
+        calendar: { display: 'flex', 'flex-direction': 'column', 'min-width': '0', 'max-width': '100%', width: 'calc({space.10} * 7 + {space.6} * 2)' },
+        header: { display: 'flex', 'align-items': 'center', 'justify-content': 'space-between', gap: '{space.2}', padding: '{space.5} {space.6} 0' },
+        month: { ...typeStyle('label-md'), color: '{color.fg-default}' },
+        nav: {
+            ...RESET_BUTTON,
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            width: '{space.8}',
+            height: '{space.8}',
+            'border-radius': '{radius.md}',
+            'font-size': '{size.icon.lg}',
+            color: '{color.fg-subtle}',
+            ...TRANSITION_COLORS,
+        },
+        weekdays: { display: 'grid', 'grid-template-columns': 'repeat(7, minmax(0, 1fr))', 'margin-top': '{space.3}', 'padding-inline': '{space.6}', ...typeStyle('label-sm'), color: '{color.fg-muted}', 'text-align': 'center', 'line-height': '{space.10}' },
+        grid: { display: 'grid', 'grid-template-columns': 'repeat(7, minmax(0, 1fr))', 'row-gap': '{space.1}', padding: '0 {space.6} {space.5}' },
+        day: {
+            ...RESET_BUTTON,
+            position: 'relative',
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            width: '100%',
+            height: '{space.10}',
+            'border-radius': '{radius.full}',
+            ...typeStyle('body-sm'),
+            'line-height': '{font.lineHeight.none}',
+            color: '{color.fg-default}',
+            'font-variant-numeric': 'tabular-nums',
+            ...TRANSITION_COLORS,
+        },
+        footer: { display: 'flex', 'flex-wrap': 'wrap', 'align-items': 'center', gap: '{space.3}', padding: '{space.4} {space.6}', 'border-top': '{border.width.thin} solid {color.border-default}' },
+    },
+    variants: {
+        variant: {
+            single: { root: {} },
+            range: { root: {} },
+            'with-presets': { root: {} },
+        },
+        size: {
+            sm: {
+                calendar: { width: `calc(${DAY.sm} * 7 + {space.6} * 2)` },
+                weekdays: { 'line-height': DAY.sm },
+                day: { height: DAY.sm },
+                header: { padding: '{space.4} {space.6} 0' },
+            },
+            md: { day: { height: DAY.md } },
+        },
+    },
+    extraCss: `
+.cn-date-picker .cn-date-picker__day:hover:not(:disabled):not([aria-selected="true"]) { background-color: {color.bg-subtle}; }
+.cn-date-picker .cn-date-picker__day:focus-visible { outline: none; box-shadow: {shadow.focus}; z-index: {z.raised}; }
+.cn-date-picker .cn-date-picker__day[data-today] { font-weight: {font.weight.semibold}; }
+.cn-date-picker .cn-date-picker__day[data-today]::after { content: ''; position: absolute; bottom: 4px; left: 50%; width: 4px; height: 4px; margin-left: -2px; border-radius: {radius.full}; background-color: {color.bg-action}; }
+.cn-date-picker .cn-date-picker__day[data-range] { border-radius: 0; background-color: {color.bg-action-subtle}; font-weight: {font.weight.medium}; }
+.cn-date-picker .cn-date-picker__day[data-range="start"] { border-radius: {radius.full} 0 0 {radius.full}; }
+.cn-date-picker .cn-date-picker__day[data-range="end"] { border-radius: 0 {radius.full} {radius.full} 0; }
+.cn-date-picker .cn-date-picker__day[aria-selected="true"] { background-color: {color.bg-action}; color: {color.fg-on-action}; font-weight: {font.weight.medium}; }
+.cn-date-picker .cn-date-picker__day[aria-selected="true"]::after { background-color: {color.fg-on-action}; }
+.cn-date-picker .cn-date-picker__day[data-outside] { color: {color.fg-subtle}; }
+.cn-date-picker .cn-date-picker__day:disabled { color: {color.fg-disabled}; cursor: not-allowed; background-color: transparent; }
+.cn-date-picker .cn-date-picker__nav:hover { background-color: {color.bg-subtle}; color: {color.fg-default}; }
+.cn-date-picker .cn-date-picker__nav:focus-visible { outline: none; box-shadow: {shadow.focus}; }
+.cn-date-picker .cn-date-picker__preset:hover { background-color: {color.bg-subtle}; color: {color.fg-default}; }
+.cn-date-picker .cn-date-picker__preset[aria-current="true"] { background-color: {color.bg-subtle}; color: {color.fg-default}; font-weight: {font.weight.medium}; }
+.cn-date-picker .cn-date-picker__preset:focus-visible { outline: none; box-shadow: {shadow.focus}; }
+.cn-date-picker .cn-date-picker__footer > .cn-input { flex: 1 1 100%; min-width: 0; }
+.cn-date-picker .cn-date-picker__footer > .cn-button { flex: 1 1 0; }
+@media (max-width: {breakpoint.sm}) {
+  .cn-date-picker { flex-direction: column; }
+  .cn-date-picker .cn-date-picker__presets { flex-direction: row; flex-wrap: wrap; min-width: 0; max-width: calc({space.10} * 7 + {space.6} * 2); border-inline-end: 0; border-bottom: {border.width.thin} solid {color.border-default}; }
+  .cn-date-picker .cn-date-picker__header, .cn-date-picker .cn-date-picker__weekdays, .cn-date-picker .cn-date-picker__grid, .cn-date-picker .cn-date-picker__footer { padding-inline: {space.4}; }
+}`,
+    examples: [
+        ex('Single date', panel('data-variant="single" data-size="md"', calendar(single(18), 'Sep 18, 2026', 'Selected date')), 'September 2026: the 18th is selected, today (the 11th) carries the dot, Aug 31 and Oct 1–4 are outside days.'),
+        ex('Range 8–14', panel('data-variant="range" data-size="md"', calendar(range(8, 14), 'Sep 8 – Sep 14, 2026', 'Selected range')), 'Start and end are filled; the days between take the subtle tint with no radius. Today falls inside the range and keeps its dot.'),
+        ex('With presets', panel('data-variant="with-presets" data-size="md"', presets('Last week') + calendar(range(8, 14), 'Sep 8 – Sep 14, 2026', 'Selected range')), 'A shortcut column on the left; "Last week" is the active preset and drives the range.'),
+        ex('Small', panel('data-variant="single" data-size="sm"', calendar(single(11), 'Sep 11, 2026', 'Selected date')), '36px days, 300px panel, for popovers inside dense toolbars.'),
+        ex('Date input (trigger)', `<div style="display:flex;flex-wrap:wrap;gap:var(--cn-space-3);align-items:center"><div class="cn-input" data-variant="default" data-size="md" style="max-width:220px">${ICON.calendar.replace('cn-icon', 'cn-input__icon')}<input class="cn-input__field" type="text" value="Sep 11, 2026" aria-label="Due date" aria-haspopup="dialog"></div><button type="button" class="cn-button" data-variant="outline" data-size="md" aria-haspopup="dialog">${ICON.calendar.replace('cn-icon', 'cn-button__icon')}<span class="cn-button__label">Sep 8 – Sep 14, 2026</span></button></div>`, 'The panel opens from an Input with a leading calendar icon (forms) or from an outline Button (filters).'),
+        ex('Disabled days', panel('data-variant="single" data-size="md"', calendar(september((n) => ({ selected: n === 15, disabled: n < 11 })), 'Sep 15, 2026', 'Delivery date')), 'Days before today are disabled: no hover, disabled ink, still visible so the month reads whole.'),
+    ],
+    rules: [
+        'Weeks start on Monday and every month renders 6 rows at most, padded with outside days (data-outside) so the panel height does not jump between months.',
+        'Today always carries the dot (data-today + aria-current="date"), even when selected or inside a range.',
+        'A range is start + end with aria-selected="true" and data-range="start|end"; the days between get data-range="middle". The footer input shows the range as "Sep 8 – Sep 14, 2026".',
+        'The footer is mandatory: the typed date in a small Input (with a leading calendar icon), Cancel (outline) and Apply (primary), size sm. Selection is committed by Apply, not by clicking a day.',
+        'Presets are for filters by period, not for forms; the list is fixed (Today, Yesterday, This week, Last week, This month, Last month) and the active one has aria-current="true".',
+        'Dates in the input and in triggers use the "Sep 11, 2026" format; never numeric-only dates that differ by locale.',
+        'The panel is statically positioned by the component; the app anchors it under its trigger with an 8px offset (Popover rules) and closes it on Escape and outside click.',
+        'Sizes: md by default; sm only inside dense toolbars. Do not scale the panel by other means.',
+    ],
+    a11y: [
+        'The panel is role="dialog" with an aria-label; focus moves into it on open (to the selected day or today) and returns to the trigger on close.',
+        'Days use a roving tabindex: one day is tabbable, Arrow keys move by day and week, Home/End jump to the row ends, PageUp/PageDown change the month.',
+        'Each day button needs a full accessible name ("Tuesday, September 8, 2026") via aria-label; the visible number alone is ambiguous.',
+        'The month name has aria-live="polite" so navigating months is announced; the nav buttons have aria-labels.',
+        'Disabled days stay in the DOM with disabled; explain the constraint near the trigger ("Deliveries start tomorrow").',
+    ],
+    related: ['input', 'button', 'popover', 'field', 'input-group'],
+};

package/lib/components/description-list.mjs

@@ -0,0 +1,88 @@
+import { ex, typeStyle } from "./_shared.mjs";
+// key/value pairs in the reference's detail rhythm: 14px medium gray-600 terms on a 160px column,
+// 14px ink values, gray-200 hairlines with 12px of padding, or stacked pairs 4px apart.
+const HAIRLINE = '{border.width.thin} solid {color.border-default}';
+const pair = (term, detail) => `<div class="cn-description-list__item"><dt class="cn-description-list__term">${term}</dt><dd class="cn-description-list__detail">${detail}</dd></div>`;
+const WORKSPACE = [
+    pair('Workspace', 'Lumen'),
+    pair('Workspace ID', '<code class="cn-text-code-sm">ws_8f2a91c4</code>'),
+    pair('Owner', 'Maya Chen'),
+    pair('Plan', '<span class="cn-badge" data-tone="accent" data-variant="soft" data-size="sm">Business</span>'),
+    pair('Created', 'March 12, 2024'),
+].join('');
+const dl = (layout, size, divided, body, style = 'width:100%;max-width:560px') => `<dl class="cn-description-list" data-layout="${layout}" data-size="${size}" data-divided="${divided}" style="${style}">${body}</dl>`;
+export const descriptionList = {
+    name: 'DescriptionList',
+    slug: 'description-list',
+    category: 'data-display',
+    description: 'Key/value pairs: a 14px medium muted term and its ink value, side by side on a 160px column or stacked, divided by gray-200 hairlines. The quiet way to show the facts of one record.',
+    usage: 'Details of one entity (a workspace, an invoice header, a customer profile) in drawers, cards and detail pages. For many records use Table; for a list of things use List.',
+    anatomy: [
+        { part: 'root', element: 'dl', description: 'The <dl>. Column of items; the layout prop decides how each pair sits.' },
+        { part: 'item', element: 'div', description: 'One pair. A <div> wrapping the dt and dd so they can be laid out as a row.' },
+        { part: 'term', element: 'dt', description: 'The key. 14px medium fg-muted, sentence case, no colon.' },
+        { part: 'detail', element: 'dd', description: 'The value. 14px in ink; may hold a Badge, a code value, a link or an Avatar with a name.' },
+    ],
+    props: {
+        layout: {
+            values: ['horizontal', 'vertical'],
+            default: 'horizontal',
+            description: 'horizontal = term on a 160px column, value beside it (drawers, detail pages, ≥ 360px wide); vertical = term above the value, 4px apart (narrow columns, card grids, mobile).',
+        },
+        size: { values: ['sm', 'md'], default: 'md', description: 'md = 14px term and value (default); sm = 12px, for dense cards and summaries.' },
+        divided: { values: ['yes', 'no'], default: 'yes', description: 'yes = a gray-200 hairline between pairs with 12px of vertical padding (scannable lists of 4+ facts); no = pairs separated by an 8px gap only (2–3 facts inside a card).' },
+    },
+    states: {},
+    base: {
+        root: { display: 'flex', 'flex-direction': 'column', margin: '0', 'min-width': '0', color: '{color.fg-default}' },
+        item: { display: 'grid', 'min-width': '0' },
+        term: { ...typeStyle('label-sm'), color: '{color.fg-muted}', 'min-width': '0' },
+        detail: { ...typeStyle('body-md'), color: '{color.fg-default}', margin: '0', 'min-width': '0', 'overflow-wrap': 'anywhere' },
+    },
+    variants: {
+        layout: {
+            horizontal: { item: { 'grid-template-columns': '{space.40} minmax(0, 1fr)', 'column-gap': '{space.4}', 'align-items': 'baseline' } },
+            vertical: { item: { 'grid-template-columns': 'minmax(0, 1fr)', 'row-gap': '{space.1}' } },
+        },
+        size: {
+            sm: { term: { 'font-size': '{font.size.xs}' }, detail: { 'font-size': '{font.size.xs}' } },
+            md: { term: { 'font-size': '{font.size.sm}' }, detail: { 'font-size': '{font.size.sm}' } },
+        },
+        divided: {
+            yes: { root: { gap: '0' }, item: { 'padding-block': '{space.3}' } },
+            no: { root: { gap: '{space.2}' }, item: { 'padding-block': '0' } },
+        },
+    },
+    compound: [
+        { when: { layout: 'horizontal', size: 'sm' }, block: { item: { 'grid-template-columns': '{space.32} minmax(0, 1fr)' } } },
+        { when: { divided: 'yes', size: 'sm' }, block: { item: { 'padding-block': '{space.2}' } } },
+        { when: { layout: 'vertical', divided: 'no' }, block: { root: { gap: '{space.4}' } } },
+    ],
+    extraCss: `
+.cn-description-list[data-divided="yes"] > .cn-description-list__item + .cn-description-list__item { border-top: ${HAIRLINE}; }
+.cn-description-list[data-divided="yes"] > .cn-description-list__item:first-child { padding-top: 0; }
+.cn-description-list[data-divided="yes"] > .cn-description-list__item:last-child { padding-bottom: 0; }
+.cn-description-list__detail > .cn-avatar-label-group { display: inline-flex; }`,
+    examples: [
+        ex('Horizontal, divided', dl('horizontal', 'md', 'yes', WORKSPACE), '160px term column, 14px medium muted terms, ink values, hairlines with 12px of padding.'),
+        ex('Vertical (narrow columns)', dl('vertical', 'md', 'yes', WORKSPACE, 'width:100%;max-width:280px'), 'Term above the value, 4px apart.'),
+        ex('Compact inside a card', `<section class="cn-card" data-variant="default" data-padding="sm" style="width:100%;max-width:360px"><div class="cn-card__body">${dl('horizontal', 'sm', 'no', [pair('Plan', 'Business · $2,900 / month'), pair('Seats', '12 of 15 used'), pair('Renews', 'October 1, 2026')].join(''), '')}</div></section>`, 'size sm, no dividers: three facts as a quiet block.'),
+        ex('Values with components', dl('horizontal', 'md', 'yes', [pair('Owner', '<span class="cn-avatar-label-group" data-size="sm"><span class="cn-avatar" data-size="xs" data-shape="circle" data-tone="neutral" data-status="none" role="img" aria-label="Maya Chen"><span class="cn-avatar__fallback" aria-hidden="true">MC</span></span><span class="cn-avatar-label-group__text"><span class="cn-avatar-label-group__name">Maya Chen</span></span></span>'), pair('Status', '<span class="cn-badge" data-tone="success" data-variant="soft" data-size="sm"><span class="cn-badge__dot"></span>Active</span>'), pair('Website', '<a href="#" class="cn-link">lumen.co</a>'), pair('Notes', 'Prefers email over Slack. Decision maker is the head of product, not the CEO.')].join(''))),
+    ],
+    rules: [
+        'Terms are sentence-case nouns with no trailing colon ("Workspace ID", not "Workspace ID:"), 14px medium muted.',
+        'Keep terms short (1–3 words) so they fit the 160px column; if a term needs a sentence, it is not a key/value pair.',
+        'Values are facts in ink, not paragraphs. A value longer than two lines belongs in a section of its own.',
+        'Empty values show an em dash ("—") in fg-subtle, never a blank cell and never the word "null" or "N/A".',
+        'Order pairs by how people look things up (identity first, then status, then dates), not by the database schema.',
+        'Use horizontal at ≥ 360px of width; below that, or in card grids, switch to vertical.',
+        'divided="yes" for 4 or more pairs; "no" for 2–3 pairs inside a card that already has a frame.',
+        'Values may hold one component (Badge sm, avatar label group, code, Link) but not buttons; actions live in the surface\'s header.',
+    ],
+    a11y: [
+        'Use the real <dl>/<dt>/<dd> elements; the wrapping <div> per pair is valid HTML and keeps the term/detail association.',
+        'Do not put interactive controls in dd besides links; a control needs a labelled form field.',
+        'Abbreviated terms (ID, VAT) get an <abbr title> or the expansion in the value on first use.',
+    ],
+    related: ['table', 'list', 'card', 'badge', 'stat', 'avatar'],
+};