canon-ds 0.1.0

package/lib/components/avatar.mjs

@@ -0,0 +1,225 @@
+import { ex, ICON, typeStyle } from "./_shared.mjs";
+// the reference avatar: xxs 16 · xs 24 · sm 32 · md 40 · lg 48 · xl 56 · 2xl 64, semibold initials
+// (12 → 24px) on gray-100, a 0.5px inner contrast ring, a status dot (6 → 16px) with a 1.5px
+// surface ring, a blue verified tick (10 → 20px), a company-logo badge, a square (radius 6)
+// shape for companies, and the avatar label group (name + email) next to it.
+const SIZE = {
+    xxs: { box: '{space.4}', font: '{font.size.2xs}', icon: '{size.icon.xs}', dot: '{space.1}', tick: '{space.2}', badge: '{space.2}' },
+    xs: { box: '{space.6}', font: '{font.size.xs}', icon: '{size.icon.sm}', dot: '{space.1.5}', tick: '{space.2.5}', badge: '{space.2}' },
+    sm: { box: '{space.8}', font: '{font.size.sm}', icon: '{size.icon.md}', dot: '{space.2}', tick: '{space.3}', badge: '{space.3}' },
+    md: { box: '{space.10}', font: '{font.size.md}', icon: '{size.icon.lg}', dot: '{space.2.5}', tick: '{space.3.5}', badge: '{space.3.5}' },
+    lg: { box: '{space.12}', font: '{font.size.lg}', icon: '{size.icon.xl}', dot: '{space.3}', tick: '{space.4}', badge: '{space.4}' },
+    xl: { box: '{space.14}', font: '{font.size.xl}', icon: '{size.icon.2xl}', dot: '{space.3.5}', tick: '18px', badge: '18px' },
+    '2xl': { box: '{space.16}', font: '{font.size.2xl}', icon: '{size.icon.2xl}', dot: '{space.4}', tick: '{space.5}', badge: '{space.5}' },
+};
+const TONE = {
+    neutral: { bg: '{color.bg-muted}', fg: '{color.fg-subtle}' },
+    accent: { bg: '{color.bg-accent-subtle}', fg: '{color.fg-accent}' },
+    info: { bg: '{color.bg-info-subtle}', fg: '{color.fg-info}' },
+    success: { bg: '{color.bg-success-subtle}', fg: '{color.fg-success}' },
+    warning: { bg: '{color.bg-warning-subtle}', fg: '{color.fg-warning}' },
+};
+const STATUS = {
+    online: '{green.500}',
+    away: '{amber.500}',
+    busy: '{red.500}',
+    offline: '{color.border-control}',
+};
+/** 0.5px inner contrast ring and the 1.5px surface ring around dots and badges. */
+const CONTRAST = 'inset 0 0 0 0.5px color-mix(in srgb, {black} 16%, transparent)';
+const SURFACE_RING = '0 0 0 1.5px {color.bg-surface}';
+/** Neutral silhouette so the gallery renders an image without the network. */
+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 LOGO = "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 32 32'%3E%3Crect width='32' height='32' rx='16' fill='%23B4309F'/%3E%3Cpath d='M9 22V10h3.4l3.6 7.2L19.6 10H23v12h-3v-7l-3 6h-1l-3-6v7z' fill='%23fff'/%3E%3C/svg%3E";
+const VERIFIED = `<svg class="cn-avatar__verified" viewBox="0 0 16 16" aria-hidden="true"><path fill="currentColor" d="M8 0l1.9 1.6 2.4-.5.9 2.3 2.3.9-.5 2.4L16 8l-1.6 1.9.5 2.4-2.3.9-.9 2.3-2.4-.5L8 16l-1.9-1.6-2.4.5-.9-2.3-2.3-.9.5-2.4L0 8l1.6-1.9-.5-2.4 2.3-.9.9-2.3 2.4.5z"/><path d="M4.8 8.3l2.1 2.1 4.3-4.4" fill="none" stroke="var(--cn-color-fg-on-action)" stroke-width="1.6" stroke-linecap="round" stroke-linejoin="round"/></svg>`;
+const BUILDING = '<svg class="cn-avatar__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 13.5V3.5a1 1 0 011-1h5a1 1 0 011 1v10M10 6.5h2a1 1 0 011 1v6M1.5 13.5h13M5.5 5h2M5.5 7.5h2M5.5 10h2"/></svg>';
+const av = (size, inner, name, shape = 'circle', tone = 'neutral', status = 'none', extra = '') => `<span class="cn-avatar" data-size="${size}" data-shape="${shape}" data-tone="${tone}" data-status="${status}" role="img" aria-label="${name}"${extra}>${inner}${status !== 'none' ? '<span class="cn-avatar__status"></span>' : ''}</span>`;
+const initials = (size, text, name, extra = '') => av(size, `<span class="cn-avatar__fallback" aria-hidden="true">${text}</span>`, name, 'circle', 'neutral', 'none', extra);
+const photo = (size, name, status = 'none', extra = '') => `<span class="cn-avatar" data-size="${size}" data-shape="circle" data-tone="neutral" data-status="${status}"${extra}><img class="cn-avatar__image" src="${SILHOUETTE}" alt="${name}${status !== 'none' ? `, ${status}` : ''}">${status !== 'none' ? '<span class="cn-avatar__status"></span>' : ''}</span>`;
+const labelGroup = (size, avatar, name, email) => `<div class="cn-avatar-label-group" data-size="${size}">${avatar}<div class="cn-avatar-label-group__text"><span class="cn-avatar-label-group__name">${name}</span><span class="cn-avatar-label-group__email">${email}</span></div></div>`;
+export const avatar = {
+    name: 'Avatar',
+    slug: 'avatar',
+    category: 'data-display',
+    description: 'A person or company as a small picture in the reference\'s seven sizes (16 → 64px): photo when there is one, semibold initials on gray-100 or a placeholder icon when there is not, a 0.5px contrast ring, and optional status dot, verified tick or company badge on the corner. Circles are people; squares are companies.',
+    usage: 'Next to a name in tables, lists, comments, assignee fields, menus and headers; with the avatar label group when the name and email sit beside it. Use AvatarGroup for several people in one slot. Not a button: wrap it in a Button or Link when it opens something.',
+    anatomy: [
+        { part: 'root', element: 'span', description: 'Sized box, position relative, overflow visible so the badges can sit on the edge; draws the 0.5px inner contrast ring. Carries role="img" + aria-label when showing initials. Add data-border for the 1px outer ring, tabindex or make it a button when focusable.' },
+        { part: 'image', element: 'img', description: 'The photo, cropped with object-fit cover, clipped by the root radius, with the reference\'s faint 1px light rim at the top and bottom edge. Needs alt.', optional: true },
+        { part: 'fallback', element: 'span', description: 'Initials (1–2 letters, semibold, 12 → 24px) centered on the gray-100 fill. Shown when there is no image.', optional: true },
+        { part: 'icon', element: 'svg', description: 'Placeholder icon (a person, or a building for companies) inside the fallback: 12 → 32px, fg-subtle.', optional: true },
+        { part: 'status', element: 'span', description: 'Presence dot at the bottom-right (6 → 16px) with a 1.5px surface ring so it reads on any photo. Hidden unless data-status is a value other than none.', optional: true },
+        { part: 'verified', element: 'svg', description: 'The blue verified tick at the bottom-right (10 → 20px): a blue-500 seal with a white check.', optional: true },
+        { part: 'badge', element: 'span', description: 'Company-logo badge at the bottom-right (8 → 20px): a round brand-50 tile with a 1.5px surface ring holding a small logo image.', optional: true },
+    ],
+    props: {
+        size: {
+            values: ['xxs', 'xs', 'sm', 'md', 'lg', 'xl', '2xl'],
+            default: 'md',
+            description: 'Outer size: xxs 16px (inline in text, tags), xs 24px (dense tables, menus, kanban cards), sm 32px (lists, table rows), md 40px (default: account cards, comments, table rows with two lines), lg 48px (headers, drawers), xl 56px and 2xl 64px (profile and settings pages).',
+        },
+        shape: {
+            values: ['circle', 'square'],
+            default: 'circle',
+            description: 'circle = a person; square (radius 6) = a company, workspace or integration. Never mix shapes in one list.',
+        },
+        tone: {
+            values: ['neutral', 'accent', 'info', 'success', 'warning'],
+            default: 'neutral',
+            description: 'Tint of the initials fallback. neutral (gray-100 with gray-500 initials, the reference) for people; accent only for the product\'s own assistant; info/success/warning only when the entity itself has that state. Never assign colors per person.',
+        },
+        status: {
+            values: ['none', 'online', 'away', 'busy', 'offline'],
+            default: 'none',
+            description: 'Presence dot: none hides it (default); online = green-500, away = amber, busy = red, offline = gray-300. Only for real-time presence.',
+        },
+    },
+    states: {
+        focus: { selector: ':focus-visible', description: 'Keyboard focus when the avatar is a button or link (account menu trigger): the 4px brand ring.', markup: 'make the avatar a <button> or <a>, or add tabindex="0"' },
+    },
+    base: {
+        root: {
+            display: 'inline-flex',
+            position: 'relative',
+            'flex-shrink': '0',
+            'vertical-align': 'middle',
+            overflow: 'visible',
+            'border-radius': '{radius.full}',
+            'background-color': '{color.bg-muted}',
+        },
+        image: {
+            display: 'block',
+            width: '100%',
+            height: '100%',
+            'object-fit': 'cover',
+            'border-radius': 'inherit',
+            overflow: 'hidden',
+        },
+        fallback: {
+            display: 'flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            width: '100%',
+            height: '100%',
+            'border-radius': 'inherit',
+            overflow: 'hidden',
+            'background-color': '{color.bg-muted}',
+            color: '{color.fg-subtle}',
+            ...typeStyle('label-md'),
+            'line-height': '1',
+            'user-select': 'none',
+        },
+        icon: { display: 'block', color: '{color.fg-subtle}', 'stroke-width': '2' },
+        status: {
+            display: 'none',
+            position: 'absolute',
+            bottom: '0',
+            right: '0',
+            'border-radius': '{radius.full}',
+            'box-shadow': SURFACE_RING,
+            'background-color': '{color.border-control}',
+            'z-index': '{z.raised}',
+        },
+        verified: {
+            position: 'absolute',
+            bottom: '0',
+            right: '0',
+            display: 'block',
+            color: '{blue.500}',
+            'z-index': '{z.raised}',
+        },
+        badge: {
+            position: 'absolute',
+            bottom: '-2px',
+            right: '-2px',
+            display: 'flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            overflow: 'hidden',
+            'border-radius': '{radius.full}',
+            'background-color': '{brand.50}',
+            'box-shadow': SURFACE_RING,
+            'z-index': '{z.raised}',
+        },
+        '@states': {
+            focus: { root: { outline: 'none', 'box-shadow': '{shadow.focus}' } },
+        },
+    },
+    variants: {
+        size: Object.fromEntries(Object.entries(SIZE).map(([s, v]) => [s, {
+                root: { width: v.box, height: v.box },
+                fallback: { 'font-size': v.font },
+                icon: { width: v.icon, height: v.icon },
+                status: { width: v.dot, height: v.dot },
+                verified: { width: v.tick, height: v.tick },
+                badge: { width: v.badge, height: v.badge },
+            }])),
+        shape: {
+            circle: { root: { 'border-radius': '{radius.full}' } },
+            square: { root: { 'border-radius': '{radius.md}' }, status: { transform: 'translate(25%, 25%)' } },
+        },
+        tone: Object.fromEntries(Object.entries(TONE).map(([t, v]) => [t, { root: { 'background-color': v.bg }, fallback: { 'background-color': v.bg, color: v.fg } }])),
+        status: {
+            none: { status: { display: 'none' } },
+            ...Object.fromEntries(Object.entries(STATUS).map(([s, c]) => [s, { status: { display: 'block', 'background-color': c } }])),
+        },
+    },
+    compound: [
+        { when: { size: 'xxs', shape: 'square' }, block: { root: { 'border-radius': '{radius.sm}' } } },
+        { when: { size: 'xs', shape: 'square' }, block: { root: { 'border-radius': '{radius.sm}' } } },
+    ],
+    extraCss: `
+.cn-avatar::after { content: ""; position: absolute; inset: 0; border-radius: inherit; box-shadow: ${CONTRAST}; pointer-events: none; }
+.cn-avatar:has(> .cn-avatar__image)::before { content: ""; position: absolute; inset: 0; border-radius: inherit; border: 1px solid color-mix(in srgb, {white} 32%, transparent); -webkit-mask-image: linear-gradient(to bottom, black 0%, transparent 25%, transparent 75%, black 100%); mask-image: linear-gradient(to bottom, black 0%, transparent 25%, transparent 75%, black 100%); pointer-events: none; }
+.cn-avatar[data-size="xxs"]::before, .cn-avatar[data-size="xs"]::before { display: none; }
+.cn-avatar[data-size="xs"] .cn-avatar__verified, .cn-avatar[data-size="xxs"] .cn-avatar__verified { right: -1px; bottom: -1px; }
+.cn-avatar[data-size="xxs"] .cn-avatar__fallback { font-size: 8px; }
+.cn-avatar[data-border] { outline: 1px solid color-mix(in srgb, {black} 10%, transparent); outline-offset: 1px; }
+.cn-avatar[data-size="lg"][data-border], .cn-avatar[data-size="xl"][data-border], .cn-avatar[data-size="2xl"][data-border] { outline-offset: 2px; }
+.cn-avatar__badge > img { width: 100%; height: 100%; object-fit: cover; border-radius: inherit; }
+button.cn-avatar, a.cn-avatar { appearance: none; border: 0; padding: 0; margin: 0; cursor: pointer; }
+.cn-avatar-label-group { display: inline-flex; align-items: center; gap: {space.3}; min-width: 0; vertical-align: middle; }
+.cn-avatar-label-group__text { display: flex; flex-direction: column; min-width: 0; }
+.cn-avatar-label-group__name { font-size: {font.size.sm}; font-weight: {font.weight.medium}; line-height: {font.lineHeight.normal}; color: {color.fg-default}; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.cn-avatar-label-group__email { font-size: {font.size.xs}; line-height: {font.lineHeight.normal}; color: {color.fg-muted}; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+.cn-avatar-label-group[data-size="sm"] { gap: {space.2.5}; }
+.cn-avatar-label-group[data-size="md"] .cn-avatar-label-group__email { font-size: {font.size.sm}; }
+.cn-avatar-label-group[data-size="lg"] { gap: {space.4}; }
+.cn-avatar-label-group[data-size="lg"] .cn-avatar-label-group__name { font-size: {font.size.md}; font-weight: {font.weight.semibold}; }
+.cn-avatar-label-group[data-size="lg"] .cn-avatar-label-group__email { font-size: {font.size.sm}; }
+.cn-avatar-add { display: inline-flex; align-items: center; justify-content: center; flex-shrink: 0; appearance: none; margin: 0; padding: 0; width: {space.10}; height: {space.10}; border-radius: {radius.full}; border: 1px dashed {color.border-control}; background-color: {color.bg-surface}; color: {color.fg-subtle}; cursor: pointer; transition: background-color {motion.duration.fast} {motion.easing.linear}, color {motion.duration.fast} {motion.easing.linear}; }
+.cn-avatar-add > .cn-icon { width: {size.icon.md}; height: {size.icon.md}; }
+.cn-avatar-add:hover { background-color: {color.bg-subtle}; color: {color.fg-muted}; }
+.cn-avatar-add:focus-visible { outline: none; box-shadow: {shadow.focus}; }
+.cn-avatar-add:disabled { opacity: {opacity.disabled}; cursor: not-allowed; }
+.cn-avatar-add[data-size="xs"] { width: {space.6}; height: {space.6}; } .cn-avatar-add[data-size="xs"] > .cn-icon { width: {size.icon.sm}; height: {size.icon.sm}; }
+.cn-avatar-add[data-size="sm"] { width: {space.8}; height: {space.8}; } .cn-avatar-add[data-size="sm"] > .cn-icon { width: {size.icon.sm}; height: {size.icon.sm}; }`,
+    examples: [
+        ex('Sizes', `<div style="display:flex;flex-wrap:wrap;align-items:flex-end;gap:var(--cn-space-4)">${initials('xxs', 'M', 'Maya Chen')}${initials('xs', 'MC', 'Maya Chen')}${initials('sm', 'MC', 'Maya Chen')}${initials('md', 'MC', 'Maya Chen')}${initials('lg', 'MC', 'Maya Chen')}${initials('xl', 'MC', 'Maya Chen')}${initials('2xl', 'MC', 'Maya Chen')}</div>`, 'xxs 16 · xs 24 · sm 32 · md 40 · lg 48 · xl 56 · 2xl 64. Semibold initials on gray-100 with the 0.5px contrast ring.'),
+        ex('Photo, border and status', `<div style="display:flex;flex-wrap:wrap;align-items:center;gap:var(--cn-space-4)">${photo('md', 'Daniel Costa')}${photo('md', 'Daniel Costa', 'none', ' data-border')}${photo('md', 'Sofia Almeida', 'online')}${photo('md', 'Lucas Ferreira', 'offline')}${photo('md', 'Aisha Khan', 'away')}${photo('md', 'Noah Berg', 'busy')}</div>`, 'The photo gets a faint light rim; data-border adds the 1px outer ring. Dots: online green, offline gray-300, away amber, busy red, each with a 1.5px surface ring.'),
+        ex('Status dot per size', `<div style="display:flex;flex-wrap:wrap;align-items:flex-end;gap:var(--cn-space-4)">${photo('xs', 'Maya Chen', 'online')}${photo('sm', 'Maya Chen', 'online')}${photo('md', 'Maya Chen', 'online')}${photo('lg', 'Maya Chen', 'online')}${photo('xl', 'Maya Chen', 'online')}${photo('2xl', 'Maya Chen', 'online')}</div>`, '6 · 8 · 10 · 12 · 14 · 16px dots.'),
+        ex('Verified tick', `<div style="display:flex;flex-wrap:wrap;align-items:flex-end;gap:var(--cn-space-4)">${av('xs', `<img class="cn-avatar__image" src="${SILHOUETTE}" alt="">${VERIFIED}`, 'Elena Rossi, verified')}${av('sm', `<img class="cn-avatar__image" src="${SILHOUETTE}" alt="">${VERIFIED}`, 'Elena Rossi, verified')}${av('md', `<img class="cn-avatar__image" src="${SILHOUETTE}" alt="">${VERIFIED}`, 'Elena Rossi, verified')}${av('lg', `<img class="cn-avatar__image" src="${SILHOUETTE}" alt="">${VERIFIED}`, 'Elena Rossi, verified')}${av('xl', `<img class="cn-avatar__image" src="${SILHOUETTE}" alt="">${VERIFIED}`, 'Elena Rossi, verified')}${av('2xl', `<img class="cn-avatar__image" src="${SILHOUETTE}" alt="">${VERIFIED}`, 'Elena Rossi, verified')}</div>`, 'The blue-500 seal with a white check, 10 → 20px, bottom-right.'),
+        ex('Company badge and placeholders', `<div style="display:flex;flex-wrap:wrap;align-items:center;gap:var(--cn-space-4)">${av('md', `<img class="cn-avatar__image" src="${SILHOUETTE}" alt=""><span class="cn-avatar__badge"><img src="${LOGO}" alt=""></span>`, 'Tomás Silva at Lumen')}${av('md', `<span class="cn-avatar__fallback" aria-hidden="true">${ICON.user.replace('cn-icon', 'cn-avatar__icon')}</span>`, 'Unknown person')}${av('md', `<span class="cn-avatar__fallback" aria-hidden="true">${BUILDING}</span>`, 'Lumen', 'square')}${av('md', `<span class="cn-avatar__fallback" aria-hidden="true">LU</span>`, 'Lumen', 'square')}${av('lg', `<img class="cn-avatar__image" src="${LOGO}" alt="Lumen">`, 'Lumen', 'square')}</div>`, 'A 14px company badge on a person; the person placeholder icon; the square company placeholder (building icon or initials) and a square logo.'),
+        ex('Label group', `<div style="display:flex;flex-direction:column;align-items:flex-start;gap:var(--cn-space-5)">${labelGroup('sm', photo('sm', 'Maya Chen', 'online'), 'Maya Chen', 'maya@lumen.co')}${labelGroup('md', photo('md', 'Daniel Costa', 'online'), 'Daniel Costa', 'daniel@lumen.co')}${labelGroup('lg', initials('lg', 'SA', 'Sofia Almeida'), 'Sofia Almeida', 'sofia@lumen.co')}</div>`, 'The avatar label group recipe: avatar + name (14px medium) + email (fg-muted); data-size sm / md / lg sets the gap and text sizes.'),
+        ex('Tones and the focusable trigger', `<div style="display:flex;flex-wrap:wrap;align-items:center;gap:var(--cn-space-4)">${initials('md', 'MC', 'Maya Chen')}${av('md', '<span class="cn-avatar__fallback" aria-hidden="true">AI</span>', 'Lumen assistant', 'circle', 'accent')}${av('md', '<span class="cn-avatar__fallback" aria-hidden="true">NC</span>', 'New contact', 'circle', 'info')}${av('md', '<span class="cn-avatar__fallback" aria-hidden="true">VB</span>', 'Verified buyer', 'circle', 'success')}${av('md', '<span class="cn-avatar__fallback" aria-hidden="true">PR</span>', 'Pending review', 'circle', 'warning')}<button type="button" class="cn-avatar" data-size="md" data-shape="circle" data-tone="neutral" data-status="none" aria-label="Open account menu" aria-haspopup="menu"><span class="cn-avatar__fallback" aria-hidden="true">MC</span></button><button type="button" class="cn-avatar-add" aria-label="Add teammate">${ICON.plus}</button></div>`, 'neutral for people; the other tones only when the entity has that state. A button avatar gets the focus ring; .cn-avatar-add is the dashed add button.'),
+    ],
+    rules: [
+        'Circle = a person. Square (radius 6) = a company, a workspace or an integration. One shape per list.',
+        'Initials: first + last name (2 letters) from xs up; a single letter at xxs. Semibold, gray-500 on gray-100.',
+        'Fallback tone is neutral for people. accent is reserved for the product\'s assistant. Never give people random colors.',
+        'Show the status dot only for real-time presence that matters; never as decoration; data-status="none" otherwise. The verified tick and the company badge are mutually exclusive with the dot.',
+        'Photos are cropped with cover, never stretched; the only frame is data-border (1px outer ring) on profile pages.',
+        'Sizes follow the slot: xxs inline in text and tags, xs in dense tables and menus, sm in list rows, md in account cards and 72px table rows, lg in headers and drawers, xl / 2xl on profile pages.',
+        'Next to a name and email use the avatar label group (.cn-avatar-label-group) so the text sizes and gaps match the avatar size.',
+        'The avatar is not a control unless it is the account menu trigger: then it is a <button aria-haspopup="menu"> and gets the focus ring; do not add hover styles.',
+        'Always pair with the name in text nearby except in tight groups; the picture is never the only identification.',
+    ],
+    a11y: [
+        'Photo: alt is the person\'s name when the name is not adjacent text; alt="" when it is, to avoid reading the name twice.',
+        'Initials: put role="img" and aria-label="Full name" on the root and aria-hidden="true" on the initials span.',
+        'Presence and verification must be available as text: include them in the alt or aria-label ("Maya Chen, online", "Elena Rossi, verified"). The dot and tick alone are not accessible.',
+        'When clickable, the avatar is a <button> or <a> with an aria-label and shows the focus ring; a wrapping Link works too.',
+        'The add button (.cn-avatar-add) needs aria-label ("Add teammate").',
+    ],
+    related: ['avatar-group', 'badge', 'list', 'table', 'menu', 'kanban'],
+};

package/lib/components/badge-group.mjs

@@ -0,0 +1,55 @@
+import { ex, ICON, typeStyle } from "./_shared.mjs";
+const TONES = { brand: ['{color.bg-accent-subtle}', '{color.fg-accent}', '{brand.200}'], gray: ['{color.bg-subtle}', '{color.fg-muted}', '{color.border-default}'], success: ['{color.bg-success-subtle}', '{color.fg-success}', '{green.200}'], warning: ['{color.bg-warning-subtle}', '{color.fg-warning}', '{amber.200}'], error: ['{color.bg-danger-subtle}', '{color.fg-danger}', '{red.200}'] };
+export const badgeGroup = {
+    name: 'BadgeGroup',
+    slug: 'badge-group',
+    category: 'data-display',
+    description: 'A pill that holds a small inner badge plus a message and an arrow: the "badge group" used for announcements above hero titles ("New feature · Check out the team dashboard →").',
+    usage: 'Announcements, release notes and "what is new" links above a page or hero title. One per page. Not for status in tables (use Badge).',
+    anatomy: [
+        { part: 'root', element: 'a', description: 'The outer pill. A link when it navigates.' },
+        { part: 'badge', element: 'span', description: 'The inner pill (e.g. "New feature").' },
+        { part: 'label', element: 'span', description: 'The message.' },
+        { part: 'icon', element: 'svg', description: 'Trailing arrow, 16px.' },
+    ],
+    props: {
+        tone: { values: ['brand', 'gray', 'success', 'warning', 'error'], default: 'brand', description: 'Color family of the group.' },
+        theme: { values: ['light', 'modern'], default: 'light', description: 'light = tinted outer pill with white inner badge; modern = white outer pill with grey ring and a tinted inner badge.' },
+        size: { values: ['sm', 'md', 'lg'], default: 'md', description: 'Outer pill 24 / 28 / 32px; text 12 / 14 / 14.' },
+        align: { values: ['leading', 'trailing'], default: 'leading', description: 'leading = inner badge first; trailing = inner badge after the message.' },
+    },
+    states: { hover: { selector: ':hover', description: 'Slightly stronger fill; arrow moves 2px.', markup: 'native' }, focus: { selector: ':focus-visible', description: 'Focus ring.', markup: 'native' } },
+    base: {
+        root: { display: 'inline-flex', 'align-items': 'center', gap: '{space.2}', 'border-radius': '{radius.full}', border: '{border.width.thin} solid transparent', 'padding-inline': '{space.1} {space.2.5}', ...typeStyle('label-sm'), 'text-decoration': 'none', 'min-width': '0', 'max-width': '100%', 'padding-block': '{space.0.5}', cursor: 'pointer', 'transition-property': 'background-color, border-color', 'transition-duration': '{motion.duration.fast}', 'transition-timing-function': '{motion.easing.standard}' },
+        badge: { 'flex-shrink': '0', 'white-space': 'nowrap', display: 'inline-flex', 'align-items': 'center', height: '22px', 'padding-inline': '{space.2}', 'border-radius': '{radius.full}', border: '{border.width.thin} solid transparent', 'font-size': '{font.size.xs}', 'font-weight': '{font.weight.medium}', 'line-height': '1' },
+        label: { display: 'inline-block', 'min-width': '0', 'overflow-wrap': 'anywhere' },
+        icon: { width: '{size.icon.sm}', height: '{size.icon.sm}', 'flex-shrink': '0', transition: 'transform {motion.duration.fast} {motion.easing.standard}' },
+        '@states': { focus: { root: { outline: 'none', 'box-shadow': '{shadow.focus}' } }, hover: { icon: { transform: 'translateX(2px)' } } },
+    },
+    variants: {
+        tone: Object.fromEntries(Object.keys(TONES).map((t) => [t, { root: {} }])),
+        theme: { light: { root: {} }, modern: { root: { 'background-color': '{color.bg-surface}', 'border-color': '{color.border-control}', color: '{color.fg-muted}', 'box-shadow': '{shadow.xs}' } } },
+        size: {
+            sm: { root: { 'min-height': '24px', 'font-size': '{font.size.xs}' }, badge: { height: '18px', 'padding-inline': '{space.1.5}' } },
+            md: { root: { 'min-height': '28px' }, badge: { height: '22px' } },
+            lg: { root: { 'min-height': '32px', 'padding-inline': '{space.1} {space.3}' }, badge: { height: '24px', 'font-size': '{font.size.sm}' } },
+        },
+        align: { leading: { root: {} }, trailing: { root: { 'flex-direction': 'row-reverse', 'padding-inline': '{space.2.5} {space.1}' } } },
+    },
+    compound: Object.entries(TONES).flatMap(([t, [bg, fg, border]]) => [
+        { when: { tone: t, theme: 'light' }, block: { root: { 'background-color': bg, color: fg, 'border-color': border }, badge: { 'background-color': '{color.bg-surface}', color: fg, 'border-color': border }, '@states': { hover: { root: { 'border-color': fg } } } } },
+        { when: { tone: t, theme: 'modern' }, block: { badge: { 'background-color': bg, color: fg, 'border-color': border } } },
+    ]),
+    extraCss: `
+.cn-badge-group[data-align="trailing"] .cn-badge-group__icon { order: -1; transform: none; }
+.cn-badge-group[data-align="trailing"]:hover .cn-badge-group__icon { transform: translateX(-2px); }`,
+    examples: [
+        ex('Light, leading (default)', `<a href="#" class="cn-badge-group" data-tone="brand" data-theme="light" data-size="md" data-align="leading"><span class="cn-badge-group__badge">New feature</span><span class="cn-badge-group__label">Check out the team dashboard</span>${ICON.arrow.replace('cn-icon', 'cn-badge-group__icon')}</a>`),
+        ex('Modern', `<a href="#" class="cn-badge-group" data-tone="brand" data-theme="modern" data-size="md" data-align="leading"><span class="cn-badge-group__badge">We're hiring!</span><span class="cn-badge-group__label">Join our remote team</span>${ICON.arrow.replace('cn-icon', 'cn-badge-group__icon')}</a>`),
+        ex('Tones', `<a href="#" class="cn-badge-group" data-tone="gray" data-theme="light" data-size="md" data-align="leading"><span class="cn-badge-group__badge">Update</span><span class="cn-badge-group__label">Version 4.2 is live</span>${ICON.arrow.replace('cn-icon', 'cn-badge-group__icon')}</a> <a href="#" class="cn-badge-group" data-tone="success" data-theme="light" data-size="md" data-align="leading"><span class="cn-badge-group__badge">Resolved</span><span class="cn-badge-group__label">All systems normal</span>${ICON.arrow.replace('cn-icon', 'cn-badge-group__icon')}</a> <a href="#" class="cn-badge-group" data-tone="error" data-theme="light" data-size="md" data-align="leading"><span class="cn-badge-group__badge">Incident</span><span class="cn-badge-group__label">API latency degraded</span>${ICON.arrow.replace('cn-icon', 'cn-badge-group__icon')}</a>`),
+        ex('Trailing and sizes', `<a href="#" class="cn-badge-group" data-tone="brand" data-theme="light" data-size="sm" data-align="trailing"><span class="cn-badge-group__badge">New</span><span class="cn-badge-group__label">Read the changelog</span>${ICON.arrow.replace('cn-icon', 'cn-badge-group__icon')}</a> <a href="#" class="cn-badge-group" data-tone="brand" data-theme="light" data-size="lg" data-align="leading"><span class="cn-badge-group__badge">New feature</span><span class="cn-badge-group__label">Check out the team dashboard</span>${ICON.arrow.replace('cn-icon', 'cn-badge-group__icon')}</a>`),
+    ],
+    rules: ['One badge group per page, placed above the hero or page title with 16–24px below it.', 'Inner badge: 1–2 words; label: one short sentence; always ends with the arrow when it links.', 'the system equivalent: badge group (light / modern; leading / trailing; sm–lg).'],
+    a11y: ['When it navigates it is an <a href>; otherwise a <span> without hover affordance.', 'The inner badge text is part of the link name; do not hide it.'],
+    related: ['badge', 'kicker', 'banner'],
+};

package/lib/components/badge.mjs

@@ -0,0 +1,174 @@
+import { RESET_BUTTON, TRANSITION_COLORS, ex, ICON, typeStyle } from "./_shared.mjs";
+const mix = (a, b, pct) => `color-mix(in srgb, ${a} ${pct}%, ${b})`;
+const scale = (s) => ({ bg: `{${s}.50}`, fg: `{${s}.700}`, ring: `{${s}.200}`, addon: `{${s}.500}`, solidBg: `{${s}.600}`, solidFg: '{white}' });
+/** Hues our primitives do not carry (gray-blue, indigo, pink, orange) are mixed from two neighbouring scales. */
+const mixed = (a, b, pct) => ({
+    bg: mix(`{${a}.50}`, `{${b}.50}`, pct),
+    fg: mix(`{${a}.700}`, `{${b}.700}`, pct),
+    ring: mix(`{${a}.200}`, `{${b}.200}`, pct),
+    addon: mix(`{${a}.500}`, `{${b}.500}`, pct),
+    solidBg: mix(`{${a}.600}`, `{${b}.600}`, pct),
+    solidFg: '{white}',
+});
+const TONES = {
+    neutral: { bg: '{color.bg-subtle}', fg: '{color.fg-muted}', ring: '{color.border-default}', addon: '{color.fg-subtle}', solidBg: '{color.bg-inverse}', solidFg: '{color.fg-inverse}' },
+    accent: scale('brand'),
+    success: scale('green'),
+    warning: scale('amber'),
+    danger: scale('red'),
+    info: scale('blue'),
+    'gray-blue': mixed('neutral', 'blue', 72),
+    'blue-light': { bg: '{blue.50}', fg: '{blue.600}', ring: '{blue.100}', addon: '{blue.400}', solidBg: '{blue.500}', solidFg: '{white}' },
+    blue: scale('blue'),
+    indigo: mixed('brand', 'blue', 55),
+    purple: scale('brand'),
+    pink: mixed('red', 'brand', 58),
+    orange: mixed('red', 'amber', 50),
+};
+const compound = Object.entries(TONES).flatMap(([tone, t]) => [
+    { when: { tone, variant: 'soft' }, block: { root: { 'background-color': t.bg, color: t.fg, 'border-color': t.ring } } },
+    { when: { tone, variant: 'outline' }, block: { root: { 'background-color': 'transparent', color: t.fg, 'border-color': t.ring } } },
+    { when: { tone, variant: 'solid' }, block: { root: { 'background-color': t.solidBg, color: t.solidFg, 'border-color': t.solidBg } } },
+]);
+const b = (text, tone = 'neutral', variant = 'soft', size = 'md', shape = 'square', inner = '') => `<span class="cn-badge" data-tone="${tone}" data-variant="${variant}" data-size="${size}" data-shape="${shape}">${inner}${text}</span>`;
+const DOT = '<span class="cn-badge__dot"></span>';
+const icon = (name) => ICON[name].replace('cn-icon', 'cn-badge__icon');
+const AVATAR = "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 avatar = (name) => `<img class="cn-badge__avatar" src="${AVATAR}" alt="" data-name="${name}">`;
+const x = (label) => `<button type="button" class="cn-badge__x" aria-label="Remove ${label}">${ICON.x}</button>`;
+export const badge = {
+    name: 'Badge',
+    slug: 'badge',
+    category: 'data-display',
+    description: 'Small status label with compact corners (or an optional pill): 12/14px medium text, a 1px ring one step darker than the fill, optional dot, icon, avatar or close button. The tone carries meaning, the variant carries emphasis.',
+    usage: 'Statuses, categories and counts next to a title, in a table cell, inside a tab or a nav item. Not for actions (use Button) and not for selectable or removable filters (use Tag) — the close button here only dismisses a label.',
+    anatomy: [
+        { part: 'root', element: 'span', description: 'The pill (or square). Sizes sm 22 / md 24 / lg 28px tall; text is medium weight, never uppercase.' },
+        { part: 'dot', element: 'span', description: 'Optional 6px status dot before the text in the tone\'s addon color. Use for live states (online, running).', optional: true },
+        { part: 'icon', element: 'svg', description: 'Optional 12px icon before or after the text, in the tone\'s addon color. Decorative.', optional: true },
+        { part: 'avatar', element: 'img', description: 'Optional 16px round image (a person, a flag, a logo) before the text.', optional: true },
+        { part: 'x', element: 'button', description: 'Optional 16px close button after the text (12px × icon). Needs aria-label "Remove {text}".', optional: true },
+    ],
+    props: {
+        tone: {
+            values: ['neutral', 'accent', 'success', 'warning', 'danger', 'info', 'gray-blue', 'blue-light', 'blue', 'indigo', 'purple', 'pink', 'orange'],
+            default: 'neutral',
+            description: 'Meaning. neutral (gray) for categories; accent (brand) for brand/AI; success/warning/danger (error) for state; info = blue. The extra hues (gray-blue, blue-light, blue, indigo, purple, pink, orange) are the system\'s decorative palette for labels and tags: use them only for user-chosen categories, never for state.',
+        },
+        variant: {
+            values: ['soft', 'outline', 'solid', 'modern'],
+            default: 'soft',
+            description: 'soft = tinted fill with a ring one step darker (the system pill-color / color); modern = white fill, gray ring and shadow-xs, only the dot/icon takes the tone color; outline = ring only, transparent fill; solid = filled, for one emphasized status per row at most.',
+        },
+        shape: {
+            values: ['pill', 'square'],
+            default: 'square',
+            description: 'square = compact token-defined corners (default); pill = fully rounded, for an explicitly round visual family.',
+        },
+        size: { values: ['sm', 'md', 'lg'], default: 'md', description: 'sm 22px tall with 12px text (tables, tabs, nav items); md 24px with 14px text (default); lg 28px with 14px text (page headers, cards).' },
+    },
+    states: {},
+    base: {
+        root: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            gap: '{space.1.5}',
+            'flex-shrink': '0',
+            'box-sizing': 'border-box',
+            height: '{space.6}',
+            'padding-inline': '{space.2.5}',
+            ...typeStyle('label-sm'),
+            'border-radius': '{radius.sm}',
+            border: '{border.width.thin} solid transparent',
+            'white-space': 'nowrap',
+            'vertical-align': 'middle',
+        },
+        dot: { width: '6px', height: '6px', 'border-radius': '{radius.full}', 'flex-shrink': '0', 'background-color': '{color.fg-subtle}' },
+        icon: { width: '{size.icon.xs}', height: '{size.icon.xs}', 'flex-shrink': '0', 'stroke-width': '2', color: '{color.fg-subtle}' },
+        avatar: { width: '{space.4}', height: '{space.4}', 'border-radius': '{radius.full}', 'object-fit': 'cover', 'flex-shrink': '0', 'max-width': 'none', 'background-color': '{color.bg-muted}' },
+        x: {
+            ...RESET_BUTTON,
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            width: '{space.4}',
+            height: '{space.4}',
+            'border-radius': '{radius.full}',
+            'flex-shrink': '0',
+            opacity: '{opacity.muted}',
+            ...TRANSITION_COLORS,
+        },
+    },
+    variants: {
+        tone: Object.fromEntries(Object.entries(TONES).map(([t, v]) => [t, { dot: { 'background-color': v.addon }, icon: { color: v.addon } }])),
+        variant: {
+            soft: { root: {} },
+            outline: { root: {} },
+            solid: { root: {}, dot: { 'background-color': 'currentColor' }, icon: { color: 'currentColor' } },
+            modern: { root: { 'background-color': '{color.bg-surface}', color: '{color.fg-muted}', 'border-color': '{color.border-control}', 'box-shadow': '{shadow.xs}' } },
+        },
+        shape: {
+            pill: { root: { 'border-radius': '{radius.full}' }, x: { 'border-radius': '{radius.full}' } },
+            square: { root: { 'border-radius': '{radius.md}' }, x: { 'border-radius': '3px' } },
+        },
+        size: {
+            sm: { root: { height: '22px', 'padding-inline': '{space.2}', gap: '{space.1}', ...typeStyle('label-xs') } },
+            md: { root: { height: '{space.6}', 'padding-inline': '{space.2.5}' } },
+            lg: { root: { height: '{space.7}', 'padding-inline': '{space.3}' } },
+        },
+    },
+    compound: [
+        ...compound,
+        { when: { shape: 'square', size: 'sm' }, block: { root: { 'padding-inline': '{space.1.5}' } } },
+        { when: { shape: 'square', size: 'md' }, block: { root: { 'padding-inline': '{space.2}' } } },
+        { when: { shape: 'square', size: 'lg' }, block: { root: { 'padding-inline': '{space.2.5}', 'border-radius': '{radius.lg}' } } },
+    ],
+    extraCss: `
+.cn-badge__x { color: currentColor; }
+.cn-badge__x:hover { opacity: 1; background-color: color-mix(in srgb, currentColor 12%, transparent); }
+.cn-badge__x:focus-visible { outline: none; opacity: 1; box-shadow: {shadow.focus}; }
+.cn-badge__x .cn-icon { width: {size.icon.xs}; height: {size.icon.xs}; stroke-width: 2; }
+/* the system trims the padding on the side that carries a dot, icon, avatar or close button. */
+.cn-badge:has(> .cn-badge__dot:first-child), .cn-badge:has(> .cn-badge__icon:first-child) { padding-inline-start: {space.2}; }
+.cn-badge[data-size="sm"]:has(> .cn-badge__dot:first-child), .cn-badge[data-size="sm"]:has(> .cn-badge__icon:first-child) { padding-inline-start: {space.1.5}; }
+.cn-badge[data-size="lg"]:has(> .cn-badge__dot:first-child), .cn-badge[data-size="lg"]:has(> .cn-badge__icon:first-child) { padding-inline-start: {space.2.5}; }
+.cn-badge:has(> .cn-badge__icon:last-child) { padding-inline-end: {space.2}; }
+.cn-badge[data-size="sm"]:has(> .cn-badge__icon:last-child) { padding-inline-end: {space.1.5}; }
+.cn-badge[data-size="lg"]:has(> .cn-badge__icon:last-child) { padding-inline-end: {space.2.5}; }
+.cn-badge:has(> .cn-badge__icon) { gap: {space.1}; }
+.cn-badge[data-size="sm"]:has(> .cn-badge__icon) { gap: {space.0.5}; }
+.cn-badge:has(> .cn-badge__avatar:first-child) { padding-inline-start: {space.1}; }
+.cn-badge[data-size="sm"]:has(> .cn-badge__avatar:first-child) { padding-inline-start: 3px; }
+.cn-badge[data-size="lg"]:has(> .cn-badge__avatar:first-child) { padding-inline-start: {space.1.5}; }
+.cn-badge[data-shape="square"]:has(> .cn-badge__avatar:first-child) { padding-inline-start: {space.1.5}; }
+.cn-badge[data-shape="square"][data-size="sm"]:has(> .cn-badge__avatar:first-child) { padding-inline-start: {space.1}; }
+.cn-badge[data-shape="square"][data-size="lg"]:has(> .cn-badge__avatar:first-child) { padding-inline-start: {space.2}; }
+.cn-badge:has(> .cn-badge__x:last-child) { padding-inline-end: {space.1}; gap: {space.0.5}; }
+.cn-badge[data-size="sm"]:has(> .cn-badge__x:last-child) { padding-inline-end: 3px; }
+.cn-badge[data-size="lg"]:has(> .cn-badge__x:last-child) { padding-inline-end: {space.1.5}; }`,
+    examples: [
+        ex('Colors (pill, soft)', ['neutral', 'accent', 'danger', 'warning', 'success', 'info', 'gray-blue', 'blue-light', 'blue', 'indigo', 'purple', 'pink', 'orange'].map((t) => b('Label', t)).join(' '), 'Order: gray, brand, error, warning, success, then the decorative hues.'),
+        ex('Sizes', `${b('Label', 'accent', 'soft', 'sm')} ${b('Label', 'accent', 'soft', 'md')} ${b('Label', 'accent', 'soft', 'lg')}`, 'sm 22px · md 24px · lg 28px.'),
+        ex('Types: pill-color, badge-color, badge-modern', `${b('Label', 'success', 'soft', 'md', 'pill')} ${b('Label', 'success', 'soft', 'md', 'square')} ${b('Label', 'success', 'modern', 'md', 'square')} ${b('Label', 'success', 'modern', 'lg', 'square')}`, 'square = 6px radius (8px at lg); modern = white with a gray ring and shadow-xs.'),
+        ex('With dot', `${b('Active', 'success', 'soft', 'md', 'pill', DOT)} ${b('Processing', 'accent', 'soft', 'md', 'square', DOT)} ${b('Online', 'success', 'modern', 'md', 'square', DOT)} ${b('Offline', 'neutral', 'modern', 'sm', 'square', DOT)}`, 'In the modern type only the dot takes the color.'),
+        ex('With icon', `${b('Verified', 'success', 'soft', 'md', 'pill', icon('check'))} ${b('Needs attention', 'warning', 'soft', 'md', 'square', icon('warning'))} <span class="cn-badge" data-tone="accent" data-variant="modern" data-size="md" data-shape="square">Open${icon('arrow')}</span>`, 'Leading or trailing, 12px, addon color.'),
+        ex('With avatar', `${b('Maya Chen', 'neutral', 'soft', 'md', 'pill', avatar('Maya Chen'))} ${b('Daniel Costa', 'neutral', 'modern', 'md', 'square', avatar('Daniel Costa'))} ${b('Sofia Almeida', 'accent', 'soft', 'lg', 'pill', avatar('Sofia Almeida'))}`),
+        ex('With x', `<span class="cn-badge" data-tone="neutral" data-variant="soft" data-size="md" data-shape="pill">Design${x('Design')}</span> <span class="cn-badge" data-tone="accent" data-variant="soft" data-size="md" data-shape="square">Reporting${x('Reporting')}</span> <span class="cn-badge" data-tone="neutral" data-variant="modern" data-size="lg" data-shape="square">the system${x('the system')}</span>`),
+        ex('Outline and solid', `${b('Draft', 'neutral', 'outline')} ${b('Overdue', 'danger', 'solid')} ${b('Live', 'success', 'solid', 'sm', 'pill', DOT)} ${b('New', 'accent', 'outline', 'md', 'square')}`),
+    ],
+    rules: [
+        'Text is 1–2 words in sentence case, medium weight, never uppercase.',
+        'One solid badge per row at most. Everything else soft, modern or outline.',
+        'Tone is meaning, not decoration: success = done/healthy, warning = needs attention, danger = failed/blocked, info = new/informational, accent = brand or AI-generated, neutral = category. The decorative hues are for user-defined labels only.',
+        'Modern badges keep gray text whatever the tone; only the dot or icon takes the color. Use them on tinted backgrounds where a colored fill would clash.',
+        'sm inside tables, tabs and nav items; md next to titles; lg in page headers and cards. Match the size of the text next to it.',
+        'Never make the badge itself clickable. If it filters, it is a Tag; if it acts, it is a Button. The × only dismisses a label.',
+    ],
+    a11y: [
+        'The text must carry the meaning; the dot, icon and tone are reinforcement. "Working" not just a green dot.',
+        'The close button needs aria-label "Remove {text}" and is the only focusable thing in a badge.',
+        'Live states with a dot may also use aria-live on the containing region, not on the badge.',
+        'Avatar images inside badges are decorative (alt="") because the text names the person.',
+    ],
+    related: ['tag', 'kicker', 'counter'],
+};

package/lib/components/banner.mjs

@@ -0,0 +1,116 @@
+import { FOCUS_RING, RESET_BUTTON, TRANSITION_COLORS, ex, ICON, typeStyle } from "./_shared.mjs";
+// tone → soft (bg, border, fg) and solid (bg, fg)
+const TONES = {
+    neutral: { bg: '{color.bg-subtle}', border: '{color.border-default}', fg: '{color.fg-default}', solidBg: '{color.bg-inverse}', solidFg: '{color.fg-inverse}' },
+    info: { bg: '{color.bg-info-subtle}', border: '{color.border-info}', fg: '{color.fg-info}', solidBg: '{color.bg-info}', solidFg: '{white}' },
+    warning: { bg: '{color.bg-warning-subtle}', border: '{color.border-warning}', fg: '{color.fg-warning}', solidBg: '{color.bg-warning}', solidFg: '{neutral.950}' },
+    danger: { bg: '{color.bg-danger-subtle}', border: '{color.border-danger}', fg: '{color.fg-danger}', solidBg: '{color.bg-danger}', solidFg: '{white}' },
+    accent: { bg: '{color.bg-accent-subtle}', border: '{color.border-default}', fg: '{color.fg-accent}', solidBg: '{color.bg-accent}', solidFg: '{color.fg-on-accent}' },
+};
+const compound = Object.entries(TONES).flatMap(([t, v]) => [
+    { when: { tone: t, variant: 'soft' }, block: { root: { 'background-color': v.bg, 'border-bottom-color': v.border, color: v.fg } } },
+    { when: { tone: t, variant: 'solid' }, block: { root: { 'background-color': v.solidBg, 'border-bottom-color': 'transparent', color: v.solidFg } } },
+]);
+const icon = (name) => ICON[name].replace('cn-icon', 'cn-banner__icon');
+const dismiss = `<button type="button" class="cn-banner__dismiss" aria-label="Dismiss">${ICON.x}</button>`;
+export const banner = {
+    name: 'Banner',
+    slug: 'banner',
+    category: 'feedback',
+    description: 'Full-width strip at the top of the page or a section: one line of text, an optional icon, one action and a dismiss. Square corners, no shadow, a hairline at the bottom; it reads as part of the chrome, not as a card.',
+    usage: 'Use for one notice that concerns the whole page or account: maintenance tonight, trial ending, a product announcement (tone accent), an outage (tone danger). Not for feedback on a specific element (use Alert) and not for transient confirmations (use Toast).',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'The strip. Spans the full width of its container; role="status" (or "alert" for danger).' },
+        { part: 'icon', element: 'svg', description: '16px icon in the current text color. Decorative.', optional: true },
+        { part: 'content', element: 'div', description: 'The message, one sentence, body-sm. Flexes to fill; may contain a <strong> lead.' },
+        { part: 'actions', element: 'div', description: 'One link or outline Button (size sm) on the right.', optional: true },
+        { part: 'dismiss', element: 'button', description: '24px ghost icon button with an X at the far end. aria-label="Dismiss".', optional: true },
+    ],
+    props: {
+        tone: {
+            values: ['neutral', 'info', 'warning', 'danger', 'accent'],
+            default: 'neutral',
+            description: 'neutral = housekeeping notice; info = something to know; warning = act before a deadline; danger = something is broken now; accent = brand announcement (new feature, launch) in the accent wash — never for status.',
+        },
+        variant: {
+            values: ['soft', 'solid'],
+            default: 'soft',
+            description: 'soft = tinted background with dark tone text (default); solid = filled tone background with white text, reserved for danger (outage) and info (maintenance) when the notice must not be missed.',
+        },
+    },
+    states: {
+        dismissHover: { selector: ' .cn-banner__dismiss:hover', description: 'Pointer over the dismiss button: faint current-color wash. Styled in extraCss because it lives on a child.', markup: 'native :hover on .cn-banner__dismiss' },
+        dismissFocus: { selector: ' .cn-banner__dismiss:focus-visible', description: 'Keyboard focus on the dismiss button shows the focus ring. Styled in extraCss.', markup: 'native :focus-visible on .cn-banner__dismiss' },
+        sticky: { selector: '[data-sticky]', description: 'Sticks under the topbar while the page scrolls. Position only; styled in extraCss so examples stay static.', markup: 'data-sticky attribute on the root' },
+    },
+    base: {
+        root: {
+            display: 'flex',
+            'align-items': 'center',
+            gap: '{space.3}',
+            width: '100%',
+            'min-height': '{size.control.lg}',
+            padding: '{space.2} {space.4}',
+            'border-radius': '{radius.none}',
+            'border-bottom': '{border.width.thin} solid {color.border-default}',
+            'background-color': '{color.bg-subtle}',
+            color: '{color.fg-default}',
+            ...typeStyle('body-sm'),
+            'box-shadow': 'none',
+        },
+        icon: { width: '{size.icon.md}', height: '{size.icon.md}', 'flex-shrink': '0' },
+        content: { flex: '1 1 auto', 'min-width': '0' },
+        actions: { display: 'flex', 'align-items': 'center', gap: '{space.2}', 'flex-shrink': '0' },
+        dismiss: {
+            ...RESET_BUTTON,
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            width: '{size.icon.xl}',
+            height: '{size.icon.xl}',
+            'margin-inline-end': 'calc({space.1} * -1)',
+            'border-radius': '{radius.md}',
+            color: 'inherit',
+            opacity: '{opacity.muted}',
+            ...TRANSITION_COLORS,
+        },
+    },
+    variants: {
+        tone: Object.fromEntries(Object.keys(TONES).map((t) => [t, { root: {} }])),
+        variant: { soft: { root: {} }, solid: { root: {} } },
+    },
+    compound,
+    extraCss: `
+.cn-banner .cn-banner__dismiss .cn-icon { width: {size.icon.sm}; height: {size.icon.sm}; }
+.cn-banner .cn-banner__dismiss:hover { opacity: 1; background-color: color-mix(in srgb, currentColor 12%, transparent); }
+.cn-banner .cn-banner__dismiss:focus-visible { opacity: 1; outline: none; box-shadow: ${FOCUS_RING['box-shadow']}; }
+.cn-banner .cn-banner__actions .cn-button { color: inherit; }
+.cn-banner[data-variant="solid"] .cn-banner__actions .cn-button[data-variant="outline"] { background-color: transparent; border-color: color-mix(in srgb, currentColor 40%, transparent); box-shadow: none; }
+.cn-banner[data-variant="solid"] .cn-banner__actions .cn-button[data-variant="link"] { text-decoration-color: currentColor; }
+.cn-banner[data-sticky] { position: sticky; top: 0; z-index: {z.sticky}; }`,
+    examples: [
+        ex('Neutral (soft)', `<div class="cn-banner" data-tone="neutral" data-variant="soft" role="status">${icon('info')}<div class="cn-banner__content"><strong>Scheduled maintenance</strong> on Saturday 14 Sep, 02:00–03:00 UTC. Outreach pauses during that hour.</div><div class="cn-banner__actions"><button type="button" class="cn-button" data-variant="link" data-size="sm"><span class="cn-button__label">Details</span></button></div>${dismiss}</div>`),
+        ex('Info', `<div class="cn-banner" data-tone="info" data-variant="soft" role="status">${icon('info')}<div class="cn-banner__content">Your trial ends in 6 days. Add a payment method to keep your prospects and drafts.</div><div class="cn-banner__actions"><button type="button" class="cn-button" data-variant="outline" data-size="sm"><span class="cn-button__label">Add payment method</span></button></div>${dismiss}</div>`),
+        ex('Warning', `<div class="cn-banner" data-tone="warning" data-variant="soft" role="status">${icon('warning')}<div class="cn-banner__content">The Gmail connection for <strong>sales@verolabs.com</strong> expires tomorrow. Reconnect to avoid a gap in replies.</div><div class="cn-banner__actions"><button type="button" class="cn-button" data-variant="outline" data-size="sm"><span class="cn-button__label">Reconnect</span></button></div></div>`),
+        ex('Accent (announcement)', `<div class="cn-banner" data-tone="accent" data-variant="soft" role="status">${icon('spark')}<div class="cn-banner__content"><strong>New:</strong> agents now read replies in Japanese and German and draft answers in the buyer’s language.</div><div class="cn-banner__actions"><button type="button" class="cn-button" data-variant="link" data-size="sm"><span class="cn-button__label">See what changed</span></button></div>${dismiss}</div>`),
+        ex('Danger (solid)', `<div class="cn-banner" data-tone="danger" data-variant="solid" role="alert">${icon('warning')}<div class="cn-banner__content">Email delivery is degraded since 09:12 UTC. Sent messages may arrive late; nothing is lost.</div><div class="cn-banner__actions"><button type="button" class="cn-button" data-variant="outline" data-size="sm"><span class="cn-button__label">Status page</span></button></div></div>`, 'solid is reserved for danger and info notices that must not be missed. No dismiss while the incident is open.'),
+    ],
+    rules: [
+        'One banner per page at most. If a second notice appears, the more urgent one wins and the other waits.',
+        'One sentence, ideally under 90 characters, with an optional <strong> lead. No title, no second line.',
+        'One action at most (link or outline, size sm) plus the dismiss. Never a primary Button in a banner.',
+        'No radius, no shadow, no margin: the banner touches the edges of its container and sits directly under the topbar.',
+        'Use data-sticky only when the notice must stay visible while scrolling (an open incident). Sticky banners are never accent.',
+        'variant="solid" only for tone danger or info. Never solid accent, warning or neutral.',
+        'Danger banners for open incidents are not dismissible; they leave when the incident closes.',
+        'Accent tone is for announcements only. It never signals a status or an error.',
+    ],
+    a11y: [
+        'role="status" by default; role="alert" for danger banners inserted after page load.',
+        'The banner is inside the header landmark or the first child of <main>, so screen readers meet it before the page content.',
+        'The dismiss button needs aria-label="Dismiss"; the action must be a real <button> or <a href>.',
+        'Solid variants keep AA contrast: white text on info/danger, ink text on warning.',
+    ],
+    related: ['alert', 'toast', 'topbar', 'button'],
+};