canon-ds 0.1.0

package/lib/components/filter-bar.mjs

@@ -0,0 +1,179 @@
+import { RESET_BUTTON, TRANSITION_COLORS, ex, ICON, typeStyle } from "./_shared.mjs";
+// Filter bar: the row above a table or list that holds search, dropdown filter
+// buttons, a date range, sort, a list/grid view toggle, the result count and the
+// active-filter chips. Everything inside is an existing control; this component
+// only lays them out and styles the chips and the view toggle.
+const SVG = {
+    grid: '<svg class="cn-icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linejoin="round" aria-hidden="true"><rect x="2.5" y="2.5" width="4.5" height="4.5" rx="1"/><rect x="9" y="2.5" width="4.5" height="4.5" rx="1"/><rect x="2.5" y="9" width="4.5" height="4.5" rx="1"/><rect x="9" y="9" width="4.5" height="4.5" rx="1"/></svg>',
+    filter: '<svg class="cn-icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" aria-hidden="true"><path d="M2.5 4.5h11M4.5 8h7M6.5 11.5h3"/></svg>',
+    sort: '<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="M5 3v10M5 13l-2-2M5 13l2-2M11 13V3M11 3L9 5M11 3l2 2"/></svg>',
+};
+const bi = (name) => (name in ICON ? ICON[name] : SVG[name]).replace('cn-icon', 'cn-button__icon');
+const btn = (label, variant = 'outline', leading = '', trailing = '', size = 'sm') => `<button type="button" class="cn-button" data-variant="${variant}" data-size="${size}">${leading}<span class="cn-button__label">${label}</span>${trailing}</button>`;
+const dropdown = (label) => btn(label, 'outline', '', bi('chevronDown')).replace('class="cn-button"', 'class="cn-button" aria-haspopup="menu" aria-expanded="false"');
+const SEARCH = `<div class="cn-filter-bar__search"><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="Search customers…" aria-label="Search customers"></div></div>`;
+const chip = (key, value) => `<span class="cn-filter-bar__chip"><span class="cn-filter-bar__chip-key">${key}:</span>${value}<button type="button" class="cn-filter-bar__chip-remove" aria-label="Remove filter ${key}: ${value}">${ICON.x}</button></span>`;
+const VIEW = `<div class="cn-filter-bar__view" role="group" aria-label="Layout"><button type="button" class="cn-filter-bar__view-item" aria-pressed="true" aria-label="List view">${ICON.menu}</button><button type="button" class="cn-filter-bar__view-item" aria-pressed="false" aria-label="Grid view">${SVG.grid}</button></div>`;
+const count = (n) => `<span class="cn-filter-bar__count" aria-live="polite">${n}</span>`;
+const CLEAR = `<div class="cn-filter-bar__clear">${btn('Clear filters', 'link')}</div>`;
+const DATE = `<div class="cn-filter-bar__date">${btn('Sep 1 – Sep 11, 2026', 'outline', bi('calendar'), bi('chevronDown')).replace('class="cn-button"', 'class="cn-button" aria-haspopup="dialog" aria-expanded="false"')}</div>`;
+const SORT = `<div class="cn-filter-bar__sort">${btn('Sort: Newest', 'outline', bi('sort'), bi('chevronDown')).replace('class="cn-button"', 'class="cn-button" aria-haspopup="menu" aria-expanded="false"')}</div>`;
+const tab = (label, selected, id, extra = '') => `<button type="button" role="tab" class="cn-tabs__tab" id="fb-tab-${id}" aria-selected="${selected}" tabindex="${selected ? '0' : '-1'}">${label}${extra}</button>`;
+const bar = (variant, align, inner) => `<div class="cn-filter-bar" data-variant="${variant}" data-align="${align}" role="search" aria-label="Filter customers" style="width:100%">${inner}</div>`;
+export const filterBar = {
+    name: 'FilterBar',
+    slug: 'filter-bar',
+    category: 'forms',
+    description: 'The toolbar above a table or list: a 320px search, dropdown filter buttons with chevrons, a date-range button, sort, a list/grid toggle, the result count, and a wrapping row of active-filter chips with an × each. Composes Input, Button and Tabs; adds only the chips and the view toggle.',
+    usage: 'Use above any collection view (customers, invoices, files) that can be searched, filtered or re-sorted. Not for form fields (Field), not for page-level tabs (Tabs on their own), and not inside a Card header (put a single search Input there).',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'The bar: flex row that wraps, 12px gaps, role="search" or a labelled toolbar. Width comes from the layout.' },
+        { part: 'search', element: 'div', description: 'Wrapper for a sm Input with a leading search icon; 320px wide, shrinks to 200px.', optional: true },
+        { part: 'group', element: 'div', description: 'A cluster of outline sm Buttons with trailing chevrons that open filter menus (Status, Plan, Owner).', optional: true },
+        { part: 'chips', element: 'div', description: 'The wrapping row of active filters. Takes the full width so it sits under the controls.', optional: true },
+        { part: 'chip', element: 'span', description: 'One active filter: 28px pill with a hairline, "Key: value" and a 16px × remove button.', optional: true },
+        { part: 'chip-key', element: 'span', description: 'The muted "Status:" prefix inside a chip.', optional: true },
+        { part: 'chip-remove', element: 'button', description: 'The 16px × that removes this filter. aria-label "Remove filter Status: Active".', optional: true },
+        { part: 'date', element: 'div', description: 'Wrapper for the date-range button: outline sm Button with a leading calendar icon and a trailing chevron that opens a DatePicker.', optional: true },
+        { part: 'sort', element: 'div', description: 'Wrapper for the sort control: an outline sm Button ("Sort: Newest") that opens a Menu of radio items.', optional: true },
+        { part: 'view', element: 'div', description: 'The list/grid toggle: a hairline box of 32px icon buttons, role="group".', optional: true },
+        { part: 'view-item', element: 'button', description: 'One icon button inside the view toggle; aria-pressed="true" on the active layout, aria-label naming it.', optional: true },
+        { part: 'count', element: 'span', description: 'The result count in body-sm muted ("128 results"), aria-live so filtering announces the new number.', optional: true },
+        { part: 'clear', element: 'div', description: 'Wrapper for the link sm "Clear filters" Button. Only rendered when at least one filter is active.', optional: true },
+        { part: 'tabs', element: 'div', description: 'Wrapper for a Tabs component (underline for segments of the collection, pill for quick date ranges).', optional: true },
+        { part: 'end', element: 'div', description: 'The trailing cluster (count, sort, view, clear). With align="between" it is pushed to the right edge.', optional: true },
+    ],
+    props: {
+        variant: {
+            values: ['simple', 'with-chips', 'with-date', 'with-tabs', 'dense'],
+            default: 'simple',
+            description: 'simple = search + filter buttons + count (most tables). with-chips = the same plus a second line of active-filter chips with × and a Clear link (when filters persist). with-date = quick-range pill Tabs + a date-range button for time-based data (invoices, analytics). with-tabs = underline Tabs that segment the collection ("All / Active / Trial") with search on the right. dense = 8px gaps and 24px chips for toolbars inside drawers and cards.',
+        },
+        align: {
+            values: ['start', 'between'],
+            default: 'start',
+            description: 'start = everything flows from the left in one run. between = the end cluster (count, sort, view) is pushed to the right edge, leaving the middle empty. Use between on full-width pages, start inside narrower panels.',
+        },
+    },
+    states: {
+        chipRemoveHover: { selector: ' .cn-filter-bar__chip-remove:hover', description: 'Pointer over a chip\'s × (on the button; extraCss): muted fill, ink icon.', markup: 'native :hover on .cn-filter-bar__chip-remove' },
+        chipRemoveFocus: { selector: ' .cn-filter-bar__chip-remove:focus-visible', description: 'Keyboard focus on a chip\'s × shows the focus ring (extraCss).', markup: 'native :focus-visible on .cn-filter-bar__chip-remove' },
+        viewPressed: { selector: ' .cn-filter-bar__view-item[aria-pressed="true"]', description: 'The active layout in the view toggle (on the item; extraCss): subtle fill, ink icon.', markup: 'aria-pressed="true" on .cn-filter-bar__view-item' },
+        viewHover: { selector: ' .cn-filter-bar__view-item:hover', description: 'Pointer over a layout button: subtle fill (extraCss).', markup: 'native :hover on .cn-filter-bar__view-item' },
+        viewFocus: { selector: ' .cn-filter-bar__view-item:focus-visible', description: 'Keyboard focus on a layout button: an inset 2px ring (the toggle clips overflow) (extraCss).', markup: 'native :focus-visible on .cn-filter-bar__view-item' },
+    },
+    base: {
+        root: { display: 'flex', 'flex-wrap': 'wrap', 'align-items': 'center', gap: '{space.3}', width: '100%', 'min-width': '0', color: '{color.fg-default}' },
+        search: { flex: '0 1 320px', 'min-width': '200px', 'max-width': '100%' },
+        group: { display: 'flex', 'flex-wrap': 'wrap', 'align-items': 'center', gap: '{space.2}', 'min-width': '0' },
+        chips: { display: 'flex', 'flex-wrap': 'wrap', 'align-items': 'center', gap: '{space.2}', 'flex-basis': '100%', 'min-width': '0' },
+        chip: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            gap: '{space.1}',
+            height: '{space.7}',
+            padding: '0 {space.1} 0 {space.2.5}',
+            'background-color': '{color.bg-surface}',
+            border: '{border.width.thin} solid {color.border-control}',
+            'border-radius': '{radius.full}',
+            'box-shadow': '{shadow.xs}',
+            ...typeStyle('label-sm'),
+            color: '{color.fg-default}',
+            'white-space': 'nowrap',
+        },
+        'chip-key': { color: '{color.fg-muted}', 'font-weight': '{font.weight.regular}' },
+        'chip-remove': {
+            ...RESET_BUTTON,
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            width: '{space.4}',
+            height: '{space.4}',
+            'margin-inline-start': '{space.0.5}',
+            'border-radius': '{radius.full}',
+            color: '{color.fg-subtle}',
+            ...TRANSITION_COLORS,
+        },
+        date: { display: 'inline-flex', 'flex-shrink': '0' },
+        sort: { display: 'inline-flex', 'flex-shrink': '0' },
+        view: {
+            display: 'inline-flex',
+            'align-items': 'stretch',
+            'flex-shrink': '0',
+            height: '{size.control.sm}',
+            'background-color': '{color.bg-surface}',
+            border: '{border.width.thin} solid {color.border-control}',
+            'border-radius': '{radius.control}',
+            'box-shadow': '{shadow.xs}',
+            overflow: 'hidden',
+        },
+        'view-item': {
+            ...RESET_BUTTON,
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            width: '{size.control.sm}',
+            color: '{color.fg-subtle}',
+            ...TRANSITION_COLORS,
+        },
+        count: { ...typeStyle('body-sm'), color: '{color.fg-muted}', 'white-space': 'nowrap', 'flex-shrink': '0', 'font-variant-numeric': 'tabular-nums' },
+        clear: { display: 'inline-flex', 'flex-shrink': '0' },
+        tabs: { display: 'flex', 'min-width': '0', flex: '0 1 auto' },
+        end: { display: 'flex', 'flex-wrap': 'wrap', 'align-items': 'center', gap: '{space.3}', 'min-width': '0' },
+    },
+    variants: {
+        variant: {
+            simple: { root: {} },
+            'with-chips': { root: {} },
+            'with-date': { root: {} },
+            'with-tabs': { root: {} },
+            dense: {
+                root: { gap: '{space.2}' },
+                search: { flex: '0 1 240px', 'min-width': '160px' },
+                chips: { gap: '{space.1.5}' },
+                chip: { height: '{space.6}', padding: '0 {space.0.5} 0 {space.2}', ...typeStyle('label-xs') },
+                end: { gap: '{space.2}' },
+            },
+        },
+        align: {
+            start: { end: { 'margin-inline-start': '0' } },
+            between: { end: { 'margin-inline-start': 'auto' } },
+        },
+    },
+    extraCss: `
+.cn-filter-bar__chip-remove .cn-icon { width: {size.icon.xs}; height: {size.icon.xs}; stroke-width: 2; }
+.cn-filter-bar__chip-remove:hover { background-color: {color.bg-muted}; color: {color.fg-default}; }
+.cn-filter-bar__chip-remove:focus-visible { outline: none; box-shadow: {shadow.focus}; }
+.cn-filter-bar__view-item + .cn-filter-bar__view-item { border-inline-start: {border.width.thin} solid {color.border-control}; }
+.cn-filter-bar__view-item .cn-icon { width: {size.icon.md}; height: {size.icon.md}; }
+.cn-filter-bar__view-item:hover { background-color: {color.bg-subtle}; color: {color.fg-muted}; }
+.cn-filter-bar__view-item[aria-pressed="true"] { background-color: {color.bg-subtle}; color: {color.fg-default}; }
+.cn-filter-bar__view-item:focus-visible { outline: none; box-shadow: inset 0 0 0 2px {color.ring-focus}; }
+.cn-filter-bar__tabs .cn-tabs { max-width: 100%; }`,
+    examples: [
+        ex('Simple', bar('simple', 'start', `${SEARCH}<div class="cn-filter-bar__group">${dropdown('Status')}${dropdown('Plan')}${dropdown('Owner')}</div><div class="cn-filter-bar__end">${count('128 results')}</div>`), 'Search, three filter menus and the count in one run.'),
+        ex('With chips', bar('with-chips', 'between', `${SEARCH}<div class="cn-filter-bar__group">${btn('Filters', 'outline', bi('filter'))}</div><div class="cn-filter-bar__end">${count('37 results')}${SORT}${VIEW}</div><div class="cn-filter-bar__chips">${chip('Status', 'Active')}${chip('Plan', 'Team')}${chip('Owner', 'Maya Chen')}${CLEAR}</div>`), 'Active filters wrap onto a second line as removable chips; Clear filters is a link Button at the end.'),
+        ex('With date range', bar('with-date', 'between', `<div class="cn-filter-bar__tabs"><div class="cn-tabs" data-variant="pill" data-size="sm" role="tablist" aria-label="Quick ranges">${tab('12 months', false, '12m')}${tab('30 days', true, '30d')}${tab('7 days', false, '7d')}${tab('24 hours', false, '24h')}</div></div>${DATE}<div class="cn-filter-bar__end">${btn('Filters', 'outline', bi('filter'))}${SORT}</div>`), 'Quick ranges as pill Tabs, a custom range from the calendar button.'),
+        ex('With tabs', bar('with-tabs', 'between', `<div class="cn-filter-bar__tabs"><div class="cn-tabs" data-variant="underline" data-size="md" role="tablist" aria-label="Customer segments">${tab('All', true, 'all', '<span class="cn-tabs__count">128</span>')}${tab('Active', false, 'active')}${tab('Trial', false, 'trial', '<span class="cn-tabs__count">9</span>')}${tab('Churned', false, 'churned')}</div></div><div class="cn-filter-bar__end">${SEARCH}${VIEW}</div>`), 'Tabs segment the collection; search and the view toggle sit on the right.'),
+        ex('Dense', bar('dense', 'start', `${SEARCH}<div class="cn-filter-bar__group">${dropdown('Type')}${dropdown('Modified')}</div>${count('12 files')}<div class="cn-filter-bar__chips">${chip('Type', 'PDF')}${chip('Modified', 'Last 7 days')}${CLEAR}</div>`), '8px gaps and 24px chips for toolbars inside drawers and cards.'),
+    ],
+    rules: [
+        'Order from left to right: search, filter menus, date range, then the end cluster: count, sort, view toggle. Never put the count first.',
+        'Filter buttons are outline sm Buttons with a trailing chevron and open a Menu; the button label names the field ("Status"), never the value.',
+        'Chips show "Key: value" and only appear for active filters; the Clear link appears with the first chip and disappears with the last.',
+        'Search is 320px on pages, shrinks to 200px, and is the only Input in the bar. Put more fields in a filter Drawer.',
+        'The count uses the exact number and the noun ("128 results", "12 files") and updates live; no "Showing" prefix.',
+        'The view toggle has two or three layouts at most, icon-only, with one aria-pressed="true".',
+        'Sort is a button labelled "Sort: {option}" that opens a Menu of radio items; never a bare Select in the bar.',
+        'align="between" on full-width pages; align="start" inside panels narrower than 720px, where the bar wraps anyway.',
+        'dense only inside drawers, cards and split views; on a page the default heights keep 36px targets.',
+    ],
+    a11y: [
+        'Root is role="search" when it contains the search field, otherwise role="toolbar"; give it an aria-label naming the collection.',
+        'Filter buttons expose aria-haspopup="menu" and aria-expanded; the date button aria-haspopup="dialog".',
+        'Chip × buttons have aria-label "Remove filter {Key}: {value}"; removing one moves focus to the next chip or to the search field.',
+        'The view toggle is role="group" with aria-label; each item has aria-pressed and an aria-label naming the layout.',
+        'The count carries aria-live="polite" so screen readers hear the new number after filtering; keep the text short.',
+    ],
+    related: ['input', 'button', 'tabs', 'menu', 'tag', 'table', 'segmented-control'],
+};

package/lib/components/header-navigation.mjs

@@ -0,0 +1,94 @@
+import { ex, ICON, typeStyle } from "./_shared.mjs";
+const navItem = (label, current = false, dropdown = false) => `<a href="#" class="cn-header-navigation__item"${current ? ' aria-current="page"' : ''}>${label}${dropdown ? ICON.chevronDown.replace('cn-icon', 'cn-header-navigation__chevron') : ''}</a>`;
+const NAV = `${navItem('Home', true)}${navItem('Products', false, true)}${navItem('Resources', false, true)}${navItem('Pricing')}`;
+const LOGO = `<a href="#" class="cn-header-navigation__logo"><span class="cn-header-navigation__mark" aria-hidden="true"></span>Lumen</a>`;
+const ACTIONS = `<div class="cn-header-navigation__actions"><button type="button" class="cn-button" data-variant="ghost" data-size="lg"><span class="cn-button__label">Log in</span></button><button type="button" class="cn-button" data-variant="primary" data-size="lg"><span class="cn-button__label">Sign up</span></button></div>`;
+const menuItem = (title, desc, icon) => `<a href="#" class="cn-header-navigation__menu-item">${icon.replace('cn-icon', 'cn-header-navigation__menu-icon')}<span class="cn-header-navigation__menu-text"><span class="cn-header-navigation__menu-title">${title}</span><span class="cn-header-navigation__menu-desc">${desc}</span></span></a>`;
+export const headerNavigation = {
+    name: 'HeaderNavigation',
+    slug: 'header-navigation',
+    category: 'navigation',
+    description: 'Marketing website header: 80px bar with logo, text links (with optional mega menu), and Log in / Sign up actions; collapses to a hamburger on mobile. "header navigation".',
+    usage: 'Top of every marketing page (landing, pricing, about, blog). Inside the product use Topbar or Sidebar instead.',
+    anatomy: [
+        { part: 'root', element: 'header', description: 'Full-width bar, 80px, bottom hairline (transparent when over a hero).' },
+        { part: 'container', element: 'div', description: 'Centered 1280px row with 32px side padding.' },
+        { part: 'logo', element: 'a', description: 'Logo mark + wordmark, links home.' },
+        { part: 'mark', element: 'span', description: '32px mark.' },
+        { part: 'nav', element: 'nav', description: 'The text links, 8px apart.' },
+        { part: 'item', element: 'a', description: '16px semibold link, 40px tall, fg-muted → fg-default; current is fg-default.' },
+        { part: 'chevron', element: 'svg', description: 'Dropdown indicator, 20px.' },
+        { part: 'actions', element: 'div', description: 'Right side: Log in (ghost) and Sign up (primary), lg size.' },
+        { part: 'toggle', element: 'button', description: 'Hamburger IconButton shown under 1024px.' },
+        { part: 'menu', element: 'div', description: 'Mega menu panel: white, radius 12, shadow-lg, 2–3 columns of menu items.', optional: true },
+        { part: 'menu-item', element: 'a', description: 'Icon + title + description row, 12px radius, hover bg-subtle.' },
+        { part: 'menu-icon', element: 'svg', description: '24px icon in brand color.' },
+        { part: 'menu-text', element: 'span', description: 'Title and description column.' },
+        { part: 'menu-title', element: 'span', description: 'label-md semibold.' },
+        { part: 'menu-desc', element: 'span', description: 'body-md fg-muted.' },
+    ],
+    props: {
+        variant: { values: ['default', 'transparent', 'with-menu'], default: 'default', description: 'default = white with bottom hairline; transparent = no background/border (over a hero); with-menu = shows the mega menu panel open under the bar (static preview).' },
+        theme: { values: ['light', 'dark'], default: 'light', description: 'dark = gray-950 bar with light text (dark landing pages).' },
+    },
+    states: {
+        hover: { selector: ' .cn-header-navigation__item:hover', description: 'Link darkens.', markup: 'native' },
+        current: { selector: ' .cn-header-navigation__item[aria-current="page"]', description: 'Current section is fg-default.', markup: 'aria-current="page"' },
+        open: { selector: '[data-state="open"]', description: 'Mega menu visible.', markup: 'data-state="open" on the root' },
+    },
+    base: {
+        root: { position: 'relative', 'background-color': '{color.bg-surface}', 'border-bottom': '{border.width.thin} solid {color.border-default}' },
+        container: { display: 'flex', 'align-items': 'center', gap: '{space.10}', height: '80px', 'max-width': '{size.container.xl}', 'margin-inline': 'auto', 'padding-inline': '{space.8}' },
+        logo: { display: 'inline-flex', 'align-items': 'center', gap: '{space.2.5}', ...typeStyle('label-lg'), 'font-size': '{font.size.lg}', color: '{color.fg-default}', 'text-decoration': 'none', 'flex-shrink': '0' },
+        mark: { width: '32px', height: '32px', 'border-radius': '{radius.lg}', 'background-color': '{color.bg-action}' },
+        nav: { display: 'flex', 'align-items': 'center', gap: '{space.2}', flex: '1 1 auto' },
+        item: { display: 'inline-flex', 'align-items': 'center', gap: '{space.1}', height: '40px', 'padding-inline': '{space.3}', 'border-radius': '{radius.md}', ...typeStyle('label-lg'), color: '{color.fg-muted}', 'text-decoration': 'none', 'transition-property': 'color, background-color', 'transition-duration': '{motion.duration.fast}', 'transition-timing-function': '{motion.easing.standard}' },
+        chevron: { width: '{size.icon.md}', height: '{size.icon.md}', color: '{color.fg-subtle}' },
+        actions: { display: 'flex', 'align-items': 'center', gap: '{space.3}', 'flex-shrink': '0' },
+        toggle: { display: 'none', appearance: 'none', border: '0', background: 'none', padding: '0', width: '40px', height: '40px', 'border-radius': '{radius.md}', color: '{color.fg-muted}', cursor: 'pointer', 'align-items': 'center', 'justify-content': 'center', 'margin-inline-start': 'auto' },
+        menu: { display: 'none', position: 'absolute', top: '100%', left: '50%', transform: 'translateX(-50%)', width: '{size.container.md}', 'max-width': 'calc(100% - {space.8})', 'margin-top': '{space.2}', padding: '{space.5}', 'background-color': '{color.bg-surface-raised}', border: '{border.width.thin} solid {color.border-default}', 'border-radius': '{radius.card}', 'box-shadow': '{shadow.lg}', 'grid-template-columns': 'repeat(2, minmax(0, 1fr))', gap: '{space.2}', 'z-index': '{z.dropdown}' },
+        'menu-item': { display: 'flex', gap: '{space.4}', 'align-items': 'flex-start', padding: '{space.3}', 'border-radius': '{radius.lg}', 'text-decoration': 'none', color: 'inherit', 'transition-property': 'background-color', 'transition-duration': '{motion.duration.fast}', 'transition-timing-function': '{motion.easing.standard}' },
+        'menu-icon': { width: '{size.icon.lg}', height: '{size.icon.lg}', color: '{brand.600}', 'flex-shrink': '0', 'margin-top': '2px' },
+        'menu-text': { display: 'flex', 'flex-direction': 'column', gap: '{space.1}', 'min-width': '0' },
+        'menu-title': { ...typeStyle('label-md'), 'font-size': '{font.size.md}', color: '{color.fg-default}' },
+        'menu-desc': { ...typeStyle('body-md'), color: '{color.fg-muted}' },
+        '@states': {
+            hover: { item: { color: '{color.fg-default}' } },
+            current: { item: { color: '{color.fg-default}' } },
+            open: { menu: { display: 'grid' } },
+        },
+    },
+    variants: {
+        variant: {
+            default: { root: {} },
+            transparent: { root: { 'background-color': 'transparent', 'border-bottom-color': 'transparent' } },
+            'with-menu': { root: {}, menu: { display: 'grid', position: 'relative', top: 'auto', left: 'auto', transform: 'none', 'margin-inline': 'auto', 'margin-bottom': '{space.6}' } },
+        },
+        theme: {
+            light: { root: {} },
+            dark: { root: { 'background-color': '{neutral.950}', 'border-bottom-color': '{neutral.800}' }, logo: { color: '{white}' }, item: { color: '{neutral.300}' }, chevron: { color: '{neutral.500}' }, toggle: { color: '{neutral.300}' }, '@states': { hover: { item: { color: '{white}' } }, current: { item: { color: '{white}' } } } },
+        },
+    },
+    extraCss: `
+.cn-header-navigation__mark { clip-path: polygon(0 0, 100% 0, 100% 22%, 27% 22%, 27% 78%, 100% 78%, 100% 100%, 0 100%); border-radius: 0; }
+.cn-header-navigation__item:hover .cn-header-navigation__chevron { color: currentColor; }
+.cn-header-navigation__menu-item:hover { background-color: {color.bg-subtle}; }
+.cn-header-navigation[data-theme="dark"] .cn-button[data-variant="ghost"] { color: {neutral.300}; }
+.cn-header-navigation[data-theme="dark"] .cn-button[data-variant="ghost"]:hover { background-color: {neutral.800}; color: {white}; }
+@media (max-width: {breakpoint.lg}) { .cn-header-navigation .cn-header-navigation__nav, .cn-header-navigation .cn-header-navigation__actions { display: none; } .cn-header-navigation .cn-header-navigation__toggle { display: inline-flex; } .cn-header-navigation .cn-header-navigation__container { height: 64px; padding-inline: {space.4}; } }`,
+    examples: [
+        ex('Default', `<header class="cn-header-navigation" data-variant="default" data-theme="light"><div class="cn-header-navigation__container">${LOGO}<nav class="cn-header-navigation__nav" aria-label="Main">${NAV}</nav>${ACTIONS}<button type="button" class="cn-header-navigation__toggle" aria-label="Open menu">${ICON.menu}</button></div></header>`),
+        ex('With mega menu open', `<header class="cn-header-navigation" data-variant="with-menu" data-theme="light" data-state="open"><div class="cn-header-navigation__container">${LOGO}<nav class="cn-header-navigation__nav" aria-label="Main">${navItem('Home')}${navItem('Products', true, true)}${navItem('Resources', false, true)}${navItem('Pricing')}</nav>${ACTIONS}<button type="button" class="cn-header-navigation__toggle" aria-label="Open menu">${ICON.menu}</button></div><div class="cn-header-navigation__menu">${menuItem('Analytics', 'Get a better understanding of your traffic.', ICON.calendar)}${menuItem('Engagement', 'Speak directly to your customers.', ICON.inbox)}${menuItem('Security', 'Your customers’ data will be safe and secure.', ICON.check)}${menuItem('Integrations', 'Connect with third-party tools.', ICON.copy)}${menuItem('Automations', 'Build strategic funnels that will convert.', ICON.spark)}${menuItem('Reports', 'Get detailed reports with the click of a button.', ICON.home)}</div></header>`),
+        ex('Transparent over a hero surface', `<div style="background:var(--cn-color-bg-subtle)"><header class="cn-header-navigation" data-variant="transparent" data-theme="light"><div class="cn-header-navigation__container">${LOGO}<nav class="cn-header-navigation__nav" aria-label="Main">${NAV}</nav>${ACTIONS}<button type="button" class="cn-header-navigation__toggle" aria-label="Open menu">${ICON.menu}</button></div></header></div>`),
+        ex('Dark', `<header class="cn-header-navigation" data-variant="default" data-theme="dark"><div class="cn-header-navigation__container">${LOGO}<nav class="cn-header-navigation__nav" aria-label="Main">${NAV}</nav>${ACTIONS}<button type="button" class="cn-header-navigation__toggle" aria-label="Open menu">${ICON.menu}</button></div></header>`),
+    ],
+    rules: [
+        '80px tall on desktop, 64 on mobile; 1280px container with 32px padding; logo left, links after a 40px gap, actions right.',
+        'Links: 16px semibold gray; ≤ 5 items; dropdown items show a chevron and open a mega menu with icon + title + one-line description rows.',
+        'Actions: exactly "Log in" (tertiary/ghost, lg) and one primary CTA (lg). Never two filled buttons.',
+        'Below 1024px, links and actions hide behind the hamburger; the mobile menu lists the same links stacked, then the two actions full width.',
+        'Transparent variant only over a hero whose background guarantees contrast.',
+    ],
+    a11y: ['<header> + <nav aria-label="Main">; dropdown triggers use aria-expanded; the mega menu is reachable by keyboard and closes with Escape.', 'The hamburger is a labelled button.'],
+    related: ['topbar', 'button', 'mobile-header', 'menu'],
+};

package/lib/components/icon-button.mjs

@@ -0,0 +1,179 @@
+import { CONTROL, RESET_BUTTON, STATE, SIZE_PROP, ex, ICON } from "./_shared.mjs";
+// the system icon-only button (Button with data-icon-only) plus the ButtonUtility
+// used for close (×) and table-row actions: same box as Button (32–48px), 20px icon
+// (16px on xs), a flat fill or a single inset border on filled/ringed intents.
+const TRANSITION_FAST = {
+    'transition-property': 'background-color, border-color, color, box-shadow, opacity',
+    'transition-duration': '{motion.duration.fast}',
+    'transition-timing-function': '{motion.easing.linear}',
+};
+const ring = (color) => `inset 0 0 0 1px ${color}`;
+const SHADOW_SOLID = '{shadow.control}, {shadow.xs}';
+const shadowRinged = (color) => `${ring(color)}, ${SHADOW_SOLID}`;
+const ICON_ON_SOLID = 'color-mix(in srgb, currentColor 60%, transparent)';
+const ICON_ON_SOLID_HOVER = 'color-mix(in srgb, currentColor 70%, transparent)';
+const solid = (bg, hoverBg, fg, focus) => ({
+    root: { 'background-color': bg, color: fg, 'box-shadow': SHADOW_SOLID },
+    icon: { color: ICON_ON_SOLID },
+    '@states': {
+        hover: { root: { 'background-color': hoverBg }, icon: { color: ICON_ON_SOLID_HOVER } },
+        loading: { root: { 'background-color': hoverBg } },
+        focus: { root: { 'box-shadow': `${SHADOW_SOLID}, ${focus}` } },
+        pressed: { root: { 'background-color': hoverBg } },
+    },
+});
+const bordered = (bg, ringColor, hoverBg, pressedBg) => ({
+    root: { 'background-color': bg, color: '{color.fg-subtle}', 'box-shadow': shadowRinged(ringColor) },
+    '@states': {
+        hover: { root: { 'background-color': hoverBg, color: '{color.fg-muted}' } },
+        loading: { root: { 'background-color': hoverBg } },
+        focus: { root: { 'box-shadow': `${shadowRinged(ringColor)}, {shadow.focus}` } },
+        pressed: { root: { 'background-color': pressedBg, color: '{color.fg-default}', 'box-shadow': shadowRinged(ringColor) } },
+    },
+});
+const plain = () => ({
+    root: { 'background-color': 'transparent', color: '{color.fg-subtle}', 'box-shadow': 'none' },
+    '@states': {
+        hover: { root: { 'background-color': '{color.bg-subtle}', color: '{color.fg-muted}' } },
+        loading: { root: { 'background-color': '{color.bg-subtle}' } },
+        focus: { root: { 'box-shadow': '{shadow.focus}' } },
+        pressed: { root: { 'background-color': '{color.bg-subtle}', color: '{color.fg-default}' } },
+    },
+});
+const sizeBlock = (s) => ({
+    root: { width: CONTROL[s].height, height: CONTROL[s].height },
+    icon: { width: CONTROL[s].icon, height: CONTROL[s].icon },
+    spinner: { width: CONTROL[s].icon, height: CONTROL[s].icon },
+});
+const icon = (name) => ICON[name].replace('cn-icon', 'cn-icon-button__icon');
+const btn = (variant, size, shape, label, i, attrs = '') => `<button type="button" class="cn-icon-button" data-variant="${variant}" data-size="${size}" data-shape="${shape}" aria-label="${label}"${attrs}>${icon(i)}</button>`;
+const row = (...items) => `<div style="display:flex;flex-wrap:wrap;align-items:center;gap:var(--cn-space-3)">${items.join('')}</div>`;
+export const iconButton = {
+    name: 'IconButton',
+    slug: 'icon-button',
+    category: 'actions',
+    description: 'A square (or round) button holding exactly one icon: icon-only button and its utility button. Same intents and sizes as Button, width equals height, the icon sits in a muted gray until hover, and the accessible name lives in aria-label.',
+    usage: 'Use for a frequent, unambiguous action next to content: close, more actions, copy, delete a row, toggle a panel. If the icon needs a caption to be understood, use a Button with a label instead. Toggles (pin, bookmark, show calendar) use aria-pressed. Always pair with a Tooltip that repeats the aria-label.',
+    anatomy: [
+        { part: 'root', element: 'button', description: 'The interactive element. <button type="button"> with a mandatory aria-label; <a> only when it navigates.' },
+        { part: 'icon', element: 'svg', description: 'The single icon, 20px (16px on xs). Decorative: aria-hidden="true". No text inside the button.' },
+        { part: 'spinner', element: 'span', description: 'Shown only while data-loading; the icon becomes invisible, the button keeps its size.', optional: true },
+    ],
+    props: {
+        variant: {
+            values: ['primary', 'secondary', 'outline', 'ghost', 'danger', 'utility'],
+            default: 'ghost',
+            description: 'ghost = default for toolbars, table rows and card headers: transparent, gray-400 icon, gray-50 fill on hover (Tertiary icon-only). utility = the same colors in a smaller 6px-radius box for close (×) buttons, table-row and file-list actions (ButtonUtility tertiary: 28px on xs, 32px on sm). outline = white with a gray-300 ring when it stands alone on the canvas (Secondary icon-only). secondary = gray-50 fill with a ring next to a filled action. primary = the one filled action (rare: a "+" that is the main action on a small screen). danger = destructive, always behind a confirm.',
+        },
+        size: SIZE_PROP(),
+        shape: {
+            values: ['square', 'circle'],
+            default: 'square',
+            description: 'square = 8px radius (6px for utility), sits in toolbars and rows next to Buttons; circle = fully round, for avatars and floating actions. Do not mix shapes in one row.',
+        },
+    },
+    states: {
+        hover: STATE.hover(),
+        active: { selector: ':active:not(:disabled):not([aria-disabled="true"])', description: 'While pressed. has no distinct pressed style: it keeps the hover colors.', markup: 'native :active' },
+        focus: { selector: ':focus-visible', description: 'Keyboard focus. The 4px brand ring (red for danger) is added under the existing ring and shadow.', markup: 'native :focus-visible' },
+        disabled: { selector: ':disabled, &[aria-disabled="true"]', description: 'Not interactive. Whole button at 50% opacity, cursor not-allowed, no hover.', markup: 'disabled attribute (or aria-disabled="true")' },
+        loading: STATE.loading(),
+        pressed: { selector: '[aria-pressed="true"]', description: 'Toggle is on. Gray-50 fill + default ink so the state is visible at rest, not only on hover. Use with ghost, utility or outline.', markup: 'aria-pressed="true" (toggle buttons only)' },
+    },
+    base: {
+        root: {
+            ...RESET_BUTTON,
+            position: 'relative',
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            padding: '0',
+            color: '{color.fg-subtle}',
+            'border-radius': '{radius.control}',
+            ...TRANSITION_FAST,
+        },
+        icon: { 'flex-shrink': '0', display: 'block', 'pointer-events': 'none', transition: 'inherit' },
+        spinner: {
+            display: 'none',
+            position: 'absolute',
+            inset: '0',
+            margin: 'auto',
+            'border-radius': '{radius.full}',
+            border: '2px solid currentColor',
+            'border-right-color': 'transparent',
+            animation: 'icon-button-spin 0.7s linear infinite',
+        },
+        '@states': {
+            focus: { root: { outline: 'none', 'box-shadow': '{shadow.focus}' } },
+            disabled: { root: { opacity: '{opacity.disabled}', cursor: 'not-allowed' } },
+            loading: {
+                root: { cursor: 'progress', 'pointer-events': 'none' },
+                icon: { visibility: 'hidden' },
+                spinner: { display: 'block' },
+            },
+            pressed: { root: { 'background-color': '{color.bg-subtle}', color: '{color.fg-default}' } },
+        },
+    },
+    variants: {
+        variant: {
+            primary: solid('{color.bg-action}', '{color.bg-action-hover}', '{color.fg-on-action}', '{shadow.focus}'),
+            secondary: bordered('{color.bg-subtle}', '{color.border-control}', '{color.bg-muted}', '{color.bg-muted}'),
+            outline: bordered('{color.bg-surface}', '{color.border-control}', '{color.bg-subtle}', '{color.bg-subtle}'),
+            ghost: plain(),
+            danger: solid('{color.bg-danger}', '{color.bg-danger-hover}', '{white}', '{shadow.focus-danger}'),
+            utility: { ...plain(), root: { ...plain().root, 'border-radius': '{radius.md}' } },
+        },
+        size: {
+            xs: sizeBlock('xs'),
+            sm: sizeBlock('sm'),
+            md: sizeBlock('md'),
+            lg: sizeBlock('lg'),
+            xl: sizeBlock('xl'),
+        },
+        shape: {
+            square: { root: {} },
+            circle: { root: { 'border-radius': '{radius.full}' } },
+        },
+    },
+    // ButtonUtility: xs 28×28 with a 16px icon, sm 32×32 with a 20px icon.
+    compound: [
+        { when: { variant: 'utility', size: 'xs' }, block: { root: { width: 'calc({size.control.xs} - {space.1})', height: 'calc({size.control.xs} - {space.1})' } } },
+        { when: { variant: 'utility', size: 'sm' }, block: { root: { width: '{size.control.xs}', height: '{size.control.xs}' } } },
+    ],
+    extraCss: `
+@keyframes icon-button-spin { to { transform: rotate(360deg); } }
+.cn-icon-button[data-shape="circle"]::before { border-radius: {radius.full}; }`,
+    examples: [
+        ex('Ghost (toolbar default)', btn('ghost', 'md', 'square', 'More actions', 'dots'), 'Transparent, gray-400 icon; gray-50 fill and a darker icon on hover.'),
+        ex('Intents', row(btn('primary', 'md', 'square', 'Add member', 'plus'), btn('secondary', 'md', 'square', 'Settings', 'settings'), btn('outline', 'md', 'square', 'Copy link', 'copy'), btn('ghost', 'md', 'square', 'Search', 'search'), btn('danger', 'md', 'square', 'Delete row', 'trash')), 'Same colors as Button. Ghost is the default because most icon buttons sit inside toolbars and rows.'),
+        ex('Utility (close and row actions)', row(btn('utility', 'xs', 'square', 'Delete file', 'trash'), btn('utility', 'sm', 'square', 'Close', 'x'), btn('utility', 'md', 'square', 'Close panel', 'x')), 'ButtonUtility: 28px (xs) and 32px (sm) boxes with a 6px radius, for file rows, tags and dialog headers.'),
+        ex('Circle', row(btn('ghost', 'md', 'circle', 'Close', 'x'), btn('outline', 'md', 'circle', 'Open profile', 'user'), btn('primary', 'lg', 'circle', 'New message', 'plus')), 'Round for avatars and floating actions.'),
+        ex('Pressed (toggle)', row(btn('outline', 'md', 'square', 'Show calendar', 'calendar', ' aria-pressed="true"'), btn('outline', 'md', 'square', 'Show inbox', 'inbox', ' aria-pressed="false"'), btn('ghost', 'md', 'square', 'Pin to sidebar', 'spark', ' aria-pressed="true"')), 'aria-pressed="true" keeps the gray-50 fill at rest so the on state is visible without hovering.'),
+        ex('Sizes', row(btn('outline', 'xs', 'square', 'Search', 'search'), btn('outline', 'sm', 'square', 'Search', 'search'), btn('outline', 'md', 'square', 'Search', 'search'), btn('outline', 'lg', 'square', 'Search', 'search'), btn('outline', 'xl', 'square', 'Search', 'search')), '32 / 36 / 40 / 44 / 48px; the icon is 20px except on xs (16px).'),
+        ex('Loading', `<button type="button" class="cn-icon-button" data-variant="primary" data-size="md" data-shape="square" aria-label="Sending" data-loading aria-busy="true"><span class="cn-icon-button__spinner" aria-hidden="true"></span>${icon('arrow')}</button>`),
+        ex('Disabled', row(btn('outline', 'md', 'square', 'Delete row', 'trash', ' disabled'), btn('ghost', 'md', 'square', 'More actions', 'dots', ' disabled'))),
+    ],
+    recipes: [
+        ex('Row actions in a card header', `<div style="display:flex;gap:var(--cn-space-1)">${btn('ghost', 'sm', 'square', 'Copy ID', 'copy')}${btn('ghost', 'sm', 'square', 'Open in new tab', 'external')}${btn('ghost', 'sm', 'square', 'More actions', 'dots')}</div>`, 'Ghost, size sm, 4px apart. The "more" menu is always last.'),
+    ],
+    rules: [
+        'aria-label is mandatory and names the action, not the icon: "Delete row", not "Trash".',
+        'Always pair with a Tooltip that shows the same text as aria-label; hover reveals what keyboard users already hear.',
+        'Ghost inside toolbars, table rows and card headers; utility for close buttons and file-list actions; outline when the button stands alone on the canvas; primary only when the icon action is the main action of the region.',
+        'No text inside an IconButton. The moment it needs a caption, it is a Button with a leading icon.',
+        'Toggles set aria-pressed and use ghost, utility or outline; the icon keeps its meaning in both states (a pin stays a pin, it does not become a cross).',
+        'Icon size comes from size; never scale the svg by hand or pad the button to change its footprint.',
+        'Touch targets: md (40px) or larger on mobile and in touch-first screens; xs/sm are for dense desktop rows only.',
+        'One shape per row. Square next to Buttons; circle for avatars and floating actions.',
+        'Destructive icon actions (danger, or a ghost trash icon) always confirm before acting.',
+    ],
+    a11y: [
+        'Use <button type="button"> with aria-label (or aria-labelledby). An icon alone has no accessible name.',
+        'The svg is aria-hidden="true" and focusable="false"; the name comes from the button.',
+        'Toggle buttons expose aria-pressed="true|false" and keep the same aria-label in both states.',
+        'Focus ring on :focus-visible only, as a 4px box-shadow ring; never outline: none without a replacement.',
+        'While loading set aria-busy="true" and keep the aria-label; disabled removes it from the tab order.',
+    ],
+    related: ['button', 'button-group', 'menu', 'tooltip'],
+};

package/lib/components/index.mjs

@@ -0,0 +1,52 @@
+import { readdirSync } from 'node:fs';
+import { dirname, extname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+export const CATEGORY_ORDER = ['typography', 'actions', 'forms', 'navigation', 'data-display', 'feedback', 'overlays', 'layout', 'media'];
+export const CATEGORY_LABEL = {
+    typography: 'Typography', actions: 'Actions', forms: 'Forms', navigation: 'Navigation', 'data-display': 'Data display', feedback: 'Feedback', overlays: 'Overlays', layout: 'Layout', media: 'Media',
+};
+/** Preferred documentation order inside each category; unknown slugs go after, alphabetically. */
+export const DOC_ORDER = [
+    'kicker', 'prose', 'link', 'code', 'kbd',
+    'button', 'icon-button', 'button-group', 'segmented-control',
+    'field', 'input', 'textarea', 'select', 'combobox', 'checkbox', 'radio', 'switch', 'slider', 'file-dropzone',
+    'topbar', 'tabs', 'sidebar-nav', 'breadcrumb', 'pagination', 'menu', 'command-palette', 'stepper',
+    'badge', 'tag', 'counter', 'avatar', 'avatar-group', 'agent-presence', 'stat', 'table', 'list', 'description-list', 'accordion', 'timeline', 'kanban', 'chart-frame',
+    'alert', 'banner', 'toast', 'progress', 'spinner', 'skeleton', 'empty-state',
+    'tooltip', 'popover', 'dialog', 'drawer',
+    'card', 'divider',
+    'media-frame',
+];
+let cache = null;
+/** Discover source or compiled modules exporting a ComponentSpec. */
+export async function loadCatalog() {
+    if (cache)
+        return cache;
+    const dir = dirname(fileURLToPath(import.meta.url));
+    const extension = extname(fileURLToPath(import.meta.url));
+    const files = readdirSync(dir).filter((f) => f.endsWith(extension) && !f.startsWith('_') && f !== `index${extension}`).sort();
+    const specs = [];
+    for (const f of files) {
+        const mod = await import(pathToFileURL(join(dir, f)).href);
+        for (const v of Object.values(mod)) {
+            if (v && typeof v === 'object' && 'slug' in v && 'anatomy' in v)
+                specs.push(v);
+        }
+    }
+    specs.sort(compareSpecs);
+    cache = specs;
+    return specs;
+}
+export function compareSpecs(a, b) {
+    const ca = CATEGORY_ORDER.indexOf(a.category), cb = CATEGORY_ORDER.indexOf(b.category);
+    if (ca !== cb)
+        return ca - cb;
+    const oa = DOC_ORDER.indexOf(a.slug), ob = DOC_ORDER.indexOf(b.slug);
+    if (oa !== -1 && ob !== -1)
+        return oa - ob;
+    if (oa !== -1)
+        return -1;
+    if (ob !== -1)
+        return 1;
+    return a.slug.localeCompare(b.slug);
+}