canon-ds 0.1.0

package/lib/color.js

@@ -0,0 +1,160 @@
+// Color math: sRGB <-> OKLCH, scale generation, contrast. Plain JS so the same
+// code runs in Node (imported by the TS generators) and inline in preview.html.
+
+/** @param {string} hex */
+export function hexToRgb(hex) {
+  let h = hex.replace('#', '').trim();
+  if (h.length === 3 || h.length === 4) h = h.split('').map((c) => c + c).join('');
+  const n = parseInt(h.slice(0, 6), 16);
+  return [(n >> 16) & 255, (n >> 8) & 255, n & 255];
+}
+
+/** @param {number[]} rgb */
+export function rgbToHex([r, g, b]) {
+  const c = (v) => Math.max(0, Math.min(255, Math.round(v))).toString(16).padStart(2, '0');
+  return `#${c(r)}${c(g)}${c(b)}`.toUpperCase();
+}
+
+const srgbToLinear = (c) => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+const linearToSrgb = (c) => (c <= 0.0031308 ? 12.92 * c : 1.055 * c ** (1 / 2.4) - 0.055);
+
+/** @param {number[]} rgb 0..255 → oklab [L,a,b] */
+export function rgbToOklab([r, g, b]) {
+  const R = srgbToLinear(r / 255), G = srgbToLinear(g / 255), B = srgbToLinear(b / 255);
+  const l = Math.cbrt(0.4122214708 * R + 0.5363325363 * G + 0.0514459929 * B);
+  const m = Math.cbrt(0.2119034982 * R + 0.6806995451 * G + 0.1073969566 * B);
+  const s = Math.cbrt(0.0883024619 * R + 0.2817188376 * G + 0.6299787005 * B);
+  return [
+    0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+    1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+    0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+  ];
+}
+
+/** @param {number[]} lab → rgb 0..255 (unclamped floats) */
+export function oklabToRgb([L, a, b]) {
+  const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
+  const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
+  const s_ = L - 0.0894841775 * a - 1.291485548 * b;
+  const l = l_ ** 3, m = m_ ** 3, s = s_ ** 3;
+  const R = 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s;
+  const G = -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s;
+  const B = -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s;
+  return [linearToSrgb(R) * 255, linearToSrgb(G) * 255, linearToSrgb(B) * 255];
+}
+
+export function hexToOklch(hex) {
+  const [L, a, b] = rgbToOklab(hexToRgb(hex));
+  const C = Math.hypot(a, b);
+  let H = (Math.atan2(b, a) * 180) / Math.PI;
+  if (H < 0) H += 360;
+  return { L, C, H: C < 1e-4 ? 0 : H };
+}
+
+function inGamut(rgb) {
+  return rgb.every((v) => v >= -0.5 && v <= 255.5);
+}
+
+/** OKLCH → hex, reducing chroma until the color fits in sRGB. */
+export function oklchToHex({ L, C, H }) {
+  const rad = (H * Math.PI) / 180;
+  let c = C;
+  for (let i = 0; i < 24; i++) {
+    const rgb = oklabToRgb([L, c * Math.cos(rad), c * Math.sin(rad)]);
+    if (inGamut(rgb)) return rgbToHex(rgb);
+    c *= 0.9;
+  }
+  return rgbToHex(oklabToRgb([L, 0, 0]));
+}
+
+// Lightness / chroma curve for an 11-step scale (50…950). Tuned so the 500/600
+// steps carry the seed's saturation and the ends stay usable as surfaces/text.
+export const SCALE_STEPS = ['50', '100', '200', '300', '400', '500', '600', '700', '800', '900', '950'];
+const SCALE_L = [0.985, 0.965, 0.925, 0.865, 0.78, 0.68, 0.59, 0.51, 0.44, 0.38, 0.28];
+const SCALE_C = [0.04, 0.08, 0.17, 0.32, 0.6, 0.9, 1.0, 0.92, 0.78, 0.62, 0.45];
+
+/**
+ * Build a full 50…950 scale from one seed color. The seed lands on its
+ * nearest step; the rest is derived along the curve with the seed's hue.
+ * @param {string} seedHex
+ * @param {{ maxChroma?: number, hueShift?: number }} [opts]
+ */
+export function buildScale(seedHex, opts = {}) {
+  const seed = hexToOklch(seedHex);
+  const peak = Math.min(opts.maxChroma ?? 0.4, Math.max(seed.C, 0.002));
+  // Which step is the seed closest to (by lightness)? Anchor there.
+  let anchor = 0, best = Infinity;
+  SCALE_L.forEach((L, i) => { const d = Math.abs(L - seed.L); if (d < best) { best = d; anchor = i; } });
+  const scale = {};
+  SCALE_STEPS.forEach((step, i) => {
+    if (i === anchor) { scale[step] = seedHex.toUpperCase(); return; }
+    const C = (peak / SCALE_C[anchor]) * SCALE_C[i];
+    const H = seed.H + (opts.hueShift ?? 0) * ((i - anchor) / 10);
+    scale[step] = oklchToHex({ L: SCALE_L[i], C: Math.max(C, 0), H });
+  });
+  return scale;
+}
+
+/**
+ * Neutral scale: near-grey, optionally tinted with a hue at very low chroma.
+ * @param {{ hue?: number, chroma?: number, light?: string, dark?: string }} [opts]
+ *  light/dark override the 50 and 950 endpoints (e.g. an off-white canvas and a charcoal ink).
+ */
+export function buildNeutralScale(opts = {}) {
+  const hue = opts.hue ?? 0;
+  const chroma = opts.chroma ?? 0;
+  // Map the curve so it hits the requested endpoints exactly and stays monotonic.
+  const L0 = opts.light ? hexToOklch(opts.light).L : SCALE_L[0];
+  const L10 = opts.dark ? hexToOklch(opts.dark).L : SCALE_L[SCALE_L.length - 1];
+  const cMin = SCALE_L[SCALE_L.length - 1], cMax = SCALE_L[0];
+  const scale = {};
+  SCALE_STEPS.forEach((step, i) => {
+    const t = (SCALE_L[i] - cMin) / (cMax - cMin); // 1 at 50 … 0 at 950
+    const L = L10 + t * (L0 - L10);
+    scale[step] = oklchToHex({ L, C: chroma, H: hue });
+  });
+  if (opts.light) scale['50'] = opts.light.toUpperCase();
+  if (opts.dark) scale['950'] = opts.dark.toUpperCase();
+  return scale;
+}
+
+/** WCAG relative luminance */
+export function luminance(hex) {
+  const [r, g, b] = hexToRgb(hex).map((v) => srgbToLinear(v / 255));
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/** WCAG contrast ratio between two hex colors */
+export function contrast(a, b) {
+  const la = luminance(a), lb = luminance(b);
+  const [hi, lo] = la > lb ? [la, lb] : [lb, la];
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/** Perceptual distance in OKLab (0 = identical; < 0.02 is visually very close) */
+export function distance(hexA, hexB) {
+  const a = rgbToOklab(hexToRgb(hexA)), b = rgbToOklab(hexToRgb(hexB));
+  return Math.hypot(a[0] - b[0], a[1] - b[1], a[2] - b[2]);
+}
+
+/** Parse any css color literal we care about into hex (or null). */
+export function parseCssColor(str) {
+  const s = str.trim();
+  if (/^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(s)) return rgbToHex(hexToRgb(s));
+  let m = s.match(/^rgba?\(\s*(\d+)[\s,]+(\d+)[\s,]+(\d+)/i);
+  if (m) return rgbToHex([+m[1], +m[2], +m[3]]);
+  m = s.match(/^hsla?\(\s*([\d.]+)[\s,]+([\d.]+)%[\s,]+([\d.]+)%/i);
+  if (m) {
+    const h = +m[1] / 360, sat = +m[2] / 100, l = +m[3] / 100;
+    const q = l < 0.5 ? l * (1 + sat) : l + sat - l * sat, p = 2 * l - q;
+    const t2c = (t) => { if (t < 0) t += 1; if (t > 1) t -= 1; if (t < 1 / 6) return p + (q - p) * 6 * t; if (t < 1 / 2) return q; if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6; return p; };
+    return rgbToHex([t2c(h + 1 / 3) * 255, t2c(h) * 255, t2c(h - 1 / 3) * 255]);
+  }
+  return null;
+}
+
+/** "rgba(HEX, alpha)" helper used by tokens: returns rgba() string */
+export function alpha(hex, a) {
+  const [r, g, b] = hexToRgb(hex);
+  return `rgba(${r}, ${g}, ${b}, ${a})`;
+}

package/lib/components/_shared.mjs

@@ -0,0 +1,93 @@
+export const SIZES = ['xs', 'sm', 'md', 'lg', 'xl'];
+/** Height / horizontal padding / font / icon / gap for a control of a size. */
+export const CONTROL = {
+    xs: { height: '{size.control.xs}', px: '{size.controlPadding.xs}', font: '{font.control.xs}', icon: '{size.controlIcon.xs}', gap: '{space.1}', radius: '{radius.control}' },
+    sm: { height: '{size.control.sm}', px: '{size.controlPadding.sm}', font: '{font.control.sm}', icon: '{size.controlIcon.sm}', gap: '{space.1.5}', radius: '{radius.control}' },
+    md: { height: '{size.control.md}', px: '{size.controlPadding.md}', font: '{font.control.md}', icon: '{size.controlIcon.md}', gap: '{space.2}', radius: '{radius.control}' },
+    lg: { height: '{size.control.lg}', px: '{size.controlPadding.lg}', font: '{font.control.lg}', icon: '{size.controlIcon.lg}', gap: '{space.2}', radius: '{radius.control}' },
+    xl: { height: '{size.control.xl}', px: '{size.controlPadding.xl}', font: '{font.control.xl}', icon: '{size.controlIcon.xl}', gap: '{space.2.5}', radius: '{radius.control}' },
+};
+export const FOCUS_RING = {
+    outline: 'none',
+    'box-shadow': '{shadow.focus}',
+};
+export const FOCUS_RING_DANGER = {
+    outline: 'none',
+    'box-shadow': '{shadow.focus-danger}',
+};
+export const TRANSITION_COLORS = {
+    'transition-property': 'background-color, border-color, color, box-shadow, opacity',
+    'transition-duration': '{motion.duration.normal}',
+    'transition-timing-function': '{motion.easing.standard}',
+};
+export const TRANSITION_ALL = {
+    'transition-property': 'background-color, border-color, color, box-shadow, opacity, transform',
+    'transition-duration': '{motion.duration.normal}',
+    'transition-timing-function': '{motion.easing.standard}',
+};
+/** Typography declarations from a composite type style ref name (e.g. 'label-md'). */
+export function typeStyle(name) {
+    return {
+        'font-family': `{type.${name}.family}`,
+        'font-size': `{type.${name}.size}`,
+        'font-weight': `{type.${name}.weight}`,
+        'line-height': `{type.${name}.lineHeight}`,
+        'letter-spacing': `{type.${name}.letterSpacing}`,
+        'text-transform': `{type.${name}.transform}`,
+    };
+}
+export const RESET_BUTTON = {
+    appearance: 'none',
+    '-webkit-appearance': 'none',
+    border: '0',
+    margin: '0',
+    padding: '0',
+    background: 'none',
+    font: 'inherit',
+    color: 'inherit',
+    cursor: 'pointer',
+    'text-decoration': 'none',
+    'user-select': 'none',
+    '-webkit-tap-highlight-color': 'transparent',
+};
+export const STATE = {
+    hover: (extra = '') => ({ selector: `:hover:not(:disabled):not([aria-disabled="true"])${extra}`, description: 'Pointer over the element (mouse only; never the only cue).', markup: 'native :hover' }),
+    active: () => ({ selector: ':active:not(:disabled):not([aria-disabled="true"])', description: 'While pressed.', markup: 'native :active' }),
+    focus: () => ({ selector: ':focus-visible', description: 'Keyboard focus. Shows the 3px ring; never on mouse click.', markup: 'native :focus-visible' }),
+    disabled: () => ({ selector: ':disabled, &[aria-disabled="true"]', description: 'Not interactive. Reduced opacity, no hover, cursor not-allowed.', markup: 'disabled attribute (or aria-disabled="true")' }),
+    loading: () => ({ selector: '[data-loading]', description: 'Async action in flight. Shows the spinner, hides the label visually, keeps width.', markup: 'data-loading attribute' }),
+    invalid: () => ({ selector: '[aria-invalid="true"]', description: 'Validation failed. Danger border + danger focus ring; pair with a FieldError.', markup: 'aria-invalid="true"' }),
+    checked: () => ({ selector: ':checked', description: 'Selected.', markup: 'checked attribute' }),
+    selected: () => ({ selector: '[aria-selected="true"], &[data-selected]', description: 'Selected item.', markup: 'aria-selected="true" or data-selected' }),
+    current: () => ({ selector: '[aria-current="page"], &[data-active]', description: 'The current item (navigation).', markup: 'aria-current="page" or data-active' }),
+    open: () => ({ selector: '[data-state="open"]', description: 'Expanded / visible.', markup: 'data-state="open"' }),
+};
+export const SIZE_PROP = (values = SIZES, def = 'md') => ({
+    values: [...values],
+    default: def,
+    description: 'Control height and its matching padding, font and icon size.',
+});
+export const ex = (title, html, description) => ({ title, html: html.trim(), description });
+/** Inline SVG icons used in examples so the gallery renders without a font. */
+export const ICON = {
+    plus: '<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="M8 3v10M3 8h10"/></svg>',
+    arrow: '<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="M3 8h10M9 4l4 4-4 4"/></svg>',
+    check: '<svg class="cn-icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3 8.5l3 3 7-7"/></svg>',
+    x: '<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="M4 4l8 8M12 4l-8 8"/></svg>',
+    chevronDown: '<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="M4 6l4 4 4-4"/></svg>',
+    chevronRight: '<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 4l4 4-4 4"/></svg>',
+    search: '<svg class="cn-icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" aria-hidden="true"><circle cx="7" cy="7" r="4.5"/><path d="M10.5 10.5L14 14"/></svg>',
+    info: '<svg class="cn-icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" aria-hidden="true"><circle cx="8" cy="8" r="6.25"/><path d="M8 7v4M8 5v.5"/></svg>',
+    warning: '<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="M8 2.5l6 11H2l6-11zM8 7v3M8 11.5v.5"/></svg>',
+    dots: '<svg class="cn-icon" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><circle cx="3.5" cy="8" r="1.25"/><circle cx="8" cy="8" r="1.25"/><circle cx="12.5" cy="8" r="1.25"/></svg>',
+    spark: '<svg class="cn-icon" viewBox="0 0 16 16" fill="currentColor" aria-hidden="true"><path d="M8 1.5l1.6 4.9 4.9 1.6-4.9 1.6L8 14.5l-1.6-4.9L1.5 8l4.9-1.6z"/></svg>',
+    menu: '<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="M3 5h10M3 8h10M3 11h10"/></svg>',
+    calendar: '<svg class="cn-icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" aria-hidden="true"><rect x="2.5" y="3.5" width="11" height="10" rx="1.5"/><path d="M2.5 7h11M5.5 2v3M10.5 2v3"/></svg>',
+    home: '<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="M2.5 7.5L8 3l5.5 4.5V13a.5.5 0 01-.5.5H3a.5.5 0 01-.5-.5V7.5z"/></svg>',
+    user: '<svg class="cn-icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" aria-hidden="true"><circle cx="8" cy="5.5" r="2.75"/><path d="M2.75 13.5c.6-2.6 2.6-4 5.25-4s4.65 1.4 5.25 4"/></svg>',
+    inbox: '<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="M2.5 9.5h3l1 2h3l1-2h3M2.5 9.5V4a1 1 0 011-1h9a1 1 0 011 1v5.5M2.5 9.5V12a1 1 0 001 1h9a1 1 0 001-1V9.5"/></svg>',
+    settings: '<svg class="cn-icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" aria-hidden="true"><circle cx="8" cy="8" r="2"/><path d="M8 1.75v1.5M8 12.75v1.5M1.75 8h1.5M12.75 8h1.5M3.6 3.6l1.05 1.05M11.35 11.35l1.05 1.05M3.6 12.4l1.05-1.05M11.35 4.65l1.05-1.05"/></svg>',
+    external: '<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="M7 3.5H3.5v9h9V9M9.5 3h3.5v3.5M13 3L7.5 8.5"/></svg>',
+    trash: '<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="M3 4.5h10M6.5 4.5V3h3v1.5M4.5 4.5l.6 8.5h5.8l.6-8.5"/></svg>',
+    copy: '<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="5.5" y="5.5" width="8" height="8" rx="1.5"/><path d="M10.5 5.5V3.5a1 1 0 00-1-1h-6a1 1 0 00-1 1v6a1 1 0 001 1h2"/></svg>',
+};

package/lib/components/accordion.mjs

@@ -0,0 +1,136 @@
+import { RESET_BUTTON, ex, ICON, typeStyle } from "./_shared.mjs";
+// the reference FAQ accordion: full-width trigger rows (16 / 18px semibold ink) with a 20 / 24px
+// gray-400 chevron or plus on the right, gray-200 hairlines, 16px gray-600 body text, 16 / 24px of
+// vertical padding; optionally each item its own card.
+const HAIRLINE = '{border.width.thin} solid {color.border-default}';
+const ring = (color) => `inset 0 0 0 1px ${color}`;
+const PLUS = '<svg class="cn-accordion__icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" aria-hidden="true"><path class="cn-accordion__icon-v" d="M8 3v10"/><path d="M3 8h10"/></svg>';
+const item = (id, state, title, body, extra = '', icon = ICON.chevronDown.replace('cn-icon', 'cn-accordion__icon')) => `<div class="cn-accordion__item" data-state="${state}"><h3 style="margin:0;font:inherit"><button type="button" class="cn-accordion__trigger" id="${id}-trigger" aria-expanded="${state === 'open'}" aria-controls="${id}-content"${extra}>${title}${icon}</button></h3><div class="cn-accordion__content" id="${id}-content" role="region" aria-labelledby="${id}-trigger">${body}</div></div>`;
+const FAQ = (prefix, icon) => [
+    item(`${prefix}-1`, 'open', 'Is there a free trial available?', 'Yes, you can try Lumen for free for 30 days. If you want, we\'ll provide you with a free, personalized 30-minute onboarding call to get you up and running as soon as possible.', '', icon),
+    item(`${prefix}-2`, 'closed', 'Can I change my plan later?', 'Of course. Our pricing scales with your company. Chat to our friendly team to find a solution that works for you.', '', icon),
+    item(`${prefix}-3`, 'closed', 'What is your cancellation policy?', 'We understand that things change. You can cancel your plan at any time and we\'ll refund you the difference already paid.', '', icon),
+].join('');
+export const accordion = {
+    name: 'Accordion',
+    slug: 'accordion',
+    category: 'data-display',
+    description: 'Stacked disclosure sections in the reference FAQ style: a full-width semibold trigger row with a chevron (or plus) that flips on the right, and muted body text that shows under it when open. Gray-200 hairlines between items; optional separated or card framing.',
+    usage: 'Secondary content people open on demand: FAQ, advanced settings, details of a step, long explanations under a summary. Not for primary navigation (Tabs) and not for hiding required form fields.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'Column of items.' },
+        { part: 'item', element: 'div', description: 'One section. Carries data-state="open|closed", which drives the icon and hides the content. Hairline below.' },
+        { part: 'trigger', element: 'button', description: 'Full-width <button aria-expanded aria-controls> inside a heading element. Semibold ink label left, icon right; padding 16 / 24px by size.' },
+        { part: 'icon', element: 'svg', description: '20 / 24px chevron-down (rotates 180° when open) or plus (its vertical bar hides when open) at the end of the trigger, fg-subtle.' },
+        { part: 'icon-v', element: 'path', description: 'The vertical bar of the plus icon; hidden when the item is open so the plus becomes a minus.', optional: true },
+        { part: 'content', element: 'div', description: 'The revealed panel: role="region", fg-muted body text, prose width, padding below. Hidden when the item is closed.' },
+    ],
+    props: {
+        variant: {
+            values: ['default', 'separated', 'card'],
+            default: 'default',
+            description: 'default = items divided by hairlines, no frame (inside a Card or a page section); separated = each item is its own card (radius 12, ring) with a 16px gap (settings groups, FAQ on the canvas); card = the whole list in one card frame with items divided.',
+        },
+        size: {
+            values: ['sm', 'md', 'lg'],
+            default: 'md',
+            description: 'sm = 14px semibold triggers with 12px padding and 14px body (dense settings); md = 16px semibold triggers, 16px padding, 16px body (the default in cards and drawers); lg = 18px semibold triggers, 24px padding, 16px body with a 24px icon (the reference FAQ section).',
+        },
+    },
+    states: {
+        open: { selector: ' > [data-state="open"]', description: 'On an item, not the root: the chevron is rotated (or the plus becomes a minus) and the content is visible.', markup: 'data-state="open" on the item and aria-expanded="true" on its trigger' },
+        closed: { selector: ' > [data-state="closed"]', description: 'On an item: the content is display none.', markup: 'data-state="closed" on the item and aria-expanded="false" on its trigger' },
+        hover: { selector: ' > * > * > button:hover', description: 'On the trigger: the icon darkens; no background change.', markup: 'native :hover on the trigger' },
+        focus: { selector: ' > * > * > button:focus-visible', description: 'On the trigger: the 4px brand ring.', markup: 'native :focus-visible on the trigger' },
+        disabled: { selector: ' > * > * > button:disabled', description: 'On the trigger: 50% opacity, cannot open.', markup: 'disabled on the trigger button' },
+    },
+    base: {
+        root: { display: 'flex', 'flex-direction': 'column', width: '100%', 'min-width': '0', color: '{color.fg-default}' },
+        item: { 'border-bottom': HAIRLINE, 'min-width': '0' },
+        trigger: {
+            ...RESET_BUTTON,
+            display: 'flex',
+            'align-items': 'flex-start',
+            'justify-content': 'space-between',
+            gap: '{space.4}',
+            width: '100%',
+            padding: '{space.4} 0',
+            ...typeStyle('heading-xs'),
+            'text-align': 'left',
+            color: '{color.fg-default}',
+            'border-radius': '{radius.sm}',
+            'transition-property': 'color, box-shadow',
+            'transition-duration': '{motion.duration.fast}',
+            'transition-timing-function': '{motion.easing.linear}',
+        },
+        icon: {
+            width: '{size.icon.md}',
+            height: '{size.icon.md}',
+            'flex-shrink': '0',
+            'margin-top': '{space.0.5}',
+            color: '{color.fg-subtle}',
+            'transition-property': 'transform, color',
+            'transition-duration': '{motion.duration.normal}',
+            'transition-timing-function': '{motion.easing.standard}',
+        },
+        'icon-v': { 'transition-property': 'opacity', 'transition-duration': '{motion.duration.fast}', 'transition-timing-function': '{motion.easing.linear}' },
+        content: {
+            padding: '0 {space.10} {space.4} 0',
+            ...typeStyle('body-lg'),
+            color: '{color.fg-muted}',
+            'max-width': '{size.container.prose}',
+        },
+    },
+    variants: {
+        variant: {
+            default: { root: {} },
+            separated: {
+                root: { gap: '{space.4}' },
+                item: { 'border-bottom': '0', 'box-shadow': ring('{color.border-default}'), 'border-radius': '{radius.card}', 'background-color': '{color.bg-surface}', 'padding-inline': '{space.6}' },
+            },
+            card: {
+                root: { 'box-shadow': `${ring('{color.border-default}')}, {shadow.xs}`, 'border-radius': '{radius.card}', 'background-color': '{color.bg-surface}', overflow: 'hidden' },
+                item: { 'padding-inline': '{space.6}' },
+            },
+        },
+        size: {
+            sm: { trigger: { padding: '{space.3} 0', ...typeStyle('label-md') }, icon: { width: '{size.icon.sm}', height: '{size.icon.sm}', 'margin-top': '{space.0.5}' }, content: { padding: '0 {space.8} {space.3} 0', ...typeStyle('body-md') } },
+            md: { root: {} },
+            lg: { trigger: { padding: '{space.6} 0', ...typeStyle('heading-sm') }, icon: { width: '{size.icon.lg}', height: '{size.icon.lg}' }, content: { padding: '0 {space.12} {space.6} 0' } },
+        },
+    },
+    extraCss: `
+.cn-accordion__item[data-state="open"] > * > .cn-accordion__trigger .cn-accordion__icon { transform: rotate(180deg); }
+.cn-accordion__item[data-state="open"] > * > .cn-accordion__trigger .cn-accordion__icon:has(.cn-accordion__icon-v) { transform: none; }
+.cn-accordion__item[data-state="open"] > * > .cn-accordion__trigger .cn-accordion__icon-v { opacity: 0; }
+.cn-accordion__item[data-state="closed"] > .cn-accordion__content { display: none; }
+.cn-accordion__trigger:hover .cn-accordion__icon { color: {color.fg-muted}; }
+.cn-accordion__trigger:focus-visible { outline: none; box-shadow: {shadow.focus}; }
+.cn-accordion__trigger:disabled { opacity: {opacity.disabled}; cursor: not-allowed; }
+.cn-accordion[data-variant="default"] > .cn-accordion__item:last-child, .cn-accordion[data-variant="card"] > .cn-accordion__item:last-child { border-bottom: 0; }
+.cn-accordion[data-variant="default"] > .cn-accordion__item:first-child > * > .cn-accordion__trigger { padding-top: 0; }`,
+    examples: [
+        ex('Default (md), first item open', `<div class="cn-accordion" data-variant="default" data-size="md" style="max-width:640px">${FAQ('faq-a')}</div>`, '16px semibold triggers on gray-200 hairlines, 20px chevron, 16px muted body.'),
+        ex('FAQ (lg) with plus / minus icons', `<div class="cn-accordion" data-variant="default" data-size="lg" style="max-width:768px">${FAQ('faq-b', PLUS)}</div>`, 'The reference FAQ section: 18px semibold, 24px padding, a 24px plus that becomes a minus when open.'),
+        ex('Separated', `<div class="cn-accordion" data-variant="separated" data-size="md" style="max-width:640px">${FAQ('faq-c')}</div>`, 'Each item is its own card (radius 12, gray-200 ring), 16px apart; use on the canvas.'),
+        ex('Card, small, with a disabled item', `<div class="cn-accordion" data-variant="card" data-size="sm" style="max-width:560px">${item('faq-d-1', 'open', 'Approval rules', 'Every outgoing message needs one approval. Replies to an approved thread can be auto-approved per conversation.')}${item('faq-d-2', 'closed', 'Sending window', 'Messages go out between 08:00 and 18:00 in the recipient\'s time zone.')}${item('faq-d-3', 'closed', 'Custom signatures (Business plan)', 'Upgrade to edit signatures per sender.', ' disabled')}</div>`, 'One card frame with 14px triggers; the disabled trigger stays readable.'),
+    ],
+    rules: [
+        'Every item carries data-state="open|closed" and its trigger aria-expanded; never leave the state implicit.',
+        'Trigger labels are short noun phrases or questions in sentence case (≤ 10 words); no icons before the label, only the chevron or plus after it. One icon style per accordion.',
+        'Content is prose or a small form, capped at prose width with a 40px right inset so it never runs under the icon; it is not a place for tables or lists of records.',
+        'Default to all items closed except when there is one obvious first item; open at most one item by default.',
+        'Allow several items open at once unless the content is mutually exclusive; do not force single-open behavior for FAQs.',
+        'No hover background on the trigger; only the icon darkens. Focus ring on keyboard focus only.',
+        'default inside cards and sections; separated on the canvas for long lists; card for a compact block of 2–4 items; lg only for FAQ sections on marketing and help pages.',
+        'Do not nest accordions.',
+    ],
+    a11y: [
+        'The trigger is a <button> inside a heading (h2–h4 at the right level) with aria-expanded and aria-controls pointing to the content id.',
+        'The content has role="region" and aria-labelledby pointing to the trigger id.',
+        'Keyboard: Enter/Space toggle; Tab moves between triggers. Arrow-key navigation is optional and must not trap focus.',
+        'Closed content is display none, so it is removed from the tab order and the accessibility tree; do not use visibility tricks that keep it focusable.',
+        'Disabled triggers stay visible and readable; if the reason matters, say it in the label ("(Business plan)").',
+    ],
+    related: ['tabs', 'card', 'list', 'description-list', 'divider'],
+};

package/lib/components/account-card.mjs

@@ -0,0 +1,166 @@
+import { FOCUS_RING, RESET_BUTTON, TRANSITION_COLORS, ex, ICON, typeStyle } from "./_shared.mjs";
+// Account card: the signed-in person as a row: 40px avatar with a presence dot,
+// name and email, and a ⋯ button that opens the account Menu. Lives at the
+// bottom of the Sidebar and the mobile drawer, and in account switchers.
+const SELECTOR = '<svg class="cn-icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M5 6.25l3-3 3 3M5 9.75l3 3 3-3"/></svg>';
+const LOGOUT = '<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 13.5h-3a1 1 0 01-1-1v-9a1 1 0 011-1h3M10.5 11l3-3-3-3M13.5 8h-7"/></svg>';
+const card = (o) => `<div class="cn-account-card" data-variant="${o.variant ?? 'card'}" data-size="${o.size ?? 'md'}"${o.attrs ?? ''}><span class="cn-account-card__avatar" role="img" aria-label="${o.name}${o.status ? `, ${o.status}` : ''}">${o.initials}${o.status ? `<span class="cn-account-card__status" data-status="${o.status}"></span>` : ''}</span><div class="cn-account-card__content"><span class="cn-account-card__name">${o.name}</span><span class="cn-account-card__email">${o.email}</span></div>${o.menu ?? `<button type="button" class="cn-account-card__menu" aria-label="Account menu" aria-haspopup="menu" aria-expanded="false">${SELECTOR}</button>`}</div>`;
+const wrap = (inner, width = '296px') => `<div style="width:100%;max-width:${width}">${inner}</div>`;
+const menuItem = (label, icon, attrs = '') => `<button type="button" role="menuitem" class="cn-menu__item"${attrs}>${icon.replace('cn-icon', 'cn-menu__icon')}<span class="cn-menu__text">${label}</span></button>`;
+export const accountCard = {
+    name: 'AccountCard',
+    slug: 'account-card',
+    category: 'data-display',
+    description: 'The signed-in person as a row: a 40px avatar with a presence dot, name in label-md, email in body-sm muted, and a ⋯ button that opens the account Menu. A hairline card at the bottom of the Sidebar, a plain row inside menus, or a compact row in account switchers.',
+    usage: 'Use wherever the current account is shown with a way to act on it: the bottom of the Sidebar and the mobile drawer, the header of the account Menu, the rows of a workspace switcher. Not for other people in lists (use List with an Avatar) and not for a profile page header (PageHeader).',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'The row: flex, 12px gap and padding, bg-surface, hairline, radius card, shadow-xs. Relative so a Menu can anchor to it.' },
+        { part: 'avatar', element: 'span', description: '40px circle with initials or an <img>; relative so the status dot sits on its edge. role="img" + aria-label including presence.' },
+        { part: 'status', element: 'span', description: '10px presence dot at the bottom-right of the avatar with a 2px surface ring; data-status="online|away|busy|offline" colors it.', optional: true },
+        { part: 'content', element: 'div', description: 'Name over email, fills the row, truncates.' },
+        { part: 'name', element: 'span', description: 'label-md, one line, ellipsis.' },
+        { part: 'email', element: 'span', description: 'body-sm muted, one line, ellipsis.' },
+        { part: 'menu', element: 'button', description: '32px ghost button with a 16px up/down selector icon that opens the account Menu. aria-label "Account menu", aria-haspopup, aria-expanded.', optional: true },
+    ],
+    props: {
+        variant: {
+            values: ['card', 'plain', 'compact'],
+            default: 'card',
+            description: 'card = hairline card with shadow-xs, the Sidebar account card. plain = no border or shadow, 8px padding, for the header of a Menu or a Popover. compact = 8px padding, 32px avatar and smaller text for rows in an account switcher.',
+        },
+        size: {
+            values: ['sm', 'md'],
+            default: 'md',
+            description: 'md = 40px avatar, label-md name, body-sm email (sidebars, drawers). sm = 32px avatar, label-sm name, body-xs email for dense panels and popovers.',
+        },
+    },
+    states: {
+        hover: { selector: '[data-interactive]:hover', description: 'Pointer over a clickable card (only when the whole row is the trigger, marked data-interactive): subtle fill.', markup: 'data-interactive on the root and native :hover' },
+        selected: { selector: '[aria-selected="true"], &[data-selected]', description: 'The current account in a switcher: action-colored border and a 1px ring.', markup: 'aria-selected="true" (inside a listbox) or data-selected on the root' },
+        menuHover: { selector: ' .cn-account-card__menu:hover', description: 'Pointer over the ⋯ button (extraCss): subtle fill, ink icon.', markup: 'native :hover on .cn-account-card__menu' },
+        menuOpen: { selector: ' .cn-account-card__menu[aria-expanded="true"]', description: 'The account Menu is open (extraCss): the button keeps the subtle fill.', markup: 'aria-expanded="true" on .cn-account-card__menu' },
+        menuFocus: { selector: ' .cn-account-card__menu:focus-visible', description: 'Keyboard focus on the ⋯ button shows the focus ring (extraCss).', markup: 'native :focus-visible on .cn-account-card__menu' },
+    },
+    base: {
+        root: {
+            position: 'relative',
+            display: 'flex',
+            'align-items': 'center',
+            gap: '{space.3}',
+            width: '100%',
+            'min-width': '0',
+            padding: '{space.3}',
+            'background-color': '{color.bg-surface}',
+            border: '{border.width.thin} solid {color.border-default}',
+            'border-radius': '{radius.card}',
+            'box-shadow': '{shadow.xs}',
+            color: '{color.fg-default}',
+            ...TRANSITION_COLORS,
+        },
+        avatar: {
+            position: 'relative',
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            width: '{space.10}',
+            height: '{space.10}',
+            'border-radius': '{radius.full}',
+            'background-color': '{color.bg-subtle}',
+            color: '{color.fg-muted}',
+            ...typeStyle('label-sm'),
+            'letter-spacing': '{font.letterSpacing.wide}',
+            'text-transform': 'uppercase',
+            'user-select': 'none',
+        },
+        status: {
+            position: 'absolute',
+            bottom: '0',
+            right: '0',
+            width: '{space.2.5}',
+            height: '{space.2.5}',
+            'border-radius': '{radius.full}',
+            'background-color': '{color.fg-subtle}',
+            'box-shadow': '0 0 0 {border.width.medium} {color.bg-surface}',
+        },
+        content: { flex: '1 1 auto', 'min-width': '0', display: 'flex', 'flex-direction': 'column', gap: '{space.0.5}' },
+        name: { ...typeStyle('label-md'), 'line-height': '{font.lineHeight.snug}', 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' },
+        menu: {
+            ...RESET_BUTTON,
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            width: '{space.8}',
+            height: '{space.8}',
+            'border-radius': '{radius.md}',
+            color: '{color.fg-subtle}',
+            ...TRANSITION_COLORS,
+        },
+        '@states': {
+            hover: { root: { 'background-color': '{color.bg-subtle}', cursor: 'pointer' } },
+            selected: { root: { 'border-color': '{color.border-action}', 'box-shadow': '0 0 0 {border.width.thin} {color.border-action}' } },
+        },
+    },
+    variants: {
+        variant: {
+            card: { root: {} },
+            plain: { root: { border: '0', 'box-shadow': 'none', 'background-color': 'transparent', padding: '{space.2}' } },
+            compact: {
+                root: { padding: '{space.2}', gap: '{space.2.5}' },
+                avatar: { width: '{space.8}', height: '{space.8}', 'font-size': '{font.size.2xs}' },
+                status: { width: '{space.2}', height: '{space.2}' },
+                name: { ...typeStyle('label-sm'), 'line-height': '{font.lineHeight.snug}' },
+                email: { ...typeStyle('body-xs') },
+            },
+        },
+        size: {
+            md: { root: {} },
+            sm: {
+                avatar: { width: '{space.8}', height: '{space.8}', 'font-size': '{font.size.2xs}' },
+                status: { width: '{space.2}', height: '{space.2}' },
+                name: { ...typeStyle('label-sm'), 'line-height': '{font.lineHeight.snug}' },
+                email: { ...typeStyle('body-xs') },
+            },
+        },
+    },
+    extraCss: `
+.cn-account-card__avatar > img { display: block; width: 100%; height: 100%; object-fit: cover; border-radius: inherit; }
+.cn-account-card__status[data-status="online"] { background-color: {color.bg-success}; }
+.cn-account-card__status[data-status="away"] { background-color: {color.bg-warning}; }
+.cn-account-card__status[data-status="busy"] { background-color: {color.bg-danger}; }
+.cn-account-card__status[data-status="offline"] { background-color: {color.fg-subtle}; }
+.cn-account-card__menu .cn-icon { width: {size.icon.md}; height: {size.icon.md}; }
+.cn-account-card__menu:hover { background-color: {color.bg-subtle}; color: {color.fg-default}; }
+.cn-account-card__menu[aria-expanded="true"] { background-color: {color.bg-subtle}; color: {color.fg-default}; }
+.cn-account-card__menu:focus-visible { outline: none; box-shadow: ${FOCUS_RING['box-shadow']}; }
+.cn-account-card[data-variant="plain"][data-selected], .cn-account-card[data-variant="plain"][aria-selected="true"] { background-color: {color.bg-subtle}; border: 0; box-shadow: none; }`,
+    examples: [
+        ex('Card (sidebar)', wrap(card({ initials: 'MC', name: 'Maya Chen', email: 'maya@lumen.co', status: 'online' })), 'The bottom-of-sidebar card: 40px avatar with a presence dot, name, email, and the selector button that opens the account Menu.'),
+        ex('Plain (inside a menu or popover)', wrap(card({ variant: 'plain', initials: 'DC', name: 'Daniel Costa', email: 'daniel@lumen.co', status: 'away', menu: '' })), 'No border or shadow, 8px padding; the surrounding panel provides the frame.'),
+        ex('Compact rows in a switcher', wrap(`<div role="listbox" aria-label="Switch account" style="display:flex;flex-direction:column;gap:var(--cn-space-1)">${card({ variant: 'compact', initials: 'MC', name: 'Maya Chen', email: 'maya@lumen.co', status: 'online', attrs: ' role="option" aria-selected="true"', menu: '' })}${card({ variant: 'compact', initials: 'LD', name: 'Lumen Design', email: 'design@lumen.co', attrs: ' role="option" aria-selected="false" data-interactive', menu: '' })}${card({ variant: 'compact', initials: 'SA', name: 'Sofia Almeida', email: 'sofia@lumen.co', status: 'busy', attrs: ' role="option" aria-selected="false" data-interactive', menu: '' })}</div>`), 'aria-selected="true" draws the action-colored ring; the other rows are clickable (data-interactive).'),
+        ex('Small size and presence values', wrap(`<div style="display:flex;flex-direction:column;gap:var(--cn-space-3)">${card({ size: 'sm', initials: 'AK', name: 'Aisha Khan', email: 'aisha@lumen.co', status: 'online' })}${card({ size: 'sm', initials: 'NB', name: 'Noah Berg', email: 'noah@lumen.co', status: 'offline' })}</div>`), 'sm = 32px avatar, label-sm name, body-xs email. online · away · busy · offline.'),
+    ],
+    recipes: [
+        ex('With the account menu open', `<div class="cn-menu-anchor" style="width:100%;max-width:296px;min-height:232px">${card({ initials: 'MC', name: 'Maya Chen', email: 'maya@lumen.co', status: 'online', menu: `<button type="button" class="cn-account-card__menu" id="acct-menu-trigger" aria-label="Account menu" aria-haspopup="menu" aria-expanded="true" aria-controls="acct-menu">${SELECTOR}</button>` })}<div class="cn-menu" data-size="md" role="menu" id="acct-menu" aria-labelledby="acct-menu-trigger" data-state="open" data-floating style="width:100%">${menuItem('View profile', ICON.user)}${menuItem('Settings', ICON.settings)}<div class="cn-menu__separator" role="separator"></div>${menuItem('Log out', LOGOUT)}</div></div>`, 'The Menu anchors to the card with .cn-menu-anchor + data-floating and spans its width. Log out is last, after a separator.'),
+    ],
+    rules: [
+        'Shows the signed-in person only: their own name, their own email. Other people are List rows with an Avatar.',
+        'One action: the selector button opens the account Menu (profile, settings, switch account, log out). Never add a second button to the row.',
+        'Presence dots only when the product has real-time presence; otherwise omit the status part rather than showing everyone online.',
+        'card in the Sidebar and the mobile drawer; plain as the header of the account Menu or a Popover; compact for the rows of an account switcher.',
+        'Name and email truncate with an ellipsis; the full values are in the avatar\'s aria-label and the Menu header. Never wrap to two lines.',
+        'A clickable whole row (data-interactive) is for switchers only; in the Sidebar the row is static and the button is the trigger.',
+        'The selected account in a switcher gets the action-colored ring; hover uses the subtle fill. Never both on the same row.',
+        'Keep the avatar neutral (initials on bg-subtle or the photo); the accent tone is reserved for the AI agent.',
+    ],
+    a11y: [
+        'The avatar carries role="img" and an aria-label with the full name and presence ("Maya Chen, online"); the dot alone is decorative.',
+        'The menu button has aria-label "Account menu", aria-haspopup="menu", aria-expanded and aria-controls pointing at the Menu; Escape closes the menu and returns focus to it.',
+        'In a switcher the rows are role="option" inside role="listbox" with aria-selected; Up/Down move, Enter selects.',
+        'Name and email are plain text so they are read in order; do not hide them with CSS in narrow layouts, truncate instead.',
+        'Contrast: name in fg-default, email in fg-muted (AA on bg-surface and bg-subtle).',
+    ],
+    related: ['sidebar', 'mobile-header', 'menu', 'avatar', 'popover', 'list'],
+};