@pithyjs/pidl-catalog 0.1.0-beta.0

package/dist/specs/sections/contact-section.pidl.json

@@ -0,0 +1,183 @@
+{
+    "kind": "component",
+    "id": "ui.contact-section",
+    "name": "ContactSection",
+    "displayName": "Contact Section",
+    "version": "0.1.0",
+    "level": "section",
+    "domain": "sections",
+    "bidi": true,
+    "description": "Contact information section with semantic address element, contact details, and form placeholder. Children projected into form area for V0.2 forms or external embeds.",
+    "props": [
+        {
+            "name": "heading",
+            "reactive": true,
+            "label": "Heading",
+            "type": "string | Signal<string>",
+            "default": "Contact Us",
+            "placeholder": "Get in touch",
+            "description": "Section heading text"
+        },
+        {
+            "name": "headingLevel",
+            "label": "Heading level",
+            "editor": { "tab": "settings" },
+            "type": "number",
+            "enum": [1, 2, 3, 4, 5, 6],
+            "default": 2,
+            "description": "Heading level for semantic correctness"
+        },
+        {
+            "name": "description",
+            "reactive": true,
+            "label": "Description",
+            "type": "string | Signal<string>",
+            "placeholder": "We'd love to hear from you. Reach out anytime.",
+            "description": "Section description below heading"
+        },
+        {
+            "name": "contacts",
+            "reactive": true,
+            "label": "Contacts",
+            "type": "ContactInfo[] | Signal<ContactInfo[]>",
+            "placeholder": [
+                {
+                    "label": "Email",
+                    "value": "hello@example.com",
+                    "href": "mailto:hello@example.com",
+                    "icon": "mail"
+                },
+                {
+                    "label": "Phone",
+                    "value": "+1 (555) 010-0000",
+                    "href": "tel:+15550100000",
+                    "icon": "phone"
+                },
+                {
+                    "label": "Address",
+                    "value": "123 Main St, Suite 100, San Francisco, CA 94103",
+                    "icon": "map-pin"
+                }
+            ],
+            "description": "Array of contact items with label, value, optional icon and href",
+            "itemSchema": {
+                "label": {
+                    "type": "string",
+                    "required": true,
+                    "description": "Contact method label (e.g. 'Email', 'Phone')"
+                },
+                "value": {
+                    "type": "string",
+                    "required": true,
+                    "description": "Contact value (e.g. 'hello@example.com')"
+                },
+                "icon": {
+                    "type": "string",
+                    "editor": { "type": "icon" },
+                    "description": "Optional icon name"
+                },
+                "href": {
+                    "type": "string",
+                    "description": "Optional link href (e.g. 'mailto:', 'tel:')"
+                }
+            }
+        },
+        {
+            "name": "spacing",
+            "label": "Spacing",
+            "editor": { "tab": "layout", "type": "token-space" },
+            "type": "enum",
+            "enum": ["0", "xs", "sm", "md", "lg", "xl"],
+            "default": "xl",
+            "description": "Vertical padding — maps to u-py-* utilities"
+        },
+        {
+            "name": "id",
+            "label": "Anchor ID",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Optional anchor id for in-page linking"
+        }
+    ],
+    "events": [],
+    "slots": [
+        {
+            "name": "form",
+            "displayName": "Form",
+            "description": "Contact form rendered beside the contact info.",
+            "accepts": ["ui.form"],
+            "max": 1
+        }
+    ],
+    "tokens": {
+        "spacing.vertical": "--space-{spacing} (via u-py-*)",
+        "spacing.container": "--space-md (gutter padding)"
+    },
+    "spacing": {
+        "heading-to-description": "--space-sm (close friends — heading and description)",
+        "description-to-contacts": "--space-lg (acquaintances — different content groups)",
+        "info-to-form": "--space-xl (strangers — contact info side and form side)",
+        "contact-items": "--space-sm (close friends — between contact list items)",
+        "icon-to-value": "--space-xs (lovers — icon and contact value)"
+    },
+    "designGuidance": {
+        "surface": "Contact section has no background — it relies on the page surface. The form/content side (projected children) should provide its own surface treatment (e.g. --color-surface-variant background with --radius-md).",
+        "depth": "No shadows on the section. Depth comes from the two-column layout and the contrast between the info side (text) and form side (contained card).",
+        "borders": "No section borders. Contact links use --color-text at rest with hover transition to --color-primary + underline.",
+        "interactivity": "Contact links are interactive — color transition on hover (motion-safe). Icons are decorative. The form side should contain interactive content (email button, form embed).",
+        "bestPractices": [
+            "Always provide href for actionable contacts — mailto: for email, tel: for phone",
+            "Form side should use a surface-variant background card, not a dashed wireframe placeholder",
+            "If no form is available, show a 'Send us a message' card with an email link — never show empty/wireframe states",
+            "Contact items use semantic <address> + <ul> — do not replace with divs",
+            "Two-column layout stacks on narrow viewports — design both orientations"
+        ]
+    },
+    "constraints": [
+        "Contact info rendered in semantic <address> element",
+        "href on contacts should use proper protocols (mailto:, tel:)",
+        "Children projected into form placeholder area (right side)",
+        "Layout uses flex-wrap with min-column tokens — stacks naturally when container is too narrow for two columns",
+        "Container uses fluid-center-parent (justify-content: center) and info side uses fluid-center-child (max-inline-size) — info block centers when wrapped to full width; form absorbs remaining space in two-column mode so centering has no effect"
+    ],
+    "a11y": [
+        "Renders semantic <section> element with aria-labelledby linked to heading",
+        "Uses <address> element for contact information",
+        "Contact links use proper href protocols for assistive tech",
+        "Icons are decorative (aria-hidden=true)",
+        "Contact list uses semantic <ul>/<li> markup",
+        "Contact list carries an explicit role=\"list\" because u-list-reset applies list-style: none !important, which strips list semantics in Safari/VoiceOver — the attribute is load-bearing, not redundant, and must not be removed",
+        "A contact's label reaches assistive tech by TWO different mechanisms, chosen by whether the value is a link. A linked value is an <a>, a nameable role, so it takes aria-label=\"Label: value\". A value with no usable href (an address, or an href rejected by isSafeHref) is a <span> — role=generic, where ARIA-in-HTML PROHIBITS naming and browsers discard aria-label — so its label is a visually hidden <span class=\"u-sr-only\"> instead. Do not unify these on aria-label: on the span it is inert, and the label is silently lost. axe does not flag it, because a prohibited name is discarded rather than reported"
+    ],
+    "ai": {
+        "synonyms": [
+            "contact",
+            "get in touch",
+            "reach us",
+            "contact form",
+            "contact info",
+            "contact details"
+        ],
+        "avoid": [
+            "div for contact info — use ContactSection with contacts array",
+            "links without proper protocol — use mailto: for email, tel: for phone"
+        ],
+        "patterns": [
+            "Basic contact: <ContactSection contacts=\"contactItems\"/>",
+            "With form placeholder: <ContactSection contacts=\"contactItems\"><p>Form coming in V0.2</p></ContactSection>",
+            "Custom heading: <ContactSection heading=\"'Get in Touch'\" description=\"'We'd love to hear from you'\" contacts=\"contactItems\"/>"
+        ]
+    },
+    "examples": [
+        {
+            "id": "basic-contact",
+            "title": "Contact section with details",
+            "pithy": "<ContactSection contacts=\"[{label:'Email',value:'hi@example.com',href:'mailto:hi@example.com',icon:'mail'}]\"/>",
+            "assertions": [
+                "renders <section>",
+                "<address> element present",
+                "contact link with mailto:"
+            ]
+        }
+    ]
+}

package/dist/specs/sections/cta-section.pidl.json

@@ -0,0 +1,168 @@
+{
+    "kind": "component",
+    "id": "ui.cta-section",
+    "name": "CTASection",
+    "displayName": "CTA Section",
+    "version": "0.1.0",
+    "level": "section",
+    "domain": "sections",
+    "bidi": true,
+    "description": "Call-to-action banner section with heading, description, and action buttons. Supports centered and inline layouts with semantic color theming.",
+    "props": [
+        {
+            "name": "eyebrow",
+            "reactive": true,
+            "label": "Eyebrow",
+            "type": "string | Signal<string>",
+            "placeholder": "GET STARTED",
+            "description": "Small uppercased label above the heading (e.g. 'LIMITED TIME', 'NEW')"
+        },
+        {
+            "name": "heading",
+            "reactive": true,
+            "label": "Heading",
+            "type": "string | Signal<string>",
+            "required": true,
+            "placeholder": "Ready to ship faster?",
+            "description": "CTA heading text"
+        },
+        {
+            "name": "headingLevel",
+            "label": "Heading level",
+            "editor": { "tab": "settings" },
+            "type": "number",
+            "enum": [1, 2, 3, 4, 5, 6],
+            "default": 2,
+            "description": "Heading level for semantic correctness"
+        },
+        {
+            "name": "description",
+            "reactive": true,
+            "label": "Description",
+            "type": "string | Signal<string>",
+            "placeholder": "Join thousands of developers building with our platform.",
+            "description": "Supporting description text below the heading"
+        },
+        {
+            "name": "color",
+            "label": "Color",
+            "editor": { "type": "token-color" },
+            "type": "enum",
+            "enum": [
+                "primary",
+                "secondary",
+                "tertiary",
+                "success",
+                "info",
+                "warning",
+                "danger"
+            ],
+            "default": "primary",
+            "description": "Semantic color scheme — sets data-color attribute for theming."
+        },
+        {
+            "name": "variant",
+            "label": "Variant",
+            "type": "enum",
+            "enum": ["centered", "inline"],
+            "default": "centered",
+            "description": "Layout variant — centered (stacked) or inline (text beside buttons)"
+        },
+        {
+            "name": "spacing",
+            "label": "Spacing",
+            "editor": { "tab": "layout", "type": "token-space" },
+            "type": "enum",
+            "enum": ["0", "xs", "sm", "md", "lg", "xl"],
+            "default": "lg",
+            "description": "Vertical padding — maps to u-py-* utilities"
+        },
+        {
+            "name": "id",
+            "label": "Anchor ID",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Optional anchor id for in-page linking"
+        }
+    ],
+    "events": [],
+    "slots": [
+        {
+            "name": "actions",
+            "displayName": "Actions",
+            "description": "Call-to-action buttons.",
+            "accepts": ["ui.button"]
+        }
+    ],
+    "tokens": {
+        "color.theme": "--color-{color} (via data-color attribute)",
+        "spacing.vertical": "--space-{spacing} (via u-py-*)",
+        "spacing.container": "--space-md (gutter padding)"
+    },
+    "spacing": {
+        "heading-to-description": "--space-sm (close friends — heading and supporting text)",
+        "content-to-actions": "--space-lg (acquaintances — text block and CTA buttons)",
+        "text-to-buttons-inline": "--space-lg (acquaintances — text side and buttons side in inline)"
+    },
+    "designGuidance": {
+        "surface": "CTA uses the standard --color-surface-variant background token to create a distinct visual band without being visually heavy. The background remains neutral; the color prop is expressed through themed accents and content rather than a tinted container.",
+        "depth": "Visual depth comes from the contrast between the surface-variant background and the surrounding page, plus the top and bottom borders. Avoid adding extra drop shadows so the section stays lightweight and consistent with other surfaces.",
+        "borders": "Top and bottom borders use the standard --color-border token to delineate the section. In forced-colors mode, rely on system border and background colors for sufficient contrast.",
+        "interactivity": "CTA itself is not interactive — buttons handle all interaction. Use eyebrow prop for urgency signals (e.g. 'LIMITED TIME').",
+        "bestPractices": [
+            "Use eyebrow for urgency or novelty signals — it draws the eye before the heading",
+            "Prefer ghost over outline for secondary CTA buttons",
+            "color prop controls accent theming (e.g. eyebrow color) while the background stays neutral — use 'warning' for urgency, 'success' for positive actions",
+            "Inline variant works best for newsletter/subscribe CTAs; centered for primary conversion CTAs",
+            "Description text is constrained to 60ch — keep it to 1-2 sentences"
+        ]
+    },
+    "constraints": [
+        "Children should contain CTA buttons — projected into the actions area",
+        "Color prop sets data-color for CSS theming — does not set inline background",
+        "Inline variant wraps to stacked layout on narrow containers"
+    ],
+    "a11y": [
+        "Renders semantic <section> element with aria-labelledby linked to heading",
+        "Heading uses correct <h1>-<h6> tag",
+        "CTA buttons maintain natural tab order"
+    ],
+    "ai": {
+        "synonyms": [
+            "cta",
+            "call to action",
+            "banner cta",
+            "signup banner",
+            "action section",
+            "conversion banner"
+        ],
+        "avoid": [
+            "div with styled background — use CTASection with color prop",
+            "multiple headings in CTA — use heading + description props"
+        ],
+        "patterns": [
+            "Centered CTA: <CTASection heading=\"'Ready to start?'\" description=\"'Join thousands'\"><Button>Sign Up</Button></CTASection>",
+            "Inline CTA: <CTASection variant=\"'inline'\" heading=\"'Get updates'\"><Button>Subscribe</Button></CTASection>",
+            "Colored CTA: <CTASection heading=\"'Limited offer'\" color=\"'warning'\"><Button>Claim Now</Button></CTASection>"
+        ]
+    },
+    "examples": [
+        {
+            "id": "centered-cta",
+            "title": "Centered CTA banner",
+            "pithy": "<CTASection heading=\"'Ready to get started?'\" description=\"'Join thousands of developers'\"><Button color=\"'primary'\">Sign Up Free</Button></CTASection>",
+            "assertions": [
+                "renders <section>",
+                "data-color='primary'",
+                "h2 with heading text",
+                "children in actions area"
+            ]
+        },
+        {
+            "id": "inline-cta",
+            "title": "Inline CTA",
+            "pithy": "<CTASection variant=\"'inline'\" heading=\"'Stay updated'\"><Button>Subscribe</Button></CTASection>",
+            "assertions": ["inline layout", "text beside buttons"]
+        }
+    ]
+}

package/dist/specs/sections/faq-section.pidl.json

@@ -0,0 +1,202 @@
+{
+    "kind": "component",
+    "id": "ui.faq-section",
+    "name": "FaqSection",
+    "displayName": "FAQ Section",
+    "version": "0.1.0",
+    "level": "section",
+    "domain": "sections",
+    "bidi": true,
+    "description": "Frequently-asked-questions section composed from the Accordion organism. Renders a centered header (optional eyebrow + heading + subheading) above a measure-constrained stack of native <details> disclosures, one per question.",
+    "props": [
+        {
+            "name": "heading",
+            "reactive": true,
+            "label": "Heading",
+            "type": "string | Signal<string>",
+            "default": "Frequently asked questions",
+            "placeholder": "Frequently asked questions",
+            "description": "Section heading text displayed above the questions"
+        },
+        {
+            "name": "headingLevel",
+            "label": "Heading level",
+            "editor": { "tab": "settings" },
+            "type": "number",
+            "enum": [1, 2, 3, 4, 5, 6],
+            "default": 2,
+            "description": "Heading level for semantic correctness"
+        },
+        {
+            "name": "subheading",
+            "reactive": true,
+            "label": "Subheading",
+            "type": "string | Signal<string>",
+            "placeholder": "Everything you need to know before getting started.",
+            "description": "Section description below the heading"
+        },
+        {
+            "name": "eyebrow",
+            "label": "Eyebrow",
+            "type": "string",
+            "placeholder": "FAQ",
+            "description": "Short uppercase kicker rendered above the heading"
+        },
+        {
+            "name": "items",
+            "reactive": true,
+            "label": "Questions",
+            "type": "FaqItem[] | Signal<FaqItem[]>",
+            "required": true,
+            "placeholder": [
+                {
+                    "question": "What do I get out of the box?",
+                    "answer": "Accessible, responsive components that follow the design system automatically — no custom CSS required to look consistent."
+                },
+                {
+                    "question": "Can I use it without JavaScript?",
+                    "answer": "Yes. The questions are native <details> elements, so they expand and collapse even before any JavaScript loads."
+                },
+                {
+                    "question": "Does it work on mobile?",
+                    "answer": "Every section is intrinsically fluid — layouts reflow to a single column on narrow screens with no breakpoints to configure."
+                },
+                {
+                    "question": "How do I get help?",
+                    "answer": "Reach out through the contact section, or open an issue in the repository. We usually respond within a day."
+                }
+            ],
+            "description": "Array of question/answer pairs. Questions and answers may be plain strings or reactive accessors.",
+            "itemSchema": {
+                "question": {
+                    "type": "string",
+                    "required": true,
+                    "description": "The question, rendered as the disclosure trigger"
+                },
+                "answer": {
+                    "type": "string",
+                    "required": true,
+                    "description": "The answer, revealed when the item is open"
+                },
+                "open": {
+                    "type": "boolean",
+                    "description": "Force this question open on first render"
+                }
+            }
+        },
+        {
+            "name": "mode",
+            "label": "Mode",
+            "type": "enum",
+            "enum": ["single", "multi"],
+            "default": "multi",
+            "description": "'single' closes sibling answers when one opens; 'multi' (default) lets answers stay open independently."
+        },
+        {
+            "name": "defaultOpen",
+            "label": "Default open",
+            "editor": { "tab": "settings" },
+            "type": "number | number[]",
+            "description": "Which question index(es) start open (index or array of indices)."
+        },
+        {
+            "name": "spacing",
+            "label": "Spacing",
+            "editor": { "tab": "layout", "type": "token-space" },
+            "type": "enum",
+            "enum": ["0", "xs", "sm", "md", "lg", "xl"],
+            "default": "xl",
+            "description": "Vertical padding — maps to u-py-* utilities"
+        },
+        {
+            "name": "id",
+            "label": "Anchor ID",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Optional anchor id for in-page linking"
+        }
+    ],
+    "events": [],
+    "slots": [
+        {
+            "name": "extras",
+            "displayName": "Extras",
+            "description": "Extra content below the questions, e.g. a \"Still have questions? Contact us\" link."
+        }
+    ],
+    "tokens": {
+        "spacing.vertical": "--space-{spacing} (via u-py-*)",
+        "spacing.container": "--space-md (gutter padding)",
+        "eyebrow.color": "--color-primary (via .ui-section-eyebrow)",
+        "heading.color": "--color-text (via Heading component)",
+        "subheading.color": "--color-text-muted (via Text component)",
+        "accordion.measure": "--measure-content max-inline-size, centered via margin-inline: auto"
+    },
+    "spacing": {
+        "eyebrow-to-heading": "--space-sm (close friends — kicker and heading)",
+        "heading-to-subheading": "--space-sm (close friends — heading and description)",
+        "header-to-accordion": "--space-lg (acquaintances — header block and question list)",
+        "questions-gap": "--space-sm (close friends — items in a list)"
+    },
+    "designGuidance": {
+        "surface": "The section itself has no background — it relies on the page surface. Each question is a bordered --color-surface card supplied by the Accordion organism, so the list reads as a contained stack against the page.",
+        "depth": "No shadows. Depth comes from the bordered question cards and the open/closed affordance, not elevation. The header is centered and the accordion is constrained to a readable measure so long FAQ lists stay scannable.",
+        "borders": "No section borders. Question borders (hairline, tinting to primary on hover) come from the Accordion.",
+        "interactivity": "Questions are native <details> disclosures — keyboard and screen-reader correct with no ARIA scaffolding. Choose 'single' mode for a focused reading experience or 'multi' for comparison.",
+        "bestPractices": [
+            "Provide real, useful answers in the items array — never ship an empty FAQ (the placeholder seeds four generic questions so the section is never blank on insert).",
+            "Use 'single' mode for long answers so only one occupies the viewport at a time.",
+            "Keep questions phrased the way a user would ask them — they double as scannable headings.",
+            "Add a contact link in the extras slot for questions the FAQ does not cover.",
+            "Set defaultOpen to the most common question to reduce clicks."
+        ]
+    },
+    "constraints": [
+        "Renders a semantic <section> with aria-labelledby linked to the heading",
+        "Composes the Accordion organism — questions are native <details>/<summary>, usable with zero JavaScript",
+        "items should be a non-empty array",
+        "Accordion is constrained to --measure-content and centered for readability",
+        "Layout is intrinsically fluid — no @media/@container breakpoints for stacking",
+        "Entrance animation observes the section root (motion-safe, SSR-safe)",
+        "destroy() disposes the composed Accordion, the heading/subheading atoms, the entrance observer, and empties the section"
+    ],
+    "a11y": [
+        "Renders semantic <section> element with aria-labelledby linked to heading",
+        "Questions use native <details>/<summary> — correct expanded/collapsed semantics with no added ARIA",
+        "Heading hierarchy: section heading at headingLevel",
+        "Question triggers are not wrapped in headings (avoids distorting the document outline)"
+    ],
+    "ai": {
+        "synonyms": [
+            "faq",
+            "frequently asked questions",
+            "questions",
+            "q&a",
+            "help",
+            "common questions",
+            "faqs"
+        ],
+        "avoid": [
+            "manual list of collapsibles — use FaqSection with an items array",
+            "div-based expanders with aria-expanded — FaqSection uses native <details> via Accordion"
+        ],
+        "patterns": [
+            "Basic FAQ: <FaqSection items=\"faqs\"/>",
+            "Single-open with eyebrow: <FaqSection eyebrow=\"'FAQ'\" heading=\"'Questions'\" mode=\"'single'\" items=\"faqs\"/>",
+            "First question open: <FaqSection items=\"faqs\" defaultOpen=\"0\"/>"
+        ]
+    },
+    "examples": [
+        {
+            "id": "basic-faq",
+            "title": "FAQ section with questions",
+            "pithy": "<FaqSection heading=\"'FAQ'\" items=\"faqs\"/>",
+            "assertions": [
+                "renders <section>",
+                "h2 section heading",
+                "aria-labelledby linked to heading",
+                "one <details> per question"
+            ]
+        }
+    ]
+}