canon-ds 0.1.0

package/lib/components/textarea.mjs

@@ -0,0 +1,117 @@
+import { CONTROL, SIZE_PROP, ex, typeStyle } from "./_shared.mjs";
+// the reference textarea: padding 12px (sm) / 12×14px (md, lg), 14px/20px text (16px/24px on lg;
+// the reference uses 16px on md too — we keep 14px as the default UI size), 1px inset gray-300
+// ring under shadow-xs, radius 8, focus = brand ring, invalid = red-300 ring, disabled = 50%.
+// Height comes from rows (rows="3" by default in our forms; the browser default is 2).
+const TRANSITION_FAST = {
+    'transition-property': 'box-shadow, background-color, color, opacity',
+    'transition-duration': '{motion.duration.fast}',
+    'transition-timing-function': '{motion.easing.linear}',
+};
+const ring = (color) => `inset 0 0 0 1px ${color}`;
+const RING_REST = `${ring('{color.border-control}')}, {shadow.xs}`;
+const RING_HOVER = `${ring('{color.border-control-hover}')}, {shadow.xs}`;
+const RING_FOCUS = `${ring('{color.border-action}')}, {shadow.xs}, {shadow.focus}`;
+const RING_INVALID = `${ring('{color.border-danger}')}, {shadow.xs}`;
+const RING_INVALID_FOCUS = `${ring('{color.border-danger}')}, {shadow.xs}, {shadow.focus-danger}`;
+const SIZE = {
+    sm: { px: '{space.3}', py: '{space.3}', lh: '{type.body-md.lineHeight}' },
+    md: { px: '{space.3.5}', py: '{space.3}', lh: '{type.body-md.lineHeight}' },
+    lg: { px: '{space.3.5}', py: '{space.3}', lh: '{type.body-lg.lineHeight}' },
+};
+const sizeBlock = (s) => ({
+    field: { 'padding-inline': SIZE[s].px, 'padding-block': SIZE[s].py, 'font-size': CONTROL[s].font, 'line-height': SIZE[s].lh },
+});
+const ta = (attrs, body = '', size = 'md', resize = 'vertical', style = 'max-width:480px') => `<div class="cn-textarea" data-size="${size}" data-resize="${resize}" style="${style}"><textarea class="cn-textarea__field" rows="3" ${attrs}>${body}</textarea></div>`;
+export const textarea = {
+    name: 'Textarea',
+    slug: 'textarea',
+    category: 'forms',
+    description: 'Multi-line text field with the same ring, radius 8, shadow-xs and focus ring as Input. Padding 12px (sm) or 12×14px (md, lg); the height comes from rows. The wrapper carries the ring; the native textarea is bare.',
+    usage: 'Free-form text longer than one line: notes, messages, descriptions, addresses. For one line use Input; for rich formatting use an editor component. Pair with Field for label, hint and a character count.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'Wrapper that draws the ring, background, radius, shadow-xs and the focus ring (:focus-within).' },
+        { part: 'field', element: 'textarea', description: 'The native <textarea>. No border, no outline, fills the wrapper. Set rows to size it (3 in forms); the wrapper grows with it and with a vertical resize.' },
+    ],
+    props: {
+        size: SIZE_PROP(['sm', 'md', 'lg']),
+        resize: { values: ['none', 'vertical'], default: 'vertical', description: 'vertical = the user can drag the corner to make it taller (default for notes and messages); none = fixed height, for inputs with a strict length or inside dense layouts.' },
+    },
+    states: {
+        hover: { selector: ':hover:not([data-disabled])', description: 'Pointer over the field. The reference has no hover change; presets with a distinct border-control-hover strengthen the ring.', markup: 'native' },
+        focus: { selector: ':focus-within', description: 'The inset ring turns to the brand color and the 4px brand focus ring appears around the wrapper.', markup: 'native :focus-within on the wrapper' },
+        invalid: { selector: '[data-invalid], &:has([aria-invalid="true"])', description: 'Red-300 ring; on focus the focus ring turns red. Always accompanied by a Field error.', markup: 'aria-invalid="true" on the textarea, or data-invalid on the wrapper' },
+        disabled: { selector: '[data-disabled], &:has(:disabled)', description: 'Whole control at 50% opacity, cursor not-allowed, no resize handle.', markup: 'disabled on the textarea' },
+    },
+    base: {
+        root: {
+            display: 'flex',
+            width: '100%',
+            'min-width': '0',
+            'background-color': '{color.bg-surface}',
+            'border-radius': '{radius.control}',
+            'box-shadow': RING_REST,
+            color: '{color.fg-default}',
+            ...TRANSITION_FAST,
+        },
+        field: {
+            display: 'block',
+            flex: '1 1 auto',
+            width: '100%',
+            'min-width': '0',
+            margin: '0',
+            border: '0',
+            outline: 'none',
+            background: 'transparent',
+            'box-shadow': 'none',
+            'border-radius': '{radius.control}',
+            ...typeStyle('body-md'),
+            color: 'inherit',
+            resize: 'vertical',
+            'scroll-padding-block': '{space.3}',
+        },
+        '@states': {
+            hover: { root: { 'box-shadow': RING_HOVER } },
+            focus: { root: { 'box-shadow': RING_FOCUS } },
+            invalid: { root: { 'box-shadow': RING_INVALID } },
+            disabled: { root: { opacity: '{opacity.disabled}', cursor: 'not-allowed' }, field: { cursor: 'not-allowed', resize: 'none' } },
+        },
+    },
+    variants: {
+        size: { sm: sizeBlock('sm'), md: sizeBlock('md'), lg: sizeBlock('lg') },
+        resize: {
+            none: { field: { resize: 'none' } },
+            vertical: { field: { resize: 'vertical' } },
+        },
+    },
+    extraCss: `
+.cn-textarea .cn-textarea__field::placeholder { color: {color.fg-placeholder}; opacity: 1; }
+.cn-textarea .cn-textarea__field:-webkit-autofill { border-radius: {radius.control}; -webkit-text-fill-color: {color.fg-default}; }
+.cn-textarea:has([aria-invalid="true"]):focus-within, .cn-textarea[data-invalid]:focus-within { box-shadow: ${RING_INVALID_FOCUS}; }`,
+    examples: [
+        ex('Default', ta('placeholder="Describe the change for the release notes…" aria-label="Description"'), 'Three rows, 12×14px padding, gray-300 ring and shadow-xs, radius 8.'),
+        ex('With content', ta('aria-label="Notes"', 'Daniel Costa asked for the onboarding checklist to be split by role. Maya Chen will draft the designer track before the Friday review.'), 'The wrapper grows with rows; drag the corner to make it taller.'),
+        ex('Sizes', `<div style="display:flex;flex-direction:column;gap:var(--cn-space-4)">${ta('placeholder="Small · 12px padding, 14px text" aria-label="Small"', '', 'sm', 'vertical', 'max-width:480px')}${ta('placeholder="Medium · 12×14px padding, 14px text" aria-label="Medium"', '', 'md')}${ta('placeholder="Large · 12×14px padding, 16px text" aria-label="Large"', '', 'lg')}</div>`, 'sm 12px all round; md and lg 12px vertical, 14px horizontal. Text is 16px on lg.'),
+        ex('Fixed height', ta('placeholder="Internal note (not visible to the client)" aria-label="Internal note"', '', 'sm', 'none', 'max-width:360px'), 'resize="none" hides the handle for strict layouts.'),
+        ex('Invalid', ta('aria-invalid="true" aria-label="Description" aria-describedby="ta-err"', 'ok'), 'Red-300 ring. Pair with a Field error such as "Write at least 40 characters".'),
+        ex('Disabled', ta('disabled aria-label="Terms"', 'Standard terms apply to this workspace and cannot be edited after the plan is signed.'), 'Same fill and ring at 50% opacity; no resize handle.'),
+    ],
+    recipes: [
+        ex('With character count', `<div class="cn-field" data-layout="vertical" data-size="md" style="max-width:480px"><label class="cn-field__label" for="ta-bio">Public description</label><div class="cn-field__control"><div class="cn-textarea" data-size="md" data-resize="vertical"><textarea class="cn-textarea__field" id="ta-bio" rows="3" maxlength="240" aria-describedby="ta-bio-helper">Lumen helps product teams turn research into decisions: interviews, notes and evidence in one workspace.</textarea></div></div><p class="cn-field__helper" id="ta-bio-helper" style="display:flex;justify-content:space-between;gap:var(--cn-space-3)"><span>Shown on your public profile.</span><span class="cn-tabular">109 / 240</span></p></div>`, 'The count lives in the Field hint, right-aligned, tabular numerals. Turn it to fg-danger only when the limit is exceeded.'),
+    ],
+    rules: [
+        'Start at 3 rows (rows="3"); use 4–6 only for the primary text of a screen (a message composer). Never taller than the viewport.',
+        'Vertical resize only. Horizontal resize breaks the layout; disable resize entirely (resize="none") when the height is a design constraint.',
+        'Always inside a Field with a visible label. Use the hint for the limit and the tone expected ("Visible to the client").',
+        'Width comes from the layout (100% of the Field). Set max-width on the Field, never a fixed width on the wrapper.',
+        'Show a character count only when there is a hard limit, as "109 / 240" in the hint. Do not block typing at the limit; mark the field invalid.',
+        'Sizes match the Inputs around it: md in forms, sm in side panels and comment threads, lg on marketing and auth screens.',
+    ],
+    a11y: [
+        'Every textarea has an accessible name: a <label for> from the Field, or aria-label when standalone.',
+        'aria-invalid="true" and aria-describedby pointing to the Field error id when invalid.',
+        'Keep the native resize handle keyboard-independent: the height must never be required to read the content (the textarea scrolls).',
+        'A character limit is announced through the hint text; do not rely on maxlength alone.',
+    ],
+    related: ['input', 'field', 'select'],
+};

package/lib/components/timeline.mjs

@@ -0,0 +1,135 @@
+import { ex, typeStyle } from "./_shared.mjs";
+// the reference activity feed: events down a 2px gray-200 line, an 8px dot (or a 32px avatar)
+// per event, a 14px semibold ink title, a 12px gray-500 time and 14px gray-600 detail; the
+// current event pulses in brand, completed events are green, failures red.
+const RING = '0 0 0 1.5px {color.bg-surface}';
+const SILHOUETTE = "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Crect width='64' height='64' fill='%23CDCED1'/%3E%3Ccircle cx='32' cy='25' r='11' fill='%23FAFAFA'/%3E%3Cpath d='M10 64c2-13 11-21 22-21s20 8 22 21z' fill='%23FAFAFA'/%3E%3C/svg%3E";
+const event = (time, title, description, extra = '', avatar = '') => `<li class="cn-timeline__item"${extra}>${avatar ? `<span class="cn-timeline__avatar cn-avatar" data-size="sm" data-shape="circle" data-tone="neutral" data-status="none" aria-hidden="true"><img class="cn-avatar__image" src="${SILHOUETTE}" alt=""></span>` : '<span class="cn-timeline__marker" aria-hidden="true"></span>'}<span class="cn-timeline__line" aria-hidden="true"></span><time class="cn-timeline__time" datetime="2026-09-11">${time}</time><span class="cn-timeline__title">${title}</span>${description ? `<span class="cn-timeline__description">${description}</span>` : ''}</li>`;
+const RELEASE = [
+    event('Sep 8 · 09:12', 'Release branch created', 'v2.4.0 cut from main by Daniel Costa.', ' data-state="complete"'),
+    event('Sep 8 · 09:40', '12 pull requests merged', '8 features, 4 fixes.', ' data-state="complete"'),
+    event('Sep 9 · 14:05', 'Staging deploy approved', 'Sofia Almeida signed off on the design review.', ' data-state="complete"'),
+    event('Sep 11 · 08:31', 'Production rollout in progress', '25% of workspaces migrated; no errors so far.', ' data-state="current"'),
+].join('');
+export const timeline = {
+    name: 'Timeline',
+    slug: 'timeline',
+    category: 'data-display',
+    description: 'Events in order down a thin vertical line: an 8px dot (or a 32px avatar) per event, a 12px timestamp, a 14px semibold title and a muted note. The current event pulses in brand; completed events are green; failures are red.',
+    usage: 'Activity of one thing over time: a release, a conversation, an order, a support ticket. For a multi-step process the user walks through use Stepper; for a list of records use List.',
+    anatomy: [
+        { part: 'root', element: 'ol', description: 'Ordered list of events, oldest first (or newest first for activity feeds; be consistent per screen).' },
+        { part: 'item', element: 'li', description: 'One event. Relative, left padding for the marker. data-state="complete|current" and data-tone="danger" color the marker.' },
+        { part: 'marker', element: 'span', description: '8px dot on the line with a 1.5px surface ring. Gray-300 by default; green when complete, brand (pulsing) when current, red for failures.' },
+        { part: 'avatar', element: 'span', description: 'Optional 32px Avatar in place of the dot (an Avatar root that also carries this class) for activity by a person; the line runs behind it.', optional: true },
+        { part: 'line', element: 'span', description: '2px gray-200 rule from this marker to the next. Hidden on the last item.' },
+        { part: 'time', element: 'time', description: 'When it happened, 12px medium fg-subtle. Use a <time datetime>. Relative ("2h ago") or absolute, consistent per screen.' },
+        { part: 'title', element: 'span', description: 'What happened, 14px semibold in ink, past tense ("Staging deploy approved").' },
+        { part: 'description', element: 'span', description: 'Optional one or two lines of detail, 14px fg-muted.', optional: true },
+    ],
+    props: {
+        size: { values: ['sm', 'md'], default: 'md', description: 'md = 14px titles with 20px between events (detail pages, drawers); sm = 12px titles and time, tighter spacing (side panels, cards).' },
+        variant: {
+            values: ['default', 'compact'],
+            default: 'default',
+            description: 'default = time above the title, each event a small block; compact = time inline after the title on one line, description under it, for dense activity feeds.',
+        },
+    },
+    states: {
+        complete: { selector: ' > [data-state="complete"]', description: 'On an item, not the root: the marker is green.', markup: 'data-state="complete" on the item' },
+        current: { selector: ' > [data-state="current"]', description: 'On an item: brand marker with a soft pulsing halo; the title is semibold brand.', markup: 'data-state="current" on the item (at most one per timeline)' },
+        danger: { selector: ' > [data-tone="danger"]', description: 'On an item: red marker and title for a failure (bounce, rejection, error).', markup: 'data-tone="danger" on the item' },
+    },
+    base: {
+        root: { display: 'flex', 'flex-direction': 'column', position: 'relative', margin: '0', padding: '0', 'list-style': 'none', 'min-width': '0', color: '{color.fg-default}' },
+        item: {
+            position: 'relative',
+            display: 'flex',
+            'flex-direction': 'column',
+            gap: '{space.0.5}',
+            'padding-inline-start': '{space.6}',
+            'padding-bottom': '{space.5}',
+            'min-width': '0',
+        },
+        marker: {
+            position: 'absolute',
+            left: '0',
+            top: '{space.1.5}',
+            width: '{space.2}',
+            height: '{space.2}',
+            'border-radius': '{radius.full}',
+            'background-color': '{color.border-control}',
+            'box-shadow': RING,
+            'z-index': '{z.raised}',
+        },
+        avatar: { position: 'absolute', left: 'calc({space.4} * -1 + {space.1})', top: '0', 'z-index': '{z.raised}', 'box-shadow': RING },
+        line: {
+            position: 'absolute',
+            left: '3px',
+            top: '{space.4}',
+            bottom: 'calc({space.1} * -1)',
+            width: '{border.width.medium}',
+            'border-radius': '{radius.full}',
+            'background-color': '{color.border-default}',
+        },
+        time: { ...typeStyle('label-xs'), color: '{color.fg-subtle}', 'white-space': 'nowrap', 'font-variant-numeric': 'tabular-nums' },
+        title: { ...typeStyle('label-md'), color: '{color.fg-default}' },
+        description: { ...typeStyle('body-md'), color: '{color.fg-muted}' },
+    },
+    variants: {
+        size: {
+            sm: { item: { 'padding-bottom': '{space.4}', 'padding-inline-start': '{space.5}' }, title: { ...typeStyle('label-sm') }, description: { ...typeStyle('body-sm') }, marker: { top: '{space.1}' } },
+            md: { item: { 'padding-bottom': '{space.5}' } },
+        },
+        variant: {
+            default: { item: {} },
+            compact: {
+                item: { 'flex-direction': 'row', 'flex-wrap': 'wrap', 'align-items': 'baseline', 'column-gap': '{space.2}', 'row-gap': '{space.0.5}', 'padding-bottom': '{space.3}' },
+                time: { order: '1' },
+                description: { 'flex-basis': '100%', order: '2' },
+            },
+        },
+    },
+    compound: [
+        { when: { size: 'sm', variant: 'compact' }, block: { item: { 'padding-bottom': '{space.2}' } } },
+    ],
+    extraCss: `
+.cn-timeline__item:last-child .cn-timeline__line { display: none; }
+.cn-timeline__item:has(> .cn-timeline__avatar) { padding-inline-start: {space.11}; }
+.cn-timeline__item:has(> .cn-timeline__avatar) > .cn-timeline__avatar { left: 0; }
+.cn-timeline__item:has(> .cn-timeline__avatar) > .cn-timeline__line { left: calc({space.4} - {border.width.thin}); top: {space.10}; }
+.cn-timeline__item[data-state="complete"] .cn-timeline__marker { background-color: {color.bg-success}; }
+.cn-timeline__item[data-state="current"] .cn-timeline__marker { background-color: {color.bg-action}; animation: cn-timeline-pulse 2s {motion.easing.standard} infinite; }
+.cn-timeline__item[data-state="current"] .cn-timeline__title { color: {color.fg-action}; }
+.cn-timeline__item[data-tone="danger"] .cn-timeline__marker { background-color: {color.bg-danger}; animation: none; }
+.cn-timeline__item[data-tone="danger"] .cn-timeline__title { color: {color.fg-danger}; }
+@keyframes cn-timeline-pulse {
+  0% { box-shadow: ${RING}, 0 0 0 {border.width.medium} {color.bg-action-subtle}; }
+  70% { box-shadow: ${RING}, 0 0 0 {space.2} transparent; }
+  100% { box-shadow: ${RING}, 0 0 0 {space.2} transparent; }
+}`,
+    examples: [
+        ex('Release activity, current event last', `<ol class="cn-timeline" data-size="md" data-variant="default" style="max-width:480px">${RELEASE}</ol>`, 'Three completed events (green dots), one current (brand, pulsing). 12px time over a 14px semibold title.'),
+        ex('Compact feed with a failure', `<ol class="cn-timeline" data-size="md" data-variant="compact" style="max-width:480px">${event('08:31', 'Rollout resumed', '25% of workspaces migrated.', ' data-state="complete"')}${event('08:02', 'Rollout paused', 'Error rate above 1% in eu-west-1; Aisha Khan is investigating.', ' data-tone="danger"')}${event('Yesterday', 'Staging deploy approved by Sofia Almeida', '', ' data-state="complete"')}${event('Sep 9', '12 pull requests merged', '', ' data-state="complete"')}</ol>`, 'Time inline after the title; danger tone on the failure.'),
+        ex('With avatars (activity by people)', `<ol class="cn-timeline" data-size="md" data-variant="default" style="max-width:480px">${event('2h ago', 'Maya Chen changed the due date', 'From Sep 12 to Sep 19.', '', 'MC')}${event('Yesterday', 'Daniel Costa commented', '“Ready for review once the API is deployed.”', '', 'DC')}${event('Sep 8', 'Sofia Almeida attached 2 files', 'Brand guidelines.pdf, Q3 roadmap.xlsx', '', 'SA')}</ol>`, 'A 32px Avatar replaces the dot; the 2px line runs between avatars.'),
+        ex('Small, in a side panel', `<ol class="cn-timeline" data-size="sm" data-variant="default" style="max-width:320px">${event('Sep 11', 'Production rollout in progress', '25% of workspaces migrated.', ' data-state="current"')}${event('Sep 9', 'Staging deploy approved', '', ' data-state="complete"')}${event('Sep 8', 'Release branch created', '', ' data-state="complete"')}</ol>`, 'Newest first is fine for feeds; be consistent per screen.'),
+    ],
+    rules: [
+        'Titles are short past-tense facts ("Staging deploy approved", "12 pull requests merged"), sentence case, no trailing period.',
+        'Timestamps use a <time datetime> element in 12px medium; pick relative or absolute per screen and keep it consistent across all events.',
+        'At most one data-state="current" per timeline; it is the only pulsing element on the page.',
+        'Marker colors mean state: gray = happened, green = completed step, brand = happening now, red = failed. Never other colors.',
+        'Use the avatar marker when the event is something a person did; the dot when it is something the system did. One marker style per timeline.',
+        'Descriptions are one or two lines of detail; anything longer (a message body) links to the record.',
+        'Keep one direction per screen: oldest first for a process, newest first for an activity feed.',
+        'Do not put buttons or badges inside events; the timeline reports, the surface acts. A link inside the description is fine.',
+        'Long timelines collapse older events behind a "Show 12 earlier events" link Button; do not render hundreds of events.',
+    ],
+    a11y: [
+        'Use <ol> and <li> so the order and count are announced; the marker, avatar and line are aria-hidden decoration.',
+        'State must be in the text, not only in the marker color: the title or description says "failed", "approved", "in progress".',
+        'The pulse animation stops under prefers-reduced-motion (handled by the base stylesheet); the current item still stands out by color and weight.',
+        '<time datetime> carries the machine-readable date so relative labels ("2h ago") remain meaningful.',
+    ],
+    related: ['stepper', 'list', 'badge', 'avatar', 'card'],
+};

package/lib/components/toast.mjs

@@ -0,0 +1,115 @@
+import { FOCUS_RING, RESET_BUTTON, TRANSITION_COLORS, STATE, ex, ICON, typeStyle } from "./_shared.mjs";
+const TONE_ICON = {
+    neutral: '{color.fg-muted}',
+    success: '{color.fg-success}',
+    warning: '{color.fg-warning}',
+    danger: '{color.fg-danger}',
+    info: '{color.fg-info}',
+};
+const icon = (name) => ICON[name].replace('cn-icon', 'cn-toast__icon');
+const dismiss = `<button type="button" class="cn-toast__dismiss" aria-label="Dismiss">${ICON.x}</button>`;
+export const toast = {
+    name: 'Toast',
+    slug: 'toast',
+    category: 'feedback',
+    description: 'Short-lived notification panel that slides in at the bottom-right corner: a raised white card with an icon, a title, one line of detail and at most one action. The component styles the panel; the fixed region that stacks toasts is a separate class.',
+    usage: 'Use to confirm something the user just did ("Draft saved", "Invite sent") or to report a background event that needs no decision. Not for errors the user must act on (use Alert in place, or Dialog) and not for information that must persist (use Banner).',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'The panel. 360px wide, raised surface, shadow-lg. role="status"; data-state="open|closed".' },
+        { part: 'icon', element: 'svg', description: '16px icon in the tone color, top-aligned with the title. Decorative.', optional: true },
+        { part: 'content', element: 'div', description: 'Title + description + action. Flexes to fill.' },
+        { part: 'title', element: 'div', description: 'label-md, one line: what happened ("Invite sent").' },
+        { part: 'description', element: 'p', description: 'body-sm muted, one line of detail (who, when, how many).', optional: true },
+        { part: 'action', element: 'div', description: 'One link or ghost Button (size sm) under the description: "Undo", "View".', optional: true },
+        { part: 'dismiss', element: 'button', description: '24px ghost icon button with an X in the top-right corner. aria-label="Dismiss".', optional: true },
+    ],
+    props: {
+        tone: {
+            values: ['neutral', 'success', 'warning', 'danger', 'info'],
+            default: 'neutral',
+            description: 'Only the icon color changes; the panel stays white. neutral = plain confirmation; success = a completed action; warning = something to look at later; danger = a background failure that needs no immediate decision; info = a heads-up.',
+        },
+    },
+    states: {
+        open: STATE.open(),
+        closed: { selector: '[data-state="closed"]', description: 'Removed from view (display none) after the auto-dismiss timer or the dismiss button.', markup: 'data-state="closed"' },
+        dismissHover: { selector: ' .cn-toast__dismiss:hover', description: 'Pointer over the dismiss button: subtle fill. Styled in extraCss because it lives on a child.', markup: 'native :hover on .cn-toast__dismiss' },
+        dismissFocus: { selector: ' .cn-toast__dismiss:focus-visible', description: 'Keyboard focus on the dismiss button shows the focus ring. Styled in extraCss.', markup: 'native :focus-visible on .cn-toast__dismiss' },
+    },
+    base: {
+        root: {
+            display: 'flex',
+            'align-items': 'flex-start',
+            gap: '{space.3}',
+            width: '360px',
+            'max-width': '100%',
+            padding: '{space.3} {space.4}',
+            'background-color': '{color.bg-surface-raised}',
+            border: '{border.width.thin} solid {color.border-default}',
+            'border-radius': '{radius.lg}',
+            'box-shadow': '{shadow.lg}',
+            color: '{color.fg-default}',
+            ...typeStyle('body-sm'),
+        },
+        icon: { width: '{size.icon.md}', height: '{size.icon.md}', 'flex-shrink': '0', 'margin-top': '1px', color: '{color.fg-muted}' },
+        content: { flex: '1 1 auto', 'min-width': '0' },
+        title: { ...typeStyle('label-md'), 'line-height': '{font.lineHeight.snug}' },
+        description: { ...typeStyle('body-sm'), color: '{color.fg-muted}', 'margin-top': '{space.1}' },
+        action: { display: 'flex', 'align-items': 'center', gap: '{space.2}', 'margin-top': '{space.2}' },
+        dismiss: {
+            ...RESET_BUTTON,
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            width: '{size.icon.xl}',
+            height: '{size.icon.xl}',
+            'margin-block': 'calc({space.1} * -1)',
+            'margin-inline-end': 'calc({space.1} * -1)',
+            'border-radius': '{radius.md}',
+            color: '{color.fg-subtle}',
+            ...TRANSITION_COLORS,
+        },
+        '@states': {
+            open: { root: { animation: 'cn-toast-enter {motion.duration.slow} {motion.easing.out} both' } },
+            closed: { root: { display: 'none' } },
+        },
+    },
+    variants: {
+        tone: Object.fromEntries(Object.entries(TONE_ICON).map(([t, color]) => [t, { icon: { color } }])),
+    },
+    extraCss: `
+.cn-toast-region { position: fixed; bottom: {space.6}; right: {space.6}; display: flex; flex-direction: column; gap: {space.2}; z-index: {z.toast}; pointer-events: none; }
+.cn-toast-region > .cn-toast { pointer-events: auto; }
+@keyframes cn-toast-enter { from { opacity: 0; transform: translateY(8px); } to { opacity: 1; transform: translateY(0); } }
+.cn-toast .cn-toast__dismiss .cn-icon { width: {size.icon.sm}; height: {size.icon.sm}; }
+.cn-toast .cn-toast__dismiss:hover { background-color: {color.bg-subtle}; color: {color.fg-default}; }
+.cn-toast .cn-toast__dismiss:focus-visible { outline: none; box-shadow: ${FOCUS_RING['box-shadow']}; }`,
+    examples: [
+        ex('Neutral', `<div class="cn-toast" data-tone="neutral" data-state="open" role="status">${icon('info')}<div class="cn-toast__content"><div class="cn-toast__title">Draft saved</div><p class="cn-toast__description">Reply to Nakamura Trading Co. · 2 seconds ago</p></div>${dismiss}</div>`),
+        ex('Success with action', `<div class="cn-toast" data-tone="success" data-state="open" role="status">${icon('check')}<div class="cn-toast__content"><div class="cn-toast__title">Invite sent to Hoffmann GmbH</div><p class="cn-toast__description">They will receive it within a minute.</p><div class="cn-toast__action"><button type="button" class="cn-button" data-variant="link" data-size="sm"><span class="cn-button__label">Undo</span></button></div></div>${dismiss}</div>`),
+        ex('Warning', `<div class="cn-toast" data-tone="warning" data-state="open" role="status">${icon('warning')}<div class="cn-toast__content"><div class="cn-toast__title">4 prospects skipped</div><p class="cn-toast__description">No verified email found. They stay in the list as “unreachable”.</p></div>${dismiss}</div>`),
+        ex('Danger (background failure)', `<div class="cn-toast" data-tone="danger" data-state="open" role="status">${icon('warning')}<div class="cn-toast__content"><div class="cn-toast__title">Export failed</div><p class="cn-toast__description">The file was not generated. Try again from the Export menu.</p><div class="cn-toast__action"><button type="button" class="cn-button" data-variant="ghost" data-size="sm"><span class="cn-button__label">Retry</span></button></div></div>${dismiss}</div>`),
+        ex('Info', `<div class="cn-toast" data-tone="info" data-state="open" role="status">${icon('info')}<div class="cn-toast__content"><div class="cn-toast__title">Nightly refresh finished</div><p class="cn-toast__description">37 new companies in Japan and South Korea.</p><div class="cn-toast__action"><button type="button" class="cn-button" data-variant="link" data-size="sm"><span class="cn-button__label">View</span></button></div></div>${dismiss}</div>`),
+    ],
+    recipes: [
+        ex('Stack of two (static)', `<div style="display:flex;flex-direction:column;gap:var(--cn-space-2)"><div class="cn-toast" data-tone="success" data-state="open" role="status">${icon('check')}<div class="cn-toast__content"><div class="cn-toast__title">Shortlist exported</div><p class="cn-toast__description">prospects-japan.xlsx · 1.2 MB</p></div>${dismiss}</div><div class="cn-toast" data-tone="neutral" data-state="open" role="status">${icon('info')}<div class="cn-toast__content"><div class="cn-toast__title">Agent paused</div><p class="cn-toast__description">Outreach resumes at 08:00 in the buyer’s timezone.</p></div>${dismiss}</div></div>`, 'In the app the same markup lives inside .cn-toast-region (fixed, bottom-right). Newest at the bottom.'),
+    ],
+    rules: [
+        'Toasts auto-dismiss after 5 seconds (8 seconds when they carry an action). Hovering pauses the timer.',
+        'At most 3 toasts visible; the oldest leaves when a fourth arrives.',
+        'Never use a toast for an error that needs a decision. If the user must act, show an Alert next to the thing or a Dialog.',
+        'Title is 2–5 words in past tense ("Invite sent"); description is one line with the concrete object, count or time.',
+        'At most one action, variant link or ghost, size sm. "Undo" is the most valuable action a toast can offer.',
+        'Render toasts inside .cn-toast-region (fixed, bottom-right, z toast). The panel itself is never position: fixed.',
+        'The panel stays white in every tone; only the icon changes color. No tinted toasts.',
+        'Enter animation is translateY(8px) → 0 with opacity, 260ms; leaving is opacity only. Both disappear under prefers-reduced-motion.',
+    ],
+    a11y: [
+        'role="status" on the panel (polite); use aria-live="assertive" on the region only for danger toasts.',
+        'The region is aria-label="Notifications"; toasts never steal focus when they appear.',
+        'The dismiss button has aria-label="Dismiss"; Escape dismisses the most recent toast when a toast has focus.',
+        'Pause the auto-dismiss timer while the toast or its action has focus or the pointer.',
+    ],
+    related: ['alert', 'banner', 'dialog', 'button'],
+};

package/lib/components/tooltip.mjs

@@ -0,0 +1,86 @@
+import { STATE, ex, typeStyle } from "./_shared.mjs";
+export const tooltip = {
+    name: 'Tooltip',
+    slug: 'tooltip',
+    category: 'overlays',
+    description: 'Small inverse-colored label that names or explains a control on hover and focus. One short sentence, a 6px arrow toward the trigger, nothing interactive inside.',
+    usage: 'Use to name icon-only buttons and to add a hint to truncated values or abbreviations. Not for content the user needs to act on or copy (use Popover), not for long explanations (use helper text), and not as the only place a label lives on touch devices.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'The panel. role="tooltip", id referenced by the trigger’s aria-describedby. Positioned by the app; the component styles it in place.' },
+        { part: 'arrow', element: 'span', description: '6px square rotated 45°, same background as the panel, placed on the edge facing the trigger according to data-side.', optional: true },
+    ],
+    props: {
+        side: {
+            values: ['top', 'right', 'bottom', 'left'],
+            default: 'top',
+            description: 'Which side of the trigger the tooltip sits on; only moves the arrow. top is the default; use bottom under a topbar, left/right next to a sidebar.',
+        },
+    },
+    states: {
+        open: STATE.open(),
+        closed: { selector: '[data-state="closed"]', description: 'Hidden. The panel is removed from view (display none).', markup: 'data-state="closed"' },
+    },
+    base: {
+        root: {
+            position: 'relative',
+            display: 'inline-block',
+            width: 'max-content',
+            'max-width': '240px',
+            padding: '{space.1.5} {space.2}',
+            'background-color': '{color.bg-inverse}',
+            color: '{color.fg-inverse}',
+            'border-radius': '{radius.md}',
+            'box-shadow': '{shadow.md}',
+            ...typeStyle('body-xs'),
+            'z-index': '{z.tooltip}',
+            'pointer-events': 'none',
+        },
+        arrow: {
+            position: 'absolute',
+            width: '6px',
+            height: '6px',
+            'background-color': '{color.bg-inverse}',
+            transform: 'rotate(45deg)',
+        },
+        '@states': {
+            open: { root: { animation: 'cn-tooltip-enter {motion.duration.fast} {motion.easing.standard} both' } },
+            closed: { root: { display: 'none' } },
+        },
+    },
+    variants: {
+        side: {
+            top: { arrow: { bottom: '-3px', left: 'calc(50% - 3px)' } },
+            bottom: { arrow: { top: '-3px', left: 'calc(50% - 3px)' } },
+            left: { arrow: { right: '-3px', top: 'calc(50% - 3px)' } },
+            right: { arrow: { left: '-3px', top: 'calc(50% - 3px)' } },
+        },
+    },
+    extraCss: `
+@keyframes cn-tooltip-enter { from { opacity: 0; } to { opacity: 1; } }`,
+    examples: [
+        ex('Top (default)', `<div class="cn-tooltip" data-side="top" data-state="open" role="tooltip" id="tip-archive">Archive this prospect<span class="cn-tooltip__arrow"></span></div>`),
+        ex('Bottom', `<div class="cn-tooltip" data-side="bottom" data-state="open" role="tooltip" id="tip-refresh">Refreshed nightly at 02:00 UTC<span class="cn-tooltip__arrow"></span></div>`),
+        ex('Left', `<div class="cn-tooltip" data-side="left" data-state="open" role="tooltip" id="tip-verified">Verified with 3 public sources<span class="cn-tooltip__arrow"></span></div>`),
+        ex('Right, wrapping at 240px', `<div class="cn-tooltip" data-side="right" data-state="open" role="tooltip" id="tip-score">Fit score combines trade volume, product match and reply history.<span class="cn-tooltip__arrow"></span></div>`),
+    ],
+    recipes: [
+        ex('Icon button with its tooltip (static)', `<div style="display:inline-flex;flex-direction:column;align-items:center;gap:var(--cn-space-1)"><div class="cn-tooltip" data-side="top" data-state="open" role="tooltip" id="tip-copy">Copy company ID<span class="cn-tooltip__arrow"></span></div><button type="button" class="cn-button" data-variant="outline" data-size="sm" aria-describedby="tip-copy"><span class="cn-button__label">Copy</span></button></div>`, 'The trigger points to the tooltip with aria-describedby; the tooltip never contains the trigger’s label alone if the button has visible text.'),
+    ],
+    rules: [
+        'Text only, at most one sentence, no period at the end unless it is two sentences (then it is too long).',
+        'Never put links, buttons or inputs inside a tooltip. If it must be clicked, it is a Popover.',
+        'Show after a 300ms hover delay and immediately on keyboard focus; hide on pointer leave, blur or Escape.',
+        'Tooltips are not the only label on touch: every icon-only control also has aria-label, and mobile-only elements do not rely on tooltips at all.',
+        'Prefer side="top". Use bottom under a fixed topbar and left/right for controls at the screen edge. Let the positioning library flip when there is no room.',
+        'Max width 240px; wrapping is fine, scrolling is not.',
+        'The panel is inverse-colored in both themes (dark on light, light on dark); never tone it.',
+        'Do not show a tooltip that repeats the visible label of a text button.',
+    ],
+    a11y: [
+        'role="tooltip" on the panel and aria-describedby on the trigger pointing to its id.',
+        'Opens on focus as well as hover; a control that can be hovered must be reachable by keyboard.',
+        'Escape closes it and returns nothing else; focus never moves into the tooltip.',
+        'Inverse colors keep AA contrast in both themes; body-xs is the minimum size, never smaller.',
+    ],
+    related: ['popover', 'icon-button', 'button'],
+};