canon-ds 0.1.0

package/lib/components/activity-feed.mjs

@@ -0,0 +1,176 @@
+import { FOCUS_RING, TRANSITION_COLORS, ex, typeStyle } from "./_shared.mjs";
+// Activity feed: a column of "who did what to which object, when" rows joined by a
+// 2px connector under 32px avatars, with optional quoted comments, file attachments
+// and a comment composer at the end. The compact density is the notification-feed
+// version (24px avatars, one line per event).
+const HAIRLINE = '{border.width.thin} solid {color.border-default}';
+const FILE = '<svg class="cn-icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M4.5 2.5h4.5l3 3v8a.5.5 0 01-.5.5h-7a.5.5 0 01-.5-.5v-11z"/><path d="M9 2.5v3h3"/></svg>';
+const avatar = (initials, name) => `<span class="cn-activity-feed__avatar" role="img" aria-label="${name}">${initials}</span>`;
+const comment = (text) => `<div class="cn-activity-feed__comment">${text}</div>`;
+const attachment = (name, size) => `<a href="#" class="cn-activity-feed__attachment"><span class="cn-activity-feed__attachment-icon" aria-hidden="true">${FILE}</span><span class="cn-activity-feed__attachment-name">${name}</span><span class="cn-activity-feed__attachment-size">${size}</span></a>`;
+const item = (o) => `<article class="cn-activity-feed__item">${avatar(o.initials, o.actor)}<span class="cn-activity-feed__line" aria-hidden="true"></span><div class="cn-activity-feed__content"><div class="cn-activity-feed__header"><span class="cn-activity-feed__actor">${o.actor}</span><span class="cn-activity-feed__action">${o.action}</span>${o.target ? `<span class="cn-activity-feed__target">${o.target}</span>` : ''}<time class="cn-activity-feed__time" datetime="${o.datetime}">${o.time}</time></div>${o.extra ?? ''}</div></article>`;
+const composer = `<div class="cn-activity-feed__composer">${avatar('LF', 'Lucas Ferreira')}<div class="cn-activity-feed__content"><div class="cn-textarea" data-size="sm" data-resize="none"><textarea class="cn-textarea__field" rows="2" placeholder="Leave a comment…" aria-label="Comment"></textarea></div><div class="cn-activity-feed__composer-actions"><button type="button" class="cn-button" data-variant="primary" data-size="sm"><span class="cn-button__label">Comment</span></button></div></div></div>`;
+const feed = (variant, inner, width = '560px') => `<div class="cn-activity-feed" data-variant="${variant}" role="feed" aria-label="Activity" aria-busy="false" style="width:100%;max-width:${width}">${inner}</div>`;
+export const activityFeed = {
+    name: 'ActivityFeed',
+    slug: 'activity-feed',
+    category: 'data-display',
+    description: 'A vertical feed of events on one object or workspace: a 32px avatar, "actor did action to target" in one line with a subtle timestamp, joined by a 2px connector. Events can carry a quoted comment, a file attachment, and the feed can end with a comment composer.',
+    usage: 'Use on a record page (a deal, a project, a document) or a workspace home to show what people and agents did, newest first or oldest first per screen. For a process with known steps use Timeline; for chat use Message; for system notifications a person can act on use Notification.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'The feed column (role="feed"). Flex column; width comes from the layout.' },
+        { part: 'item', element: 'article', description: 'One event: avatar on the left, content on the right, relative so the connector can hang under the avatar. 12px vertical padding.' },
+        { part: 'avatar', element: 'span', description: '32px circle with initials (24px in compact). role="img" + aria-label with the actor name, or a real Avatar image.' },
+        { part: 'line', element: 'span', description: 'The 2px connector from this avatar to the next one, border-default. aria-hidden; hidden automatically on the last item.' },
+        { part: 'content', element: 'div', description: 'Column next to the avatar: header line first, then optional comment, attachment or composer fields.' },
+        { part: 'header', element: 'div', description: 'The one-line sentence: actor, action, target, time. Wraps on narrow widths.' },
+        { part: 'actor', element: 'span', description: 'Who did it, label-sm semibold in fg-default ("Maya Chen").' },
+        { part: 'action', element: 'span', description: 'The verb phrase in body-sm muted ("commented on", "uploaded").' },
+        { part: 'target', element: 'span', description: 'The object acted on, label-sm in fg-default ("Q3 launch plan"). Optional when the action is self-contained.', optional: true },
+        { part: 'time', element: 'time', description: 'When, body-xs in fg-subtle, after the sentence. Always a <time datetime>.' },
+        { part: 'comment', element: 'div', description: 'Quoted comment text in a bg-subtle card (radius lg, 12px padding, body-sm).', optional: true },
+        { part: 'attachment', element: 'a', description: 'A file row: icon, name and size in a hairline card. A link to the file.', optional: true },
+        { part: 'attachment-icon', element: 'span', description: '32px bg-subtle square holding a 16px file icon.', optional: true },
+        { part: 'attachment-name', element: 'span', description: 'File name, label-sm, truncated.', optional: true },
+        { part: 'attachment-size', element: 'span', description: 'Size or type, body-xs fg-subtle ("2.4 MB").', optional: true },
+        { part: 'composer', element: 'div', description: 'The comment box at the end of the feed: the current user\'s avatar next to a Textarea and a Comment button.', optional: true },
+        { part: 'composer-actions', element: 'div', description: 'Right-aligned row under the textarea holding the primary sm "Comment" button.', optional: true },
+    ],
+    props: {
+        variant: {
+            values: ['simple', 'with-comments', 'compact', 'with-composer'],
+            default: 'simple',
+            description: 'simple = one sentence per event with a 32px avatar (record pages). with-comments = the same rows plus quoted comment cards and file attachments (discussion on a document). compact = 24px avatars, tighter rows, for a notification-style feed in a side panel or popover. with-composer = the feed ends with a Textarea + Comment button so people can reply in place.',
+        },
+    },
+    states: {
+        busy: { selector: '[aria-busy="true"]', description: 'The feed is loading more events: content dims slightly. Set while fetching, clear when done.', markup: 'aria-busy="true" on the root' },
+        attachmentHover: { selector: ' .cn-activity-feed__attachment:hover', description: 'Pointer over a file row (lives on the attachment, styled in extraCss): subtle fill and a stronger border.', markup: 'native :hover on .cn-activity-feed__attachment' },
+        attachmentFocus: { selector: ' .cn-activity-feed__attachment:focus-visible', description: 'Keyboard focus on a file row shows the focus ring (extraCss).', markup: 'native :focus-visible on .cn-activity-feed__attachment' },
+    },
+    base: {
+        root: { display: 'flex', 'flex-direction': 'column', width: '100%', 'min-width': '0', color: '{color.fg-default}' },
+        item: { position: 'relative', display: 'flex', 'align-items': 'flex-start', gap: '{space.3}', 'padding-block': '{space.3}', 'min-width': '0' },
+        avatar: {
+            position: 'relative',
+            'z-index': '{z.raised}',
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            width: '{space.8}',
+            height: '{space.8}',
+            'border-radius': '{radius.full}',
+            'background-color': '{color.bg-subtle}',
+            color: '{color.fg-muted}',
+            ...typeStyle('label-xs'),
+            'letter-spacing': '{font.letterSpacing.wide}',
+            'text-transform': 'uppercase',
+            'user-select': 'none',
+            overflow: 'hidden',
+        },
+        line: {
+            position: 'absolute',
+            'inset-inline-start': 'calc({space.4} - {space.px})',
+            top: 'calc({space.3} + {space.8} + {space.1})',
+            bottom: 'calc(-1 * {space.2})',
+            width: '{border.width.medium}',
+            'border-radius': '{radius.full}',
+            'background-color': '{color.border-default}',
+        },
+        content: { flex: '1 1 auto', 'min-width': '0', display: 'flex', 'flex-direction': 'column', gap: '{space.2}', 'padding-top': '{space.1.5}' },
+        header: { display: 'flex', 'flex-wrap': 'wrap', 'align-items': 'baseline', 'column-gap': '{space.1}', 'row-gap': '0', ...typeStyle('body-sm'), color: '{color.fg-muted}' },
+        actor: { ...typeStyle('label-sm'), 'font-weight': '{font.weight.semibold}', 'line-height': '{font.lineHeight.normal}', color: '{color.fg-default}' },
+        action: { color: '{color.fg-muted}' },
+        target: { ...typeStyle('label-sm'), 'line-height': '{font.lineHeight.normal}', color: '{color.fg-default}' },
+        time: { ...typeStyle('body-xs'), color: '{color.fg-subtle}', 'margin-inline-start': '{space.1}', 'white-space': 'nowrap' },
+        comment: { 'background-color': '{color.bg-subtle}', 'border-radius': '{radius.lg}', padding: '{space.3}', ...typeStyle('body-sm'), color: '{color.fg-default}', 'overflow-wrap': 'anywhere' },
+        attachment: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            gap: '{space.3}',
+            'align-self': 'flex-start',
+            'max-width': '100%',
+            padding: '{space.2.5} {space.3}',
+            'background-color': '{color.bg-surface}',
+            border: HAIRLINE,
+            'border-radius': '{radius.lg}',
+            color: '{color.fg-default}',
+            'text-decoration': 'none',
+            ...TRANSITION_COLORS,
+        },
+        'attachment-icon': { display: 'inline-flex', 'align-items': 'center', 'justify-content': 'center', 'flex-shrink': '0', width: '{space.8}', height: '{space.8}', 'border-radius': '{radius.md}', 'background-color': '{color.bg-subtle}', color: '{color.fg-muted}' },
+        'attachment-name': { ...typeStyle('label-sm'), 'line-height': '{font.lineHeight.normal}', color: '{color.fg-default}', 'min-width': '0', overflow: 'hidden', 'text-overflow': 'ellipsis', 'white-space': 'nowrap' },
+        'attachment-size': { ...typeStyle('body-xs'), color: '{color.fg-subtle}', 'white-space': 'nowrap' },
+        composer: { display: 'flex', 'align-items': 'flex-start', gap: '{space.3}', 'padding-block': '{space.3}', 'min-width': '0' },
+        'composer-actions': { display: 'flex', 'justify-content': 'flex-end', 'align-items': 'center', gap: '{space.2}', 'margin-top': '{space.2}' },
+        '@states': {
+            busy: { content: { opacity: '{opacity.muted}' } },
+        },
+    },
+    variants: {
+        variant: {
+            simple: { root: {} },
+            'with-comments': { root: {} },
+            compact: {
+                item: { gap: '{space.2}', 'padding-block': '{space.2}' },
+                avatar: { width: '{space.6}', height: '{space.6}', 'font-size': '{font.size.2xs}' },
+                line: { 'inset-inline-start': 'calc({space.3} - {space.px})', top: 'calc({space.2} + {space.6} + {space.1})' },
+                content: { 'padding-top': '{space.0.5}', gap: '{space.1.5}' },
+                comment: { padding: '{space.2} {space.2.5}' },
+            },
+            'with-composer': { root: {} },
+        },
+    },
+    extraCss: `
+.cn-activity-feed__item:last-child .cn-activity-feed__line { display: none; }
+.cn-activity-feed__composer > .cn-activity-feed__content { padding-top: 0; }
+.cn-activity-feed__attachment-icon .cn-icon { width: {size.icon.md}; height: {size.icon.md}; }
+.cn-activity-feed__attachment:hover { background-color: {color.bg-subtle}; border-color: {color.border-control-hover}; }
+.cn-activity-feed__attachment:focus-visible { outline: none; box-shadow: ${FOCUS_RING['box-shadow']}; }
+.cn-activity-feed__comment p + p { margin-top: {space.2}; }`,
+    examples: [
+        ex('Simple', feed('simple', [
+            item({ initials: 'MC', actor: 'Maya Chen', action: 'commented on', target: 'Q3 launch plan', time: '2h ago', datetime: '2026-09-11T07:40' }),
+            item({ initials: 'DC', actor: 'Daniel Costa', action: 'uploaded', target: 'brand-guidelines-v3.pdf', time: '4h ago', datetime: '2026-09-11T05:12' }),
+            item({ initials: 'SA', actor: 'Sofia Almeida', action: 'assigned', target: 'Homepage redesign to Lucas Ferreira', time: 'Yesterday', datetime: '2026-09-10T16:05' }),
+            item({ initials: 'AK', actor: 'Aisha Khan', action: 'marked', target: 'Invoice INV-3066 as paid', time: 'Sep 9', datetime: '2026-09-09T11:30' }),
+        ].join('')), 'One sentence per event. The actor and the target are emphasized; the verb and the time are quiet.'),
+        ex('With comments and an attachment', feed('with-comments', [
+            item({ initials: 'MC', actor: 'Maya Chen', action: 'commented on', target: 'Q3 launch plan', time: '2h ago', datetime: '2026-09-11T07:40', extra: comment('Can we move the pricing page to the second sprint? Legal still needs to review the new tiers.') }),
+            item({ initials: 'DC', actor: 'Daniel Costa', action: 'replied', time: '1h ago', datetime: '2026-09-11T08:32', extra: comment('Works for me. I attached the updated timeline.') + attachment('q3-launch-timeline.xlsx', '312 KB') }),
+            item({ initials: 'NB', actor: 'Noah Berg', action: 'approved', target: 'Q3 launch plan', time: '20m ago', datetime: '2026-09-11T09:20' }),
+        ].join('')), 'Quoted comments sit in a subtle card; files are hairline rows that open the file.'),
+        ex('Compact (notification feed)', feed('compact', [
+            item({ initials: 'EL', actor: 'Elena Rossi', action: 'mentioned you in', target: 'Brand refresh', time: '5m', datetime: '2026-09-11T09:35' }),
+            item({ initials: 'TS', actor: 'Tomás Silva', action: 'requested access to', target: 'Finance dashboard', time: '32m', datetime: '2026-09-11T09:08' }),
+            item({ initials: 'AK', actor: 'Aisha Khan', action: 'closed', target: 'Ticket #4821', time: '1h', datetime: '2026-09-11T08:40' }),
+            item({ initials: 'SA', actor: 'Sofia Almeida', action: 'shared', target: 'Onboarding checklist', time: '3h', datetime: '2026-09-11T06:40' }),
+            item({ initials: 'LF', actor: 'Lucas Ferreira', action: 'joined', target: 'Lumen Design', time: 'Yesterday', datetime: '2026-09-10T14:00' }),
+        ].join(''), '420px'), '24px avatars and 8px vertical padding for side panels and popovers.'),
+        ex('With composer', feed('with-composer', [
+            item({ initials: 'MC', actor: 'Maya Chen', action: 'commented on', target: 'Pricing page copy', time: '1h ago', datetime: '2026-09-11T08:40', extra: comment('The second headline reads better. Can we A/B test both?') }),
+            item({ initials: 'AK', actor: 'Aisha Khan', action: 'replied', time: '40m ago', datetime: '2026-09-11T09:00', extra: comment('Yes — I set up the test for Monday.') }),
+            composer,
+        ].join('')), 'The composer reuses the item layout so the connector runs into the current user\'s avatar.'),
+    ],
+    rules: [
+        'Every row is one sentence in the same shape: actor, verb, target, time. Actor and target are emphasized; the verb and the time stay quiet.',
+        'Verbs are past tense and specific ("uploaded", "approved", "mentioned you in"); never "updated the record".',
+        'Pick one order per screen: newest first for a home feed, oldest first on a record where the story matters.',
+        'Timestamps are relative under 24h ("2h ago"), absolute after ("Sep 9"), always in a <time datetime>.',
+        'Comments are quoted verbatim in the subtle card and truncated after four lines with a "Show more" link Button; the feed never renders an entire email.',
+        'Attachments show name and size; the icon is the file type, not a thumbnail. One attachment row per file.',
+        'Use compact only in side panels, popovers and notification drawers; on a page the default size keeps comments readable.',
+        'The composer goes last, after the newest event, and uses a sm Textarea with a single primary "Comment" button; no toolbar.',
+        'Long feeds paginate with a "Show 20 earlier events" link Button at the end, not infinite scroll inside a card.',
+    ],
+    a11y: [
+        'Root has role="feed" with an aria-label; each event is an <article> so screen readers can jump between them. Set aria-busy="true" on the root while loading more.',
+        'Initials avatars carry role="img" and aria-label with the full name; the connector line is aria-hidden.',
+        'The sentence must read correctly in DOM order: actor, action, target, time. Do not move the time before the actor with CSS.',
+        'Attachments are real links with the file name as the accessible name; the size is extra text, not the only label.',
+        'The composer textarea has a label ("Comment") and the button is a real <button>; Cmd/Ctrl+Enter may submit but is never the only way.',
+    ],
+    related: ['timeline', 'avatar', 'textarea', 'message', 'notification', 'list'],
+};

package/lib/components/activity-gauge.mjs

@@ -0,0 +1,98 @@
+import { ex, typeStyle } from "./_shared.mjs";
+// Two or three concentric rings, one per metric, in brand.600 / brand.400 / brand.200 from the
+// outside in, with a legend beside them. Same geometry rules as ProgressCircle: viewBox 0 0 100 100,
+// stroke-width 8, radii 42 / 32 / 22 → circumferences 263.89 / 201.06 / 138.23.
+const RINGS = [
+    { r: 42, c: 263.89 },
+    { r: 32, c: 201.06 },
+    { r: 22, c: 138.23 },
+];
+const RING_COLOR = ['{brand.600}', '{brand.400}', '{brand.200}'];
+const gauge = (o) => {
+    const rings = o.metrics.map((m, i) => {
+        const { r, c } = RINGS[i];
+        return `<circle class="cn-activity-gauge__ring" data-ring="${i + 1}" data-track cx="50" cy="50" r="${r}"/><circle class="cn-activity-gauge__ring" data-ring="${i + 1}" cx="50" cy="50" r="${r}" style="stroke-dasharray:${c};stroke-dashoffset:${(c * (1 - m.value / 100)).toFixed(1)}"/>`;
+    }).join('');
+    const legend = o.metrics.map((m, i) => `<li class="cn-activity-gauge__legend-item"><span class="cn-activity-gauge__swatch" data-ring="${i + 1}"></span><span class="cn-activity-gauge__label">${m.label}</span><span class="cn-activity-gauge__label" data-value>${m.text ?? `${m.value}%`}</span></li>`).join('');
+    return `<div class="cn-activity-gauge" data-size="${o.size ?? 'md'}" role="img" aria-label="${o.label}"><svg class="cn-activity-gauge__rings" viewBox="0 0 100 100" aria-hidden="true">${rings}</svg><ul class="cn-activity-gauge__legend">${legend}</ul></div>`;
+};
+const OUTREACH = [
+    { label: 'Emails sent', value: 72 },
+    { label: 'Replies', value: 48 },
+    { label: 'Meetings booked', value: 91 },
+];
+export const activityGauge = {
+    name: 'ActivityGauge',
+    slug: 'activity-gauge',
+    category: 'data-display',
+    description: 'Two or three concentric rings that each show a share of a goal, from the outer ring in the strongest brand tint to the inner one in the lightest, with a legend beside them that names each ring and its value.',
+    usage: 'Use on a dashboard card to compare 2–3 related goals at a glance (sent / replied / booked; storage / bandwidth / seats). For one value use ProgressCircle; for more than three metrics or exact comparison use a bar chart in a ChartFrame; for a trend use a line chart.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'Row (inline-flex, align center) with the rings on the left and the legend on the right. role="img" with an aria-label that reads every metric. Carries data-size.' },
+        { part: 'rings', element: 'svg', description: 'The square svg, viewBox 0 0 100 100, holding a track and a value ring per metric.' },
+        { part: 'ring', element: 'circle', description: 'One ring. data-ring="1|2|3" sets the color (brand.600 / 400 / 200, outside in); data-track marks the grey background ring. Value rings set stroke-dasharray (circumference) and stroke-dashoffset inline.' },
+        { part: 'legend', element: 'ul', description: 'Stacked list of metrics next to the rings, gap space.2, no bullets.' },
+        { part: 'legend-item', element: 'li', description: 'One row: swatch, label, value (label with data-value).' },
+        { part: 'swatch', element: 'span', description: '8px round dot in the ring color (data-ring).' },
+        { part: 'label', element: 'span', description: 'body-sm text: the metric name in fg-muted; with data-value, the number pushed to the end in fg-default, tabular.' },
+    ],
+    props: {
+        size: { values: ['sm', 'md', 'lg'], default: 'md', description: 'Ring box 96 / 128 / 160px. sm for a stat tile, md for a dashboard card, lg for a page section with a heading.' },
+    },
+    states: {},
+    base: {
+        root: { display: 'inline-flex', 'flex-wrap': 'wrap', 'align-items': 'center', gap: '{space.6}', 'max-width': '100%', color: '{color.fg-default}', 'vertical-align': 'middle' },
+        rings: { display: 'block', 'flex-shrink': '0', width: '{space.32}', height: '{space.32}', overflow: 'visible' },
+        ring: {
+            fill: 'none',
+            stroke: '{brand.600}',
+            'stroke-width': '8',
+            'stroke-linecap': 'round',
+            transform: 'rotate(-90deg)',
+            'transform-origin': '50% 50%',
+            'transition-property': 'stroke-dashoffset',
+            'transition-duration': '{motion.duration.slow}',
+            'transition-timing-function': '{motion.easing.standard}',
+        },
+        legend: { display: 'flex', 'flex-direction': 'column', gap: '{space.2}', margin: '0', padding: '0', 'list-style': 'none', 'min-width': '{space.40}' },
+        'legend-item': { display: 'flex', 'align-items': 'center', gap: '{space.2}', ...typeStyle('body-sm') },
+        swatch: { width: '{space.2}', height: '{space.2}', 'flex-shrink': '0', 'border-radius': '{radius.full}', 'background-color': '{brand.600}' },
+        label: { color: '{color.fg-muted}', 'min-width': '0', overflow: 'hidden', 'text-overflow': 'ellipsis', 'white-space': 'nowrap' },
+    },
+    variants: {
+        size: {
+            sm: { root: { gap: '{space.4}' }, rings: { width: '{space.24}', height: '{space.24}' }, 'legend-item': { 'font-size': '{font.size.xs}' }, legend: { 'min-width': '{space.32}' } },
+            md: { rings: { width: '{space.32}', height: '{space.32}' } },
+            lg: { root: { gap: '{space.8}' }, rings: { width: '{space.40}', height: '{space.40}' }, 'legend-item': { 'font-size': '{font.size.md}' }, legend: { gap: '{space.3}' } },
+        },
+    },
+    extraCss: `
+.cn-activity-gauge .cn-activity-gauge__ring[data-track] { stroke: {color.bg-subtle}; stroke-linecap: butt; }
+.cn-activity-gauge .cn-activity-gauge__ring[data-ring="1"]:not([data-track]), .cn-activity-gauge .cn-activity-gauge__swatch[data-ring="1"] { stroke: ${RING_COLOR[0]}; background-color: ${RING_COLOR[0]}; }
+.cn-activity-gauge .cn-activity-gauge__ring[data-ring="2"]:not([data-track]), .cn-activity-gauge .cn-activity-gauge__swatch[data-ring="2"] { stroke: ${RING_COLOR[1]}; background-color: ${RING_COLOR[1]}; }
+.cn-activity-gauge .cn-activity-gauge__ring[data-ring="3"]:not([data-track]), .cn-activity-gauge .cn-activity-gauge__swatch[data-ring="3"] { stroke: ${RING_COLOR[2]}; background-color: ${RING_COLOR[2]}; }
+.cn-activity-gauge .cn-activity-gauge__label[data-value] { margin-inline-start: auto; color: {color.fg-default}; font-weight: {font.weight.medium}; font-variant-numeric: tabular-nums; flex-shrink: 0; }`,
+    examples: [
+        ex('Three metrics (md)', gauge({ metrics: OUTREACH, label: 'Outreach this week: emails sent 72%, replies 48%, meetings booked 91%' }), 'Outer ring = first metric in brand.600, then brand.400, then brand.200. Offsets: 263.89 × 0.28 = 73.9, 201.06 × 0.52 = 104.6, 138.23 × 0.09 = 12.4.'),
+        ex('Two metrics', gauge({ metrics: [{ label: 'Storage', value: 64, text: '64 GB of 100' }, { label: 'Bandwidth', value: 37, text: '37%' }], label: 'Usage: storage 64 GB of 100, bandwidth 37%' }), 'With two metrics only the outer two radii are used; the values can be counts.'),
+        ex('Sizes', `<div style="display:flex;flex-wrap:wrap;align-items:center;gap:var(--cn-space-8)">${gauge({ size: 'sm', metrics: OUTREACH, label: 'Outreach: emails sent 72%, replies 48%, meetings booked 91%' })}${gauge({ size: 'lg', metrics: OUTREACH, label: 'Outreach: emails sent 72%, replies 48%, meetings booked 91%' })}</div>`, '96px (sm) and 160px (lg) rings with body-xs / body-md legends.'),
+    ],
+    recipes: [
+        ex('Dashboard card', `<section class="cn-card" data-variant="default" data-padding="md" style="max-width:420px"><header class="cn-card__header"><div><h3 class="cn-card__title">Outreach this week</h3><p class="cn-card__description">Share of the weekly goal, Sep 7–11</p></div></header><div class="cn-card__body">${gauge({ metrics: OUTREACH, label: 'Outreach this week: emails sent 72%, replies 48%, meetings booked 91%' })}</div></section>`, 'Title names the goal, description the period; the gauge is the whole body.'),
+    ],
+    rules: [
+        'Two or three rings, never one (ProgressCircle) or four. Order metrics by importance: the first is the outer ring in the strongest tint.',
+        'Geometry is fixed: viewBox 0 0 100 100, stroke 8, radii 42 / 32 / 22 with circumferences 263.89 / 201.06 / 138.23. Each value ring sets stroke-dasharray to its circumference and stroke-dashoffset = circumference × (1 − value / 100) inline.',
+        'Every value ring has a track ring of the same radius behind it (data-track) so an empty metric still reads as a ring.',
+        'Colors are the three brand tints only; the rings compare shares of goals, not statuses. Use a bar chart when the metrics need distinct hues.',
+        'The legend is mandatory and lists the metrics in ring order, each with its value; the number may be a count ("64 GB of 100") when the percentage alone is unclear.',
+        'Values are capped at 100%; show "100%" and say the goal was exceeded in the caption or the card description.',
+        'One gauge per card. sm in stat tiles, md in dashboard cards, lg in a page section.',
+    ],
+    a11y: [
+        'The root is role="img" with an aria-label that reads every metric and value in ring order; the svg is aria-hidden.',
+        'The legend repeats the same information as visible text, so the rings are never the only source.',
+        'Swatches are decorative; the pairing between ring and legend is also carried by order (outer to inner, top to bottom).',
+    ],
+    related: ['progress-circle', 'progress', 'stat', 'chart-frame', 'card'],
+};

package/lib/components/agent-presence.mjs

@@ -0,0 +1,156 @@
+import { ex, ICON, typeStyle } from "./_shared.mjs";
+// status → dot fill, pill bg, pill fg
+const STATUS = {
+    working: { dot: '{color.bg-accent}', pillBg: '{color.bg-accent-subtle}', pillFg: '{color.fg-accent}', label: 'Working' },
+    waiting: { dot: '{color.bg-warning}', pillBg: '{color.bg-warning-subtle}', pillFg: '{color.fg-warning}', label: 'Waiting for you' },
+    idle: { dot: '{color.fg-subtle}', pillBg: '{color.bg-subtle}', pillFg: '{color.fg-muted}', label: 'Idle' },
+    offline: { dot: '{color.bg-muted}', pillBg: '{color.bg-subtle}', pillFg: '{color.fg-subtle}', label: 'Offline' },
+};
+const avatar = (initials) => `<span class="cn-agent-presence__avatar">${initials ?? ICON.spark}<span class="cn-agent-presence__dot"></span></span>`;
+export const agentPresence = {
+    name: 'AgentPresence',
+    slug: 'agent-presence',
+    category: 'data-display',
+    description: 'Shows an AI agent as a teammate: avatar with a status dot, the name, a state pill and a live line saying what it is doing right now. The accent color appears only here and only when an agent is working.',
+    usage: 'Use wherever a user needs to know whether an agent is active and on what: the team rail, a conversation header, a run list, a kanban card. Not for human users (use Avatar) and not for static labels (use Badge). The activity line must be live; if there is nothing current, show the last run time instead.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'The element. Chip is inline; row and card are a grid: avatar | name + state | time on the first line, activity on the second.' },
+        { part: 'avatar', element: 'span', description: '24px circle (20px in sm) in the accent wash with the agent’s initials or the spark icon in fg-accent. Contains the dot.' },
+        { part: 'dot', element: 'span', description: '8px status dot at the avatar’s bottom-right with a 2px surface ring. Pulses (halo) only when working.' },
+        { part: 'name', element: 'span', description: 'label-sm, the agent’s name ("Vera", "Iris"). Never a role or a model name.' },
+        { part: 'state', element: 'span', description: 'Kicker-style pill: "Working", "Waiting for you", "Idle", "Offline". Hidden in chip.', optional: true },
+        { part: 'activity', element: 'span', description: 'body-xs muted, truncated, the live "now" line: "Reading 3 replies from Nakamura…". Hidden in chip.', optional: true },
+        { part: 'time', element: 'span', description: 'code-sm subtle, how long the current state has lasted ("2m", "40m"). Hidden in chip.', optional: true },
+    ],
+    props: {
+        variant: {
+            values: ['chip', 'row', 'card'],
+            default: 'row',
+            description: 'chip = inline pill with avatar, name and dot only (inside text, headers, kanban cards); row = one line in a list with the state pill, activity and time (default); card = the row on a bordered surface with padding, for a team grid or a dashboard.',
+        },
+        size: {
+            values: ['sm', 'md'],
+            default: 'md',
+            description: 'md = 24px avatar, label-sm name (default); sm = 20px avatar, label-xs name, for dense tables and chips inside text.',
+        },
+        status: {
+            values: ['working', 'waiting', 'idle', 'offline'],
+            default: 'idle',
+            description: 'working = the agent is acting right now: accent dot with a pulse and an accent pill; waiting = it needs the user (approval, a file): warning dot and pill; idle = available, nothing running: neutral; offline = paused or disconnected: muted dot and the whole element at 70% opacity.',
+        },
+    },
+    states: {},
+    base: {
+        root: {
+            display: 'grid',
+            'grid-template-columns': 'auto auto 1fr auto',
+            'grid-template-areas': '"avatar name state time" "avatar activity activity time"',
+            'align-items': 'center',
+            'column-gap': '{space.2}',
+            'row-gap': '{space.0.5}',
+            'min-width': '0',
+            color: '{color.fg-default}',
+            ...typeStyle('body-sm'),
+        },
+        avatar: {
+            'grid-area': 'avatar',
+            position: 'relative',
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            width: '{size.icon.xl}',
+            height: '{size.icon.xl}',
+            'margin-inline-end': '{space.1}',
+            'border-radius': '{radius.full}',
+            'background-color': '{color.bg-accent-subtle}',
+            color: '{color.fg-accent}',
+            ...typeStyle('label-xs'),
+            'font-size': '{font.size.2xs}',
+            'text-transform': 'uppercase',
+            'letter-spacing': '{font.letterSpacing.wide}',
+        },
+        dot: {
+            position: 'absolute',
+            right: '-1px',
+            bottom: '-1px',
+            width: '8px',
+            height: '8px',
+            'border-radius': '{radius.full}',
+            'background-color': '{color.fg-subtle}',
+            'box-shadow': '0 0 0 2px {color.bg-surface}',
+        },
+        name: { 'grid-area': 'name', ...typeStyle('label-sm'), color: '{color.fg-default}', 'white-space': 'nowrap' },
+        state: {
+            'grid-area': 'state',
+            'justify-self': 'start',
+            display: 'inline-flex',
+            'align-items': 'center',
+            height: '{size.icon.lg}',
+            'padding-inline': '{space.2}',
+            'border-radius': '{radius.full}',
+            ...typeStyle('kicker'),
+            'text-transform': 'uppercase',
+            'background-color': '{color.bg-subtle}',
+            color: '{color.fg-muted}',
+            'white-space': 'nowrap',
+        },
+        activity: { 'grid-area': 'activity', ...typeStyle('body-xs'), color: '{color.fg-muted}', 'min-width': '0', overflow: 'hidden', 'text-overflow': 'ellipsis', 'white-space': 'nowrap' },
+        time: { 'grid-area': 'time', 'align-self': 'start', ...typeStyle('code-sm'), color: '{color.fg-subtle}', 'white-space': 'nowrap', 'padding-top': '{space.0.5}' },
+    },
+    variants: {
+        variant: {
+            chip: {
+                root: { display: 'inline-flex', 'align-items': 'center', gap: '{space.1.5}', height: '{size.control.xs}', 'padding-inline': '{space.1} {space.2.5}', 'border-radius': '{radius.full}', border: '{border.width.thin} solid {color.border-default}', 'background-color': '{color.bg-surface}', 'vertical-align': 'middle' },
+                avatar: { width: '{size.icon.lg}', height: '{size.icon.lg}', 'margin-inline-end': '0' },
+                dot: { width: '6px', height: '6px' },
+                state: { display: 'none' },
+                activity: { display: 'none' },
+                time: { display: 'none' },
+            },
+            row: { root: { padding: '{space.2} 0' } },
+            card: { root: { padding: '{space.4}', 'background-color': '{color.bg-surface}', border: '{border.width.thin} solid {color.border-default}', 'border-radius': '{radius.xl}' } },
+        },
+        size: {
+            sm: { avatar: { width: '{size.icon.lg}', height: '{size.icon.lg}' }, name: { ...typeStyle('label-xs') }, state: { height: '{size.icon.md}', 'font-size': '9px' } },
+            md: { root: {} },
+        },
+        status: Object.fromEntries(Object.entries(STATUS).map(([s, v]) => [s, {
+                dot: { 'background-color': v.dot, ...(s === 'working' ? { animation: 'cn-agent-presence-pulse 1.8s {motion.easing.standard} infinite' } : {}) },
+                state: { 'background-color': v.pillBg, color: v.pillFg },
+                ...(s === 'offline' ? { root: { opacity: '{opacity.muted}' } } : {}),
+            }])),
+    },
+    extraCss: `
+@keyframes cn-agent-presence-pulse { 0% { box-shadow: 0 0 0 2px {color.bg-surface}, 0 0 0 2px color-mix(in srgb, {color.bg-accent} 45%, transparent); } 100% { box-shadow: 0 0 0 2px {color.bg-surface}, 0 0 0 8px transparent; } }
+.cn-agent-presence .cn-agent-presence__avatar .cn-icon { width: {size.icon.sm}; height: {size.icon.sm}; }
+.cn-agent-presence[data-variant="chip"] .cn-agent-presence__avatar .cn-icon { width: {size.icon.xs}; height: {size.icon.xs}; }`,
+    examples: [
+        ex('Row, working', `<div class="cn-agent-presence" data-variant="row" data-size="md" data-status="working" style="width:420px">${avatar()}<span class="cn-agent-presence__name">Vera</span><span class="cn-agent-presence__state">Working</span><span class="cn-agent-presence__activity">Reading 3 replies from Nakamura Trading Co.…</span><span class="cn-agent-presence__time">2m</span></div>`),
+        ex('Row, waiting for you', `<div class="cn-agent-presence" data-variant="row" data-size="md" data-status="waiting" style="width:420px">${avatar('IR')}<span class="cn-agent-presence__name">Iris</span><span class="cn-agent-presence__state">Waiting for you</span><span class="cn-agent-presence__activity">2 drafts ready for approval · Hoffmann GmbH, Lagos Fresh</span><span class="cn-agent-presence__time">14m</span></div>`),
+        ex('Row, idle', `<div class="cn-agent-presence" data-variant="row" data-size="md" data-status="idle" style="width:420px">${avatar('TH')}<span class="cn-agent-presence__name">Theo</span><span class="cn-agent-presence__state">Idle</span><span class="cn-agent-presence__activity">Last run 40 min ago · verified 38 companies</span><span class="cn-agent-presence__time">40m</span></div>`),
+        ex('Row, offline', `<div class="cn-agent-presence" data-variant="row" data-size="md" data-status="offline" style="width:420px">${avatar('KA')}<span class="cn-agent-presence__name">Kai</span><span class="cn-agent-presence__state">Offline</span><span class="cn-agent-presence__activity">Paused until Monday 08:00</span><span class="cn-agent-presence__time">2d</span></div>`),
+        ex('Chips', `<span class="cn-agent-presence" data-variant="chip" data-size="md" data-status="working">${avatar()}<span class="cn-agent-presence__name">Vera</span></span> <span class="cn-agent-presence" data-variant="chip" data-size="md" data-status="waiting">${avatar('IR')}<span class="cn-agent-presence__name">Iris</span></span> <span class="cn-agent-presence" data-variant="chip" data-size="sm" data-status="idle">${avatar('TH')}<span class="cn-agent-presence__name">Theo</span></span>`, 'Chips carry only avatar, dot and name. Use them inline: “Assigned to [Vera]”.'),
+        ex('Card, working, sm', `<div class="cn-agent-presence" data-variant="card" data-size="sm" data-status="working" style="width:320px">${avatar()}<span class="cn-agent-presence__name">Vera</span><span class="cn-agent-presence__state">Working</span><span class="cn-agent-presence__activity">Drafting a reply to Marisco del Sur in Spanish…</span><span class="cn-agent-presence__time">45s</span></div>`),
+    ],
+    recipes: [
+        ex('Team rail', `<div style="display:flex;flex-direction:column;width:420px;border:1px solid var(--cn-color-border-default);border-radius:var(--cn-radius-xl);background:var(--cn-color-bg-surface);padding:var(--cn-space-2) var(--cn-space-4)"><div class="cn-agent-presence" data-variant="row" data-size="md" data-status="working">${avatar()}<span class="cn-agent-presence__name">Vera</span><span class="cn-agent-presence__state">Working</span><span class="cn-agent-presence__activity">Searching importers in South Korea…</span><span class="cn-agent-presence__time">6m</span></div><div class="cn-agent-presence" data-variant="row" data-size="md" data-status="waiting">${avatar('IR')}<span class="cn-agent-presence__name">Iris</span><span class="cn-agent-presence__state">Waiting for you</span><span class="cn-agent-presence__activity">Needs the price list for Hoffmann GmbH</span><span class="cn-agent-presence__time">1h</span></div><div class="cn-agent-presence" data-variant="row" data-size="md" data-status="idle">${avatar('TH')}<span class="cn-agent-presence__name">Theo</span><span class="cn-agent-presence__state">Idle</span><span class="cn-agent-presence__activity">Last run today 07:00</span><span class="cn-agent-presence__time">3h</span></div></div>`, 'Rows stack with no divider; waiting agents sort above working ones because they need the user.'),
+    ],
+    rules: [
+        'Orchid/accent means "an agent is working". This is the only place accent is used as a status; never use it for human users or for success.',
+        'The activity line is live and concrete: verb + object + count ("Reading 3 replies from Nakamura…"). It updates in place without re-rendering the row.',
+        'When nothing is happening, the activity line shows the last run ("Last run 40 min ago · verified 38 companies"), never "Nothing to do".',
+        'Agents have a name and a task, not a personality: no "I", no emoji, no "thinking…", no model names.',
+        'State pill text is fixed: Working / Waiting for you / Idle / Offline. Do not invent states; put details in the activity line.',
+        'waiting sorts above working in any list: it is the one status that needs the user.',
+        'Chips carry no activity; if the reader needs to know what the agent is doing, use a row.',
+        'The pulse is the only motion: 1.8s halo on the dot while working, off under prefers-reduced-motion.',
+    ],
+    a11y: [
+        'The status is text (the pill) and never only the dot color; chips keep the status in an aria-label on the root ("Vera, working").',
+        'The activity line is a polite live region (aria-live="polite" on the list, not on each row) so screen readers hear changes without interruption.',
+        'Time is relative and short ("2m"); pair it with a title attribute carrying the absolute time.',
+        'Initials in the avatar are aria-hidden when the name is visible next to them.',
+    ],
+    related: ['avatar', 'badge', 'progress', 'card'],
+};