canon-ds 0.1.0

package/lib/components/card-header.mjs

@@ -0,0 +1,115 @@
+import { ex, ICON, typeStyle } from "./_shared.mjs";
+// the reference table-card header: 20 × 24px padding (16 × 20 sm), a 16px semibold title with an
+// optional gray "modern" badge 8px after it, a 14px gray-600 description 2px below, an optional
+// 40px avatar or modern featured icon before the text, actions 12px apart on the right, and a
+// gray-200 hairline that spans the card.
+const HAIRLINE = '{border.width.thin} solid {color.border-default}';
+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 btn = (label, variant, icon, size = 'md') => `<button type="button" class="cn-button" data-variant="${variant}" data-size="${size}">${icon ? ICON[icon].replace('cn-icon', 'cn-button__icon') : ''}<span class="cn-button__label">${label}</span></button>`;
+const iconBtn = (label, i) => `<button type="button" class="cn-icon-button" data-variant="ghost" data-size="sm" data-shape="square" aria-label="${label}">${ICON[i].replace('cn-icon', 'cn-icon-button__icon')}</button>`;
+const content = (title, description, badge = '') => `<div class="cn-card-header__content"><h2 class="cn-card-header__title">${title}${badge}</h2><p class="cn-card-header__description">${description}</p></div>`;
+const badge = (text, tone = 'neutral') => `<span class="cn-badge cn-card-header__badge" data-tone="${tone}" data-variant="modern" data-size="sm" data-shape="square">${text}</span>`;
+const actions = (inner) => `<div class="cn-card-header__actions">${inner}</div>`;
+const tabs = (labels, current = 0) => `<div class="cn-card-header__tabs"><div class="cn-tabs" data-variant="underline" data-size="sm" data-orientation="horizontal" data-width="hug">${labels.map((l, i) => `<a href="#" class="cn-tabs__tab"${i === current ? ' aria-current="page"' : ''}>${l}</a>`).join('')}</div></div>`;
+const AVATAR = `<div class="cn-card-header__media"><span class="cn-avatar" data-size="md" data-shape="circle" data-tone="neutral" data-status="online" aria-hidden="true"><img class="cn-avatar__image" src="${SILHOUETTE}" alt=""><span class="cn-avatar__status"></span></span></div>`;
+const FEATURED = (i) => `<div class="cn-card-header__media"><span class="cn-featured-icon" data-theme="modern" data-tone="gray" data-size="md" data-shape="square">${ICON[i].replace('cn-icon', 'cn-featured-icon__icon')}</span></div>`;
+const card = (header, body) => `<section class="cn-card" data-variant="default" data-padding="none" style="width:100%;max-width:720px">${header}<div class="cn-card__body" style="padding:var(--cn-space-5) var(--cn-space-6)"><p class="cn-text-body-md">${body}</p></div></section>`;
+export const cardHeader = {
+    name: 'CardHeader',
+    slug: 'card-header',
+    category: 'layout',
+    description: 'The header row of a Card (the reference table-card header): 20 × 24px padding, a 16px semibold title with an optional gray badge, a 14px gray-600 description, an optional 40px avatar or modern featured icon before the text and the card\'s actions on the right, closed by a gray-200 hairline that spans the card.',
+    usage: 'Use as the first child of a Card that holds a table, a list, a form section or a record. It names the card and carries its actions (Import, Add user, the "more" menu). For a page title use PageHeader; for a heading between two blocks of a page use SectionHeader. Put it in a Card with data-padding="none" so the hairline reaches the card edges.',
+    anatomy: [
+        { part: 'root', element: 'header', description: 'Wrapping flex row inside the Card: media, text block, actions; 16px gaps, aligned to the top, hairline below. Padding from size.' },
+        { part: 'media', element: 'div', description: 'Optional 40px block before the text: a modern gray FeaturedIcon (md) or an Avatar md.', optional: true },
+        { part: 'content', element: 'div', description: 'Column with 2px gap: title (with optional badge) then description. Grows to push actions right.' },
+        { part: 'title', element: 'h2', description: '16px semibold in ink (heading-xs); a flex row so a Badge can follow the text 8px after it.' },
+        { part: 'badge', element: 'span', description: 'A cn-badge (modern, gray, sm, square) inside the title after the text (add this class to the badge): "100 users", "Beta".', optional: true },
+        { part: 'description', element: 'p', description: '14px supporting text in fg-muted.', optional: true },
+        { part: 'actions', element: 'div', description: 'Row of Buttons or ghost IconButtons 12px apart; the "more" menu trigger is last.', optional: true },
+        { part: 'tabs', element: 'div', description: 'Full-width slot under the text for an underline Tabs sm whose bar sits on the header hairline.', optional: true },
+    ],
+    props: {
+        variant: {
+            values: ['default', 'with-badge', 'with-media', 'with-tabs'],
+            default: 'default',
+            description: 'default = title, description, actions. with-badge = a Badge after the title (count or state of the card). with-media = a 40px avatar or featured icon before the text (a person, a company, a feature). with-tabs = underline Tabs under the text switch views of the card\'s content.',
+        },
+        size: {
+            values: ['sm', 'md'],
+            default: 'md',
+            description: 'md = 20px vertical, 24px horizontal padding (table cards, settings cards). sm = 16px × 20px for compact cards in a grid or a side column.',
+        },
+    },
+    states: {},
+    base: {
+        root: {
+            display: 'flex',
+            'flex-wrap': 'wrap',
+            'align-items': 'flex-start',
+            'justify-content': 'space-between',
+            'column-gap': '{space.4}',
+            'row-gap': '{space.4}',
+            width: '100%',
+            'min-width': '0',
+            'border-bottom': HAIRLINE,
+            'background-color': '{color.bg-surface}',
+            color: '{color.fg-default}',
+        },
+        media: {
+            display: 'flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            width: '{space.10}',
+            height: '{space.10}',
+        },
+        content: { display: 'flex', 'flex-direction': 'column', gap: '{space.0.5}', flex: '1 1 {space.48}', 'min-width': '0' },
+        title: { display: 'flex', 'align-items': 'center', 'flex-wrap': 'wrap', gap: '{space.2}', ...typeStyle('heading-xs'), color: '{color.fg-default}', 'overflow-wrap': 'anywhere' },
+        badge: { 'flex-shrink': '0' },
+        description: { ...typeStyle('body-md'), color: '{color.fg-muted}' },
+        actions: { display: 'flex', 'align-items': 'center', 'flex-wrap': 'wrap', gap: '{space.3}', 'flex-shrink': '0', 'max-width': '100%' },
+        tabs: { 'flex-basis': '100%', 'min-width': '0', 'overflow-x': 'auto' },
+    },
+    variants: {
+        variant: {
+            default: { root: {} },
+            'with-badge': { root: {} },
+            'with-media': { root: {} },
+            'with-tabs': { root: {} },
+        },
+        size: {
+            sm: { root: { padding: '{space.4} {space.5}' }, tabs: { 'margin-bottom': 'calc({space.4} * -1)' } },
+            md: { root: { padding: '{space.5} {space.6}' }, tabs: { 'margin-bottom': 'calc({space.5} * -1)' } },
+        },
+    },
+    extraCss: `
+.cn-card-header__tabs .cn-tabs[data-variant="underline"] { border-bottom: 0; min-width: max-content; margin-bottom: 0; }
+@media (max-width: {breakpoint.md}) { .cn-card-header[data-size="md"] { padding: {space.5} {space.4}; } .cn-card-header[data-size="sm"] { padding: {space.4}; } }`,
+    examples: [
+        ex('Default (table card)', card(`<header class="cn-card-header" data-variant="default" data-size="md">${content('Team members', 'Manage your team members and their account permissions here.')}${actions(btn('Import', 'outline', 'inbox') + btn('Add user', 'primary', 'plus'))}</header>`, '24 members · 3 pending invites · Last change 2 hours ago by Daniel Costa.'), 'Card with data-padding="none" so the header hairline spans the full width; 20 × 24px padding, 16px semibold title.'),
+        ex('With badge', card(`<header class="cn-card-header" data-variant="with-badge" data-size="md">${content('Team members', 'Manage your team members and their account permissions here.', badge('100 users'))}${actions(iconBtn('More actions', 'dots'))}</header>`, 'Maya Chen, Daniel Costa, Sofia Almeida and 97 others.'), 'A modern gray badge 8px after the title; a single ghost "more" IconButton on the right.'),
+        ex('With avatar', card(`<header class="cn-card-header" data-variant="with-media" data-size="md">${AVATAR}${content('Maya Chen', 'maya@lumen.co')}${actions(iconBtn('Copy email', 'copy') + iconBtn('More actions', 'dots'))}</header>`, 'Product Manager · Lisbon, Portugal · Joined March 2024.'), 'A 40px Avatar with status before the text.'),
+        ex('With tabs', card(`<header class="cn-card-header" data-variant="with-tabs" data-size="md">${content('Projects', 'Everything your team is working on right now.')}${actions(btn('New project', 'primary', 'plus', 'sm'))}${tabs(['All', 'Active', 'Archived'])}</header>`, '12 active projects, 4 archived this quarter.'), 'Underline Tabs sm under the text; their brand bar sits on the header hairline.'),
+        ex('Small with featured icon', card(`<header class="cn-card-header" data-variant="with-media" data-size="sm">${FEATURED('inbox')}${content('Notifications', 'Choose how you get notified.')}${actions(btn('Edit', 'outline', undefined, 'sm'))}</header>`, 'Email and push for mentions and approvals; in-app only for the rest.'), 'sm padding (16 × 20) with a 40px modern gray FeaturedIcon.'),
+    ],
+    rules: [
+        'Use inside a Card with data-padding="none" and give the body its own padding, so the header hairline reaches the card edges.',
+        'Title is a noun phrase in sentence case, 1–3 words, 16px semibold; the description is one sentence in 14px muted. Never repeat the page title in a card title.',
+        'Actions: one primary Button at most, outline for the rest, ghost IconButtons for copy / more; the "more" menu is always last, 12px apart.',
+        'A Badge after the title is a modern gray sm badge with a count or a state of the card content, never decoration; one per title.',
+        'with-media: an Avatar md for a person or company, a modern gray FeaturedIcon md for a feature or setting. Never both.',
+        'with-tabs: Tabs are underline, sm, and switch views of the card\'s own content; their bar sits on the header hairline (the tabs lose their own line).',
+        'md padding (20 × 24) on table and settings cards; sm (16 × 20) on cards narrower than 400px. Under 768px the horizontal padding drops to 16.',
+        'Keep the header on one row when space allows. Let actions wrap below the content before the title or description becomes a narrow column.',
+    ],
+    a11y: [
+        'Root is a <header> inside the Card <section>; the title heading level follows the page outline (h2 under a PageHeader h1).',
+        'A Badge inside the title becomes part of the heading name; keep it short and meaningful.',
+        'IconButtons in actions need aria-label; the "more" trigger exposes aria-haspopup="menu".',
+        'Tabs under the header are route links with aria-current="page" or a role="tablist" with aria-selected.',
+        'The featured icon is decorative (aria-hidden); an Avatar whose name is the title is aria-hidden too, so the name is not read twice.',
+    ],
+    related: ['card', 'section-header', 'page-header', 'badge', 'avatar', 'featured-icon', 'icon-button', 'tabs', 'table'],
+};

package/lib/components/card.mjs

@@ -0,0 +1,106 @@
+import { FOCUS_RING, STATE, ex, ICON, typeStyle } from "./_shared.mjs";
+// Resting surfaces stay flat; a leading rule communicates selection.
+const HAIRLINE = '{border.width.thin} solid {color.border-default}';
+const ring = (color) => `inset 0 0 0 1px ${color}`;
+const TRANSITION_FAST = {
+    'transition-property': 'background-color, box-shadow, transform',
+    'transition-duration': '{motion.duration.fast}',
+    'transition-timing-function': '{motion.easing.linear}',
+};
+const btn = (label, variant) => `<button type="button" class="cn-button" data-variant="${variant}" data-size="sm"><span class="cn-button__label">${label}</span></button>`;
+export const card = {
+    name: 'Card',
+    slug: 'card',
+    category: 'layout',
+    description: 'A bounded surface for one thing: an entity, a form section, a stat. A neutral surface, a fine outline and compact corners, with a leading rule on selected cards.',
+    usage: 'Group related content that stands alone (a customer, a settings section, a KPI). Do not use cards as a layout grid for everything; lists and tables are better for collections of similar rows. Use variant="interactive" only when the whole card is one link/action. Put a CardHeader first when the card needs a title with actions.',
+    anatomy: [
+        { part: 'root', element: 'section', description: 'The surface: surface fill, fine outline, token-defined corners; padding via the padding prop.' },
+        { part: 'header', element: 'header', description: 'Title row with optional actions on the right, inside the padding (for a full-width hairline header use CardHeader with padding none).', optional: true },
+        { part: 'title', element: 'h3', description: 'heading-sm (18/28 semibold). One per card.', optional: true },
+        { part: 'description', element: 'p', description: '14px fg-muted, under the title.', optional: true },
+        { part: 'actions', element: 'div', description: 'Right-aligned row of ghost / outline buttons in the header, 12px apart.', optional: true },
+        { part: 'body', element: 'div', description: 'Main content.' },
+        { part: 'footer', element: 'footer', description: 'Meta or actions on a gray-200 hairline, 16 × 24px padding (12 / 24 / 16 in a padding="none" card, pagination footer; add data-padding="none" on the footer itself to zero it); on a subtle surface.', optional: true },
+    ],
+    props: {
+        variant: { values: ['default', 'outlined', 'elevated', 'interactive', 'ghost'], default: 'default', description: 'default = a flat surface with a fine outline; outlined = ring only, transparent background (on white canvases); elevated = shadow-md (only on a same-color canvas); interactive = whole card is one link or action: the edge strengthens and the surface changes on hover; ghost = no ring, gray-50 fill (a quiet group inside another card).' },
+        padding: { values: ['none', 'sm', 'md', 'lg'], default: 'md', description: 'Inner padding of header/body/footer: none for tables, lists and media that bleed to the edge; sm 16px (compact cards in a grid); md 24px (default); lg 32px (hero cards and settings sections).' },
+    },
+    states: {
+        hover: { selector: ':hover', description: 'Only interactive cards react: a stronger edge and subtle fill.', markup: 'native' },
+        focus: STATE.focus(),
+        selected: STATE.selected(),
+    },
+    base: {
+        root: {
+            display: 'flex',
+            position: 'relative',
+            'flex-direction': 'column',
+            'background-color': '{color.bg-surface}',
+            'box-shadow': ring('{color.border-default}'),
+            'border-radius': '{radius.card}',
+            color: '{color.fg-default}',
+            'min-width': '0',
+            overflow: 'hidden',
+        },
+        header: { display: 'flex', 'align-items': 'flex-start', 'justify-content': 'space-between', gap: '{space.4}' },
+        title: { ...typeStyle('heading-sm'), color: '{color.fg-default}' },
+        description: { ...typeStyle('body-md'), color: '{color.fg-muted}', 'margin-top': '{space.0.5}' },
+        actions: { display: 'flex', 'align-items': 'center', gap: '{space.3}', 'flex-shrink': '0' },
+        body: { flex: '1 1 auto', 'min-width': '0' },
+        footer: { 'background-color': '{color.bg-subtle}', display: 'flex', 'align-items': 'center', gap: '{space.3}', 'border-top': HAIRLINE, ...typeStyle('body-md'), color: '{color.fg-muted}' },
+        '@states': {
+            selected: { root: { 'box-shadow': ring('{color.border-action}'), 'background-color': '{color.bg-action-subtle}' } },
+        },
+    },
+    variants: {
+        variant: {
+            default: { root: {} },
+            outlined: { root: { 'background-color': 'transparent', 'box-shadow': ring('{color.border-default}') } },
+            elevated: { root: { 'box-shadow': `${ring('{color.border-subtle}')}, {shadow.md}` } },
+            interactive: {
+                root: { cursor: 'pointer', ...TRANSITION_FAST },
+                '@states': {
+                    hover: { root: { 'box-shadow': ring('{color.border-control-hover}'), 'background-color': '{color.bg-subtle}' } },
+                    focus: { root: { ...FOCUS_RING, 'box-shadow': `${ring('{color.border-control}')}, {shadow.focus}` } },
+                },
+            },
+            ghost: { root: { 'background-color': '{color.bg-subtle}', 'box-shadow': 'none' } },
+        },
+        padding: {
+            none: { header: { padding: '0' }, body: { padding: '0' }, footer: { padding: '{space.3} {space.6} {space.4}' } },
+            sm: { header: { padding: '{space.4} {space.4} 0' }, body: { padding: '{space.4}' }, footer: { padding: '{space.3} {space.4}' } },
+            md: { header: { padding: '{space.6} {space.6} 0' }, body: { padding: '{space.6}' }, footer: { padding: '{space.4} {space.6}' } },
+            lg: { header: { padding: '{space.8} {space.8} 0' }, body: { padding: '{space.8}' }, footer: { padding: '{space.5} {space.8}' } },
+        },
+    },
+    extraCss: `
+.cn-card[data-selected]::before { content: ""; position: absolute; inset-block: {space.4}; inset-inline-start: 0; width: {border.width.thick}; background: {color.bg-action}; }
+.cn-card[data-padding="md"] .cn-card__header + .cn-card__body { padding-top: {space.5}; }
+.cn-card[data-padding="sm"] .cn-card__header + .cn-card__body { padding-top: {space.4}; }
+.cn-card[data-padding="lg"] .cn-card__header + .cn-card__body { padding-top: {space.6}; }
+.cn-card[data-padding="none"] > .cn-card__footer[data-padding="none"] { padding: 0; }`,
+    examples: [
+        ex('Default with header and footer', `<section class="cn-card" data-variant="default" data-padding="md" style="max-width:400px"><header class="cn-card__header"><div><h3 class="cn-card__title">Lumen website redesign</h3><p class="cn-card__description">Marketing site · Due Sep 19</p></div><div class="cn-card__actions"><button type="button" class="cn-icon-button" data-variant="ghost" data-size="sm" data-shape="square" aria-label="More actions">${ICON.dots.replace('cn-icon', 'cn-icon-button__icon')}</button></div></header><div class="cn-card__body"><p class="cn-text-body-md">12 tasks, 4 in review. Sofia Almeida owns the design track, Daniel Costa the build.</p></div><footer class="cn-card__footer">Updated 2h ago by Maya Chen</footer></section>`, 'Flat surface, fine outline, 24px padding; the footer sits on a hairline.'),
+        ex('With a CardHeader and a table-like body', `<section class="cn-card" data-variant="default" data-padding="none" style="max-width:480px"><header class="cn-card-header" data-variant="default" data-size="md"><div class="cn-card-header__content"><h2 class="cn-card-header__title">Team members</h2><p class="cn-card-header__description">Manage your team and their permissions.</p></div><div class="cn-card-header__actions">${btn('Add user', 'primary')}</div></header><div class="cn-card__body" style="padding:var(--cn-space-6)"><p class="cn-text-body-md">6 members · 1 invitation pending.</p></div><footer class="cn-card__footer">${btn('Previous', 'outline')}<span style="margin-inline:auto">Page 1 of 3</span>${btn('Next', 'outline')}</footer></section>`, 'padding="none" so the CardHeader hairline spans the card; the body sets its own 24px padding.'),
+        ex('Interactive and selected', `<div style="display:flex;gap:var(--cn-space-6);flex-wrap:wrap"><a href="#" class="cn-card" data-variant="interactive" data-padding="md" style="width:280px"><div class="cn-card__body"><h3 class="cn-card__title">Open the workspace</h3><p class="cn-card__description">12 projects · 3 waiting for you</p></div></a><a href="#" class="cn-card" data-variant="interactive" data-padding="md" data-selected style="width:280px"><div class="cn-card__body"><h3 class="cn-card__title">Business plan</h3><p class="cn-card__description">$2,900 / month · 15 seats</p></div></a></div>`, 'Hover strengthens the outline; selection adds an action-tinted surface and a leading rule.'),
+        ex('Sizes of padding', `<div style="display:flex;gap:var(--cn-space-6);flex-wrap:wrap;align-items:flex-start"><section class="cn-card" data-variant="default" data-padding="sm" style="width:200px"><div class="cn-card__body cn-text-body-md">sm · 16px</div></section><section class="cn-card" data-variant="default" data-padding="md" style="width:200px"><div class="cn-card__body cn-text-body-md">md · 24px</div></section><section class="cn-card" data-variant="default" data-padding="lg" style="width:200px"><div class="cn-card__body cn-text-body-md">lg · 32px</div></section></div>`),
+        ex('Outlined, elevated and ghost', `<div style="display:flex;gap:var(--cn-space-6);flex-wrap:wrap;align-items:flex-start"><section class="cn-card" data-variant="outlined" data-padding="sm" style="width:220px"><div class="cn-card__body cn-text-body-md">Outlined: ring only, no fill or shadow.</div></section><section class="cn-card" data-variant="elevated" data-padding="sm" style="width:220px"><div class="cn-card__body cn-text-body-md">Elevated: shadow-md on a same-color canvas.</div></section><section class="cn-card" data-variant="ghost" data-padding="sm" style="width:220px"><div class="cn-card__body cn-text-body-md">Ghost: a quiet gray-50 group inside another card.</div></section></div>`),
+    ],
+    rules: [
+        'Resting cards have a fine outline. Only floating layers use elevation; interactive cards respond through their edge and surface.',
+        'One title per card. Use a CardHeader (padding none) when the title needs a hairline, a badge, media or tabs; the plain header part is for simple titled cards.',
+        'Do not nest default cards inside default cards. Inside a card use ghost cards, dividers or plain groups.',
+        'A collection of similar items is a list or a table inside one card, not a grid of cards. Cards for a grid only when each item is visual (media) or the number is ≤ 6.',
+        'Padding is a prop, never ad-hoc: md 24px by default, sm 16px in dense grids, lg 32px for hero and settings cards, none when a table, list or media fills the card.',
+        'Interactive cards contain no other interactive elements (no buttons inside a link) and show a stronger edge on hover; selected cards (radio cards) carry data-selected and a leading selection rule.',
+        'Footers hold meta or the pagination / actions row, on a hairline, on a subtle surface.',
+    ],
+    a11y: [
+        'Interactive cards are an <a> (navigation) or a <button> (action), never a div with onClick; selectable cards are radios or checkboxes with the card as their label.',
+        'Use <section> with an aria-labelledby pointing to the title when the card is a landmark of the page.',
+        'The focus ring follows the active token on :focus-visible; the selected ring is separate and does not replace it.',
+    ],
+    related: ['card-header', 'section-header', 'stat', 'list', 'table', 'divider'],
+};

package/lib/components/carousel.mjs

@@ -0,0 +1,182 @@
+import { RESET_BUTTON, TRANSITION_COLORS, ex, typeStyle } from "./_shared.mjs";
+// Carousel: a clipped viewport with a flex track of slides, 40px round prev/next
+// controls (inside the viewport or in a row below it), dot or line indicators and
+// an optional caption on a scrim. Static in the gallery; the app moves the track.
+const CHEVRON_L = '<svg class="cn-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="M10 4l-4 4 4 4"/></svg>';
+const CHEVRON_R = '<svg class="cn-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="M6 4l4 4-4 4"/></svg>';
+/** Muted 16:9 scenes so slides render without the network. */
+const SCENES = [
+    `<circle cx="480" cy="104" r="40" style="fill:var(--cn-color-bg-surface)"/><path d="M0 300L150 168l110 92 100-130 280 170v60H0z" style="fill:var(--cn-color-border-strong)"/>`,
+    `<rect x="72" y="64" width="232" height="112" rx="12" style="fill:var(--cn-color-bg-surface)"/><rect x="336" y="64" width="232" height="112" rx="12" style="fill:var(--cn-color-bg-surface)"/><rect x="72" y="208" width="496" height="88" rx="12" style="fill:var(--cn-color-bg-surface)"/><path d="M96 272l60-28 70 18 66-40 80 22 96-44" fill="none" stroke-width="3" stroke-linecap="round" style="stroke:var(--cn-color-bg-action)"/>`,
+    `<rect x="200" y="72" width="240" height="216" rx="16" style="fill:var(--cn-color-bg-surface)"/><circle cx="320" cy="150" r="36" style="fill:var(--cn-color-border-strong)"/><rect x="248" y="212" width="144" height="12" rx="6" style="fill:var(--cn-color-border-default)"/><rect x="272" y="240" width="96" height="12" rx="6" style="fill:var(--cn-color-border-default)"/>`,
+];
+const scene = (i, label) => `<span class="cn-placeholder" data-radius="none"><svg viewBox="0 0 640 360" role="img" aria-label="${label}"><rect width="640" height="360" style="fill:var(--cn-color-bg-muted)"/>${SCENES[i % SCENES.length]}</svg></span>`;
+const slide = (i, total, inner) => `<div class="cn-carousel__slide" role="group" aria-roledescription="slide" aria-label="${i} of ${total}">${inner}</div>`;
+const controls = (disabledPrev = false) => `<div class="cn-carousel__controls"><button type="button" class="cn-carousel__control" aria-label="Previous slide"${disabledPrev ? ' disabled' : ''}>${CHEVRON_L}</button><button type="button" class="cn-carousel__control" aria-label="Next slide">${CHEVRON_R}</button></div>`;
+const indicators = (n, current) => `<div class="cn-carousel__indicators" role="group" aria-label="Choose slide">${Array.from({ length: n }, (_, i) => `<button type="button" class="cn-carousel__indicator" aria-label="Go to slide ${i + 1}"${i + 1 === current ? ' aria-current="true"' : ''}></button>`).join('')}</div>`;
+const root = (attrs, inner, width = '640px') => `<div class="cn-carousel" ${attrs} role="region" aria-roledescription="carousel" aria-label="Product tour" style="width:100%;max-width:${width}">${inner}</div>`;
+const quote = (text, author, meta) => `<p class="cn-carousel__quote">${text}</p><span class="cn-carousel__author">${author}</span><span class="cn-carousel__meta">${meta}</span>`;
+export const carousel = {
+    name: 'Carousel',
+    slug: 'carousel',
+    category: 'media',
+    description: 'A clipped viewport (radius card) over a flex track of slides, with 40px round prev/next controls that sit inside the picture or in a row under it, 8px dot or 24px line indicators, and an optional caption on a scrim. The component is static; the app moves the track.',
+    usage: 'Use for a small set of visual items where one at a time is enough: product screenshots, gallery photos, customer quotes, onboarding cards. Not for content people need to compare (use a grid), not for navigation, and never auto-playing text.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'The region (role="region", aria-roledescription="carousel"). Relative; stacks the viewport and, for controls="outside", the control row.' },
+        { part: 'viewport', element: 'div', description: 'Clips the track: overflow hidden, radius card, bg-subtle. Controls, indicators and caption overlay it.' },
+        { part: 'track', element: 'div', description: 'Flex row of slides that the app translates (transform) to move between them.' },
+        { part: 'slide', element: 'div', description: 'One item (role="group", aria-roledescription="slide", aria-label "2 of 5"). 100% wide in single, a third in multi, a centered quote card in testimonial.' },
+        { part: 'controls', element: 'div', description: 'Holds the two control buttons: absolutely centered over the viewport edges (inside) or a static right-aligned row under it (outside).', optional: true },
+        { part: 'control', element: 'button', description: '40px circle, bg-surface, hairline, shadow-md, 20px chevron. aria-label "Previous slide" / "Next slide"; disabled at the ends when not looping.', optional: true },
+        { part: 'indicators', element: 'div', description: 'Centered row of indicator buttons 16px above the bottom edge (role="group").', optional: true },
+        { part: 'indicator', element: 'button', description: '8px dot (or 24×4 line) in bg-muted; the current one is bg-action and carries aria-current="true".', optional: true },
+        { part: 'caption', element: 'div', description: 'Bottom-left text over a bg-inverse scrim (color-mix 60%), body-sm in fg-inverse. Leaves room for the indicators.', optional: true },
+        { part: 'quote', element: 'p', description: 'Testimonial text, heading-md, centered.', optional: true },
+        { part: 'author', element: 'span', description: 'Who said it, label-md, under the quote.', optional: true },
+        { part: 'meta', element: 'span', description: 'Role and company, body-sm muted.', optional: true },
+    ],
+    props: {
+        variant: {
+            values: ['single', 'multi', 'testimonial'],
+            default: 'single',
+            description: 'single = one full-width slide at a time (screenshots, photos). multi = three cards visible with a 16px gap, the track scrolls by one card (feature cards, logos). testimonial = each slide is a centered quote card on bg-subtle with author and role.',
+        },
+        indicators: {
+            values: ['dots', 'lines', 'none'],
+            default: 'dots',
+            description: 'dots = 8px circles (up to about 8 slides). lines = 24×4 bars, for 2–5 slides on marketing pages. none = hide the indicators when the controls or the caption already tell the position.',
+        },
+        controls: {
+            values: ['inside', 'outside', 'none'],
+            default: 'inside',
+            description: 'inside = round buttons floating over the left and right edges of the picture (photos, screenshots). outside = a row of the same buttons under the viewport, right-aligned, so nothing covers the content (cards, quotes). none = swipe and indicators only (mobile, testimonials).',
+        },
+    },
+    states: {
+        current: { selector: ' .cn-carousel__indicator[aria-current="true"]', description: 'The indicator of the visible slide (on the indicator; extraCss): bg-action.', markup: 'aria-current="true" on .cn-carousel__indicator' },
+        controlHover: { selector: ' .cn-carousel__control:hover', description: 'Pointer over a control (extraCss): bg-subtle fill, stronger border.', markup: 'native :hover on .cn-carousel__control' },
+        controlFocus: { selector: ' .cn-carousel__control:focus-visible', description: 'Keyboard focus on a control adds the focus ring under the shadow (extraCss).', markup: 'native :focus-visible on .cn-carousel__control' },
+        controlDisabled: { selector: ' .cn-carousel__control:disabled', description: 'At the first or last slide of a non-looping carousel: 50% opacity, not-allowed (extraCss).', markup: 'disabled on .cn-carousel__control' },
+    },
+    base: {
+        root: { position: 'relative', display: 'flex', 'flex-direction': 'column', width: '100%', 'min-width': '0', color: '{color.fg-default}' },
+        viewport: { position: 'relative', overflow: 'hidden', width: '100%', 'border-radius': '{radius.card}', 'background-color': '{color.bg-subtle}' },
+        track: { display: 'flex', width: '100%', 'transition-property': 'transform', 'transition-duration': '{motion.duration.slow}', 'transition-timing-function': '{motion.easing.standard}' },
+        slide: { position: 'relative', flex: '0 0 100%', 'min-width': '0' },
+        controls: {
+            position: 'absolute',
+            'inset-inline': '{space.4}',
+            top: '50%',
+            transform: 'translateY(-50%)',
+            display: 'flex',
+            'justify-content': 'space-between',
+            'pointer-events': 'none',
+            'z-index': '{z.raised}',
+        },
+        control: {
+            ...RESET_BUTTON,
+            'pointer-events': 'auto',
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            width: '{space.10}',
+            height: '{space.10}',
+            'border-radius': '{radius.full}',
+            'background-color': '{color.bg-surface}',
+            border: '{border.width.thin} solid {color.border-default}',
+            'box-shadow': '{shadow.md}',
+            color: '{color.fg-default}',
+            ...TRANSITION_COLORS,
+        },
+        indicators: {
+            position: 'absolute',
+            'inset-inline': '0',
+            bottom: '{space.4}',
+            display: 'flex',
+            'justify-content': 'center',
+            'align-items': 'center',
+            gap: '{space.2}',
+            'pointer-events': 'none',
+            'z-index': '{z.raised}',
+        },
+        indicator: {
+            ...RESET_BUTTON,
+            'pointer-events': 'auto',
+            width: '{space.2}',
+            height: '{space.2}',
+            'border-radius': '{radius.full}',
+            'background-color': '{color.bg-muted}',
+            ...TRANSITION_COLORS,
+        },
+        caption: {
+            position: 'absolute',
+            'inset-inline': '0',
+            bottom: '0',
+            padding: '{space.4} {space.5}',
+            'background-color': 'color-mix(in srgb, {color.bg-inverse} 60%, transparent)',
+            color: '{color.fg-inverse}',
+            ...typeStyle('body-sm'),
+        },
+        quote: { ...typeStyle('heading-md'), color: '{color.fg-default}', 'text-align': 'center', 'text-wrap': 'balance', 'max-width': '{size.container.sm}' },
+        author: { ...typeStyle('label-md'), color: '{color.fg-default}', 'margin-top': '{space.6}' },
+        meta: { ...typeStyle('body-sm'), color: '{color.fg-muted}', 'margin-top': '{space.1}' },
+    },
+    variants: {
+        variant: {
+            single: { slide: { flex: '0 0 100%' } },
+            multi: {
+                viewport: { 'border-radius': '{radius.none}', 'background-color': 'transparent' },
+                track: { gap: '{space.4}' },
+                slide: { flex: '0 0 calc((100% - 2 * {space.4}) / 3)', 'border-radius': '{radius.card}', overflow: 'hidden' },
+            },
+            testimonial: {
+                slide: { display: 'flex', 'flex-direction': 'column', 'align-items': 'center', 'justify-content': 'center', 'text-align': 'center', padding: '{space.10} {space.8} {space.12}', 'min-height': '280px' },
+            },
+        },
+        indicators: {
+            dots: { indicator: {} },
+            lines: { indicator: { width: '{space.6}', height: '{space.1}' } },
+            none: { indicators: { display: 'none' } },
+        },
+        controls: {
+            inside: { controls: {} },
+            outside: { controls: { position: 'static', transform: 'none', 'justify-content': 'flex-end', gap: '{space.3}', 'padding-top': '{space.4}', 'pointer-events': 'auto' } },
+            none: { controls: { display: 'none' } },
+        },
+    },
+    extraCss: `
+.cn-carousel__control .cn-icon { width: {size.icon.lg}; height: {size.icon.lg}; }
+.cn-carousel__control:hover:not(:disabled) { background-color: {color.bg-subtle}; border-color: {color.border-strong}; }
+.cn-carousel__control:focus-visible { outline: none; box-shadow: {shadow.md}, {shadow.focus}; }
+.cn-carousel__control:disabled { opacity: {opacity.disabled}; cursor: not-allowed; }
+.cn-carousel__indicator[aria-current="true"] { background-color: {color.bg-action}; }
+.cn-carousel__indicator:focus-visible { outline: none; box-shadow: {shadow.focus}; }
+.cn-carousel:not([data-indicators="none"]) .cn-carousel__caption { padding-bottom: {space.9}; }
+.cn-carousel__slide > .cn-placeholder { border-radius: 0; }`,
+    examples: [
+        ex('Single with caption', root('data-variant="single" data-indicators="dots" data-controls="inside"', `<div class="cn-carousel__viewport"><div class="cn-carousel__track">${slide(1, 3, scene(0, 'Lumen dashboard on a laptop'))}${slide(2, 3, scene(1, 'Reporting view'))}${slide(3, 3, scene(2, 'Mobile app'))}</div>${controls(true)}${indicators(3, 1)}<div class="cn-carousel__caption">Lumen Studio · the new reporting workspace, September 2026</div></div>`), 'Round controls float over the edges; the caption sits on a scrim and leaves room for the dots. Previous is disabled on the first slide.'),
+        ex('Multi (three cards) with outside controls', root('data-variant="multi" data-indicators="none" data-controls="outside"', `<div class="cn-carousel__viewport"><div class="cn-carousel__track">${slide(1, 5, scene(1, 'Dashboards'))}${slide(2, 5, scene(2, 'Approvals'))}${slide(3, 5, scene(0, 'Mobile'))}${slide(4, 5, scene(1, 'Integrations'))}${slide(5, 5, scene(2, 'Reports'))}</div></div>${controls()}`, '760px'), 'Three cards visible with a 16px gap; the controls sit under the row so nothing covers the cards.'),
+        ex('Testimonial', root('data-variant="testimonial" data-indicators="dots" data-controls="none"', `<div class="cn-carousel__viewport"><div class="cn-carousel__track">${slide(1, 3, quote('“We replaced four spreadsheets with one Lumen dashboard. The finance review went from a day to forty minutes.”', 'Elena Rossi', 'Head of Finance, Northwind Freight'))}${slide(2, 3, quote('“Approvals on the phone changed how our field team works.”', 'Tomás Silva', 'Operations Lead, Verde Farms'))}${slide(3, 3, quote('“Onboarding a new analyst takes an afternoon now.”', 'Aisha Khan', 'Data Lead, Orbit Health'))}</div>${indicators(3, 1)}</div>`), 'A centered quote card per slide; dots only, swipe to move.'),
+        ex('Lines, no controls', root('data-variant="single" data-indicators="lines" data-controls="none"', `<div class="cn-carousel__viewport"><div class="cn-carousel__track">${slide(1, 4, scene(2, 'Onboarding step 1'))}${slide(2, 4, scene(0, 'Onboarding step 2'))}${slide(3, 4, scene(1, 'Onboarding step 3'))}${slide(4, 4, scene(2, 'Onboarding step 4'))}</div>${indicators(4, 2)}</div>`, '480px'), '24×4 line indicators for a short onboarding sequence; the second slide is current.'),
+    ],
+    rules: [
+        'Three to eight slides. With one there is nothing to move; with more than eight use a grid with pagination.',
+        'Never auto-play. If a marketing page insists, pause on hover and focus, stop after one loop, and offer a pause button.',
+        'Controls inside only over pictures with quiet edges; over text or cards use outside so nothing is covered.',
+        'Disable Previous on the first slide and Next on the last unless the carousel loops; show both buttons always.',
+        'Indicators are dots up to eight slides, lines for two to five on marketing pages; hide them when a caption or counter already shows the position.',
+        'Captions are one line of body-sm on the scrim, bottom-left; longer descriptions go under the carousel as text.',
+        'Slides keep one aspect ratio across the set (16:9 by default); never let the height jump between slides.',
+        'The viewport is the only element with overflow hidden; the track moves with transform, 260ms, and respects reduced motion.',
+        'On touch, swipe moves one slide; on keyboard, Left/Right move when the region has focus.',
+    ],
+    a11y: [
+        'Root: role="region", aria-roledescription="carousel", aria-label naming the set. Slides: role="group", aria-roledescription="slide", aria-label "2 of 5".',
+        'Controls are real <button>s with aria-label "Previous slide" / "Next slide"; indicators are buttons with aria-label "Go to slide n" and aria-current="true" on the current one.',
+        'Hidden slides are aria-hidden="true" and their links get tabindex="-1" so keyboard users do not tab into off-screen content.',
+        'Announce slide changes with an aria-live="polite" region ("Slide 2 of 5") rather than moving focus.',
+        'Images need alt text or, for decorative art, alt=""; captions that describe the slide can serve as the accessible name via aria-labelledby.',
+    ],
+    related: ['media-frame', 'video-player', 'card', 'icon-button', 'pagination'],
+};

package/lib/components/chart-frame.mjs

@@ -0,0 +1,101 @@
+import { ex, ICON, typeStyle } from "./_shared.mjs";
+// the reference chart card: white, gray-200 ring, shadow-xs, radius 12, 20 × 24px padding; an
+// 18px semibold title with a 14px muted description, a legend of 8px round swatches with 14px
+// gray-600 labels 12px apart, gray-100 gridlines and 12px gray-500 axis text.
+const ring = (color) => `inset 0 0 0 1px ${color}`;
+/** Grouped bars, 6 months × 2 series, drawn with token variables only. */
+const MONTHS = ['Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep'];
+const SIGNUPS = [42, 55, 38, 60, 47, 51];
+const UPGRADES = [12, 19, 15, 24, 18, 21];
+const BASE = 170, MAX = 60, H = 130;
+const bars = MONTHS.map((m, i) => {
+    const cx = 32 + 73 * i + 36.5;
+    const hs = Math.round((SIGNUPS[i] / MAX) * H), hr = Math.round((UPGRADES[i] / MAX) * H);
+    return `<rect x="${cx - 22}" y="${BASE - hs}" width="20" height="${hs}" rx="2" fill="var(--cn-color-bg-action)"><title>${m} sign-ups: ${SIGNUPS[i]}</title></rect><rect x="${cx + 2}" y="${BASE - hr}" width="20" height="${hr}" rx="2" fill="var(--cn-brand-300)"><title>${m} upgrades: ${UPGRADES[i]}</title></rect><text x="${cx}" y="188" text-anchor="middle">${m}</text>`;
+}).join('');
+const grid = [0, 20, 40, 60].map((v) => { const y = Math.round(BASE - (v / MAX) * H); return `<line x1="32" x2="472" y1="${y}" y2="${y}" stroke="var(--cn-color-border-subtle)"/><text x="24" y="${y + 4}" text-anchor="end">${v}</text>`; }).join('');
+const BAR_CHART = `<svg viewBox="0 0 480 200" width="100%" role="img" aria-label="Sign-ups and upgrades per month, last 6 months. Upgrades grew from 12 to 21." style="display:block;max-width:100%">${grid}${bars}</svg>`;
+const SPARK = `<svg viewBox="0 0 320 80" width="100%" role="img" aria-label="Conversion rate, last 30 days: 3.2% to 4.2%" style="display:block;color:var(--cn-color-bg-action);max-width:100%"><defs><linearGradient id="cn-spark-fill" x1="0" x2="0" y1="0" y2="1"><stop offset="0" stop-color="currentColor" stop-opacity="0.16"/><stop offset="1" stop-color="currentColor" stop-opacity="0"/></linearGradient></defs><path d="M0,62 L32,58 L64,60 L96,48 L128,52 L160,40 L192,44 L224,30 L256,34 L288,22 L320,18 V80 H0 Z" fill="url(#cn-spark-fill)"/><polyline points="0,62 32,58 64,60 96,48 128,52 160,40 192,44 224,30 256,34 288,22 320,18" fill="none" stroke="currentColor" stroke-width="2" stroke-linejoin="round" stroke-linecap="round"/><circle cx="320" cy="18" r="4" fill="var(--cn-color-bg-surface)" stroke="currentColor" stroke-width="2"/></svg>`;
+const legend = (items) => `<div class="cn-chart-frame__legend">${items.map(([label, color]) => `<span class="cn-chart-frame__legend-item"><span class="cn-chart-frame__swatch" style="background:${color}"></span>${label}</span>`).join('')}</div>`;
+export const chartFrame = {
+    name: 'ChartFrame',
+    slug: 'chart-frame',
+    category: 'data-display',
+    description: 'The card every chart lives in: an 18px semibold title and muted description on the left, a legend of round swatches on the right, a fixed-height body for the chart and a small footer line. White, gray-200 ring, shadow-xs, radius 12. The chart itself is your SVG or library output; the frame gives it the system\'s type, colors and spacing.',
+    usage: 'Wrap every chart (bars, lines, areas, donuts) in dashboards and reports. Not for single numbers (Stat) and not for tables of values (Table).',
+    anatomy: [
+        { part: 'root', element: 'section', description: 'The card: white, gray-200 ring, shadow-xs, radius 12, 20 × 24px padding, column layout with 20px gaps.' },
+        { part: 'header', element: 'header', description: 'Row: title + description on the left, legend (or a small control) on the right, 16px apart.' },
+        { part: 'title', element: 'h3', description: 'What the chart shows, 18px semibold in ink, sentence case ("Sign-ups per month").' },
+        { part: 'description', element: 'p', description: 'Optional one line: period, filter or definition, 14px fg-muted.', optional: true },
+        { part: 'legend', element: 'div', description: 'Wrapping row of legend items, 12px apart, 14px fg-muted.', optional: true },
+        { part: 'legend-item', element: 'span', description: 'Swatch + series name, 8px apart.', optional: true },
+        { part: 'swatch', element: 'span', description: '8px round swatch with a 0.5px inner contrast ring, filled with the series color via an inline style using a token variable.', optional: true },
+        { part: 'body', element: 'div', description: 'Where the chart goes. Position relative, min-height from size, the SVG fills the width; axis text is 12px fg-subtle. Also the place for an EmptyState or Skeleton.' },
+        { part: 'footer', element: 'footer', description: 'Optional source or note, 12px fg-subtle ("Source: product analytics · Updated 2h ago").', optional: true },
+    ],
+    props: {
+        size: {
+            values: ['sm', 'md', 'lg'],
+            default: 'md',
+            description: 'Minimum height of the body: sm 160px (sparklines and small multiples, 16 × 20px padding), md 240px (dashboard tiles), lg 320px (the main chart of a report page).',
+        },
+    },
+    states: {},
+    base: {
+        root: {
+            display: 'flex',
+            'flex-direction': 'column',
+            gap: '{space.5}',
+            'background-color': '{color.bg-surface}',
+            'box-shadow': `${ring('{color.border-default}')}, {shadow.xs}`,
+            'border-radius': '{radius.card}',
+            padding: '{space.5} {space.6}',
+            'min-width': '0',
+            color: '{color.fg-default}',
+        },
+        header: { display: 'flex', 'align-items': 'flex-start', 'justify-content': 'space-between', gap: '{space.4}', 'flex-wrap': 'wrap' },
+        title: { ...typeStyle('heading-sm'), color: '{color.fg-default}', margin: '0' },
+        description: { ...typeStyle('body-md'), color: '{color.fg-muted}', 'margin-top': '{space.0.5}' },
+        legend: { display: 'flex', 'flex-wrap': 'wrap', gap: '{space.1} {space.3}', ...typeStyle('body-md'), color: '{color.fg-muted}' },
+        'legend-item': { display: 'inline-flex', 'align-items': 'center', gap: '{space.2}', 'white-space': 'nowrap' },
+        swatch: { width: '{space.2}', height: '{space.2}', 'border-radius': '{radius.full}', 'flex-shrink': '0', 'background-color': '{color.bg-action}', 'box-shadow': 'inset 0 0 0 0.5px color-mix(in srgb, {black} 10%, transparent)' },
+        body: { position: 'relative', 'min-width': '0', 'min-height': 'calc({space.56} + {space.4})' },
+        footer: { ...typeStyle('body-sm'), color: '{color.fg-subtle}' },
+    },
+    variants: {
+        size: {
+            sm: { body: { 'min-height': '{space.40}' }, root: { padding: '{space.4} {space.5}', gap: '{space.4}' } },
+            md: { body: { 'min-height': 'calc({space.56} + {space.4})' } },
+            lg: { body: { 'min-height': 'calc({space.64} + {space.16})' } },
+        },
+    },
+    extraCss: `
+.cn-chart-frame__body > svg { display: block; width: 100%; height: auto; }
+.cn-chart-frame__body > svg text { font-family: {font.family.sans}; font-size: {font.size.xs}; fill: {color.fg-subtle}; }
+.cn-chart-frame .cn-chart-frame__body[data-scroll] { overflow-x: auto; }
+.cn-chart-frame__body[data-scroll] > svg { min-width: {size.container.xs}; }
+.cn-chart-frame__header > .cn-stat { align-items: flex-end; }`,
+    examples: [
+        ex('Bars, two series', `<section class="cn-chart-frame" data-size="md" style="width:100%;max-width:560px"><header class="cn-chart-frame__header"><div><h3 class="cn-chart-frame__title">Sign-ups and upgrades</h3><p class="cn-chart-frame__description">Last 6 months · all plans</p></div>${legend([['Sign-ups', 'var(--cn-color-bg-action)'], ['Upgrades', 'var(--cn-brand-300)']])}</header><div class="cn-chart-frame__body" data-scroll role="region" tabindex="0" aria-label="Sign-ups and upgrades chart; scroll horizontally on small screens">${BAR_CHART}</div><footer class="cn-chart-frame__footer">Source: product analytics · Updated 2h ago</footer></section>`, 'Series 1 = brand-600, series 2 = brand-300. Gridlines gray-100, axis text 12px gray-500, round 8px swatches.'),
+        ex('Small sparkline with a Stat', `<section class="cn-chart-frame" data-size="sm" style="width:100%;max-width:320px"><header class="cn-chart-frame__header"><div><h3 class="cn-chart-frame__title">Conversion rate</h3><p class="cn-chart-frame__description">Last 30 days</p></div><div class="cn-stat" data-size="sm" data-variant="plain" data-trend="up"><div class="cn-stat__value">4.2%</div><div class="cn-stat__delta"><svg class="cn-stat__icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M8 13V3M4 7l4-4 4 4"/></svg><span>1.0 pt</span></div></div></header><div class="cn-chart-frame__body">${SPARK}</div></section>`, 'A plain Stat in the header slot instead of a legend; the line is brand-600 with a faint fill and a hollow end dot.'),
+        ex('Large, no data', `<section class="cn-chart-frame" data-size="lg" style="width:100%;max-width:560px"><header class="cn-chart-frame__header"><div><h3 class="cn-chart-frame__title">Revenue by plan</h3><p class="cn-chart-frame__description">This quarter</p></div></header><div class="cn-chart-frame__body" style="display:flex;align-items:center;justify-content:center"><div class="cn-empty-state" data-size="sm" data-variant="default"><span class="cn-featured-icon cn-empty-state__icon" data-theme="modern" data-tone="gray" data-size="lg" data-shape="square">${ICON.inbox.replace('cn-icon', 'cn-featured-icon__icon')}</span><h3 class="cn-empty-state__title">No revenue this quarter yet</h3><p class="cn-empty-state__description">Revenue appears here once the first invoice is paid.</p></div></div></section>`, 'The body hosts an EmptyState (with a modern FeaturedIcon) when there is nothing to draw.'),
+    ],
+    rules: [
+        'Series colors in order: 1 = brand-600 (bg-action), 2 = brand-300, 3 = gray-400. Semantic colors (success, warning, danger, info) only when the series means that state. Maximum 6 series.',
+        'Gridlines are gray-100 (border-subtle), axis text is 12px gray-500, no axis lines heavier than a hairline. No 3D, no gradients beyond a faint area fill, no shadows, bars with 2px radius.',
+        'The title lives in the frame header, never inside the SVG; the SVG carries only marks, axes and labels.',
+        'Every series in the legend (8px round swatches, 12px apart), every axis with units; never rely on color alone (order and labels carry the meaning).',
+        'The chart fills the body width. Reflow axes and marks for narrow screens; for a static SVG whose labels would become too small, use data-scroll on the body with a named, focusable scroll region. Keep the minimum height from size.',
+        'One chart per frame. Small multiples are several sm frames in a grid, not one frame with subplots.',
+        'No data or loading: put an EmptyState (sm) or a Skeleton in the body; keep the header so the tile does not jump.',
+        'Numbers on the chart use the same formatting as the rest of the page (locale, units).',
+    ],
+    a11y: [
+        'The SVG has role="img" and an aria-label that states the takeaway ("Upgrades grew from 12 to 21"), not just the chart name.',
+        'Offer the data as a table (a "View as table" link Button in the footer or a visually hidden table) for screen readers and copy-paste.',
+        'Tooltips on marks are enhancements; <title> elements inside the SVG give hover text without JS.',
+        'Check series contrast against the actual surface in each supported theme. Use labels, patterns or outlines when a lighter series alone does not reach 3:1.',
+    ],
+    related: ['stat', 'card', 'card-header', 'empty-state', 'skeleton', 'table'],
+};