@pithyjs/pidl-catalog 0.1.0-beta.3 → 0.1.0-beta.7

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

@@ -0,0 +1,298 @@
+{
+    "kind": "component",
+    "id": "ui.slider",
+    "name": "Slider",
+    "displayName": "Slider",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "forms",
+    "icon": "sliders-horizontal",
+    "bidi": true,
+    "description": "Range slider atom built on a native <input type='range'>, so the slider role and keyboard (arrows, Page Up/Down, Home/End) come from the browser. Tokenised custom track and thumb with a filled portion, optional visible label and value readout, a formatter for the readout and aria-valuetext, error/success states, helper/error text and full a11y wiring.",
+    "props": [
+        {
+            "name": "id",
+            "label": "ID",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Explicit input ID — overrides the auto-generated ID."
+        },
+        {
+            "name": "name",
+            "label": "Name",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Input name attribute for form submission."
+        },
+        {
+            "name": "label",
+            "label": "Label",
+            "type": "string",
+            "required": true,
+            "placeholder": "Volume",
+            "description": "Accessible label — aria-label on the input, or visible <label for> text when showLabel is true. Always required."
+        },
+        {
+            "name": "value",
+            "reactive": true,
+            "label": "Value",
+            "editor": { "type": "number" },
+            "type": "number | Signal<number>",
+            "description": "Current value — static number or signal accessor for a controlled slider. A drag is only overwritten when the accessor's value changes. A numeric string is parsed as a number."
+        },
+        {
+            "name": "min",
+            "label": "Min",
+            "editor": { "type": "number" },
+            "type": "number",
+            "default": 0,
+            "description": "Lowest value."
+        },
+        {
+            "name": "max",
+            "label": "Max",
+            "editor": { "type": "number" },
+            "type": "number",
+            "default": 100,
+            "description": "Highest value."
+        },
+        {
+            "name": "step",
+            "label": "Step",
+            "editor": { "type": "number" },
+            "type": "number",
+            "default": 1,
+            "description": "Step between values."
+        },
+        {
+            "name": "size",
+            "label": "Size",
+            "type": "enum",
+            "enum": ["sm", "md", "lg"],
+            "default": "md",
+            "description": "Control size — drives the thumb size, track thickness and control row height."
+        },
+        {
+            "name": "color",
+            "label": "Color",
+            "editor": { "type": "token-color" },
+            "type": "enum",
+            "enum": [
+                "primary",
+                "secondary",
+                "tertiary",
+                "success",
+                "info",
+                "warning",
+                "danger"
+            ],
+            "default": "primary",
+            "description": "Semantic color of the filled track and thumb. Error and success override it."
+        },
+        {
+            "name": "showLabel",
+            "label": "Show label",
+            "type": "boolean",
+            "default": false,
+            "description": "Render the label as a visible <label for> before the track instead of aria-label."
+        },
+        {
+            "name": "showValue",
+            "label": "Show value",
+            "type": "boolean",
+            "default": false,
+            "description": "Render a value readout after the track. It is aria-hidden: the input already exposes its value."
+        },
+        {
+            "name": "formatValue",
+            "type": "(value: number) => string",
+            "description": "Formats the readout and sets aria-valuetext. Without it the readout is the plain number and no aria-valuetext is set."
+        },
+        {
+            "name": "disabled",
+            "label": "Disabled",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Disabled state — uses the native disabled attribute."
+        },
+        {
+            "name": "error",
+            "label": "Error",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Visual error state — sets aria-invalid, danger-colored fill and thumb, shake on transition."
+        },
+        {
+            "name": "errorMessage",
+            "label": "Error message",
+            "editor": { "tab": "settings" },
+            "type": "string | Signal<string>",
+            "description": "Error message shown below the slider when error is truthy. Linked via aria-describedby with role='alert'."
+        },
+        {
+            "name": "helperText",
+            "label": "Helper text",
+            "type": "string",
+            "description": "Persistent hint text below the slider. Hidden while an error message is visible."
+        },
+        {
+            "name": "success",
+            "label": "Success",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "description": "Visual success state — success-colored fill and thumb. Error takes precedence."
+        },
+        {
+            "name": "onInput",
+            "type": "(value: number, e: Event) => void",
+            "description": "Fires on every move with the current value as a number. Also fires after a form reset that changes the value, with a 'reset' Event."
+        },
+        {
+            "name": "onChange",
+            "type": "(value: number, e: Event) => void",
+            "description": "Fires when the user commits a value (pointer release, key press), and after a form reset that changes the value, with a 'reset' Event."
+        }
+    ],
+    "events": ["input", "change"],
+    "slots": [],
+    "tokens": {
+        "track.size": "--space-xs (sm/md), calc(--space-xs * 1.5) (lg)",
+        "track.rest": "color-mix(in oklch, --color-border 80%, --color-text) — ≥3:1 against the surface, as Toggle's track border",
+        "track.fill": "--_slider-color up to --_slider-fill (set from JS as a percentage)",
+        "track.radius": "--radius-pill",
+        "thumb.size.sm": "calc(var(--font-size-xs) * 1.25)",
+        "thumb.size.md": "calc(var(--font-size-sm) * 1.25)",
+        "thumb.size.lg": "calc(var(--font-size-body) * 1.25)",
+        "thumb.bg": "--_slider-color → --color-{color}, --color-danger (error), --color-success (success)",
+        "thumb.border": "--border-width-medium solid --color-surface",
+        "thumb.radius": "50%",
+        "thumb.shadow": "--shadow-sm, plus a --space-xs halo at --state-hover-opacity / --state-pressed-opacity",
+        "label.font": "--font-family-mono at --font-size-xs, --color-text-muted",
+        "value.color": "--color-text, tabular numerals",
+        "focus.ring": "a11y.focus-ring values on the thumb under :focus-visible, composed with the halo; --ring-color follows --_slider-color",
+        "disabled.opacity": "--state-disabled-opacity",
+        "hit-target": "input min-block-size 1.5rem (WCAG 2.5.8, 24px)",
+        "shake.animation": "ui-form-shake"
+    },
+    "spacing": {
+        "internal": {
+            "label-to-track": { "relationship": "close-friends", "token": "sm" },
+            "track-to-value": { "relationship": "close-friends", "token": "sm" }
+        },
+        "external": {
+            "wrapper-to-helper": { "relationship": "lovers", "token": "xs" },
+            "wrapper-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",
+        "Native <input type='range'> — never a div with role='slider'",
+        "Each engine's track/thumb pseudo-elements in their own rule — a selector list mixing ::-webkit-* and ::-moz-* is dropped by both engines",
+        "The WebKit fill gradient is flipped under :dir(rtl); Gecko uses ::-moz-range-progress",
+        "Forced-colors mode reverts to native rendering (appearance: auto)",
+        "Label prop is required",
+        "Callbacks receive numbers (valueAsNumber), never strings",
+        "A hidden, nameless <output> detects form resets, so each Slider adds one entry to form.elements and form.length (nothing to FormData)",
+        "No validation logic — error/success props are visual only",
+        "readonly, required and loading are not supported: a native range ignores them and aria-required is not allowed on the slider role",
+        "SliderProps extends Omit<FormControlBaseProps, 'readonly' | 'required' | 'loading'>"
+    ],
+    "a11y": [
+        "Native <input type='range'> — slider role, arrows / Page Up / Page Down / Home / End from the browser",
+        "aria-label carries the label by default; inside FormField the field's <label for> replaces it",
+        "showLabel renders a visible <label for> instead",
+        "formatValue sets aria-valuetext so the announced value matches the readout",
+        "The value readout is aria-hidden — the input already exposes its value",
+        "aria-invalid='true' when error is truthy",
+        "aria-describedby dynamically updated for helper/error",
+        "Error message has role='alert'",
+        "Focus ring on the thumb under :focus-visible, kept under hover and press; follows color, error and success",
+        "Input box is at least 24px tall (WCAG 2.5.8 target size)",
+        "Forced-colors: native rendering with system colors, and a Highlight outline on the focused input",
+        "Halo transition and error shake respect prefers-reduced-motion"
+    ],
+    "ai": {
+        "synonyms": [
+            "range",
+            "range slider",
+            "range input",
+            "fader",
+            "value slider",
+            "track bar"
+        ],
+        "avoid": [
+            "div with role='slider' — use the native input via <Slider>",
+            "raw color values for track / thumb — use the color prop",
+            "string values in onInput — the value is already a number",
+            "Slider without a label prop",
+            "Slider for a choice between a few named options — use SegmentedControl or RadioGroup"
+        ],
+        "patterns": [
+            "Basic: <Slider label=\"'Volume'\" />",
+            "Range and step: <Slider label=\"'Hue'\" min=\"0\" max=\"360\" step=\"1\" value=\"250\" />",
+            "Controlled: <Slider label=\"'Lightness'\" value=\"lightness\" onInput=\"setLightness\" />",
+            "Visible label and readout: <Slider label=\"'L'\" showLabel=\"true\" showValue=\"true\" />",
+            "Color: <Slider label=\"'Danger hue'\" color=\"'danger'\" />",
+            "Disabled: <Slider label=\"'Locked'\" disabled=\"true\" />"
+        ]
+    },
+    "examples": [
+        {
+            "id": "basic",
+            "title": "Basic slider",
+            "pithy": "<Slider label=\"'Volume'\" />",
+            "assertions": [
+                "renders <input type='range'>",
+                "aria-label='Volume'",
+                "min=0 max=100 step=1",
+                "no axe violations"
+            ]
+        },
+        {
+            "id": "range",
+            "title": "Custom range and step",
+            "pithy": "<Slider label=\"'Chroma'\" min=\"20\" max=\"220\" step=\"5\" value=\"160\" />",
+            "assertions": ["input.min === '20'", "input.valueAsNumber === 160"]
+        },
+        {
+            "id": "readout",
+            "title": "Visible label and value readout",
+            "pithy": "<Slider label=\"'Hue'\" min=\"0\" max=\"360\" value=\"250\" showLabel=\"true\" showValue=\"true\" />",
+            "assertions": [
+                "<label for> names the input",
+                "readout shows 250",
+                "readout is aria-hidden"
+            ]
+        },
+        {
+            "id": "color",
+            "title": "Semantic color",
+            "pithy": "<Slider label=\"'Danger hue'\" color=\"'danger'\" value=\"25\" />",
+            "assertions": ["data-color='danger' on wrapper"]
+        },
+        {
+            "id": "disabled",
+            "title": "Disabled slider",
+            "pithy": "<Slider label=\"'Locked'\" disabled=\"true\" value=\"40\" />",
+            "assertions": ["input.disabled === true", "data-disabled on wrapper"]
+        },
+        {
+            "id": "helper",
+            "title": "With helper text",
+            "pithy": "<Slider label=\"'Opacity'\" helperText=\"'Applies to the whole layer'\" />",
+            "assertions": ["helper text visible", "aria-describedby set"]
+        }
+    ],
+    "designGuidance": {
+        "surface": "Unfilled track uses a strengthened border color (border 80% / text) so it holds ≥3:1 against the surface. The filled portion and thumb share --_slider-color, which follows the color prop and is overridden by error/success.",
+        "depth": "Thumb carries --shadow-sm and a --color-surface border so it separates from the filled track. Focus ring sits on the thumb.",
+        "borders": "No border on the track — the thin pill shape reads on its own. Thumb is a circle.",
+        "interactivity": "Hover adds a soft halo around the thumb at --state-hover-opacity; press deepens it to --state-pressed-opacity. Clicking anywhere on the track jumps the thumb. Error shakes on transition.",
+        "bestPractices": "Use Slider for a continuous or finely stepped number where the relative position matters (lightness, volume, opacity). Show the value when the exact number matters, and pass formatValue so the readout and the announced value agree. Use an Input of type number when users need to type an exact value."
+    }
+}

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

@@ -6,6 +6,7 @@
     "version": "0.1.0",
     "level": "atom",
     "domain": "forms",
+    "icon": "text",
     "bidi": true,
     "description": "Textarea atom with auto-resize (CSS field-sizing with JS fallback), floating label, success/error states with shake animation and state icons, helper text, error message with aria-describedby, character counter, clear button, and loading spinner. No validation logic — states driven externally.",
     "props": [

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

@@ -6,6 +6,7 @@
     "version": "0.1.0",
     "level": "atom",
     "domain": "forms",
+    "icon": "toggle-left",
     "bidi": true,
     "description": "Accessible toggle / switch atom with a pill-shaped track and sliding thumb knob, role='switch' with aria-checked, error/success states with shake animation, helper/error text, loading spinner, and full a11y wiring. No validation logic — states driven externally.",
     "props": [

package/dist/specs/layout/grid-item.pidl.json

@@ -6,6 +6,7 @@
     "version": "0.1.0",
     "level": "atom",
     "domain": "layout",
+    "icon": "layout-grid",
     "studioReady": false,
     "bidi": true,
     "description": "Grid child component for structured placement within a Grid. Maps props to utility classes for column/row spanning and positioning.",
@@ -15,6 +16,7 @@
             "label": "Span",
             "editor": { "tab": "layout", "type": "string" },
             "type": "number | 'full'",
+            "valueKinds": ["number", "string"],
             "description": "Column span (1-12 or 'full') — maps to u-col-span-*"
         },
         {

package/dist/specs/layout/grid.pidl.json

@@ -6,6 +6,7 @@
     "version": "0.1.0",
     "level": "atom",
     "domain": "layout",
+    "icon": "layout-grid",
     "bidi": true,
     "description": "CSS grid layout atom with simple column counts, responsive breakpoints via container queries, and intrinsic auto-fit/fill patterns. Mobile-first: defaults to 1 column.",
     "props": [
@@ -14,6 +15,7 @@
             "label": "Columns",
             "editor": { "tab": "layout", "type": "string" },
             "type": "number | ResponsiveColumns | 'auto-fit' | 'auto-fill'",
+            "valueKinds": ["number", "string", "object"],
             "default": 1,
             "description": "Column configuration — number (1-12), responsive object ({ base, sm, md, lg, xl }), or intrinsic auto-fit/auto-fill"
         },

package/dist/specs/layout/page-section.pidl.json

@@ -6,6 +6,7 @@
     "version": "0.1.0",
     "level": "atom",
     "domain": "layout",
+    "icon": "layout-rows",
     "bidi": true,
     "description": "Semantic page section wrapper with consistent vertical spacing, optional containment, and full-bleed support. Named PageSection to avoid collision with native <section>.",
     "props": [
@@ -83,8 +84,8 @@
             "contained + fullBleed together — they conflict"
         ],
         "patterns": [
-            "Contained section: <PageSection spacing=\"'lg'\" contained><Heading>Features</Heading></PageSection>",
-            "Full-bleed hero: <PageSection spacing=\"'xl'\" fullBleed>...</PageSection>",
+            "Contained section: <PageSection spacing=\"'lg'\" contained=\"true\"><Heading>Features</Heading></PageSection>",
+            "Full-bleed hero: <PageSection spacing=\"'xl'\" fullBleed=\"true\">...</PageSection>",
             "Anchored section: <PageSection id=\"'about'\" as=\"'article'\">...</PageSection>"
         ]
     },
@@ -98,7 +99,7 @@
         {
             "id": "contained",
             "title": "Contained section with max-width",
-            "pithy": "<PageSection contained><Text>Centered content</Text></PageSection>",
+            "pithy": "<PageSection contained=\"true\"><Text>Centered content</Text></PageSection>",
             "assertions": ["has max-width style", "has margin-inline: auto"]
         }
     ]

package/dist/specs/layout/smart-container.pidl.json

@@ -6,6 +6,7 @@
     "version": "0.1.0",
     "level": "atom",
     "domain": "layout",
+    "icon": "layout-rows",
     "bidi": true,
     "description": "Higher-level layout component providing 5 opinionated responsive layout recipes (auto-grid, stack-to-row, row-wrap, sidebar, equal-cards) that adapt to container width via CSS container queries.",
     "props": [

package/dist/specs/layout/stack.pidl.json

@@ -6,6 +6,7 @@
     "version": "0.1.0",
     "level": "atom",
     "domain": "layout",
+    "icon": "layout-rows",
     "bidi": true,
     "description": "Flexbox layout atom that arranges children in a vertical or horizontal stack. Maps props to design-system utility classes — no custom CSS required.",
     "props": [

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

@@ -6,6 +6,7 @@
     "version": "0.1.0",
     "level": "organism",
     "domain": "content",
+    "icon": "chevron-down",
     "bidi": true,
     "description": "Disclosure list built on native <details>/<summary>. Keyboard and screen-reader correct with zero ARIA scaffolding and a zero-JS baseline. Items are passed as a typed array and/or projected as children. Optional single-open mode closes siblings when one item opens (progressive enhancement).",
     "props": [

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

@@ -6,6 +6,7 @@
     "version": "0.1.0",
     "level": "organism",
     "domain": "content",
+    "icon": "card",
     "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": [
@@ -277,7 +278,40 @@
             "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>"
+            "Feature tile (inside FeaturesSection-style grid): <Card variant=\"'subtle'\" padding=\"'lg'\"><header data-slot='header'><Icon name=\"'sparkle'\"/><Heading level='3'>Fast</Heading></header><Text>Reactive updates stay O(1).</Text></Card>"
         ]
-    }
+    },
+    "examples": [
+        {
+            "id": "basic-card",
+            "title": "Content card with a header and body",
+            "pithy": "<Card><header data-slot=\"header\"><Heading level=\"3\">Quarterly report</Heading></header><Text>Revenue grew 12% against a flat market.</Text></Card>",
+            "assertions": [
+                "renders a .ui-card root as an <article>",
+                "the header slot renders inside a semantic <header>",
+                "aria-labelledby points at the first heading",
+                "no violations in axe-core"
+            ]
+        },
+        {
+            "id": "clickable-card",
+            "title": "Outlined card that navigates",
+            "pithy": "<Card variant=\"'outlined'\" clickable=\"true\" href=\"'/reports/q3'\" linkLabel=\"'Read the Q3 report'\"><header data-slot=\"header\"><Heading level=\"3\">Q3 report</Heading></header><Text>Revenue grew 12% against a flat market.</Text></Card>",
+            "assertions": [
+                "renders one link whose accessible name is \"Read the Q3 report\"",
+                "the root carries data-clickable",
+                "inner interactive children stay independently focusable"
+            ]
+        },
+        {
+            "id": "horizontal-card",
+            "title": "Horizontal card with media and footer",
+            "pithy": "<Card orientation=\"'horizontal'\" padding=\"'lg'\"><img data-slot=\"media\" src=\"/thumb.png\" alt=\"Report cover\"><header data-slot=\"header\"><Heading level=\"4\">Search result</Heading></header><Text>Matching snippet from the document.</Text><footer data-slot=\"footer\"><Text size=\"'sm'\">3 min read</Text></footer></Card>",
+            "assertions": [
+                "the root carries data-orientation=\"horizontal\"",
+                "the media slot renders inside .ui-card-media",
+                "the footer slot renders inside a semantic <footer>"
+            ]
+        }
+    ]
 }

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

@@ -6,6 +6,7 @@
     "version": "0.1.0",
     "level": "organism",
     "domain": "feedback",
+    "icon": "alert",
     "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.",
@@ -122,7 +123,7 @@
             "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'\" />",
+            "Destructive confirm: <AlertDialog open=\"isOpen\" onClose=\"close\" onConfirm=\"clear\" tone=\"'danger'\" icon=\"'octagon-alert'\" 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.'\" />"
         ]
     },

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

@@ -6,9 +6,10 @@
     "version": "0.1.0",
     "level": "organism",
     "domain": "feedback",
+    "icon": "window",
     "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.",
+    "description": "Viewport-level dialog: a centered surface over a dimming backdrop, or a full-height drawer docked to the inline-end edge. 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",
@@ -42,6 +43,14 @@
             "required": false,
             "description": "Sets id on the dialog element — enables aria-controls on the trigger button."
         },
+        {
+            "name": "placement",
+            "label": "Placement",
+            "type": "enum",
+            "enum": ["center", "end"],
+            "default": "center",
+            "description": "center floats the dialog in the viewport; end docks it to the inline-end edge as a full-height drawer that slides in."
+        },
         {
             "name": "closeOnBackdrop",
             "label": "Close on backdrop click",
@@ -102,7 +111,7 @@
         ],
         "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>"
+            "Labelled by a visible heading: <Modal open=\"isOpen\" onClose=\"close\" title=\"'Publish'\" titleId=\"'publish-title'\"><Heading [id]=\"'publish-title'\">Publish</Heading>…</Modal>"
         ]
     },
     "designGuidance": {
@@ -126,7 +135,7 @@
         {
             "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>",
+            "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"]
         }
     ]

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

@@ -6,6 +6,7 @@
     "version": "0.1.0",
     "level": "organism",
     "domain": "feedback",
+    "icon": "bell",
     "studioReady": false,
     "bidi": true,
     "description": "Non-blocking notification. Imperative API (toast.show / success / error / warning / info) that stacks transient messages in a fixed corner region, portaled to <body>. Auto-dismisses after a duration, pauses on hover/focus, and supports an optional action button and close control.",

package/dist/specs/organisms/forms/dynamic-form.pidl.json

@@ -6,6 +6,7 @@
     "version": "0.1.0",
     "level": "organism",
     "domain": "forms",
+    "icon": "clipboard-list",
     "bidi": true,
     "description": "Config-driven form organism. Renders form fields from a FormConfig object, auto-wiring each field to a shared signal-based FormState. Supports grid layout with column spans, conditional visibility via dependsOn, validation with error display, and async submit.",
     "props": [
@@ -116,7 +117,7 @@
             "label": "Action URL",
             "editor": { "tab": "settings" },
             "type": "string",
-            "description": "Advanced override: raw native form action URL. Takes precedence over Submissions email. When set, the form posts via the browser after passing client-side validation (e.g. for a custom Formsubmit.co endpoint)."
+            "description": "Advanced override: raw native form action URL. Takes precedence over Submissions email unless it is not a safe URL (http(s), mailto, tel or relative), in which case it is ignored and Submissions email applies. When set, the form posts via the browser after passing client-side validation (e.g. for a custom Formsubmit.co endpoint)."
         },
         {
             "name": "method",

package/dist/specs/organisms/forms/form.pidl.json

@@ -6,6 +6,7 @@
     "version": "0.1.0",
     "level": "organism",
     "domain": "forms",
+    "icon": "clipboard-list",
     "studioReady": false,
     "bidi": true,
     "description": "Semantic <form> organism with signal-based state engine. Creates a <form novalidate> element, manages submit lifecycle (validate, submit, complete), and exposes state on the return object for manual wiring to child form atoms. No magic context injection — developers wire fields explicitly via state.fieldValue(), state.fieldHasError(), etc.",

package/dist/specs/organisms/forms/subscribe-form.pidl.json

@@ -6,6 +6,7 @@
     "version": "0.1.0",
     "level": "organism",
     "domain": "forms",
+    "icon": "mail",
     "bidi": true,
     "studioReady": false,
     "description": "Backend-agnostic email-capture form for landing pages, waitlists, and newsletter signups. Composes an email Input and submit Button, manages an idle/submitting/success/error state machine, validates email format client-side, and includes a honeypot spam trap. Delivers submissions via a custom onSubmit handler or by POSTing JSON to an action URL — never hardcodes a specific email provider.",

package/dist/specs/organisms/navigation/command-palette.pidl.json

@@ -6,6 +6,7 @@
     "version": "0.1.0",
     "level": "organism",
     "domain": "navigation",
+    "icon": "search",
     "studioReady": false,
     "bidi": true,
     "description": "⌘K command palette — a modal search field over a filtered command list. Composes <Modal> for the dialog (focus trap, Escape, backdrop) and <SearchInput> for the field, and adds the WAI-ARIA combobox-with-listbox-popup semantics on top: aria-expanded / aria-controls / aria-activedescendant on the field, a role=\"listbox\" of role=\"option\" items, real role=\"group\" sections for grouped commands, and a polite live region announcing the result count. SHELL ONLY — it owns no index. The default filter is a case-insensitive substring test over label + description + keywords, replaceable via the filter prop; the real search engine (Pagefind / Fuse over the codex index) is R3. studioReady is FALSE on purpose: the palette is driven by an open signal and an items array supplied in code, so there is nothing meaningful to author or preview on a canvas.",

package/dist/specs/organisms/navigation/docs-sidebar.pidl.json

@@ -6,6 +6,7 @@
     "version": "0.1.0",
     "level": "organism",
     "domain": "navigation",
+    "icon": "panel-left",
     "studioReady": false,
     "bidi": true,
     "description": "Nested docs navigation tree. Renders a <nav> landmark around real nested <ul>/<li> lists of <a href> links, with native <button aria-expanded> disclosures for groups. The link matching the router's path carries aria-current=\"page\"; the ancestor chain of that link is force-expanded on mount and on every route change. Collapse/expand state persists to localStorage under a caller-supplied key, degrading silently when storage is unavailable. NO search or filtering — that is <CommandPalette>'s job. studioReady is FALSE on purpose: the tree is a data prop and the active state comes from the live router, so there is nothing meaningful to author or preview on a canvas.",

package/dist/specs/organisms/navigation/navbar.pidl.json

@@ -6,6 +6,7 @@
     "version": "0.1.0",
     "level": "organism",
     "domain": "navigation",
+    "icon": "menu",
     "bidi": true,
     "description": "Top-of-page navigation with brand, primary links, trailing actions, and a mobile popover menu. Uses semantic <nav> with required aria-label, native Popover API for the mobile menu, and container queries for responsive layout.",
     "props": [
@@ -61,7 +62,7 @@
                 { "label": "Pricing", "href": "/pricing" },
                 { "label": "Docs", "href": "/docs" }
             ],
-            "description": "Primary nav links. Each item is {label, href, exactActive?, prefetch?}.",
+            "description": "Primary nav links. Each item is {label, href, exactActive?, prefetch?, target?, disabled?}.",
             "itemSchema": {
                 "label": {
                     "type": "string",
@@ -89,6 +90,11 @@
                     "enum": ["_blank", "_self"],
                     "required": false,
                     "description": "Anchor target. '_blank' opens the link in a new tab with rel='noopener noreferrer' and opts it out of SPA router prefetching; '_self'/undefined stay in the same tab."
+                },
+                "disabled": {
+                    "type": "boolean",
+                    "required": false,
+                    "description": "Render as a placeholder link that leads nowhere yet: no href, role='link', aria-disabled='true', never active or router-bound, out of the tab order. The href is kept so the item can be enabled later."
                 }
             }
         },

package/dist/specs/organisms/navigation/table-of-contents.pidl.json

@@ -6,6 +6,7 @@
     "version": "0.1.0",
     "level": "organism",
     "domain": "navigation",
+    "icon": "list",
     "studioReady": false,
     "bidi": true,
     "description": "Docs sidebar listing the headings of the current page, highlighting the one the reader is at and updating on scroll. Pairs with <Prose>, whose .u-prose article is the default heading source. Renders a <nav> landmark around a real nested <ul>/<li> list of <a href=\"#id\"> links; the active entry carries aria-current=\"location\". studioReady is FALSE on purpose: the component derives its entire content from the live page DOM at construction, so there is nothing meaningful to author or preview on a studio canvas — an empty article yields an empty (hidden) nav. It is registered fully so the catalog and docs tooling can see it; it is simply not canvas-droppable.",