@pithyjs/pidl-catalog 0.1.0-beta.0

package/dist/specs/atoms/forms/checkbox-group.pidl.json

@@ -0,0 +1,170 @@
+{
+    "kind": "component",
+    "id": "ui.checkbox-group",
+    "name": "CheckboxGroup",
+    "displayName": "Checkbox Group",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "forms",
+    "bidi": true,
+    "description": "Accessible group wrapper for related <Checkbox> controls. Renders <fieldset><legend> with optional helper/error text and aria-describedby wiring. Native fieldset[disabled] cascades to all child checkboxes. Children are projected through the full PithyJS pipeline.",
+    "props": [
+        {
+            "name": "id",
+            "label": "ID",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Explicit fieldset ID — overrides auto-generated ID."
+        },
+        {
+            "name": "label",
+            "label": "Label",
+            "type": "string",
+            "required": true,
+            "placeholder": "Pick your favorites",
+            "description": "Required group label rendered inside <legend>. Provides the accessible name for the group."
+        },
+        {
+            "name": "hideLabel",
+            "label": "Hide label",
+            "type": "boolean",
+            "default": false,
+            "description": "Visually hide the legend (still announced by screen readers via .u-visually-hidden)."
+        },
+        {
+            "name": "helperText",
+            "label": "Helper text",
+            "type": "string",
+            "description": "Persistent helper text below the group. Wired via aria-describedby when no error is shown."
+        },
+        {
+            "name": "errorMessage",
+            "label": "Error message",
+            "type": "string | Signal<string>",
+            "description": "Error message rendered in a span with role='alert'. Linked via aria-describedby when error is truthy. Accepts a signal accessor for reactive updates."
+        },
+        {
+            "name": "error",
+            "label": "Error",
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Visual error state — sets aria-invalid='true' and data-error on the fieldset. Error message only displays when both error and errorMessage are set. Accepts a signal accessor for reactive updates."
+        },
+        {
+            "name": "disabled",
+            "label": "Disabled",
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Disables the entire group via native fieldset[disabled], cascading to every child checkbox without extra plumbing. Accepts a signal accessor for reactive updates."
+        }
+    ],
+    "events": [],
+    "slots": [
+        {
+            "name": "default",
+            "displayName": "Checkboxes",
+            "description": "Children projected through renderChildren() — typically <Checkbox> elements but any markup is supported. The fieldset is marked as a site-builder drop zone.",
+            "accepts": ["ui.checkbox"]
+        }
+    ],
+    "tokens": {
+        "legend.color": "--color-text",
+        "helper.color": "--color-text-muted",
+        "error.color": "--color-danger",
+        "group.gap": "--space-sm"
+    },
+    "spacing": {
+        "internal": {
+            "legend-to-children": { "relationship": "close_friends", "token": "sm" },
+            "children-to-helper": { "relationship": "lovers", "token": "xs" },
+            "children-to-error": { "relationship": "lovers", "token": "xs" }
+        }
+    },
+    "constraints": [
+        "Use semantic <fieldset>/<legend> — never a div with role='group'",
+        "label prop is required — every group must have an accessible name",
+        "Native fieldset[disabled] (not aria-disabled) — cascades automatically to children",
+        "Error message only shown when both error=true and errorMessage are set",
+        "Children must be Checkbox controls (or compose them) — group semantics assume checkbox descendants",
+        "data-slot='children' is required on the fieldset for site-builder drop targeting"
+    ],
+    "a11y": [
+        "Native <fieldset><legend> — strongest semantic grouping for related form controls",
+        "label always rendered inside <legend> (visually hidden via hideLabel when needed)",
+        "aria-invalid='true' when error prop is truthy",
+        "aria-describedby points to helper id (no error) or error id (when shown)",
+        "Error message has role='alert' for live region announcement",
+        "fieldset[disabled] cascades native disabled state to all child controls",
+        "Auto-generated id enables external aria-describedby/labelling"
+    ],
+    "ai": {
+        "synonyms": [
+            "checkbox set",
+            "checkbox list",
+            "multi-select group",
+            "fieldset",
+            "option group"
+        ],
+        "avoid": [
+            "Wrapping a single Checkbox in CheckboxGroup — use Checkbox directly",
+            "Using FormField around individual Checkboxes — Checkbox already provides its own label; use CheckboxGroup for grouped controls",
+            "div with role='group' — use the native <fieldset> via <CheckboxGroup>",
+            "Omitting the label prop — the group must have an accessible name",
+            "Adding aria-disabled — use the native disabled prop instead"
+        ],
+        "patterns": [
+            "Basic: <CheckboxGroup label=\"'Toppings'\"><Checkbox label=\"'Cheese'\" /><Checkbox label=\"'Pepperoni'\" /></CheckboxGroup>",
+            "With helper: <CheckboxGroup label=\"'Toppings'\" helperText=\"'Pick any number'\">…</CheckboxGroup>",
+            "With error: <CheckboxGroup label=\"'Toppings'\" error=\"hasError\" errorMessage=\"'Pick at least one'\">…</CheckboxGroup>",
+            "Disabled (cascades): <CheckboxGroup label=\"'Locked options'\" disabled=\"true\">…</CheckboxGroup>",
+            "Visually hidden legend: <CheckboxGroup label=\"'Filters'\" hideLabel=\"true\">…</CheckboxGroup>"
+        ]
+    },
+    "examples": [
+        {
+            "id": "basic",
+            "title": "Basic checkbox group",
+            "pithy": "<CheckboxGroup label=\"'Toppings'\"><Checkbox label=\"'Cheese'\" name=\"'toppings'\" value=\"'cheese'\" /><Checkbox label=\"'Pepperoni'\" name=\"'toppings'\" value=\"'pepperoni'\" /></CheckboxGroup>",
+            "assertions": [
+                "fieldset > legend with label text",
+                "data-slot='children' on fieldset",
+                "no axe violations"
+            ]
+        },
+        {
+            "id": "helper",
+            "title": "Group with helper text",
+            "pithy": "<CheckboxGroup label=\"'Toppings'\" helperText=\"'Pick any number'\"><Checkbox label=\"'Cheese'\" /></CheckboxGroup>",
+            "assertions": ["helper rendered", "aria-describedby points to helper id"]
+        },
+        {
+            "id": "error",
+            "title": "Group with error",
+            "pithy": "<CheckboxGroup label=\"'Toppings'\" error=\"true\" errorMessage=\"'Pick at least one'\"><Checkbox label=\"'Cheese'\" /></CheckboxGroup>",
+            "assertions": [
+                "aria-invalid='true' on fieldset",
+                "error span with role='alert' visible",
+                "aria-describedby points to error id"
+            ]
+        },
+        {
+            "id": "disabled-cascade",
+            "title": "Disabled group cascades to children",
+            "pithy": "<CheckboxGroup label=\"'Locked'\" disabled=\"true\"><Checkbox label=\"'Cheese'\" /></CheckboxGroup>",
+            "assertions": ["fieldset[disabled]", "child input.disabled === true"]
+        },
+        {
+            "id": "hide-label",
+            "title": "Visually hidden legend",
+            "pithy": "<CheckboxGroup label=\"'Filters'\" hideLabel=\"true\"><Checkbox label=\"'On sale'\" /></CheckboxGroup>",
+            "assertions": ["legend present", "legend has u-visually-hidden class"]
+        }
+    ],
+    "designGuidance": {
+        "surface": "No background by default — inherits the page surface. The group is a semantic container, not a visual card.",
+        "depth": "Flat — no shadow or elevation. Children carry their own focus state.",
+        "borders": "No border on the fieldset itself (UA defaults reset). Visual grouping comes from spacing, not chrome.",
+        "interactivity": "Stateless wrapper — interactivity lives on individual Checkbox children. fieldset[disabled] cascades native disabled to descendants without per-child wiring.",
+        "bestPractices": "Always pair related checkboxes inside a CheckboxGroup. Use a clear, concise legend label. Prefer native disabled over per-child disabling. Use hideLabel sparingly — only when surrounding context (e.g., a toolbar header) already provides the accessible name."
+    }
+}

package/dist/specs/atoms/forms/checkbox.pidl.json

@@ -0,0 +1,323 @@
+{
+    "kind": "component",
+    "id": "ui.checkbox",
+    "name": "Checkbox",
+    "displayName": "Checkbox",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "forms",
+    "bidi": true,
+    "description": "Accessible checkbox atom with a custom-rendered box and inline SVG mark (animated checkmark + indeterminate dash via stroke-dashoffset), error/success states with shake animation, helper/error text, loading spinner, and full a11y wiring. No validation logic — states driven externally.",
+    "props": [
+        {
+            "name": "id",
+            "label": "ID",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Explicit input ID — overrides auto-generated ID."
+        },
+        {
+            "name": "name",
+            "label": "Name",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Input name attribute for form submission."
+        },
+        {
+            "name": "value",
+            "label": "Value",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "default": "on",
+            "description": "Submitted value when the checkbox is checked."
+        },
+        {
+            "name": "checked",
+            "label": "Checked",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Checked state — static or signal accessor for controlled checkbox."
+        },
+        {
+            "name": "indeterminate",
+            "label": "Indeterminate",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Indeterminate state — visually shows a horizontal dash. Cleared automatically on user toggle."
+        },
+        {
+            "name": "disabled",
+            "label": "Disabled",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Disabled state — uses native disabled attribute."
+        },
+        {
+            "name": "readonly",
+            "label": "Read-only",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Readonly state — focusable but not toggleable. Native input ignores readonly, so toggling is intercepted via click preventDefault, Space keydown preventDefault, and a change-event rollback to the controlled value."
+        },
+        {
+            "name": "required",
+            "label": "Required",
+            "type": "boolean",
+            "default": false,
+            "description": "Sets aria-required and adds a visual asterisk to the label."
+        },
+        {
+            "name": "error",
+            "label": "Error",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Visual error state — sets aria-invalid, red box border, shake on transition."
+        },
+        {
+            "name": "errorMessage",
+            "label": "Error message",
+            "editor": { "tab": "settings" },
+            "type": "string | Signal<string>",
+            "description": "Error message shown below the checkbox when error is truthy. Linked via aria-describedby with role='alert'."
+        },
+        {
+            "name": "helperText",
+            "label": "Helper text",
+            "type": "string",
+            "description": "Persistent hint text below the checkbox. Hidden when error is visible."
+        },
+        {
+            "name": "success",
+            "label": "Success",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Visual success state — green border / fill. Error takes precedence."
+        },
+        {
+            "name": "size",
+            "label": "Size",
+            "type": "enum",
+            "enum": ["sm", "md", "lg"],
+            "default": "md",
+            "description": "Control size — drives box dimensions and label font-size."
+        },
+        {
+            "name": "label",
+            "label": "Label",
+            "type": "string",
+            "required": true,
+            "placeholder": "Accept terms and conditions",
+            "description": "Visible label text rendered next to the box. Always required."
+        },
+        {
+            "name": "loading",
+            "label": "Loading",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Loading state — overlays a spinner inside the box and sets aria-busy."
+        },
+        {
+            "name": "onChange",
+            "type": "(checked: boolean, e: Event) => void",
+            "description": "Fires whenever the checked state changes."
+        },
+        {
+            "name": "onBlur",
+            "type": "(e: FocusEvent) => void",
+            "description": "Fires when the checkbox loses focus."
+        },
+        {
+            "name": "onFocus",
+            "type": "(e: FocusEvent) => void",
+            "description": "Fires when the checkbox gains focus."
+        }
+    ],
+    "events": ["change", "blur", "focus"],
+    "slots": [],
+    "tokens": {
+        "box.size.sm": "calc(var(--font-size-xs) * 1.25)",
+        "box.size.md": "calc(var(--font-size-sm) * 1.25)",
+        "box.size.lg": "calc(var(--font-size-body) * 1.25)",
+        "box.bg.default": "--color-surface",
+        "box.bg.checked": "--color-primary",
+        "box.bg.checked.hover": "--color-primary-hover",
+        "box.bg.error": "--color-danger",
+        "box.bg.success": "--color-success",
+        "box.border.default": "border(control)",
+        "box.border.hover": "--color-primary",
+        "box.border.error": "--color-danger",
+        "box.border.success": "--color-success",
+        "box.radius": "--radius-sm",
+        "checkmark.color": "--color-on-primary",
+        "label.color": "--color-text",
+        "label.color.error": "--color-danger",
+        "focus.ring": "ring() with --ring-offset: 2px",
+        "disabled.opacity": "--state-disabled-opacity",
+        "required.indicator": "--color-danger asterisk",
+        "shake.animation": "ui-form-shake",
+        "touch-target": "a11y.touch-target-pseudo (--control-min-touch)",
+        "spinner.color": "--_cmp-spinner-color → --color-primary (default), --color-on-primary (checked/indeterminate), --color-danger (error), --color-success (success)"
+    },
+    "spacing": {
+        "internal": {
+            "box-to-label": { "relationship": "lovers", "token": "xs" }
+        },
+        "external": {
+            "wrapper-to-helper": { "relationship": "lovers", "token": "xs" },
+            "wrapper-to-error": { "relationship": "lovers", "token": "xs" },
+            "checkbox-to-checkbox": { "relationship": "close_friends", "token": "sm" }
+        }
+    },
+    "constraints": [
+        "Never use raw hex colors — use design system tokens",
+        "Use logical CSS properties only",
+        "All transitions wrapped in @include a11y.motion-safe",
+        "Must handle forced-colors mode — Highlight for checked, GrayText for disabled",
+        "No validation logic — error/success props are visual only",
+        "Label prop is required",
+        "Native disabled (not aria-disabled)",
+        "Error takes precedence over success visually",
+        "Error shake skips initial render (firstRun guard)",
+        "Indeterminate is mutually exclusive with checked (checked wins)",
+        "User toggle clears indeterminate (UA convention)",
+        "Readonly is custom — native checkboxes ignore the readonly attribute. Toggling is blocked via click preventDefault, Space keydown preventDefault, and a change-event rollback that restores the controlled value if a stray event slips through",
+        "Checkmark + indeterminate dash rendered as inline SVG paths animated via stroke-dashoffset (pathLength=1)",
+        "Native input is visually hidden but stays focusable; visual focus ring is on .ui-checkbox-box via :has(:focus-visible)",
+        "CheckboxProps extends FormControlBaseProps"
+    ],
+    "a11y": [
+        "Native <input type='checkbox'> — full keyboard support (Space toggles)",
+        "Wrapper is a <label> — clicking anywhere toggles the input",
+        "aria-invalid='true' when error prop is truthy",
+        "aria-describedby dynamically updated for helper/error",
+        "Error message has role='alert'",
+        "aria-required='true' when required",
+        "aria-readonly='true' when readonly (mirrors custom intercept)",
+        "aria-busy='true' when loading",
+        "Auto-generated id enables FormField association",
+        "Focus ring on the visible box via :has(:focus-visible)",
+        "Forced-colors: Highlight for checked, GrayText for disabled, Highlight outline on focus",
+        "Custom box has aria-hidden='true' (decorative — input is the real control)",
+        "Error shake respects prefers-reduced-motion"
+    ],
+    "ai": {
+        "synonyms": [
+            "check box",
+            "tick box",
+            "toggle option",
+            "boolean input",
+            "multi-select option"
+        ],
+        "avoid": [
+            "div with role='checkbox' — use the native input via <Checkbox>",
+            "raw color values for box / checkmark — use design tokens",
+            "validation inside the component — belongs in Form/DynamicForm",
+            "Checkbox without a label prop"
+        ],
+        "patterns": [
+            "Basic: <Checkbox label=\"'Accept terms'\" />",
+            "Required: <Checkbox label=\"'I agree'\" required=\"true\" />",
+            "Controlled: <Checkbox label=\"'Subscribe'\" checked=\"isSubscribed\" onChange=\"toggle\" />",
+            "Indeterminate (select all): <Checkbox label=\"'Select all'\" indeterminate=\"someSelected\" checked=\"allSelected\" />",
+            "Helper text: <Checkbox label=\"'Marketing emails'\" helperText=\"'You can unsubscribe at any time'\" />",
+            "Error: <Checkbox label=\"'Accept terms'\" error=\"hasError\" errorMessage=\"'You must accept the terms'\" />",
+            "Group: <CheckboxGroup label=\"'Toppings'\"><Checkbox label=\"'Cheese'\" /><Checkbox label=\"'Pepperoni'\" /></CheckboxGroup>"
+        ]
+    },
+    "examples": [
+        {
+            "id": "basic",
+            "title": "Basic checkbox",
+            "pithy": "<Checkbox label=\"'Accept terms'\" />",
+            "assertions": [
+                "renders <input type='checkbox'>",
+                "label is visible",
+                "no axe violations"
+            ]
+        },
+        {
+            "id": "checked",
+            "title": "Pre-checked checkbox",
+            "pithy": "<Checkbox label=\"'Subscribe'\" checked=\"true\" />",
+            "assertions": ["input.checked === true", "data-checked on wrapper"]
+        },
+        {
+            "id": "indeterminate",
+            "title": "Indeterminate (select-all) checkbox",
+            "pithy": "<Checkbox label=\"'Select all'\" indeterminate=\"true\" />",
+            "assertions": [
+                "input.indeterminate === true",
+                "data-indeterminate on wrapper",
+                "dash visible"
+            ]
+        },
+        {
+            "id": "disabled",
+            "title": "Disabled checkbox",
+            "pithy": "<Checkbox label=\"'Locked'\" disabled=\"true\" />",
+            "assertions": ["input.disabled === true", "data-disabled on wrapper"]
+        },
+        {
+            "id": "readonly",
+            "title": "Readonly checkbox",
+            "pithy": "<Checkbox label=\"'Auto-set'\" readonly=\"true\" checked=\"true\" />",
+            "assertions": [
+                "click does not toggle",
+                "Space does not toggle",
+                "remains focusable"
+            ]
+        },
+        {
+            "id": "required",
+            "title": "Required checkbox",
+            "pithy": "<Checkbox label=\"'I agree'\" required=\"true\" />",
+            "assertions": ["aria-required on input", "asterisk visible on label"]
+        },
+        {
+            "id": "error",
+            "title": "Error with shake",
+            "pithy": "<Checkbox label=\"'Accept'\" error=\"hasError\" errorMessage=\"'Required'\" />",
+            "assertions": [
+                "aria-invalid on input",
+                "shake animation on transition",
+                "error message shown"
+            ]
+        },
+        {
+            "id": "success",
+            "title": "Success state",
+            "pithy": "<Checkbox label=\"'Verified'\" success=\"true\" checked=\"true\" />",
+            "assertions": ["data-success on wrapper", "green box fill"]
+        },
+        {
+            "id": "loading",
+            "title": "Loading state",
+            "pithy": "<Checkbox label=\"'Saving'\" loading=\"isSaving\" />",
+            "assertions": ["spinner visible", "aria-busy='true'"]
+        },
+        {
+            "id": "group",
+            "title": "Checkbox group with fieldset",
+            "pithy": "<CheckboxGroup label=\"'Toppings'\"><Checkbox label=\"'Cheese'\" name=\"'toppings'\" value=\"'cheese'\" /></CheckboxGroup>",
+            "assertions": [
+                "fieldset contains legend",
+                "data-slot='children' on fieldset",
+                "fieldset[disabled] cascades"
+            ]
+        }
+    ],
+    "designGuidance": {
+        "surface": "Box uses --color-surface unfilled, switching to --color-primary when checked or indeterminate. Hover deepens to --color-primary-hover.",
+        "depth": "No shadow by default. Focus ring via box-shadow ring() with 2px offset on the visible box.",
+        "borders": "Stable border width — only color changes across states.",
+        "interactivity": "Hover tints border. Active applies pressed state-background. Focus shows ring on the box. Error shakes on transition. Indeterminate replaces checkmark with a dash; user toggle clears it. Loading overlays spinner inside the box.",
+        "bestPractices": "Always provide a label. Use indeterminate for select-all summaries. Pair related checkboxes inside a <CheckboxGroup> with a legend. Use disabled (not readonly) when the value cannot change at all; use readonly when the value is meaningful but locked."
+    }
+}

package/dist/specs/atoms/forms/file-picker.pidl.json

@@ -0,0 +1,161 @@
+{
+    "kind": "component",
+    "id": "ui.file-picker",
+    "name": "FilePicker",
+    "displayName": "File Picker",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "forms",
+    "bidi": true,
+    "description": "Accessible file upload control with a click/drag-and-drop zone. Built on a semantic <label> wrapping a real focusable native <input type='file'> (no role='button'), validates type against `accept` and size against `maxSizeBytes`, shows an optional image preview, and surfaces inline errors via aria-live. No upload logic — the consumer wires `onSelect`.",
+    "props": [
+        {
+            "name": "accept",
+            "label": "Accept",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "default": "image/*",
+            "placeholder": "image/*",
+            "description": "Accept filter — forwarded to the input and used for type validation. Supports MIME types ('image/png'), wildcards ('image/*'), and extensions ('.webp'), comma-separated."
+        },
+        {
+            "name": "maxSizeBytes",
+            "label": "Max size (bytes)",
+            "editor": { "tab": "settings" },
+            "type": "number",
+            "default": 5242880,
+            "description": "Maximum accepted file size in bytes. Files over the limit are rejected with an inline error (default 5 MB)."
+        },
+        {
+            "name": "showPreview",
+            "label": "Show preview",
+            "editor": { "tab": "settings" },
+            "type": "boolean",
+            "default": true,
+            "description": "Render an image preview of the selected file. Image files only; ignored for other types."
+        },
+        {
+            "name": "hint",
+            "label": "Hint",
+            "type": "string",
+            "default": "Click or drag a file here",
+            "placeholder": "Click or drag a file here",
+            "description": "Instructional text shown inside the drop zone before a file is selected."
+        },
+        {
+            "name": "ariaLabel",
+            "label": "Accessible label",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "default": "Upload file — click or drag and drop",
+            "description": "Accessible name applied to the native input."
+        },
+        {
+            "name": "onSelect",
+            "type": "(file: File) => void | Promise<void>",
+            "required": true,
+            "description": "Called with the selected file once it passes type/size validation. May be async (e.g. an upload); a rejection surfaces an inline 'Upload failed' error, guarded so only the latest selection can set it."
+        }
+    ],
+    "events": ["change", "dragover", "dragenter", "dragleave", "drop"],
+    "slots": [],
+    "tokens": {
+        "zone.bg": "--color-surface-variant",
+        "zone.bg.hover": "--color-surface-hover",
+        "zone.border": "border-width-thin + border-style-dashed + --color-border",
+        "zone.border.hover": "--color-primary",
+        "zone.radius": "--radius-md",
+        "zone.padding": "--space-md (block) / --space-sm (inline)",
+        "hint.color": "--color-text-muted",
+        "hint.font-size": "--font-size-sm",
+        "error.color": "--color-danger",
+        "error.font-size": "--font-size-sm",
+        "focus.ring": "a11y.focus-ring via :has(.ui-file-picker-input:focus-visible)",
+        "preview.max-block": "calc(--control-min-height-md * 3) — three control-rows tall; scales with the a11y control-size preset"
+    },
+    "spacing": {
+        "internal": {
+            "zone-to-error": { "relationship": "lovers", "token": "xs" }
+        }
+    },
+    "constraints": [
+        "Never use raw hex colors — use design system tokens",
+        "Use logical CSS properties only",
+        "All transitions wrapped in @include a11y.motion-safe",
+        "Must handle forced-colors mode — ButtonText border on the drop zone",
+        "Drop zone is a <label> (no role='button') wrapping a real focusable <input> — no re-implemented button semantics",
+        "Native <input> is the focusable control — never aria-hidden or inert while focusable",
+        "No upload logic — onSelect is wired by the consumer",
+        "Object-URL previews are revoked on replace and teardown",
+        "Async error is guarded by a selection token so a superseded file cannot clobber the current state"
+    ],
+    "a11y": [
+        "Semantic <label> wraps a native <input type='file'> — clicking the zone opens the file dialog natively",
+        "Enter/Space on the focused input opens the dialog natively (no custom key handling)",
+        "Input carries the accessible name via aria-label",
+        "Focus ring on the visible zone via :has(.ui-file-picker-input:focus-visible)",
+        "Inline error uses aria-live='assertive' for immediate announcement",
+        "Forced-colors: solid ButtonText border on the drop zone"
+    ],
+    "ai": {
+        "synonyms": [
+            "file upload",
+            "image upload",
+            "drop zone",
+            "dropzone",
+            "file input",
+            "upload field",
+            "attach file",
+            "image picker"
+        ],
+        "avoid": [
+            "div with role='button' for the drop zone — use a <label> wrapping the input",
+            "aria-hidden or inert on the focusable file input",
+            "raw color values — use design tokens",
+            "upload/persistence logic inside the component — wire it via onSelect"
+        ],
+        "patterns": [
+            "Basic: <FilePicker onSelect=\"handleFile\" />",
+            "Restricted type + size: <FilePicker onSelect=\"handleFile\" accept=\"'image/png,.webp'\" maxSizeBytes=\"1048576\" />",
+            "No preview: <FilePicker onSelect=\"handleFile\" showPreview=\"false\" />",
+            "Custom copy: <FilePicker onSelect=\"handleFile\" hint=\"'Click or drag image here'\" ariaLabel=\"'Upload image'\" />"
+        ]
+    },
+    "examples": [
+        {
+            "id": "basic",
+            "title": "Basic file picker",
+            "pithy": "<FilePicker onSelect=\"handleFile\" />",
+            "assertions": [
+                "renders a <label> drop zone wrapping <input type='file'>",
+                "input has no inert/aria-hidden",
+                "no axe violations"
+            ]
+        },
+        {
+            "id": "accept",
+            "title": "Restricted accept filter",
+            "pithy": "<FilePicker onSelect=\"handleFile\" accept=\"'image/png,.webp'\" />",
+            "assertions": [
+                "input accept attribute is 'image/png,.webp'",
+                "non-matching files are rejected with an inline error"
+            ]
+        },
+        {
+            "id": "max-size",
+            "title": "Size limit",
+            "pithy": "<FilePicker onSelect=\"handleFile\" maxSizeBytes=\"4\" />",
+            "assertions": [
+                "a file over the limit is rejected",
+                "error text mentions the maximum size"
+            ]
+        }
+    ],
+    "designGuidance": {
+        "surface": "Drop zone sits on --color-surface-variant with a dashed --color-border; hover deepens to --color-surface-hover and the border tints to --color-primary.",
+        "depth": "Flat by design — a dashed outline communicates the drop affordance without elevation. Focus shows the ring on the zone.",
+        "borders": "Dashed thin border signals 'drop here'; only color changes on hover/drag-over. Radius --radius-md.",
+        "interactivity": "Click or keyboard activates the native dialog; dragging a file over highlights the zone (drag-over state); a selected image renders a capped preview inside the zone. Invalid type/size or a failed async onSelect shows an inline aria-live error.",
+        "bestPractices": "Use for a single-file upload field. Constrain with `accept` and `maxSizeBytes`. Keep `showPreview` on for images so users confirm their selection. Wire `onSelect` to your upload/asset flow — the component never persists files itself."
+    }
+}