canon-ds 0.1.0

package/lib/components/sidebar-nav.mjs

@@ -0,0 +1,172 @@
+import { ex, ICON, typeStyle } from "./_shared.mjs";
+// A compact reading rail with persistent leading markers on current destinations.
+const TRANSITION_FAST = {
+    'transition-property': 'background-color, color, box-shadow',
+    'transition-duration': '{motion.duration.fast}',
+    'transition-timing-function': '{motion.easing.linear}',
+};
+const HAIRLINE = '{border.width.thin} solid {color.border-default}';
+const ring = (color) => `inset 0 0 0 1px ${color}`;
+const icon = (name) => ICON[name].replace('cn-icon', 'cn-sidebar-nav__icon');
+const item = (label, i, attrs = '', count = '') => `<a href="#" class="cn-sidebar-nav__item"${attrs}>${i ? icon(i) : ''}<span class="cn-sidebar-nav__label">${label}</span>${count ? `<span class="cn-sidebar-nav__count">${count}</span>` : ''}</a>`;
+const parent = (label, i, open, children) => `<details class="cn-sidebar-nav__group"${open ? ' open' : ''}><summary class="cn-sidebar-nav__item">${icon(i)}<span class="cn-sidebar-nav__label">${label}</span>${ICON.chevronDown.replace('cn-icon', 'cn-sidebar-nav__chevron')}</summary>${children}</details>`;
+const group = (id, label, items) => `<div class="cn-sidebar-nav__group" role="group"${label ? ` aria-labelledby="${id}"` : ''}>${label ? `<div class="cn-sidebar-nav__group-label" id="${id}">${label}</div>` : ''}${items}</div>`;
+const MAIN = (current = 'Dashboard') => [['Home', 'home'], ['Dashboard', 'calendar'], ['Projects', 'copy'], ['Tasks', 'check', '10'], ['Reporting', 'inbox'], ['Users', 'user']].map(([l, i, c]) => item(l, i, l === current ? ' aria-current="page"' : '', c ?? '')).join('');
+export const sidebarNav = {
+    name: 'SidebarNav',
+    slug: 'sidebar-nav',
+    category: 'navigation',
+    description: 'A grouped navigation rail: a 280px column of 36px link rows (14px semibold, 20px icon, radius 6) grouped with subheadings or dividers, a quiet hover fill and a leading mark on the current destination, with count badges and collapsible children.',
+    usage: 'Use as the nav list of a Sidebar or on its own for the second level of navigation inside a product area (settings sections, a workspace\'s views). Items are answers to what the user wants to do, grouped by job, never a mirror of the data model. For 3–6 top-level destinations use the Topbar instead.',
+    anatomy: [
+        { part: 'root', element: 'nav', description: 'The column: 280px wide, 20 × 16px padding, groups stacked. Has aria-label.' },
+        { part: 'group', element: 'div', description: 'A set of related items with role="group" (or a <details> for a collapsible parent); rows 2px apart, 16px above each group after the first.' },
+        { part: 'group-label', element: 'div', description: 'Subheading naming the group in 12px semibold fg-subtle, 8px inset: "General", "Workspace". Referenced by the group\'s aria-labelledby.', optional: true },
+        { part: 'item', element: 'a', description: 'One destination: a 36px link row (or <summary> for a collapsible parent), padding 8, radius 6, 14px semibold gray-700; holds icon + label + optional count or chevron. data-level="2" indents a child row to 40px.' },
+        { part: 'icon', element: 'svg', description: '20px leading icon, fg-subtle at rest, one step darker when hovered or current. All items in a group have one, or none do.', optional: true },
+        { part: 'label', element: 'span', description: 'The destination name, 1–2 words. Fills the row and truncates with an ellipsis.' },
+        { part: 'count', element: 'span', description: 'Trailing count in a 22px gray badge (12px medium, gray-50, gray-200 ring), 12px after the label. Only for numbers that need action, never totals.', optional: true },
+        { part: 'chevron', element: 'svg', description: '16px chevron-down at the end of a collapsible parent; flips when the <details> is open.', optional: true },
+        { part: 'divider', element: 'hr', description: '1px gray-200 rule between groups (the "dividers" layout), 8px above and below.', optional: true },
+    ],
+    props: {
+        size: {
+            values: ['sm', 'md'],
+            default: 'md',
+            description: 'md = 36px rows, 14px semibold, 20px icons; the default. sm = 32px rows (padding 6 × 8), 14px semibold, 16px icons for dense admin rails and secondary panels.',
+        },
+        variant: {
+            values: ['default', 'inset'],
+            default: 'default',
+            description: 'default = transparent on the surface; hovered and current rows get the gray-50 fill (the default). inset = the whole nav is a gray-50 rail with a hairline on its trailing edge, and the current item uses a surface fill and a leading action-colored rule.',
+        },
+    },
+    states: {
+        hover: { selector: ' .cn-sidebar-nav__item:hover', description: 'Pointer over an item (lives on the ITEM, not the root): gray-50 fill, gray-800 label, gray-500 icon.', markup: 'native :hover on the item' },
+        current: { selector: ' .cn-sidebar-nav__item[aria-current="page"]', description: 'The destination the user is on: gray-50 fill (gray-100 when hovered), ink label, darker icon (inset: white pill with ring and shadow-xs). Exactly one per nav.', markup: 'aria-current="page" on the item' },
+        focus: { selector: ' .cn-sidebar-nav__item:focus-visible', description: 'Keyboard focus on an item: the token-defined focus ring around the row.', markup: 'native :focus-visible on the item' },
+        disabled: { selector: ' .cn-sidebar-nav__item[aria-disabled="true"]', description: 'Destination not available on this plan or not yet set up. 50% opacity, no hover; keep the label so the user knows it exists.', markup: 'aria-disabled="true" on the item (omit href)' },
+    },
+    base: {
+        root: {
+            display: 'flex',
+            'flex-direction': 'column',
+            gap: '{space.4}',
+            width: 'calc({space.64} + {space.6})',
+            'flex-shrink': '0',
+            padding: '{space.5} {space.4}',
+            color: '{color.fg-default}',
+        },
+        group: { display: 'flex', 'flex-direction': 'column', gap: '{space.0.5}' },
+        'group-label': {
+            display: 'block',
+            ...typeStyle('label-xs'),
+            'font-family': '{font.family.mono}',
+            'letter-spacing': '{font.letterSpacing.wide}',
+            'text-transform': 'uppercase',
+            color: '{color.fg-subtle}',
+            padding: '0 {space.2} {space.1}',
+            'user-select': 'none',
+        },
+        item: {
+            position: 'relative',
+            display: 'flex',
+            'align-items': 'center',
+            gap: '{space.2}',
+            width: '100%',
+            'max-height': '{space.9}',
+            padding: '{space.2}',
+            'border-radius': '{radius.md}',
+            ...typeStyle('label-md'),
+            color: '{color.fg-muted}',
+            'background-color': 'transparent',
+            'text-decoration': 'none',
+            cursor: 'pointer',
+            'white-space': 'nowrap',
+            'min-width': '0',
+            'user-select': 'none',
+            'list-style': 'none',
+            ...TRANSITION_FAST,
+        },
+        icon: { width: '{size.icon.md}', height: '{size.icon.md}', 'flex-shrink': '0', color: '{color.fg-subtle}', transition: 'inherit' },
+        label: { flex: '1 1 auto', 'min-width': '0', overflow: 'hidden', 'text-overflow': 'ellipsis', 'white-space': 'nowrap' },
+        count: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            height: '22px',
+            'margin-inline-start': '{space.3}',
+            'margin-block': '-1px',
+            'padding-inline': '{space.2}',
+            'border-radius': '{radius.sm}',
+            'background-color': '{color.bg-subtle}',
+            'box-shadow': ring('{color.border-default}'),
+            ...typeStyle('label-xs'),
+            color: '{color.fg-muted}',
+            'font-variant-numeric': 'tabular-nums',
+            'flex-shrink': '0',
+        },
+        chevron: { width: '{size.icon.sm}', height: '{size.icon.sm}', 'margin-inline-start': '{space.3}', 'flex-shrink': '0', color: '{color.fg-subtle}', 'stroke-width': '2.5', 'transition-property': 'transform', 'transition-duration': '{motion.duration.fast}', 'transition-timing-function': '{motion.easing.linear}' },
+        divider: { border: '0', 'border-top': HAIRLINE, width: '100%', margin: '{space.2} {space.0.5}' },
+    },
+    variants: {
+        size: {
+            sm: {
+                item: { 'max-height': '{space.8}', padding: '{space.1.5} {space.2}' },
+                icon: { width: '{size.icon.sm}', height: '{size.icon.sm}' },
+            },
+            md: { root: {} },
+        },
+        variant: {
+            default: { root: {} },
+            inset: {
+                root: { 'background-color': '{color.bg-subtle}', 'border-inline-end': HAIRLINE },
+            },
+        },
+    },
+    extraCss: `
+.cn-sidebar-nav__item:hover:not([aria-disabled="true"]) { background-color: {color.bg-subtle}; color: {color.fg-default}; }
+.cn-sidebar-nav__item:hover:not([aria-disabled="true"]) .cn-sidebar-nav__icon { color: {color.fg-muted}; }
+.cn-sidebar-nav__item[aria-current="page"] { background-color: {color.bg-action-subtle}; color: {color.fg-action}; box-shadow: inset 2px 0 0 {color.bg-action}; }
+[dir="rtl"] .cn-sidebar-nav__item[aria-current="page"] { box-shadow: inset -2px 0 0 {color.bg-action}; }
+.cn-sidebar-nav__item[aria-current="page"]:hover { background-color: {color.bg-muted}; }
+.cn-sidebar-nav__item[aria-current="page"] .cn-sidebar-nav__icon { color: inherit; }
+.cn-sidebar-nav[data-variant="inset"] .cn-sidebar-nav__item:hover:not([aria-disabled="true"]) { background-color: {color.bg-muted}; }
+.cn-sidebar-nav[data-variant="inset"] .cn-sidebar-nav__item[aria-current="page"] { background-color: {color.bg-surface}; box-shadow: inset 2px 0 0 {color.bg-action}; }
+.cn-sidebar-nav__item:focus-visible { outline: none; box-shadow: {shadow.focus}; z-index: {z.raised}; }
+.cn-sidebar-nav__item[aria-disabled="true"] { opacity: {opacity.disabled}; cursor: not-allowed; pointer-events: none; }
+.cn-sidebar-nav__item[data-level="2"] { padding-inline-start: {space.10}; padding-inline-end: {space.3}; }
+.cn-sidebar-nav[data-size="sm"] .cn-sidebar-nav__item[data-level="2"] { padding-inline-start: {space.8}; }
+details.cn-sidebar-nav__group > summary::-webkit-details-marker { display: none; }
+details.cn-sidebar-nav__group > summary::marker { content: ""; }
+details.cn-sidebar-nav__group[open] > summary .cn-sidebar-nav__chevron { transform: scaleY(-1); }
+details.cn-sidebar-nav__group > .cn-sidebar-nav__item + .cn-sidebar-nav__item { margin-top: {space.0.5}; }`,
+    examples: [
+        ex('Simple list', `<nav class="cn-sidebar-nav" data-variant="default" data-size="md" aria-label="Main">${group('sn-main', null, MAIN())}</nav>`, '36px rows, 14px semibold, 20px icons; Dashboard is current (gray-50), Tasks carries a 22px count badge.'),
+        ex('Sections with subheadings', `<nav class="cn-sidebar-nav" data-variant="default" data-size="md" aria-label="Main">${group('sn-general', 'General', item('Home', 'home') + item('Dashboard', 'calendar', ' aria-current="page"') + item('Tasks', 'check', '', '10'))}${group('sn-ws', 'Workspace', item('Projects', 'copy') + item('Reporting', 'inbox') + item('Users', 'user'))}${group('sn-acct', 'Account', item('Support', 'info') + item('Settings', 'settings'))}</nav>`, 'Groups 16px apart, each with a 12px semibold subheading.'),
+        ex('Dividers and a collapsible parent', `<nav class="cn-sidebar-nav" data-variant="default" data-size="md" aria-label="Main">${group('sn-d1', null, item('Home', 'home') + item('Dashboard', 'calendar'))}<hr class="cn-sidebar-nav__divider">${group('sn-d2', null, parent('Projects', 'copy', true, item('All projects', null, ' data-level="2" aria-current="page"') + item('Shared with me', null, ' data-level="2"') + item('Archived', null, ' data-level="2"')) + item('Reporting', 'inbox') + item('Users', 'user'))}<hr class="cn-sidebar-nav__divider">${group('sn-d3', null, item('Support', 'info') + item('Settings', 'settings'))}</nav>`, 'A <details> group with a <summary> row: the chevron flips when open; child rows are indented to 40px.'),
+        ex('Inset rail, small', `<nav class="cn-sidebar-nav" data-variant="inset" data-size="sm" aria-label="Settings">${group('sn-i1', 'Workspace', item('General', 'settings') + item('Members', 'user', ' aria-current="page"') + item('Billing', 'calendar'))}${group('sn-i2', 'Data', item('Imports', 'inbox') + item('Integrations', 'external') + item('API keys', 'copy'))}</nav>`, 'The rail is gray-50 with a trailing hairline; the current item uses a leading action-colored mark. 32px rows.'),
+        ex('Disabled item and truncation', `<nav class="cn-sidebar-nav" data-variant="default" data-size="md" aria-label="Reports">${group('sn-r', 'Reports', item('Pipeline', 'arrow', ' aria-current="page"') + item('Enterprise procurement pipeline, Q3 review', 'calendar') + `<a class="cn-sidebar-nav__item" aria-disabled="true" title="Available on the Business plan">${icon('spark')}<span class="cn-sidebar-nav__label">Attribution</span></a>`)}</nav>`, 'Long labels truncate; the disabled item keeps its name and explains itself in a title or Tooltip.'),
+    ],
+    rules: [
+        'Max 7 items per group and max 4 groups visible. If the nav needs more, the information architecture is wrong, not the component.',
+        'Never one item per database table. Items are jobs and destinations ("Dashboard", "Reporting", "Billing"), grouped by who uses them and when.',
+        'Labels are 1–2 words, sentence case, nouns. No verbs ("Manage members" → "Members"), no product jargon.',
+        'Rows are 36px (sm 32px) with 8px padding and 2px between them; never change the height with padding.',
+        'Icons are all-or-none within a group, 20px (16px at sm), fg-subtle; never emoji, never colored.',
+        'Counts use the 22px badge and only for what needs action (unread, pending approvals, failed runs), never totals; hide the count at 0.',
+        'Exactly one item carries aria-current="page" at any time, the deepest matching route; a collapsible parent stays open while a child is current.',
+        'Width is fixed at 280px; the content never widens it. Long labels truncate with an ellipsis and get a title attribute.',
+        'Two levels at most: a collapsible parent and its children. Deeper sections are Tabs on the page.',
+        'The first group may go unlabeled (the home set); later groups get a subheading or a divider, not both.',
+    ],
+    a11y: [
+        'Root is <nav aria-label="…"> naming the area ("Main", "Settings"); each group is role="group" with aria-labelledby pointing at its subheading.',
+        'Items are real <a href> links; aria-current="page" marks the current destination and is the only selection state.',
+        'Collapsible parents are <details>/<summary> so they work without JS; the chevron is decorative.',
+        'Disabled items use aria-disabled="true", drop the href, and explain why in a title or Tooltip; they stay in the DOM so the structure is stable.',
+        'Counts are read as part of the link text; add sr-only context when the number is ambiguous ("10 open tasks").',
+        'Keyboard: Tab moves through items in order; no roving tabindex or arrow keys (this is a list of links, not a menu).',
+    ],
+    related: ['sidebar', 'topbar', 'tabs', 'breadcrumb', 'badge'],
+};

package/lib/components/sidebar.mjs

@@ -0,0 +1,124 @@
+import { ex, ICON, typeStyle } from "./_shared.mjs";
+const item = (label, icon, current = false, badge = '') => `<a href="#" class="cn-sidebar__item"${current ? ' aria-current="page"' : ''}>${icon.replace('cn-icon', 'cn-sidebar__icon')}<span class="cn-sidebar__label">${label}</span>${badge ? `<span class="cn-sidebar__badge">${badge}</span>` : ''}</a>`;
+const NAV = `${item('Home', ICON.home)}${item('Dashboard', ICON.calendar, true)}${item('Projects', ICON.copy)}${item('Tasks', ICON.check, false, '10')}${item('Reporting', ICON.inbox)}${item('Users', ICON.user)}`;
+const FOOT = `${item('Support', ICON.info)}${item('Settings', ICON.settings)}`;
+const LOGO = `<div class="cn-sidebar__brand"><span class="cn-sidebar__logo" aria-hidden="true"></span><span class="cn-sidebar__brand-name">Lumen</span></div>`;
+const ACCOUNT = `<div class="cn-sidebar__account"><span class="cn-sidebar__avatar" aria-hidden="true">MC</span><div class="cn-sidebar__account-text"><span class="cn-sidebar__name">Maya Chen</span><span class="cn-sidebar__email">maya@lumen.co</span></div><button type="button" class="cn-sidebar__account-action" aria-label="Log out">${ICON.external}</button></div>`;
+const SEARCH = `<div class="cn-sidebar__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"></div>`;
+export const sidebar = {
+    name: 'Sidebar',
+    slug: 'sidebar',
+    category: 'navigation',
+    description: 'The application sidebar family of the system: a 280px column with logo, search, navigation items matching SidebarNav (36px, label-md, 20px icons), a bottom group and an account card; slim 68px rail; dual-tier rail + panel; sections with subheadings; dark theme.',
+    usage: 'Primary navigation of an application with more than 5 destinations. For 3–5 destinations prefer the Topbar with tabs. Groups: main destinations at top, support/settings at the bottom, account card last. Never one item per database table; items are user tasks.',
+    anatomy: [
+        { part: 'root', element: 'nav', description: 'The column: flex column, full height, right hairline.' },
+        { part: 'brand', element: 'div', description: 'Logo row at the top (32px logo + name).' },
+        { part: 'logo', element: 'span', description: '32px brand mark.' },
+        { part: 'brand-name', element: 'span', description: 'Product name, label-lg semibold (hidden in slim).' },
+        { part: 'search', element: 'div', description: 'Optional search Input under the logo.', optional: true },
+        { part: 'nav', element: 'div', description: 'Main list of items (flex column, gap 2px).' },
+        { part: 'section', element: 'div', description: 'A group with a subheading (sections variant).', optional: true },
+        { part: 'heading', element: 'div', description: 'Group subheading: label-xs in fg-subtle, 8px horizontal padding.', optional: true },
+        { part: 'item', element: 'a', description: 'Nav item: 36px, 8px horizontal padding and gap, radius 6, label-md (14px medium by default), fg-muted; icon + label + optional badge.' },
+        { part: 'icon', element: 'svg', description: '20px icon in fg-subtle (fg-muted when current).' },
+        { part: 'label', element: 'span', description: 'The item text, truncated.' },
+        { part: 'badge', element: 'span', description: 'Trailing count pill (22px, bg-subtle, body-xs).', optional: true },
+        { part: 'divider', element: 'hr', description: 'Hairline between groups (dividers variant).', optional: true },
+        { part: 'footer', element: 'div', description: 'Bottom group: support/settings items then the account card.' },
+        { part: 'account', element: 'div', description: 'Account card: avatar 40, name + email, trailing log-out icon; bordered card in the default theme.' },
+        { part: 'avatar', element: 'span', description: '40px circle with initials or image.' },
+        { part: 'account-text', element: 'div', description: 'Name and email column.' },
+        { part: 'name', element: 'span', description: 'label-sm semibold.' },
+        { part: 'email', element: 'span', description: 'body-sm fg-muted, truncated.' },
+        { part: 'account-action', element: 'button', description: '36px utility button (log out / ⋯).' },
+        { part: 'rail', element: 'div', description: 'The 68px icon-only column of the dual-tier variant.', optional: true },
+        { part: 'panel', element: 'div', description: 'The 256px second-tier panel of the dual-tier variant.', optional: true },
+        { part: 'rail-item', element: 'a', description: '48px square icon button with a 20px icon in a rail.', optional: true },
+    ],
+    props: {
+        variant: { values: ['simple', 'slim', 'dual-tier', 'sections', 'dividers'], default: 'simple', description: 'simple = one flat list (280px); slim = 68px icon rail with tooltips; dual-tier = 68px rail + 256px panel for the active area; sections = groups with subheadings; dividers = groups separated by hairlines.' },
+        theme: { values: ['light', 'dark', 'brand'], default: 'light', description: 'light = white; dark = gray-950 surface with gray-800 borders; brand = brand-700 surface (marketing-style app).' },
+    },
+    states: {
+        current: { selector: ' .cn-sidebar__item[aria-current="page"]', description: 'The active destination: subtle fill, fg-default, icon fg-muted.', markup: 'aria-current="page" on the item' },
+        hover: { selector: ' .cn-sidebar__item:hover', description: 'Subtle fill.', markup: 'native' },
+        focus: { selector: ' .cn-sidebar__item:focus-visible', description: 'Focus ring.', markup: 'native' },
+    },
+    base: {
+        root: { display: 'flex', 'flex-direction': 'column', width: 'calc({space.64} + {space.6})', 'min-height': '640px', 'background-color': '{color.bg-surface}', 'border-inline-end': '{border.width.thin} solid {color.border-default}', padding: '{space.5} {space.4} {space.6}', gap: '{space.5}', 'flex-shrink': '0' },
+        brand: { display: 'flex', 'align-items': 'center', gap: '{space.2.5}', 'padding-inline': '{space.2}', height: '32px' },
+        logo: { width: '32px', height: '32px', 'border-radius': '{radius.lg}', 'background-color': '{color.bg-action}', 'flex-shrink': '0' },
+        'brand-name': { ...typeStyle('label-lg'), color: '{color.fg-default}' },
+        search: { width: '100%' },
+        nav: { display: 'flex', 'flex-direction': 'column', gap: '{space.0.5}', flex: '1 1 auto', 'min-height': '0' },
+        section: { display: 'flex', 'flex-direction': 'column', gap: '{space.0.5}', 'margin-top': '{space.4}' },
+        heading: { ...typeStyle('label-xs'), color: '{color.fg-subtle}', padding: '0 {space.2} {space.1}' },
+        item: { display: 'flex', 'align-items': 'center', gap: '{space.2}', height: '{space.9}', 'padding-inline': '{space.2}', 'border-radius': '{radius.md}', ...typeStyle('label-md'), color: '{color.fg-muted}', 'text-decoration': 'none', 'transition-property': 'background-color, color', 'transition-duration': '{motion.duration.fast}', 'transition-timing-function': '{motion.easing.standard}' },
+        icon: { width: '{size.icon.md}', height: '{size.icon.md}', 'flex-shrink': '0', color: '{color.fg-subtle}' },
+        label: { flex: '1 1 auto', 'min-width': '0', overflow: 'hidden', 'text-overflow': 'ellipsis', 'white-space': 'nowrap' },
+        badge: { display: 'inline-flex', 'align-items': 'center', height: '22px', 'padding-inline': '{space.2}', 'border-radius': '{radius.full}', 'background-color': '{color.bg-subtle}', border: '{border.width.thin} solid {color.border-default}', ...typeStyle('body-xs'), 'font-weight': '{font.weight.medium}', color: '{color.fg-muted}' },
+        divider: { border: '0', 'border-top': '{border.width.thin} solid {color.border-default}', margin: '{space.3} 0' },
+        footer: { display: 'flex', 'flex-direction': 'column', gap: '{space.0.5}', 'padding-top': '{space.4}' },
+        account: { display: 'flex', 'align-items': 'center', gap: '{space.3}', padding: '{space.3}', 'margin-top': '{space.4}', 'border-radius': '{radius.card}', border: '{border.width.thin} solid {color.border-default}', 'background-color': '{color.bg-surface}', 'box-shadow': '{shadow.xs}' },
+        avatar: { display: 'inline-flex', 'align-items': 'center', 'justify-content': 'center', width: '40px', height: '40px', 'border-radius': '{radius.full}', 'background-color': '{color.bg-accent-subtle}', color: '{color.fg-accent}', ...typeStyle('label-sm'), 'flex-shrink': '0' },
+        'account-text': { display: 'flex', 'flex-direction': 'column', 'min-width': '0', flex: '1 1 auto' },
+        name: { ...typeStyle('label-sm'), color: '{color.fg-default}', overflow: 'hidden', 'text-overflow': 'ellipsis', 'white-space': 'nowrap' },
+        email: { ...typeStyle('body-sm'), color: '{color.fg-muted}', overflow: 'hidden', 'text-overflow': 'ellipsis', 'white-space': 'nowrap' },
+        'account-action': { appearance: 'none', border: '0', padding: '0', margin: '0', background: 'none', cursor: 'pointer', display: 'inline-flex', 'align-items': 'center', 'justify-content': 'center', width: '36px', height: '36px', 'border-radius': '{radius.md}', color: '{color.fg-subtle}', 'flex-shrink': '0' },
+        rail: { display: 'flex', 'flex-direction': 'column', 'align-items': 'center', gap: '{space.1}', width: '68px', padding: '{space.5} {space.2.5}', 'border-inline-end': '{border.width.thin} solid {color.border-default}' },
+        panel: { display: 'flex', 'flex-direction': 'column', gap: '{space.0.5}', width: '256px', padding: '{space.5} {space.4}' },
+        'rail-item': { display: 'inline-flex', 'align-items': 'center', 'justify-content': 'center', width: '48px', height: '48px', 'border-radius': '{radius.md}', color: '{color.fg-subtle}' },
+        '@states': {
+            current: { item: { 'background-color': '{color.bg-action-subtle}', color: '{color.fg-action}', 'box-shadow': 'inset 2px 0 0 currentColor' } },
+            hover: { item: { 'background-color': '{color.bg-subtle}', color: '{color.fg-default}' } },
+            focus: { item: { outline: 'none', 'box-shadow': '{shadow.focus}' } },
+        },
+    },
+    variants: {
+        variant: {
+            simple: { root: {} },
+            slim: { root: { width: '68px', 'align-items': 'center', padding: '{space.5} {space.2.5} {space.6}' }, item: { width: '48px', height: '48px', 'justify-content': 'center', 'padding-inline': '0' }, account: { padding: '0', border: '0', 'box-shadow': 'none', 'margin-top': '{space.4}' }, search: { display: 'none' } },
+            'dual-tier': { root: { 'flex-direction': 'row', width: 'auto', padding: '0', gap: '0' } },
+            sections: { root: {} },
+            dividers: { root: {} },
+        },
+        theme: {
+            light: { root: {} },
+            dark: { root: { 'background-color': '{neutral.950}', 'border-color': '{neutral.800}', color: '{neutral.100}' }, 'brand-name': { color: '{white}' }, item: { color: '{neutral.100}' }, icon: { color: '{neutral.400}' }, heading: { color: '{neutral.500}' }, badge: { 'background-color': '{neutral.800}', 'border-color': '{neutral.700}', color: '{neutral.200}' }, divider: { 'border-color': '{neutral.800}' }, account: { 'border-color': '{neutral.800}', 'background-color': '{neutral.950}' }, name: { color: '{white}' }, email: { color: '{neutral.400}' }, rail: { 'border-color': '{neutral.800}' }, 'account-action': { color: '{neutral.400}' }, '@states': { current: { item: { 'background-color': '{neutral.800}', color: '{white}' } }, hover: { item: { 'background-color': '{neutral.800}', color: '{white}' } } } },
+            brand: { root: { 'background-color': '{brand.700}', 'border-color': '{brand.600}', color: '{white}' }, 'brand-name': { color: '{white}' }, logo: { 'background-color': '{white}' }, item: { color: '{brand.100}' }, icon: { color: '{brand.300}' }, heading: { color: '{brand.300}' }, badge: { 'background-color': '{brand.600}', 'border-color': '{brand.500}', color: '{white}' }, divider: { 'border-color': '{brand.600}' }, account: { 'border-color': '{brand.600}', 'background-color': '{brand.700}' }, avatar: { 'background-color': '{brand.500}', color: '{white}' }, name: { color: '{white}' }, email: { color: '{brand.200}' }, 'account-action': { color: '{brand.200}' }, '@states': { current: { item: { 'background-color': '{brand.600}', color: '{white}' } }, hover: { item: { 'background-color': '{brand.600}', color: '{white}' } } } },
+        },
+    },
+    extraCss: `
+.cn-sidebar__logo { clip-path: polygon(0 0, 100% 0, 100% 22%, 27% 22%, 27% 78%, 100% 78%, 100% 100%, 0 100%); border-radius: 0; }
+[dir="rtl"] .cn-sidebar__item[aria-current="page"] { box-shadow: inset -2px 0 0 currentColor; }
+.cn-sidebar[data-variant="slim"] .cn-sidebar__label, .cn-sidebar[data-variant="slim"] .cn-sidebar__badge, .cn-sidebar[data-variant="slim"] .cn-sidebar__brand-name, .cn-sidebar[data-variant="slim"] .cn-sidebar__account-text, .cn-sidebar[data-variant="slim"] .cn-sidebar__account-action { display: none; }
+.cn-sidebar[data-variant="slim"] .cn-sidebar__brand { padding-inline: 0; }
+.cn-sidebar[data-variant="slim"] .cn-sidebar__footer { align-items: center; }
+.cn-sidebar__rail-item > svg { width: {size.icon.md}; height: {size.icon.md}; }
+.cn-sidebar[data-variant="dual-tier"] .cn-sidebar__rail-item[aria-current="page"], .cn-sidebar__rail-item:hover { background-color: {color.bg-subtle}; color: {color.fg-default}; }
+.cn-sidebar[data-variant="dual-tier"] .cn-sidebar__panel .cn-sidebar__heading { padding-inline: {space.2}; margin-bottom: {space.2}; font-size: {font.size.md}; font-weight: {font.weight.semibold}; color: {color.fg-default}; }
+.cn-sidebar__item[aria-current="page"] .cn-sidebar__icon { color: inherit; }
+.cn-sidebar[data-theme="dark"] .cn-sidebar__item[aria-current="page"] .cn-sidebar__icon, .cn-sidebar[data-theme="brand"] .cn-sidebar__item[aria-current="page"] .cn-sidebar__icon { color: currentColor; }
+.cn-sidebar__account-action:hover { background-color: {color.bg-subtle}; color: {color.fg-muted}; }
+.cn-sidebar[data-theme="dark"] .cn-sidebar__search .cn-input { background-color: {neutral.900}; border-color: {neutral.700}; color: {white}; }
+.cn-sidebar[data-theme="brand"] .cn-sidebar__search .cn-input { background-color: {brand.600}; border-color: {brand.500}; color: {white}; }`,
+    examples: [
+        ex('Simple', `<nav class="cn-sidebar" data-variant="simple" data-theme="light" aria-label="Main">${LOGO}${SEARCH}<div class="cn-sidebar__nav">${NAV}</div><div class="cn-sidebar__footer">${FOOT}${ACCOUNT}</div></nav>`),
+        ex('Sections with subheadings', `<nav class="cn-sidebar" data-variant="sections" data-theme="light" aria-label="Main">${LOGO}<div class="cn-sidebar__nav"><div class="cn-sidebar__section"><div class="cn-sidebar__heading">General</div>${item('Home', ICON.home)}${item('Dashboard', ICON.calendar, true)}${item('Tasks', ICON.check, false, '10')}</div><div class="cn-sidebar__section"><div class="cn-sidebar__heading">Workspace</div>${item('Projects', ICON.copy)}${item('Reporting', ICON.inbox)}${item('Users', ICON.user)}</div></div><div class="cn-sidebar__footer">${FOOT}${ACCOUNT}</div></nav>`),
+        ex('Dividers', `<nav class="cn-sidebar" data-variant="dividers" data-theme="light" aria-label="Main">${LOGO}<div class="cn-sidebar__nav">${item('Home', ICON.home)}${item('Dashboard', ICON.calendar, true)}<hr class="cn-sidebar__divider">${item('Projects', ICON.copy)}${item('Tasks', ICON.check, false, '10')}${item('Reporting', ICON.inbox)}<hr class="cn-sidebar__divider">${item('Users', ICON.user)}</div><div class="cn-sidebar__footer">${FOOT}${ACCOUNT}</div></nav>`),
+        ex('Slim rail', `<nav class="cn-sidebar" data-variant="slim" data-theme="light" aria-label="Main">${LOGO}<div class="cn-sidebar__nav">${item('Home', ICON.home)}${item('Dashboard', ICON.calendar, true)}${item('Projects', ICON.copy)}${item('Tasks', ICON.check)}${item('Reporting', ICON.inbox)}${item('Users', ICON.user)}</div><div class="cn-sidebar__footer">${FOOT}${ACCOUNT}</div></nav>`),
+        ex('Dual tier', `<nav class="cn-sidebar" data-variant="dual-tier" data-theme="light" aria-label="Main"><div class="cn-sidebar__rail"><span class="cn-sidebar__logo" aria-hidden="true"></span><a href="#" class="cn-sidebar__rail-item" aria-label="Home">${ICON.home}</a><a href="#" class="cn-sidebar__rail-item" aria-current="page" aria-label="Projects">${ICON.copy}</a><a href="#" class="cn-sidebar__rail-item" aria-label="Reporting">${ICON.inbox}</a><a href="#" class="cn-sidebar__rail-item" aria-label="Settings">${ICON.settings}</a></div><div class="cn-sidebar__panel"><div class="cn-sidebar__heading">Projects</div>${item('All projects', ICON.copy, true, '24')}${item('Archived', ICON.inbox)}${item('Shared with me', ICON.user)}${item('Templates', ICON.calendar)}</div></nav>`),
+        ex('Dark theme', `<nav class="cn-sidebar" data-variant="simple" data-theme="dark" aria-label="Main">${LOGO}${SEARCH}<div class="cn-sidebar__nav">${NAV}</div><div class="cn-sidebar__footer">${FOOT}${ACCOUNT}</div></nav>`),
+        ex('Brand theme', `<nav class="cn-sidebar" data-variant="simple" data-theme="brand" aria-label="Main">${LOGO}<div class="cn-sidebar__nav">${NAV}</div><div class="cn-sidebar__footer">${FOOT}${ACCOUNT}</div></nav>`),
+    ],
+    rules: [
+        'Width 280px, matching SidebarNav. Slim rail 68px. Dual tier 68 + 256. The sidebar never scrolls the page; its own nav scrolls.',
+        'Items match SidebarNav: 36px tall with a 20px icon, 8px gap and horizontal padding, label-md typography, and 2px between rows. The current item carries a leading rule and action-tinted surface; hover uses a quiet neutral fill.',
+        'Order: logo, optional search, main items (≤ 7), sections, then the footer with Support/Settings and the account card.',
+        'Counts use the badge part; never red dots for ordinary counts.',
+        'On tablets collapse to the slim rail; on mobile replace with the MobileHeader drawer.',
+    ],
+    a11y: ['<nav aria-label="Main">; the current item carries aria-current="page".', 'Slim rail items are icon-only and need aria-label (and a Tooltip on hover).', 'The account log-out control is a labelled button.'],
+    related: ['sidebar-nav', 'topbar', 'account-card', 'mobile-header', 'input'],
+};

package/lib/components/skeleton.mjs

@@ -0,0 +1,66 @@
+import { ex } from "./_shared.mjs";
+export const skeleton = {
+    name: 'Skeleton',
+    slug: 'skeleton',
+    category: 'feedback',
+    description: 'Grey placeholder shapes that hold the layout while content loads: text lines, a circle, a rectangle or a card, with a slow shimmer sweeping across. Same size as the content they stand in for, so nothing jumps when it arrives.',
+    usage: 'Use when the shape of the incoming content is known (a list, a card, a profile header) and the wait is over ~300ms. For a wait with no known layout use Spinner; for a measurable task use Progress. Never leave skeletons on screen after an error; replace them with an empty state or an Alert.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'One placeholder block. aria-hidden="true"; the region around it carries aria-busy. Size comes from the variant plus inline width/height.' },
+    ],
+    props: {
+        variant: {
+            values: ['text', 'circle', 'rect', 'card'],
+            default: 'text',
+            description: 'text = one line, 1em tall, radius sm, full width (set width inline for the last line); circle = 40px avatar placeholder, radius full; rect = a box with radius md for images, inputs and buttons (size inline); card = radius xl, min-height 120px, for a whole card.',
+        },
+    },
+    states: {},
+    base: {
+        root: {
+            display: 'block',
+            'flex-shrink': '0',
+            'background-color': '{color.bg-muted}',
+            'background-image': 'linear-gradient(90deg, {color.bg-muted} 0%, {color.bg-subtle} 50%, {color.bg-muted} 100%)',
+            'background-size': '200% 100%',
+            'border-radius': '{radius.md}',
+            animation: 'cn-skeleton-shimmer 1.4s ease-in-out infinite',
+        },
+    },
+    variants: {
+        variant: {
+            text: { root: { height: '1em', width: '100%', 'border-radius': '{radius.sm}' } },
+            circle: { root: { width: '{size.icon.2xl}', height: '{size.icon.2xl}', 'border-radius': '{radius.full}' } },
+            rect: { root: { 'border-radius': '{radius.md}' } },
+            card: { root: { 'border-radius': '{radius.xl}', 'min-height': '120px', width: '100%' } },
+        },
+    },
+    extraCss: `
+@keyframes cn-skeleton-shimmer { from { background-position: 200% 0; } to { background-position: -200% 0; } }
+.cn-skeleton + .cn-skeleton[data-variant="text"] { margin-top: {space.2}; }`,
+    examples: [
+        ex('Text lines', `<div style="width:320px" aria-busy="true"><div class="cn-skeleton" data-variant="text" aria-hidden="true"></div><div class="cn-skeleton" data-variant="text" aria-hidden="true"></div><div class="cn-skeleton" data-variant="text" aria-hidden="true" style="width:60%"></div></div>`, 'Consecutive text skeletons space themselves 8px apart. The last line is shorter.'),
+        ex('Circle', `<div class="cn-skeleton" data-variant="circle" aria-hidden="true"></div>`),
+        ex('Rect (image or control)', `<div class="cn-skeleton" data-variant="rect" aria-hidden="true" style="width:240px;height:36px"></div>`),
+        ex('Card', `<div class="cn-skeleton" data-variant="card" aria-hidden="true" style="width:320px;height:140px"></div>`),
+    ],
+    recipes: [
+        ex('List row (circle + two lines)', `<div style="display:flex;align-items:center;gap:var(--cn-space-3);width:360px" aria-busy="true"><div class="cn-skeleton" data-variant="circle" aria-hidden="true"></div><div style="flex:1;min-width:0"><div class="cn-skeleton" data-variant="text" aria-hidden="true" style="width:45%"></div><div class="cn-skeleton" data-variant="text" aria-hidden="true" style="width:70%;height:0.85em"></div></div></div>`, 'Mirrors a prospect row: avatar, name, one line of meta. Repeat it 3–5 times, never more.'),
+        ex('Card with header', `<section class="cn-card" data-variant="default" data-padding="md" style="max-width:360px" aria-busy="true"><div class="cn-card__body"><div class="cn-skeleton" data-variant="text" aria-hidden="true" style="width:40%;height:1.25em"></div><div class="cn-skeleton" data-variant="text" aria-hidden="true" style="width:80%"></div><div class="cn-skeleton" data-variant="text" aria-hidden="true" style="width:65%"></div><div class="cn-skeleton" data-variant="rect" aria-hidden="true" style="width:120px;height:32px;margin-top:var(--cn-space-4)"></div></div></section>`),
+    ],
+    rules: [
+        'Match the real content: same widths, same line count, same avatar size. A skeleton that does not match the layout causes a jump and is worse than a spinner.',
+        'Show 3–5 rows for a list, never the whole page. Below the fold the real content can arrive silently.',
+        'Do not show skeletons for waits under 300ms, and keep them at least 500ms once shown to avoid flicker.',
+        'One shimmer rhythm for the whole page (1.4s); all skeletons animate in sync because they share one keyframe.',
+        'Vary text widths (100%, 60%, 80%); identical lines look like a table, not text.',
+        'Never put skeletons inside a Button, a Badge or a Toast.',
+        'Errors replace skeletons with an Alert or an empty state; they never stay on screen.',
+    ],
+    a11y: [
+        'aria-hidden="true" on every skeleton; put aria-busy="true" on the region that is loading and remove it when content arrives.',
+        'Announce the loaded state through a live region only when the wait was long (more than a few seconds).',
+        'The shimmer stops under prefers-reduced-motion (base.css); the grey shapes remain.',
+    ],
+    related: ['spinner', 'progress', 'card'],
+};

package/lib/components/slider.mjs

@@ -0,0 +1,122 @@
+import { ex, typeStyle } from "./_shared.mjs";
+// the reference slider: 8px gray-200 rail with a brand-600 fill, a 24px white thumb with a 2px brand
+// ring and shadow-md (grab / grabbing cursor), and an optional value label — bottom (16px medium
+// under the thumb) or top (a floating white chip with shadow-lg and a hairline ring above it).
+// Focus = 4px brand ring on the thumb; disabled = whole control at 50%.
+const THUMB = `box-sizing: border-box; width: {space.6}; height: {space.6}; border-radius: {radius.full}; background-color: {white}; border: 0; box-shadow: inset 0 0 0 2px {color.bg-action}, {shadow.md}; cursor: grab; transition: box-shadow {motion.duration.fast} {motion.easing.linear};`;
+const TRACK = `height: {space.2}; border-radius: {radius.full}; background: linear-gradient(to right, {color.bg-action} var(--cn-slider-fill), {color.border-default} var(--cn-slider-fill));`;
+const THUMB_FOCUS = `box-shadow: inset 0 0 0 2px {color.bg-action}, {shadow.md}, {shadow.focus};`;
+/** Where the floating labels sit: under the thumb centre, clamped so they never leave the track. */
+const LABEL_LEFT = 'clamp({space.3}, var(--cn-slider-fill), calc(100% - {space.3}))';
+const slider_ = (attrs, fill, value = '', label = 'right', style = 'max-width:360px', root = '') => `<div class="cn-slider" data-label="${label}" style="--cn-slider-fill: ${fill};${style}" ${root}><input class="cn-slider__field" type="range" ${attrs}>${value ? `<output class="cn-slider__value" for="${attrs.match(/id="([^"]+)"/)?.[1] ?? ''}">${value}</output>` : ''}</div>`;
+export const slider = {
+    name: 'Slider',
+    slug: 'slider',
+    category: 'forms',
+    description: 'Native range input with an 8px gray-200 rail, a brand fill up to the current value and a 24px white thumb with a 2px brand ring and shadow-md. The value can sit at the right, under the thumb or in a floating chip above it.',
+    usage: 'Pick a value from a continuous or coarse range where the feel matters more than the exact figure (a threshold, a budget band, opacity, volume). For exact numbers use Input type="number"; for a few discrete options use SegmentedControl or Radio. Pair with Field for the label.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'Flex row holding the range input and, optionally, the readout. Carries --cn-slider-fill (the value as a percentage), data-label and data-disabled.' },
+        { part: 'field', element: 'input', description: 'The native <input type="range">, 24px tall. Rail and thumb are styled through pseudo-elements; the fill comes from the --cn-slider-fill custom property.' },
+        { part: 'value', element: 'output', description: 'Optional readout (<output for="<input id>">): right = 14px medium tabular text beside the track; bottom = 16px medium text centred under the thumb; top = a floating 12px semibold chip above the thumb (white, radius 8, shadow-lg, hairline ring).', optional: true },
+    ],
+    props: {
+        label: { values: ['right', 'bottom', 'top', 'none'], default: 'right', description: 'Where the value readout sits. right = beside the track (default, tabular so it never jumps); bottom = centred under the thumb (the reference "bottom"); top = a floating chip above the thumb (the reference "top-floating"); none = hidden (put the value in the Field label instead).' },
+    },
+    states: {
+        focus: { selector: ':has(:focus-visible)', description: 'Keyboard focus: the 4px brand ring around the thumb; the readout turns to the default ink.', markup: 'native :focus-visible on the input' },
+        active: { selector: ':has(:active)', description: 'While dragging: the thumb shows the grabbing cursor.', markup: 'native :active on the input' },
+        disabled: { selector: '[data-disabled], &:has(:disabled)', description: 'Whole control at 50% opacity, cursor not-allowed.', markup: 'disabled on the input' },
+    },
+    base: {
+        root: { position: 'relative', display: 'flex', 'align-items': 'center', gap: '{space.3}', width: '100%', 'min-width': '0', color: '{color.fg-default}' },
+        field: {
+            appearance: 'none',
+            '-webkit-appearance': 'none',
+            flex: '1 1 auto',
+            width: '100%',
+            'min-width': '0',
+            height: '{space.6}',
+            margin: '0',
+            padding: '0',
+            background: 'transparent',
+            outline: 'none',
+            cursor: 'pointer',
+        },
+        value: { ...typeStyle('label-sm'), color: '{color.fg-muted}', 'min-width': '{space.10}', 'text-align': 'end', 'flex-shrink': '0', 'white-space': 'nowrap', 'font-variant-numeric': 'tabular-nums' },
+        '@states': {
+            focus: { value: { color: '{color.fg-default}' } },
+            active: { field: { cursor: 'grabbing' } },
+            disabled: { root: { opacity: '{opacity.disabled}', cursor: 'not-allowed' }, field: { cursor: 'not-allowed' } },
+        },
+    },
+    variants: {
+        label: {
+            right: { value: {} },
+            bottom: {
+                root: { 'margin-block-end': '{space.8}' },
+                value: { position: 'absolute', top: 'calc(100% + {space.2})', left: LABEL_LEFT, transform: 'translateX(-50%)', 'min-width': '0', ...typeStyle('body-lg'), 'font-weight': '{font.weight.medium}', color: '{color.fg-default}', 'text-align': 'center' },
+            },
+            top: {
+                root: { 'margin-block-start': '{space.10}' },
+                value: {
+                    position: 'absolute',
+                    bottom: 'calc(100% + {space.2})',
+                    left: LABEL_LEFT,
+                    transform: 'translateX(-50%)',
+                    'min-width': '0',
+                    padding: '{space.1.5} {space.2}',
+                    'border-radius': '{radius.panel}',
+                    'background-color': '{color.bg-surface}',
+                    ...typeStyle('label-xs'),
+                    'font-weight': '{font.weight.semibold}',
+                    color: '{color.fg-muted}',
+                    'text-align': 'center',
+                    'box-shadow': '{shadow.lg}, inset 0 0 0 1px {color.border-default}',
+                },
+            },
+            none: { value: { display: 'none' } },
+        },
+    },
+    extraCss: `
+.cn-slider { --cn-slider-fill: 0%; }
+.cn-slider .cn-slider__field::-webkit-slider-runnable-track { ${TRACK} }
+.cn-slider .cn-slider__field::-moz-range-track { ${TRACK} }
+.cn-slider .cn-slider__field::-webkit-slider-thumb { -webkit-appearance: none; appearance: none; margin-top: calc(({space.2} - {space.6}) / 2); ${THUMB} }
+.cn-slider .cn-slider__field::-moz-range-thumb { ${THUMB} }
+.cn-slider .cn-slider__field:active:not(:disabled)::-webkit-slider-thumb { cursor: grabbing; }
+.cn-slider .cn-slider__field:active:not(:disabled)::-moz-range-thumb { cursor: grabbing; }
+.cn-slider .cn-slider__field:focus-visible::-webkit-slider-thumb { ${THUMB_FOCUS} }
+.cn-slider .cn-slider__field:focus-visible::-moz-range-thumb { ${THUMB_FOCUS} }
+.cn-slider .cn-slider__field:disabled::-webkit-slider-thumb { cursor: not-allowed; }
+.cn-slider .cn-slider__field:disabled::-moz-range-thumb { cursor: not-allowed; }`,
+    examples: [
+        ex('With value at the right', slider_('id="sl-score" min="0" max="100" step="1" value="40" aria-label="Minimum confidence"', '40%', '40%'), '8px gray-200 rail, brand fill, 24px white thumb with a 2px brand ring and shadow-md. Set --cn-slider-fill on the root to (value − min) ÷ (max − min).'),
+        ex('Label under the thumb', slider_('id="sl-bottom" min="0" max="100" step="5" value="65" aria-label="Storage quota"', '65%', '65%', 'bottom'), 'The reference "bottom" label: 16px medium, centred under the thumb, 8px below the track.'),
+        ex('Floating label above', slider_('id="sl-top" min="0" max="100" step="1" value="25" aria-label="Opacity"', '25%', '25%', 'top'), 'The reference "top-floating" label: a white chip with radius 8, shadow-lg and a hairline ring, 12px semibold.'),
+        ex('Without readout', slider_('min="0" max="10" step="1" value="7" aria-label="Notification intensity" aria-valuetext="7 of 10"', '70%', '', 'none'), 'Put the value in the Field label or the captions instead.'),
+        ex('Stepped (budget band)', slider_('id="sl-budget" min="5000" max="50000" step="5000" value="20000" aria-label="Monthly budget" aria-valuetext="$20,000"', '33.3%', '$20k'), 'Use step for coarse ranges; format the readout with its unit.'),
+        ex('Disabled', slider_('id="sl-locked" min="0" max="100" value="60" disabled aria-label="Sending rate"', '60%', '60%', 'right', 'max-width:360px', 'data-disabled'), 'Whole control at 50% opacity.'),
+    ],
+    recipes: [
+        ex('In a Field with range captions', `<div class="cn-field" data-layout="vertical" data-size="md" style="max-width:360px"><label class="cn-field__label" for="sl-threshold">Auto-publish confidence</label><div class="cn-field__control"><div class="cn-slider" data-label="right" style="--cn-slider-fill: 70%"><input class="cn-slider__field" id="sl-threshold" type="range" min="50" max="100" step="5" value="85" aria-describedby="sl-threshold-helper"><output class="cn-slider__value" for="sl-threshold">85%</output></div><div class="cn-text-body-sm" style="display:flex;justify-content:space-between;color:var(--cn-color-fg-subtle);margin-top:var(--cn-space-1)"><span>50% · more drafts</span><span>100% · safer</span></div></div><p class="cn-field__helper" id="sl-threshold-helper">Drafts below this confidence wait for Sofia Almeida’s approval.</p></div>`, 'Label from the Field, captions under the track in 12px, hint explains the consequence.'),
+    ],
+    rules: [
+        'Set --cn-slider-fill on the root (or on the input for label="right") to (value − min) ÷ (max − min) × 100% and update it on every input event. Without it the rail shows no fill and the floating labels sit at the start.',
+        'Always show the value somewhere: the readout (right, bottom or top), the Field label ("Threshold: 40") or captions. A slider without a number is a toy.',
+        'Use step for coarse ranges (budget bands, percentages in fives). Never a slider for exact figures (prices, dates, quantities under 20): use Input type="number".',
+        'The right readout is 14px medium, tabular, at least 40px wide so it does not jump between 9 and 10. Format with the unit ($20k, 85%).',
+        'Bottom and top labels follow the thumb; leave 32px (bottom) or 40px (top) of room, which the variant reserves with a margin.',
+        'Width comes from the Field: minimum 160px, ideal 240–360px, never full width on desktop.',
+        'One slider per row. A two-thumb range is a separate component (RangeSlider), not two sliders side by side.',
+        'Motion: none on the thumb position (it follows the pointer); only the focus ring transitions (100ms).',
+    ],
+    a11y: [
+        'Keep the native <input type="range">: it exposes role slider with min, max and the current value for free.',
+        'Give it an accessible name (Field label with for, or aria-label) and aria-valuetext when the number needs a unit ("$20,000", "7 of 10").',
+        'Keyboard: arrows move one step, Page Up/Down ten steps, Home/End jump to the ends. Do not override these.',
+        'The <output for> ties the readout to the input; update its text whenever the value changes.',
+        'The 4px focus ring on the thumb must stay visible in both themes; never set outline: none without the ring.',
+    ],
+    related: ['input', 'field', 'segmented-control'],
+};