canon-ds 0.1.0

package/lib/components/alert.mjs

@@ -0,0 +1,154 @@
+import { FOCUS_RING, RESET_BUTTON, TRANSITION_COLORS, ex, ICON, typeStyle } from "./_shared.mjs";
+// tone → { soft bg (tint), soft border, featured-icon color }
+const TONES = {
+    neutral: { bg: '{color.bg-subtle}', border: '{color.border-control}', fg: '{color.fg-muted}' },
+    brand: { bg: '{color.bg-action-subtle}', border: '{color.border-action}', fg: '{color.fg-accent}' },
+    info: { bg: '{color.bg-info-subtle}', border: '{color.border-info}', fg: '{color.fg-info}' },
+    success: { bg: '{color.bg-success-subtle}', border: '{color.border-success}', fg: '{color.fg-success}' },
+    warning: { bg: '{color.bg-warning-subtle}', border: '{color.border-warning}', fg: '{color.fg-warning}' },
+    danger: { bg: '{color.bg-danger-subtle}', border: '{color.border-danger}', fg: '{color.fg-danger}' },
+};
+// soft = tinted surface + tone border. Text stays neutral (title fg-default, description fg-muted) in every tone: only the icon, the border and the tint carry the color.
+const compound = Object.entries(TONES).map(([t, v]) => ({
+    when: { tone: t, variant: 'soft' },
+    block: { root: { 'background-color': v.bg, 'border-color': v.border } },
+}));
+const icon = (name) => `<span class="cn-alert__icon" aria-hidden="true">${ICON[name]}</span>`;
+const dismiss = `<button type="button" class="cn-alert__dismiss" aria-label="Dismiss">${ICON.x}</button>`;
+const link = (label) => `<button type="button" class="cn-button" data-variant="link" data-size="sm"><span class="cn-button__label">${label}</span></button>`;
+const actions = (a = 'Dismiss', b = 'View changes') => `<div class="cn-alert__actions">${link(a)}${link(b)}</div>`;
+export const alert = {
+    name: 'Alert',
+    slug: 'alert',
+    category: 'feedback',
+    description: 'Callout with a featured icon (a 20px line icon inside two faint concentric rings), a semibold title, a one-line description, optional link actions and a close button. 16px padding, 12px radius; tinted (soft) or white (outline); in the flow of the page, floating with a shadow, or as a full-width bar.',
+    usage: 'Use for messages tied to the content on screen: a failed sync, a plan limit, a confirmation after a form saves, a release note above a list. Not for transient feedback (use Toast), not for one-line page-wide notices (use Banner), and not for decisions that block the flow (use Dialog).',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'The callout surface. role="alert" for danger/warning that appear dynamically, role="status" otherwise. Carries data-tone, data-variant, data-layout.' },
+        { part: 'icon', element: 'span', description: 'Featured icon, "outline" style: a 20px line icon (ICON.info / ICON.check / ICON.warning inside the span) in the tone color with two concentric 2px rings at 30% and 10% opacity (28px and 38px). aria-hidden.' },
+        { part: 'content', element: 'div', description: 'Text column: title, description, actions. Flexes to fill; min-width 0 so long text wraps.' },
+        { part: 'title', element: 'div', description: 'text-sm semibold (label-md), one line. Says what happened ("We’ve just released a new feature"), not "Error".' },
+        { part: 'description', element: 'p', description: 'text-sm muted (body-md, fg-muted), one or two sentences under the title. Says what to do next.', optional: true },
+        { part: 'actions', element: 'div', description: 'Row of link Buttons (size sm), 12px apart: a quiet one first ("Dismiss", gray) then the one that does something ("View changes", brand). At most two. Inside the content column, or a direct child of the root in the full-width layout (then it sits on the right).', optional: true },
+        { part: 'dismiss', element: 'button', description: 'Close button in the top-right corner: 36px hit area, 20px X icon, fg-subtle, 8px from the edges. Requires aria-label="Dismiss".', optional: true },
+    ],
+    props: {
+        tone: {
+            values: ['neutral', 'brand', 'info', 'success', 'warning', 'danger'],
+            default: 'neutral',
+            description: 'Meaning. neutral = context or a tip (gray icon; "default"/"gray"); brand = product news and upsell (brand icon, brand tint); info = something to know, no action needed (blue); success = a completed action; warning = needs attention soon, nothing is broken; danger = failed or blocked, the user must act ("error").',
+        },
+        variant: {
+            values: ['soft', 'outline'],
+            default: 'soft',
+            description: 'soft = tinted background (tone-50) with the tone border; outline = white surface with the neutral hairline and only the icon in the tone color ("default" alert; quieter, for lists of alerts or inside cards).',
+        },
+        layout: {
+            values: ['inline', 'floating', 'full-width'],
+            default: 'inline',
+            description: 'inline = sits in the content flow above the thing it describes, no shadow (default); floating = the same card with shadow-lg, for alerts rendered over the page (bottom of the viewport, over a table); full-width = edge-to-edge bar with square corners, a bottom hairline and the actions on the right ("full-width" alert), placed directly under the topbar or at the top of a section.',
+        },
+    },
+    states: {
+        dismissHover: { selector: ' .cn-alert__dismiss:hover', description: 'Pointer over the close button: subtle fill, icon one step darker. Styled in extraCss because it lives on a child.', markup: 'native :hover on .cn-alert__dismiss' },
+        dismissFocus: { selector: ' .cn-alert__dismiss:focus-visible', description: 'Keyboard focus on the close button shows the focus ring. Styled in extraCss.', markup: 'native :focus-visible on .cn-alert__dismiss' },
+    },
+    base: {
+        root: {
+            position: 'relative',
+            display: 'flex',
+            'align-items': 'flex-start',
+            gap: '{space.4}',
+            width: '100%',
+            padding: '{space.4}',
+            'border-radius': '{radius.card}',
+            border: '{border.width.thin} solid {color.border-control}',
+            'background-color': '{color.bg-surface}',
+            color: '{color.fg-default}',
+            ...typeStyle('body-md'),
+        },
+        icon: {
+            position: 'relative',
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            width: '{size.icon.md}',
+            height: '{size.icon.md}',
+            color: '{color.fg-muted}',
+        },
+        content: { flex: '1 1 auto', 'min-width': '0' },
+        title: { ...typeStyle('label-md'), color: '{color.fg-default}' },
+        description: { ...typeStyle('body-md'), 'margin-top': '{space.1}', color: '{color.fg-muted}' },
+        actions: { display: 'flex', 'flex-wrap': 'wrap', 'align-items': 'center', gap: '{space.3}', 'margin-top': '{space.3}' },
+        dismiss: {
+            ...RESET_BUTTON,
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            width: '{size.control.sm}',
+            height: '{size.control.sm}',
+            'margin-block': 'calc({space.2} * -1)',
+            'margin-inline-end': 'calc({space.2} * -1)',
+            'border-radius': '{radius.control}',
+            color: '{color.fg-subtle}',
+            ...TRANSITION_COLORS,
+            'transition-duration': '{motion.duration.fast}',
+        },
+    },
+    variants: {
+        tone: Object.fromEntries(Object.entries(TONES).map(([t, v]) => [t, { icon: { color: v.fg } }])),
+        variant: {
+            soft: { root: {} },
+            outline: { root: { 'background-color': '{color.bg-surface}', 'border-color': '{color.border-control}' } },
+        },
+        layout: {
+            inline: { root: {} },
+            floating: { root: { 'box-shadow': '{shadow.lg}' } },
+            'full-width': {
+                root: { 'border-radius': '{radius.none}', 'border-inline': '0', 'border-top': '0', 'box-shadow': 'none', 'align-items': 'center', 'padding-inline': '{space.8}' },
+                dismiss: { 'margin-block': '0' },
+            },
+        },
+    },
+    compound,
+    extraCss: `
+.cn-alert .cn-alert__icon .cn-icon { width: {size.icon.md}; height: {size.icon.md}; }
+.cn-alert .cn-alert__icon::before, .cn-alert .cn-alert__icon::after { content: ''; position: absolute; border-radius: {radius.full}; border: {border.width.medium} solid currentColor; pointer-events: none; }
+.cn-alert .cn-alert__icon::before { inset: -4px; opacity: 0.3; }
+.cn-alert .cn-alert__icon::after { inset: -9px; opacity: 0.1; }
+.cn-alert .cn-alert__dismiss .cn-icon { width: {size.icon.md}; height: {size.icon.md}; }
+.cn-alert .cn-alert__dismiss:hover { background-color: {color.bg-subtle}; color: {color.fg-muted}; }
+.cn-alert .cn-alert__dismiss:focus-visible { outline: none; box-shadow: ${FOCUS_RING['box-shadow']}; }
+.cn-alert .cn-alert__actions .cn-button[data-variant="link"]:first-child:not(:last-child) { color: {color.fg-muted}; }
+.cn-alert[data-layout="full-width"] > .cn-alert__actions { margin-top: 0; margin-inline-start: auto; flex-shrink: 0; }`,
+    examples: [
+        ex('Default (outline, neutral, inline)', `<div class="cn-alert" data-tone="neutral" data-variant="outline" data-layout="inline" role="status" style="max-width:640px">${icon('info')}<div class="cn-alert__content"><div class="cn-alert__title">We’ve just released a new feature</div><p class="cn-alert__description">Check out the all new dashboard view. Pages now load faster.</p>${actions()}</div>${dismiss}</div>`, 'The "default" alert: white surface, gray featured icon, two link actions (gray then brand), close button top-right.'),
+        ex('Brand (soft)', `<div class="cn-alert" data-tone="brand" data-variant="soft" data-layout="inline" role="status" style="max-width:640px">${icon('spark')}<div class="cn-alert__content"><div class="cn-alert__title">We’ve just released a new feature</div><p class="cn-alert__description">Check out the all new dashboard view. Pages now load faster.</p>${actions()}</div>${dismiss}</div>`),
+        ex('Info (soft)', `<div class="cn-alert" data-tone="info" data-variant="soft" data-layout="inline" role="status" style="max-width:640px">${icon('info')}<div class="cn-alert__content"><div class="cn-alert__title">A new export format is available</div><p class="cn-alert__description">You can now download reports as an Excel workbook with one sheet per team.</p></div>${dismiss}</div>`),
+        ex('Success (soft)', `<div class="cn-alert" data-tone="success" data-variant="soft" data-layout="inline" role="status" style="max-width:640px">${icon('check')}<div class="cn-alert__content"><div class="cn-alert__title">Successfully updated profile</div><p class="cn-alert__description">Your changes have been saved and will appear in the team directory within a few minutes.</p>${actions('Dismiss', 'View profile')}</div>${dismiss}</div>`),
+        ex('Warning (soft)', `<div class="cn-alert" data-tone="warning" data-variant="soft" data-layout="inline" role="alert" style="max-width:640px">${icon('warning')}<div class="cn-alert__content"><div class="cn-alert__title">Your trial ends in 3 days</div><p class="cn-alert__description">Add a payment method to keep your projects and team members after 14 Sep.</p>${actions('Dismiss', 'Upgrade plan')}</div>${dismiss}</div>`),
+        ex('Danger (soft)', `<div class="cn-alert" data-tone="danger" data-variant="soft" data-layout="inline" role="alert" style="max-width:640px">${icon('warning')}<div class="cn-alert__content"><div class="cn-alert__title">There was a problem with that action</div><p class="cn-alert__description">We couldn’t save your changes. Check your connection and try again.</p>${actions('Dismiss', 'Try again')}</div></div>`, 'Danger alerts have no close button while the problem is open; they leave when it is fixed.'),
+        ex('Floating (shadow-lg)', `<div class="cn-alert" data-tone="neutral" data-variant="outline" data-layout="floating" role="status" style="max-width:640px">${icon('info')}<div class="cn-alert__content"><div class="cn-alert__title">We’ve just released a new feature</div><p class="cn-alert__description">Check out the all new dashboard view. Pages now load faster.</p>${actions()}</div>${dismiss}</div>`, 'Same card with shadow-lg, for alerts rendered over the page (bottom of the viewport, above a table).'),
+        ex('Full-width bar', `<div class="cn-alert" data-tone="neutral" data-variant="outline" data-layout="full-width" role="status">${icon('info')}<div class="cn-alert__content"><div class="cn-alert__title">We’ve just released a new feature</div><p class="cn-alert__description">Check out the all new dashboard view. Pages now load faster.</p></div>${actions()}${dismiss}</div>`, 'Edge to edge under the topbar: square corners, bottom hairline only, actions on the right as a direct child of the root.'),
+    ],
+    rules: [
+        'Title says what happened in plain words ("We’ve just released a new feature"); the description says what to do next. Never "Error" or "Warning" as the title.',
+        'Keep it to one title plus at most two sentences. If it needs more, link to a page.',
+        'At most two actions, size sm, variant link: the quiet one first ("Dismiss", rendered gray), the useful one last ("View changes", brand). Never a primary or danger Button inside an Alert.',
+        'Text stays neutral in every tone (title fg-default, description fg-muted). Only the icon, the border and the tint carry the color, so a soft danger alert is still readable.',
+        'inline alerts sit at the top of the region they describe (above the form, inside the card); floating alerts are the same card with shadow-lg over the page; full-width bars go directly under the topbar or at the top of a section, never inside a card.',
+        'Use soft by default. Use outline (the "default" alert) when several alerts stack, when the alert is inside another tinted surface, or when the message is neutral news.',
+        'Only neutral, brand, info and success alerts are dismissible without resolving anything. Danger alerts disappear when the problem is fixed, not when the user closes them.',
+        'Icon is required and comes from the tone: neutral/info/brand → ICON.info (or ICON.spark for brand news), success → ICON.check, warning/danger → ICON.warning. Wrap it in the icon span; the rings are drawn by CSS.',
+        'Do not animate alerts in or out; they appear with the content.',
+    ],
+    a11y: [
+        'role="alert" for warning/danger alerts inserted after load (assistive tech announces them immediately); role="status" for neutral/brand/info/success.',
+        'The featured icon is decorative (aria-hidden on the span); the title carries the meaning, so color is never the only signal.',
+        'The close button needs aria-label="Dismiss" and is the last focusable element inside the alert.',
+        'Actions are real <button> or <a> elements in reading order after the description.',
+    ],
+    related: ['banner', 'toast', 'dialog', 'button', 'badge'],
+};

package/lib/components/app-store-button.mjs

@@ -0,0 +1,108 @@
+import { RESET_BUTTON, TRANSITION_COLORS, STATE, ex } from "./_shared.mjs";
+// "Download on the App Store" / "Get it on Google Play" badges: a 40px pill-ish box with a 24px
+// store glyph, a tiny kicker line and a big label. Dark (inverse fill, thin grey border) or outline
+// (surface fill, hairline). The glyphs in the examples are simple monochrome shapes, not trademark art.
+const GLYPH = {
+    apple: '<circle cx="12" cy="13.5" r="6.5" fill="none" stroke="currentColor" stroke-width="1.75"/><path d="M12 7c0-2.2 1.3-3.5 3.5-3.5" fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round"/>',
+    google: '<path d="M6.5 4.5v15l12.5-7.5z" fill="currentColor"/>',
+};
+const COPY = {
+    apple: { kicker: 'Download on the', label: 'App Store', name: 'App Store' },
+    google: { kicker: 'Get it on', label: 'Google Play', name: 'Google Play' },
+};
+const badge = (store, theme = 'dark') => `<a href="#" class="cn-app-store-button" data-store="${store}" data-theme="${theme}" aria-label="${COPY[store].kicker} ${COPY[store].name}"><svg class="cn-app-store-button__icon" viewBox="0 0 24 24" aria-hidden="true">${GLYPH[store]}</svg><span class="cn-app-store-button__kicker">${COPY[store].kicker}</span><span class="cn-app-store-button__label">${COPY[store].label}</span></a>`;
+const row = (...items) => `<div style="display:flex;flex-wrap:wrap;align-items:center;gap:var(--cn-space-3)">${items.join('')}</div>`;
+export const appStoreButton = {
+    name: 'AppStoreButton',
+    slug: 'app-store-button',
+    category: 'actions',
+    description: 'The download badge for a mobile app: a 40px box with the store glyph on the left and two lines of text, a tiny kicker ("Download on the") over a bold store name. Dark by default, or outline on dark and busy backgrounds.',
+    usage: 'Marketing pages, app footers and "get the app" banners, always as a pair (both stores) or a single badge when only one exists. Never inside the app shell, never as a generic download button (use Button with a leading icon).',
+    anatomy: [
+        { part: 'root', element: 'a', description: 'The badge link (inline-grid: icon column + two text rows). href points to the store listing; aria-label repeats the two lines. Carries data-store and data-theme.' },
+        { part: 'icon', element: 'svg', description: '24px store glyph spanning both text rows. Monochrome, currentColor. aria-hidden.' },
+        { part: 'kicker', element: 'span', description: 'The small first line ("Download on the", "Get it on"), 11px medium, at 70% of the text color.' },
+        { part: 'label', element: 'span', description: 'The store name in 16px semibold with tight tracking.' },
+    ],
+    props: {
+        store: { values: ['apple', 'google'], default: 'apple', description: 'apple = "Download on the App Store"; google = "Get it on Google Play". The store also picks the glyph and the copy in the markup.' },
+        theme: { values: ['dark', 'outline'], default: 'dark', description: 'dark = inverse fill with light text and a thin grey border, the standard badge on light pages; outline = surface fill with a hairline and default ink, for dark or photographic backgrounds and for footers where a black block would be too heavy.' },
+    },
+    states: {
+        hover: STATE.hover(),
+        active: STATE.active(),
+        focus: STATE.focus(),
+    },
+    base: {
+        root: {
+            ...RESET_BUTTON,
+            display: 'inline-grid',
+            'grid-template-columns': 'auto 1fr',
+            'grid-template-rows': 'auto auto',
+            'column-gap': '{space.2}',
+            'align-items': 'center',
+            'align-content': 'center',
+            'justify-items': 'start',
+            height: '{space.10}',
+            'padding-inline': '{space.2.5} {space.3}',
+            'border-radius': '{radius.control}',
+            border: '{border.width.thin} solid transparent',
+            'text-align': 'start',
+            'white-space': 'nowrap',
+            'flex-shrink': '0',
+            'vertical-align': 'middle',
+            ...TRANSITION_COLORS,
+        },
+        icon: { 'grid-row': '1 / span 2', display: 'block', width: '{size.icon.xl}', height: '{size.icon.xl}', 'flex-shrink': '0', 'pointer-events': 'none' },
+        kicker: { 'grid-column': '2', 'font-family': '{font.family.sans}', 'font-size': '{font.size.2xs}', 'font-weight': '{font.weight.medium}', 'line-height': '{font.lineHeight.none}', 'letter-spacing': '{font.letterSpacing.normal}', opacity: '{opacity.muted}' },
+        label: { 'grid-column': '2', 'font-family': '{font.family.sans}', 'font-size': '{font.size.lg}', 'font-weight': '{font.weight.semibold}', 'line-height': '{font.lineHeight.none}', 'letter-spacing': '{font.letterSpacing.tight}', 'margin-top': '{space.0.5}' },
+        '@states': {
+            focus: { root: { outline: 'none', 'box-shadow': '{shadow.focus}' } },
+        },
+    },
+    variants: {
+        store: { apple: { root: {} }, google: { root: {} } },
+        theme: {
+            dark: {
+                root: { 'background-color': '{color.bg-inverse}', color: '{color.fg-inverse}', 'border-color': '{neutral.500}' },
+                '@states': {
+                    hover: { root: { 'background-color': 'color-mix(in srgb, {color.bg-inverse} 88%, {color.bg-surface})' } },
+                    active: { root: { 'background-color': 'color-mix(in srgb, {color.bg-inverse} 80%, {color.bg-surface})' } },
+                },
+            },
+            outline: {
+                root: { 'background-color': '{color.bg-surface}', color: '{color.fg-default}', 'border-color': '{color.border-control}', 'box-shadow': '{shadow.xs}' },
+                '@states': {
+                    hover: { root: { 'background-color': '{color.bg-subtle}', 'border-color': '{color.border-control-hover}' } },
+                    active: { root: { 'background-color': '{color.bg-muted}' } },
+                    focus: { root: { 'box-shadow': '{shadow.xs}, {shadow.focus}' } },
+                },
+            },
+        },
+    },
+    examples: [
+        ex('Dark pair', row(badge('apple'), badge('google')), 'The standard pair on a light page: inverse fill, thin grey border, 40px tall.'),
+        ex('Outline pair', row(badge('apple', 'outline'), badge('google', 'outline')), 'Surface fill with a hairline for footers and busy backgrounds.'),
+        ex('Outline on an inverse band', `<div style="background:var(--cn-color-bg-inverse);padding:var(--cn-space-5);border-radius:var(--cn-radius-lg)">${row(badge('apple', 'outline'), badge('google', 'outline'))}</div>`, 'On a dark band the outline theme keeps the badges readable; the dark theme would disappear.'),
+        ex('Single store', badge('apple', 'dark'), 'When the app exists on one store only. Do not fake the other badge.'),
+    ],
+    recipes: [
+        ex('Get-the-app footer row', `<div style="display:flex;flex-wrap:wrap;align-items:center;justify-content:space-between;gap:var(--cn-space-4);max-width:640px;padding:var(--cn-space-5);border:1px solid var(--cn-color-border-default);border-radius:var(--cn-radius-card)"><div><div class="cn-text-heading-xs">Lumen for iOS and Android</div><div class="cn-text-body-sm" style="color:var(--cn-color-fg-muted)">Reply to buyers and approve quotes from your phone.</div></div>${row(badge('apple'), badge('google'))}</div>`, 'Title and one line of copy on the left, the pair on the right; they wrap under the copy on narrow screens.'),
+    ],
+    rules: [
+        'Always 40px tall, never scaled: the badge is a fixed-size mark, not a button that grows with the layout.',
+        'Show both stores side by side with a 12px gap, Apple first, in the same theme; show one badge only when the app really exists on one store.',
+        'Copy is fixed by the store: "Download on the / App Store" and "Get it on / Google Play". Do not translate the store names or invent kickers.',
+        'dark on light pages; outline on dark, photographic or tinted backgrounds and in footers. Never both themes on one page.',
+        'In production use the stores\' official badge artwork inside the icon slot and follow their clear-space rules; the example glyphs are placeholders.',
+        'The badge links to the store listing (or a smart link) and opens in the same tab on mobile, a new tab on desktop.',
+        'Never place the badges inside the app shell or next to in-app actions; they belong to marketing surfaces and onboarding emails.',
+    ],
+    a11y: [
+        'It is an <a href> with an aria-label that reads both lines ("Download on the App Store"); the glyph is aria-hidden.',
+        'The two text lines are real text, not an image, so they scale with the user\'s font size and remain translatable.',
+        'Focus ring on :focus-visible; on the dark theme it is the only hover-independent state, so keep it visible.',
+        'Kicker opacity is 70% of the text color, which keeps contrast ≥ 4.5:1 on both themes; do not lower it.',
+    ],
+    related: ['social-button', 'button', 'link'],
+};

package/lib/components/avatar-group.mjs

@@ -0,0 +1,128 @@
+import { ex, ICON, typeStyle } from "./_shared.mjs";
+// the reference avatar group: stacked avatars (xs 24 · sm 32 · md 40 · lg 48) overlapping by
+// 4 / 8 / 8 / 12px, each with a 1.5px surface ring, ending in a "+N" gray disc and optionally
+// the dashed add button.
+const SIZE = {
+    xs: { box: '{space.6}', font: '{font.size.xs}', overlap: '{space.1}', icon: '{size.icon.sm}' },
+    sm: { box: '{space.8}', font: '{font.size.sm}', overlap: '{space.2}', icon: '{size.icon.sm}' },
+    md: { box: '{space.10}', font: '{font.size.md}', overlap: '{space.2}', icon: '{size.icon.md}' },
+    lg: { box: '{space.12}', font: '{font.size.lg}', overlap: '{space.3}', icon: '{size.icon.md}' },
+};
+const RING = '0 0 0 1.5px {color.bg-surface}';
+const SILHOUETTE = "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Crect width='64' height='64' fill='%23CDCED1'/%3E%3Ccircle cx='32' cy='25' r='11' fill='%23FAFAFA'/%3E%3Cpath d='M10 64c2-13 11-21 22-21s20 8 22 21z' fill='%23FAFAFA'/%3E%3C/svg%3E";
+const person = (size, text, name, image = false) => `<span class="cn-avatar cn-avatar-group__item" data-size="${size}" data-shape="circle" data-tone="neutral" data-status="none" role="img" aria-label="${name}">${image ? `<img class="cn-avatar__image" src="${SILHOUETTE}" alt="">` : `<span class="cn-avatar__fallback" aria-hidden="true">${text}</span>`}</span>`;
+const PEOPLE = [['MC', 'Maya Chen'], ['DC', 'Daniel Costa'], ['SA', 'Sofia Almeida'], ['LF', 'Lucas Ferreira'], ['AK', 'Aisha Khan']];
+const group = (size, count, overflow, label, images = false, add = false) => `<div class="cn-avatar-group" data-size="${size}" role="group" aria-label="${label ?? `Assigned to ${PEOPLE.slice(0, count).map((p) => p[1]).join(', ')}`}">${PEOPLE.slice(0, count).map(([t, n], i) => person(size, t, n, images && i % 2 === 0)).join('')}${overflow ? `<span class="cn-avatar-group__overflow">${overflow}</span>` : ''}${add ? `<button type="button" class="cn-avatar-group__add" aria-label="Add person">${ICON.plus.replace('cn-icon', 'cn-avatar-group__icon')}</button>` : ''}</div>`;
+export const avatarGroup = {
+    name: 'AvatarGroup',
+    slug: 'avatar-group',
+    category: 'data-display',
+    description: 'A row of overlapping avatars for the people on one thing, each separated by a 1.5px surface ring, ending in a "+3" gray disc when there are more than fit and optionally the dashed add button.',
+    usage: 'Assignees, participants, watchers: several people in one slot (a table cell, a card footer, a header). One person is an Avatar, not a group of one. Not for companies or integrations.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'Inline-flex row, role="group" with an aria-label that summarizes who is in it.' },
+        { part: 'item', element: 'span', description: 'An Avatar root that also carries this class. Gets the 1.5px surface ring and the negative overlap; the group\'s data-size overrides the avatar size.' },
+        { part: 'overflow', element: 'span', description: 'The "+N" disc, same size as the avatars, gray-50 with a gray-200 ring and 12–16px semibold gray-500 text. A <button> when it opens the full list.', optional: true },
+        { part: 'add', element: 'button', description: 'The add button: a dashed gray-300 circle on white with a plus icon, same size as the avatars, 8px after the row.', optional: true },
+        { part: 'icon', element: 'svg', description: 'The 16 / 20px plus icon inside the add button.', optional: true },
+    ],
+    props: {
+        size: {
+            values: ['xs', 'sm', 'md', 'lg'],
+            default: 'md',
+            description: 'Avatar size inside the group: xs 24px (table cells, kanban cards), sm 32px (list rows, card footers), md 40px (default: card headers), lg 48px (page headers). Pass the same value as data-size on each avatar so initials scale too.',
+        },
+    },
+    states: {},
+    base: {
+        root: { display: 'inline-flex', 'align-items': 'center', 'flex-shrink': '0', 'vertical-align': 'middle' },
+        item: { position: 'relative', 'flex-shrink': '0', 'box-shadow': RING },
+        overflow: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            position: 'relative',
+            'flex-shrink': '0',
+            'padding-inline': '{space.1}',
+            'padding-block': '0',
+            'border-radius': '{radius.full}',
+            'background-color': '{color.bg-subtle}',
+            color: '{color.fg-subtle}',
+            ...typeStyle('label-xs'),
+            'font-weight': '{font.weight.semibold}',
+            'font-variant-numeric': 'tabular-nums',
+            'white-space': 'nowrap',
+            'user-select': 'none',
+            'box-shadow': `${RING}, inset 0 0 0 1px {color.border-default}`,
+        },
+        add: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            appearance: 'none',
+            margin: '0',
+            padding: '0',
+            'margin-inline-start': '{space.2}',
+            'border-radius': '{radius.full}',
+            border: '{border.width.thin} dashed {color.border-control}',
+            'background-color': '{color.bg-surface}',
+            color: '{color.fg-subtle}',
+            cursor: 'pointer',
+            'transition-property': 'background-color, color, box-shadow',
+            'transition-duration': '{motion.duration.fast}',
+            'transition-timing-function': '{motion.easing.linear}',
+        },
+        icon: { display: 'block', 'flex-shrink': '0' },
+    },
+    variants: {
+        size: Object.fromEntries(Object.entries(SIZE).map(([s, v]) => [s, {
+                item: { width: v.box, height: v.box },
+                overflow: { 'min-width': v.box, height: v.box, 'font-size': v.font },
+                add: { width: v.box, height: v.box },
+                icon: { width: v.icon, height: v.icon },
+            }])),
+    },
+    extraCss: `
+.cn-avatar-group > .cn-avatar-group__item + .cn-avatar-group__item, .cn-avatar-group > .cn-avatar-group__item + .cn-avatar-group__overflow { margin-inline-start: calc({space.2} * -1); }
+.cn-avatar-group[data-size="xs"] > .cn-avatar-group__item + .cn-avatar-group__item, .cn-avatar-group[data-size="xs"] > .cn-avatar-group__item + .cn-avatar-group__overflow { margin-inline-start: calc({space.1} * -1); }
+.cn-avatar-group[data-size="lg"] > .cn-avatar-group__item + .cn-avatar-group__item, .cn-avatar-group[data-size="lg"] > .cn-avatar-group__item + .cn-avatar-group__overflow { margin-inline-start: calc({space.3} * -1); }
+.cn-avatar-group > :nth-child(1) { z-index: 6; }
+.cn-avatar-group > :nth-child(2) { z-index: 5; }
+.cn-avatar-group > :nth-child(3) { z-index: 4; }
+.cn-avatar-group > :nth-child(4) { z-index: 3; }
+.cn-avatar-group > :nth-child(5) { z-index: 2; }
+.cn-avatar-group > :nth-child(6) { z-index: 1; }
+.cn-avatar-group > .cn-avatar-group__add { z-index: 0; }
+button.cn-avatar-group__overflow { appearance: none; border: 0; margin: 0; cursor: pointer; margin-inline-start: calc({space.2} * -1); }
+button.cn-avatar-group__overflow:hover { background-color: {color.bg-muted}; color: {color.fg-muted}; }
+button.cn-avatar-group__overflow:focus-visible { outline: none; box-shadow: ${RING}, {shadow.focus}; }
+.cn-avatar-group__add:hover { background-color: {color.bg-subtle}; color: {color.fg-muted}; }
+.cn-avatar-group__add:focus-visible { outline: none; box-shadow: {shadow.focus}; }
+.cn-avatar-group__add:disabled { opacity: {opacity.disabled}; cursor: not-allowed; }`,
+    examples: [
+        ex('Three people', group('md', 3, undefined, undefined, true), '40px avatars overlapping by 8px, each with the 1.5px surface ring; the first is drawn on top.'),
+        ex('Five visible, then overflow', group('md', 5, '+3', 'Assigned to Maya Chen, Daniel Costa, Sofia Almeida, Lucas Ferreira, Aisha Khan and 3 others', true), 'Never more than five avatars; the gray disc carries the rest.'),
+        ex('Sizes', `<div style="display:flex;align-items:center;gap:var(--cn-space-6);flex-wrap:wrap">${group('xs', 3, '+2')} ${group('sm', 3, '+2')} ${group('md', 3, '+2')} ${group('lg', 3, '+2')}</div>`, 'xs 24 · sm 32 · md 40 · lg 48; the overlap is 4 / 8 / 8 / 12px.'),
+        ex('With the add button', group('md', 4, undefined, 'Maya Chen, Daniel Costa, Sofia Almeida, Lucas Ferreira', true, true), 'The dashed add button sits 8px after the row, same size as the avatars.'),
+        ex('Overflow as a button', `<div class="cn-avatar-group" data-size="sm" role="group" aria-label="8 participants">${PEOPLE.slice(0, 4).map(([t, n]) => person('sm', t, n)).join('')}<button type="button" class="cn-avatar-group__overflow" aria-label="Show all 8 participants">+4</button></div>`, 'Only when clicking reveals the full list.'),
+    ],
+    rules: [
+        'Maximum five visible avatars. Beyond that, the overflow disc shows the remaining count ("+3"); never a second row.',
+        'Source order is relevance order: owner first, then assignees by recency. The first avatar is drawn on top so it is fully visible.',
+        'One size and one shape per group; pass the group size as data-size on every avatar as well.',
+        'Initials inside a group are fine at sm and up; at xs use a single letter so the 4px overlap does not clip them. Photos are unaffected.',
+        'The overflow disc is a <span> unless clicking it opens the full list; then it is a <button> with aria-label "Show all N people".',
+        'The add button belongs to groups the user can edit (assignees, members); never in read-only cells.',
+        'The rings are bg-surface: place groups on surface or canvas, not on tinted fills.',
+        'No status dots inside a group; the overlap hides them. Show presence in the expanded list instead.',
+        'A group of one is an Avatar. A group of zero is nothing (or "Unassigned" text), never an empty disc.',
+    ],
+    a11y: [
+        'root has role="group" and an aria-label summarizing the members ("Assigned to Maya Chen, Daniel Costa and 3 others") so it is not read one avatar at a time; each avatar keeps its own label.',
+        'The overflow count is real text and is announced; as a button it needs an aria-label with the total count.',
+        'The add button needs aria-label ("Add person") and is the only focusable element besides an overflow button.',
+        'Overlap is visual only; the DOM order is the meaningful order.',
+    ],
+    related: ['avatar', 'list', 'table', 'kanban', 'card-header'],
+};