canon-ds 0.1.0

package/lib/components/media-frame.mjs

@@ -0,0 +1,119 @@
+import { ex, typeStyle } from "./_shared.mjs";
+/** Inline SVG placeholder: neutral fill with one diagonal line, 16:9. */
+const PLACEHOLDER = `<svg class="cn-media-frame__media" viewBox="0 0 160 90" preserveAspectRatio="xMidYMid slice" role="img" aria-label="Placeholder image"><rect width="160" height="90" fill="var(--cn-color-bg-muted)"/><path d="M0 90L160 0" stroke="var(--cn-color-border-strong)" stroke-width="1"/></svg>`;
+export const mediaFrame = {
+    name: 'MediaFrame',
+    slug: 'media-frame',
+    category: 'media',
+    description: 'A figure that holds an image or video at a fixed aspect ratio: a clipping frame with a subtle fill, an optional hairline, an optional flat text overlay, and a caption below. The frame clips; the figure does not, so captions never get cut.',
+    usage: 'Use for every image or video in the product: company logos in cards, screenshots in help articles, thumbnails in lists, a video in an empty state. Never place a raw <img> in a layout; the frame guarantees the ratio, the loading placeholder and the radius.',
+    anatomy: [
+        { part: 'root', element: 'figure', description: 'The figure. Sets width; overflow visible so the caption sits below. data-ratio / data-radius / data-fit, optional data-bordered, data-state="loading".' },
+        { part: 'frame', element: 'div', description: 'The clipping box: aspect-ratio, radius, subtle fill, overflow hidden. Holds media and overlay.' },
+        { part: 'media', element: 'img', description: 'The <img>, <video> or inline <svg>. Fills the frame; object-fit from data-fit. Always has alt (or aria-label for svg).' },
+        { part: 'overlay', element: 'div', description: 'Optional flat scrim over the media with inverse text at the bottom-left: a title, a duration, a label. No gradient.', optional: true },
+        { part: 'caption', element: 'figcaption', description: 'body-xs muted line under the frame: source, date, what the image shows.', optional: true },
+    ],
+    props: {
+        ratio: {
+            values: ['auto', '1:1', '4:3', '3:2', '16:9'],
+            default: '16:9',
+            description: 'Aspect ratio of the frame. auto = the media’s own height (logos, inline illustrations); 1:1 = avatars, product shots; 4:3 = documents and screenshots; 3:2 = photos; 16:9 = video and hero thumbnails (default).',
+        },
+        radius: {
+            values: ['none', 'md', 'xl', '2xl'],
+            default: 'xl',
+            description: 'Corner radius of the frame. none = full-bleed inside a card with padding none; md = small thumbnails in rows; xl = default for cards and articles; 2xl = hero media on marketing pages.',
+        },
+        fit: {
+            values: ['cover', 'contain'],
+            default: 'cover',
+            description: 'cover = fills the frame and crops (photos, screenshots); contain = shows the whole media on the subtle fill (logos, diagrams).',
+        },
+    },
+    states: {
+        loading: { selector: '[data-state="loading"]', description: 'Media not yet available: the frame shows the skeleton shimmer and the media is hidden.', markup: 'data-state="loading" on the figure' },
+        bordered: { selector: '[data-bordered]', description: 'Adds the default hairline around the frame, for light media on white surfaces (logos, screenshots).', markup: 'data-bordered attribute on the figure' },
+    },
+    base: {
+        root: { display: 'block', width: '100%', 'min-width': '0', margin: '0', overflow: 'visible' },
+        frame: {
+            position: 'relative',
+            width: '100%',
+            'aspect-ratio': '16 / 9',
+            'background-color': '{color.bg-subtle}',
+            'border-radius': '{radius.xl}',
+            border: '{border.width.thin} solid transparent',
+            overflow: 'hidden',
+        },
+        media: { display: 'block', width: '100%', height: '100%', 'object-fit': 'cover' },
+        overlay: {
+            position: 'absolute',
+            inset: '0',
+            display: 'flex',
+            'flex-direction': 'column',
+            'justify-content': 'flex-end',
+            padding: '{space.4}',
+            'background-color': '{color.bg-overlay}',
+            color: '{color.fg-inverse}',
+            ...typeStyle('label-md'),
+        },
+        caption: { ...typeStyle('body-xs'), color: '{color.fg-muted}', padding: '{space.2} 0 0' },
+        '@states': {
+            loading: {
+                frame: {
+                    'background-image': 'linear-gradient(90deg, {color.bg-muted} 0%, {color.bg-subtle} 50%, {color.bg-muted} 100%)',
+                    'background-size': '200% 100%',
+                    animation: 'cn-media-frame-shimmer 1.4s ease-in-out infinite',
+                },
+                media: { visibility: 'hidden' },
+            },
+            bordered: { frame: { 'border-color': '{color.border-default}' } },
+        },
+    },
+    variants: {
+        ratio: {
+            auto: { frame: { 'aspect-ratio': 'auto' }, media: { height: 'auto' } },
+            '1:1': { frame: { 'aspect-ratio': '1 / 1' } },
+            '4:3': { frame: { 'aspect-ratio': '4 / 3' } },
+            '3:2': { frame: { 'aspect-ratio': '3 / 2' } },
+            '16:9': { frame: { 'aspect-ratio': '16 / 9' } },
+        },
+        radius: {
+            none: { frame: { 'border-radius': '{radius.none}' } },
+            md: { frame: { 'border-radius': '{radius.md}' } },
+            xl: { frame: { 'border-radius': '{radius.xl}' } },
+            '2xl': { frame: { 'border-radius': '{radius.2xl}' } },
+        },
+        fit: {
+            cover: { media: { 'object-fit': 'cover' } },
+            contain: { media: { 'object-fit': 'contain', padding: '{space.4}' } },
+        },
+    },
+    extraCss: `
+@keyframes cn-media-frame-shimmer { from { background-position: 200% 0; } to { background-position: -200% 0; } }`,
+    examples: [
+        ex('Default (16:9, radius xl, cover)', `<figure class="cn-media-frame" data-ratio="16:9" data-radius="xl" data-fit="cover" style="width:320px"><div class="cn-media-frame__frame">${PLACEHOLDER}</div><figcaption class="cn-media-frame__caption">Osaka port, container terminal · Photo: Nakamura Trading Co.</figcaption></figure>`),
+        ex('Square thumbnail, bordered, radius md', `<figure class="cn-media-frame" data-ratio="1:1" data-radius="md" data-fit="contain" data-bordered style="width:96px"><div class="cn-media-frame__frame">${PLACEHOLDER.replace('preserveAspectRatio="xMidYMid slice"', 'preserveAspectRatio="xMidYMid meet"')}</div></figure>`, 'contain keeps logos whole on the subtle fill; the hairline separates light logos from a white card.'),
+        ex('4:3 with overlay', `<figure class="cn-media-frame" data-ratio="4:3" data-radius="xl" data-fit="cover" style="width:280px"><div class="cn-media-frame__frame">${PLACEHOLDER}<div class="cn-media-frame__overlay">How agents verify a company · 3:40</div></div></figure>`, 'The overlay is a flat scrim with inverse text; no gradient.'),
+        ex('Loading', `<figure class="cn-media-frame" data-ratio="3:2" data-radius="xl" data-fit="cover" data-state="loading" style="width:240px" aria-busy="true"><div class="cn-media-frame__frame">${PLACEHOLDER}</div><figcaption class="cn-media-frame__caption">Loading preview…</figcaption></figure>`),
+        ex('Auto ratio, no radius (full bleed)', `<figure class="cn-media-frame" data-ratio="auto" data-radius="none" data-fit="cover" style="width:320px"><div class="cn-media-frame__frame"><svg class="cn-media-frame__media" viewBox="0 0 160 40" role="img" aria-label="Placeholder banner"><rect width="160" height="40" fill="var(--cn-color-bg-muted)"/><path d="M0 40L160 0" stroke="var(--cn-color-border-strong)" stroke-width="1"/></svg></div></figure>`, 'auto takes the media’s own height. Use inside a Card with padding none.'),
+    ],
+    rules: [
+        'Every image and video in the product lives in a MediaFrame; a raw <img> in a layout is a lint error.',
+        'Pick the ratio from the content, not the space: 1:1 logos and avatars, 4:3 screenshots, 3:2 photos, 16:9 video. Do not stretch a screenshot into 16:9.',
+        'Width comes from the layout (100% of its column); set it inline only in isolated thumbnails.',
+        'Logos and diagrams use fit="contain" and data-bordered; photos use cover without a border.',
+        'The overlay is flat (bg-overlay) with one line of label-md inverse text at the bottom-left. No gradients, no blur, no second line.',
+        'Captions are body-xs muted, one line, below the frame: source, date, or what the picture shows. They are not titles.',
+        'Radius matches the container: md in rows, xl in cards, 2xl on marketing heroes, none when the media bleeds to the card edge.',
+        'Show data-state="loading" only for network images; inline SVGs render immediately.',
+    ],
+    a11y: [
+        'Every <img> has alt text that says what it shows; decorative images use alt="" and the figure gets no caption.',
+        'Inline SVG media uses role="img" with aria-label; videos have captions or a transcript.',
+        'The figcaption is the accessible description; do not repeat the alt text in it.',
+        'Overlay text keeps AA contrast on the scrim (inverse text on bg-overlay); never place text over unscrimmed media.',
+    ],
+    related: ['card', 'skeleton', 'avatar'],
+};

package/lib/components/menu.mjs

@@ -0,0 +1,190 @@
+import { STATE, ex, ICON, typeStyle } from "./_shared.mjs";
+// the reference dropdown: a 248px white panel, radius 8, 1px ring + shadow-lg, 4px vertical
+// padding; items 36px tall (padding 8 × 10 inside a 6px gutter, radius 6, 14px medium gray-700),
+// 16px gray-400 icons 8px before the label, 12px gray-500 shortcut on the right, gray-200
+// separators 4px apart, gray-50 when highlighted, red for destructive, 50% when disabled.
+const TRANSITION_FAST = {
+    'transition-property': 'background-color, color, box-shadow',
+    'transition-duration': '{motion.duration.fast}',
+    'transition-timing-function': '{motion.easing.linear}',
+};
+const HAIRLINE = '{border.width.thin} solid {color.border-default}';
+const icon = (name) => ICON[name].replace('cn-icon', 'cn-menu__icon');
+const CHECK = ICON.check.replace('cn-icon', 'cn-menu__check');
+const item = (label, i = null, shortcut = '', attrs = '') => `<button type="button" role="menuitem" class="cn-menu__item"${attrs}>${i ? icon(i) : ''}<span class="cn-menu__text">${label}</span>${shortcut ? `<kbd class="cn-menu__shortcut">${shortcut}</kbd>` : ''}</button>`;
+const check = (role, label, checked, attrs = '') => `<div role="${role}" tabindex="-1" aria-checked="${checked}" class="cn-menu__item"${attrs}>${CHECK}<span class="cn-menu__text">${label}</span></div>`;
+const SEP = '<div class="cn-menu__separator" role="separator"></div>';
+const label = (id, text) => `<div class="cn-menu__label" id="${id}">${text}</div>`;
+const AVATAR_SRC = "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 64 64'%3E%3Crect width='64' height='64' fill='%23CDCED1'/%3E%3Ccircle cx='32' cy='25' r='11' fill='%23FAFAFA'/%3E%3Cpath d='M10 64c2-13 11-21 22-21s20 8 22 21z' fill='%23FAFAFA'/%3E%3C/svg%3E";
+const person = (name, checked = false) => `<div role="menuitemradio" tabindex="-1" aria-checked="${checked}" class="cn-menu__item"><img class="cn-menu__avatar" src="${AVATAR_SRC}" alt=""><span class="cn-menu__text">${name}</span>${CHECK}</div>`;
+const HEADER = `<div class="cn-menu__header cn-avatar-label-group" data-size="md"><span class="cn-avatar" data-size="md" data-shape="circle" data-tone="neutral" data-status="online" role="img" aria-label="Maya Chen, online"><span class="cn-avatar__fallback" aria-hidden="true">MC</span><span class="cn-avatar__status"></span></span><div class="cn-avatar-label-group__text"><span class="cn-avatar-label-group__name">Maya Chen</span><span class="cn-avatar-label-group__email">maya@lumen.co</span></div></div>`;
+export const menu = {
+    name: 'Menu',
+    slug: 'menu',
+    category: 'overlays',
+    description: 'The dropdown panel of the reference: a 248px raised white surface (radius 8, hairline ring, shadow-lg) of 36px items with 16px icons, right-aligned shortcuts, gray-200 separators, section labels, an optional account-card header and a destructive last item. Styles the panel only; positioning is a separate anchor layer.',
+    usage: 'Use for a short list of actions on one object (row actions, "More" in a card header, the account menu) and for grouped option toggles (sort, view, switch account). Not for navigation (SidebarNav), not for picking a form value (Select / Combobox), not for anything that needs a search field (CommandPalette).',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'The panel: role="menu", 248px wide, bg-surface-raised, gray-200 ring, radius 8, shadow-lg, 4px vertical and 6px horizontal padding. data-state="open|closed".' },
+        { part: 'header', element: 'div', description: 'Optional account card at the top: an Avatar md with the avatar label group (name + email), 12px padding, hairline below; bleeds to the panel edges.', optional: true },
+        { part: 'group', element: 'div', description: 'role="group" wrapping related items, optionally labelled.', optional: true },
+        { part: 'label', element: 'div', description: 'Section heading in 12px semibold fg-subtle, padding 6 × 10 (4 below): "Sort by", "Switch account". Referenced by the group\'s aria-labelledby.', optional: true },
+        { part: 'item', element: 'button', description: 'One action or option: role="menuitem" | "menuitemcheckbox" | "menuitemradio". 36px tall, padding 8 × 10, radius 6, 14px medium gray-700. Holds icon / avatar / check + text + shortcut or chevron.' },
+        { part: 'icon', element: 'svg', description: '16px leading icon, fg-subtle. All items in a group have one, or none do.', optional: true },
+        { part: 'avatar', element: 'img', description: '20px round avatar in the leading slot (account switchers, assignees).', optional: true },
+        { part: 'check', element: 'svg', description: '16px brand check mark of checkbox / radio items, in the leading slot (or trailing after an avatar); invisible until aria-checked="true" so text stays aligned.', optional: true },
+        { part: 'text', element: 'span', description: 'The item label; grows and truncates.', optional: true },
+        { part: 'shortcut', element: 'kbd', description: 'Keyboard shortcut in 12px medium fg-subtle, pushed to the end. Only for shortcuts that really work.', optional: true },
+        { part: 'chevron', element: 'svg', description: '16px chevron-right at the end of an item that opens a submenu.', optional: true },
+        { part: 'separator', element: 'div', description: 'A 1px gray-200 rule bleeding to the panel edges, 4px above and below. role="separator".', optional: true },
+    ],
+    props: {
+        size: {
+            values: ['sm', 'md'],
+            default: 'md',
+            description: 'md = 36px items, 14px medium; the reference. sm = 32px items (padding 6 × 8) for dense table row menus and toolbars.',
+        },
+    },
+    states: {
+        open: STATE.open(),
+        closed: { selector: '[data-state="closed"]', description: 'Hidden. The panel stays in the DOM for focus management but is display: none.', markup: 'data-state="closed"' },
+        highlighted: { selector: ' .cn-menu__item[data-highlighted], & .cn-menu__item:hover', description: 'The item under the pointer or reached by arrow keys (on the ITEM): gray-50 fill, text one step darker.', markup: 'data-highlighted on the item (keyboard) or native :hover' },
+        checked: { selector: ' .cn-menu__item[aria-checked="true"]', description: 'A checkbox / radio item that is on: the brand check mark becomes visible.', markup: 'aria-checked="true" on a role="menuitemcheckbox|menuitemradio" item' },
+        danger: { selector: ' .cn-menu__item[data-danger]', description: 'Destructive action: fg-danger text and icon, danger-subtle fill when highlighted. Always last, after a separator.', markup: 'data-danger on the item' },
+        disabled: { selector: ' .cn-menu__item[aria-disabled="true"]', description: 'Not available now: 50% opacity, cursor not-allowed, no hover. Stays visible and focusable so the user learns it exists.', markup: 'aria-disabled="true" on the item' },
+    },
+    base: {
+        root: {
+            display: 'flex',
+            'flex-direction': 'column',
+            gap: '{space.0.5}',
+            width: 'calc({space.56} + {space.6})',
+            'max-width': '100%',
+            padding: '{space.1} {space.1.5}',
+            'background-color': '{color.bg-surface-raised}',
+            border: HAIRLINE,
+            'border-radius': '{radius.panel}',
+            'box-shadow': '{shadow.lg}',
+            color: '{color.fg-default}',
+            outline: 'none',
+        },
+        header: {
+            display: 'flex',
+            'align-items': 'center',
+            gap: '{space.3}',
+            padding: '{space.3} {space.4}',
+            margin: 'calc({space.1} * -1) calc({space.1.5} * -1) {space.1}',
+            'border-bottom': HAIRLINE,
+            'min-width': '0',
+        },
+        group: { display: 'flex', 'flex-direction': 'column', gap: '{space.0.5}' },
+        label: {
+            ...typeStyle('label-xs'),
+            'font-weight': '{font.weight.semibold}',
+            color: '{color.fg-subtle}',
+            padding: '{space.1.5} {space.2.5} {space.1}',
+            'user-select': 'none',
+        },
+        item: {
+            appearance: 'none',
+            '-webkit-appearance': 'none',
+            border: '0',
+            margin: '0',
+            background: 'none',
+            font: 'inherit',
+            'text-align': 'start',
+            width: '100%',
+            display: 'flex',
+            'align-items': 'center',
+            gap: '{space.2}',
+            'flex-shrink': '0',
+            height: '{space.9}',
+            padding: '{space.2} {space.2.5}',
+            'border-radius': '{radius.md}',
+            ...typeStyle('label-sm'),
+            color: '{color.fg-muted}',
+            'text-decoration': 'none',
+            cursor: 'pointer',
+            'user-select': 'none',
+            'white-space': 'nowrap',
+            outline: 'none',
+            ...TRANSITION_FAST,
+        },
+        icon: { width: '{size.icon.sm}', height: '{size.icon.sm}', 'flex-shrink': '0', color: '{color.fg-subtle}', transition: 'inherit' },
+        avatar: { width: '{size.icon.md}', height: '{size.icon.md}', 'border-radius': '{radius.full}', 'object-fit': 'cover', 'flex-shrink': '0', 'background-color': '{color.bg-muted}', 'max-width': 'none' },
+        check: { width: '{size.icon.sm}', height: '{size.icon.sm}', 'flex-shrink': '0', visibility: 'hidden', color: '{brand.600}' },
+        text: { flex: '1 1 auto', 'min-width': '0', overflow: 'hidden', 'text-overflow': 'ellipsis' },
+        shortcut: {
+            ...typeStyle('label-xs'),
+            color: '{color.fg-subtle}',
+            'margin-inline-start': 'auto',
+            'padding-inline': '{space.1} {space.1}',
+            'flex-shrink': '0',
+        },
+        chevron: { width: '{size.icon.sm}', height: '{size.icon.sm}', 'flex-shrink': '0', 'margin-inline-start': 'auto', color: '{color.fg-subtle}' },
+        separator: {
+            height: '0',
+            'border-top': HAIRLINE,
+            margin: '{space.1} calc({space.1.5} * -1)',
+        },
+        '@states': {
+            open: { root: { display: 'flex' } },
+            closed: { root: { display: 'none' } },
+        },
+    },
+    variants: {
+        size: {
+            sm: {
+                item: { height: '{space.8}', padding: '{space.1.5} {space.2}' },
+                label: { padding: '{space.1} {space.2} {space.1}' },
+            },
+            md: { root: {} },
+        },
+    },
+    extraCss: `
+.cn-menu__item[data-highlighted], .cn-menu__item:hover:not([aria-disabled="true"]), .cn-menu__item:focus-visible { background-color: {color.bg-subtle}; color: {color.fg-default}; }
+.cn-menu__item[data-highlighted] .cn-menu__icon, .cn-menu__item:hover:not([aria-disabled="true"]) .cn-menu__icon { color: {color.fg-muted}; }
+.cn-menu__item:focus-visible { box-shadow: inset 0 0 0 2px {brand.500}; }
+.cn-menu__item[data-danger] { color: {color.fg-danger}; }
+.cn-menu__item[data-danger] .cn-menu__icon { color: {red.500}; }
+.cn-menu__item[data-danger][data-highlighted], .cn-menu__item[data-danger]:hover:not([aria-disabled="true"]), .cn-menu__item[data-danger]:focus-visible { background-color: {color.bg-danger-subtle}; color: {color.fg-danger}; }
+.cn-menu__item[aria-disabled="true"] { opacity: {opacity.disabled}; cursor: not-allowed; }
+.cn-menu__item[aria-checked="true"] .cn-menu__check { visibility: visible; }
+.cn-menu__item > .cn-menu__avatar + .cn-menu__text + .cn-menu__check { margin-inline-start: auto; }
+.cn-menu-anchor { position: relative; display: inline-block; }
+.cn-menu[data-floating] { position: absolute; top: calc(100% + {space.1}); inset-inline-start: 0; z-index: {z.dropdown}; }
+.cn-menu[data-floating][data-align="end"] { inset-inline-start: auto; inset-inline-end: 0; }
+.cn-menu[data-floating][data-side="top"] { top: auto; bottom: calc(100% + {space.1}); }`,
+    examples: [
+        ex('Actions on one object', `<div class="cn-menu" data-size="md" role="menu" aria-label="Project actions" data-state="open">${item('View project', 'external', '↵')}${item('Edit', 'settings', '⌘E')}${item('Duplicate', 'copy', '⌘D')}${item('Move to…', 'arrow')}${SEP}${item('Delete', 'trash', '⌫', ' data-danger')}</div>`, '248px panel; verbs in sentence case, "…" when the item opens a dialog. Delete is last, after a separator, in red.'),
+        ex('Account menu with header', `<div class="cn-menu" data-size="md" role="menu" aria-label="Account" data-state="open">${HEADER}${item('View profile', 'user', '⌘K→P')}${item('Settings', 'settings', '⌘S')}${item('Keyboard shortcuts', 'info', '?')}${SEP}<div class="cn-menu__group" role="group" aria-labelledby="menu-switch">${label('menu-switch', 'Switch account')}${person('Maya Chen', true)}${person('Daniel Costa')}</div>${SEP}${item('Log out', 'external', '⌥⇧Q')}</div>`, 'The header is the account card (Avatar md + name + email); the "Switch account" section uses 20px avatars with the check on the right.'),
+        ex('Grouped options with checks', `<div class="cn-menu" data-size="md" role="menu" aria-label="View options" data-state="open"><div class="cn-menu__group" role="group" aria-labelledby="menu-sort">${label('menu-sort', 'Sort by')}${check('menuitemradio', 'Newest first', true)}${check('menuitemradio', 'Oldest first', false)}${check('menuitemradio', 'Name', false)}</div>${SEP}<div class="cn-menu__group" role="group" aria-labelledby="menu-show">${label('menu-show', 'Show')}${check('menuitemcheckbox', 'Archived projects', true)}${check('menuitemcheckbox', 'Only mine', false)}</div></div>`, 'The brand check occupies the leading slot even when hidden, so labels align.'),
+        ex('Submenu, highlighted and disabled items', `<div class="cn-menu" data-size="md" role="menu" aria-label="Row actions" data-state="open">${item('Assign to…', 'user', '', ' data-highlighted')}<button type="button" role="menuitem" class="cn-menu__item" aria-haspopup="menu" aria-expanded="false">${icon('inbox')}<span class="cn-menu__text">Share</span>${ICON.chevronRight.replace('cn-icon', 'cn-menu__chevron')}</button>${item('Snooze', 'calendar', 'S')}${item('Mark as done', 'check', 'E', ' aria-disabled="true"')}</div>`, 'data-highlighted is what keyboard navigation sets; a submenu item ends in a chevron; disabled items stay visible at 50%.'),
+        ex('Small', `<div class="cn-menu" data-size="sm" role="menu" aria-label="Cell actions" data-state="open">${item('Copy', 'copy', '⌘C')}${item('Paste', 'inbox', '⌘V')}${SEP}${item('Clear', 'trash', '', ' data-danger')}</div>`, '32px items for dense tables.'),
+        ex('Closed (in the DOM, hidden)', `<div class="cn-menu" data-size="md" role="menu" aria-label="Hidden menu" data-state="closed">${item('You should not see this', 'info')}</div><span class="cn-text-body-sm">data-state="closed" renders nothing.</span>`),
+    ],
+    recipes: [
+        ex('Anchored to a trigger', `<div class="cn-menu-anchor" style="min-height:220px"><button type="button" class="cn-icon-button" data-variant="outline" data-size="md" data-shape="square" aria-label="More actions" aria-haspopup="menu" aria-expanded="true" aria-controls="menu-anchored" id="menu-anchored-trigger">${ICON.dots.replace('cn-icon', 'cn-icon-button__icon')}</button><div class="cn-menu" data-size="md" role="menu" id="menu-anchored" aria-labelledby="menu-anchored-trigger" data-state="open" data-floating>${item('Rename', 'settings')}${item('Duplicate', 'copy', '⌘D')}${SEP}${item('Delete', 'trash', '', ' data-danger')}</div></div>`, 'Wrap trigger + panel in .cn-menu-anchor; data-floating positions the panel 4px under the trigger. Add data-align="end" to right-align, data-side="top" to flip.'),
+    ],
+    rules: [
+        'Max 7 items per group and about 12 in total. Beyond that, the object has too many actions; move rare ones into a dialog or a settings page.',
+        'Items are verbs in sentence case ("Duplicate", "Move to…"); "…" when the item opens a dialog. Options (sort, show) are nouns with checks.',
+        'Items are 36px (sm 32) with 14px medium text; icons 16px fg-subtle, all-or-none within a group; shortcuts 12px on the right only when the key really works.',
+        'Destructive actions are last, after a separator, marked data-danger, and always confirm.',
+        'The panel is 248px wide (or wider to fit the trigger when the trigger is a full-width control); never narrower.',
+        'Position with .cn-menu-anchor + data-floating (4px below the trigger, aligned to its start; data-align="end" to align to its end, data-side="top" to flip). One open menu at a time.',
+        'The account header is the only place for an avatar label group inside a menu; items use 20px avatars.',
+        'No submenus deeper than one level; the chevron item opens a second panel to the side.',
+        'Disabled items stay visible with aria-disabled and explain themselves in a Tooltip; hiding them makes the menu feel unstable.',
+        'The panel styles only; put backdrop, focus trap and scroll lock in the app layer, never in the component.',
+    ],
+    a11y: [
+        'Root has role="menu" and aria-labelledby pointing at the trigger (or aria-label). The trigger has aria-haspopup="menu", aria-expanded and aria-controls.',
+        'Items are role="menuitem", "menuitemcheckbox" or "menuitemradio" with aria-checked; groups are role="group" with aria-labelledby; separators are role="separator".',
+        'Keyboard: Down/Up move highlight (wrapping), Home/End jump, Enter/Space activate, Right opens a submenu, Esc closes and returns focus to the trigger, typing jumps to a matching item.',
+        'Only one item is tabbable (roving tabindex); highlight is set with data-highlighted and reflected by aria-activedescendant or focus.',
+        'Disabled items use aria-disabled="true" and remain focusable so they can be announced; never the disabled attribute.',
+        'Avatars inside items are decorative (alt=""); the text names the person.',
+    ],
+    related: ['icon-button', 'button-group', 'command-palette', 'popover', 'select', 'avatar'],
+};

package/lib/components/message.mjs

@@ -0,0 +1,249 @@
+import { FOCUS_RING, TRANSITION_COLORS, ex, typeStyle } from "./_shared.mjs";
+// Chat messaging: a thread of bubbles (incoming on the left in bg-subtle, outgoing
+// on the right in the action color), each with a name + time line, optional file or
+// image attachment inside the bubble, a three-dot typing indicator and a composer
+// with a toolbar and a primary Send button.
+const HAIRLINE = '{border.width.thin} solid {color.border-control}';
+const SVG = {
+    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>',
+    clip: '<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="M10.5 5.5l-4.25 4.25a1.5 1.5 0 002.12 2.12L13 7.25a2.83 2.83 0 00-4-4L4.25 8a4.24 4.24 0 006 6l3.25-3.25"/></svg>',
+    smile: '<svg class="cn-icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" aria-hidden="true"><circle cx="8" cy="8" r="6"/><path d="M5.5 9.5s.9 1.5 2.5 1.5 2.5-1.5 2.5-1.5M6 6.25v.5M10 6.25v.5"/></svg>',
+    mic: '<svg class="cn-icon" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" aria-hidden="true"><rect x="6" y="2.5" width="4" height="7" rx="2"/><path d="M4 8a4 4 0 008 0M8 12v1.5"/></svg>',
+    send: '<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="M2.5 8l11-5.5-3 11-2.5-4.5L2.5 8z"/><path d="M8 9L13.5 2.5"/></svg>',
+};
+/** Muted 4:3 picture so the image attachment renders without the network. */
+const PICTURE = `<svg viewBox="0 0 320 240" role="img" aria-label="Photo of the new office lobby"><rect width="320" height="240" style="fill:var(--cn-color-bg-muted)"/><circle cx="236" cy="70" r="28" style="fill:var(--cn-color-bg-surface)"/><path d="M0 200L84 116l64 56 52-70 120 98v40H0z" style="fill:var(--cn-color-border-strong)"/></svg>`;
+const iconBtn = (svg, label) => `<button type="button" class="cn-icon-button" data-variant="ghost" data-size="sm" data-shape="square" aria-label="${label}">${svg.replace('cn-icon', 'cn-icon-button__icon')}</button>`;
+const avatar = (initials, name) => `<span class="cn-message__avatar" role="img" aria-label="${name}">${initials}</span>`;
+const msg = (o) => `<div class="cn-message__item" data-direction="${o.dir}">${o.dir === 'in' && o.initials ? avatar(o.initials, o.name) : ''}<div class="cn-message__content"><div class="cn-message__meta"><span class="cn-message__name">${o.name}</span><time class="cn-message__time" datetime="${o.datetime}">${o.time}</time></div><div class="cn-message__bubble">${o.body}</div></div></div>`;
+const fileCard = (name, meta) => `<a href="#" class="cn-message__attachment"><span class="cn-message__attachment-icon" aria-hidden="true">${SVG.file}</span><span><span class="cn-message__attachment-name">${name}</span><span class="cn-message__attachment-meta">${meta}</span></span></a>`;
+const typing = (initials, name) => `<div class="cn-message__item" data-direction="in">${avatar(initials, name)}<div class="cn-message__content"><div class="cn-message__typing" role="status" aria-label="${name} is typing"><span class="cn-message__dot"></span><span class="cn-message__dot"></span><span class="cn-message__dot"></span></div></div></div>`;
+const divider = (text) => `<div class="cn-message__date-divider" role="separator">${text}</div>`;
+const COMPOSER = `<div class="cn-message__composer"><textarea class="cn-message__composer-input" rows="2" placeholder="Message Maya Chen…" aria-label="Message"></textarea><div class="cn-message__composer-toolbar"><div class="cn-message__composer-tools">${iconBtn(SVG.clip, 'Attach a file')}${iconBtn(SVG.smile, 'Add emoji')}${iconBtn(SVG.mic, 'Record a voice note')}</div><button type="button" class="cn-button" data-variant="primary" data-size="sm"><span class="cn-button__label">Send</span>${SVG.send.replace('cn-icon', 'cn-button__icon')}</button></div></div>`;
+const thread = (variant, density, inner, width = '560px') => `<div class="cn-message" data-variant="${variant}" data-density="${density}" role="log" aria-label="Conversation with Maya Chen" style="width:100%;max-width:${width}">${inner}</div>`;
+export const message = {
+    name: 'Message',
+    slug: 'message',
+    category: 'data-display',
+    description: 'Chat messages in a thread: incoming bubbles on the left in bg-subtle, outgoing on the right in the action color, each with a name and time line, a 32px avatar, optional file or image attachments, a three-dot typing indicator, centered date chips and a composer with a toolbar and a primary Send.',
+    usage: 'Use for two-way conversations in real time: support chat, a thread with a teammate, the transcript of an agent conversation. For a comment stream on a document use ActivityFeed; for a timeline of events use Timeline; for one-off notifications use Notification.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'The thread (role="log"): a flex column of items and date dividers with a 16px gap. Width comes from the layout.' },
+        { part: 'date-divider', element: 'div', description: 'Centered chip that separates days ("Today", "Sep 9"). role="separator".', optional: true },
+        { part: 'item', element: 'div', description: 'One message: avatar + content in a row. data-direction="in" (received, left) or "out" (sent, right, mirrored).' },
+        { part: 'avatar', element: 'span', description: '32px circle with initials (24px in compact), aligned to the bottom of the bubble. Only on incoming messages; role="img" + aria-label.', optional: true },
+        { part: 'content', element: 'div', description: 'Column with the meta line and the bubble, aligned to the start (in) or the end (out).' },
+        { part: 'meta', element: 'div', description: 'Name and time on one line above the bubble.' },
+        { part: 'name', element: 'span', description: 'Sender name, label-sm ("Maya Chen", "You").' },
+        { part: 'time', element: 'time', description: 'Sent time, body-xs fg-subtle, a <time datetime>.' },
+        { part: 'bubble', element: 'div', description: 'The message body, max 70% of the thread width, 10/14px padding, 16/24 text, radius 8 with the corner nearest the sender squared. Holds text and optional attachments.' },
+        { part: 'attachment', element: 'a', description: 'A file card (icon + name + meta) or, with data-kind="image", a picture, inside the bubble. Links to the file.', optional: true },
+        { part: 'attachment-icon', element: 'span', description: '32px square with a 16px file icon.', optional: true },
+        { part: 'attachment-name', element: 'span', description: 'File name, label-sm, truncated.', optional: true },
+        { part: 'attachment-meta', element: 'span', description: 'Size or type under the name, body-xs, muted.', optional: true },
+        { part: 'typing', element: 'div', description: 'Three animated dots in an incoming-style bubble. role="status" with "{Name} is typing".', optional: true },
+        { part: 'dot', element: 'span', description: 'One 6px dot of the typing indicator; the three dots bounce in sequence.', optional: true },
+        { part: 'composer', element: 'div', description: 'The reply box: hairline border, radius card, focus ring on :focus-within. Holds the textarea and the toolbar.', optional: true },
+        { part: 'composer-input', element: 'textarea', description: 'Bare <textarea>, two rows, no border; grows with content in the app.', optional: true },
+        { part: 'composer-toolbar', element: 'div', description: 'Bottom row of the composer: tool icon buttons on the left, the primary sm Send on the right.', optional: true },
+        { part: 'composer-tools', element: 'div', description: 'The group of ghost IconButtons (attach, emoji, voice) that fills the toolbar\'s left side.', optional: true },
+    ],
+    props: {
+        variant: {
+            values: ['thread', 'composer', 'bubble'],
+            default: 'thread',
+            description: 'thread = the full conversation column with dividers, messages, typing and optionally a composer at the end. composer = the root holds only the reply box (a chat that lives elsewhere, a "quick reply" footer). bubble = the root holds a single message, for embedding one quoted message in another surface.',
+        },
+        density: {
+            values: ['default', 'compact'],
+            default: 'default',
+            description: 'default = 32px avatars, 16/24 text, 16px between messages (full-page chat). compact = 24px avatars, 14px text, 8px between messages, for side panels and support widgets.',
+        },
+    },
+    states: {
+        incoming: { selector: ' .cn-message__item[data-direction="in"]', description: 'A received message (on the item): avatar on the left, bg-subtle bubble with the top-left corner squared. Styled in extraCss.', markup: 'data-direction="in" on .cn-message__item' },
+        outgoing: { selector: ' .cn-message__item[data-direction="out"]', description: 'A sent message (on the item): mirrored to the right, action-colored bubble with the top-right corner squared, no avatar. Styled in extraCss.', markup: 'data-direction="out" on .cn-message__item' },
+        composerFocus: { selector: ' .cn-message__composer:focus-within', description: 'Typing in the composer: the border turns action-colored and the 3px ring appears (extraCss).', markup: 'native :focus-within on .cn-message__composer' },
+        composerDisabled: { selector: ' .cn-message__composer[data-disabled]', description: 'The conversation is closed or read-only: grey fill, muted text, textarea disabled (extraCss).', markup: 'data-disabled on .cn-message__composer plus disabled on the textarea' },
+    },
+    base: {
+        root: { display: 'flex', 'flex-direction': 'column', gap: '{space.4}', width: '100%', 'min-width': '0', color: '{color.fg-default}' },
+        'date-divider': {
+            'align-self': 'center',
+            display: 'inline-flex',
+            'align-items': 'center',
+            height: '{space.6}',
+            'padding-inline': '{space.2.5}',
+            'border-radius': '{radius.full}',
+            'background-color': '{color.bg-subtle}',
+            ...typeStyle('label-xs'),
+            color: '{color.fg-subtle}',
+            'user-select': 'none',
+        },
+        item: { display: 'flex', 'align-items': 'flex-end', gap: '{space.2}', 'max-width': '100%', 'min-width': '0' },
+        avatar: {
+            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',
+        },
+        content: { flex: '1 1 auto', 'min-width': '0', display: 'flex', 'flex-direction': 'column', 'align-items': 'flex-start', gap: '{space.1.5}' },
+        meta: { display: 'flex', 'align-items': 'baseline', gap: '{space.2}', 'padding-inline': '{space.1}' },
+        name: { ...typeStyle('label-sm'), 'line-height': '{font.lineHeight.normal}', color: '{color.fg-default}' },
+        time: { ...typeStyle('body-xs'), color: '{color.fg-subtle}', 'white-space': 'nowrap' },
+        bubble: {
+            display: 'flex',
+            'flex-direction': 'column',
+            gap: '{space.2}',
+            'max-width': '70%',
+            padding: '{space.2.5} {space.3.5}',
+            ...typeStyle('body-lg'),
+            'line-height': '{font.lineHeight.normal}',
+            'border-radius': '{radius.lg}',
+            'background-color': '{color.bg-subtle}',
+            color: '{color.fg-default}',
+            'overflow-wrap': 'anywhere',
+        },
+        attachment: {
+            display: 'flex',
+            'align-items': 'center',
+            gap: '{space.3}',
+            'min-width': '0',
+            padding: '{space.2.5} {space.3}',
+            'border-radius': '{radius.md}',
+            'background-color': '{color.bg-surface}',
+            border: '{border.width.thin} solid {color.border-default}',
+            color: 'inherit',
+            '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': { display: 'block', ...typeStyle('label-sm'), 'line-height': '{font.lineHeight.normal}', 'min-width': '0', overflow: 'hidden', 'text-overflow': 'ellipsis', 'white-space': 'nowrap' },
+        'attachment-meta': { display: 'block', ...typeStyle('body-xs'), opacity: '{opacity.muted}' },
+        typing: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            gap: '{space.1}',
+            padding: '{space.3.5} {space.3.5}',
+            'border-radius': '{radius.lg}',
+            'border-start-start-radius': '{radius.none}',
+            'background-color': '{color.bg-subtle}',
+            'align-self': 'flex-start',
+        },
+        dot: { width: '6px', height: '6px', 'border-radius': '{radius.full}', 'background-color': '{color.fg-subtle}', animation: 'cn-message-typing 1.2s {motion.easing.standard} infinite' },
+        composer: {
+            display: 'flex',
+            'flex-direction': 'column',
+            width: '100%',
+            'min-width': '0',
+            'background-color': '{color.bg-surface}',
+            border: HAIRLINE,
+            'border-radius': '{radius.card}',
+            'box-shadow': '{shadow.xs}',
+            overflow: 'hidden',
+            ...TRANSITION_COLORS,
+        },
+        'composer-input': {
+            display: 'block',
+            width: '100%',
+            'min-height': 'calc(2 * {font.size.md} * {font.lineHeight.normal} + 2 * {space.3})',
+            margin: '0',
+            padding: '{space.3} {space.3.5}',
+            border: '0',
+            outline: 'none',
+            background: 'transparent',
+            ...typeStyle('body-md'),
+            color: 'inherit',
+            resize: 'none',
+        },
+        'composer-toolbar': { display: 'flex', 'align-items': 'center', gap: '{space.2}', padding: '0 {space.2} {space.2} {space.2}' },
+        'composer-tools': { display: 'flex', 'align-items': 'center', gap: '{space.0.5}', flex: '1 1 auto', 'min-width': '0' },
+    },
+    variants: {
+        variant: {
+            thread: { root: {} },
+            composer: { root: { gap: '0' } },
+            bubble: { root: { gap: '0' } },
+        },
+        density: {
+            default: { root: {} },
+            compact: {
+                root: { gap: '{space.2}' },
+                item: { gap: '{space.1.5}' },
+                avatar: { width: '{space.6}', height: '{space.6}', 'font-size': '{font.size.2xs}' },
+                bubble: { padding: '{space.2} {space.3}', ...typeStyle('body-md') },
+                meta: { gap: '{space.1.5}' },
+                typing: { padding: '{space.2.5} {space.3}' },
+                'composer-input': { 'min-height': 'calc(1 * {font.size.md} * {font.lineHeight.normal} + 2 * {space.2.5})', padding: '{space.2.5} {space.3}' },
+            },
+        },
+    },
+    extraCss: `
+.cn-message__item[data-direction="in"] .cn-message__bubble { border-start-start-radius: {radius.none}; }
+.cn-message__item[data-direction="out"] { flex-direction: row-reverse; }
+.cn-message__item[data-direction="out"] .cn-message__content { align-items: flex-end; }
+.cn-message__item[data-direction="out"] .cn-message__meta { flex-direction: row-reverse; }
+.cn-message__item[data-direction="out"] .cn-message__bubble { background-color: {color.bg-action}; color: {color.fg-on-action}; border-start-end-radius: {radius.none}; }
+.cn-message__item[data-direction="out"] .cn-message__attachment { background-color: color-mix(in srgb, {color.fg-on-action} 12%, transparent); border-color: color-mix(in srgb, {color.fg-on-action} 24%, transparent); }
+.cn-message__item[data-direction="out"] .cn-message__attachment-icon { background-color: color-mix(in srgb, {color.fg-on-action} 16%, transparent); color: inherit; }
+.cn-message__attachment:hover { border-color: {color.border-control-hover}; }
+.cn-message__attachment > span:last-child { min-width: 0; flex: 1 1 auto; }
+.cn-message__attachment:focus-visible { outline: none; box-shadow: ${FOCUS_RING['box-shadow']}; }
+.cn-message__attachment-icon .cn-icon { width: {size.icon.md}; height: {size.icon.md}; }
+.cn-message__attachment[data-kind="image"] { display: block; padding: 0; border: 0; overflow: hidden; border-radius: {radius.md}; max-width: 320px; }
+.cn-message__attachment[data-kind="image"] > svg, .cn-message__attachment[data-kind="image"] > img { display: block; width: 100%; height: auto; }
+.cn-message__dot:nth-child(2) { animation-delay: 0.2s; }
+.cn-message__dot:nth-child(3) { animation-delay: 0.4s; }
+@keyframes cn-message-typing { 0%, 60%, 100% { transform: translateY(0); opacity: {opacity.disabled}; } 30% { transform: translateY(-3px); opacity: 1; } }
+.cn-message__composer:focus-within { border-color: {color.border-action}; box-shadow: ${FOCUS_RING['box-shadow']}; }
+.cn-message__composer-input::placeholder { color: {color.fg-placeholder}; opacity: 1; }
+.cn-message__composer[data-disabled] { background-color: {color.bg-disabled}; color: {color.fg-disabled}; border-color: {color.border-disabled}; box-shadow: none; }
+.cn-message__composer[data-disabled] .cn-message__composer-input { cursor: not-allowed; }`,
+    examples: [
+        ex('Thread with an attachment and typing', thread('thread', 'default', [
+            divider('Today'),
+            msg({ dir: 'in', name: 'Maya Chen', initials: 'MC', time: '09:12', datetime: '2026-09-11T09:12', body: 'Morning! Did the Q3 launch plan land in your inbox?' }),
+            msg({ dir: 'out', name: 'You', time: '09:14', datetime: '2026-09-11T09:14', body: 'It did — reading it now. Two questions about the pricing page.' }),
+            msg({ dir: 'in', name: 'Maya Chen', initials: 'MC', time: '09:16', datetime: '2026-09-11T09:16', body: `Here is the latest deck, the pricing slides start on page 12.${fileCard('q3-launch-plan-v4.pdf', 'PDF · 2.4 MB')}` }),
+            msg({ dir: 'out', name: 'You', time: '09:20', datetime: '2026-09-11T09:20', body: 'Perfect, thanks. I will leave comments before lunch.' }),
+            typing('MC', 'Maya Chen'),
+        ].join('')), 'Received on the left with an avatar, sent on the right in the action color. The typing indicator is an incoming bubble with three bouncing dots.'),
+        ex('Composer', thread('composer', 'default', COMPOSER), 'Attach, emoji and voice as ghost IconButtons; Send is the only primary button. Enter sends, Shift+Enter adds a line.'),
+        ex('Single bubble', thread('bubble', 'default', msg({ dir: 'in', name: 'Daniel Costa', initials: 'DC', time: 'Yesterday · 17:40', datetime: '2026-09-10T17:40', body: 'Reminder: the brand review moved to Thursday at 10:00.' }), '480px'), 'One message embedded in another surface (a notification, a quoted reply).'),
+        ex('Image attachment, compact density', thread('thread', 'compact', [
+            msg({ dir: 'out', name: 'You', time: '12:02', datetime: '2026-09-11T12:02', body: `The lobby signage went up this morning.<a href="#" class="cn-message__attachment" data-kind="image" aria-label="Open photo">${PICTURE}</a>` }),
+            msg({ dir: 'in', name: 'Sofia Almeida', initials: 'SA', time: '12:05', datetime: '2026-09-11T12:05', body: 'Looks great in daylight. Can you send the night shot too?' }),
+            msg({ dir: 'out', name: 'You', time: '12:06', datetime: '2026-09-11T12:06', body: 'On it.' }),
+        ].join(''), '420px'), 'compact = 24px avatars, 14px text, 8px between messages, for side panels and widgets.'),
+        ex('Disabled composer', thread('composer', 'default', COMPOSER.replace('class="cn-message__composer"', 'class="cn-message__composer" data-disabled').replace('rows="2" placeholder="Message Maya Chen…"', 'rows="2" disabled placeholder="This conversation is closed"')), 'A closed conversation keeps the composer visible but disabled, with the reason as placeholder.'),
+    ],
+    rules: [
+        'Incoming on the left with an avatar, outgoing on the right without one. Never color-code people; direction is the only distinction.',
+        'Bubbles are at most 70% of the thread width and wrap text; never a fixed width, never a scrollbar inside a bubble.',
+        'Every message shows the sender and a time. Group consecutive messages from the same sender within 5 minutes under one meta line.',
+        'Date dividers between days only ("Today", "Yesterday", "Sep 9"); never a divider between every message.',
+        'Attachments live inside the bubble: a file card for documents, a picture (max 320px wide, radius md) for images. One attachment per bubble; more than one becomes a list.',
+        'The typing indicator shows for one person at a time and disappears after 5 seconds of silence; it is never shown for the current user.',
+        'The composer is the only bordered surface in the thread; tools are ghost IconButtons and Send is a primary sm Button. Enter sends, Shift+Enter breaks the line.',
+        'Compact density only in side panels and widgets narrower than 480px.',
+        'Long threads load older messages above with a "Load earlier messages" link Button; keep the newest message and the composer in view.',
+    ],
+    a11y: [
+        'Root is role="log" with an aria-label naming the conversation; new messages are appended so screen readers announce them politely.',
+        'Each message exposes sender and time as text in DOM order before the body; the direction mirroring is CSS-only.',
+        'Avatars with initials use role="img" + aria-label; sent messages have no avatar and say "You" in the name.',
+        'The typing indicator is role="status" with an aria-label such as "Maya Chen is typing"; the dots are decorative.',
+        'The composer textarea has an accessible name, tool buttons have aria-labels, and the Send button is a real <button>; Escape clears a draft only after a confirm.',
+    ],
+    related: ['activity-feed', 'avatar', 'textarea', 'icon-button', 'button', 'notification'],
+};