canon-ds 0.1.0

package/lib/components/checkbox.mjs

@@ -0,0 +1,163 @@
+import { ex, typeStyle } from "./_shared.mjs";
+// the reference checkbox: 16px box with radius 4 (sm) or 20px with radius 6 (md), 1px inset gray-300
+// ring on white, brand-600 fill with a white 12 / 14px check (or a dash when indeterminate), 8 / 12px
+// to a 14 / 16px medium label with a muted supporting line; box nudged 2px down to sit on the first
+// line. Focus = 4px brand ring on the box; disabled = box at 50% (gray-100 when unchecked).
+const TRANSITION_FAST = {
+    'transition-property': 'background-color, box-shadow, color, opacity',
+    'transition-duration': '{motion.duration.fast}',
+    'transition-timing-function': '{motion.easing.linear}',
+};
+const ring = (color) => `inset 0 0 0 1px ${color}`;
+/** the reference check: 14-unit viewBox, 2px stroke, round caps. */
+const check = '<svg class="cn-checkbox__indicator" viewBox="0 0 14 14" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M11.6666 3.5L5.24992 9.91667L2.33325 7"/></svg>';
+/** label wrapper → hidden input → box → text (+ optional description) */
+const cb = (root, input, label, description = '', variant = 'default') => `<label class="cn-checkbox" data-variant="${variant}" ${root}><input class="cn-checkbox__input" type="checkbox" ${input}><span class="cn-checkbox__control" aria-hidden="true">${check}</span><span class="cn-checkbox__label">${label}</span>${description ? `<span class="cn-checkbox__description">${description}</span>` : ''}</label>`;
+const stack = (...items) => `<div style="display:flex;flex-direction:column;gap:var(--cn-space-3)">${items.join('')}</div>`;
+export const checkbox = {
+    name: 'Checkbox',
+    slug: 'checkbox',
+    category: 'forms',
+    description: 'Yes/no or multi-select choice: a 16px (sm) or 20px (md) box with a gray-300 ring that fills with the brand color and shows a white check, next to a medium label and a muted supporting line. The native input stays in the DOM (invisible but focusable) so every state is CSS-only via :has().',
+    usage: 'Independent options that take effect on save (permissions, filters, consent) and multi-select lists. For one-of-many use Radio; for a setting that applies immediately use Switch. Always with a visible label; never a lone box. The card variant turns each option into a selectable bordered card.',
+    anatomy: [
+        { part: 'root', element: 'label', description: 'The <label> wrapping everything: it is the hit target and gives the input its name. inline-grid: box in column 1, text in column 2, 8px (sm) or 12px (md) apart.' },
+        { part: 'input', element: 'input', description: 'Native <input type="checkbox">, visually hidden (opacity 0, positioned over the box) but focusable. Carries checked, disabled, aria-invalid.' },
+        { part: 'control', element: 'span', description: 'The visible box: white with a 1px gray-300 inset ring, radius 4 (sm) or 6 (md), nudged 2px down to align with the first text line. aria-hidden; purely decorative.' },
+        { part: 'indicator', element: 'svg', description: 'The white check (12px on sm, 14px on md) inside the box. Hidden until checked; replaced by a dash when indeterminate.' },
+        { part: 'label', element: 'span', description: '14px (sm) or 16px (md) medium text in the default ink. Sentence case, no period, states the positive outcome.' },
+        { part: 'description', element: 'span', description: 'Optional supporting line under the label, same size, regular weight, muted: consequence or scope of the option.', optional: true },
+    ],
+    props: {
+        size: { values: ['sm', 'md'], default: 'sm', description: 'sm = 16px box (radius 4) with a 14px label: forms, settings, tables (the reference default); md = 20px box (radius 6) with a 16px label: touch screens, onboarding and prominent options.' },
+        variant: { values: ['default', 'card'], default: 'default', description: 'default = bare box and text; card = the whole option is a selectable card (white, 1px gray-200 ring, radius 12, 16px padding) whose ring turns into a 2px brand ring when checked. Use cards for plans, roles and add-ons where the description matters.' },
+    },
+    states: {
+        checked: { selector: ':has(:checked)', description: 'Box fills with the brand color and shows the white check. A card gets a 2px brand ring.', markup: 'checked attribute on the input' },
+        indeterminate: { selector: '[data-indeterminate], &:has(:indeterminate)', description: 'Partial selection (a "Select all" over a mixed group): brand fill with a dash instead of the check.', markup: 'data-indeterminate on the root, plus input.indeterminate = true in JS' },
+        invalid: { selector: '[data-invalid], &:has([aria-invalid="true"])', description: 'Red-300 ring on the box, for a required acceptance that was skipped. Pair with a visible error message next to the group.', markup: 'aria-invalid="true" on the input, or data-invalid on the root' },
+        focus: { selector: ':has(:focus-visible)', description: 'Keyboard focus on the hidden input shows the 4px brand ring on the box (on the whole card in the card variant).', markup: 'native :focus-visible on the input' },
+        disabled: { selector: '[data-disabled], &:has(:disabled)', description: 'Box at 50% opacity (gray-100 fill when unchecked), cursor not-allowed on the whole row; the text keeps its color. A checked disabled box keeps its check.', markup: 'disabled on the input' },
+    },
+    base: {
+        root: {
+            position: 'relative',
+            display: 'inline-grid',
+            'grid-template-columns': 'auto minmax(0, 1fr)',
+            'column-gap': '{space.2}',
+            'row-gap': '0',
+            'align-items': 'start',
+            'max-width': '100%',
+            color: '{color.fg-default}',
+            cursor: 'pointer',
+            '-webkit-tap-highlight-color': 'transparent',
+        },
+        input: { position: 'absolute', top: '{space.0.5}', left: '0', margin: '0', padding: '0', opacity: '0', cursor: 'pointer' },
+        control: {
+            position: 'relative',
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            'grid-column': '1',
+            'grid-row': '1',
+            'margin-top': '{space.0.5}',
+            'background-color': '{color.bg-surface}',
+            'box-shadow': ring('{color.border-control}'),
+            'border-radius': '{radius.sm}',
+            color: '{color.fg-on-action}',
+            ...TRANSITION_FAST,
+        },
+        indicator: { display: 'none', 'flex-shrink': '0', 'pointer-events': 'none' },
+        label: { 'grid-column': '2', ...typeStyle('label-sm'), color: '{color.fg-default}', 'user-select': 'none' },
+        description: { 'grid-column': '2', ...typeStyle('body-md'), color: '{color.fg-muted}' },
+        '@states': {
+            checked: { control: { 'background-color': '{color.bg-action}', 'box-shadow': ring('{color.bg-action}') }, indicator: { display: 'block' } },
+            indeterminate: { control: { 'background-color': '{color.bg-action}', 'box-shadow': ring('{color.bg-action}') }, indicator: { display: 'none' } },
+            invalid: { control: { 'box-shadow': ring('{color.border-danger}') } },
+            focus: { control: { 'box-shadow': `${ring('{color.border-action}')}, {shadow.focus}` } },
+            disabled: {
+                root: { cursor: 'not-allowed' },
+                input: { cursor: 'not-allowed' },
+                control: { 'background-color': '{color.bg-muted}', opacity: '{opacity.disabled}' },
+            },
+        },
+    },
+    variants: {
+        size: {
+            sm: {
+                input: { width: '{size.icon.sm}', height: '{size.icon.sm}' },
+                control: { width: '{size.icon.sm}', height: '{size.icon.sm}', 'border-radius': '{radius.sm}' },
+                indicator: { width: '{size.icon.xs}', height: '{size.icon.xs}' },
+            },
+            md: {
+                root: { 'column-gap': '{space.3}', 'row-gap': '{space.0.5}' },
+                input: { width: '{size.icon.md}', height: '{size.icon.md}' },
+                control: { width: '{size.icon.md}', height: '{size.icon.md}', 'border-radius': '{radius.md}' },
+                indicator: { width: '{space.3.5}', height: '{space.3.5}' },
+                label: { ...typeStyle('label-lg'), 'font-weight': '{font.weight.medium}' },
+                description: { ...typeStyle('body-lg') },
+            },
+        },
+        variant: {
+            default: { root: {} },
+            card: {
+                root: {
+                    display: 'grid',
+                    width: '100%',
+                    padding: '{space.4}',
+                    'background-color': '{color.bg-surface}',
+                    'border-radius': '{radius.card}',
+                    'box-shadow': ring('{color.border-default}'),
+                    ...TRANSITION_FAST,
+                },
+                input: { top: '{space.4}', left: '{space.4}' },
+                '@states': {
+                    checked: { root: { 'box-shadow': 'inset 0 0 0 2px {color.bg-action}' } },
+                    focus: { root: { 'box-shadow': `${ring('{color.border-default}')}, {shadow.focus}` }, control: { 'box-shadow': ring('{color.border-control}') } },
+                    invalid: { root: { 'box-shadow': ring('{color.border-danger}') } },
+                    disabled: { root: { 'background-color': '{color.bg-subtle}' } },
+                },
+            },
+        },
+    },
+    extraCss: `
+.cn-checkbox:has(:checked):has(:focus-visible) .cn-checkbox__control, .cn-checkbox[data-indeterminate]:has(:focus-visible) .cn-checkbox__control { box-shadow: inset 0 0 0 1px {color.bg-action}, {shadow.focus}; }
+.cn-checkbox[data-indeterminate] .cn-checkbox__control::after, .cn-checkbox:has(:indeterminate) .cn-checkbox__control::after { content: ''; display: block; width: {space.1.5}; height: 2px; border-radius: {radius.full}; background-color: currentColor; }
+.cn-checkbox[data-size="md"][data-indeterminate] .cn-checkbox__control::after, .cn-checkbox[data-size="md"]:has(:indeterminate) .cn-checkbox__control::after { width: {space.2}; }
+.cn-checkbox[data-invalid]:has(:focus-visible) .cn-checkbox__control, .cn-checkbox:has([aria-invalid="true"]):has(:focus-visible) .cn-checkbox__control { box-shadow: inset 0 0 0 1px {color.border-danger}, {shadow.focus-danger}; }
+.cn-checkbox[data-variant="card"]:has(:checked):has(:focus-visible) { box-shadow: inset 0 0 0 2px {color.bg-action}, {shadow.focus}; }
+.cn-checkbox[data-variant="card"]:has(:checked):has(:focus-visible) .cn-checkbox__control { box-shadow: inset 0 0 0 1px {color.bg-action}; }`,
+    examples: [
+        ex('Default', cb('data-size="sm"', '', 'Send me a weekly digest'), '16px box, radius 4, gray-300 ring; 14px medium label 8px away.'),
+        ex('Checked', cb('data-size="sm"', 'checked', 'Notify me when Daniel Costa comments'), 'Brand-600 fill with a 12px white check.'),
+        ex('With supporting text', cb('data-size="sm"', 'checked', 'Require two-factor authentication', 'Members must verify with an authenticator app every 30 days.'), 'The supporting line is the same size, regular weight, muted.'),
+        ex('Medium', cb('data-size="md"', 'checked', 'Share usage analytics with Lumen', 'Helps us prioritise what to build next. Never includes your content.'), '20px box, radius 6, 14px check, 16px text 12px away with a 2px gap between lines.'),
+        ex('Indeterminate (select all)', cb('data-size="sm" data-indeterminate', 'aria-label="Select all members"', 'Select all', '3 of 8 members selected'), 'Set input.indeterminate = true in JS and mirror it with data-indeterminate for CSS.'),
+        ex('Invalid', cb('data-size="sm" data-invalid', 'aria-invalid="true" required', 'I agree to the Terms of Service and the Data Processing Agreement'), 'Red-300 ring. Show the error ("Accept the terms to continue") under the group, not inside the label.'),
+        ex('Disabled', stack(cb('data-size="sm"', 'checked disabled', 'Unlimited seats', 'Included in the Scale plan.'), cb('data-size="sm"', 'disabled', 'Dedicated IP address')), 'The box fades to 50% (gray-100 when unchecked); the text keeps its color.'),
+        ex('Card', stack(cb('data-size="sm"', 'checked', 'Research', 'Interviews, notes and evidence for Sofia Almeida’s team.', 'card'), cb('data-size="sm"', '', 'Design', 'Files, prototypes and the review queue.', 'card')), 'A selectable card: 1px gray-200 ring, radius 12, 16px padding; a 2px brand ring when checked.'),
+    ],
+    recipes: [
+        ex('Permission group', `<div role="group" aria-labelledby="perm-label" style="display:flex;flex-direction:column;gap:var(--cn-space-3);max-width:420px"><div class="cn-text-label-sm" id="perm-label">Member permissions</div>${cb('data-size="sm"', 'checked', 'View projects and conversations')}${cb('data-size="sm"', 'checked', 'Publish updates', 'Posts go out under the member’s own name.')}${cb('data-size="sm"', '', 'Approve invoices above $10,000')}${cb('data-size="sm"', 'disabled', 'Manage billing', 'Owners only.')}</div>`, 'A label names the group; options stack 12px apart; the locked one stays visible but disabled.'),
+        ex('Add-ons as cards', `<div role="group" aria-labelledby="addons-label" style="display:flex;flex-direction:column;gap:var(--cn-space-3);max-width:420px"><div class="cn-text-label-sm" id="addons-label">Add-ons</div>${cb('data-size="sm"', 'checked', 'Priority support · $49/mo', 'A named contact and a 4-hour response time.', 'card')}${cb('data-size="sm"', '', 'Audit log export · $19/mo', 'Stream every event to your SIEM.', 'card')}${cb('data-size="sm"', 'disabled', 'SSO enforcement', 'Included in the Enterprise plan.', 'card')}</div>`, 'Cards stack 12px apart; the whole card is the hit target and shows the focus ring.'),
+    ],
+    rules: [
+        'Use a checkbox for options that take effect on save. For an immediate effect use Switch; for one-of-many use Radio.',
+        'The label states the positive outcome ("Send me a weekly digest"), never a negation ("Do not send…") and never an "Enable/Disable" prefix.',
+        'Labels are sentence case without a period; the supporting line is one full sentence with a period.',
+        'Stack checkboxes vertically 12px apart (16px between cards). Never place more than two side by side.',
+        'Indeterminate is only for a parent that summarizes children ("Select all"). Set input.indeterminate in JS and mirror it with data-indeterminate; clicking it checks everything.',
+        'Invalid is reserved for a required acceptance (terms, consent). Put the error message under the group, in fg-danger, and clear it as soon as the box is checked.',
+        'sm (16px) in forms, settings and tables; md (20px) on touch screens, onboarding and prominent options. Cards for plans, roles and add-ons where the description matters.',
+        'Keep the native input in the DOM. The box is decorative (aria-hidden); never rebuild the checkbox with a div and onClick.',
+    ],
+    a11y: [
+        'The root is a <label> wrapping the input, so the text is the accessible name and the whole row (or card) is the hit target.',
+        'The visible box is aria-hidden; checked, focus and disabled come from the native input via :has(), so assistive tech sees a normal checkbox.',
+        'A native checkbox announces "mixed" on its own once input.indeterminate is true; do not add aria-checked to it.',
+        'Groups get role="group" (or a <fieldset>) with aria-labelledby pointing at the group label.',
+        'Keep descriptions inside the label; if they contain links or run long, move them out and connect them with aria-describedby.',
+    ],
+    related: ['radio', 'switch', 'field'],
+};

package/lib/components/close-button.mjs

@@ -0,0 +1,49 @@
+import { FOCUS_RING, TRANSITION_COLORS, RESET_BUTTON, STATE, ex, ICON } from "./_shared.mjs";
+export const closeButton = {
+    name: 'CloseButton',
+    slug: 'close-button',
+    category: 'actions',
+    description: 'The × that dismisses dialogs, drawers, alerts, toasts and chips. A square utility button with a grey icon and a subtle hover fill.',
+    usage: 'Use only to dismiss the surface it sits in (top-right of dialogs/drawers/toasts, end of alerts/banners). It is never a "cancel" action in a footer; use a ghost Button there.',
+    anatomy: [
+        { part: 'root', element: 'button', description: 'Square hit area. Requires aria-label="Close".' },
+        { part: 'icon', element: 'svg', description: 'The × icon, 20px (sm) or 24px (md/lg).' },
+    ],
+    props: {
+        size: { values: ['xs', 'sm', 'md', 'lg'], default: 'sm', description: 'xs 24px (chips, badges) · sm 36px (alerts, toasts, cards) · md 44px (dialogs, drawers) · lg 48px.' },
+        theme: { values: ['light', 'dark'], default: 'light', description: 'light = grey icon on light surfaces; dark = translucent white icon for dark or brand surfaces.' },
+    },
+    states: { hover: STATE.hover(), active: STATE.active(), focus: STATE.focus(), disabled: STATE.disabled() },
+    base: {
+        root: { ...RESET_BUTTON, display: 'inline-flex', 'align-items': 'center', 'justify-content': 'center', 'flex-shrink': '0', 'border-radius': '{radius.lg}', color: '{color.fg-subtle}', ...TRANSITION_COLORS },
+        icon: { display: 'block', 'stroke-width': '2' },
+        '@states': {
+            focus: { root: FOCUS_RING },
+            disabled: { root: { opacity: '{opacity.disabled}', cursor: 'not-allowed' } },
+        },
+    },
+    variants: {
+        size: {
+            xs: { root: { width: '24px', height: '24px', 'border-radius': '{radius.sm}' }, icon: { width: '{size.icon.xs}', height: '{size.icon.xs}' } },
+            sm: { root: { width: '{size.control.sm}', height: '{size.control.sm}' }, icon: { width: '{size.icon.md}', height: '{size.icon.md}' } },
+            md: { root: { width: '{size.control.lg}', height: '{size.control.lg}' }, icon: { width: '{size.icon.lg}', height: '{size.icon.lg}' } },
+            lg: { root: { width: '{size.control.xl}', height: '{size.control.xl}' }, icon: { width: '{size.icon.lg}', height: '{size.icon.lg}' } },
+        },
+        theme: {
+            light: { root: {}, '@states': { hover: { root: { 'background-color': '{color.bg-subtle}', color: '{color.fg-muted}' } }, active: { root: { 'background-color': '{color.bg-muted}' } } } },
+            dark: { root: { color: 'rgba(255, 255, 255, 0.7)' }, '@states': { hover: { root: { 'background-color': 'rgba(255, 255, 255, 0.1)', color: '{white}' } }, active: { root: { 'background-color': 'rgba(255, 255, 255, 0.16)' } } } },
+        },
+    },
+    examples: [
+        ex('Sizes', `<button type="button" class="cn-close-button" data-size="xs" data-theme="light" aria-label="Close">${ICON.x.replace('cn-icon', 'cn-close-button__icon')}</button> <button type="button" class="cn-close-button" data-size="sm" data-theme="light" aria-label="Close">${ICON.x.replace('cn-icon', 'cn-close-button__icon')}</button> <button type="button" class="cn-close-button" data-size="md" data-theme="light" aria-label="Close">${ICON.x.replace('cn-icon', 'cn-close-button__icon')}</button> <button type="button" class="cn-close-button" data-size="lg" data-theme="light" aria-label="Close">${ICON.x.replace('cn-icon', 'cn-close-button__icon')}</button>`),
+        ex('Dark theme on an inverse surface', `<div style="background:var(--cn-color-bg-inverse);padding:var(--cn-space-3);border-radius:var(--cn-radius-lg)"><button type="button" class="cn-close-button" data-size="sm" data-theme="dark" aria-label="Close">${ICON.x.replace('cn-icon', 'cn-close-button__icon')}</button></div>`),
+    ],
+    rules: [
+        'Always aria-label="Close" (or "Dismiss notification"), never a visible label.',
+        'Position: top-right, aligned with the title baseline, with the same inset as the surface padding minus 8px so the icon aligns with the content edge.',
+        'sm inside cards, alerts, toasts and chips; md/lg only in dialogs and drawers.',
+        'Escape must trigger the same close action wherever a close button exists.',
+    ],
+    a11y: ['It is a real <button type="button"> with an accessible name.', 'Focus returns to the trigger that opened the surface after closing.'],
+    related: ['dialog', 'drawer', 'toast', 'alert', 'icon-button'],
+};

package/lib/components/code.mjs

@@ -0,0 +1,123 @@
+import { RESET_BUTTON, ex, ICON, typeStyle } from "./_shared.mjs";
+// Code has no direct equivalent in the reference; it borrows the reference's conventions: inline
+// chips share the Kbd look (12px mono on gray-50, 1px gray-200 ring, radius 4), blocks are the
+// table-card surface (white, 1px gray-200 ring + shadow-xs, radius 12) with a gray-50 header in the
+// table-head voice (12px semibold gray-500) and a 28px utility copy button.
+const TRANSITION_FAST = {
+    'transition-property': 'background-color, color, box-shadow',
+    'transition-duration': '{motion.duration.fast}',
+    'transition-timing-function': '{motion.easing.linear}',
+};
+const ring = (color) => `inset 0 0 0 1px ${color}`;
+const inline = (text, size = 'md') => `<code class="cn-code" data-variant="inline" data-size="${size}">${text}</code>`;
+const copyButton = `<button type="button" class="cn-code__copy" aria-label="Copy code">${ICON.copy}</button>`;
+const block = (attrs, body, header) => `<figure class="cn-code" data-variant="block" ${attrs}>${header !== undefined ? `<div class="cn-code__header"><span>${header}</span>${copyButton}</div>` : ''}<pre class="cn-code__pre"><code>${body}</code></pre></figure>`;
+export const code = {
+    name: 'Code',
+    slug: 'code',
+    category: 'typography',
+    description: 'Monospace code, inline or as a block. Inline is a quiet chip in running text (gray-50, 1px gray-200 ring, radius 4); block is a card surface (white, hairline ring, shadow-xs, radius 12) with an optional file-name header and a copy button.',
+    usage: 'Inline for literals inside a sentence: commands, file names, attribute values, token names. Block for multi-line snippets, config files and terminal output. Keyboard shortcuts are Kbd, not Code; numbers in tables use numeric-md, not Code.',
+    anatomy: [
+        { part: 'root', element: 'code', description: 'Inline: a <code> span. Block: a <figure> wrapping the header and the pre.' },
+        { part: 'header', element: 'div', description: 'Optional bar above the code: file path or language in the table-head voice (12px semibold gray-500) keeping its case, since file paths are case-sensitive. Copy button on the right, bottom hairline, gray-50 fill, 44px tall.', optional: true },
+        { part: 'pre', element: 'pre', description: 'The code in <pre><code>. 14px mono (12px on sm), 16px padding, scrolls horizontally, never wraps.' },
+        { part: 'copy', element: 'button', description: '28px utility icon button (radius 6, 16px icon) in the header that copies the raw text. aria-label="Copy code".', optional: true },
+    ],
+    props: {
+        variant: { values: ['inline', 'block'], default: 'inline', description: 'inline = chip inside text for a literal; block = full-width card surface with radius 12 for multi-line code, with optional header and copy button.' },
+        size: { values: ['sm', 'md'], default: 'md', description: 'md = 12px inline and 14px block for docs and settings; sm = 11px inline and 12px block for tables, tooltips and popovers.' },
+    },
+    states: {},
+    base: {
+        root: { color: '{color.fg-default}' },
+        header: {
+            display: 'flex',
+            'align-items': 'center',
+            'justify-content': 'space-between',
+            gap: '{space.2}',
+            'min-height': '{size.control.lg}',
+            padding: '{space.2} {space.2} {space.2} {space.4}',
+            'background-color': '{color.bg-subtle}',
+            'box-shadow': '0 1px 0 0 {color.border-default}',
+            ...typeStyle('label-xs'),
+            'font-weight': '{font.weight.semibold}',
+            color: '{color.fg-subtle}',
+        },
+        pre: { margin: '0', overflow: 'auto', ...typeStyle('code-md'), color: '{color.fg-default}', 'tab-size': '2', 'white-space': 'pre' },
+        copy: {
+            ...RESET_BUTTON,
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            width: 'calc({size.control.xs} - {space.1})',
+            height: 'calc({size.control.xs} - {space.1})',
+            'border-radius': '{radius.md}',
+            color: '{color.fg-subtle}',
+            'font-size': '{size.icon.sm}',
+            ...TRANSITION_FAST,
+        },
+    },
+    variants: {
+        variant: {
+            inline: {
+                root: {
+                    display: 'inline',
+                    ...typeStyle('code-sm'),
+                    'background-color': '{color.bg-subtle}',
+                    'box-shadow': ring('{color.border-default}'),
+                    'border-radius': '{radius.sm}',
+                    padding: '{space.px} {space.1}',
+                    'overflow-wrap': 'anywhere',
+                    'vertical-align': 'baseline',
+                },
+            },
+            block: {
+                root: {
+                    display: 'flex',
+                    'flex-direction': 'column',
+                    width: '100%',
+                    'min-width': '0',
+                    'background-color': '{color.bg-surface}',
+                    'box-shadow': `${ring('{color.border-default}')}, {shadow.xs}`,
+                    'border-radius': '{radius.card}',
+                    overflow: 'hidden',
+                },
+            },
+        },
+        size: {
+            sm: { root: { 'font-size': '{font.size.2xs}' }, pre: { 'font-size': '{font.size.xs}', padding: '{space.3}' } },
+            md: { root: { 'font-size': '{font.size.xs}' }, pre: { 'font-size': '{font.size.sm}', padding: '{space.4}' } },
+        },
+    },
+    extraCss: `
+.cn-code .cn-code__pre code { font: inherit; color: inherit; background: none; padding: 0; border: 0; box-shadow: none; }
+.cn-code .cn-code__copy .cn-icon { width: {size.icon.sm}; height: {size.icon.sm}; }
+.cn-code .cn-code__copy:hover { background-color: {color.bg-muted}; color: {color.fg-muted}; }
+.cn-code .cn-code__copy:focus-visible { outline: none; box-shadow: {shadow.focus}; color: {color.fg-muted}; }`,
+    examples: [
+        ex('Inline', inline('npm install -g @lumen/canon'), '12px mono on gray-50 with a gray-200 ring, radius 4.'),
+        ex('Inline in a sentence', `<p class="cn-text-body-md" style="max-width:560px">Run ${inline('canon build')} after editing ${inline('design/tokens.json')}; the gallery at ${inline('dist/preview.html')} reloads on its own.</p>`),
+        ex('Block with file name and copy', block('data-size="md" style="max-width:560px"', `{\n  "name": "Lumen",\n  "prefix": "ui",\n  "brand": "#B4309F",\n  "radiusScale": 1,\n  "controlHeight": 40\n}`, 'design/system.json'), 'A card surface with a gray-50 header (12px semibold gray-500) and a 28px copy button.'),
+        ex('Block, terminal (no header)', block('data-size="md" style="max-width:560px"', `$ canon init "Lumen" --prefix ui\n✓ built 86 files → design/dist\n$ canon install\n✓ DESIGN.md, CLAUDE.md block and lint hook installed`)),
+        ex('Block, small', block('data-size="sm" style="max-width:480px"', `.ui-button[data-variant="primary"] {\n  background-color: var(--ui-color-bg-action);\n  color: var(--ui-color-fg-on-action);\n}`, 'components.css'), '12px mono with 12px padding for tables and popovers.'),
+        ex('Inline, small', `<span class="cn-text-body-sm" style="color:var(--cn-color-fg-muted)">Token ${inline('{color.bg-action}', 'sm')} uses the action color defined for the current theme.</span>`),
+    ],
+    rules: [
+        'Inline code is for literals the reader might type or see verbatim: commands, file names, attribute values, token names. Never for emphasis.',
+        'Block code never wraps; it scrolls horizontally. Keep lines under 80 characters in docs and trim leading indentation.',
+        'The header shows the file path or the language in its original case (design/system.json, not DESIGN/SYSTEM.JSON). Omit it for terminal commands and one-liners.',
+        'One copy button per block, in the header, 28px utility. It copies the raw text (not the rendered HTML) and confirms with a short "Copied" tooltip.',
+        'Escape HTML inside <code> (&lt; &gt; &amp;); never inject raw user content.',
+        'md in docs, settings and dialogs; sm inside tables, tooltips and popovers. Code does not scale with the surrounding heading.',
+        'Syntax highlighting, if any, uses fg-default, fg-muted, fg-accent and fg-info only. No rainbow palettes, no background per token.',
+    ],
+    a11y: [
+        'Use the semantic elements: <code> inline and <pre><code> for blocks, so screen readers announce code.',
+        'The copy button has aria-label="Copy code" and a visible focus ring; announce "Copied" in a live region after the click.',
+        'When a block overflows horizontally, give the <pre> tabindex="0" so keyboard users can scroll it.',
+        'Never convey meaning by color alone in highlighted code; keep textual markers (+ / − in diffs).',
+    ],
+    related: ['kbd', 'prose', 'tooltip'],
+};

package/lib/components/color-picker.mjs

@@ -0,0 +1,122 @@
+import { FOCUS_RING, RESET_BUTTON, TRANSITION_COLORS, ex } from "./_shared.mjs";
+// A small panel: an 8-column grid of round swatches and a hex field with a preview swatch and an
+// eyedropper button. Selection is a ring drawn with box-shadow so the swatch never changes size.
+const EYEDROPPER = '<svg class="cn-icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M10.75 2.25l3 3-1.5 1.5-.75-.75L6 11.5 3.5 12.5 4.5 10l5.5-5.5-.75-.75z"/><path d="M9.25 5.25l1.5 1.5"/></svg>';
+const swatch = (name, cssVar, selected = false) => `<button type="button" class="cn-color-picker__swatch" role="option" aria-selected="${selected}" aria-label="${name}" style="background:var(--cn-${cssVar})"></button>`;
+const GRID = [
+    ['Ink', 'neutral-950'], ['Slate', 'neutral-700'], ['Stone', 'neutral-400'], ['Mist', 'neutral-200'],
+    ['Brand 800', 'brand-800'], ['Brand 600', 'brand-600'], ['Brand 400', 'brand-400'], ['Brand 200', 'brand-200'],
+    ['Red 600', 'red-600'], ['Red 400', 'red-400'], ['Amber 500', 'amber-500'], ['Amber 300', 'amber-300'],
+    ['Green 600', 'green-600'], ['Green 400', 'green-400'], ['Blue 600', 'blue-600'], ['Blue 400', 'blue-400'],
+];
+const grid = (selected) => `<div class="cn-color-picker__swatches" role="listbox" aria-label="Preset colors">${GRID.map(([n, v]) => swatch(n, v, n === selected)).join('')}</div>`;
+const field = (hex, previewVar, attrs = '') => `<div class="cn-color-picker__field"><div class="cn-input" data-variant="default" data-size="sm"><span class="cn-color-picker__swatch" data-preview aria-hidden="true" style="background:var(--cn-${previewVar})"></span><input class="cn-input__field" type="text" value="${hex}" aria-label="Hex color" spellcheck="false" autocapitalize="characters" maxlength="7"${attrs}></div><button type="button" class="cn-color-picker__eyedropper" aria-label="Pick a color from the screen">${EYEDROPPER}</button></div>`;
+const picker = (size, inner) => `<div class="cn-color-picker" data-size="${size}" role="group" aria-label="Color">${inner}</div>`;
+export const colorPicker = {
+    name: 'ColorPicker',
+    slug: 'color-picker',
+    category: 'forms',
+    description: 'A compact panel for choosing a color: an 8-column grid of round swatches, and a hex Input with a preview swatch and an eyedropper button. The selected swatch shows an action-colored ring.',
+    usage: 'Use for brand colors, labels, tags and chart series where a curated palette is enough. Offer the hex field for exact values and the eyedropper when the browser supports it. Not for full-spectrum editing (a design tool); for a fixed set of 3–6 colors use a Radio group of swatches inline.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'The panel (flex column, gap space.3): 280px wide (240 on sm), padding space.4, surface-raised, hairline, radius panel, shadow-lg. role="group" with an aria-label. Carries data-size.' },
+        { part: 'swatches', element: 'div', description: '8-column grid, gap space.2. role="listbox" aria-label "Preset colors".' },
+        { part: 'swatch', element: 'button', description: 'One 24px round swatch (20px on sm) with a hairline; its color is an inline background. role="option" aria-selected, aria-label naming the color. With data-preview it is the 16px preview inside the hex field.' },
+        { part: 'field', element: 'div', description: 'Row (flex, gap space.2) with the hex Input (size sm, leading preview swatch) and the eyedropper button.' },
+        { part: 'eyedropper', element: 'button', description: 'Square outline icon button (control height sm) with a pipette icon. aria-label "Pick a color from the screen". Hide it when the EyeDropper API is unavailable.' },
+    ],
+    props: {
+        size: { values: ['sm', 'md'], default: 'md', description: 'md = 24px swatches in a 280px panel (default); sm = 20px swatches in a 240px panel for popovers inside dense settings.' },
+    },
+    states: {
+        selected: { selector: ' .cn-color-picker__swatch[aria-selected="true"]', description: 'On the __swatch: a 2px action-colored ring (box-shadow, offset by the panel surface) marks the current color. Styled in extraCss because it lives on a child.', markup: 'aria-selected="true" on the swatch' },
+        swatchHover: { selector: ' .cn-color-picker__swatch:hover', description: 'On the __swatch: the hairline strengthens. Styled in extraCss.', markup: 'native :hover on a swatch' },
+        swatchFocus: { selector: ' .cn-color-picker__swatch:focus-visible', description: 'On the __swatch: the focus ring. Styled in extraCss.', markup: 'native :focus-visible on a swatch' },
+        eyedropperHover: { selector: ' .cn-color-picker__eyedropper:hover', description: 'On the __eyedropper: subtle fill and default ink. Styled in extraCss.', markup: 'native :hover on the eyedropper' },
+    },
+    base: {
+        root: {
+            display: 'flex',
+            'flex-direction': 'column',
+            gap: '{space.3}',
+            width: 'calc({space.64} + {space.6})',
+            'max-width': '100%',
+            padding: '{space.4}',
+            'background-color': '{color.bg-surface-raised}',
+            border: '{border.width.thin} solid {color.border-default}',
+            'border-radius': '{radius.panel}',
+            'box-shadow': '{shadow.lg}',
+            color: '{color.fg-default}',
+            'z-index': '{z.popover}',
+        },
+        swatches: { display: 'grid', 'grid-template-columns': 'repeat(8, 1fr)', 'justify-items': 'center', gap: '{space.2}' },
+        swatch: {
+            ...RESET_BUTTON,
+            display: 'block',
+            'flex-shrink': '0',
+            width: '{space.6}',
+            height: '{space.6}',
+            'border-radius': '{radius.full}',
+            'box-shadow': 'inset 0 0 0 1px {color.border-default}',
+            'background-color': '{color.bg-muted}',
+            ...TRANSITION_COLORS,
+        },
+        field: { display: 'flex', 'align-items': 'center', gap: '{space.2}' },
+        eyedropper: {
+            ...RESET_BUTTON,
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            width: '{size.control.sm}',
+            height: '{size.control.sm}',
+            'font-size': '{size.icon.md}',
+            'background-color': '{color.bg-surface}',
+            border: '{border.width.thin} solid {color.border-control}',
+            'border-radius': '{radius.control}',
+            'box-shadow': '{shadow.xs}',
+            color: '{color.fg-subtle}',
+            ...TRANSITION_COLORS,
+        },
+    },
+    variants: {
+        size: {
+            sm: { root: { width: 'calc({space.56} + {space.4})', padding: '{space.3}', gap: '{space.2.5}' }, swatches: { gap: '{space.1.5}' }, swatch: { width: '{space.5}', height: '{space.5}' } },
+            md: { swatch: { width: '{space.6}', height: '{space.6}' } },
+        },
+    },
+    extraCss: `
+.cn-color-picker .cn-color-picker__swatch:hover { box-shadow: inset 0 0 0 1px {color.border-strong}; }
+.cn-color-picker .cn-color-picker__swatch[aria-selected="true"] { box-shadow: 0 0 0 2px {color.bg-surface-raised}, 0 0 0 4px {color.border-action}; }
+.cn-color-picker .cn-color-picker__swatch:focus-visible { ${Object.entries(FOCUS_RING).map(([k, v]) => `${k}: ${v}`).join('; ')}; }
+.cn-color-picker .cn-color-picker__swatch[aria-selected="true"]:focus-visible { box-shadow: 0 0 0 2px {color.bg-surface-raised}, 0 0 0 4px {color.border-action}, {shadow.focus}; }
+.cn-color-picker .cn-input .cn-color-picker__swatch[data-preview] { width: {space.4}; height: {space.4}; margin-inline-start: {space.3}; cursor: default; pointer-events: none; }
+.cn-color-picker .cn-input .cn-color-picker__swatch[data-preview] + .cn-input__field { padding-inline-start: {space.2}; font-family: {font.family.mono}; text-transform: uppercase; }
+.cn-color-picker .cn-input { flex: 1 1 auto; min-width: 0; }
+.cn-color-picker .cn-color-picker__eyedropper:hover { background-color: {color.bg-subtle}; color: {color.fg-default}; }
+.cn-color-picker .cn-color-picker__eyedropper:focus-visible { outline: none; box-shadow: {shadow.focus}; border-color: {color.border-action}; }`,
+    examples: [
+        ex('Swatch grid with hex field', picker('md', grid('Brand 600') + field('#B4309F', 'brand-600')), 'Sixteen preset swatches in two rows; Brand 600 is selected and previewed in the hex field. Swatch colors are inline backgrounds using the primitive scale variables.'),
+        ex('Custom value (no swatch match)', picker('md', grid() + field('#1E9E6A', 'green-600')), 'A typed hex that matches no preset: no swatch is selected, the preview shows the typed color.'),
+        ex('Small', picker('sm', grid('Blue 600') + field('#2563EB', 'blue-600')), '20px swatches in a 240px panel.'),
+        ex('Invalid hex', picker('md', grid() + field('#12G', 'neutral-200', ' aria-invalid="true" aria-describedby="hex-error"')).replace('</div></div>', `</div><p class="cn-text-body-sm" id="hex-error" style="margin:0;color:var(--cn-color-fg-danger)">Enter 6 hex digits, like #B4309F.</p></div>`), 'The hex Input takes the invalid state; the message sits under the row.'),
+    ],
+    rules: [
+        'Exactly 8 swatches per row and 1–3 rows (8–24 colors). Order them by hue family, darkest to lightest, neutrals first.',
+        'The swatch color is the only inline style allowed (style="background:…"), preferably a primitive scale variable so the palette follows the theme.',
+        'Selection is a ring, not a checkmark or a size change: aria-selected="true" draws the 2px action ring offset by the panel surface.',
+        'The hex field always mirrors the selection: clicking a swatch writes its hex; typing a valid hex selects a matching swatch or clears the selection.',
+        'Accept #RGB and #RRGGBB, normalize to uppercase #RRGGBB on blur, and mark the field invalid (with a message) otherwise.',
+        'Show the eyedropper only when window.EyeDropper exists; never render a disabled eyedropper.',
+        'The panel is statically positioned by the component; the app anchors it under its trigger (a swatch button or an Input) with an 8px offset and closes it on Escape.',
+        'One ColorPicker per popover; never inline in a form, where a Radio group of swatches is lighter.',
+    ],
+    a11y: [
+        'The swatch grid is role="listbox" with role="option" swatches; each has an aria-label naming the color ("Brand 600") and aria-selected. Arrow keys move between swatches, Enter or Space select.',
+        'The hex input has an accessible name ("Hex color") and aria-invalid plus aria-describedby when the value is not a valid hex.',
+        'The preview swatch inside the field is aria-hidden; the hex text is the accessible value.',
+        'The eyedropper is a real <button> with aria-label; it announces the picked color by updating the hex input.',
+        'Color is never the only cue for selection: the ring and the hex value both change.',
+    ],
+    related: ['input', 'popover', 'icon-button', 'radio'],
+};