@pithyjs/pidl-catalog 0.1.0-beta.0

package/dist/specs/organisms/content/card.pidl.json

@@ -0,0 +1,283 @@
+{
+    "kind": "component",
+    "id": "ui.card",
+    "name": "Card",
+    "displayName": "Card",
+    "version": "0.1.0",
+    "level": "organism",
+    "domain": "content",
+    "bidi": true,
+    "description": "Content container with named slots (media, header, body, footer), five variants, two orientations, and a pseudo-link overlay for full-card navigation. Semantic <article> root with container-query sizing and paint containment.",
+    "props": [
+        {
+            "name": "variant",
+            "label": "Variant",
+            "type": "enum",
+            "enum": ["default", "outlined", "elevated", "subtle", "ghost"],
+            "default": "default",
+            "description": "Visual shape. 'default' = surface + hairline + shadow-xs. 'outlined' = surface + hairline, no shadow. 'elevated' = surface + shadow-md (also keeps a hairline for cross-mode edge readability). 'subtle' = surface-variant + hairline, no shadow. 'ghost' = transparent + no border (chrome fades in on hover)."
+        },
+        {
+            "name": "padding",
+            "label": "Padding",
+            "editor": { "tab": "layout" },
+            "type": "enum",
+            "enum": ["none", "sm", "md", "lg"],
+            "default": "md",
+            "description": "Inset padding. Use 'none' to bleed media to the card edges (blog cards, product tiles)."
+        },
+        {
+            "name": "radius",
+            "label": "Radius",
+            "type": "enum",
+            "enum": ["none", "sm", "md", "lg"],
+            "default": "md",
+            "description": "Corner radius. Use 'none' for full-bleed mobile heroes."
+        },
+        {
+            "name": "orientation",
+            "label": "Orientation",
+            "editor": { "tab": "layout" },
+            "type": "enum",
+            "enum": ["vertical", "horizontal"],
+            "default": "vertical",
+            "description": "'horizontal' places the media slot at the inline-start and runs header/body/footer alongside. Below the 'sm' container breakpoint (30rem / 480px) the layout auto-stacks to vertical via @container query so narrow cards remain readable."
+        },
+        {
+            "name": "mediaAspect",
+            "label": "Media aspect",
+            "editor": { "tab": "layout" },
+            "type": "enum",
+            "enum": ["1/1", "4/3", "16/9", "3/2", "21/9"],
+            "description": "Aspect ratio for the media slot. Optional in vertical mode (defaults to intrinsic). In horizontal mode the aspect is locked to '16/9' when unset so thumbnails stay rhythmically consistent across lists."
+        },
+        {
+            "name": "mediaOverlay",
+            "label": "Media overlay",
+            "type": "boolean",
+            "default": false,
+            "description": "Flips the card topology: the media slot fills the whole card (ignoring padding) and the header / body / footer collapse into a caption group that rides a design-system gradient scrim at the block-end with inverse text colors. Canonical pattern for hero tiles, gallery cards, and marketing listings."
+        },
+        {
+            "name": "clickable",
+            "label": "Clickable",
+            "type": "boolean",
+            "default": false,
+            "description": "Renders a stretched <a class='ui-card-link'> overlay so the whole card is a navigation target. Internal buttons/links stay interactive via z-index layering."
+        },
+        {
+            "name": "href",
+            "label": "Link URL",
+            "type": "string",
+            "description": "Target URL for the clickable overlay. Validated via isSafeHref — unsafe schemes (javascript:, data:, vbscript:) are rejected with a DEV warning and the overlay is not rendered. Required when clickable is true."
+        },
+        {
+            "name": "linkLabel",
+            "label": "Link label",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Accessible label for the stretched link. Defaults to ariaLabel, or the trimmed text of the first heading in the header slot, or 'Open'."
+        },
+        {
+            "name": "disabled",
+            "label": "Disabled",
+            "editor": { "tab": "settings" },
+            "type": "boolean | () => boolean",
+            "default": false,
+            "reactive": true,
+            "description": "Dims the card, sets aria-disabled, and marks the article inert so all descendants (including the link overlay) are removed from focus, hit-testing, and the a11y tree. Accepts a boolean or a reactive getter (() => boolean) — a getter wires an internal effect so the state flips without remounting."
+        },
+        {
+            "name": "selected",
+            "label": "Selected",
+            "editor": { "tab": "settings" },
+            "type": "boolean | () => boolean",
+            "default": false,
+            "reactive": true,
+            "description": "Applies a primary-colored border and inner ring. When combined with clickable (and not disabled), also sets aria-current='true'. Accepts a boolean or a reactive getter (() => boolean) — a getter wires an internal effect so selection flips without remounting. Use for plan pickers, filter card grids, and selectable previews."
+        },
+        {
+            "name": "eyebrow",
+            "label": "Eyebrow",
+            "type": "string",
+            "description": "Short primary-colored uppercase kicker rendered above the heading in the header slot (auto-injected). Use for categories and editorial tags ('Engineering', 'Design', 'Changelog'). Mirrors the Hero / CTA section eyebrow pattern so cards-in-sections read as one editorial voice."
+        },
+        {
+            "name": "ariaLabel",
+            "label": "ARIA label",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Fallback accessible name for the <article>. Used when there is no heading in the header slot and no ariaLabelledBy is provided."
+        },
+        {
+            "name": "ariaLabelledBy",
+            "label": "ARIA labelled by",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "id of an element outside the card that labels it. Takes precedence over the auto-detected heading id and over ariaLabel."
+        },
+        {
+            "name": "id",
+            "label": "Anchor ID",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Anchor id on the <article> root. Useful for deep-linking or for wiring a view-transition-name via a utility class."
+        }
+    ],
+    "requiredProps": [],
+    "events": [],
+    "slots": [
+        {
+            "name": "media",
+            "displayName": "Media",
+            "description": "Full-bleed image, icon, or video at the top (vertical) or inline-start (horizontal). Rendered inside .ui-card-media with optional aspect ratio lock.",
+            "accepts": ["ui.image", "ui.icon"],
+            "max": 1,
+            "media": "fill"
+        },
+        {
+            "name": "header",
+            "displayName": "Header",
+            "description": "Heading, eyebrow, and meta. Rendered inside a semantic <header>. Auto-generates aria-labelledby from the first heading.",
+            "accepts": ["ui.heading", "ui.text", "ui.badge"]
+        },
+        {
+            "name": "default",
+            "displayName": "Body",
+            "description": "Primary content area — paragraphs, lists, form fields. Rendered inside .ui-card-layout as the default projection target."
+        },
+        {
+            "name": "footer",
+            "displayName": "Footer",
+            "description": "Tags, timestamps, CTAs. Rendered inside a semantic <footer>. Pinned to the block-end via margin-block-start: auto.",
+            "accepts": ["ui.text", "ui.button", "ui.badge"]
+        }
+    ],
+    "tokens": {
+        "surface.default": "--color-surface + --border-width-hairline --color-border + --shadow-xs",
+        "surface.outlined": "--color-surface + --border-width-hairline --color-border, no shadow",
+        "surface.elevated": "--color-surface + --border-width-hairline --color-border + --shadow-md (hairline kept for cross-mode edge readability)",
+        "surface.subtle": "--color-surface-variant + --border-width-hairline --color-border, no shadow",
+        "surface.ghost": "transparent, no border — chrome fades in on hover via surface-variant tint",
+        "padding.none": "0 (media bleeds to card edges)",
+        "padding.sm": "--space-sm",
+        "padding.md": "--space-md (default)",
+        "padding.lg": "--space-lg",
+        "radius.none": "0",
+        "radius.sm": "--radius-sm",
+        "radius.md": "--radius-md (default)",
+        "radius.lg": "--radius-lg",
+        "gap.header-to-body": "--space-sm (Close Friends — heading to body copy)",
+        "gap.body-paragraph": "--space-sm (Close Friends — paragraph rhythm inside the body slot)",
+        "gap.footer-inline": "--space-sm (Close Friends — tag chips, timestamps, meta)",
+        "gap.header-internal": "--space-xs (Lovers / Close Friends — eyebrow ↔ title ↔ meta)",
+        "gap.horizontal.media-to-body": "--space-md (Friends — distinct clusters)",
+        "border.hover.clickable": "color-mix(in oklch, --color-primary 25%, --color-border) — primary infusion, not a hard swap",
+        "shadow.hover.default": "--shadow-md (from --shadow-xs)",
+        "shadow.hover.outlined": "--shadow-sm (from none)",
+        "shadow.hover.elevated": "--shadow-xl (from --shadow-md)",
+        "shadow.hover.subtle": "--shadow-sm (from none) — no translate, keeps list stable",
+        "shadow.hover.ghost": "chrome appears: --color-surface-variant bg + --color-border border",
+        "motion.translate": "--motion-distance-subtle — clickable cards only (not subtle, never disabled)",
+        "motion.duration": "--motion-duration-normal",
+        "motion.easing": "--motion-easing-standard",
+        "selected.border": "--color-primary",
+        "selected.ring": "inset 0 0 0 --border-width-thin --color-primary (belt-and-suspenders emphasis)",
+        "disabled.opacity": "--state-disabled-opacity",
+        "focus.ring": "a11y.focus-ring — painted on the whole article via :has(.ui-card-link:focus-visible)"
+    },
+    "spacing": {
+        "header-to-body": "--space-sm (Close Friends — tightly coupled meaning)",
+        "body-to-footer": "--space-sm (Close Friends — footer is the tail of the same content cluster)",
+        "media-to-header.vertical": "--space-md (Friends — the image is a distinct content cluster from the text block below it; flex gap --space-sm + supplemental margin = --space-md total)",
+        "media-to-body.horizontal": "--space-md (Friends — distinct visual clusters)",
+        "header-internal": "--space-xs (Lovers — eyebrow, title, and meta are one typographic unit)",
+        "footer-pinned": "margin-block-start: auto (pins footer to the block-end so cards in a grid line up at the base)",
+        "footer-inline": "--space-sm (Close Friends — tag chips, timestamps)",
+        "grid-between-cards": "--space-md (Friends — cards in the same grid are peers)"
+    },
+    "designGuidance": {
+        "surface": "Five variants cover the full surface vocabulary: 'default' is the workhorse with a hairline + shadow-xs; 'outlined' reads as a form-group container (no shadow); 'elevated' is the featured/hero card with shadow-md AND a hairline (shadow conveys presence, the hairline keeps the edge readable in dark mode and on tinted backgrounds); 'subtle' is the settings-pane / feature-card style on surface-variant; 'ghost' is for list-row cards that only reveal chrome on hover. Never stack shadows — the tokens encode elevation levels. Never pair elevated with outlined — it reads as uncertainty.",
+        "depth": "Static cards never translate on hover — lifting every hover cheapens the motion. Only clickable cards translate by --motion-distance-subtle. 'subtle' is the deliberate exception within clickable: it gains a shadow but stays flat so long lists don't jitter. 'elevated' carries shadow-md at rest; on hover it climbs to shadow-xl without gaining new borders.",
+        "borders": "Borders are always a hairline, never thicker. The only exception is the selected state's inner ring (--border-width-thin via inset box-shadow) which pairs with the colored outer border for double emphasis. On hover, borders tint toward primary via color-mix(25%) — a subtle infusion that signals interactivity without swapping values hard. Forced-colors mode always draws a 1px ButtonText border and suppresses shadows.",
+        "interactivity": "Clickable cards use the pseudo-link pattern: a stretched <a class='ui-card-link'> fills the article at z-index 1 so mouse clicks anywhere on the card body reach the anchor. The layout wrapper stays at z-index auto (no explicit z-index — any value would create a stacking context and trap descendants below the overlay); interactive descendants (buttons, tag chips, inline links, form controls) are raised to z-index 2 so they still receive their own clicks. Keyboard focus paints the focus ring on the whole <article> via :has(.ui-card-link:focus-visible) — the card *is* the focus indicator, not the invisible overlay. Selected state is a separate axis: combine with clickable for plan pickers (aria-current='true'), or use alone as a static highlight.",
+        "bestPractices": [
+            "Prefer 'default' for content lists and dashboards. Reach for 'elevated' only for hero/featured cards — too many elevated cards compete for attention.",
+            "Use 'subtle' inside sections that already sit on --color-surface (feature grids, settings panes) — it reads as a secondary container.",
+            "Use 'ghost' for list rows that need a hit target without competing with the surrounding content (search results, command-palette results).",
+            "Pair padding='none' with a media slot when you want the image edge-to-edge (blog cards, product tiles). Pair padding='lg' + no media for quote cards or callouts.",
+            "Horizontal orientation is for blog listings and search results. It auto-stacks to vertical below the 'sm' container breakpoint via the card's own container query, so reach for it when that responsive collapse is the desired behavior.",
+            "Don't wrap an entire Card in <a> yourself — use clickable+href so internal interactive elements still work. If you need onClick instead of navigation, nest a <Button class='u-absolute u-inset-0'> inside with transparent styling (V0.2 will add a first-class onClick card).",
+            "When a heading lives in the header slot of a clickable card, aria-labelledby is auto-wired. If no heading is present, pass ariaLabel for an explicit accessible name.",
+            "Don't use variant='elevated' on surface-variant backgrounds — the shadow reads as dirt. Use 'outlined' or 'subtle' instead."
+        ]
+    },
+    "constraints": [
+        "Root element is a semantic <article>",
+        "All CSS uses logical properties (inline-start/end, block-start/end) — RTL-safe",
+        "Design-system-controlled visual values use tokens — every color/space/font-size/radius/shadow/duration uses a design system token or a --_card-* custom property that resolves to one. Intrinsic layout math (aspect ratios, percentages, clamp()/minmax() bounds, and container-query thresholds) is allowed to use dimensional units via named Sass variables scoped to the component stylesheet",
+        "Slot wrappers (.ui-card-media, .ui-card-header, .ui-card-body, .ui-card-footer) are only rendered when the slot has content — no empty DOM wrappers",
+        "In horizontal orientation, mediaAspect defaults to '16/9' when unset so lists stay visually consistent. Below the 'sm' container breakpoint (30rem) the horizontal layout auto-stacks to vertical via @container query",
+        "In clickable mode, the pseudo-link <a class='ui-card-link'> sits at z-index 1 so mouse clicks on the card body reach the anchor; interactive descendants (buttons, inner links, chips) are raised to z-index 2 so they still receive their own clicks",
+        "Disabled cards set aria-disabled='true' AND the native inert attribute — descendants are removed from focus, hit-testing, and the a11y tree",
+        "Selected cards get aria-current='true' only when also clickable AND not disabled (aria-current has no meaning without a navigation context, and a disabled card is inert)",
+        "Focus ring is painted on the whole article via :has(.ui-card-link:focus-visible) — the overlay is never the visible focus indicator",
+        "When clickable=true, href is required — the component warns in DEV and omits the overlay link when href is absent or unsafe",
+        "Unsafe hrefs (javascript:, data:, vbscript:) are rejected via isSafeHref — DEV warning + the overlay is not rendered",
+        "All transitions are gated by @include a11y.motion-safe so prefers-reduced-motion zeroes translate + shadow transitions"
+    ],
+    "a11y": {
+        "landmarks": [
+            "Semantic <article> element — a self-contained composition (blog post preview, product card, plan card, etc.)"
+        ],
+        "keyboard": {
+            "clickable": "The stretched <a class='ui-card-link'> is a real anchor — native Tab/Shift+Tab focus, Enter activates navigation.",
+            "innerInteractives": "Internal buttons/links receive their own focus stops. In clickable cards, interactive descendants (buttons, inner links, chips, form controls) are raised to z-index 2 so they win click events over the z-index 1 overlay.",
+            "disabled": "inert blocks Tab, click, and screen-reader interaction for the whole card and every descendant."
+        },
+        "focus": {
+            "visible": "When the overlay link takes keyboard focus, :has(.ui-card-link:focus-visible) paints the design-system focus ring on the whole article — the card itself is the focus indicator.",
+            "innerFocus": "Focus on an inner button/link keeps that element's own focus ring; the card paints a subtle :focus-within border-tint to telegraph 'something inside me has focus'."
+        },
+        "aria": {
+            "root": "<article>",
+            "labelledBy": "When clickable + a heading exists in the header slot, an auto-generated id is attached to the heading and the article receives aria-labelledby pointing at it. Explicit ariaLabelledBy always wins.",
+            "label": "Accessible name fallback chain: ariaLabelledBy > heading (auto-id) > ariaLabel > linkLabel > DEV warning. linkLabel is a last-resort fallback so clickable cards that set it but forget ariaLabel still get an accessible name on the <article>.",
+            "current": "Selected + clickable cards set aria-current='true' (unless also disabled) so AT announce 'current page/item'.",
+            "disabled": "data-disabled='true' + aria-disabled='true' + inert attribute"
+        },
+        "forcedColors": "forced-colors mode renders a 1px ButtonText border (2px Highlight when selected), suppresses shadows, and outlines the overlay with Highlight on focus — WCAG 1.4.1 parity.",
+        "motion": {
+            "reducedMotion": "All transitions (background, border, shadow, translate) are wrapped in @include a11y.motion-safe — prefers-reduced-motion zeroes duration. WCAG 2.3.3 satisfied.",
+            "staticCards": "Non-clickable cards never translate on hover — motion is reserved as a signal of interactivity."
+        },
+        "contentAssertions": "When clickable, the overlay anchor always has an accessible name. Fallback chain: aria-label from linkLabel > aria-labelledby forwarded from ariaLabelledBy > aria-labelledby pointing at the heading's auto-id (so the name stays in sync with reactive heading text) > aria-label from ariaLabel > visually-hidden 'Open' span."
+    },
+    "ai": {
+        "synonyms": [
+            "card",
+            "tile",
+            "panel",
+            "surface",
+            "content block",
+            "article card",
+            "feature card",
+            "product card",
+            "plan card",
+            "blog card"
+        ],
+        "avoid": [
+            "<div class='card'> — use <Card> with a semantic <article> root and slot API",
+            "Wrapping the whole card in <a href> — use clickable+href so internal interactive children still work",
+            "onClick on the card with role='button' — accessibility-hostile and ambiguous with inner buttons; navigate with clickable+href, or nest a visible <Button>",
+            "Stacking shadows manually — the variant tokens encode the right elevation",
+            "variant='elevated' on a surface-variant background — the shadow reads as dirt"
+        ],
+        "patterns": [
+            "Blog preview: <Card variant=\"'default'\" padding=\"'none'\" clickable=\"true\" href=\"'/post/hello'\"><img data-slot='media' ...><header data-slot='header'><Heading level='3'>Hello</Heading></header><Text>Excerpt…</Text><footer data-slot='footer'><Text size=\"'sm'\">3 min</Text></footer></Card>",
+            "Plan picker: <Card variant=\"'outlined'\" selected=\"isSelected\" clickable=\"true\" href=\"'/pricing?plan=pro'\"><header data-slot='header'><Heading level='3'>Pro</Heading></header><Text>$19/mo</Text></Card>",
+            "Horizontal search result: <Card orientation=\"'horizontal'\" variant=\"'ghost'\" clickable=\"true\" href=\"'/result/42'\"><img data-slot='media' ...><header data-slot='header'><Heading level='4'>Result title</Heading></header><Text>Match snippet…</Text></Card>",
+            "Feature tile (inside FeaturesSection-style grid): <Card variant=\"'subtle'\" padding=\"'lg'\"><header data-slot='header'><Icon name=\"'zap'\"/><Heading level='3'>Fast</Heading></header><Text>Reactive updates stay O(1).</Text></Card>"
+        ]
+    }
+}

package/dist/specs/organisms/feedback/alert-dialog.pidl.json

@@ -0,0 +1,158 @@
+{
+    "kind": "component",
+    "id": "ui.alert-dialog",
+    "name": "AlertDialog",
+    "displayName": "Alert Dialog",
+    "version": "0.1.0",
+    "level": "organism",
+    "domain": "feedback",
+    "studioReady": false,
+    "bidi": true,
+    "description": "Confirmation dialog built on <Modal> with role='alertdialog'. A titled message with a tone-colored confirm action and an optional cancel — for destructive confirms and acknowledgements. Does not dismiss on backdrop click; Escape cancels.",
+    "props": [
+        {
+            "name": "open",
+            "label": "Open",
+            "type": "boolean | () => boolean",
+            "reactive": true,
+            "required": true,
+            "description": "Visibility state. Static boolean or a () => boolean accessor. The dialog mounts to <body> when true and unmounts when false."
+        },
+        {
+            "name": "title",
+            "label": "Title",
+            "type": "string",
+            "required": true,
+            "placeholder": "Clear page",
+            "description": "Accessible name and visible heading for the dialog."
+        },
+        {
+            "name": "message",
+            "label": "Message",
+            "type": "string | () => string",
+            "reactive": true,
+            "required": true,
+            "placeholder": "Remove all blocks from this page? You can undo this.",
+            "description": "Body copy explaining the action. Static string or a () => string accessor for reactive copy (e.g. a live count)."
+        },
+        {
+            "name": "tone",
+            "label": "Tone",
+            "type": "enum",
+            "enum": ["info", "warning", "danger"],
+            "default": "info",
+            "description": "Semantic tone — colors the confirm button and the icon (info, warning, danger)."
+        },
+        {
+            "name": "icon",
+            "label": "Icon",
+            "editor": { "tab": "settings" },
+            "type": "icon",
+            "required": false,
+            "description": "Optional icon shown beside the title, tinted by tone."
+        },
+        {
+            "name": "confirmLabel",
+            "label": "Confirm label",
+            "type": "string",
+            "required": false,
+            "placeholder": "Confirm",
+            "description": "Label for the confirm button. Defaults to 'Confirm' when onConfirm is set, else 'OK'."
+        },
+        {
+            "name": "cancelLabel",
+            "label": "Cancel label",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "default": "Cancel",
+            "description": "Label for the cancel button (shown only when onConfirm is provided)."
+        },
+        {
+            "name": "dialogId",
+            "label": "Dialog id",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "required": false,
+            "description": "Sets id on the dialog element — enables aria-controls on the trigger button."
+        }
+    ],
+    "events": [
+        {
+            "name": "onClose",
+            "description": "Requested close — fired on Escape, Cancel, or after Confirm. The consumer flips open to false."
+        },
+        {
+            "name": "onConfirm",
+            "description": "The user confirmed the action. When provided, a Cancel button is shown; onClose runs immediately after."
+        }
+    ],
+    "tokens": {
+        "color": "--color-info, --color-warning, --color-danger (tone), --color-text-muted (message)",
+        "spacing": "--space-sm (head gap, actions gap, content gap), --space-md (actions offset)",
+        "inherits": "surface, backdrop, radius, shadow, and layer from <Modal>"
+    },
+    "spacing": {
+        "head-icon": "--space-sm (close friends — icon ↔ title)",
+        "message-actions": "--space-md (actions sit below the message)"
+    },
+    "constraints": [
+        "Built on <Modal role='alertdialog'> — inherits focus trap, scroll lock, and portal-to-body",
+        "closeOnBackdrop is forced off: a destructive confirm requires an explicit choice (Escape still cancels)",
+        "Initial focus lands on Cancel when present, else the confirm button",
+        "Without onConfirm the dialog is acknowledge-only — a single confirm button (default label 'OK')"
+    ],
+    "a11y": [
+        "role='alertdialog' — screen readers announce the content immediately and expect a response",
+        "aria-labelledby wired to the visible title heading",
+        "Focus trapped inside the dialog and restored to the trigger on close (via Modal)",
+        "Backdrop click does not dismiss; Escape cancels"
+    ],
+    "ai": {
+        "synonyms": [
+            "alert",
+            "confirm",
+            "confirmation",
+            "are you sure",
+            "destructive confirm",
+            "prompt"
+        ],
+        "avoid": [
+            "using a plain <Modal role='dialog'> for a destructive confirm — alertdialog is required so the message is announced immediately",
+            "omitting onConfirm when the action needs an explicit yes/no — that renders an acknowledge-only OK dialog",
+            "long paragraphs in message — keep it to the action and its consequence"
+        ],
+        "patterns": [
+            "Destructive confirm: <AlertDialog open=\"isOpen\" onClose=\"close\" onConfirm=\"clear\" tone=\"'danger'\" icon=\"'trash'\" title=\"'Clear page'\" message=\"'Remove all blocks? You can undo this.'\" confirmLabel=\"'Clear page'\" />",
+            "Acknowledge-only: <AlertDialog open=\"isOpen\" onClose=\"close\" title=\"'Saved'\" message=\"'Your changes are saved.'\" />"
+        ]
+    },
+    "designGuidance": {
+        "surface": "Inherits the Modal surface and backdrop; the confirm button and icon carry the tone color.",
+        "depth": "Elevated as a Modal layer above the page.",
+        "borders": "Inherited from Modal (hairline; CanvasText in forced-colors).",
+        "interactivity": "Confirm runs the action then closes; Cancel/Escape dismiss; backdrop click is inert.",
+        "darkMode": "Adapts via --color-* tokens; tone colors resolve per theme."
+    },
+    "examples": [
+        {
+            "id": "confirm",
+            "title": "Destructive confirm",
+            "pithy": "<AlertDialog open=\"true\" onClose=\"close\" onConfirm=\"clear\" tone=\"'danger'\" title=\"'Clear page'\" message=\"'Remove all blocks?'\" confirmLabel=\"'Clear page'\" />",
+            "assertions": [
+                "renders role='alertdialog'",
+                "confirm button has data-color='danger'",
+                "a Cancel button is present"
+            ]
+        },
+        {
+            "id": "acknowledge",
+            "title": "Acknowledge-only",
+            "pithy": "<AlertDialog open=\"true\" onClose=\"close\" title=\"'Saved'\" message=\"'Your changes are saved.'\" />",
+            "assertions": [
+                "a single 'OK' button",
+                "no Cancel button",
+                "confirm button data-color='info'"
+            ]
+        }
+    ]
+}

package/dist/specs/organisms/feedback/modal.pidl.json

@@ -0,0 +1,133 @@
+{
+    "kind": "component",
+    "id": "ui.modal",
+    "name": "Modal",
+    "displayName": "Modal",
+    "version": "0.1.0",
+    "level": "organism",
+    "domain": "feedback",
+    "studioReady": false,
+    "bidi": true,
+    "description": "Viewport-level dialog: a centered surface over a dimming backdrop. Portals to <body>, traps focus and locks body scroll via @pithyjs/core's FocusTrap, and closes on Escape or backdrop click. Reactive open state.",
+    "props": [
+        {
+            "name": "open",
+            "label": "Open",
+            "type": "boolean | () => boolean",
+            "reactive": true,
+            "required": true,
+            "description": "Visibility state. Static boolean or a () => boolean accessor. The dialog mounts to <body> when true and unmounts when false."
+        },
+        {
+            "name": "title",
+            "label": "Title",
+            "type": "string",
+            "required": true,
+            "placeholder": "Publish",
+            "description": "Accessible name for the dialog. Used as aria-label unless titleId is provided."
+        },
+        {
+            "name": "titleId",
+            "label": "Title element id",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "required": false,
+            "description": "Id of a visible title element inside the content — wired as aria-labelledby (takes precedence over title)."
+        },
+        {
+            "name": "dialogId",
+            "label": "Dialog id",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "required": false,
+            "description": "Sets id on the dialog element — enables aria-controls on the trigger button."
+        },
+        {
+            "name": "closeOnBackdrop",
+            "label": "Close on backdrop click",
+            "editor": { "tab": "settings" },
+            "type": "boolean",
+            "default": true,
+            "description": "Close when the backdrop (outside the dialog) is clicked."
+        },
+        {
+            "name": "closeOnEscape",
+            "label": "Close on Escape",
+            "editor": { "tab": "settings" },
+            "type": "boolean",
+            "default": true,
+            "description": "Close when Escape is pressed. Consumed in the capture phase so the dialog wins over global handlers."
+        }
+    ],
+    "events": [
+        {
+            "name": "onClose",
+            "description": "Requested close — fired on Escape, backdrop click, or any programmatic dismiss. The consumer flips open to false."
+        }
+    ],
+    "slots": [{ "name": "default", "displayName": "Content" }],
+    "tokens": {
+        "color": "--color-surface, --color-text, --color-border, --color-overlay-rgb (scrim)",
+        "spacing": "--space-lg (dialog padding), --space-md (backdrop padding, content gap)",
+        "radius": "--radius-lg (dialog)",
+        "shadow": "--shadow-xl (dialog)",
+        "border": "--border-width-hairline (idle), --border-width-thin (forced-colors)",
+        "layer": "--z-modal (backdrop stacking)",
+        "motion": "--motion-duration-fast, --motion-duration-normal, --motion-easing-standard, --motion-easing-emphasized"
+    },
+    "spacing": {
+        "backdrop-inset": "--space-md (gutter so the dialog never touches the viewport edge)",
+        "dialog-content": "--space-md (friends — stacked content regions inside the dialog)"
+    },
+    "constraints": [
+        "title (or titleId) is required — DEV warning when both are missing, to prevent an unnamed dialog",
+        "Portals to <body>; the returned el is a hidden anchor until open, so template placement never shows a stray scrim",
+        "Escape is consumed in the capture phase (stopPropagation) so the dialog closes before global keydown handlers fire",
+        "Backdrop click only closes when the target is the backdrop itself — clicks inside the dialog do not dismiss"
+    ],
+    "a11y": [
+        "role='dialog' + aria-modal='true' on the dialog surface",
+        "aria-labelledby (titleId) when a visible title is present, else aria-label (title)",
+        "Focus is trapped inside the dialog and restored to the trigger on close (FocusTrap)",
+        "Body scroll is locked while open (FocusTrap preventScroll)",
+        "Backdrop scrim and entrance animation respect prefers-reduced-motion",
+        "Forced-colors: explicit CanvasText border on the dialog surface"
+    ],
+    "ai": {
+        "synonyms": ["modal", "dialog", "overlay", "popup", "sheet", "lightbox"],
+        "avoid": [
+            "a hand-rolled fixed-position div with a backdrop — use <Modal> so focus trap, scroll lock, Escape, and aria-modal are correct",
+            "leaving title empty — every dialog needs an accessible name",
+            "putting the trigger button inside the Modal content — the trigger lives outside and drives the open prop"
+        ],
+        "patterns": [
+            "Confirm dialog: <Modal open=\"isOpen\" onClose=\"close\" title=\"'Delete page?'\">…content…</Modal>",
+            "Labelled by a visible heading: <Modal open=\"isOpen\" onClose=\"close\" title=\"'Publish'\" titleId=\"'publish-title'\"><Heading id=\"'publish-title'\">Publish</Heading>…</Modal>"
+        ]
+    },
+    "designGuidance": {
+        "surface": "Dialog uses --color-surface with a hairline border; the backdrop is a translucent scrim over --color-overlay-rgb.",
+        "depth": "Elevated with --shadow-xl to read as a layer above the page.",
+        "borders": "Hairline border on the dialog; forced-colors swaps to a CanvasText border.",
+        "interactivity": "Backdrop click and Escape dismiss; content inside is fully interactive and focus-trapped.",
+        "darkMode": "Adapts automatically via --color-* tokens; the scrim uses the theme's overlay color."
+    },
+    "examples": [
+        {
+            "id": "open",
+            "title": "Open modal",
+            "pithy": "<Modal open=\"true\" onClose=\"close\" title=\"'Publish'\"><Text>Ready to ship.</Text></Modal>",
+            "assertions": [
+                "renders a <div class='ui-modal' role='dialog'>",
+                "aria-modal='true'",
+                "aria-label='Publish'"
+            ]
+        },
+        {
+            "id": "labelledby",
+            "title": "Labelled by a visible title",
+            "pithy": "<Modal open=\"true\" onClose=\"close\" title=\"'Publish'\" titleId=\"'publish-title'\"><Heading id=\"'publish-title'\">Publish</Heading></Modal>",
+            "assertions": ["aria-labelledby='publish-title'", "aria-label not set"]
+        }
+    ]
+}