canon-ds 0.1.0

package/lib/components/featured-card.mjs

@@ -0,0 +1,124 @@
+import { FOCUS_RING, RESET_BUTTON, TRANSITION_COLORS, ex, ICON, typeStyle } from "./_shared.mjs";
+// Featured card: the small promo / usage card at the bottom of a sidebar: a
+// bg-subtle card with a label-sm title, a body-sm description, an optional 8px
+// progress bar or 16:9 image, a ghost "Dismiss" + link "Upgrade plan" row and a
+// 20px × in the corner.
+const IMAGE = `<svg viewBox="0 0 320 180" role="img" aria-label="Lumen on a phone"><rect width="320" height="180" style="fill:var(--cn-color-bg-muted)"/><rect x="118" y="20" width="84" height="176" rx="14" style="fill:var(--cn-color-bg-surface)"/><rect x="128" y="36" width="64" height="8" rx="4" style="fill:var(--cn-color-border-strong)"/><rect x="128" y="52" width="40" height="6" rx="3" style="fill:var(--cn-color-border-default)"/><rect x="128" y="72" width="64" height="44" rx="6" style="fill:var(--cn-color-bg-subtle)"/><path d="M134 106l14-12 12 8 12-16 20 12" fill="none" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round" style="stroke:var(--cn-color-bg-action)"/><rect x="128" y="126" width="64" height="10" rx="5" style="fill:var(--cn-color-bg-action)"/></svg>`;
+const DISMISS = `<button type="button" class="cn-featured-card__dismiss" aria-label="Dismiss">${ICON.x}</button>`;
+const actions = (secondary, primary) => `<div class="cn-featured-card__actions"><button type="button" class="cn-button" data-variant="ghost" data-size="sm"><span class="cn-button__label">${secondary}</span></button><button type="button" class="cn-button" data-variant="link-color" data-size="sm"><span class="cn-button__label">${primary}</span></button></div>`;
+const progress = (pct, label) => `<div class="cn-featured-card__progress" role="progressbar" aria-label="${label}" aria-valuemin="0" aria-valuemax="100" aria-valuenow="${pct}"><div class="cn-featured-card__progress-fill" style="width:${pct}%"></div></div>`;
+const card = (variant, tone, inner) => `<div class="cn-featured-card" data-variant="${variant}" data-tone="${tone}" role="complementary" aria-label="Sidebar notice" style="width:100%;max-width:264px">${inner}</div>`;
+export const featuredCard = {
+    name: 'FeaturedCard',
+    slug: 'featured-card',
+    category: 'feedback',
+    description: 'The small promo or usage card at the bottom of a sidebar: a bg-subtle card with a label-sm title, body-sm muted description, an optional 8px progress bar or 16:9 image, a ghost "Dismiss" and a link-color action, and a 20px × in the corner.',
+    usage: 'Use for one gentle nudge that lives in navigation: plan usage, a trial countdown, a new app or feature, an invite prompt. One per sidebar, always dismissible. For page-level messages use Banner or Alert; for a row inside content use InlineCta.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'The card: bg-subtle, radius card, 16px padding, flex column with 12px gaps, relative for the × button. 264px wide in a sidebar.' },
+        { part: 'title', element: 'div', description: 'label-sm title, one line, with room on the right for the ×.' },
+        { part: 'description', element: 'p', description: 'body-sm muted, one to three lines. Includes the number when there is one ("80% of 10 GB used").' },
+        { part: 'progress', element: 'div', description: '8px track (bg-muted, radius full) for usage and countdowns. role="progressbar".', optional: true },
+        { part: 'progress-fill', element: 'div', description: 'The action-colored fill; width is the inline percentage.', optional: true },
+        { part: 'media', element: 'div', description: '16:9 image slot with radius md above the actions (announcements).', optional: true },
+        { part: 'actions', element: 'div', description: 'Row of two sm Buttons: ghost "Dismiss" first, link-color action last.', optional: true },
+        { part: 'dismiss', element: 'button', description: '24px hit area with a 20px × in the top-right corner. aria-label "Dismiss".', optional: true },
+    ],
+    props: {
+        variant: {
+            values: ['progress', 'image', 'text'],
+            default: 'progress',
+            description: 'progress = title, description and an 8px bar (storage used, seats, trial days left). image = title, description and a 16:9 picture (a new app, a feature launch). text = title and description only (invite your team, complete your profile).',
+        },
+        tone: {
+            values: ['neutral', 'brand'],
+            default: 'neutral',
+            description: 'neutral = bg-subtle card, the everyday usage card. brand = bg-action-subtle with an action-colored title for the one promotional card (upgrade, trial). Never two brand cards in a sidebar.',
+        },
+    },
+    states: {
+        dismissHover: { selector: ' .cn-featured-card__dismiss:hover', description: 'Pointer over the × (extraCss): muted fill, ink icon.', markup: 'native :hover on .cn-featured-card__dismiss' },
+        dismissFocus: { selector: ' .cn-featured-card__dismiss:focus-visible', description: 'Keyboard focus on the × shows the focus ring (extraCss).', markup: 'native :focus-visible on .cn-featured-card__dismiss' },
+    },
+    base: {
+        root: {
+            position: 'relative',
+            display: 'flex',
+            'flex-direction': 'column',
+            gap: '{space.3}',
+            width: '100%',
+            'min-width': '0',
+            padding: '{space.4}',
+            'background-color': '{color.bg-subtle}',
+            'border-radius': '{radius.card}',
+            color: '{color.fg-default}',
+        },
+        title: { ...typeStyle('label-sm'), 'line-height': '{font.lineHeight.normal}', color: '{color.fg-default}', 'padding-inline-end': '{space.6}' },
+        description: { ...typeStyle('body-sm'), color: '{color.fg-muted}', 'margin-top': 'calc(-1 * {space.2})' },
+        progress: { width: '100%', height: '{space.2}', 'border-radius': '{radius.full}', 'background-color': '{color.bg-muted}', overflow: 'hidden' },
+        'progress-fill': { height: '100%', width: '0', 'border-radius': '{radius.full}', 'background-color': '{color.bg-action}', 'transition-property': 'width', 'transition-duration': '{motion.duration.slow}', 'transition-timing-function': '{motion.easing.standard}' },
+        media: { display: 'block', width: '100%', 'aspect-ratio': '16 / 9', 'border-radius': '{radius.md}', overflow: 'hidden', 'background-color': '{color.bg-muted}' },
+        actions: { display: 'flex', 'align-items': 'center', gap: '{space.3}' },
+        dismiss: {
+            ...RESET_BUTTON,
+            position: 'absolute',
+            top: '{space.3}',
+            'inset-inline-end': '{space.3}',
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            width: '{space.6}',
+            height: '{space.6}',
+            'border-radius': '{radius.sm}',
+            color: '{color.fg-subtle}',
+            ...TRANSITION_COLORS,
+        },
+    },
+    variants: {
+        variant: {
+            progress: { root: {} },
+            image: { root: {} },
+            text: { root: {} },
+        },
+        tone: {
+            neutral: { root: { 'background-color': '{color.bg-subtle}' } },
+            brand: {
+                root: { 'background-color': '{color.bg-action-subtle}' },
+                title: { color: '{color.fg-action}' },
+                progress: { 'background-color': 'color-mix(in srgb, {color.bg-action} 16%, transparent)' },
+                dismiss: { color: '{color.fg-action}' },
+            },
+        },
+    },
+    extraCss: `
+.cn-featured-card__dismiss .cn-icon { width: {size.icon.lg}; height: {size.icon.lg}; }
+.cn-featured-card__dismiss:hover { background-color: {color.bg-muted}; color: {color.fg-default}; }
+.cn-featured-card__dismiss:focus-visible { outline: none; box-shadow: ${FOCUS_RING['box-shadow']}; }
+.cn-featured-card[data-tone="brand"] .cn-featured-card__dismiss:hover { background-color: color-mix(in srgb, {color.bg-action} 16%, transparent); }
+.cn-featured-card__media > svg, .cn-featured-card__media > img { display: block; width: 100%; height: 100%; object-fit: cover; }
+.cn-featured-card__actions > .cn-button[data-variant="ghost"]:first-child { margin-inline-start: calc(-1 * {size.controlPadding.sm}); }`,
+    examples: [
+        ex('Usage with progress', card('progress', 'neutral', `<div class="cn-featured-card__title">Used space</div><p class="cn-featured-card__description">Your team has used 80% of the available space. Need more?</p>${progress(80, 'Storage used')}${actions('Dismiss', 'Upgrade plan')}${DISMISS}`), 'The bottom-of-sidebar usage card: number in the text, bar below, two quiet actions.'),
+        ex('Announcement with image, brand tone', card('image', 'brand', `<div class="cn-featured-card__title">Lumen for iOS is here</div><p class="cn-featured-card__description">Approve requests and reply to comments from your phone.</p><div class="cn-featured-card__media">${IMAGE}</div>${actions('Dismiss', 'Get the app')}${DISMISS}`), 'One brand-toned card per sidebar; the image is 16:9 with radius md.'),
+        ex('Text only', card('text', 'neutral', `<div class="cn-featured-card__title">Invite your team</div><p class="cn-featured-card__description">Lumen works better together. Add teammates to share dashboards and approvals.</p>${actions('Dismiss', 'Send invites')}${DISMISS}`), 'A nudge with no bar or picture.'),
+        ex('Trial countdown, brand tone', card('progress', 'brand', `<div class="cn-featured-card__title">Trial ends in 4 days</div><p class="cn-featured-card__description">10 of 14 days used. Keep your dashboards by choosing a plan.</p>${progress(71, 'Trial days used')}${actions('Dismiss', 'Choose a plan')}${DISMISS}`), 'Countdowns use the progress variant with the days in the description.'),
+    ],
+    rules: [
+        'One featured card per sidebar, always at the bottom above the account card, always dismissible.',
+        'Title in label-sm, one line, sentence case; description at most three lines and includes the number ("80% of 10 GB used").',
+        'Exactly two actions: a ghost sm "Dismiss" first and one link-color sm action last. Never a primary button in the sidebar.',
+        'The × dismisses for this session; the "Dismiss" button dismisses for good. Do not show the card again within 30 days.',
+        'Progress fills with the action color and warns in the text, not by turning red; the sidebar is not the place for alarms.',
+        'brand tone only for the one promotional card (upgrade, trial); usage and housekeeping cards are neutral.',
+        'Images are 16:9, radius md, illustrative; never a screenshot with text small enough to need reading.',
+        'Do not stack a FeaturedCard with a Banner about the same thing; pick the surface closest to where the action happens.',
+    ],
+    a11y: [
+        'The card is a complementary region (role="complementary" or an <aside>) with an aria-label so it can be skipped.',
+        'The progress bar carries role="progressbar" with aria-valuenow/min/max and an aria-label; the percentage also appears in the description text.',
+        'The × has aria-label "Dismiss" and comes last in the tab order inside the card; Escape does nothing here (the card is not modal).',
+        'Images have alt text or aria-label describing what is promoted; decorative art uses alt="".',
+        'Both actions are real <button>s or links; the link-color action opens the page it names.',
+    ],
+    related: ['sidebar', 'inline-cta', 'banner', 'progress', 'button', 'close-button'],
+};

package/lib/components/featured-icon.mjs

@@ -0,0 +1,67 @@
+import { ex, ICON } from "./_shared.mjs";
+const sizes = { sm: { box: '32px', icon: '{size.icon.sm}', radius: '{radius.md}' }, md: { box: '40px', icon: '{size.icon.md}', radius: '{radius.lg}' }, lg: { box: '48px', icon: '{size.icon.lg}', radius: '{radius.lg}' }, xl: { box: '56px', icon: '{size.icon.xl}', radius: '{radius.xl}' } };
+const tone = (fill, fg, solid, ringA, ringB) => ({ fill, fg, solid, ringA, ringB });
+const TONES = {
+    brand: tone('{color.bg-accent-subtle}', '{color.fg-accent}', '{color.bg-action}', '{brand.50}', '{brand.100}'),
+    gray: tone('{color.bg-muted}', '{color.fg-muted}', '{color.bg-inverse}', '{neutral.50}', '{neutral.100}'),
+    success: tone('{color.bg-success-subtle}', '{color.fg-success}', '{color.bg-success}', '{green.50}', '{green.100}'),
+    warning: tone('{color.bg-warning-subtle}', '{color.fg-warning}', '{color.bg-warning}', '{amber.50}', '{amber.100}'),
+    error: tone('{color.bg-danger-subtle}', '{color.fg-danger}', '{color.bg-danger}', '{red.50}', '{red.100}'),
+};
+const compound = Object.entries(TONES).flatMap(([t, v]) => [
+    { when: { tone: t, theme: 'light' }, block: { root: { 'background-color': v.fill, color: v.fg, 'border-inline-start': '2px solid currentColor' } } },
+    { when: { tone: t, theme: 'dark' }, block: { root: { 'background-color': v.solid, color: t === 'brand' ? '{color.fg-on-action}' : t === 'gray' ? '{color.fg-inverse}' : '{white}' } } },
+    { when: { tone: t, theme: 'outline' }, block: { root: { 'background-color': '{color.bg-surface}', color: v.fg, border: '1px solid currentColor', 'border-inline-start-width': '2px' } } },
+]);
+export const featuredIcon = {
+    name: 'FeaturedIcon',
+    slug: 'featured-icon',
+    category: 'media',
+    description: 'A compact icon frame with a leading edge and a clipped corner. Introduces a dialog, an empty state or a meaningful section.',
+    usage: 'Use at the top of a dialog, an empty state, a feature card or a step. One per block. Never as a decorative bullet in lists and never next to a title inside a table row (use a plain 20px icon there).',
+    anatomy: [
+        { part: 'root', element: 'span', description: 'The container. Size, radius and theme live here.' },
+        { part: 'icon', element: 'svg', description: 'The icon, sized by the container size (16/20/24/28). Stroke 1.5, currentColor.' },
+    ],
+    props: {
+        theme: { values: ['light', 'dark', 'modern', 'outline'], default: 'outline', description: 'outline = a fine frame with a stronger leading edge (default); light = a quiet tinted surface; dark = solid fill with contrasting icon; modern = a neutral surface with a fine border.' },
+        tone: { values: ['brand', 'gray', 'success', 'warning', 'error'], default: 'brand', description: 'Color family. gray for neutral/system, success/warning/error for status dialogs.' },
+        size: { values: ['sm', 'md', 'lg', 'xl'], default: 'md', description: 'Container 32 / 40 / 48 / 56px with icon 16 / 20 / 24 / 28.' },
+        shape: { values: ['square', 'circle'], default: 'square', description: 'square = compact corners with a clipped upper corner; circle = an optional round silhouette. Use square throughout a view.' },
+    },
+    states: {},
+    base: {
+        root: { position: 'relative', display: 'inline-flex', 'align-items': 'center', 'justify-content': 'center', 'flex-shrink': '0', 'vertical-align': 'middle' },
+        icon: { display: 'block', 'stroke-width': '1.5' },
+    },
+    variants: {
+        theme: {
+            light: { root: {} },
+            dark: { root: {} },
+            modern: { root: { 'background-color': '{color.bg-surface}', color: '{color.fg-muted}', border: '{border.width.thin} solid {color.border-default}', 'box-shadow': 'none' } },
+            outline: { root: {} },
+        },
+        tone: Object.fromEntries(Object.keys(TONES).map((t) => [t, { root: {} }])),
+        size: Object.fromEntries(Object.entries(sizes).map(([k, v]) => [k, { root: { width: v.box, height: v.box, 'border-radius': v.radius }, icon: { width: v.icon, height: v.icon } }])),
+        shape: { square: { root: {} }, circle: { root: { 'border-radius': '{radius.full}' } } },
+    },
+    compound: [...compound, { when: { theme: 'modern', tone: 'gray' }, block: { root: { color: '{color.fg-muted}' } } }],
+    extraCss: `
+.cn-featured-icon:not([data-shape="circle"]) { clip-path: polygon(0 0, calc(100% - 7px) 0, 100% 7px, 100% 100%, 0 100%); }
+.cn-featured-icon[data-theme="outline"]:not([data-shape="circle"])::after { content: ""; position: absolute; width: 10px; height: 1px; top: 2px; right: -2px; transform: rotate(45deg); background: currentColor; }`,
+    examples: [
+        ex('Framed icons (default)', `<span class="cn-featured-icon" data-theme="outline" data-tone="brand" data-size="md" data-shape="square">${ICON.spark.replace('cn-icon', 'cn-featured-icon__icon')}</span> <span class="cn-featured-icon" data-theme="outline" data-tone="gray" data-size="md" data-shape="square">${ICON.settings.replace('cn-icon', 'cn-featured-icon__icon')}</span> <span class="cn-featured-icon" data-theme="outline" data-tone="success" data-size="md" data-shape="square">${ICON.check.replace('cn-icon', 'cn-featured-icon__icon')}</span> <span class="cn-featured-icon" data-theme="outline" data-tone="warning" data-size="md" data-shape="square">${ICON.warning.replace('cn-icon', 'cn-featured-icon__icon')}</span> <span class="cn-featured-icon" data-theme="outline" data-tone="error" data-size="md" data-shape="square">${ICON.trash.replace('cn-icon', 'cn-featured-icon__icon')}</span>`),
+        ex('Dark and modern', `<span class="cn-featured-icon" data-theme="dark" data-tone="brand" data-size="md" data-shape="square">${ICON.spark.replace('cn-icon', 'cn-featured-icon__icon')}</span> <span class="cn-featured-icon" data-theme="dark" data-tone="error" data-size="md" data-shape="square">${ICON.trash.replace('cn-icon', 'cn-featured-icon__icon')}</span> <span class="cn-featured-icon" data-theme="modern" data-tone="gray" data-size="md" data-shape="square">${ICON.inbox.replace('cn-icon', 'cn-featured-icon__icon')}</span> <span class="cn-featured-icon" data-theme="modern" data-tone="gray" data-size="lg" data-shape="square">${ICON.search.replace('cn-icon', 'cn-featured-icon__icon')}</span>`),
+        ex('Outline frames (dialogs and alerts)', `<span class="cn-featured-icon" data-theme="outline" data-tone="brand" data-size="md" data-shape="square">${ICON.check.replace('cn-icon', 'cn-featured-icon__icon')}</span> <span class="cn-featured-icon" data-theme="outline" data-tone="error" data-size="md" data-shape="square">${ICON.warning.replace('cn-icon', 'cn-featured-icon__icon')}</span> <span class="cn-featured-icon" data-theme="outline" data-tone="success" data-size="md" data-shape="square">${ICON.check.replace('cn-icon', 'cn-featured-icon__icon')}</span>`),
+        ex('Sizes', `<span class="cn-featured-icon" data-theme="light" data-tone="brand" data-size="sm" data-shape="square">${ICON.spark.replace('cn-icon', 'cn-featured-icon__icon')}</span> <span class="cn-featured-icon" data-theme="light" data-tone="brand" data-size="md" data-shape="square">${ICON.spark.replace('cn-icon', 'cn-featured-icon__icon')}</span> <span class="cn-featured-icon" data-theme="light" data-tone="brand" data-size="lg" data-shape="square">${ICON.spark.replace('cn-icon', 'cn-featured-icon__icon')}</span> <span class="cn-featured-icon" data-theme="light" data-tone="brand" data-size="xl" data-shape="square">${ICON.spark.replace('cn-icon', 'cn-featured-icon__icon')}</span>`),
+    ],
+    rules: [
+        'One featured icon per block, always above or left of a title. It introduces; it never decorates.',
+        'Dialogs: lg (48px) light or outline; empty states: lg/xl; feature cards on marketing pages: md/lg light or dark; alerts: sm outline frame.',
+        'Tone follows meaning: brand for neutral product actions, error for destructive confirmations, success for completed, warning for caution, gray for system/info.',
+        'The icon is always an outline icon from the set with stroke 1.5 and currentColor. Never emoji, never a filled icon.',
+        'Do not put featured icons in table rows, list items or badges.',
+    ],
+    a11y: ['Decorative: the icon carries aria-hidden and the title next to it names the content.', 'If it must convey a status alone (rare), add role="img" and aria-label to the root.'],
+    related: ['empty-state', 'dialog', 'alert', 'card'],
+};

package/lib/components/field.mjs

@@ -0,0 +1,122 @@
+import { ex, ICON, typeStyle } from "./_shared.mjs";
+// the reference text field wrapper: label → control → hint stacked 6px apart. Label 14px medium in
+// the default ink with an optional brand asterisk (2px away) and a 16px help icon; hint 14px muted
+// (12px on sm) that turns to the danger color when invalid. Nothing else: no colon, no bold.
+const inp = (id, attrs, size = 'md', affix = '') => `<div class="cn-input" data-variant="default" data-size="${size}">${affix}<input class="cn-input__field" id="${id}" ${attrs}></div>`;
+const REQUIRED = '<span class="cn-field__required" aria-hidden="true">*</span>';
+const help = (text) => `<button type="button" class="cn-field__tooltip" aria-label="${text}">${ICON.info}</button>`;
+const fld = (id, label, control, o = {}) => `<div class="cn-field" data-layout="${o.layout ?? 'vertical'}" data-size="${o.size ?? 'md'}" ${o.root ?? ''} style="${o.style ?? 'max-width:360px'}"><label class="cn-field__label" for="${id}">${label}${o.labelExtra ?? ''}</label><div class="cn-field__control">${control}</div>${o.hint ? `<p class="cn-field__helper" id="${id}-hint">${o.hint}</p>` : ''}${o.error ? `<p class="cn-field__error" id="${id}-error">${o.error}</p>` : ''}</div>`;
+export const field = {
+    name: 'Field',
+    slug: 'field',
+    category: 'forms',
+    description: 'Label, control and one line of hint or error text stacked 6px apart (the reference text-field rhythm). The label is 14px medium with an optional brand asterisk and help icon; the hint is 14px muted and turns red when the field is invalid. It owns the words around a control so every form reads the same way.',
+    usage: 'Wrap every Input, Textarea, Select, Combobox, Slider and FileDropzone in a Field so it gets a visible label and a place for hint and error text. Do not wrap Checkbox, Radio or Switch (they carry their own label; group them with a radio-group or a fieldset). Use layout="horizontal" only on settings pages where many short fields stack under one another.',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'The wrapper: a 6px vertical stack by default; a label-column grid in horizontal layout. Carries data-invalid and data-disabled.' },
+        { part: 'label', element: 'label', description: 'Visible label with for="<control id>": 14px medium in the default ink, a flex row with 2px gaps for the asterisk and help icon. Sentence case, no trailing colon, 1–4 words ("Company name").' },
+        { part: 'required', element: 'span', description: 'Optional brand asterisk right after the label text (2px away) marking a required field; turns red when invalid. aria-hidden — the control carries required.', optional: true },
+        { part: 'tooltip', element: 'button', description: 'Optional 16px help icon after the label that opens a Tooltip on hover/focus (aria-label = the tooltip text). Gray-500, darker on hover.', optional: true },
+        { part: 'optional', element: 'span', description: 'Muted "(optional)" marker inside the label, regular weight, for forms that mark optional fields instead of required ones.', optional: true },
+        { part: 'control', element: 'div', description: 'Slot holding exactly one control (an Input, Select, Textarea, Combobox…). No styling besides min-width: 0.' },
+        { part: 'helper', element: 'p', description: 'The hint: one short line under the control, 14px (12px on sm) muted: format, example or limit ("Shown on invoices"). Hidden while the field is invalid.', optional: true },
+        { part: 'error', element: 'p', description: 'Validation message in the same size as the hint, in the danger color (an optional 16px icon may lead it). Hidden until data-invalid is on the root; give it an id and reference it from the control with aria-describedby.', optional: true },
+    ],
+    props: {
+        layout: { values: ['vertical', 'horizontal'], default: 'vertical', description: 'vertical = label above the control (forms, dialogs, onboarding); horizontal = label in a fixed 192px left column with the control on the right (settings pages with many short fields).' },
+        size: { values: ['sm', 'md'], default: 'md', description: 'md = 14px label and 14px hint, pairs with md/lg controls; sm = 14px label and 12px hint, pairs with sm controls in dense panels and filters (the reference size="sm" hint).' },
+    },
+    states: {
+        invalid: { selector: '[data-invalid]', description: 'Shows the error in the danger color, hides the hint and turns the asterisk red. Set together with aria-invalid="true" on the control.', markup: 'data-invalid on the root' },
+        disabled: { selector: '[data-disabled]', description: 'The control fades on its own (50% opacity); the label and hint stay readable and the label shows the not-allowed cursor. Set together with disabled on the control.', markup: 'data-disabled on the root' },
+    },
+    base: {
+        root: { display: 'flex', 'flex-direction': 'column', 'align-items': 'stretch', gap: '{space.1.5}', width: '100%', 'min-width': '0' },
+        label: { display: 'flex', 'align-items': 'center', gap: '{space.0.5}', ...typeStyle('label-sm'), color: '{color.fg-default}', cursor: 'default' },
+        required: { color: '{brand.600}', 'user-select': 'none' },
+        tooltip: {
+            display: 'inline-flex',
+            'align-items': 'center',
+            'justify-content': 'center',
+            'flex-shrink': '0',
+            width: '{size.icon.sm}',
+            height: '{size.icon.sm}',
+            margin: '0',
+            padding: '0',
+            border: '0',
+            background: 'none',
+            'border-radius': '{radius.sm}',
+            color: '{color.fg-subtle}',
+            cursor: 'pointer',
+            'transition-property': 'color, box-shadow',
+            'transition-duration': '{motion.duration.slow}',
+            'transition-timing-function': '{motion.easing.linear}',
+        },
+        optional: { 'font-weight': '{font.weight.regular}', color: '{color.fg-subtle}', 'margin-inline-start': '{space.0.5}' },
+        control: { 'min-width': '0' },
+        helper: { ...typeStyle('body-md'), color: '{color.fg-muted}' },
+        error: { display: 'none', 'align-items': 'flex-start', gap: '{space.1.5}', ...typeStyle('body-md'), color: '{color.fg-danger}' },
+        '@states': {
+            invalid: { helper: { display: 'none' }, error: { display: 'flex' }, required: { color: '{color.fg-danger}' } },
+            disabled: { label: { cursor: 'not-allowed' } },
+        },
+    },
+    variants: {
+        layout: {
+            vertical: { root: {} },
+            horizontal: {
+                root: { display: 'grid', 'grid-template-columns': '{space.48} minmax(0, 1fr)', 'column-gap': '{space.6}', 'row-gap': '{space.1.5}', 'align-items': 'start' },
+                label: { 'grid-column': '1', 'grid-row': '1', 'padding-block-start': '{space.2.5}' },
+                control: { 'grid-column': '2', 'grid-row': '1' },
+                helper: { 'grid-column': '2' },
+                error: { 'grid-column': '2' },
+            },
+        },
+        size: {
+            sm: { helper: { ...typeStyle('body-sm') }, error: { ...typeStyle('body-sm') } },
+            md: { helper: {}, error: {} },
+        },
+    },
+    extraCss: `
+.cn-field .cn-field__tooltip .cn-icon { width: {size.icon.sm}; height: {size.icon.sm}; stroke-width: 2.25; }
+.cn-field .cn-field__tooltip:hover, .cn-field .cn-field__tooltip:focus-visible { color: {color.fg-muted}; }
+.cn-field .cn-field__tooltip:focus-visible { outline: none; box-shadow: {shadow.focus}; }
+.cn-field .cn-field__error .cn-icon { width: {size.icon.sm}; height: {size.icon.sm}; flex-shrink: 0; margin-top: {space.0.5}; }
+.cn-field[data-layout="horizontal"][data-size="sm"] .cn-field__label { padding-block-start: {space.2}; }
+@media (max-width: {breakpoint.sm}) {
+  .cn-field[data-layout="horizontal"] { grid-template-columns: minmax(0, 1fr); gap: {space.1.5}; }
+  .cn-field[data-layout="horizontal"] .cn-field__label, .cn-field[data-layout="horizontal"] .cn-field__control, .cn-field[data-layout="horizontal"] .cn-field__helper, .cn-field[data-layout="horizontal"] .cn-field__error { grid-column: 1; grid-row: auto; }
+  .cn-field[data-layout="horizontal"] .cn-field__label, .cn-field[data-layout="horizontal"][data-size="sm"] .cn-field__label { padding-block-start: 0; }
+}`,
+    examples: [
+        ex('Vertical (default)', fld('field-company', 'Company name', inp('field-company', 'type="text" placeholder="Lumen Studio" aria-describedby="field-company-hint"'), { hint: 'The legal name that appears on invoices.' }), 'Label 14px medium, 6px, the control, 6px, a 14px muted hint.'),
+        ex('Required with help icon', fld('field-email', 'Work email', inp('field-email', 'type="email" placeholder="maya@lumen.app" required aria-describedby="field-email-hint"'), { hint: 'We only send billing receipts here.', labelExtra: REQUIRED + help('Used to sign in and to receive receipts') }), 'The brand asterisk sits 2px after the label; the 16px help icon opens a Tooltip.'),
+        ex('Optional marker', fld('field-site', 'Website', inp('field-site', 'type="url" placeholder="lumen.app"', 'md', '<span class="cn-input__affix">https://</span>'), { labelExtra: ' <span class="cn-field__optional">(optional)</span>' }), 'For forms that mark optional fields instead of required ones.'),
+        ex('Invalid', fld('field-email2', 'Work email', inp('field-email2', 'type="email" value="maya@lumen" aria-invalid="true" required aria-describedby="field-email2-error"'), { root: 'data-invalid', hint: 'We only send billing receipts here.', error: 'Enter a complete address, like maya@lumen.app.', labelExtra: REQUIRED }), 'The error replaces the hint in the danger color and the asterisk turns red; the text says how to fix it.'),
+        ex('Horizontal (settings page)', fld('field-display', 'Display name', inp('field-display', 'type="text" value="Maya Chen"'), { layout: 'horizontal', hint: 'Shown to teammates in comments and activity.', style: 'max-width:640px' }), 'A 192px label column; the label aligns with the 40px control.'),
+        ex('Disabled', fld('field-plan', 'Plan', inp('field-plan', 'type="text" value="Team (annual)" disabled'), { root: 'data-disabled', hint: 'Managed by Aisha Khan, your billing admin.' }), 'The control fades; the words stay readable.'),
+        ex('Small', fld('field-min', 'Minimum order value', inp('field-min', 'type="number" value="5000"', 'sm', '<span class="cn-input__affix">USD</span>'), { size: 'sm', hint: 'Orders below this value are hidden.', style: 'max-width:280px' }), 'A 14px label with a 12px hint, for sm controls.'),
+    ],
+    recipes: [
+        ex('Settings section', `<section class="cn-card" data-variant="default" data-padding="md" style="max-width:640px;width:100%"><header class="cn-card__header"><div><h3 class="cn-card__title">Workspace</h3><p class="cn-card__description">Name and region are visible to every member.</p></div></header><div class="cn-card__body" style="display:flex;flex-direction:column;gap:var(--cn-space-5)">${fld('ws-name', 'Workspace name', inp('ws-name', 'type="text" value="Lumen Studio"'), { layout: 'horizontal', style: '' })}${fld('ws-slug', 'URL', inp('ws-slug', 'type="text" value="lumen-studio"', 'md', '<span class="cn-input__affix">app.lumen.app/</span>'), { layout: 'horizontal', hint: 'Lowercase letters, numbers and dashes.', style: '' })}${fld('ws-region', 'Data region', inp('ws-region', 'type="text" value="Europe (Frankfurt)" disabled'), { layout: 'horizontal', root: 'data-disabled', hint: 'Contact support to migrate regions.', style: '' })}</div><footer class="cn-card__footer" style="justify-content:flex-end"><button type="button" class="cn-button" data-variant="primary" data-size="sm"><span class="cn-button__label">Save changes</span></button></footer></section>`, 'Horizontal fields inside a Card, stacked 20px apart. One primary action in the footer.'),
+    ],
+    rules: [
+        'Every control gets a visible label. Placeholder text is an example value, never the label.',
+        'Labels are 1–4 words in sentence case with no colon. Name what goes in the field ("Work email"), not the action ("Enter your email").',
+        'Pick one convention per form: mark required fields with the brand asterisk, or mark optional ones with "(optional)". Never both.',
+        'Hint text is one sentence in present tense that answers "what format" or "why do you need it". If it needs two lines, the label or the flow is wrong.',
+        'Invalid: set data-invalid on the Field AND aria-invalid="true" on the control. The error replaces the hint and says how to fix it ("Enter a complete address"), not just "Invalid".',
+        'The help icon carries context that does not fit the hint (why, where it is used); it never replaces the hint or the error.',
+        'Use one layout per form. Horizontal settings fields have a 192px label column and stack vertically below 640px of available width.',
+        'Fields stack 20px apart; two related short fields (city + postal code) may share a row 16px apart.',
+        'Constrain short values (postal code, quantity, currency) with max-width on the Field, not on the control.',
+    ],
+    a11y: [
+        'The <label for> references the control id, so clicking the label focuses the control and screen readers announce it.',
+        'The asterisk is aria-hidden; put required on the control (or aria-required) so the requirement is announced.',
+        'The help icon is a real <button> with aria-label equal to the tooltip text; the tooltip is referenced with aria-describedby.',
+        'When invalid, the control has aria-invalid="true" and aria-describedby pointing at the error id; when valid, aria-describedby points at the hint id.',
+        'The error text is static in the flow. Announce submit results with a separate live region, not by making every error aria-live.',
+    ],
+    related: ['input', 'textarea', 'select', 'combobox', 'checkbox', 'radio', 'tooltip'],
+};

package/lib/components/file-dropzone.mjs

@@ -0,0 +1,166 @@
+import { ex, ICON, typeStyle } from "./_shared.mjs";
+// the reference file upload: a white dropzone with a 1px gray-200 ring, radius 12, 16×24px padding,
+// a centered 40px modern featured icon, "Click to upload" (brand link) + "or drag and drop" (14px
+// muted) and a 12px hint; drag-over = 2px brand ring; disabled = gray-50. Files list as bordered
+// cards (radius 12, 16px padding, 12px gap): 40px file icon, medium name, size · status row, an 8px
+// progress bar, a utility delete button top-right; failed rows get a 2px red ring and "Try again".
+const TRANSITION_FAST = {
+    'transition-property': 'box-shadow, background-color, color, opacity',
+    'transition-duration': '{motion.duration.fast}',
+    'transition-timing-function': '{motion.easing.linear}',
+};
+const ring = (width, color) => `inset 0 0 0 ${width} ${color}`;
+const UPLOAD_PATH = '<path d="M8 10.5V3M4.5 6.5L8 3l3.5 3.5M2.5 11v1.5a1 1 0 001 1h9a1 1 0 001-1V11"/>';
+const svg16 = (cls, body, sw = '1.5') => `<svg class="${cls}" viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="${sw}" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">${body}</svg>`;
+const featured = `<span class="cn-featured-icon" data-theme="modern" data-tone="gray" data-size="md" data-shape="square">${svg16('cn-featured-icon__icon', UPLOAD_PATH)}</span>`;
+const FILE_ICON = '<svg class="cn-file-dropzone__file-icon" viewBox="0 0 40 40" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M11 5h13l9 9v19a2 2 0 01-2 2H11a2 2 0 01-2-2V7a2 2 0 012-2z"/><path d="M24 5v9h9"/></svg>';
+const STATUS_ICON = {
+    complete: svg16('cn-icon', '<circle cx="8" cy="8" r="6.25"/><path d="M5.5 8.25l1.75 1.75 3.5-3.5"/>', '1.75'),
+    uploading: svg16('cn-icon', UPLOAD_PATH, '1.75'),
+    failed: svg16('cn-icon', '<circle cx="8" cy="8" r="6.25"/><path d="M6 6l4 4M10 6l-4 4"/>', '1.75'),
+};
+const STATUS_TEXT = { complete: 'Complete', uploading: 'Uploading…', failed: 'Failed' };
+const deleteButton = (name) => `<button type="button" class="cn-icon-button" data-variant="utility" data-size="xs" data-shape="square" aria-label="Delete ${name}">${ICON.trash.replace('cn-icon', 'cn-icon-button__icon')}</button>`;
+const progress = (name, pct) => `<div class="cn-progress" data-size="lg" data-tone="action" role="progressbar" aria-label="Uploading ${name}" aria-valuenow="${pct}" aria-valuemin="0" aria-valuemax="100"><div class="cn-progress__track"><div class="cn-progress__indicator" style="width:${pct}%"></div></div></div>`;
+const fileRow = (name, size, state, pct) => `<li class="cn-file-dropzone__file" data-state="${state}">${FILE_ICON}<div class="cn-file-dropzone__file-body"><span class="cn-file-dropzone__file-name">${name}</span><div class="cn-file-dropzone__file-meta"><span class="cn-file-dropzone__file-size">${size}</span><span class="cn-file-dropzone__file-divider" aria-hidden="true"></span><span class="cn-file-dropzone__file-status">${STATUS_ICON[state]}${STATUS_TEXT[state]}</span></div>${state === 'failed' ? `<div class="cn-file-dropzone__file-retry"><button type="button" class="cn-button" data-variant="danger-link" data-size="sm"><span class="cn-button__label">Try again</span></button></div>` : `<div class="cn-file-dropzone__file-progress">${progress(name, pct)}<span class="cn-file-dropzone__file-percent">${pct}%</span></div>`}</div><div class="cn-file-dropzone__file-actions">${deleteButton(name)}</div></li>`;
+const TITLE = '<span class="cn-file-dropzone__action">Click to upload</span> or drag and drop';
+const zone = (root, input, hint, files = '', title = TITLE) => `<div class="cn-file-dropzone" ${root}><input class="cn-file-dropzone__input" type="file" ${input}>${featured}<div class="cn-file-dropzone__text"><span class="cn-file-dropzone__title">${title}</span><span class="cn-file-dropzone__hint">${hint}</span></div>${files ? `<ul class="cn-file-dropzone__files">${files}</ul>` : ''}</div>`;
+export const fileDropzone = {
+    name: 'FileDropzone',
+    slug: 'file-dropzone',
+    category: 'forms',
+    description: 'Upload target: a white card with a 1px gray-200 ring and radius 12, a centered 40px featured icon, "Click to upload or drag and drop" and a hint of accepted types. The native file input covers the whole zone, so click and drop work without extra JS. Selected files list under the text as bordered cards with progress and a delete button.',
+    usage: 'Any file upload in a form or dialog (documents, spreadsheets, a logo). For a single small image next to a preview use size="sm". Not for pasting text or URLs, and not as a full-page drop overlay (that is a separate layer).',
+    anatomy: [
+        { part: 'root', element: 'div', description: 'The zone: white, 1px gray-200 inset ring, radius 12, padding 16×24 (md) or 16 (sm), centered column with a 12px gap. Carries data-state="idle|dragover", data-invalid, data-disabled.' },
+        { part: 'input', element: 'input', description: 'Native <input type="file"> stretched over the whole zone at opacity 0. Carries accept, multiple, disabled, aria-invalid.' },
+        { part: 'icon', element: 'svg', description: 'The upload-cloud icon. Put it inside a FeaturedIcon (theme modern, tone gray, size md = 40px, radius 8); on its own it renders as a 20px muted icon.', optional: true },
+        { part: 'text', element: 'div', description: 'Centered text block: the title line and the hint, 4px apart.' },
+        { part: 'title', element: 'span', description: 'The first line, 14px muted: the action ("Click to upload") followed by "or drag and drop" (or "Release to upload" while dragging).' },
+        { part: 'action', element: 'span', description: 'The brand link-colored words inside the title ("Click to upload"): 14px semibold, underlined when the zone is hovered. Not a button — the input above it takes the click.' },
+        { part: 'hint', element: 'span', description: '12px muted line: accepted types and size limit ("SVG, PNG, JPG or GIF (max. 800×400px)"). Turns to the danger color and carries the rejection reason when invalid.' },
+        { part: 'files', element: 'ul', description: 'List of selected files under the text, full width, 12px between rows, raised above the input so its buttons are clickable.', optional: true },
+        { part: 'file', element: 'li', description: 'One file card: white, 1px gray-200 ring, radius 12, 16px padding, 12px gap between icon, body and actions. data-state="uploading|complete|failed"; failed rows get a 2px red ring.', optional: true },
+        { part: 'file-icon', element: 'svg', description: '40×40 file-type icon, muted, does not shrink.', optional: true },
+        { part: 'file-body', element: 'div', description: 'Name, meta row, progress or retry stacked; takes the remaining width.', optional: true },
+        { part: 'file-name', element: 'span', description: 'The file name, 14px medium, truncated with an ellipsis.', optional: true },
+        { part: 'file-meta', element: 'div', description: 'Row 2px under the name: size, a 1×12px divider and the status, 8px apart, 14px muted.', optional: true },
+        { part: 'file-size', element: 'span', description: 'Formatted size ("1.2 MB"), 14px muted, tabular.', optional: true },
+        { part: 'file-divider', element: 'span', description: 'A 1×12px gray-300 rule between size and status.', optional: true },
+        { part: 'file-status', element: 'span', description: '16px icon + word, 14px medium, 4px apart: "Uploading…" muted, "Complete" green, "Failed" red (colors follow data-state on the row).', optional: true },
+        { part: 'file-progress', element: 'div', description: 'Row 4px under the meta: a Progress bar (size lg = 8px track) with the percentage at the right, 12px apart.', optional: true },
+        { part: 'file-percent', element: 'span', description: 'The percentage next to the bar, 14px medium, tabular.', optional: true },
+        { part: 'file-retry', element: 'div', description: 'Row 6px under the meta on failed rows holding a danger-link sm "Try again" button.', optional: true },
+        { part: 'file-actions', element: 'div', description: 'Top-right slot for the utility xs delete button, pulled 8px into the padding so the icon aligns with the content edge.', optional: true },
+    ],
+    props: {
+        size: { values: ['sm', 'md'], default: 'md', description: 'md = padding 16×24 with the 40px featured icon (documents in forms and dialogs, the reference dropzone); sm = padding 16 all round for a single avatar, logo or attachment next to a preview.' },
+    },
+    states: {
+        dragover: { selector: '[data-state="dragover"]', description: 'A file is being dragged over the zone: the ring becomes 2px in the brand color.', markup: 'data-state="dragover" on the root (set on dragenter, cleared on dragleave/drop)' },
+        hover: { selector: ':hover:not([data-disabled])', description: 'Pointer over the zone: the action words underline, like a link. Nothing else changes.', markup: 'native :hover' },
+        focus: { selector: ':has(> input:focus-visible)', description: 'Keyboard focus on the file input (not on a row button) shows the 4px brand ring around the zone.', markup: 'native :focus-visible on the input' },
+        invalid: { selector: '[data-invalid], &:has([aria-invalid="true"])', description: 'A rejected file (type or size): the hint turns to the danger color and carries the reason.', markup: 'aria-invalid="true" on the input, or data-invalid on the root' },
+        disabled: { selector: '[data-disabled], &:has(> input:disabled)', description: 'Gray-50 fill, cursor not-allowed, the featured icon at 50%, no drop. Scoped to the file input so a disabled row button does not trigger it.', markup: 'disabled on the input' },
+        'file-failed': { selector: '[data-state="failed"]', description: 'On a __file row: 2px red ring, red status, "Try again" instead of the progress bar.', markup: 'data-state="failed" on the row' },
+    },
+    base: {
+        root: {
+            position: 'relative',
+            display: 'flex',
+            'flex-direction': 'column',
+            'align-items': 'center',
+            gap: '{space.3}',
+            width: '100%',
+            'min-width': '0',
+            'background-color': '{color.bg-surface}',
+            'border-radius': '{radius.card}',
+            'box-shadow': ring('1px', '{color.border-default}'),
+            color: '{color.fg-muted}',
+            cursor: 'pointer',
+            ...TRANSITION_FAST,
+        },
+        input: { position: 'absolute', inset: '0', width: '100%', height: '100%', margin: '0', padding: '0', opacity: '0', cursor: 'pointer' },
+        icon: { display: 'block', width: '{size.icon.md}', height: '{size.icon.md}', 'flex-shrink': '0', color: '{color.fg-muted}' },
+        text: { display: 'flex', 'flex-direction': 'column', gap: '{space.1}', 'text-align': 'center', 'min-width': '0' },
+        title: { display: 'flex', 'justify-content': 'center', 'flex-wrap': 'wrap', gap: '{space.1}', ...typeStyle('body-md'), color: '{color.fg-muted}' },
+        action: { ...typeStyle('label-md'), color: '{color.fg-action}', 'text-decoration-line': 'underline', 'text-decoration-color': 'transparent', 'text-underline-offset': '3px', ...TRANSITION_FAST },
+        hint: { ...typeStyle('body-sm'), color: '{color.fg-muted}', ...TRANSITION_FAST },
+        files: { position: 'relative', 'z-index': '{z.raised}', display: 'flex', 'flex-direction': 'column', gap: '{space.3}', width: '100%', 'margin-top': '{space.1}', 'text-align': 'start', cursor: 'default' },
+        file: {
+            position: 'relative',
+            display: 'flex',
+            'align-items': 'flex-start',
+            gap: '{space.3}',
+            'min-width': '0',
+            padding: '{space.4}',
+            'background-color': '{color.bg-surface}',
+            'border-radius': '{radius.card}',
+            'box-shadow': ring('1px', '{color.border-default}'),
+            color: '{color.fg-default}',
+            'transition-property': 'box-shadow',
+            'transition-duration': '{motion.duration.fast}',
+            'transition-timing-function': '{motion.easing.linear}',
+        },
+        'file-icon': { width: '{space.10}', height: '{space.10}', 'flex-shrink': '0', color: '{color.fg-subtle}' },
+        'file-body': { flex: '1 1 auto', 'min-width': '0', display: 'flex', 'flex-direction': 'column' },
+        'file-name': { display: 'block', ...typeStyle('label-sm'), color: '{color.fg-default}', overflow: 'hidden', 'text-overflow': 'ellipsis', 'white-space': 'nowrap' },
+        'file-meta': { display: 'flex', 'align-items': 'center', gap: '{space.2}', 'margin-top': '{space.0.5}', ...typeStyle('body-md'), color: '{color.fg-muted}' },
+        'file-size': { 'flex-shrink': '0', 'font-variant-numeric': 'tabular-nums' },
+        'file-divider': { width: '{space.px}', height: '{space.3}', 'border-radius': '{radius.full}', 'background-color': '{color.border-control}', 'flex-shrink': '0' },
+        'file-status': { display: 'inline-flex', 'align-items': 'center', gap: '{space.1}', ...typeStyle('label-sm'), color: '{color.fg-subtle}' },
+        'file-progress': { display: 'flex', 'align-items': 'center', gap: '{space.3}', 'margin-top': '{space.1}', width: '100%' },
+        'file-percent': { 'flex-shrink': '0', ...typeStyle('label-sm'), color: '{color.fg-muted}', 'font-variant-numeric': 'tabular-nums' },
+        'file-retry': { 'margin-top': '{space.1.5}' },
+        'file-actions': { 'align-self': 'flex-start', 'flex-shrink': '0', margin: 'calc(-1 * {space.2}) calc(-1 * {space.2}) 0 0' },
+        '@states': {
+            dragover: { root: { 'box-shadow': ring('2px', '{color.border-action}') } },
+            hover: { action: { 'text-decoration-color': 'currentColor' } },
+            focus: { root: { 'box-shadow': `${ring('1px', '{color.border-default}')}, {shadow.focus}` } },
+            invalid: { hint: { color: '{color.fg-danger}' } },
+            disabled: { root: { 'background-color': '{color.bg-subtle}', cursor: 'not-allowed', 'pointer-events': 'none' }, input: { cursor: 'not-allowed' }, icon: { opacity: '{opacity.disabled}' } },
+            'file-failed': { file: { 'box-shadow': ring('2px', '{color.border-danger}') }, 'file-status': { color: '{color.fg-danger}' } },
+        },
+    },
+    variants: {
+        size: {
+            sm: { root: { padding: '{space.4}', gap: '{space.2}' } },
+            md: { root: { padding: '{space.4} {space.6}' } },
+        },
+    },
+    extraCss: `
+.cn-file-dropzone[data-disabled] .cn-featured-icon, .cn-file-dropzone:has(> input:disabled) .cn-featured-icon { opacity: {opacity.disabled}; }
+.cn-file-dropzone .cn-file-dropzone__file[data-state="complete"] .cn-file-dropzone__file-status { color: {color.fg-success}; }
+.cn-file-dropzone .cn-file-dropzone__file[data-state="uploading"] .cn-file-dropzone__file-status { color: {color.fg-subtle}; }
+.cn-file-dropzone .cn-file-dropzone__file[data-state="complete"] .cn-file-dropzone__file-percent { color: {color.fg-muted}; }
+.cn-file-dropzone .cn-file-dropzone__file-status .cn-icon { width: {size.icon.sm}; height: {size.icon.sm}; stroke-width: 2.5; }
+.cn-file-dropzone .cn-file-dropzone__file-progress .cn-progress { flex: 1 1 auto; min-width: 0; }`,
+    examples: [
+        ex('Default', zone('data-size="md" data-state="idle" style="max-width:512px"', 'multiple accept=".pdf,.docx,.fig" aria-label="Upload files"', 'PDF, DOCX or FIG (max. 25 MB)'), 'White, 1px gray-200 ring, radius 12, 16×24 padding; 40px modern featured icon; "Click to upload" in the brand link color.'),
+        ex('Drag over', zone('data-size="md" data-state="dragover" style="max-width:512px"', 'multiple accept=".pdf,.docx,.fig" aria-label="Upload files"', 'PDF, DOCX or FIG (max. 25 MB)', '', 'Release to upload'), 'The ring becomes 2px in the brand color; nothing else moves.'),
+        ex('With files (complete, uploading, failed)', zone('data-size="md" data-state="idle" style="max-width:512px"', 'multiple accept=".pdf,.docx,.fig" aria-label="Upload files"', 'PDF, DOCX or FIG (max. 25 MB)', fileRow('brand-guidelines-v3.pdf', '1.2 MB', 'complete', 100) + fileRow('research-synthesis.fig', '348 KB', 'uploading', 60) + fileRow('interview-notes-daniel-costa.docx', '2.1 MB', 'failed', 0)), 'Rows are bordered cards with a 40px file icon, medium name, size · status, an 8px progress bar and a utility delete button; a failed row gets a 2px red ring and "Try again".'),
+        ex('Small (single image)', zone('data-size="sm" data-state="idle" style="max-width:280px"', 'accept="image/png,image/jpeg" aria-label="Upload logo"', 'PNG or JPG, square, up to 2 MB'), '16px padding all round, for one asset next to its preview.'),
+        ex('Invalid', zone('data-size="md" data-state="idle" data-invalid style="max-width:512px"', 'multiple accept=".pdf,.docx,.fig" aria-invalid="true" aria-label="Upload files"', 'archive.zip is not accepted. Upload PDF, DOCX or FIG (max. 25 MB).'), 'The hint turns to the danger color and starts with the rejected file.'),
+        ex('Disabled', zone('data-size="md" data-state="idle" style="max-width:512px"', 'disabled aria-label="Upload files"', 'Uploads are paused while the project is archived.'), 'Gray-50 fill, cursor not-allowed, the featured icon at 50%.'),
+    ],
+    recipes: [
+        ex('In a Field', `<div class="cn-field" data-layout="vertical" data-size="md" style="max-width:512px"><label class="cn-field__label" for="dz-docs">Supporting documents <span class="cn-field__optional">(optional)</span></label><div class="cn-field__control">${zone('data-size="md" data-state="idle"', 'id="dz-docs" multiple accept=".pdf,.docx,.fig" aria-describedby="dz-docs-hint"', 'PDF, DOCX or FIG (max. 25 MB)', fileRow('usability-report-q3.pdf', '212 KB', 'complete', 100))}</div><p class="cn-field__helper" id="dz-docs-hint">Visible to everyone in the Lumen workspace.</p></div>`, 'The Field label names the input through for/id; the hint says where the files go.'),
+    ],
+    rules: [
+        'The whole area is the target: the file input covers the root, so a click anywhere opens the picker and a drop anywhere works. Do not add a separate "Browse" button.',
+        'Title copy is "Click to upload" (brand link) + "or drag and drop"; while dragging over it may change to "Release to upload". Under 768px the second half may be dropped ("Click to upload and attach files").',
+        'The hint always states accepted types and the size limit ("PDF, DOCX or FIG (max. 25 MB)"); when invalid it starts with the rejected file and keeps the same constraints in one sentence.',
+        'Set data-state="dragover" on dragenter and clear it on dragleave and drop. The ring changes in 100ms; nothing pulses.',
+        'Selected files list as cards 12px apart with name, size · status, an 8px progress bar with the percentage and a utility xs delete button. Failed rows set data-state="failed", get a 2px red ring and a danger-link "Try again".',
+        'md in forms and dialogs, max-width 512px; sm for one small asset (avatar, logo) placed next to its preview.',
+        'Never a full-page dropzone inside the app shell; use a page-level drop overlay for that and keep this component in the form.',
+    ],
+    a11y: [
+        'The native <input type="file"> stays focusable: Tab reaches it, Enter or Space open the picker, and the ring shows on the zone through :has(:focus-visible).',
+        'Give the input an accessible name that says what to upload ("Upload files"): a Field label with for/id, or aria-label.',
+        'Use accept and multiple on the input so the OS picker and assistive tech know the constraints; repeat them in the hint.',
+        'Delete buttons carry aria-label "Delete <file name>"; progress bars carry aria-label and aria-valuenow; announce completion or failure in a live region.',
+        'Drag and drop is an enhancement: the picker must always work, including on touch devices.',
+    ],
+    related: ['field', 'featured-icon', 'progress', 'icon-button', 'button'],
+};