canon-ds 0.1.0

package/lib/components/dialog.mjs

@@ -0,0 +1,140 @@
+import { FOCUS_RING, RESET_BUTTON, TRANSITION_COLORS, STATE, ex, ICON, typeStyle } from "./_shared.mjs";
+const close = `<button type="button" class="cn-dialog__close" aria-label="Close">${ICON.x}</button>`;
+const icon = (name) => `<span class="cn-dialog__icon">${ICON[name]}</span>`;
+export const dialog = {
+    name: 'Dialog',
+    slug: 'dialog',
+    category: 'overlays',
+    description: 'Modal panel centered over a scrim for one decision or one short task. Raised white surface, radius-2xl, shadow-lg; header with a required title, a scrolling body, and a subtle footer where the single primary action sits last.',
+    usage: 'Use when the user must decide or complete something before continuing: confirm a deletion, name a new search, pick between two plans. Not for details of a list item (use Drawer, which keeps the list visible), not for hints (Tooltip/Popover), and never as a container for a whole page of settings.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'The panel. role="dialog" aria-modal="true" aria-labelledby → title. data-state="open|closed". Rendered inside .cn-dialog-backdrop in the app.' },
+        { part: 'header', element: 'header', description: 'Icon (optional) + title/description on the left, close button top-right. No bottom border.' },
+        { part: 'icon', element: 'span', description: '32px circle before the title: subtle fill and muted icon by default; danger fill and icon in variant="destructive".', optional: true },
+        { part: 'title', element: 'h2', description: 'heading-md. Required. A question or a short verb phrase: "Delete this search?", "Name your shortlist".' },
+        { part: 'description', element: 'p', description: 'body-sm muted, one or two sentences with the consequence.', optional: true },
+        { part: 'close', element: 'button', description: '32px ghost icon button with an X in the top-right. aria-label="Close".', optional: true },
+        { part: 'body', element: 'div', description: 'body-md content: a field, a short form, a summary. Scrolls when the panel hits max-height.' },
+        { part: 'footer', element: 'footer', description: 'Subtle background, top hairline, right-aligned: ghost cancel first, then one primary (or danger) Button.' },
+    ],
+    props: {
+        size: {
+            values: ['sm', 'md', 'lg', 'xl'],
+            default: 'md',
+            description: 'Max width of the panel. sm = 400px for a yes/no confirmation; md = 520px for one field or a short form (default); lg = 640px for a form with several fields; xl = 800px for a two-column layout or a preview. Pick two sizes per app and stick to them.',
+        },
+        variant: {
+            values: ['default', 'destructive'],
+            default: 'default',
+            description: 'default = neutral header icon (or none); destructive = the header icon turns danger (red circle) and the footer’s primary action is a danger Button. Use only for irreversible actions.',
+        },
+    },
+    states: {
+        open: STATE.open(),
+        closed: { selector: '[data-state="closed"]', description: 'Hidden (display none). The backdrop is removed at the same time.', markup: 'data-state="closed"' },
+        closeHover: { selector: ' .cn-dialog__close:hover', description: 'Pointer over the close button: subtle fill. Styled in extraCss because it lives on a child.', markup: 'native :hover on .cn-dialog__close' },
+        closeFocus: { selector: ' .cn-dialog__close:focus-visible', description: 'Keyboard focus on the close button shows the focus ring. Styled in extraCss.', markup: 'native :focus-visible on .cn-dialog__close' },
+    },
+    base: {
+        root: {
+            display: 'flex',
+            'flex-direction': 'column',
+            width: '100%',
+            'max-width': '520px',
+            'max-height': 'calc(100vh - {space.16})',
+            'background-color': '{color.bg-surface-raised}',
+            border: '{border.width.thin} solid {color.border-default}',
+            'border-radius': '{radius.2xl}',
+            'box-shadow': '{shadow.lg}',
+            color: '{color.fg-default}',
+            overflow: 'hidden',
+            ...typeStyle('body-md'),
+        },
+        header: { display: 'flex', 'align-items': 'flex-start', 'justify-content': 'space-between', gap: '{space.4}', padding: '{space.6} {space.6} 0' },
+        icon: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            width: '{size.icon.2xl}',
+            height: '{size.icon.2xl}',
+            'border-radius': '{radius.full}',
+            'background-color': '{color.bg-subtle}',
+            color: '{color.fg-muted}',
+        },
+        title: { ...typeStyle('heading-md'), color: '{color.fg-default}' },
+        description: { ...typeStyle('body-sm'), color: '{color.fg-muted}', 'margin-top': '{space.1}' },
+        close: {
+            ...RESET_BUTTON,
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            width: '{size.icon.2xl}',
+            height: '{size.icon.2xl}',
+            'margin-block': 'calc({space.1} * -1)',
+            'margin-inline-end': 'calc({space.2} * -1)',
+            'border-radius': '{radius.md}',
+            color: '{color.fg-subtle}',
+            ...TRANSITION_COLORS,
+        },
+        body: { flex: '1 1 auto', 'min-height': '0', overflow: 'auto', padding: '{space.6}', ...typeStyle('body-md') },
+        footer: {
+            display: 'flex',
+            'align-items': 'center',
+            'justify-content': 'flex-end',
+            gap: '{space.2}',
+            padding: '{space.4} {space.6}',
+            'border-top': '{border.width.thin} solid {color.border-subtle}',
+            'background-color': '{color.bg-subtle}',
+        },
+        '@states': {
+            open: { root: { animation: 'cn-dialog-enter {motion.duration.slow} {motion.easing.out} both' } },
+            closed: { root: { display: 'none' } },
+        },
+    },
+    variants: {
+        size: {
+            sm: { root: { 'max-width': '400px' } },
+            md: { root: { 'max-width': '520px' } },
+            lg: { root: { 'max-width': '640px' } },
+            xl: { root: { 'max-width': '800px' } },
+        },
+        variant: {
+            default: { root: {} },
+            destructive: { icon: { 'background-color': '{color.bg-danger-subtle}', color: '{color.fg-danger}' } },
+        },
+    },
+    extraCss: `
+.cn-dialog-backdrop { position: fixed; inset: 0; background: {color.bg-overlay}; display: grid; place-items: center; padding: {space.6}; z-index: {z.modal}; }
+.cn-dialog[data-state="closed"] { display: none; }
+@keyframes cn-dialog-enter { from { opacity: 0; transform: scale(0.98); } to { opacity: 1; transform: scale(1); } }
+.cn-dialog .cn-dialog__icon .cn-icon { width: {size.icon.md}; height: {size.icon.md}; }
+.cn-dialog .cn-dialog__close .cn-icon { width: {size.icon.md}; height: {size.icon.md}; }
+.cn-dialog .cn-dialog__close:hover { background-color: {color.bg-subtle}; color: {color.fg-default}; }
+.cn-dialog .cn-dialog__close:focus-visible { outline: none; box-shadow: ${FOCUS_RING['box-shadow']}; }`,
+    examples: [
+        ex('Default (md)', `<div class="cn-dialog" data-size="md" data-variant="default" data-state="open" role="dialog" aria-modal="true" aria-labelledby="dlg-name-title"><header class="cn-dialog__header"><div><h2 class="cn-dialog__title" id="dlg-name-title">Name your shortlist</h2><p class="cn-dialog__description">You can rename it later from the list header.</p></div>${close}</header><div class="cn-dialog__body"><div class="cn-input" data-variant="default" data-size="md"><input class="cn-input__field" type="text" value="Japan · frozen seafood · Q4" aria-label="Shortlist name"></div></div><footer class="cn-dialog__footer"><button type="button" class="cn-button" data-variant="ghost" data-size="md"><span class="cn-button__label">Cancel</span></button><button type="button" class="cn-button" data-variant="primary" data-size="md"><span class="cn-button__label">Create shortlist</span></button></footer></div>`),
+        ex('Destructive (sm)', `<div class="cn-dialog" data-size="sm" data-variant="destructive" data-state="open" role="dialog" aria-modal="true" aria-labelledby="dlg-delete-title"><header class="cn-dialog__header"><div style="display:flex;gap:var(--cn-space-3);align-items:flex-start">${icon('trash')}<div><h2 class="cn-dialog__title" id="dlg-delete-title">Delete this search?</h2><p class="cn-dialog__description">“Germany · industrial pumps” and its 38 prospects will be removed. This cannot be undone.</p></div></div>${close}</header><footer class="cn-dialog__footer"><button type="button" class="cn-button" data-variant="ghost" data-size="md"><span class="cn-button__label">Cancel</span></button><button type="button" class="cn-button" data-variant="danger" data-size="md"><span class="cn-button__label">Delete search</span></button></footer></div>`, 'The only dialog that ends with a danger Button. Cancel stays first and ghost.'),
+        ex('With header icon (md)', `<div class="cn-dialog" data-size="md" data-variant="default" data-state="open" role="dialog" aria-modal="true" aria-labelledby="dlg-pause-title"><header class="cn-dialog__header"><div style="display:flex;gap:var(--cn-space-3);align-items:flex-start">${icon('calendar')}<div><h2 class="cn-dialog__title" id="dlg-pause-title">Pause outreach until Monday?</h2><p class="cn-dialog__description">Drafts stay ready; nothing is sent until 08:00 on 15 Sep in each buyer’s timezone.</p></div></div>${close}</header><footer class="cn-dialog__footer"><button type="button" class="cn-button" data-variant="ghost" data-size="md"><span class="cn-button__label">Keep sending</span></button><button type="button" class="cn-button" data-variant="primary" data-size="md"><span class="cn-button__label">Pause until Monday</span></button></footer></div>`),
+        ex('Large with scrolling body (lg)', `<div class="cn-dialog" data-size="lg" data-variant="default" data-state="open" role="dialog" aria-modal="true" aria-labelledby="dlg-plan-title" style="max-height:360px"><header class="cn-dialog__header"><div><h2 class="cn-dialog__title" id="dlg-plan-title">Review the outreach plan</h2><p class="cn-dialog__description">12 companies · 3 waves · first wave tomorrow 09:00 JST</p></div>${close}</header><div class="cn-dialog__body"><p>Wave 1 (4 companies): Nakamura Trading Co., Hoffmann GmbH, Lagos Fresh Ltd., Marisco del Sur.</p><p style="margin-top:var(--cn-space-3)">Wave 2 (4 companies): Busan Cold Chain, Norsk Havfisk AS, Valencia Congelados, Pacific Reef Foods.</p><p style="margin-top:var(--cn-space-3)">Wave 3 (4 companies): Tokyo Maruha, Baltic Seafood OÜ, Dalian Ocean Trade, Cape Fisheries.</p><p style="margin-top:var(--cn-space-3)">Each company receives one email and one follow-up after 4 business days. Replies are drafted by the agent and wait for your approval.</p></div><footer class="cn-dialog__footer"><button type="button" class="cn-button" data-variant="ghost" data-size="md"><span class="cn-button__label">Back</span></button><button type="button" class="cn-button" data-variant="primary" data-size="md"><span class="cn-button__label">Start outreach</span></button></footer></div>`, 'max-height is inline here only to show the body scrolling; in the app it comes from calc(100vh - 64px).'),
+    ],
+    rules: [
+        'A title is required and is the accessible name. Write it as the question being answered or the task being done.',
+        'Exactly one primary action, last in the footer. Cancel (or the escape hatch) comes first as a ghost Button, labelled with what it does ("Keep sending"), not "Cancel" when a better verb exists.',
+        'variant="destructive": header icon in danger colors and the primary becomes a danger Button. Never two filled buttons.',
+        'Render the panel inside .cn-dialog-backdrop (fixed, scrim, centered, z modal). The panel itself is never position: fixed.',
+        'Escape and the backdrop click close the dialog unless the body has unsaved input; then ask.',
+        'Pick at most two sizes per app (typically sm for confirmations and md for forms). xl is for previews only.',
+        'The body scrolls; header and footer stay put. Never let the whole panel exceed the viewport.',
+        'Do not stack dialogs. A dialog that needs another step becomes a stepper inside the same dialog or a full page.',
+        'Enter: scale 0.98 → 1 with fade, 260ms; the scrim fades in at the same time.',
+    ],
+    a11y: [
+        'role="dialog" aria-modal="true" aria-labelledby pointing to the title (and aria-describedby to the description when present).',
+        'Focus is trapped inside while open; on open it goes to the first control (or the cancel button for destructive dialogs) and returns to the trigger on close.',
+        'Escape closes. The close button has aria-label="Close" and is the last element in the header.',
+        'Everything behind the dialog gets inert (or aria-hidden) while it is open; body scroll is locked.',
+    ],
+    related: ['drawer', 'popover', 'alert', 'button', 'input'],
+};

package/lib/components/divider.mjs

@@ -0,0 +1,115 @@
+import { ex, typeStyle } from "./_shared.mjs";
+// the reference content dividers: a 1px gray-200 rule, optionally carrying text (14px medium
+// gray-600), a heading, a button or a button group in the middle, at the start or at the end;
+// single line, dual line (rules above and below the content) or a gray-50 fill band.
+const HAIRLINE = '{border.width.thin} solid {color.border-default}';
+const SPACING = { none: '0', sm: '{space.2}', md: '{space.4}', lg: '{space.8}' };
+const btn = (label, variant = 'outline', icon = '') => `<button type="button" class="cn-button" data-variant="${variant}" data-size="sm">${icon}<span class="cn-button__label">${label}</span></button>`;
+const PLUS = '<svg class="cn-button__icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" aria-hidden="true"><path d="M8 3v10M3 8h10"/></svg>';
+const para = (text) => `<p class="cn-text-body-md" style="color:var(--cn-color-fg-muted);margin:0">${text}</p>`;
+const sep = (o) => `<div class="cn-divider" data-orientation="${o.orientation ?? 'horizontal'}" data-variant="${o.variant ?? 'single'}" data-spacing="${o.spacing ?? 'md'}" data-label="${o.label ?? 'center'}" role="separator"><span class="cn-divider__content">${o.inner}</span></div>`;
+export const divider = {
+    name: 'Divider',
+    slug: 'divider',
+    category: 'layout',
+    description: 'A 1px gray-200 hairline that separates. Horizontal between blocks, vertical between inline controls, or the reference content divider carrying text, a heading, a button or a button group on the line, between two lines, or on a gray-50 band.',
+    usage: 'Between sections of a card or form, between groups in a toolbar or menu, to label a break ("Earlier", "Or continue with") or to place an action between two blocks ("Add step"). Not between every list row or table row (those components draw their own rules), and never as decoration.',
+    anatomy: [
+        { part: 'root', element: 'hr', description: 'An <hr> for a plain horizontal rule. A <div role="separator"> when vertical or when it carries content (add data-label="center|start|end").' },
+        { part: 'content', element: 'span', description: 'Optional slot on the line: text, a heading, a Button or a ButtonGroup. Centered, or at the start / end with data-label.', optional: true },
+        { part: 'label', element: 'span', description: 'Plain text inside the content slot: 14px medium fg-muted ("Earlier", "Or"). A heading uses a real h-tag with the heading-xs class instead.', optional: true },
+    ],
+    props: {
+        orientation: {
+            values: ['horizontal', 'vertical'],
+            default: 'horizontal',
+            description: 'horizontal = full-width rule between stacked blocks; vertical = 1px column that stretches to the height of a flex row (toolbars, inline meta).',
+        },
+        variant: {
+            values: ['single', 'dual', 'fill'],
+            default: 'single',
+            description: 'single = one hairline, with the content sitting on it (the default). dual = a hairline above and below the content row (44px with text, 56 with buttons), for section breaks that carry an action. fill = a gray-50 band (36 / 52px) holding the content, for sticky sub-headers and grouped feeds.',
+        },
+        spacing: {
+            values: ['none', 'sm', 'md', 'lg'],
+            default: 'md',
+            description: 'Margin around the rule: none 0 (inside components that manage their own spacing), sm 8px (toolbars, dense cards), md 16px (default inside cards and forms), lg 32px (between page sections). Applies as margin-block when horizontal and margin-inline when vertical.',
+        },
+    },
+    states: {},
+    base: {
+        root: {
+            border: '0',
+            'border-top': HAIRLINE,
+            width: '100%',
+            height: '0',
+            margin: '0',
+            'flex-shrink': '0',
+            color: '{color.fg-muted}',
+        },
+        content: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            gap: '{space.2}',
+            'padding-inline': '{space.3}',
+            'white-space': 'nowrap',
+        },
+        label: {
+            ...typeStyle('label-sm'),
+            color: '{color.fg-muted}',
+            'white-space': 'nowrap',
+        },
+    },
+    variants: {
+        orientation: {
+            horizontal: { root: { width: '100%', height: '0', 'border-top': HAIRLINE, 'border-inline-start': '0' } },
+            vertical: { root: { width: '0', height: 'auto', 'min-height': '{space.4}', 'align-self': 'stretch', 'border-top': '0', 'border-inline-start': HAIRLINE } },
+        },
+        variant: {
+            single: { root: {} },
+            dual: { root: {} },
+            fill: { root: {} },
+        },
+        spacing: Object.fromEntries(Object.entries(SPACING).map(([k, v]) => [k, { root: { 'margin-block': v } }])),
+    },
+    compound: Object.entries(SPACING).map(([k, v]) => ({ when: { orientation: 'vertical', spacing: k }, block: { root: { 'margin-block': '0', 'margin-inline': v } } })),
+    extraCss: `
+.cn-divider[data-label] { display: flex; align-items: center; width: 100%; border: 0; height: auto; }
+.cn-divider[data-label]::before, .cn-divider[data-label]::after { content: ""; flex: 1 1 auto; height: 0; border-top: ${HAIRLINE}; }
+.cn-divider[data-label="start"]::before { flex: 0 0 {space.4}; }
+.cn-divider[data-label="end"]::after { flex: 0 0 {space.4}; }
+.cn-divider[data-label][data-variant="dual"] { border-top: ${HAIRLINE}; border-bottom: ${HAIRLINE}; padding-block: {space.3}; }
+.cn-divider[data-label][data-variant="dual"]::before, .cn-divider[data-label][data-variant="dual"]::after { border-top: 0; }
+.cn-divider[data-label][data-variant="fill"] { background-color: {color.bg-subtle}; padding: {space.2} {space.1}; border-radius: {radius.md}; }
+.cn-divider[data-label][data-variant="fill"]::before, .cn-divider[data-label][data-variant="fill"]::after { border-top: 0; }
+.cn-divider[data-label="start"][data-variant="dual"]::before, .cn-divider[data-label="start"][data-variant="fill"]::before { flex: 0 0 0; }
+.cn-divider[data-label="end"][data-variant="dual"]::after, .cn-divider[data-label="end"][data-variant="fill"]::after { flex: 0 0 0; }
+.cn-divider__content > .cn-text-heading-xs { color: {color.fg-default}; }`,
+    examples: [
+        ex('Horizontal (default)', `<div style="width:100%;max-width:480px">${para('Lumen keeps every project, task and file in one workspace your team can search.')}<hr class="cn-divider" data-orientation="horizontal" data-variant="single" data-spacing="md">${para('Invite teammates, set roles and connect the tools you already use.')}</div>`, 'A plain <hr>: 1px gray-200 with 16px above and below.'),
+        ex('With text', `<div style="width:100%;max-width:480px">${para('Sofia Almeida commented · 08:31')}${sep({ inner: '<span class="cn-divider__label">Earlier</span>' })}${para('Daniel Costa opened the pull request · Sep 9')}</div>`, '14px medium gray-600 text on the line, 12px of air each side. Use for time breaks and "or" separators.'),
+        ex('Heading at the start, button at the end', `<div style="width:100%;max-width:560px">${sep({ label: 'start', spacing: 'sm', inner: '<h3 class="cn-text-heading-xs">Shipping details</h3>' })}${para('FOB Santos · 24 t · 1 × 40\' reefer')}${sep({ label: 'end', spacing: 'md', inner: btn('Add step', 'outline', PLUS) })}</div>`, 'data-label="start" / "end" keep a 16px stub of line before or after the content.'),
+        ex('Button and button group in the middle', `<div style="width:100%;max-width:560px;display:flex;flex-direction:column;gap:var(--cn-space-4)">${sep({ spacing: 'none', inner: btn('Add step', 'outline', PLUS) })}${sep({ spacing: 'none', inner: `<div class="cn-button-group" data-variant="attached" data-orientation="horizontal" role="group" aria-label="Insert">${btn('Text', 'outline')}${btn('Image', 'outline')}${btn('Embed', 'outline')}</div>` })}</div>`, 'An action between two blocks: one outline Button, or a ButtonGroup.'),
+        ex('Dual line and fill', `<div style="width:100%;max-width:560px;display:flex;flex-direction:column;gap:var(--cn-space-6)">${sep({ variant: 'dual', spacing: 'none', inner: '<span class="cn-divider__label">Today</span>' })}${sep({ variant: 'dual', spacing: 'none', label: 'end', inner: btn('Show 12 earlier events', 'ghost') })}${sep({ variant: 'fill', spacing: 'none', label: 'start', inner: '<span class="cn-divider__label">Yesterday</span>' })}</div>`, 'dual = rules above and below the content row; fill = a gray-50 band (radius 6) holding it.'),
+        ex('Vertical in a toolbar', `<div style="display:flex;flex-wrap:wrap;align-items:center;gap:var(--cn-space-1)">${btn('Approve', 'primary')}${btn('Edit', 'ghost')}<div class="cn-divider" data-orientation="vertical" data-variant="single" data-spacing="sm" role="separator" aria-orientation="vertical"></div>${btn('Snooze', 'ghost')}${btn('Discard', 'ghost')}</div>`, 'Stretches to the row height; margin-inline from spacing.'),
+        ex('Large spacing between sections', `<div style="width:100%;max-width:480px"><h3 class="cn-text-heading-sm">Company</h3>${para('Lumen · Lisbon, Portugal')}<hr class="cn-divider" data-orientation="horizontal" data-variant="single" data-spacing="lg"><h3 class="cn-text-heading-sm">Contacts</h3>${para('Maya Chen · Product Manager')}</div>`),
+    ],
+    rules: [
+        'A divider separates two things that are both present; never end a block with one and never stack two.',
+        'Do not add dividers between rows of List, Table, DescriptionList or Accordion; they draw their own rules.',
+        'Spacing is a prop, never an ad-hoc margin: sm in toolbars and dense cards, md inside cards and forms, lg between page sections, none inside components that already space their children.',
+        'Prefer whitespace over a divider when the two blocks already differ in type (a heading followed by a paragraph needs no rule).',
+        'Text on the line is 14px medium muted, 1–3 words ("Earlier", "Or", "Today"); a heading on the line is a real h-tag in heading-xs; a labeled divider is not a section title on its own.',
+        'One action on a divider at most: an outline or ghost sm Button, or one ButtonGroup; never a primary button.',
+        'single by default; dual only when the divider carries an action between two long blocks; fill for sticky date bands in feeds.',
+        'Vertical dividers only between inline controls or meta of the same height; never taller than the row.',
+        'Always gray-200; never a stronger color, never thicker than 1px, never dashed (dashed is reserved for drop zones).',
+    ],
+    a11y: [
+        'A plain horizontal rule is an <hr> (implicit role separator). A labeled or vertical one is a <div role="separator">; add aria-orientation="vertical" when vertical.',
+        'The label is read as text; keep it meaningful on its own ("Earlier" is fine, "———" is not).',
+        'A button or button group on the divider is focusable in the normal order; the separator role does not hide it.',
+        'Decorative dividers inside a component that already conveys grouping may use aria-hidden="true" to reduce noise.',
+    ],
+    related: ['card', 'button', 'button-group', 'list', 'accordion', 'timeline'],
+};

package/lib/components/drawer.mjs

@@ -0,0 +1,150 @@
+import { FOCUS_RING, RESET_BUTTON, TRANSITION_COLORS, STATE, ex, ICON, typeStyle } from "./_shared.mjs";
+const close = `<button type="button" class="cn-drawer__close" aria-label="Close">${ICON.x}</button>`;
+export const drawer = {
+    name: 'Drawer',
+    slug: 'drawer',
+    category: 'overlays',
+    description: 'Side panel that slides in over the page for the detail of one item while the list stays visible behind the scrim. Raised surface, a hairline on the inner edge, shadow-lg; sticky header and footer with a scrolling body.',
+    usage: 'Use for the detail of a list or table row (a prospect, a conversation, an agent run), for editing one record, and for filters on mobile. Not for confirmations (use Dialog) and never as a replacement for a page: if the content has its own navigation, it is a page.',
+    anatomy: [
+        { part: 'root', element: 'aside', description: 'The panel. role="dialog" aria-modal="true" aria-labelledby → title. data-state="open|closed", data-side, data-size. Rendered inside .cn-drawer-backdrop in the app; in the gallery it is shown bounded with an inline height.' },
+        { part: 'header', element: 'header', description: 'Title/description on the left, close button on the right. Bottom hairline. Does not scroll.' },
+        { part: 'title', element: 'h2', description: 'heading-md. Names the item ("Nakamura Trading Co.") or the task ("Edit agent").' },
+        { part: 'description', element: 'p', description: 'body-sm muted, one line of context under the title.', optional: true },
+        { part: 'close', element: 'button', description: '32px ghost icon button with an X in the header. aria-label="Close".' },
+        { part: 'body', element: 'div', description: 'The scrolling area. Padding space-6; content is sections, description lists, a timeline, a form.' },
+        { part: 'footer', element: 'footer', description: 'Subtle background, top hairline, right-aligned actions: ghost first, one primary last. Only when the drawer edits something.', optional: true },
+    ],
+    props: {
+        side: {
+            values: ['right', 'left', 'bottom'],
+            default: 'right',
+            description: 'Edge the drawer slides in from. right = detail of a list item (default, the Vera pattern); left = navigation or filters; bottom = a sheet on mobile: full width, 80vh tall, rounded top corners.',
+        },
+        size: {
+            values: ['sm', 'md', 'lg'],
+            default: 'md',
+            description: 'Width for right/left drawers. sm = 360px for a short detail or filters; md = 480px for the detail of a record (default); lg = 640px for a conversation or an editor. Ignored for side="bottom".',
+        },
+    },
+    states: {
+        open: STATE.open(),
+        closed: { selector: '[data-state="closed"]', description: 'Hidden (display none); the backdrop is removed at the same time.', markup: 'data-state="closed"' },
+        closeHover: { selector: ' .cn-drawer__close:hover', description: 'Pointer over the close button: subtle fill. Styled in extraCss because it lives on a child.', markup: 'native :hover on .cn-drawer__close' },
+        closeFocus: { selector: ' .cn-drawer__close:focus-visible', description: 'Keyboard focus on the close button shows the focus ring. Styled in extraCss.', markup: 'native :focus-visible on .cn-drawer__close' },
+    },
+    base: {
+        root: {
+            display: 'flex',
+            'flex-direction': 'column',
+            width: '480px',
+            'max-width': '100vw',
+            height: '100%',
+            'background-color': '{color.bg-surface-raised}',
+            'border-inline-start': '{border.width.thin} solid {color.border-default}',
+            'box-shadow': '{shadow.lg}',
+            color: '{color.fg-default}',
+            overflow: 'hidden',
+            ...typeStyle('body-md'),
+        },
+        header: {
+            display: 'flex',
+            'align-items': 'flex-start',
+            'justify-content': 'space-between',
+            gap: '{space.4}',
+            padding: '{space.5} {space.6}',
+            'border-bottom': '{border.width.thin} solid {color.border-subtle}',
+            'flex-shrink': '0',
+        },
+        title: { ...typeStyle('heading-md'), color: '{color.fg-default}' },
+        description: { ...typeStyle('body-sm'), color: '{color.fg-muted}', 'margin-top': '{space.1}' },
+        close: {
+            ...RESET_BUTTON,
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            width: '{size.icon.2xl}',
+            height: '{size.icon.2xl}',
+            'margin-block': 'calc({space.1} * -1)',
+            'margin-inline-end': 'calc({space.2} * -1)',
+            'border-radius': '{radius.md}',
+            color: '{color.fg-subtle}',
+            ...TRANSITION_COLORS,
+        },
+        body: { flex: '1 1 auto', 'min-height': '0', overflow: 'auto', padding: '{space.6}' },
+        footer: {
+            display: 'flex',
+            'flex-wrap': 'wrap',
+            'align-items': 'center',
+            'justify-content': 'flex-end',
+            gap: '{space.2}',
+            padding: '{space.4} {space.6}',
+            'border-top': '{border.width.thin} solid {color.border-subtle}',
+            'background-color': '{color.bg-subtle}',
+            'flex-shrink': '0',
+        },
+        '@states': {
+            closed: { root: { display: 'none' } },
+        },
+    },
+    variants: {
+        side: {
+            right: {
+                root: {},
+                '@states': { open: { root: { animation: 'cn-drawer-in-right {motion.duration.slow} {motion.easing.out} both' } } },
+            },
+            left: {
+                root: { 'border-inline-start': '0', 'border-inline-end': '{border.width.thin} solid {color.border-default}' },
+                '@states': { open: { root: { animation: 'cn-drawer-in-left {motion.duration.slow} {motion.easing.out} both' } } },
+            },
+            bottom: {
+                root: { width: '100%', 'max-width': '100vw', height: '80vh', 'border-inline-start': '0', 'border-top': '{border.width.thin} solid {color.border-default}', 'border-radius': '{radius.2xl} {radius.2xl} 0 0' },
+                '@states': { open: { root: { animation: 'cn-drawer-in-bottom {motion.duration.slow} {motion.easing.out} both' } } },
+            },
+        },
+        size: {
+            sm: { root: { width: '360px' } },
+            md: { root: { width: '480px' } },
+            lg: { root: { width: '640px' } },
+        },
+    },
+    compound: [
+        { when: { side: 'bottom', size: 'sm' }, block: { root: { width: '100%' } } },
+        { when: { side: 'bottom', size: 'md' }, block: { root: { width: '100%' } } },
+        { when: { side: 'bottom', size: 'lg' }, block: { root: { width: '100%' } } },
+    ],
+    extraCss: `
+.cn-drawer-backdrop { position: fixed; inset: 0; background: {color.bg-overlay}; z-index: {z.modal}; display: flex; justify-content: flex-end; align-items: stretch; }
+.cn-drawer-backdrop[data-side="left"] { justify-content: flex-start; }
+.cn-drawer-backdrop[data-side="bottom"] { flex-direction: column; justify-content: flex-end; }
+@keyframes cn-drawer-in-right { from { opacity: 0; transform: translateX(16px); } to { opacity: 1; transform: translateX(0); } }
+@keyframes cn-drawer-in-left { from { opacity: 0; transform: translateX(-16px); } to { opacity: 1; transform: translateX(0); } }
+@keyframes cn-drawer-in-bottom { from { opacity: 0; transform: translateY(16px); } to { opacity: 1; transform: translateY(0); } }
+.cn-drawer .cn-drawer__close .cn-icon { width: {size.icon.md}; height: {size.icon.md}; }
+.cn-drawer .cn-drawer__close:hover { background-color: {color.bg-subtle}; color: {color.fg-default}; }
+.cn-drawer .cn-drawer__close:focus-visible { outline: none; box-shadow: ${FOCUS_RING['box-shadow']}; }`,
+    examples: [
+        ex('Right, md (item detail)', `<aside class="cn-drawer" data-side="right" data-size="md" data-state="open" role="dialog" aria-modal="true" aria-labelledby="drw-nakamura" style="height:420px"><header class="cn-drawer__header"><div><h2 class="cn-drawer__title" id="drw-nakamura">Nakamura Trading Co.</h2><p class="cn-drawer__description">Osaka, Japan · Importer of frozen seafood · <span class="cn-badge" data-tone="success" data-variant="soft" data-size="sm">Verified</span></p></div>${close}</header><div class="cn-drawer__body"><p><strong>Why it fits</strong><br>Imports 1,200 t/year of frozen shrimp from Ecuador and Vietnam; two decision makers found; replied to a similar offer in 2025.</p><p style="margin-top:var(--cn-space-4)"><strong>Last activity</strong><br>Email opened 3 days ago · No reply yet · Follow-up scheduled for Tuesday 09:00 JST.</p><p style="margin-top:var(--cn-space-4)"><strong>Contacts</strong><br>Kenji Nakamura, Purchasing Director · Aiko Sato, Import Coordinator.</p></div><footer class="cn-drawer__footer"><button type="button" class="cn-button" data-variant="ghost" data-size="md"><span class="cn-button__label">Archive</span></button><button type="button" class="cn-button" data-variant="primary" data-size="md"><span class="cn-button__label">Send follow-up now</span></button></footer></aside>`, 'height:420px is inline only so the gallery shows the bounded panel; in the app it fills the backdrop.'),
+        ex('Left, sm (filters)', `<aside class="cn-drawer" data-side="left" data-size="sm" data-state="open" role="dialog" aria-modal="true" aria-labelledby="drw-filters" style="height:360px"><header class="cn-drawer__header"><div><h2 class="cn-drawer__title" id="drw-filters">Filters</h2><p class="cn-drawer__description">38 of 214 prospects match</p></div>${close}</header><div class="cn-drawer__body"><div class="cn-input" data-variant="default" data-size="sm">${ICON.search.replace('cn-icon', 'cn-input__icon')}<input class="cn-input__field" type="search" placeholder="Country or product…" aria-label="Filter prospects"></div><p style="margin-top:var(--cn-space-4);color:var(--cn-color-fg-muted)">Japan · South Korea · Frozen seafood · Replied</p></div><footer class="cn-drawer__footer"><button type="button" class="cn-button" data-variant="ghost" data-size="md"><span class="cn-button__label">Clear all</span></button><button type="button" class="cn-button" data-variant="primary" data-size="md"><span class="cn-button__label">Show 38</span></button></footer></aside>`),
+        ex('Bottom sheet (mobile)', `<div style="width:100%;max-width:420px"><aside class="cn-drawer" data-side="bottom" data-size="md" data-state="open" role="dialog" aria-modal="true" aria-labelledby="drw-sheet" style="height:300px"><header class="cn-drawer__header"><div><h2 class="cn-drawer__title" id="drw-sheet">Approve this reply?</h2><p class="cn-drawer__description">Drafted by the agent 2 minutes ago</p></div>${close}</header><div class="cn-drawer__body">“Thank you for your interest, Nakamura-san. We can supply 40 t of frozen shrimp per month from October, CIF Osaka. Would a call on Thursday suit you?”</div><footer class="cn-drawer__footer"><button type="button" class="cn-button" data-variant="ghost" data-size="md"><span class="cn-button__label">Edit</span></button><button type="button" class="cn-button" data-variant="primary" data-size="md"><span class="cn-button__label">Approve and send</span></button></footer></aside></div>`, 'Bottom drawers are full width, 80vh tall, with rounded top corners. The wrapper is inline here only to bound the example.'),
+        ex('Large, read-only (no footer)', `<aside class="cn-drawer" data-side="right" data-size="lg" data-state="open" role="dialog" aria-modal="true" aria-labelledby="drw-run" style="height:360px"><header class="cn-drawer__header"><div><h2 class="cn-drawer__title" id="drw-run">Agent run · 11 Sep, 09:14</h2><p class="cn-drawer__description">Prospecting · Japan · frozen seafood · 4 min 12 s</p></div>${close}</header><div class="cn-drawer__body"><p>Read 3 replies from Nakamura, Hoffmann and Lagos Fresh. Drafted 3 answers. Flagged Hoffmann as “asks for a price list” — waiting for your file.</p><p style="margin-top:var(--cn-space-4)">Searched 212 companies, verified 38, discarded 174 (no trade data or wrong product).</p></div></aside>`),
+    ],
+    rules: [
+        'The detail of a list item opens in a drawer, never in a new page. The list stays visible behind the scrim so the user keeps their place.',
+        'One level deep only: a drawer never opens another drawer. A link inside a drawer that needs more space closes it and navigates.',
+        'Render the panel inside .cn-drawer-backdrop with the same data-side; the panel itself is never position: fixed.',
+        'Header is sticky and carries the item name; the body scrolls; the footer appears only when the drawer edits something (ghost first, one primary last).',
+        'Width comes from size; never set it inline. Below 640px every drawer becomes full width (right/left) or a bottom sheet.',
+        'Close on Escape, on the close button and on scrim click, unless the body has unsaved edits; then ask.',
+        'Deep-link the open drawer (?prospect=123) so refresh and share keep it open.',
+        'Enter: 16px slide from its side with fade, 260ms; leave is the reverse at 180ms.',
+    ],
+    a11y: [
+        'role="dialog" aria-modal="true" with aria-labelledby on the title.',
+        'Focus moves to the close button (read-only drawers) or the first field (edit drawers) on open, and returns to the row that opened it on close.',
+        'Focus is trapped inside while open; the page behind is inert.',
+        'The close button has aria-label="Close"; Escape closes.',
+    ],
+    related: ['dialog', 'popover', 'card', 'button', 'badge'],
+};

package/lib/components/empty-state.mjs

@@ -0,0 +1,112 @@
+import { ex, ICON, typeStyle } from "./_shared.mjs";
+// the reference empty state: a 512px centered column; a 48px modern gray featured icon (56 at lg)
+// or an illustration in the header (16 / 20 / 20px below); content max 352px with a 16 / 18 / 20px
+// semibold title and 14 / 14 / 16px gray-600 text (4 / 8 / 8px apart, 24 / 32 / 32px above the
+// footer); actions 12px apart; optional search field and background pattern.
+const HAIRLINE = '{border.width.thin} solid {color.border-default}';
+const ring = (color) => `inset 0 0 0 1px ${color}`;
+const button = (label, variant, size = 'md', icon = '') => `<button type="button" class="cn-button" data-variant="${variant}" data-size="${size}">${icon ? icon.replace('cn-icon', 'cn-button__icon') : ''}<span class="cn-button__label">${label}</span></button>`;
+const featured = (i, size = 'lg') => `<span class="cn-featured-icon cn-empty-state__icon" data-theme="modern" data-tone="gray" data-size="${size}" data-shape="square">${ICON[i].replace('cn-icon', 'cn-featured-icon__icon')}</span>`;
+/** A quiet inline illustration (a stack of documents) drawn with token variables. */
+const ILLUSTRATION = `<svg class="cn-empty-state__illustration" viewBox="0 0 152 120" aria-hidden="true"><ellipse cx="76" cy="108" rx="60" ry="6" fill="var(--cn-color-bg-muted)"/><rect x="38" y="30" width="76" height="74" rx="8" fill="var(--cn-color-bg-surface)" stroke="var(--cn-color-border-control)" stroke-width="1.5"/><rect x="46" y="22" width="76" height="74" rx="8" fill="var(--cn-color-bg-surface)" stroke="var(--cn-color-border-control)" stroke-width="1.5"/><rect x="54" y="14" width="76" height="74" rx="8" fill="var(--cn-color-bg-surface)" stroke="var(--cn-color-border-control)" stroke-width="1.5"/><rect x="66" y="30" width="36" height="6" rx="3" fill="var(--cn-color-bg-muted)"/><rect x="66" y="44" width="52" height="6" rx="3" fill="var(--cn-color-bg-subtle)"/><rect x="66" y="58" width="44" height="6" rx="3" fill="var(--cn-color-bg-subtle)"/><circle cx="110" cy="80" r="14" fill="var(--cn-color-bg-action-subtle)" stroke="var(--cn-color-bg-action)" stroke-width="1.5"/><path d="M104.5 80.5l3.5 3.5 7-7.5" fill="none" stroke="var(--cn-color-bg-action)" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"/></svg>`;
+const SEARCH = `<div class="cn-empty-state__search cn-input" data-variant="default" data-size="md">${ICON.search.replace('cn-icon', 'cn-input__icon')}<input class="cn-input__field" type="search" placeholder="Search" aria-label="Search" value="Osaka"></div>`;
+const state = (o) => `<div class="cn-empty-state" data-size="${o.size ?? 'md'}" data-variant="${o.variant ?? 'default'}"${o.style ? ` style="${o.style}"` : ''}>${o.header ? `<div class="cn-empty-state__header">${o.header}</div>` : ''}<h3 class="cn-empty-state__title">${o.title}</h3>${o.description ? `<p class="cn-empty-state__description">${o.description}</p>` : ''}${o.search ?? ''}${o.actions ? `<div class="cn-empty-state__actions">${o.actions}</div>` : ''}</div>`;
+export const emptyState = {
+    name: 'EmptyState',
+    slug: 'empty-state',
+    category: 'feedback',
+    description: 'What a region shows when it has nothing to show, in the reference layout: a modern gray featured icon (or a quiet illustration) above a short semibold title, one sentence of help capped at 352px and the actions that fill it. Centered, narrow, calm.',
+    usage: 'Empty collections (no projects yet), empty filters and searches (no results), empty slots (no file uploaded) and drop zones. Not for errors (Alert) and not for loading (Skeleton).',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'Centered column, max width 512px, padding from size. Plain, card or dashed frame.' },
+        { part: 'header', element: 'div', description: 'Optional wrapper for the featured icon or illustration, 16 / 20 / 20px above the title (24 with an illustration).', optional: true },
+        { part: 'icon', element: 'span', description: 'A FeaturedIcon (theme modern, tone gray, 48px; 56px at lg) that also carries this class; or a bare 24px line icon in fg-subtle for the smallest inline states. Decorative.', optional: true },
+        { part: 'illustration', element: 'svg', description: 'An inline SVG illustration (≈152 × 120) drawn with token variables: documents, a cloud, a box, a credit card.', optional: true },
+        { part: 'title', element: 'h3', description: '16 / 18 / 20px semibold in ink: what is empty, in plain words ("No projects yet").' },
+        { part: 'description', element: 'p', description: 'One sentence, 14px (16px at lg) fg-muted, max 352px: why it is empty or what will fill it.', optional: true },
+        { part: 'search', element: 'div', description: 'Optional search Input (max 352px) between the text and the actions for "no results" states, so the user can refine the query in place.', optional: true },
+        { part: 'actions', element: 'div', description: 'Row of one primary Button and optionally one secondary (outline) Button, 12px apart, 24 / 32 / 32px below the text.', optional: true },
+    ],
+    props: {
+        size: {
+            values: ['sm', 'md', 'lg'],
+            default: 'md',
+            description: 'sm = inline in a card, table body or chart (16px title, 14px text, 48px icon, 4px text gap); md = a page section (18px title, 14px text, 48px icon, 8px gap); lg = a whole empty page (20px title, 16px text, 56px icon).',
+        },
+        variant: {
+            values: ['default', 'card', 'dashed', 'illustration', 'with-search'],
+            default: 'default',
+            description: 'default = no frame, a featured icon in the header (inside a Card, table or panel); card = white with a gray-200 ring, shadow-xs and radius 12 (standalone on the canvas); dashed = dashed gray-300 border, transparent, for drop zones and "create your first" slots; illustration = an inline SVG illustration in the header instead of the icon (24px below it); with-search = a search field under the text for "no results" states.',
+        },
+    },
+    states: {},
+    base: {
+        root: {
+            display: 'flex',
+            'flex-direction': 'column',
+            'align-items': 'center',
+            'text-align': 'center',
+            gap: '{space.2}',
+            padding: '{space.12} {space.6}',
+            width: '100%',
+            'max-width': 'calc({space.64} * 2)',
+            'margin-inline': 'auto',
+            color: '{color.fg-default}',
+        },
+        header: { position: 'relative', display: 'flex', 'align-items': 'center', 'justify-content': 'center', 'margin-bottom': '{space.3}' },
+        icon: { 'flex-shrink': '0', 'margin-bottom': '{space.3}' },
+        illustration: { display: 'block', width: '152px', height: 'auto', 'max-width': '100%' },
+        title: { ...typeStyle('heading-sm'), color: '{color.fg-default}', margin: '0', 'max-width': 'calc({space.64} + {space.24})' },
+        description: { ...typeStyle('body-md'), color: '{color.fg-muted}', 'max-width': 'calc({space.64} + {space.24})', margin: '0' },
+        search: { width: '100%', 'max-width': 'calc({space.64} + {space.24})', 'margin-top': '{space.4}' },
+        actions: { display: 'flex', 'flex-wrap': 'wrap', 'justify-content': 'center', 'align-items': 'center', gap: '{space.3}', 'margin-top': '{space.6}' },
+    },
+    variants: {
+        size: {
+            sm: { root: { padding: '{space.8} {space.4}', gap: '{space.1}' }, header: { 'margin-bottom': '{space.3}' }, icon: { 'margin-bottom': '{space.3}' }, title: { ...typeStyle('heading-xs') }, actions: { 'margin-top': '{space.5}' } },
+            md: { root: { padding: '{space.12} {space.6}' } },
+            lg: { root: { padding: '{space.16} {space.8}' }, title: { 'font-size': '{font.size.xl}', 'line-height': '{font.lineHeight.normal}' }, description: { ...typeStyle('body-lg') } },
+        },
+        variant: {
+            default: { root: {} },
+            card: { root: { 'background-color': '{color.bg-surface}', 'box-shadow': `${ring('{color.border-default}')}, {shadow.xs}`, 'border-radius': '{radius.card}' } },
+            dashed: { root: { 'background-color': 'transparent', border: '{border.width.thin} dashed {color.border-control}', 'border-radius': '{radius.card}' } },
+            illustration: { header: { 'margin-bottom': '{space.4}' } },
+            'with-search': { root: {} },
+        },
+    },
+    extraCss: `
+.cn-empty-state__header > .cn-empty-state__icon { margin-bottom: 0; }
+svg.cn-empty-state__icon { width: {size.icon.lg}; height: {size.icon.lg}; color: {color.fg-subtle}; }
+.cn-empty-state[data-size="lg"] .cn-featured-icon.cn-empty-state__icon { width: {space.14}; height: {space.14}; border-radius: {radius.xl}; }
+.cn-empty-state[data-size="lg"] .cn-featured-icon.cn-empty-state__icon > .cn-featured-icon__icon { width: {size.icon.xl}; height: {size.icon.xl}; }
+.cn-empty-state__title + .cn-empty-state__search, .cn-empty-state__description + .cn-empty-state__search { margin-top: {space.4}; }
+.cn-empty-state__search + .cn-empty-state__actions { margin-top: {space.4}; }
+.cn-empty-state[data-variant="dashed"] .cn-empty-state__icon { margin-bottom: {space.3}; }`,
+    examples: [
+        ex('No projects yet (default md)', state({ header: featured('copy'), title: 'No projects yet', description: 'Projects keep your team\'s work in one place. Create the first one or import from another tool.', actions: button('Import', 'outline') + button('New project', 'primary', 'md', ICON.plus) }), 'A 48px modern gray featured icon 20px above an 18px semibold title, 14px gray-600 text capped at 352px, two buttons 12px apart 32px below.'),
+        ex('Illustration', state({ variant: 'illustration', header: ILLUSTRATION, title: 'You\'re all caught up', description: 'Every task assigned to you is done. New work will show up here as soon as a teammate assigns it.', actions: button('View all tasks', 'link-color', 'md') }), 'An inline SVG illustration (documents) in the header, 24px above the title.'),
+        ex('No results, with search (sm)', state({ size: 'sm', variant: 'with-search', header: featured('search'), title: 'No customers found', description: 'Your search “Osaka” did not match any customers. Try a different name or clear the filters.', search: SEARCH, actions: button('Clear search', 'outline', 'sm') + button('New customer', 'primary', 'sm', ICON.plus) }), 'The search field sits between the text and the actions so the query can be refined in place; 16px title.'),
+        ex('Drop zone (dashed)', state({ variant: 'dashed', header: featured('inbox', 'md'), title: 'Drop a CSV here', description: 'One customer per row, with at least a name and an email address.', actions: button('Choose file', 'outline'), style: 'max-width:512px' }), 'Dashed gray-300 frame with a 40px modern icon; the button is the keyboard path.'),
+        ex('Whole page (lg, card)', state({ size: 'lg', variant: 'card', header: featured('inbox', 'xl'), title: 'Nothing waiting for you', description: 'Your team is working on 12 tasks. You will see reviews and approvals here as soon as they need a decision.', actions: button('See what the team is doing', 'outline') }), '56px icon, 20px title, 16px text; the white card frame when the empty state is the whole canvas region.'),
+        ex('Inline in a chart or table body', `<div class="cn-empty-state" data-size="sm" data-variant="default">${ICON.search.replace('cn-icon', 'cn-empty-state__icon')}<h3 class="cn-empty-state__title">No results for “Osaka”</h3><p class="cn-empty-state__description">Try a wider region or clear the score filter.</p><div class="cn-empty-state__actions">${button('Clear filters', 'link-color', 'sm')}</div></div>`, 'The bare 24px line icon for the smallest inline states, no header wrapper.'),
+    ],
+    rules: [
+        'Title says what is empty in the user\'s words ("No projects yet", "Nothing waiting for you"), never "No data", "Empty" or "404".',
+        'Description is one sentence, 14px, capped at 352px, that says why or what will fill it; skip it when the title is enough.',
+        'One primary action at most, and only if the user can fill the region from here; a second action is outline or link-color, 12px before it.',
+        'The header holds one thing: a modern gray FeaturedIcon (48px, 56 at lg), an illustration, or a file icon. Never a colored disc, never an emoji.',
+        'Filter-empty ("No results for X") is size sm with the with-search variant, keeps the filters visible and offers "Clear search"; it never uses a card or dashed frame.',
+        'Use dashed only for drop zones and "create the first one" slots; card only when the empty state is the whole canvas region; illustration for onboarding moments, not for every empty table.',
+        'Loading is not empty: show a Skeleton until the data arrives, then the EmptyState if it is truly empty.',
+        'Do not center the empty state vertically in a tall page; keep it at the top with its padding so it reads like content.',
+    ],
+    a11y: [
+        'The title is a real heading at the level of the region it replaces (h2 for a page, h3 for a card); do not skip levels.',
+        'The featured icon and illustration are aria-hidden; nothing in the empty state depends on them.',
+        'When the empty state appears after a filter or search, announce it with aria-live="polite" on the region so the change is heard.',
+        'Drop zones also work by keyboard: the "Choose file" Button opens the file picker; the dashed area is not the only way.',
+        'A search field inside the empty state keeps the current query as its value and has an aria-label.',
+    ],
+    related: ['featured-icon', 'skeleton', 'alert', 'button', 'input', 'card', 'table', 'list', 'file-dropzone'],
+};