canon-ds 0.1.0

package/lib/components/progress-circle.mjs

@@ -0,0 +1,115 @@
+import { ex, typeStyle } from "./_shared.mjs";
+// SVG ring in a 100-unit viewBox: r = 42, circumference 2π·42 = 263.89. The indicator is a dashed
+// circle whose stroke-dashoffset = 263.89 × (1 − value) (half gauge: 131.95 × (1 − value)).
+// The label and caption are HTML centered over the ring; the svg sits behind them.
+const C = 263.89;
+const HALF = 131.95;
+const off = (pct, half = false) => ((half ? HALF : C) * (1 - pct / 100)).toFixed(1);
+const SIZES = {
+    xs: { box: '{space.16}', stroke: '10', label: 'label-xs' },
+    sm: { box: '{space.24}', stroke: '8', label: 'label-sm' },
+    md: { box: '{space.40}', stroke: '6', label: 'heading-sm' },
+    lg: { box: 'calc({space.40} + {space.10})', stroke: '5', label: 'heading-lg' },
+};
+const TONE = { action: '{color.bg-action}', success: '{color.bg-success}', warning: '{color.bg-warning}', danger: '{color.bg-danger}' };
+const ring = (o) => {
+    const half = o.variant === 'half';
+    return `<div class="cn-progress-circle" data-size="${o.size ?? 'md'}" data-variant="${o.variant ?? 'circle'}" data-tone="${o.tone ?? 'action'}" role="progressbar" aria-valuenow="${o.value}" aria-valuemin="0" aria-valuemax="100" aria-label="${o.label}"><svg viewBox="0 0 100 100" aria-hidden="true"><circle class="cn-progress-circle__track" cx="50" cy="50" r="42"/><circle class="cn-progress-circle__indicator" cx="50" cy="50" r="42" style="stroke-dashoffset:${off(o.value, half)}"/></svg><div class="cn-progress-circle__label">${o.text ?? `${o.value}%`}</div>${o.caption ? `<div class="cn-progress-circle__caption">${o.caption}</div>` : ''}</div>`;
+};
+export const progressCircle = {
+    name: 'ProgressCircle',
+    slug: 'progress-circle',
+    category: 'feedback',
+    description: 'A ring that shows a share of a whole: a hairline track, a round-capped indicator in the action (or status) color, and the value centered inside with an optional caption. The half variant is a gauge that opens downward.',
+    usage: 'Use for one headline percentage that deserves space: storage used, goal completion, a KPI on a dashboard card, an upload in a dialog. For inline or row-level progress use Progress (the bar); for a wait without a value use Spinner; for several metrics at once use ActivityGauge.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'Square box (inline-flex column, centered) that positions the svg behind the label. role="progressbar" with aria-valuenow/min/max and an aria-label. Carries data-size, data-variant, data-tone.' },
+        { part: 'track', element: 'circle', description: 'The full ring in the hairline color (stroke border-default). r = 42 in a 0 0 100 100 viewBox, fill none.' },
+        { part: 'indicator', element: 'circle', description: 'The value ring: same geometry, stroke in the tone color, round caps, dasharray 263.89. Its stroke-dashoffset is an inline style computed from the value.' },
+        { part: 'label', element: 'div', description: 'The centered value ("72%"), tabular numerals. Type scales with size: label-xs / label-sm / heading-sm / heading-lg.' },
+        { part: 'caption', element: 'div', description: 'body-xs muted line under the value ("Active users"). Hidden on xs.', optional: true },
+    ],
+    props: {
+        size: { values: ['xs', 'sm', 'md', 'lg'], default: 'md', description: 'Outer box 64 / 96 / 160 / 200px. xs = inside table rows and list items (value only); sm = stat tiles; md = a dashboard card; lg = a page hero or an empty-state style focus.' },
+        variant: { values: ['circle', 'half'], default: 'circle', description: 'circle = full ring, value in the middle; half = the top half of the ring as a gauge, value sitting on the chord. Use half when the number reads as a level (capacity, health) rather than completion.' },
+        tone: { values: ['action', 'success', 'warning', 'danger'], default: 'action', description: 'Indicator color. action = default; success = completed or healthy; warning = near a limit (≥ 80%); danger = over the limit or failed.' },
+    },
+    states: {},
+    base: {
+        root: {
+            position: 'relative',
+            display: 'inline-flex',
+            'flex-direction': 'column',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            width: '{space.40}',
+            height: '{space.40}',
+            color: '{color.fg-default}',
+            'vertical-align': 'middle',
+        },
+        track: { fill: 'none', stroke: '{color.border-default}', 'stroke-width': '6', transform: 'rotate(-90deg)', 'transform-origin': '50% 50%' },
+        indicator: {
+            fill: 'none',
+            stroke: '{color.bg-action}',
+            'stroke-width': '6',
+            'stroke-linecap': 'round',
+            'stroke-dasharray': '263.89',
+            'stroke-dashoffset': '263.89',
+            transform: 'rotate(-90deg)',
+            'transform-origin': '50% 50%',
+            'transition-property': 'stroke-dashoffset, stroke',
+            'transition-duration': '{motion.duration.slow}',
+            'transition-timing-function': '{motion.easing.standard}',
+        },
+        label: { position: 'relative', 'z-index': '{z.raised}', ...typeStyle('heading-sm'), 'font-variant-numeric': 'tabular-nums', color: '{color.fg-default}', 'text-align': 'center' },
+        caption: { position: 'relative', 'z-index': '{z.raised}', 'margin-top': '{space.0.5}', ...typeStyle('body-xs'), color: '{color.fg-muted}', 'text-align': 'center', 'max-width': '70%' },
+    },
+    variants: {
+        size: Object.fromEntries(Object.entries(SIZES).map(([k, v]) => [k, {
+                root: { width: v.box, height: v.box },
+                track: { 'stroke-width': v.stroke },
+                indicator: { 'stroke-width': v.stroke },
+                label: typeStyle(v.label),
+                ...(k === 'xs' ? { caption: { display: 'none' } } : {}),
+            }])),
+        variant: {
+            circle: { root: {} },
+            half: {
+                root: { 'justify-content': 'flex-end', 'padding-bottom': '{space.1}' },
+                track: { 'stroke-dasharray': '131.95 263.89', transform: 'rotate(180deg)' },
+                indicator: { 'stroke-dasharray': '131.95 263.89', 'stroke-dashoffset': '131.95', transform: 'rotate(180deg)' },
+            },
+        },
+        tone: Object.fromEntries(Object.entries(TONE).map(([t, color]) => [t, { indicator: { stroke: color } }])),
+    },
+    compound: Object.entries(SIZES).map(([k, v]) => ({ when: { variant: 'half', size: k }, block: { root: { height: `calc(${v.box} / 2)` } } })),
+    extraCss: `
+.cn-progress-circle > svg { position: absolute; inset: 0; width: 100%; height: 100%; display: block; overflow: visible; }
+.cn-progress-circle[data-variant="half"] > svg { height: 200%; }
+.cn-progress-circle[data-variant="half"] { overflow: hidden; }`,
+    examples: [
+        ex('Default (md, action)', ring({ value: 72, label: 'Active users: 72%', caption: 'Active users' }), 'stroke-dashoffset = 263.89 × (1 − 0.72) = 73.9.'),
+        ex('Sizes', `<div style="display:flex;flex-wrap:wrap;align-items:flex-end;gap:var(--cn-space-6)">${ring({ size: 'xs', value: 40, label: 'Storage used: 40%' })}${ring({ size: 'sm', value: 65, label: 'Onboarding: 65%', caption: 'Onboarding' })}${ring({ size: 'md', value: 72, label: 'Active users: 72%', caption: 'Active users' })}${ring({ size: 'lg', value: 88, label: 'Quarterly goal: 88%', caption: 'Quarterly goal' })}</div>`, '64 / 96 / 160 / 200px with label-xs / label-sm / heading-sm / heading-lg values.'),
+        ex('Tones', `<div style="display:flex;flex-wrap:wrap;gap:var(--cn-space-6)">${ring({ size: 'sm', tone: 'success', value: 100, label: 'Import complete', text: 'Done', caption: 'Import' })}${ring({ size: 'sm', tone: 'warning', value: 82, label: 'Seats used: 82%', caption: 'Seats used' })}${ring({ size: 'sm', tone: 'danger', value: 96, label: 'API quota: 96%', caption: 'API quota' })}</div>`, 'success at completion, warning from 80%, danger over the limit.'),
+        ex('Half gauge', `<div style="display:flex;flex-wrap:wrap;align-items:flex-end;gap:var(--cn-space-6)">${ring({ variant: 'half', size: 'md', value: 65, label: 'Deal health: 65%', caption: 'Deal health' })}${ring({ variant: 'half', size: 'sm', tone: 'warning', value: 84, label: 'Warehouse capacity: 84%', caption: 'Capacity' })}</div>`, 'Half the circumference: stroke-dashoffset = 131.95 × (1 − 0.65) = 46.2.'),
+        ex('Custom label', ring({ size: 'md', value: 56, label: '118 of 212 companies verified', text: '118', caption: 'of 212 verified' }), 'The label can be a count instead of a percentage; aria-valuenow still carries the percentage.'),
+    ],
+    rules: [
+        'Geometry is fixed: viewBox 0 0 100 100, r = 42, circumference 263.89. Set the value only through the inline style on the indicator: stroke-dashoffset = 263.89 × (1 − value / 100); for the half variant 131.95 × (1 − value / 100).',
+        'The label is HTML, never SVG text, so it uses the type scale and stays selectable; keep it to a number or a short word ("Done").',
+        'Tone follows the value, not the brand: switch to warning at ≥ 80% of a limit and to danger when the limit is exceeded or the task failed; success only at 100% or "healthy".',
+        'One ProgressCircle per card. Several percentages side by side are a table or an ActivityGauge.',
+        'xs has no caption: put the meaning in the row label next to it.',
+        'Never animate on first paint; transition only between value updates (260ms).',
+        'Use half for levels (capacity, health, score) and circle for completion (progress, share of a goal).',
+        'Stroke width scales with the size (10 / 8 / 6 / 5 viewBox units) so the ring stays around 6–10px at every size; do not override it.',
+    ],
+    a11y: [
+        'role="progressbar" with aria-valuenow, aria-valuemin="0", aria-valuemax="100" and an aria-label naming what is measured ("Active users: 72%").',
+        'Use aria-valuetext when the visible label is not a percentage ("118 of 212 verified").',
+        'The svg is aria-hidden; the label text is the visible equivalent of the ring, so color is never the only signal.',
+        'Respect prefers-reduced-motion: the dashoffset transition is the only motion and can be disabled globally.',
+    ],
+    related: ['progress', 'activity-gauge', 'stat', 'spinner'],
+};

package/lib/components/progress.mjs

@@ -0,0 +1,93 @@
+import { ex, typeStyle } from "./_shared.mjs";
+const TONE_FILL = {
+    action: '{color.bg-action}',
+    accent: '{color.bg-accent}',
+    success: '{color.bg-success}',
+    warning: '{color.bg-warning}',
+    danger: '{color.bg-danger}',
+};
+export const progress = {
+    name: 'Progress',
+    slug: 'progress',
+    category: 'feedback',
+    description: 'Horizontal bar that shows how much of a known task is done: a muted track, a filled indicator whose width is the value, and an optional label/value line above. Indeterminate mode slides a short segment when the total is unknown.',
+    usage: 'Use for tasks with a measurable share: an import, seats used of a plan, steps of an onboarding. Use the indeterminate state only briefly, while the total is being computed. For a wait without a value use Spinner; for loading content use Skeleton.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'Wrapper: header + track stacked with a 6px gap. role="progressbar" with aria-valuenow/min/max, or aria-busy in indeterminate mode.' },
+        { part: 'header', element: 'div', description: 'Optional line above the track: label on the left, value on the right, body-xs muted.', optional: true },
+        { part: 'label', element: 'span', description: 'What is being measured ("Importing prospects", "Seats used").', optional: true },
+        { part: 'value', element: 'span', description: 'The number, tabular ("42%", "12 / 40").', optional: true },
+        { part: 'track', element: 'div', description: 'The full-width muted bar, radius full, clips the indicator.' },
+        { part: 'indicator', element: 'div', description: 'The filled part. Width comes from an inline style (style="width:42%") and transitions smoothly.' },
+    ],
+    props: {
+        size: {
+            values: ['sm', 'md', 'lg'],
+            default: 'md',
+            description: 'Track height. sm = 2px for inside table rows and cards; md = 4px default; lg = 8px for a page-level task (import, onboarding).',
+        },
+        tone: {
+            values: ['action', 'accent', 'success', 'warning', 'danger'],
+            default: 'action',
+            description: 'Fill color. action = default; accent = an agent is working on it; success = completed; warning = near a limit (≥ 80%); danger = over the limit or failed.',
+        },
+    },
+    states: {
+        indeterminate: { selector: '[data-state="indeterminate"]', description: 'Total unknown: a 40%-wide segment slides across the track in a loop. No aria-valuenow; aria-busy="true".', markup: 'data-state="indeterminate" on the root (omit the inline width)' },
+    },
+    base: {
+        root: { display: 'flex', 'flex-direction': 'column', gap: '{space.1.5}', width: '100%', 'min-width': '0' },
+        header: { display: 'flex', 'align-items': 'baseline', 'justify-content': 'space-between', gap: '{space.3}', ...typeStyle('body-xs'), color: '{color.fg-muted}' },
+        label: { 'min-width': '0', overflow: 'hidden', 'text-overflow': 'ellipsis', 'white-space': 'nowrap' },
+        value: { 'flex-shrink': '0', 'font-variant-numeric': 'tabular-nums', color: '{color.fg-default}' },
+        track: { position: 'relative', width: '100%', height: '4px', 'background-color': '{color.bg-muted}', 'border-radius': '{radius.full}', overflow: 'hidden' },
+        indicator: {
+            height: '100%',
+            width: '0',
+            'background-color': '{color.bg-action}',
+            'border-radius': '{radius.full}',
+            'transition-property': 'width',
+            'transition-duration': '{motion.duration.slow}',
+            'transition-timing-function': '{motion.easing.standard}',
+        },
+        '@states': {
+            indeterminate: {
+                indicator: { width: '40%', animation: 'cn-progress-slide 1.2s {motion.easing.standard} infinite' },
+            },
+        },
+    },
+    variants: {
+        size: {
+            sm: { track: { height: '2px' } },
+            md: { track: { height: '4px' } },
+            lg: { track: { height: '8px' } },
+        },
+        tone: Object.fromEntries(Object.entries(TONE_FILL).map(([t, color]) => [t, { indicator: { 'background-color': color } }])),
+    },
+    extraCss: `
+@keyframes cn-progress-slide { from { transform: translateX(-100%); } to { transform: translateX(250%); } }`,
+    examples: [
+        ex('Default with label and value', `<div class="cn-progress" data-size="md" data-tone="action" role="progressbar" aria-labelledby="prg-import" aria-valuenow="42" aria-valuemin="0" aria-valuemax="100" style="max-width:360px"><div class="cn-progress__header"><span class="cn-progress__label" id="prg-import">Importing prospects</span><span class="cn-progress__value">42%</span></div><div class="cn-progress__track"><div class="cn-progress__indicator" style="width:42%"></div></div></div>`),
+        ex('Large, accent (agent working)', `<div class="cn-progress" data-size="lg" data-tone="accent" role="progressbar" aria-labelledby="prg-verify" aria-valuenow="118" aria-valuemin="0" aria-valuemax="212" style="max-width:360px"><div class="cn-progress__header"><span class="cn-progress__label" id="prg-verify">Verifying companies</span><span class="cn-progress__value">118 / 212</span></div><div class="cn-progress__track"><div class="cn-progress__indicator" style="width:56%"></div></div></div>`),
+        ex('Warning near a limit', `<div class="cn-progress" data-size="md" data-tone="warning" role="progressbar" aria-labelledby="prg-seats" aria-valuenow="34" aria-valuemin="0" aria-valuemax="40" style="max-width:360px"><div class="cn-progress__header"><span class="cn-progress__label" id="prg-seats">Seats used</span><span class="cn-progress__value">34 / 40</span></div><div class="cn-progress__track"><div class="cn-progress__indicator" style="width:85%"></div></div></div>`),
+        ex('Success, complete', `<div class="cn-progress" data-size="md" data-tone="success" role="progressbar" aria-labelledby="prg-done" aria-valuenow="100" aria-valuemin="0" aria-valuemax="100" style="max-width:360px"><div class="cn-progress__header"><span class="cn-progress__label" id="prg-done">Export</span><span class="cn-progress__value">Done</span></div><div class="cn-progress__track"><div class="cn-progress__indicator" style="width:100%"></div></div></div>`),
+        ex('Small, no header (inside a row)', `<div class="cn-progress" data-size="sm" data-tone="danger" role="progressbar" aria-label="Bounce rate" aria-valuenow="12" aria-valuemin="0" aria-valuemax="100" style="max-width:160px"><div class="cn-progress__track"><div class="cn-progress__indicator" style="width:12%"></div></div></div>`),
+        ex('Indeterminate', `<div class="cn-progress" data-size="md" data-tone="action" data-state="indeterminate" role="progressbar" aria-labelledby="prg-prep" aria-busy="true" style="max-width:360px"><div class="cn-progress__header"><span class="cn-progress__label" id="prg-prep">Preparing the search…</span></div><div class="cn-progress__track"><div class="cn-progress__indicator"></div></div></div>`),
+    ],
+    rules: [
+        'Width comes from the layout; the indicator width is the only inline style allowed (style="width:42%").',
+        'Always show the value when the user can act on it (seats, quota). Show "Done" instead of 100% when the task is finished.',
+        'Tone follows the value, not the brand: switch to warning at ≥ 80% of a limit and to danger when the limit is exceeded or the task failed.',
+        'accent means an agent is doing the work. Do not use it for user-driven uploads.',
+        'Indeterminate for at most a few seconds; if the total stays unknown, replace it with a Spinner and a sentence.',
+        'Sizes: sm inside rows and cards, md by default, lg for one page-level task at a time.',
+        'Never animate the indicator on first paint; only transitions between updates (260ms).',
+    ],
+    a11y: [
+        'role="progressbar" with aria-valuenow, aria-valuemin and aria-valuemax; use aria-valuetext when the number alone is unclear ("34 of 40 seats").',
+        'Name it with aria-labelledby pointing to the label, or aria-label when there is no visible label.',
+        'Indeterminate: omit aria-valuenow and set aria-busy="true" on the region being loaded.',
+        'Color is never the only signal: the value text or the label states warning/danger conditions.',
+    ],
+    related: ['spinner', 'skeleton', 'agent-presence', 'badge'],
+};

package/lib/components/prose.mjs

@@ -0,0 +1,96 @@
+import { ex, typeStyle } from "./_shared.mjs";
+/** Composite type style as a CSS declaration string for extraCss. */
+const ts = (name) => Object.entries(typeStyle(name)).map(([p, v]) => `${p}: ${v};`).join(' ');
+export const prose = {
+    name: 'Prose',
+    slug: 'prose',
+    category: 'typography',
+    description: 'Container for long-form text (help articles, agent reports, release notes, legal): sets the reading measure and styles every HTML element inside it — headings, paragraphs, lists, quotes, code, tables — from the type scale, so markdown output looks right without classes.',
+    usage: 'Wrap any block of rendered markdown or editorial HTML in it. Not for UI text (labels, descriptions, table cells), which uses the type utilities directly, and not for forms.',
+    anatomy: [
+        { part: 'root', element: 'article', description: 'The container. Max width 65ch, default text color, base font from size. Every element inside is styled by tag; the only class you may add inside is .cn-kicker above a heading.' },
+    ],
+    props: {
+        size: {
+            values: ['sm', 'md', 'lg'],
+            default: 'md',
+            description: 'Base text size. sm = body-sm with headings one step smaller (side panels, drawers, tooltips of an article); md = body-md, the app default (help center, reports); lg = body-lg for marketing and long reads.',
+        },
+    },
+    states: {},
+    base: {
+        root: {
+            'max-width': '{size.container.prose}',
+            color: '{color.fg-default}',
+            ...typeStyle('body-md'),
+            'overflow-wrap': 'break-word',
+        },
+    },
+    variants: {
+        size: {
+            sm: { root: { ...typeStyle('body-sm') } },
+            md: { root: {} },
+            lg: { root: { ...typeStyle('body-lg') } },
+        },
+    },
+    extraCss: `
+.cn-prose > :first-child { margin-top: 0; }
+.cn-prose > :last-child { margin-bottom: 0; }
+.cn-prose h1 { ${ts('heading-xl')} color: {color.fg-default}; margin-top: {space.10}; margin-bottom: {space.4}; }
+.cn-prose h2 { ${ts('heading-lg')} color: {color.fg-default}; margin-top: {space.8}; margin-bottom: {space.3}; }
+.cn-prose h3 { ${ts('heading-md')} color: {color.fg-default}; margin-top: {space.6}; margin-bottom: {space.2}; }
+.cn-prose h4 { ${ts('heading-sm')} color: {color.fg-default}; margin-top: {space.5}; margin-bottom: {space.2}; }
+.cn-prose p { margin-bottom: {space.4}; }
+.cn-prose ul, .cn-prose ol { padding-left: {space.5}; margin-bottom: {space.4}; }
+.cn-prose ul { list-style: disc; }
+.cn-prose ol { list-style: decimal; }
+.cn-prose li { margin-bottom: {space.1}; }
+.cn-prose li > ul, .cn-prose li > ol { margin-top: {space.1}; margin-bottom: 0; }
+.cn-prose li::marker { color: {color.fg-subtle}; }
+.cn-prose blockquote { border-left: {border.width.medium} solid {color.border-strong}; padding-left: {space.4}; margin-bottom: {space.4}; color: {color.fg-muted}; }
+.cn-prose blockquote p:last-child { margin-bottom: 0; }
+.cn-prose a { color: {color.fg-link}; text-decoration: underline; text-underline-offset: 3px; text-decoration-color: {color.border-strong}; }
+.cn-prose a:hover { color: {color.fg-link-hover}; text-decoration-color: currentColor; }
+.cn-prose strong { font-weight: {font.weight.semibold}; }
+.cn-prose code { ${ts('code-sm')} background-color: {color.bg-subtle}; border-radius: {radius.sm}; padding: 1px 5px; }
+.cn-prose pre { ${ts('code-md')} background-color: {color.bg-subtle}; border-radius: {radius.lg}; padding: {space.4}; margin-bottom: {space.4}; overflow: auto; }
+.cn-prose pre code { background: none; border-radius: 0; padding: 0; font: inherit; }
+.cn-prose hr { border: 0; border-top: {border.width.thin} solid {color.border-default}; margin: {space.8} 0; }
+.cn-prose img, .cn-prose video { border-radius: {radius.lg}; margin-bottom: {space.4}; }
+.cn-prose figure { margin-bottom: {space.4}; }
+.cn-prose figcaption { ${ts('body-xs')} color: {color.fg-muted}; margin-top: {space.2}; }
+.cn-prose table { ${ts('body-sm')} width: 100%; border-collapse: collapse; margin-bottom: {space.4}; }
+.cn-prose th { ${ts('kicker')} text-transform: uppercase; color: {color.fg-subtle}; text-align: left; padding: {space.2} {space.3}; border-bottom: {border.width.thin} solid {color.border-default}; }
+.cn-prose td { padding: {space.2} {space.3}; border-bottom: {border.width.thin} solid {color.border-subtle}; vertical-align: top; }
+.cn-prose .cn-kicker { margin-bottom: {space.2}; }
+.cn-prose[data-size="sm"] h1 { ${ts('heading-lg')} margin-top: {space.8}; margin-bottom: {space.3}; }
+.cn-prose[data-size="sm"] h2 { ${ts('heading-md')} margin-top: {space.6}; margin-bottom: {space.2}; }
+.cn-prose[data-size="sm"] h3 { ${ts('heading-sm')} margin-top: {space.5}; margin-bottom: {space.2}; }
+.cn-prose[data-size="sm"] h4 { ${ts('heading-xs')} margin-top: {space.4}; margin-bottom: {space.1.5}; }
+.cn-prose[data-size="sm"] p, .cn-prose[data-size="sm"] ul, .cn-prose[data-size="sm"] ol, .cn-prose[data-size="sm"] pre, .cn-prose[data-size="sm"] table, .cn-prose[data-size="sm"] blockquote { margin-bottom: {space.3}; }
+.cn-prose[data-size="sm"] table { ${ts('body-xs')} }
+.cn-prose[data-size="lg"] p, .cn-prose[data-size="lg"] ul, .cn-prose[data-size="lg"] ol { margin-bottom: {space.5}; }`,
+    examples: [
+        ex('Article (md)', `<article class="cn-prose" data-size="md"><h2>How agents verify a company</h2><p>Before a company reaches your shortlist, an agent checks it against three public sources: customs records, the national business registry and the company’s own site. Only companies with a match in at least two sources are marked <strong>verified</strong>.</p><ul><li>Customs records show real import volume and product codes (HS 0306 for frozen shrimp).</li><li>The registry confirms the legal entity, its age and its directors.</li><li>The website confirms the product line and the contact channel.</li></ul><blockquote><p>“Verified does not mean interested. It means the company exists, imports what you sell, and can be reached.”</p></blockquote><p>Each check leaves a trace. Open a prospect and look for the <code>verified_by</code> field; it lists the sources and the date of the last check.</p><table><thead><tr><th>Source</th><th>What it proves</th><th>Refreshed</th></tr></thead><tbody><tr><td>Customs records</td><td>Import volume, HS codes</td><td>Monthly</td></tr><tr><td>Business registry</td><td>Legal entity, directors</td><td>Quarterly</td></tr><tr><td>Company website</td><td>Product line, contacts</td><td>Weekly</td></tr></tbody></table><h3>When a check fails</h3><p>The prospect stays in the results as <em>unverified</em> and the agent retries after 7 days. You can force a re-check from the prospect drawer.</p><pre><code>GET /v1/prospects/nk-2041/verification
+→ { "verified": true, "sources": ["customs", "registry"], "checked_at": "2026-09-10" }</code></pre></article>`),
+        ex('Small (inside a drawer)', `<article class="cn-prose" data-size="sm" style="max-width:360px"><h3>Release notes · 11 Sep 2026</h3><p>Agents now read replies in Japanese and German and draft answers in the buyer’s language.</p><ol><li>Open a conversation with a reply in another language.</li><li>Check the draft; the original is shown below it.</li><li>Approve, edit, or ask the agent to rewrite.</li></ol><p>Questions? See <a href="#">Working with drafts</a>.</p></article>`),
+        ex('Large (marketing)', `<article class="cn-prose" data-size="lg"><h2>Find real buyers, not lists</h2><p>Vera reads trade data the way an analyst does: who imported what, from where, how often. Then it writes to the people who can say yes — and waits for your approval before anything is sent.</p><hr><p>Start with one product and one country. Most teams see the first verified reply within two weeks.</p></article>`),
+    ],
+    rules: [
+        'Prose is for rendered documents; UI text never goes inside it. If an element needs a class, it does not belong in Prose (except .cn-kicker above a heading).',
+        'One h1 per document; start articles inside the app at h2 because the page already has the h1.',
+        'Keep the measure: never widen beyond 65ch. Wide layouts put Prose in one column and media or a table of contents in the other.',
+        'Links are ink-colored and underlined, never blue. External links get the external icon after the text.',
+        'Code inline for identifiers and values; pre for anything with more than one line. Never pre for a single command inside a sentence.',
+        'Tables inside Prose are simple (≤ 4 columns); anything sortable or wider is a Table component outside the Prose.',
+        'Images and video inside Prose get radius lg and a caption in the figcaption, not in the paragraph below.',
+        'Size follows the container: sm in drawers and popovers, md in app pages, lg only on marketing and long-read pages.',
+    ],
+    a11y: [
+        'Use semantic elements (h2–h4 in order, ul/ol, blockquote, table with th) so the structure is navigable by headings and landmarks.',
+        'The root is an <article> (self-contained) or a <section> with aria-labelledby when it is part of a page.',
+        'Link text says where it goes ("Working with drafts"), never "click here"; underline is kept so color is not the only cue.',
+        'Code blocks scroll horizontally and are focusable (tabindex="0") when they overflow, so keyboard users can reach the content.',
+    ],
+    related: ['kicker', 'link', 'card', 'media-frame'],
+};

package/lib/components/radio.mjs

@@ -0,0 +1,160 @@
+import { ex, typeStyle } from "./_shared.mjs";
+// the reference radio button: 16px circle (sm) or 20px (md) with a 1px inset gray-300 ring on white,
+// brand-600 fill with a white 6 / 8px dot when selected, 8 / 12px to a 14 / 16px medium label with a
+// muted supporting line; circle nudged 2px down. Focus = 4px brand ring; disabled = circle at 50%
+// (gray-100 when unselected). Groups stack 16px apart.
+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}`;
+/** label wrapper → hidden input → circle → text (+ optional description) */
+const rd = (root, input, label, description = '', variant = 'default') => `<label class="cn-radio" data-variant="${variant}" ${root}><input class="cn-radio__input" type="radio" ${input}><span class="cn-radio__control" aria-hidden="true"><span class="cn-radio__indicator"></span></span><span class="cn-radio__label">${label}</span>${description ? `<span class="cn-radio__description">${description}</span>` : ''}</label>`;
+const stack = (...items) => `<div style="display:flex;flex-direction:column;gap:var(--cn-space-4)">${items.join('')}</div>`;
+export const radio = {
+    name: 'Radio',
+    slug: 'radio',
+    category: 'forms',
+    description: 'One-of-many choice: a 16px (sm) or 20px (md) circle with a gray-300 ring that fills with the brand color and shows a white dot, next to a medium label and a muted supporting line. Same anatomy as Checkbox; always used in a named group of 2–5 options.',
+    usage: 'Pick exactly one option when all options should be visible and compared (billing cycle, priority, delivery method). For more than 5 options use Select; for an on/off setting use Switch; for a view toggle in a toolbar use SegmentedControl. The card variant turns each option into a selectable bordered card.',
+    anatomy: [
+        { part: 'root', element: 'label', description: 'The <label> wrapping everything: hit target and accessible name. inline-grid: circle in column 1, text in column 2, 8px (sm) or 12px (md) apart.' },
+        { part: 'input', element: 'input', description: 'Native <input type="radio" name="…">, visually hidden but focusable. Options of one question share the same name.' },
+        { part: 'control', element: 'span', description: 'The visible circle: white with a 1px gray-300 inset ring, radius full, nudged 2px down to align with the first text line. aria-hidden.' },
+        { part: 'indicator', element: 'span', description: 'The white inner dot (6px on sm, 8px on md). Hidden until checked.' },
+        { part: 'label', element: 'span', description: '14px (sm) or 16px (md) medium text in the default ink. A noun phrase in sentence case, no period.' },
+        { part: 'description', element: 'span', description: 'Optional supporting line under the label, same size, regular weight, muted: price, consequence or example.', optional: true },
+    ],
+    props: {
+        size: { values: ['sm', 'md'], default: 'sm', description: 'sm = 16px circle with a 14px label: forms, dialogs, tables (the reference default); md = 20px circle with a 16px label: touch screens, onboarding and prominent choices.' },
+        variant: { values: ['default', 'card'], default: 'default', description: 'default = bare circle 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 selected. Use cards for plans and tiers where the description matters.' },
+    },
+    states: {
+        checked: { selector: ':has(:checked)', description: 'Circle fills with the brand color and shows the white dot. A card gets a 2px brand ring.', markup: 'checked attribute on the input' },
+        invalid: { selector: '[data-invalid], &:has([aria-invalid="true"])', description: 'Red-300 ring on every option of a required group with no selection. Pair with an error message under the group.', markup: 'aria-invalid="true" on the inputs, or data-invalid on each root' },
+        focus: { selector: ':has(:focus-visible)', description: 'Keyboard focus shows the 4px brand ring on the circle (on the whole card in the card variant).', markup: 'native :focus-visible on the input' },
+        disabled: { selector: '[data-disabled], &:has(:disabled)', description: 'Circle at 50% opacity (gray-100 fill when unselected), cursor not-allowed on the whole row; the text keeps its color. A checked disabled option keeps its dot.', 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.full}',
+            color: '{color.fg-on-action}',
+            ...TRANSITION_FAST,
+        },
+        indicator: { display: 'none', 'border-radius': '{radius.full}', 'background-color': 'currentColor', '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' } },
+            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}' },
+                indicator: { width: '{space.1.5}', height: '{space.1.5}' },
+            },
+            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}' },
+                indicator: { width: '{space.2}', height: '{space.2}' },
+                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-radio:has(:checked):has(:focus-visible) .cn-radio__control { box-shadow: inset 0 0 0 1px {color.bg-action}, {shadow.focus}; }
+.cn-radio[data-invalid]:has(:focus-visible) .cn-radio__control, .cn-radio:has([aria-invalid="true"]):has(:focus-visible) .cn-radio__control { box-shadow: inset 0 0 0 1px {color.border-danger}, {shadow.focus-danger}; }
+.cn-radio[data-variant="card"]:has(:checked):has(:focus-visible) { box-shadow: inset 0 0 0 2px {color.bg-action}, {shadow.focus}; }
+.cn-radio[data-variant="card"]:has(:checked):has(:focus-visible) .cn-radio__control { box-shadow: inset 0 0 0 1px {color.bg-action}; }
+.cn-radio-group { display: flex; flex-direction: column; gap: {space.4}; min-width: 0; margin: 0; padding: 0; border: 0; }
+.cn-radio-group__label { font-family: {type.label-sm.family}; font-size: {type.label-sm.size}; font-weight: {type.label-sm.weight}; line-height: {type.label-sm.lineHeight}; letter-spacing: {type.label-sm.letterSpacing}; color: {color.fg-default}; margin-bottom: {space.0.5}; }
+.cn-radio-group[data-orientation="horizontal"] { flex-direction: row; flex-wrap: wrap; row-gap: {space.3}; column-gap: {space.6}; }
+.cn-radio-group[data-orientation="horizontal"] .cn-radio-group__label { flex-basis: 100%; margin-bottom: 0; }`,
+    examples: [
+        ex('Default (unchecked)', rd('data-size="sm"', 'name="ex-cycle" value="monthly"', 'Monthly'), '16px circle, gray-300 ring; 14px medium label 8px away.'),
+        ex('Checked', rd('data-size="sm"', 'name="ex-checked" value="annual" checked', 'Annual'), 'Brand-600 fill with a 6px white dot.'),
+        ex('With supporting text', rd('data-size="sm"', 'name="ex-desc" value="team" checked', 'Team', '$99 per seat, billed monthly.'), 'The supporting line is the same size, regular weight, muted.'),
+        ex('Medium', rd('data-size="md"', 'name="ex-md" value="scale" checked', 'Scale', 'Unlimited seats, SSO and audit log.'), '20px circle with an 8px dot; 16px text 12px away with a 2px gap between lines.'),
+        ex('Invalid', rd('data-size="sm" data-invalid', 'name="ex-invalid" value="wire" aria-invalid="true" required', 'Wire transfer'), 'Every option of the group gets data-invalid; the error message sits under the group.'),
+        ex('Disabled', stack(rd('data-size="sm"', 'name="ex-disabled" value="card" checked disabled', 'Company card', 'Locked by Aisha Khan, your finance admin.'), rd('data-size="sm"', 'name="ex-disabled" value="invoice" disabled', 'Invoice')), 'The circle fades to 50% (gray-100 when unselected); the text keeps its color.'),
+        ex('Card', stack(rd('data-size="sm"', 'name="ex-card" value="starter"', 'Starter — $29/mo', 'Up to 5 members and 3 projects.', 'card'), rd('data-size="sm"', 'name="ex-card" value="team" checked', 'Team — $99/mo', 'Unlimited members, 20 projects and shared libraries.', 'card')), 'A selectable card: 1px gray-200 ring, radius 12, 16px padding; a 2px brand ring when selected.'),
+    ],
+    recipes: [
+        ex('Radio group (stacked)', `<div class="cn-radio-group" role="radiogroup" aria-labelledby="rg-billing"><div class="cn-radio-group__label" id="rg-billing">Billing cycle</div>${rd('data-size="sm"', 'name="billing" value="monthly"', 'Monthly', '$99 per seat, cancel anytime.')}${rd('data-size="sm"', 'name="billing" value="annual" checked', 'Annual', '$79 per seat, billed once a year. Save 20%.')}</div>`, 'A label names the question; options stack 16px apart; one is always checked.'),
+        ex('Radio group (horizontal)', `<div class="cn-radio-group" role="radiogroup" aria-labelledby="rg-priority" data-orientation="horizontal"><div class="cn-radio-group__label" id="rg-priority">Priority</div>${rd('data-size="sm"', 'name="priority" value="low"', 'Low')}${rd('data-size="sm"', 'name="priority" value="normal" checked', 'Normal')}${rd('data-size="sm"', 'name="priority" value="high"', 'High')}</div>`, 'Horizontal only for short one-word options without descriptions.'),
+        ex('Plans as cards', `<div class="cn-radio-group" role="radiogroup" aria-labelledby="rg-plan" style="max-width:420px"><div class="cn-radio-group__label" id="rg-plan">Plan</div>${rd('data-size="sm"', 'name="plan" value="starter"', 'Starter — $29/mo', 'Up to 5 members and 3 projects.', 'card')}${rd('data-size="sm"', 'name="plan" value="team" checked', 'Team — $99/mo', 'Unlimited members, 20 projects and shared libraries.', 'card')}${rd('data-size="sm"', 'name="plan" value="enterprise"', 'Enterprise', 'SSO, audit log and a named contact. Talk to Noah Berg.', 'card')}</div>`, 'Cards stack 16px apart; the whole card is the hit target and shows the focus ring.'),
+    ],
+    rules: [
+        'A radio group has 2–5 options and always one selected (pre-select the safest or most common). No selection is a validation error, not a state.',
+        'Wrap options in .cn-radio-group with a label; never a loose row of radios without a visible question.',
+        'Options are parallel noun phrases in sentence case ("Monthly", "Annual"), never questions or verbs. Put price and consequence in the supporting line.',
+        'Stacked 16px apart by default; horizontal (data-orientation="horizontal", 24px column gap) only for one-word options without descriptions.',
+        'If choosing an option reveals more fields, put them directly under that option indented by the label column (8px + circle width), not at the end of the group.',
+        'Use SegmentedControl instead when the choice is a view/mode in a toolbar; use Select when there are more than 5 options.',
+        'sm (16px) in forms and dialogs; md (20px) on touch screens and onboarding. Cards for plans and tiers where the description matters.',
+    ],
+    a11y: [
+        'Each option is a <label> wrapping a native <input type="radio">; every input of the group shares the same name so arrow keys move between them.',
+        'The group container has role="radiogroup" (or is a <fieldset> with <legend>) and aria-labelledby pointing at the group label.',
+        'Keyboard: Tab enters the group on the checked option; Up/Down and Left/Right move and select; Space selects when nothing is checked.',
+        'Invalid: aria-invalid="true" on every input plus aria-describedby pointing at the error under the group.',
+        'The circle and dot are aria-hidden; state comes from the native input, so no aria-checked is needed.',
+    ],
+    related: ['checkbox', 'switch', 'segmented-control', 'select', 'field'],
+};

package/lib/components/rating.mjs

@@ -0,0 +1,93 @@
+import { ex, typeStyle } from "./_shared.mjs";
+// Star rating for display: five stars painted amber when filled and border-strong when empty, a
+// numeric value in label-sm and a muted count. The badge variant packs five 12px stars and the value
+// into a hairline pill for testimonials and marketing cards.
+const STAR = 'M10 1.5l2.6 5.4 5.9.8-4.3 4.1 1.1 5.9L10 14.9l-5.3 2.8 1.1-5.9L1.5 7.7l5.9-.8z';
+const star = (filled) => filled === 'half'
+    ? `<svg class="cn-rating__star" data-filled="half" viewBox="0 0 20 20" aria-hidden="true"><path d="${STAR}"/><path d="${STAR}"/></svg>`
+    : `<svg class="cn-rating__star" data-filled="${filled}" viewBox="0 0 20 20" aria-hidden="true"><path d="${STAR}"/></svg>`;
+/** Five stars for a value between 0 and 5; a fraction ≥ .25 and < .75 renders a half star. */
+const stars = (value) => Array.from({ length: 5 }, (_, i) => star(value >= i + 0.75 ? 'true' : value >= i + 0.25 ? 'half' : 'false')).join('');
+const rate = (o) => `<div class="cn-rating" data-variant="${o.variant ?? 'stars'}" data-size="${o.size ?? 'md'}" role="img" aria-label="${o.label}">${o.inner}</div>`;
+export const rating = {
+    name: 'Rating',
+    slug: 'rating',
+    category: 'data-display',
+    description: 'Read-only star rating: five stars (filled amber, half, or empty in the hairline color), an optional numeric value and a muted count. The badge variant packs five small stars and the value into a hairline pill; inline shows one star with the number for dense rows.',
+    usage: 'Display reviews, satisfaction scores and quality grades next to a product, a vendor or a testimonial. It is not an input: for collecting a rating use a Radio group of stars. Do not use stars for anything that is not a rating (priority, importance).',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'Inline row (flex, align center, gap space.1). role="img" with aria-label "4.5 out of 5 stars, 128 reviews". Carries data-variant and data-size.' },
+        { part: 'star', element: 'svg', description: 'One star. data-filled="true" paints it amber, "false" the hairline color, "half" splits it with a clip on the right half. 16px (sm) or 20px (md); 12px inside the badge.' },
+        { part: 'value', element: 'span', description: 'The number ("4.5"), label-sm, tabular. Follows the stars with a small gap.', optional: true },
+        { part: 'count', element: 'span', description: 'Muted body-sm context: "(128 reviews)", "from 1,240 reviews".', optional: true },
+        { part: 'badge', element: 'span', description: 'Hairline pill (surface fill, radius full, padding-inline space.2) holding five 12px stars and the value. Used by the badge variant.', optional: true },
+    ],
+    props: {
+        variant: {
+            values: ['stars', 'badge', 'inline'],
+            default: 'stars',
+            description: 'stars = five stars with an optional value and count, for product pages and vendor cards; badge = a pill with five small stars and the value, followed by muted text, for testimonials and marketing proof lines; inline = a single star plus the value (and count), for table cells, list rows and compact cards.',
+        },
+        size: { values: ['sm', 'md'], default: 'md', description: 'md = 20px stars with label-sm value (cards, headers); sm = 16px stars with label-xs value (rows, dense lists). The badge always uses 12px stars.' },
+    },
+    states: {},
+    base: {
+        root: { display: 'inline-flex', 'align-items': 'center', gap: '{space.1}', 'vertical-align': 'middle', color: '{color.fg-default}' },
+        star: { display: 'block', 'flex-shrink': '0', width: '{size.icon.lg}', height: '{size.icon.lg}', fill: '{color.border-strong}' },
+        value: { 'margin-inline-start': '{space.1}', ...typeStyle('label-sm'), 'font-variant-numeric': 'tabular-nums', color: '{color.fg-default}' },
+        count: { ...typeStyle('body-sm'), color: '{color.fg-muted}', 'white-space': 'nowrap' },
+        badge: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            gap: '{space.0.5}',
+            height: '{space.6}',
+            'padding-inline': '{space.2}',
+            'background-color': '{color.bg-surface}',
+            border: '{border.width.thin} solid {color.border-default}',
+            'border-radius': '{radius.full}',
+            'box-shadow': '{shadow.xs}',
+            'white-space': 'nowrap',
+        },
+    },
+    variants: {
+        variant: {
+            stars: { root: {} },
+            badge: { root: { gap: '{space.2}' }, star: { width: '{size.icon.xs}', height: '{size.icon.xs}' }, value: { ...typeStyle('label-xs'), 'margin-inline-start': '{space.1}' } },
+            inline: { root: { gap: '{space.1.5}' }, value: { 'margin-inline-start': '0' } },
+        },
+        size: {
+            sm: { star: { width: '{size.icon.md}', height: '{size.icon.md}' }, value: { 'font-size': '{font.size.xs}' }, count: { 'font-size': '{font.size.xs}' } },
+            md: { star: { width: '{size.icon.lg}', height: '{size.icon.lg}' } },
+        },
+    },
+    extraCss: `
+.cn-rating .cn-rating__star[data-filled="true"] { fill: {amber.400}; }
+.cn-rating .cn-rating__star[data-filled="half"] path:last-child { fill: {amber.400}; clip-path: inset(0 50% 0 0); }
+.cn-rating[data-variant="badge"] .cn-rating__star { width: {size.icon.xs}; height: {size.icon.xs}; }`,
+    examples: [
+        ex('Stars with value and count', rate({ value: 4.5, label: '4.5 out of 5 stars, 128 reviews', inner: `${stars(4.5)}<span class="cn-rating__value">4.5</span><span class="cn-rating__count">(128 reviews)</span>` }), 'Four filled stars, one half star, the number and the count.'),
+        ex('Stars only', rate({ value: 5, label: '5 out of 5 stars', inner: stars(5) }), 'When the number is shown elsewhere (a heading, a table column).'),
+        ex('Badge (proof line)', rate({ variant: 'badge', value: 4.9, label: '4.9 out of 5 stars from 1,240 reviews', inner: `<span class="cn-rating__badge">${stars(4.9)}<span class="cn-rating__value">4.9</span></span><span class="cn-rating__count">from 1,240 reviews</span>` }), 'Five 12px stars and the value inside a hairline pill, the count as muted text after it.'),
+        ex('Inline (rows and cells)', `<div style="display:flex;flex-direction:column;gap:var(--cn-space-2);align-items:flex-start">${rate({ variant: 'inline', value: 4.8, label: '4.8 out of 5 stars, 312 reviews', inner: `${star('true')}<span class="cn-rating__value">4.8</span><span class="cn-rating__count">(312)</span>` })}${rate({ variant: 'inline', size: 'sm', value: 3.6, label: '3.6 out of 5 stars, 41 reviews', inner: `${star('true')}<span class="cn-rating__value">3.6</span><span class="cn-rating__count">(41)</span>` })}</div>`, 'One star and the number; the count in parentheses.'),
+        ex('Sizes', `<div style="display:flex;flex-direction:column;gap:var(--cn-space-2);align-items:flex-start">${rate({ size: 'sm', value: 4, label: '4 out of 5 stars', inner: `${stars(4)}<span class="cn-rating__value">4.0</span>` })}${rate({ size: 'md', value: 4, label: '4 out of 5 stars', inner: `${stars(4)}<span class="cn-rating__value">4.0</span>` })}</div>`, '16px stars (sm) and 20px stars (md).'),
+        ex('Low and empty', `<div style="display:flex;flex-direction:column;gap:var(--cn-space-2);align-items:flex-start">${rate({ value: 2.3, label: '2.3 out of 5 stars, 9 reviews', inner: `${stars(2.3)}<span class="cn-rating__value">2.3</span><span class="cn-rating__count">(9 reviews)</span>` })}${rate({ value: 0, label: 'No ratings yet', inner: `${stars(0)}<span class="cn-rating__count">No ratings yet</span>` })}</div>`, 'Empty stars stay visible in the hairline color so the scale is always readable.'),
+    ],
+    recipes: [
+        ex('Testimonial header', `<div style="display:flex;flex-direction:column;gap:var(--cn-space-2);max-width:420px">${rate({ variant: 'badge', value: 5, label: '5 out of 5 stars', inner: `<span class="cn-rating__badge">${stars(5)}<span class="cn-rating__value">5.0</span></span>` })}<p class="cn-text-body-md" style="margin:0">“Lumen found the buyers we had been chasing for two years in one afternoon.”</p><p class="cn-text-body-sm" style="margin:0;color:var(--cn-color-fg-muted)">Elena Rossi, Head of Procurement</p></div>`, 'Badge above the quote, attribution in muted text below.'),
+    ],
+    rules: [
+        'Always five stars. Fill from the left; a fraction from .25 to .75 is a half star, never a partial fill at other widths.',
+        'Filled stars are amber, empty stars the hairline color. Never recolor stars by brand or by score; the number carries the nuance.',
+        'Show the value with one decimal ("4.5", "4.0") and the count with a thousands separator ("1,240 reviews"). Round the value, never the count.',
+        'stars on product and vendor pages; inline in tables, lists and compact cards; badge only on marketing and testimonial blocks.',
+        'With fewer than 5 reviews show the count and no value; with 0 show empty stars and "No ratings yet".',
+        'Rating is display only. Collecting a rating is a form control (Radio group of stars) with its own focus and keyboard behavior.',
+        'Sizes match the surrounding text: sm next to body-sm, md next to body-md and headings.',
+    ],
+    a11y: [
+        'The root is role="img" with aria-label that states the score and the count ("4.5 out of 5 stars, 128 reviews"); the stars are aria-hidden.',
+        'The visible value and count repeat the aria-label content, so sighted and screen-reader users get the same information.',
+        'Color is not the only cue: filled and empty stars differ in luminance and the number is always available nearby or in the label.',
+    ],
+    related: ['badge', 'stat', 'card', 'radio'],
+};