canon-ds 0.1.0

package/lib/components/rich-text-editor.mjs

@@ -0,0 +1,178 @@
+import { FOCUS_RING, RESET_BUTTON, TRANSITION_COLORS, ex, ICON, typeStyle } from "./_shared.mjs";
+// Rich text editor: an Input-like frame (border-control, radius card, focus ring
+// on :focus-within) with a wrapping toolbar of 32px ghost tool buttons grouped by
+// hairlines, a block-type Select, a contenteditable area with a placeholder and
+// prose styles, and an optional footer with a character count and actions.
+const HAIRLINE = '{border.width.thin} solid {color.border-default}';
+const decl = (d) => Object.entries(d).map(([k, v]) => `${k}: ${v};`).join(' ');
+const glyph = (text, attrs = '') => `<svg class="cn-icon" viewBox="0 0 16 16" aria-hidden="true"><text x="8" y="12" text-anchor="middle" font-size="12" fill="currentColor" font-family="inherit" ${attrs}>${text}</text></svg>`;
+const SVG = {
+    bold: glyph('B', 'font-weight="700"'),
+    italic: glyph('I', 'font-style="italic" font-weight="500"'),
+    underline: glyph('U', 'text-decoration="underline" font-weight="500"'),
+    h1: glyph('H1', 'font-size="9" font-weight="700"'),
+    h2: glyph('H2', 'font-size="9" font-weight="700"'),
+    bullets: '<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="M6 4h7M6 8h7M6 12h7"/><circle cx="3" cy="4" r=".9" fill="currentColor" stroke="none"/><circle cx="3" cy="8" r=".9" fill="currentColor" stroke="none"/><circle cx="3" cy="12" r=".9" fill="currentColor" stroke="none"/></svg>',
+    numbers: '<svg class="cn-icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M6.5 4h7M6.5 8h7M6.5 12h7M2.25 3l1-.5v3M2 9.25a1 1 0 011.75.5c0 .8-1.75 1.25-1.75 2.25h2"/></svg>',
+    link: '<svg class="cn-icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M6.5 9.5l3-3M7 11.25l-1.25 1.25a2.12 2.12 0 01-3-3L4 8.25M9 4.75l1.25-1.25a2.12 2.12 0 013 3L12 7.75"/></svg>',
+    image: '<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"><rect x="2.5" y="3.5" width="11" height="9" rx="1.5"/><circle cx="6" cy="7" r="1"/><path d="M13.5 10.5l-3-3-4 4"/></svg>',
+};
+const tool = (svg, label, pressed, extra = '') => `<button type="button" class="cn-rich-text-editor__tool" aria-label="${label}"${pressed !== undefined ? ` aria-pressed="${pressed}"` : ''}${extra}>${svg}</button>`;
+const group = (...tools) => `<div class="cn-rich-text-editor__tool-group" role="group">${tools.join('')}</div>`;
+const SELECT = `<div class="cn-rich-text-editor__select"><div class="cn-select" data-variant="filled" data-size="sm"><select class="cn-select__field" aria-label="Block type"><option value="p" selected>Paragraph</option><option value="h1">Heading 1</option><option value="h2">Heading 2</option><option value="h3">Heading 3</option><option value="quote">Quote</option></select>${ICON.chevronDown.replace('cn-icon', 'cn-select__chevron')}</div></div>`;
+const TOOLBAR = (full = true) => `<div class="cn-rich-text-editor__toolbar" role="toolbar" aria-label="Formatting">${full ? SELECT : ''}${group(tool(SVG.bold, 'Bold', false), tool(SVG.italic, 'Italic', false), tool(SVG.underline, 'Underline', false))}${full ? group(tool(SVG.h1, 'Heading 1', false), tool(SVG.h2, 'Heading 2', false)) : ''}${full ? group(tool(SVG.bullets, 'Bulleted list', true), tool(SVG.numbers, 'Numbered list', false)) : ''}${group(tool(SVG.link, 'Insert link'), full ? tool(SVG.image, 'Insert image') : '')}</div>`;
+const CONTENT = `<h3>Release notes — September</h3><p>This month we shipped the new reporting workspace and a faster search index. Highlights:</p><ul><li>Custom dashboards for every workspace</li><li>Search results in under 200 ms</li><li>Exports to CSV and Google Sheets</li></ul><p>Read the <a href="#">full changelog</a> or reply to this note with questions.</p>`;
+const editor = (variant, size, inner, attrs = '', width = '640px') => `<div class="cn-rich-text-editor" data-variant="${variant}" data-size="${size}"${attrs} style="width:100%;max-width:${width}">${inner}</div>`;
+const area = (content, attrs = '') => `<div class="cn-rich-text-editor__area" contenteditable="true" role="textbox" aria-multiline="true" aria-label="Note" data-placeholder="Write something…"${attrs}>${content}</div>`;
+export const richTextEditor = {
+    name: 'RichTextEditor',
+    slug: 'rich-text-editor',
+    category: 'forms',
+    description: 'A formatted-text field: the Input frame (control border, radius card, shadow-xs, focus ring on :focus-within) with a wrapping toolbar of 32px ghost tool buttons separated into groups by hairlines, a block-type Select, a contenteditable area with a placeholder and prose styles, and an optional footer with a character count and actions.',
+    usage: 'Use where people write more than a note: descriptions, announcements, email bodies, comments with formatting. Keep the toolbar to what the destination can render. For plain multi-line text use Textarea; for code use Code; for read-only formatted text use Prose.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'The frame: bg-surface, control border, radius card, shadow-xs, flex column, overflow hidden. Focus ring on :focus-within; data-invalid and data-disabled for those states.' },
+        { part: 'toolbar', element: 'div', description: 'role="toolbar": wrapping row of tool groups and the block-type select, 8px padding, bottom hairline.' },
+        { part: 'tool-group', element: 'div', description: 'A cluster of related tools (inline styles, headings, lists, inserts); every group after the first gets a hairline on its left.' },
+        { part: 'tool', element: 'button', description: '32px ghost icon button (28px in sm). Toggles carry aria-pressed; actions (link, image) do not.' },
+        { part: 'select', element: 'div', description: 'Wrapper for a filled sm Select of block types (Paragraph, Heading 1–3, Quote); 160px wide.', optional: true },
+        { part: 'area', element: 'div', description: 'The contenteditable (role="textbox", aria-multiline): min-height 160px, 16px padding, body-md, prose styles for headings, lists, links and quotes. Shows data-placeholder while empty.' },
+        { part: 'footer', element: 'div', description: 'Optional bottom row with a top hairline: character count on the left, actions on the right.', optional: true },
+        { part: 'count', element: 'span', description: 'Character count in body-xs tabular ("412 / 2,000"); fg-danger when over the limit.', optional: true },
+        { part: 'actions', element: 'div', description: 'Right-aligned row of sm Buttons (ghost Cancel, primary Save).', optional: true },
+    ],
+    props: {
+        variant: {
+            values: ['default', 'minimal', 'with-footer'],
+            default: 'default',
+            description: 'default = full toolbar (block type, inline styles, headings, lists, link, image) above a 160px area. minimal = inline styles and link only, no hairline under the toolbar, a 96px area: comments and short descriptions. with-footer = default plus a footer with a character count and Cancel/Save actions, for notes that are saved explicitly.',
+        },
+        size: {
+            values: ['sm', 'md'],
+            default: 'md',
+            description: 'md = 32px tools, 16px area padding, body-md text (forms and full pages). sm = 28px tools, 12px padding, body-sm text for side panels and comment boxes.',
+        },
+    },
+    states: {
+        focus: { selector: ':focus-within', description: 'Writing or using the toolbar: the border becomes action-colored and the 3px ring appears on the frame.', markup: 'native :focus-within on the root' },
+        invalid: { selector: '[data-invalid]', description: 'Validation failed (required, over the limit): danger border, danger ring while focused. Pair with a Field error.', markup: 'data-invalid on the root plus aria-invalid="true" on the area' },
+        disabled: { selector: '[data-disabled]', description: 'Read-only or locked: grey fill, disabled text, tools at 50% and inert, area not editable.', markup: 'data-disabled on the root plus contenteditable="false" on the area' },
+        toolHover: { selector: ' .cn-rich-text-editor__tool:hover', description: 'Pointer over a tool (extraCss): subtle fill, ink icon.', markup: 'native :hover on .cn-rich-text-editor__tool' },
+        toolPressed: { selector: ' .cn-rich-text-editor__tool[aria-pressed="true"]', description: 'A formatting toggle that applies to the selection (extraCss): subtle fill and ink icon at rest.', markup: 'aria-pressed="true" on .cn-rich-text-editor__tool' },
+        toolFocus: { selector: ' .cn-rich-text-editor__tool:focus-visible', description: 'Keyboard focus on a tool shows the focus ring (extraCss).', markup: 'native :focus-visible on .cn-rich-text-editor__tool' },
+        toolDisabled: { selector: ' .cn-rich-text-editor__tool:disabled', description: 'A tool that does not apply now (extraCss): 50% opacity, not-allowed.', markup: 'disabled on .cn-rich-text-editor__tool' },
+    },
+    base: {
+        root: {
+            display: 'flex',
+            'flex-direction': 'column',
+            width: '100%',
+            'min-width': '0',
+            'background-color': '{color.bg-surface}',
+            border: '{border.width.thin} solid {color.border-control}',
+            'border-radius': '{radius.card}',
+            'box-shadow': '{shadow.xs}',
+            color: '{color.fg-default}',
+            overflow: 'hidden',
+            ...TRANSITION_COLORS,
+        },
+        toolbar: { display: 'flex', 'flex-wrap': 'wrap', 'align-items': 'center', gap: '{space.1}', padding: '{space.2}', 'border-bottom': HAIRLINE },
+        'tool-group': { display: 'flex', 'align-items': 'center', gap: '{space.0.5}' },
+        tool: {
+            ...RESET_BUTTON,
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            width: '{space.8}',
+            height: '{space.8}',
+            'border-radius': '{radius.md}',
+            color: '{color.fg-muted}',
+            ...TRANSITION_COLORS,
+        },
+        select: { display: 'inline-flex', flex: '0 0 auto', width: '160px', 'max-width': '100%' },
+        area: {
+            'min-height': '{space.40}',
+            padding: '{space.4}',
+            ...typeStyle('body-md'),
+            color: '{color.fg-default}',
+            outline: 'none',
+            'overflow-wrap': 'anywhere',
+            'caret-color': '{color.bg-action}',
+            cursor: 'text',
+        },
+        footer: { display: 'flex', 'align-items': 'center', 'justify-content': 'space-between', gap: '{space.3}', padding: '{space.2} {space.3}', 'border-top': HAIRLINE, ...typeStyle('body-xs'), color: '{color.fg-muted}' },
+        count: { 'font-variant-numeric': 'tabular-nums', 'white-space': 'nowrap' },
+        actions: { display: 'flex', 'align-items': 'center', gap: '{space.2}' },
+        '@states': {
+            focus: { root: { ...FOCUS_RING, 'border-color': '{color.border-action}' } },
+            invalid: { root: { 'border-color': '{color.border-danger}' }, count: { color: '{color.fg-danger}' } },
+            disabled: { root: { 'background-color': '{color.bg-disabled}', color: '{color.fg-disabled}', 'border-color': '{color.border-disabled}', 'box-shadow': 'none' }, area: { color: '{color.fg-disabled}', cursor: 'not-allowed' } },
+        },
+    },
+    variants: {
+        variant: {
+            default: { root: {} },
+            minimal: { toolbar: { 'border-bottom': '0', 'padding-bottom': '0' }, area: { 'min-height': '{space.24}' } },
+            'with-footer': { root: {} },
+        },
+        size: {
+            sm: {
+                toolbar: { padding: '{space.1.5}', gap: '{space.0.5}' },
+                tool: { width: '{space.7}', height: '{space.7}' },
+                select: { width: '140px' },
+                area: { padding: '{space.3}', 'min-height': '{space.32}', ...typeStyle('body-sm') },
+                footer: { padding: '{space.1.5} {space.2.5}' },
+            },
+            md: { root: {} },
+        },
+    },
+    extraCss: `
+.cn-rich-text-editor__tool .cn-icon { width: {size.icon.md}; height: {size.icon.md}; }
+.cn-rich-text-editor__tool:hover:not(:disabled) { background-color: {color.bg-subtle}; color: {color.fg-default}; }
+.cn-rich-text-editor__tool[aria-pressed="true"] { background-color: {color.bg-subtle}; color: {color.fg-default}; }
+.cn-rich-text-editor__tool:focus-visible { outline: none; box-shadow: ${FOCUS_RING['box-shadow']}; }
+.cn-rich-text-editor__tool:disabled { opacity: {opacity.disabled}; cursor: not-allowed; }
+.cn-rich-text-editor__tool-group + .cn-rich-text-editor__tool-group { margin-inline-start: {space.1}; padding-inline-start: {space.1.5}; border-inline-start: ${HAIRLINE}; }
+.cn-rich-text-editor__select + .cn-rich-text-editor__tool-group { margin-inline-start: {space.1}; padding-inline-start: {space.1.5}; border-inline-start: ${HAIRLINE}; }
+.cn-rich-text-editor__area:empty::before { content: attr(data-placeholder); color: {color.fg-placeholder}; pointer-events: none; }
+.cn-rich-text-editor__area > * + * { margin-top: {space.3}; }
+.cn-rich-text-editor__area h1 { ${decl(typeStyle('heading-lg'))} }
+.cn-rich-text-editor__area h2 { ${decl(typeStyle('heading-md'))} }
+.cn-rich-text-editor__area h3 { ${decl(typeStyle('heading-sm'))} }
+.cn-rich-text-editor__area ul { list-style: disc; padding-inline-start: {space.5}; }
+.cn-rich-text-editor__area ol { list-style: decimal; padding-inline-start: {space.5}; }
+.cn-rich-text-editor__area li + li { margin-top: {space.1}; }
+.cn-rich-text-editor__area a { color: {color.fg-link}; text-decoration: underline; text-underline-offset: 3px; text-decoration-color: {color.border-strong}; }
+.cn-rich-text-editor__area a:hover { color: {color.fg-link-hover}; text-decoration-color: currentColor; }
+.cn-rich-text-editor__area strong { font-weight: {font.weight.semibold}; }
+.cn-rich-text-editor__area blockquote { border-inline-start: {border.width.medium} solid {color.border-strong}; padding-inline-start: {space.3}; color: {color.fg-muted}; }
+.cn-rich-text-editor__area img { max-width: 100%; border-radius: {radius.md}; }
+.cn-rich-text-editor[data-invalid]:focus-within { border-color: {color.border-danger}; box-shadow: {shadow.focus-danger}; }
+.cn-rich-text-editor[data-disabled] .cn-rich-text-editor__tool { opacity: {opacity.disabled}; pointer-events: none; }
+.cn-rich-text-editor[data-disabled] .cn-rich-text-editor__toolbar, .cn-rich-text-editor[data-disabled] .cn-rich-text-editor__footer { border-color: {color.border-disabled}; }`,
+    examples: [
+        ex('Default with content', editor('default', 'md', `${TOOLBAR()}${area(CONTENT)}`), 'Block-type select, inline styles, headings, lists, link and image. The bulleted-list tool is pressed because the caret sits in the list.'),
+        ex('Minimal, small, empty', editor('minimal', 'sm', `${TOOLBAR(false)}${area('')}`, '', '480px'), 'Inline styles and link only; the placeholder comes from data-placeholder.'),
+        ex('With footer (count and actions)', editor('with-footer', 'md', `${TOOLBAR()}${area(CONTENT)}<div class="cn-rich-text-editor__footer"><span class="cn-rich-text-editor__count" aria-live="polite">412 / 2,000</span><div class="cn-rich-text-editor__actions"><button type="button" class="cn-button" data-variant="ghost" data-size="sm"><span class="cn-button__label">Cancel</span></button><button type="button" class="cn-button" data-variant="primary" data-size="sm"><span class="cn-button__label">Save note</span></button></div></div>`), 'The count turns fg-danger over the limit and the frame becomes invalid.'),
+        ex('Invalid and disabled', `<div style="display:flex;flex-direction:column;gap:var(--cn-space-4);width:100%;max-width:640px">${editor('with-footer', 'sm', `${TOOLBAR(false)}${area('<p>Thanks for the update, looping in the finance team so they can confirm the invoice dates before we publish the notes to every workspace and send the customer digest that goes out on Friday morning.</p>', ' aria-invalid="true"')}<div class="cn-rich-text-editor__footer"><span class="cn-rich-text-editor__count" aria-live="polite">212 / 200</span></div>`, ' data-invalid', '640px')}${editor('minimal', 'sm', `${TOOLBAR(false)}${area('<p>This announcement was published on Sep 9 and can no longer be edited.</p>', ' contenteditable="false"')}`, ' data-disabled', '640px')}</div>`, 'data-invalid draws the danger border; data-disabled greys the frame and makes the tools inert.'),
+    ],
+    rules: [
+        'Offer only what the destination renders: an email body gets inline styles and links; a document gets headings and lists too. Never a toolbar with twenty tools.',
+        'Group tools by kind (block type, inline, headings, lists, inserts) with the hairline between groups; keep the same order in every editor of the product.',
+        'Toggles (bold, italic, lists) show aria-pressed for the current selection; actions (link, image) open a small Dialog or Popover, never a browser prompt.',
+        'The area starts at 160px (96px minimal) and grows with content; never an inner scrollbar unless the editor sits in a fixed-height panel.',
+        'Placeholders are an example of the expected content ("Write the release notes…"), not a label; the label lives in the Field.',
+        'Show a character count only with a hard limit; over the limit the count turns danger and the frame becomes invalid, but typing is not blocked.',
+        'Paste keeps only the formatting the toolbar offers; strip colors, fonts and sizes.',
+        'Save explicitly with a footer (with-footer) when the text is a record; autosave with a status line when it is a draft. Never both.',
+        'sm inside comment boxes and side panels; md in forms and full pages.',
+    ],
+    a11y: [
+        'The area is role="textbox" with aria-multiline="true" and an accessible name (a Field label or aria-label); set aria-invalid and aria-describedby with the error when invalid.',
+        'The toolbar is role="toolbar" with an aria-label; Tab enters it once, Left/Right move between tools, and the tools are real <button>s with aria-label.',
+        'Formatting toggles expose aria-pressed; the block-type Select is a native <select> so it works everywhere.',
+        'Keyboard shortcuts (Cmd/Ctrl+B, I, U, K) mirror the toolbar and are listed in a Tooltip on each tool.',
+        'Announce the character count with aria-live="polite" and say "over the limit" in the Field error, not only in color.',
+    ],
+    related: ['textarea', 'field', 'select', 'icon-button', 'prose', 'code'],
+};

package/lib/components/section-header.mjs

@@ -0,0 +1,62 @@
+import { ex, ICON, typeStyle } from "./_shared.mjs";
+const btn = (v, label, size = 'md') => `<button type="button" class="cn-button" data-variant="${v}" data-size="${size}"><span class="cn-button__label">${label}</span></button>`;
+export const sectionHeader = {
+    name: 'SectionHeader',
+    slug: 'section-header',
+    category: 'layout',
+    description: 'Heading row of a section inside a page or a card: title, supporting text, optional badge, tabs or search, and section-level actions. Smaller than PageHeader.',
+    usage: 'Above tables, forms, lists and settings groups. Use inside Card as its header row when the card holds a data set. Do not use for the page title (PageHeader).',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'Flex row with a bottom hairline (divider prop).' },
+        { part: 'content', element: 'div', description: 'Title + description column.' },
+        { part: 'title', element: 'h2', description: 'heading-sm (18/28 semibold) with optional inline badge.' },
+        { part: 'badge', element: 'span', description: 'Optional count/status badge after the title (Badge markup).', optional: true },
+        { part: 'description', element: 'p', description: 'body-md in fg-muted.' },
+        { part: 'actions', element: 'div', description: 'Right-aligned buttons (sm or md).' },
+        { part: 'tabs', element: 'div', description: 'Optional Tabs (pill/button variant) in the actions slot or below.', optional: true },
+        { part: 'search', element: 'div', description: 'Optional search Input (width 280) in the actions slot.', optional: true },
+    ],
+    props: {
+        variant: { values: ['default', 'with-badge', 'with-tabs', 'with-search', 'card'], default: 'default', description: 'default; with-badge = count/status next to the title; with-tabs = filter tabs on the right; with-search = search input on the right; card = padding for use as a Card header (20/24px) with the divider.' },
+        divider: { values: ['yes', 'no'], default: 'yes', description: 'Hairline under the header.' },
+    },
+    states: {},
+    base: {
+        root: { display: 'flex', 'flex-wrap': 'wrap', 'align-items': 'flex-start', 'justify-content': 'space-between', gap: '{space.4}', 'padding-bottom': '{space.5}' },
+        content: { display: 'flex', 'flex-direction': 'column', gap: '{space.1}', 'min-width': '0', flex: '1 1 280px' },
+        title: { ...typeStyle('heading-sm'), color: '{color.fg-default}', display: 'flex', 'align-items': 'center', gap: '{space.2}', 'flex-wrap': 'wrap' },
+        badge: { 'flex-shrink': '0' },
+        description: { ...typeStyle('body-md'), color: '{color.fg-muted}' },
+        actions: { display: 'flex', 'align-items': 'center', gap: '{space.3}', 'flex-shrink': '0', 'flex-wrap': 'wrap' },
+        tabs: { 'flex-shrink': '0' },
+        search: { width: '280px', 'max-width': '100%' },
+    },
+    variants: {
+        variant: {
+            default: { root: {} },
+            'with-badge': { root: {} },
+            'with-tabs': { root: {} },
+            'with-search': { root: {} },
+            card: { root: { padding: '{space.5} {space.6}' } },
+        },
+        divider: { yes: { root: { 'border-bottom': '{border.width.thin} solid {color.border-default}' } }, no: { root: { 'padding-bottom': '0' } } },
+    },
+    extraCss: `
+.cn-section-header[data-variant="card"][data-divider="no"] { padding-bottom: {space.5}; }
+@media (max-width: {breakpoint.md}) { .cn-section-header .cn-section-header__actions { width: 100%; } .cn-section-header .cn-section-header__search { width: 100%; } }`,
+    examples: [
+        ex('Default', `<div class="cn-section-header" data-variant="default" data-divider="yes"><div class="cn-section-header__content"><h2 class="cn-section-header__title">Personal info</h2><p class="cn-section-header__description">Update your photo and personal details here.</p></div><div class="cn-section-header__actions">${btn('outline', 'Cancel')}${btn('primary', 'Save')}</div></div>`),
+        ex('With badge', `<div class="cn-section-header" data-variant="with-badge" data-divider="yes"><div class="cn-section-header__content"><h2 class="cn-section-header__title">Team members <span class="cn-section-header__badge cn-badge" data-tone="accent" data-variant="soft" data-size="sm">100 users</span></h2><p class="cn-section-header__description">Manage your team members and their account permissions here.</p></div><div class="cn-section-header__actions">${btn('outline', 'Download all')}${btn('primary', 'Add user')}</div></div>`),
+        ex('With tabs', `<div class="cn-section-header" data-variant="with-tabs" data-divider="yes"><div class="cn-section-header__content"><h2 class="cn-section-header__title">Vendor movements</h2><p class="cn-section-header__description">Keep track of vendor and their security ratings.</p></div><div class="cn-section-header__tabs cn-tabs" data-variant="pill" data-size="sm" role="tablist"><button type="button" class="cn-tabs__tab" role="tab" aria-selected="true">12 months</button><button type="button" class="cn-tabs__tab" role="tab" aria-selected="false">30 days</button><button type="button" class="cn-tabs__tab" role="tab" aria-selected="false">7 days</button><button type="button" class="cn-tabs__tab" role="tab" aria-selected="false">24 hours</button></div></div>`),
+        ex('With search', `<div class="cn-section-header" data-variant="with-search" data-divider="yes"><div class="cn-section-header__content"><h2 class="cn-section-header__title">Invoices</h2><p class="cn-section-header__description">Pick an account plan that fits your workflow.</p></div><div class="cn-section-header__actions"><div class="cn-section-header__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 invoices"></div>${btn('outline', 'Filters')}</div></div>`),
+        ex('As a card header', `<section class="cn-card" data-variant="default" data-padding="none" style="max-width:640px"><div class="cn-section-header" data-variant="card" data-divider="yes"><div class="cn-section-header__content"><h2 class="cn-section-header__title">Notifications</h2><p class="cn-section-header__description">Choose what you want to be notified about.</p></div><div class="cn-section-header__actions">${btn('ghost', 'Reset', 'sm')}</div></div><div class="cn-card__body" style="padding:var(--cn-space-6)"><p class="cn-text-body-md">Card content</p></div></section>`),
+    ],
+    rules: [
+        'Title is an h2 (or h3 inside a card that already has an h2). Never a page title.',
+        'Description one sentence; omit rather than repeat the title.',
+        'Actions on the right are sm inside cards, md on the page. At most one primary.',
+        '20px padding below, hairline divider, then 24px (space.6) to the content.',
+    ],
+    a11y: ['Headings keep document order: h1 (page) → h2 (section) → h3 (card inside a section).', 'Filter tabs use role="tablist" only when they switch panels; otherwise use a SegmentedControl.'],
+    related: ['page-header', 'card', 'tabs', 'badge', 'input'],
+};

package/lib/components/segmented-control.mjs

@@ -0,0 +1,121 @@
+import { RESET_BUTTON, ex, ICON, typeStyle } from "./_shared.mjs";
+// the reference "button-border" rail: a gray-50 track with a 1px gray-200 ring and 4px padding,
+// radius 10 (sm) / 12 (md), items with 14px semibold text (16px on md in the reference tabs — we keep
+// 14px so the rail matches ButtonGroup), radius 6 / 8, gray-600 → the selected item lifts on white
+// with shadow-sm and the default ink. Total heights 36 (sm) / 40 (md) so it sits next to a ButtonGroup.
+const TRANSITION_FAST = {
+    'transition-property': 'background-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 icon = (name) => ICON[name].replace('cn-icon', 'cn-segmented-control__icon');
+const item = (label, attrs = '', ic = '') => `<button type="button" role="radio" class="cn-segmented-control__item" ${attrs}>${ic}${label}</button>`;
+const rail = (attrs, items, size = 'md', variant = 'default') => `<div class="cn-segmented-control" role="radiogroup" data-size="${size}" data-variant="${variant}" ${attrs}>${items}</div>`;
+export const segmentedControl = {
+    name: 'SegmentedControl',
+    slug: 'segmented-control',
+    category: 'forms',
+    description: 'Single-choice group drawn as one rail: a gray-50 track with a hairline ring and 4px padding where the selected item lifts on a white surface with shadow-sm. Same heights (36 / 40px) and 14px semibold type as ButtonGroup, so the two sit side by side in a toolbar.',
+    usage: 'Two to five mutually exclusive views or modes whose change is immediate (List / Board, Day / Week / Month, Monthly / Annual). For form data use Radio; for navigation between pages use Tabs; for actions on one object use ButtonGroup; for more than five options use Select.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'The rail: inline-flex, gray-50 fill, 1px gray-200 inset ring, 4px padding, radius 10 (sm) / 12 (md), 4px between items. role="radiogroup" with an aria-label.' },
+        { part: 'item', element: 'button', description: 'One option: <button role="radio" aria-checked>. 28px (sm) / 32px (md) tall, padding 10px, radius 6 / 8, 14px semibold gray-600 until selected.' },
+        { part: 'icon', element: 'svg', description: 'Optional leading icon (16px on sm, 20px on md) inside an item, gray-500, or the only content with aria-label on the item. Decorative.', optional: true },
+    ],
+    props: {
+        size: { values: ['sm', 'md'], default: 'md', description: 'md = 40px rail with 32px items (matches md controls and a md ButtonGroup); sm = 36px rail with 28px items for cards, tables and popovers.' },
+        variant: { values: ['default', 'full'], default: 'default', description: 'default = items at their content width, the rail hugs them; full = the rail fills its container and every item takes an equal share (mobile sheets, narrow cards).' },
+    },
+    states: {
+        selected: { selector: '[aria-checked="true"], &[data-selected]', description: 'On the __item (not the root): white surface, default ink, shadow-sm; the icon darkens. Exactly one per group.', markup: 'aria-checked="true" on the item button (data-selected also accepted)' },
+        hover: { selector: ':hover:not(:disabled)', description: 'On an unselected __item: text turns to the default ink and the icon darkens; no background change.', markup: 'native :hover on the item' },
+        focus: { selector: ':focus-visible', description: 'On the __item: the 4px brand ring on the item itself, raised above its neighbours.', markup: 'native :focus-visible on the item' },
+        'item-disabled': { selector: ':disabled', description: 'On the __item: 50% opacity, cursor not-allowed; stays visible so the option is known to exist.', markup: 'disabled on the item button' },
+        disabled: { selector: '[data-disabled]', description: 'Whole group at 50% opacity and not interactive.', markup: 'data-disabled on the root' },
+    },
+    base: {
+        root: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            gap: '{space.1}',
+            'max-width': '100%',
+            padding: '{space.1}',
+            'background-color': '{color.bg-subtle}',
+            'box-shadow': ring('{color.border-default}'),
+            'border-radius': 'calc({radius.xl} - 2px)',
+        },
+        item: {
+            ...RESET_BUTTON,
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            'white-space': 'nowrap',
+            ...typeStyle('label-md'),
+            color: '{color.fg-muted}',
+            'border-radius': '{radius.md}',
+            ...TRANSITION_FAST,
+        },
+        icon: { 'flex-shrink': '0', display: 'block', color: '{color.fg-subtle}', transition: 'inherit' },
+        '@states': {
+            disabled: { root: { opacity: '{opacity.disabled}', 'pointer-events': 'none' } },
+        },
+    },
+    variants: {
+        size: {
+            sm: {
+                root: { 'border-radius': 'calc({radius.xl} - 2px)' },
+                item: { height: 'calc({size.control.sm} - {space.2})', 'padding-inline': '{space.2.5}', gap: '{space.1}', 'border-radius': '{radius.md}' },
+                icon: { width: '{size.icon.sm}', height: '{size.icon.sm}' },
+            },
+            md: {
+                root: { 'border-radius': '{radius.xl}' },
+                item: { height: 'calc({size.control.md} - {space.2})', 'padding-inline': '{space.2.5}', gap: '{space.1.5}', 'border-radius': '{radius.lg}' },
+                icon: { width: '{size.icon.md}', height: '{size.icon.md}' },
+            },
+        },
+        variant: {
+            default: { root: {} },
+            full: { root: { display: 'flex', width: '100%' }, item: { flex: '1 1 0', 'min-width': '0' } },
+        },
+    },
+    extraCss: `
+.cn-segmented-control .cn-segmented-control__item[aria-checked="true"], .cn-segmented-control .cn-segmented-control__item[data-selected] { background-color: {color.bg-surface}; color: {color.fg-default}; box-shadow: {shadow.sm}; }
+.cn-segmented-control .cn-segmented-control__item[aria-checked="true"] .cn-segmented-control__icon, .cn-segmented-control .cn-segmented-control__item[data-selected] .cn-segmented-control__icon { color: {color.fg-muted}; }
+.cn-segmented-control .cn-segmented-control__item:hover:not(:disabled):not([aria-checked="true"]) { color: {color.fg-default}; }
+.cn-segmented-control .cn-segmented-control__item:hover:not(:disabled):not([aria-checked="true"]) .cn-segmented-control__icon { color: {color.fg-muted}; }
+.cn-segmented-control .cn-segmented-control__item:focus-visible { position: relative; z-index: {z.raised}; outline: none; box-shadow: {shadow.focus}; }
+.cn-segmented-control .cn-segmented-control__item[aria-checked="true"]:focus-visible { box-shadow: {shadow.sm}, {shadow.focus}; }
+.cn-segmented-control .cn-segmented-control__item:disabled { opacity: {opacity.disabled}; cursor: not-allowed; }
+.cn-segmented-control .cn-segmented-control__item[aria-checked="true"] + .cn-segmented-control__item { margin-inline-start: 0; }`,
+    examples: [
+        ex('Default', rail('aria-label="View"', item('List', 'aria-checked="true" tabindex="0"') + item('Board', 'aria-checked="false" tabindex="-1"') + item('Timeline', 'aria-checked="false" tabindex="-1"')), '40px rail: gray-50 with a hairline ring and 4px padding; the selected item is white with shadow-sm.'),
+        ex('With icons', rail('aria-label="Inbox view"', item('Inbox', 'aria-checked="true" tabindex="0"', icon('inbox')) + item('Calendar', 'aria-checked="false" tabindex="-1"', icon('calendar')) + item('People', 'aria-checked="false" tabindex="-1"', icon('user'))), '20px gray-500 icons, 6px before the label; darker on the selected item.'),
+        ex('Icon-only', rail('aria-label="Layout"', item('', 'aria-checked="true" aria-label="List layout" tabindex="0"', icon('menu')) + item('', 'aria-checked="false" aria-label="Grid layout" tabindex="-1"', icon('home')) + item('', 'aria-checked="false" aria-label="Settings layout" tabindex="-1"', icon('settings'))), 'Every icon-only item carries an aria-label.'),
+        ex('Full width', rail('aria-label="Billing cycle" style="max-width:360px"', item('Monthly', 'aria-checked="false" tabindex="-1"') + item('Annual · save 20%', 'aria-checked="true" tabindex="0"'), 'md', 'full')),
+        ex('Small', rail('aria-label="Range"', item('Day', 'aria-checked="false" tabindex="-1"') + item('Week', 'aria-checked="true" tabindex="0"') + item('Month', 'aria-checked="false" tabindex="-1"') + item('Quarter', 'aria-checked="false" tabindex="-1"'), 'sm'), '36px rail with 28px items and radius 10.'),
+        ex('Disabled item', rail('aria-label="Export format"', item('CSV', 'aria-checked="true" tabindex="0"') + item('Excel', 'aria-checked="false" tabindex="-1"') + item('PDF', 'aria-checked="false" tabindex="-1" disabled aria-disabled="true"')), 'PDF export is a Scale feature: the item stays visible at 50%.'),
+        ex('Disabled group', rail('aria-label="View" data-disabled aria-disabled="true"', item('List', 'aria-checked="true" tabindex="-1" disabled') + item('Board', 'aria-checked="false" tabindex="-1" disabled'))),
+    ],
+    recipes: [
+        ex('Next to a ButtonGroup in a toolbar', `<div style="display:flex;align-items:center;gap:var(--cn-space-3)">${rail('aria-label="View"', item('List', 'aria-checked="true" tabindex="0"') + item('Board', 'aria-checked="false" tabindex="-1"'))}<div class="cn-button-group" data-variant="attached" data-orientation="horizontal" role="group" aria-label="Range"><button type="button" class="cn-button" data-variant="outline" data-size="md" aria-pressed="true"><span class="cn-button__label">30 days</span></button><button type="button" class="cn-button" data-variant="outline" data-size="md" aria-pressed="false"><span class="cn-button__label">7 days</span></button></div></div>`, 'Both are 40px tall with 14px semibold labels; the rail is for a view, the group for a range.'),
+    ],
+    rules: [
+        'Use for 2–5 mutually exclusive views or modes whose change is immediate. For form data use Radio; for page navigation use Tabs; for actions on one object use ButtonGroup.',
+        'Labels are one or two words in sentence case, or an icon with aria-label. Keep every item in the same voice: all nouns or all icons, never mixed.',
+        'One item is always selected; there is no empty state and no toggling off.',
+        'variant="full" only inside narrow containers (mobile sheets, cards ≤ 400px) so each item stretches equally; default keeps items at content width.',
+        'md (40px) matches md controls in a toolbar; sm (36px) sits inside tables, cards and popovers. Never place a SegmentedControl taller than the controls beside it.',
+        'Maximum five items. Beyond that the choice becomes a Select or Tabs.',
+        'Do not mix action buttons into the rail; put related actions in a ButtonGroup beside it, 12px away.',
+    ],
+    a11y: [
+        'The root has role="radiogroup" with aria-label (or aria-labelledby); each item is a <button role="radio" aria-checked="true|false">.',
+        'Roving tabindex: only the selected item has tabindex="0"; Left/Right (and Up/Down) move selection and check the new item, Home/End jump.',
+        'Icon-only items require aria-label; the svg is aria-hidden.',
+        'Disabled item: disabled plus aria-disabled="true"; a disabled group sets data-disabled and aria-disabled on the root.',
+        'Selection change must not move focus or navigate. If it changes the URL, use Tabs instead.',
+    ],
+    related: ['radio', 'tabs', 'button-group', 'select'],
+};

package/lib/components/select.mjs

@@ -0,0 +1,163 @@
+import { CONTROL, SIZE_PROP, ex, ICON, typeStyle } from "./_shared.mjs";
+// the reference select trigger, measure for measure: 36 / 40 / 44px, padding 8px 10px 8px 12px (sm),
+// 8×12 (md), 10×14 (lg); 14px text (16px on lg; the reference uses 16px on md too — we keep 14px
+// as the default UI size); chevron 16px (20px on lg) in gray-500 at the trailing edge; 1px inset
+// gray-300 ring under shadow-xs, radius 8; focus or open = brand ring; disabled = 50% opacity.
+const TRANSITION_FAST = {
+    'transition-property': 'box-shadow, background-color, color, opacity',
+    'transition-duration': '{motion.duration.fast}',
+    'transition-timing-function': '{motion.easing.linear}',
+};
+const ring = (color) => `inset 0 0 0 1px ${color}`;
+const RING_REST = `${ring('{color.border-control}')}, {shadow.xs}`;
+const RING_HOVER = `${ring('{color.border-control-hover}')}, {shadow.xs}`;
+const RING_FOCUS = `${ring('{color.border-action}')}, {shadow.xs}, {shadow.focus}`;
+const RING_INVALID = `${ring('{color.border-danger}')}, {shadow.xs}`;
+const RING_INVALID_FOCUS = `${ring('{color.border-danger}')}, {shadow.xs}, {shadow.focus-danger}`;
+/** pl/pr = leading/trailing padding, icon = leading icon, chevron = trailing chevron size. */
+const SIZE = {
+    sm: { pl: '{space.3}', pr: '{space.2.5}', icon: '{size.icon.sm}', chevron: '{size.icon.sm}', lh: '{type.body-md.lineHeight}' },
+    md: { pl: '{space.3}', pr: '{space.3}', icon: '{size.icon.md}', chevron: '{size.icon.sm}', lh: '{type.body-md.lineHeight}' },
+    lg: { pl: '{space.3.5}', pr: '{space.3.5}', icon: '{size.icon.md}', chevron: '{size.icon.md}', lh: '{type.body-lg.lineHeight}' },
+};
+const sizeBlock = (s) => ({
+    root: { height: CONTROL[s].height },
+    field: {
+        'padding-inline-start': SIZE[s].pl,
+        'padding-inline-end': `calc(${SIZE[s].pr} + ${SIZE[s].chevron} + {space.2})`,
+        'font-size': CONTROL[s].font,
+        'line-height': SIZE[s].lh,
+    },
+    icon: { width: SIZE[s].icon, height: SIZE[s].icon, 'inset-inline-start': SIZE[s].pl },
+    chevron: { width: SIZE[s].chevron, height: SIZE[s].chevron, 'inset-inline-end': SIZE[s].pr },
+});
+const chevron = ICON.chevronDown.replace('cn-icon', 'cn-select__chevron');
+const icon = (name) => ICON[name].replace('cn-icon', 'cn-select__icon');
+const sel = (attrs, options, size = 'md', variant = 'default', leading = '', style = 'max-width:280px') => `<div class="cn-select" data-variant="${variant}" data-size="${size}" style="${style}">${leading}<select class="cn-select__field" ${attrs}>${options}</select>${chevron}</div>`;
+const PEOPLE = '<option value="maya" selected>Maya Chen</option><option value="daniel">Daniel Costa</option><option value="sofia">Sofia Almeida</option><option value="lucas">Lucas Ferreira</option><option value="aisha">Aisha Khan</option><option value="noah">Noah Berg</option>';
+export const select = {
+    name: 'Select',
+    slug: 'select',
+    category: 'forms',
+    description: 'Native <select> dressed as the reference select trigger: the Input ring, radius 8 and heights (36 / 40 / 44px), an optional leading icon and a gray-500 chevron at the trailing edge. The dropdown itself is the operating system menu.',
+    usage: 'Choose one option from a short, known list (5–15 items: owner, plan, status, sort order). Under 5 options use Radio or SegmentedControl; for long or searchable lists, icons or supporting text in the rows, use Combobox; for multiple choices use Checkboxes. Pair with Field for label and hint.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'Wrapper that draws the ring, background, radius, shadow-xs and the focus ring (:focus-within). Position: relative for the icon and chevron.' },
+        { part: 'icon', element: 'svg', description: 'Optional leading icon (16px on sm, 20px on md and lg) absolutely placed at the padding edge in gray-500; the text starts 8px after it. Decorative, pointer-events: none.', optional: true },
+        { part: 'field', element: 'select', description: 'The native <select> with appearance: none. Fills the wrapper; the trailing padding reserves room for the chevron.' },
+        { part: 'chevron', element: 'svg', description: 'Chevron-down, 16px (20px on lg), gray-500, absolutely placed 10 / 12 / 14px from the trailing edge. Decorative, pointer-events: none.' },
+    ],
+    props: {
+        size: SIZE_PROP(['sm', 'md', 'lg']),
+        variant: { values: ['default', 'filled'], default: 'default', description: 'default = white with the gray-300 ring and shadow-xs (the reference trigger; forms); filled = gray-50 fill without ring or shadow until focus (toolbars, table filters, sort controls — no reference equivalent).' },
+    },
+    states: {
+        hover: { selector: ':hover:not([data-disabled])', description: 'Pointer over the trigger. The reference has no hover change; presets with a distinct border-control-hover strengthen the ring.', markup: 'native' },
+        focus: { selector: ':focus-within', description: 'Focused or open: the inset ring turns to the brand color and the 4px brand focus ring appears.', markup: 'native :focus-within on the wrapper' },
+        invalid: { selector: '[data-invalid], &:has([aria-invalid="true"])', description: 'Red-300 ring; red focus ring on focus. Always accompanied by a Field error.', markup: 'aria-invalid="true" on the select, or data-invalid on the wrapper' },
+        disabled: { selector: '[data-disabled], &:has(select:disabled)', description: 'Whole control at 50% opacity, cursor not-allowed. Scoped to the <select> so a disabled placeholder <option> does not trigger it.', markup: 'disabled on the select' },
+    },
+    base: {
+        root: {
+            position: 'relative',
+            display: 'flex',
+            'align-items': 'center',
+            width: '100%',
+            'min-width': '0',
+            'background-color': '{color.bg-surface}',
+            'border-radius': '{radius.control}',
+            'box-shadow': RING_REST,
+            color: '{color.fg-default}',
+            ...TRANSITION_FAST,
+        },
+        field: {
+            appearance: 'none',
+            '-webkit-appearance': 'none',
+            flex: '1 1 auto',
+            width: '100%',
+            'min-width': '0',
+            height: '100%',
+            margin: '0',
+            'padding-block': '0',
+            border: '0',
+            outline: 'none',
+            background: 'transparent',
+            'border-radius': '{radius.control}',
+            ...typeStyle('body-md'),
+            'font-weight': '{font.weight.medium}',
+            color: 'inherit',
+            cursor: 'pointer',
+            'white-space': 'nowrap',
+            'text-overflow': 'ellipsis',
+        },
+        icon: {
+            position: 'absolute',
+            top: '50%',
+            transform: 'translateY(-50%)',
+            'flex-shrink': '0',
+            color: '{color.fg-subtle}',
+            'pointer-events': 'none',
+        },
+        chevron: {
+            position: 'absolute',
+            top: '50%',
+            transform: 'translateY(-50%)',
+            'flex-shrink': '0',
+            color: '{color.fg-subtle}',
+            'stroke-width': '2.25',
+            'pointer-events': 'none',
+        },
+        '@states': {
+            hover: { root: { 'box-shadow': RING_HOVER } },
+            focus: { root: { 'box-shadow': RING_FOCUS } },
+            invalid: { root: { 'box-shadow': RING_INVALID } },
+            disabled: { root: { opacity: '{opacity.disabled}', cursor: 'not-allowed' }, field: { cursor: 'not-allowed' } },
+        },
+    },
+    variants: {
+        variant: {
+            default: { root: {} },
+            filled: {
+                root: { 'background-color': '{color.bg-subtle}', 'box-shadow': 'none' },
+                '@states': {
+                    hover: { root: { 'background-color': '{color.bg-muted}', 'box-shadow': 'none' } },
+                    focus: { root: { 'background-color': '{color.bg-surface}', 'box-shadow': RING_FOCUS } },
+                    invalid: { root: { 'box-shadow': RING_INVALID } },
+                },
+            },
+        },
+        size: { sm: sizeBlock('sm'), md: sizeBlock('md'), lg: sizeBlock('lg') },
+    },
+    extraCss: `
+.cn-select .cn-select__field::-ms-expand { display: none; }
+.cn-select .cn-select__field:has(option[value=""]:checked) { color: {color.fg-placeholder}; font-weight: {font.weight.regular}; }
+.cn-select:has([aria-invalid="true"]):focus-within, .cn-select[data-invalid]:focus-within { box-shadow: ${RING_INVALID_FOCUS}; }
+.cn-select .cn-select__icon + .cn-select__field { padding-inline-start: calc({space.3} + {size.icon.md} + {space.2}); }
+.cn-select[data-size="sm"] .cn-select__icon + .cn-select__field { padding-inline-start: calc({space.3} + {size.icon.sm} + {space.2}); }
+.cn-select[data-size="lg"] .cn-select__icon + .cn-select__field { padding-inline-start: calc({space.3.5} + {size.icon.md} + {space.2}); }`,
+    examples: [
+        ex('Default', sel('aria-label="Owner"', PEOPLE), '40px tall, 12px padding, medium text, 16px gray-500 chevron 12px from the edge.'),
+        ex('Sizes', `<div style="display:flex;flex-direction:column;gap:var(--cn-space-4)">${sel('aria-label="Owner (small)"', PEOPLE, 'sm')}${sel('aria-label="Owner (medium)"', PEOPLE, 'md')}${sel('aria-label="Owner (large)"', PEOPLE, 'lg')}</div>`, '36 / 40 / 44px; the chevron grows to 20px and the padding to 14px on lg.'),
+        ex('With leading icon', sel('aria-label="Assignee"', PEOPLE, 'md', 'default', icon('user')), 'A 20px gray-500 icon at the padding edge; the text starts 8px after it.'),
+        ex('With placeholder option', sel('aria-label="Plan"', '<option value="" selected disabled>Select a plan</option><option value="starter">Starter — $29/mo</option><option value="team">Team — $99/mo</option><option value="scale">Scale — $299/mo</option>'), 'An empty-value disabled option renders in the placeholder color at regular weight.'),
+        ex('Filled, small (toolbar sort)', sel('aria-label="Sort by"', '<option value="recent" selected>Sort: most recent</option><option value="name">Sort: name</option><option value="owner">Sort: owner</option>', 'sm', 'filled', '', 'max-width:200px')),
+        ex('Invalid', sel('aria-invalid="true" aria-label="Region"', '<option value="" selected disabled>Select a region</option><option value="eu">Europe (Frankfurt)</option><option value="us">United States (Oregon)</option><option value="br">South America (São Paulo)</option>'), 'Pair with a Field error such as "Choose a region to continue".'),
+        ex('Disabled', sel('disabled aria-label="Currency"', '<option value="usd" selected>USD — US dollar</option><option value="eur">EUR — Euro</option>')),
+    ],
+    rules: [
+        'Use for 5–15 known options. Fewer: Radio or SegmentedControl (all options visible). More, or user-generated lists: Combobox with search.',
+        'The first option is either a real default or a disabled placeholder with value="" ("Select a plan"); never "Select…" as a selectable option.',
+        'Option labels are nouns in sentence case, 1–4 words; put the unit or price after an em dash ("Team — $99/mo").',
+        'Always inside a Field with a visible label, except sort/filter selects in a toolbar (variant="filled", size="sm") whose label is in the option text ("Sort: most recent").',
+        'Width comes from the layout; set max-width on the Field for short values (currency, region).',
+        'Sizes: md (40px) in forms; sm (36px) in toolbars and tables; lg (44px) on marketing and auth screens. Never change the height with padding.',
+        'Keep the native <select>. If the menu needs search, avatars, supporting text or groups with headers, use Combobox.',
+    ],
+    a11y: [
+        'Every select has an accessible name: a <label for> from the Field or aria-label for toolbar selects.',
+        'Use <optgroup label> for grouped options instead of fake heading options.',
+        'aria-invalid="true" plus aria-describedby pointing at the Field error id when invalid.',
+        'The icon and chevron are aria-hidden and pointer-events: none; the select itself receives the click and the keyboard (Alt+Down / typing to jump).',
+    ],
+    related: ['input', 'field', 'combobox', 'radio', 'segmented-control'],
+};