@pithyjs/pidl-catalog 0.1.0-beta.0

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

@@ -0,0 +1,356 @@
+{
+    "kind": "component",
+    "id": "ui.navbar",
+    "name": "Navbar",
+    "displayName": "Navbar",
+    "version": "0.1.0",
+    "level": "organism",
+    "domain": "navigation",
+    "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": [
+        {
+            "name": "label",
+            "label": "Label",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "required": true,
+            "placeholder": "Primary",
+            "description": "Accessible name for the <nav> landmark. Required because a page can contain multiple <nav> elements (header, footer, sidebar) and screen readers need to distinguish them."
+        },
+        {
+            "name": "brand",
+            "label": "Brand",
+            "type": "string",
+            "placeholder": "Your Brand",
+            "description": "Wordmark / brand text shown at the start of the navbar. Rendered beside brandImageSrc if both are provided."
+        },
+        {
+            "name": "brandImageSrc",
+            "label": "Brand image source",
+            "type": "string",
+            "description": "Logo image URL shown at the start of the navbar."
+        },
+        {
+            "name": "brandImageAlt",
+            "label": "Brand image alt",
+            "type": "string",
+            "description": "Alt text for the brand logo image. REQUIRED when brandImageSrc is set."
+        },
+        {
+            "name": "brandHref",
+            "label": "Brand link",
+            "type": "string",
+            "default": "/",
+            "description": "Href for the brand link (usually the home page)."
+        },
+        {
+            "name": "brandTarget",
+            "label": "Open brand link in new tab",
+            "type": "enum",
+            "enum": ["_blank", "_self"],
+            "default": "_self",
+            "description": "Anchor target for the brand link. '_blank' opens it in a new tab with rel='noopener noreferrer'; '_self'/undefined stay in the same tab."
+        },
+        {
+            "name": "items",
+            "label": "Items",
+            "type": "NavbarItem[]",
+            "placeholder": [
+                { "label": "Features", "href": "/features" },
+                { "label": "Pricing", "href": "/pricing" },
+                { "label": "Docs", "href": "/docs" }
+            ],
+            "description": "Primary nav links. Each item is {label, href, exactActive?, prefetch?}.",
+            "itemSchema": {
+                "label": {
+                    "type": "string",
+                    "required": true,
+                    "description": "Link text"
+                },
+                "href": {
+                    "type": "string",
+                    "required": true,
+                    "description": "Link URL"
+                },
+                "exactActive": {
+                    "type": "boolean",
+                    "required": false,
+                    "description": "Use exact pathname match for active state (default: false = prefix match)"
+                },
+                "prefetch": {
+                    "type": "enum",
+                    "enum": ["none", "hover", "visible", "intent"],
+                    "required": false,
+                    "description": "Prefetch strategy when the PithyJS router is available. Ignored for plain-anchor fallback. Default 'none'."
+                },
+                "target": {
+                    "type": "enum",
+                    "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."
+                }
+            }
+        },
+        {
+            "name": "sticky",
+            "label": "Sticky",
+            "editor": { "tab": "layout" },
+            "type": "boolean",
+            "default": false,
+            "description": "Sticks to the top of the viewport as the page scrolls (position: sticky; inset-block-start: 0)."
+        },
+        {
+            "name": "transparent",
+            "label": "Transparent",
+            "type": "boolean",
+            "default": false,
+            "description": "Transparent background until the user scrolls past the top. Intended for use directly above a hero section."
+        },
+        {
+            "name": "density",
+            "label": "Density",
+            "editor": { "tab": "layout" },
+            "type": "enum",
+            "enum": ["comfortable", "compact"],
+            "default": "comfortable",
+            "description": "Vertical density. 'comfortable' is the default marketing navbar; 'compact' suits app/dashboard chrome."
+        },
+        {
+            "name": "skipToContentTarget",
+            "label": "Skip to content target",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "default": "main-content",
+            "description": "Target element id for the skip-to-content link. The element (usually <main>) must exist on the page."
+        },
+        {
+            "name": "id",
+            "label": "Anchor ID",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Optional anchor id on the <nav> element."
+        }
+    ],
+    "requiredProps": ["label"],
+    "events": [],
+    "slots": [
+        {
+            "name": "brand",
+            "displayName": "Brand",
+            "description": "Brand logo or wordmark at the inline-start. Overrides the brand/brandImageSrc props when projected.",
+            "accepts": ["ui.image", "ui.text"],
+            "max": 1,
+            "media": "logo"
+        },
+        {
+            "name": "actions",
+            "displayName": "Actions",
+            "description": "Trailing action buttons/links at the inline-end (desktop) or bottom of the mobile menu.",
+            "accepts": ["ui.button", "ui.icon-group"]
+        },
+        {
+            "name": "search",
+            "displayName": "Search",
+            "description": "Search input or command palette trigger. Rendered inside the nav menu area.",
+            "accepts": ["ui.input"],
+            "max": 1
+        },
+        {
+            "name": "announcement",
+            "displayName": "Announcement",
+            "description": "Top banner bar above the nav — dismissible alerts, promos, notices.",
+            "max": 1
+        }
+    ],
+    "tokens": {
+        "surface.rest": "transparent by default, --color-surface when scrolled or transparent=false",
+        "surface.scrolled": "color-mix(in oklch, var(--color-surface) 80%, transparent) + backdrop-filter: blur(12px) saturate(1.4)",
+        "surface.innerHighlight": "inset 0 1px 0 color-mix(text 6%, transparent) — simulates sealed frosted glass",
+        "border.scrolled": "--border-width-hairline, --color-border (block-end only)",
+        "shadow.scrolled": "--shadow-sm (stacked with the inset 1px highlight)",
+        "condense.comfortable": "min-block-size drops from control-padding-y-md → control-padding-y-sm on scroll; container padding-block matches",
+        "brand.letterSpacing.rest": "-0.01em",
+        "brand.letterSpacing.scrolled": "-0.02em (subtle tighten, motion-safe)",
+        "padding.block.comfortable": "--control-padding-md",
+        "padding.block.compact": "--control-padding-sm",
+        "padding.inline": "--space-md (gutter)",
+        "gap.items": "--space-sm (close friends — nav link list)",
+        "gap.brand-to-items": "--space-lg (acquaintances)",
+        "gap.items-to-actions": "--space-md (friends)",
+        "hamburger.size": "--control-min-touch (touch target ≥44px)",
+        "hamburger.stroke": "2.25 (matches drawer typographic weight)",
+        "link.color": "--color-text",
+        "link.color-hover": "--color-text",
+        "link.color-active": "--color-primary",
+        "brand.mark.default": "primary-colored dot via ::before when no brandImageSrc — sized 0.55em so it scales with the wordmark",
+        "indicator.desktop": "2px primary-colored pill bar positioned absolutely inside .ui-navbar-list; JS publishes --_indicator-x / --_indicator-w on active-item change and CSS transitions translate + inline-size",
+        "indicator.mobile": "3px leading pill bar on the active drawer item (::before on .ui-navbar-link, block-size animates from 0 → 1.5rem)",
+        "drawer.layout": "position: fixed; inset-block: 0 0; inset-inline-end: 0; inline-size: min(88vw, 22rem); leading-edge rounded corners + hairline inline-start border",
+        "drawer.backdrop": "color-mix(--color-text 55%, transparent) + backdrop-filter: blur(14px) saturate(1.2)",
+        "container.maxWidth": "xl container breakpoint (80rem) — nav content caps and centers on wide viewports while the bar background stays full-width",
+        "container.gutter": "--space-lg",
+        "view-transition": "A per-instance view-transition-name (pithy-<menuId>) pins the navbar across route transitions so only the outlet cross-fades; multiple navbars on one page each get a unique name to avoid collision",
+        "motion.chrome": "--motion-duration-normal, --motion-easing-standard",
+        "motion.popover-entrance": "--motion-duration-normal, --motion-easing-entrance",
+        "motion.indicator": "--motion-duration-normal, --motion-easing-entrance (translate + inline-size)",
+        "motion.hover-underline": "scale(0 1 → 1 1) transform-origin: inline-start; --motion-duration-normal, --motion-easing-entrance"
+    },
+    "spacing": {
+        "brand-to-items": "--space-lg (acquaintances — the brand is a separate semantic cluster from the nav links)",
+        "item-list-gap": "--space-sm (close friends — nav links are peers)",
+        "items-to-actions": "--space-md (friends — related but distinct clusters)",
+        "hamburger-to-content": "--space-sm (close friends — toggle next to menu trigger)",
+        "drawer-flex-gap": "--space-sm (close friends — drawer flex column gap)",
+        "drawer-header-to-list": "--space-md (friends — brand/close row to nav list, separated by hairline divider)",
+        "drawer-actions-pinned": "margin-block-start: auto (actions/theme-toggle anchored to drawer bottom with hairline top divider)"
+    },
+    "designGuidance": {
+        "surface": "Three surface modes: (1) transparent=false, sticky=false → solid --color-surface always; (2) sticky=true, transparent=false → solid surface always, with hairline bottom border + inner 1px highlight + --shadow-sm when scrolled; (3) transparent=true → fully transparent over hero at rest, translucent via tokenized glass.glass-surface(...) mixin once scrolled past the 1px sentinel. The scrolled-state transition is motion-safe. Comfortable density additionally condenses (min-block-size + padding-block drop one tier) on scroll; compact is already condensed and is not altered. Brand wordmark letter-spacing tightens from -0.01em → -0.02em on scroll.",
+        "depth": "No shadow at rest. When scrolled, --shadow-sm and a hairline block-end border appear together — depth signals 'this is elevated above the page now'. Do not stack additional shadows.",
+        "borders": "No borders at rest. On scroll, a single hairline --border-width-hairline in --color-border on the block-end. In forced-colors mode, a 1px ButtonText border is always present for visibility.",
+        "interactivity": "Desktop links use --color-text at rest; hover/focus-visible draws a hairline ::after underline from the leading edge (scale-x transition) and active state is shown by a single 2px primary pill bar that slides between items (JS publishes --_indicator-x / --_indicator-w on aria-current change). Mobile drawer items use --color-text medium weight at rest; active uses --color-primary semibold plus a 3px leading pill bar (::before) that grows from 0 → 1.5rem. The hamburger is a ≥44×44 target, scale(0.96) press feedback, morphs to an X via stroke transforms — all motion-safe. All tap highlights are suppressed (-webkit-tap-highlight-color: transparent) and drawer link contextmenu is preventDefault'd to stop long-press state drift on touch.",
+        "bestPractices": [
+            "One <Navbar> per page as the primary nav landmark. Use distinct label values if you have multiple navs (e.g. 'Primary', 'Utility').",
+            "Place the Navbar as the first visible element, immediately before the <main> element. The skip link's target id must match an element on the page.",
+            "Use transparent=true only when the content directly below is a full-bleed Hero with sufficient contrast behind text — otherwise the unscrolled state is unreadable.",
+            "The nav collapses to a hamburger when primary items no longer fit in a single row (content-aware via ResizeObserver). Cap item count at ~7 top-level links for desktop readability; more belongs in a dropdown/mega-menu (separate component, post-V0.1).",
+            "For brand: pass a logo image (brandImageSrc + brandImageAlt) or a short wordmark (brand) — when only the wordmark is set, Navbar renders a default primary-colored dot mark before it.",
+            "Don't put primary CTAs in the link list — use the actions slot so CTAs stay visually distinct (e.g. a <Button variant='solid'>).",
+            "Prefer density='comfortable' for marketing sites; switch to 'compact' for app/dashboard shells where vertical real-estate is precious."
+        ]
+    },
+    "constraints": [
+        "Uses semantic <nav> element with required aria-label",
+        "Link list uses <ul>/<li> semantic markup",
+        "Mobile menu uses native Popover API (popover='auto') — no custom show/hide JS required",
+        "Hamburger toggle uses Invoker Commands (commandfor/command) — no manual click handler for open/close",
+        "Responsive layout is content-aware: a ResizeObserver on the nav + list flips to mobile when items overflow a single row and reverts to desktop when the nav grows past the width that forced the switch. Layout flips are guarded by a `data-layout-transitioning` attribute that suppresses the popover's discrete-display transitions so the switch can't flash items",
+        "All CSS uses logical properties (inline-start/end, block-start/end) — RTL-safe",
+        "Zero raw CSS values — every color/space/font-size/radius/shadow/duration uses a design system token",
+        "Skip link is always the first focusable element inside <nav>",
+        "When brandImageSrc is provided, brandImageAlt must also be set",
+        "Mobile drawer is a CSS-only full-height side-sheet (position: fixed; inset-block: 0 0; inset-inline-end: 0; block-size: 100dvh). The JS anchor-positioning path early-exits on mobile so CSS owns layout",
+        "Desktop popover positioning is direction-aware: RTL uses the toggle's physical-left edge, LTR uses the viewport-right-to-toggle-right distance",
+        "Body scroll is locked (document.body.style.overflow='hidden') while the popover is open on mobile; restored on close and on destroy",
+        "Long-press on a drawer link calls event.preventDefault() to suppress the browser's native contextmenu, preventing in-between popover state on touch-emulation and real iOS",
+        "Inline position styles (desktop only) are cleared after the close transition's `opacity` transitionend (with 600ms fallback) so the popover never flashes top-left mid-animation",
+        "Nav content inside .ui-navbar-container is capped at the `xl` container breakpoint (80rem) and centered with margin-inline: auto on wide viewports; the bar's background stays full-width",
+        "Anchors are tagged with data-router-link + data-prefetch/exact-match attributes so setGlobalRouter → bindExistingRouterLinks binds them even when the router mounts after Navbar",
+        "The navbar sets a per-instance view-transition-name (pithy-<menuId>) so View Transitions pin it across route changes (only the outlet cross-fades), with unique names across multiple concurrent navbars"
+    ],
+    "a11y": {
+        "landmarks": [
+            "Semantic <nav> landmark with a required aria-label (WCAG 1.3.1, 2.4.1)",
+            "Skip-to-content link (visually hidden until :focus-visible) is the first focusable element — satisfies WCAG 2.4.1 'Bypass Blocks'. Target id defaults to #main-content and must exist in the page."
+        ],
+        "keyboard": {
+            "toggleActivation": "Enter or Space on the hamburger opens the popover (native Invoker Commands).",
+            "initialFocus": "On keyboard-open (Enter/Space), focus moves to the first focusable item inside the menu. On pointer/touch-open, focus stays on the trigger so no unrequested focus ring appears.",
+            "insideMenu": {
+                "ArrowDown": "Focus next focusable item; wraps from last to first",
+                "ArrowUp": "Focus previous focusable item; wraps from first to last",
+                "Home": "Focus first focusable item",
+                "End": "Focus last focusable item",
+                "Tab": "On mobile (hamburger visible), Tab/Shift+Tab cycles within the popover — focus trap. On desktop, Tab flows naturally through the inline menu.",
+                "Escape": "Closes the popover (native popover-auto); focus returns to the trigger"
+            },
+            "nonShortcuts": "No typeahead or single-character shortcuts — satisfies WCAG 2.1.4 (Character Key Shortcuts) by design."
+        },
+        "focus": {
+            "visible": "All interactive elements use the design-system `focus-ring` mixin; never removed (WCAG 2.4.7).",
+            "notObscured": "When the popover overflows its max-block-size and scrolls internally, a focusin listener scrolls the focused item into view with an 8px breathing margin. Satisfies WCAG 2.4.11 'Focus Not Obscured' (AA).",
+            "restore": "Closing the popover returns focus to the trigger (native popover-auto behavior)."
+        },
+        "aria": {
+            "navLandmark": "aria-label on <nav>",
+            "hamburger": "aria-label swaps between 'Open menu' and 'Close menu'; aria-expanded is synced from the popover's own toggle event (belt-and-suspenders over Invoker Commands)",
+            "controls": "aria-controls pairs with commandfor; no aria-haspopup because the popover is a Disclosure of links (APG Disclosure pattern), not an ARIA menu widget",
+            "activeItem": "Current page is indicated by router-link-active class + aria-current='page' + data-current='page' (mirror for CSS targeting without ARIA selectors)",
+            "decorativeIcon": "Hamburger SVG has aria-hidden='true' + focusable='false' — the button's aria-label provides the accessible name"
+        },
+        "touch": {
+            "targetSize": "Hamburger and nav links use --control-min-touch (≥44×44) — WCAG 2.5.5 (AAA) / 2.5.8 (AA)",
+            "tapDelay": "touch-action: manipulation on the toggle and links kills the legacy ~300ms tap delay without disabling pinch-zoom"
+        },
+        "viewport": {
+            "safeArea": "Popover max-block-size and padding-block-end subtract env(safe-area-inset-bottom) so the last item never sits under the iOS home indicator / Android gesture bar. Requires the app-level <meta name='viewport' content='...,viewport-fit=cover'> for the insets to be non-zero on iOS.",
+            "dynamicViewport": "max-block-size uses 100dvh (with 100vh fallback) so the cap tracks mobile browser chrome showing/hiding.",
+            "reflow": "Container-query-driven responsive layout; no horizontal scroll at 320px (WCAG 1.4.10). Mobile-first — desktop layout is the @container (min-width) branch."
+        },
+        "rtl": {
+            "logicalProperties": "All CSS uses logical properties (inline-start/end, block-start/end). Verified by test.",
+            "positioningMath": "JavaScript popover positioning is direction-aware: RTL uses r.left, LTR uses window.innerWidth - r.right. Resolved from the nearest explicit `dir` attribute, then getComputedStyle.direction."
+        },
+        "motion": {
+            "reducedMotion": "All transitions (chrome, hamburger morph, popover entrance, item stagger) are wrapped in prefers-reduced-motion: no-preference — WCAG 2.3.3.",
+            "bodyScrollLock": "While the mobile popover is open, body overflow is set to 'hidden' so the document can't scroll behind it; restored on close and on destroy. Not a motion concern but prevents disorienting background movement on mobile.",
+            "inertSiblings": "While the mobile popover is open, every direct child of document.body that does not contain the nav is marked `inert` so AT, hit-testing, and tabbing are all blocked behind the menu. Restored on close and on destroy. Belt-and-suspenders alongside body scroll lock."
+        },
+        "forcedColors": "forced-colors mode renders a ButtonText bottom border, uses system link colors, and keeps hamburger borders visible — WCAG 1.4.1 (Use of Color) parity.",
+        "contentAssertions": "Brand logo image requires brandImageAlt (enforced at compile time via discriminated-union prop types)."
+    },
+    "ai": {
+        "synonyms": [
+            "navbar",
+            "nav bar",
+            "top nav",
+            "header",
+            "site header",
+            "primary navigation",
+            "main nav",
+            "top navigation",
+            "menu bar",
+            "app bar",
+            "open in new tab",
+            "new tab",
+            "external link"
+        ],
+        "avoid": [
+            "<div class='nav'> — use <Navbar> with a semantic <nav> landmark and required label",
+            "Custom hamburger with JS click handlers — use the native Popover API + Invoker Commands flow Navbar provides",
+            "Viewport media queries for the mobile collapse — Navbar uses container queries on the nav root so it adapts to its own width",
+            "Stuffing CTAs into the items array — they belong in the actions slot so they read as actions, not navigation"
+        ],
+        "patterns": [
+            "Marketing site top bar: <Navbar label=\"'Main'\" brand=\"'Acme'\" items=\"navItems\" sticky=\"true\"/>",
+            "Transparent over hero: <Navbar label=\"'Main'\" brandImageSrc=\"'/logo.svg'\" brandImageAlt=\"'Acme'\" items=\"navItems\" sticky=\"true\" transparent=\"true\"/>",
+            "App dashboard chrome: <Navbar label=\"'App'\" brand=\"'Console'\" items=\"appNav\" density=\"'compact'\" sticky=\"true\"/>",
+            "With trailing CTA (projected children fall through to actions slot): <Navbar label=\"'Main'\" brand=\"'Acme'\" items=\"navItems\"><Button>Sign in</Button></Navbar>"
+        ]
+    },
+    "examples": [
+        {
+            "id": "basic-navbar",
+            "title": "Basic sticky navbar with brand and items",
+            "pithy": "<Navbar label=\"'Main'\" brand=\"'Acme'\" items=\"[{label:'Features',href:'/features'},{label:'Pricing',href:'/pricing'},{label:'Docs',href:'/docs'}]\" sticky=\"true\"/>",
+            "assertions": [
+                "renders <nav aria-label='Main'>",
+                "includes a skip-to-content link as first focusable element",
+                "items render as <a class='ui-nav-link'> inside <ul>/<li>",
+                "hamburger toggle uses commandfor/command",
+                "mobile menu renders with popover='auto'",
+                "data-sticky='true' on the root"
+            ]
+        },
+        {
+            "id": "transparent-hero-navbar",
+            "title": "Transparent navbar over a hero",
+            "pithy": "<Navbar label=\"'Main'\" brandImageSrc=\"'/logo.svg'\" brandImageAlt=\"'Acme'\" items=\"items\" sticky=\"true\" transparent=\"true\"/>",
+            "assertions": [
+                "data-transparent='true' on the root",
+                "brand image has alt attribute",
+                "no background at rest; tinted + backdrop-blur once data-scrolled='true'"
+            ]
+        },
+        {
+            "id": "compact-app-navbar",
+            "title": "Compact navbar for app shells",
+            "pithy": "<Navbar label=\"'App'\" brand=\"'Console'\" items=\"appNav\" density=\"'compact'\" sticky=\"true\"/>",
+            "assertions": [
+                "data-density='compact' reduces vertical padding one tier",
+                "touch targets still ≥44×44"
+            ]
+        }
+    ]
+}

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

@@ -0,0 +1,197 @@
+{
+    "kind": "component",
+    "id": "ui.table-of-contents",
+    "name": "TableOfContents",
+    "displayName": "Table of contents",
+    "version": "0.1.0",
+    "level": "organism",
+    "domain": "navigation",
+    "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.",
+    "props": [
+        {
+            "name": "container",
+            "label": "Container",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "default": ".u-prose",
+            "placeholder": ".u-prose",
+            "description": "Where the headings live. Defaults to '.u-prose', the design-system utility <Prose> applies to its root — so a bare <TableOfContents /> beside a <Prose> document needs no configuration. The TypeScript API additionally accepts an HTMLElement (for callers that already hold the container) or a () => HTMLElement | null getter (for a container built after the ToC, e.g. a router outlet). A selector that matches nothing renders the empty state and DEV-warns rather than throwing."
+        },
+        {
+            "name": "minLevel",
+            "label": "Shallowest heading",
+            "editor": { "tab": "settings" },
+            "type": "number",
+            "default": 2,
+            "description": "Shallowest heading level to list, 1-6. Default 2 — h1 is normally the page title, which the reader is already looking at. Values are clamped to 1-6, and an inverted minLevel/maxLevel pair is re-ordered rather than collecting nothing."
+        },
+        {
+            "name": "maxLevel",
+            "label": "Deepest heading",
+            "editor": { "tab": "settings" },
+            "type": "number",
+            "default": 3,
+            "description": "Deepest heading level to list, 1-6. Default 3. Headings deeper than this are ignored entirely — a four-level table of contents is longer than the page it indexes."
+        },
+        {
+            "name": "label",
+            "label": "Label",
+            "type": "string",
+            "default": "On this page",
+            "placeholder": "On this page",
+            "description": "Accessible name for the <nav> landmark. Always applied (never optional): a docs page typically holds several <nav> elements — site header, docs sidebar, this — and the name is what lets a screen-reader user tell them apart in a landmark list. A whitespace-only value falls back to the default rather than producing an empty accessible name."
+        },
+        {
+            "name": "smoothScroll",
+            "label": "Smooth scroll",
+            "editor": { "tab": "settings" },
+            "type": "boolean",
+            "default": true,
+            "description": "Animate the jump to a heading when a link is clicked. ALWAYS overridden by prefers-reduced-motion: reduce, which forces an instant jump regardless of this value — the media query is read at click time, not at construction, so a mid-session preference change takes effect immediately."
+        },
+        {
+            "name": "class",
+            "label": "Extra classes",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "required": false,
+            "description": "Extra class names appended after 'ui-toc'."
+        },
+        {
+            "name": "id",
+            "label": "Element id",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "required": false,
+            "description": "id for the <nav> element — useful as a skip-link target."
+        }
+    ],
+    "tokens": {
+        "typography": "--font-size-sm + --line-height-body (list text), --font-weight-semibold (current entry)",
+        "color": "--color-text-muted (rest), --color-text (hover + current), --color-primary via --_toc-accent (current rail + hover tint), --color-divider via --_toc-rail (rest rail), --color-border via --_toc-rail-hover",
+        "spacing": "--space-xs (entry gap, link block padding, sublist offset), --space-sm (link inline padding, sublist indent), --space-lg (sticky offset)",
+        "border": "--border-width-medium + --border-style-solid (the inline-start rail on every link)",
+        "radius": "--radius-xs (inline-end corners of the link box, so the rail stays square against the track)",
+        "focus": "--focus-ring-width / --focus-ring-offset / --ring-color via the a11y focus-ring mixin on :focus-visible",
+        "motion": "--motion-transition-color / --motion-transition-background / --motion-transition-border, inside prefers-reduced-motion: no-preference"
+    },
+    "spacing": {
+        "entry-gap": "--space-xs (Lovers) — sibling entries read as one continuous track, not as separate items",
+        "sublist-indent": "--space-sm inline (Close Friends) — a sub-entry belongs to the heading above it; depth reads from the indent, never from a size or colour change",
+        "link-padding": "--space-xs block / --space-sm inline — enough hit area without turning the list into a button stack",
+        "sticky-offset": "--space-lg (Acquaintances) — the gap between the ToC and the top of the viewport when it sticks"
+    },
+    "constraints": [
+        "Derives its content from the page DOM, not from props — it takes NO children and declares NO slot",
+        "The document is scanned ONCE, at construction; mount the ToC after the content it describes and re-create it on navigation",
+        "A heading that already has an id keeps it, always — that id may be the target of links elsewhere on the site",
+        "Generated ids are content-derived slugs (slugifyHeadingText), de-duplicated with -2/-3/… against BOTH the slugs this pass generated AND ids already present in the document",
+        "Non-latin letters survive slugification; only latin diacritics are stripped. Reducing to [a-z0-9] would erase a Japanese or Cyrillic heading and collapse a whole document into section, section-2, section-3",
+        "A slug starting with a digit is prefixed 'section-': #2024-notes is a legal fragment but an invalid CSS selector, so querySelector('#' + id) would throw",
+        "Empty and punctuation-only headings fall back to 'section' — the empty string is not a usable id",
+        "Long slugs are truncated at a word boundary (64 chars) and never end in a hyphen",
+        "h3 entries nest inside the preceding h2's <li>; an h3 with no preceding h2 is promoted to the top level rather than being dropped",
+        "Zero headings renders a real <nav hidden data-empty=\"true\"> with NO list. `hidden` resolves to display:none, so the element leaves BOTH layout and the accessibility tree — it does not hold a space in the caller's layout. It is still returned so the { el, destroy } handle contract holds and the caller can mount it unconditionally",
+        "The active entry is recomputed from the FULL observer state on every batch, never patched from the delta — that is what makes overlapping and rapid-fire batches converge deterministically",
+        "Several headings on screen at once resolve to the first in DOCUMENT order, not the first in the entry batch (the browser does not order entries)",
+        "A heading the observer has not reported on yet is at an unknown position, tracked as +Infinity — treating it as 0 would read as 'exactly at the viewport top' and hand the active state to the last heading in the document",
+        "The bottom-of-page fallback (the final heading may be too close to the document end ever to reach the viewport top) is gated on the document actually being scrollable — otherwise a page shorter than the viewport would pin the last entry permanently",
+        "Without IntersectionObserver the list still renders and still navigates; only the highlight is inert",
+        "destroy() disconnects the observer, removes the scroll/resize listeners and every click listener, removes ONLY the tabindex it added, and empties the nav; a second call is a no-op"
+    ],
+    "a11y": [
+        "Renders a <nav> landmark with an always-present accessible name (default 'On this page') — a docs page holds several <nav> elements and the name is what distinguishes them in a landmark list",
+        "The entries are a REAL <ul>/<li> list with a nested <ul> per sub-level, so assistive tech announces the count and the depth; a stack of <div>s would announce neither",
+        "Links are real <a href=\"#id\"> elements — Tab, Enter, middle-click, ctrl/cmd-click and 'copy link address' all keep their native behaviour. The click handler bails out on any modified click",
+        "The current entry is marked aria-current=\"location\", NOT aria-current=\"page\": every link here points inside the page the reader is already on",
+        "Exactly one link carries aria-current at a time",
+        "The current state is never conveyed by colour alone (WCAG 1.4.1): the entry gains --font-weight-semibold AND a solid accent rail on top of the muted rail every entry carries",
+        "Clicking an entry moves FOCUS to the target heading, so keyboard and screen-reader users land where sighted users are looking. tabindex=\"-1\" is added only when the heading has none of its own, and removed again on destroy",
+        "focus() is called with preventScroll so it does not jump instantly and defeat the smooth scroll",
+        "Smooth scrolling is gated on prefers-reduced-motion: reduce, which forces behavior: 'auto'; matchMedia is read at click time and guarded for being absent",
+        "CSS transitions are wrapped in prefers-reduced-motion: no-preference via the a11y motion-safe mixin",
+        "Forced colours redraws the rail (GrayText at rest, Highlight when current/hovered) and restores the focus outline — a11y.focus-ring draws its indicator as a box-shadow over `outline: none`, and forced-colors discards box-shadow without reinstating the suppressed outline (WCAG 2.4.7)",
+        "The empty state is <nav hidden>, which removes the nameless, link-less landmark from the accessibility tree instead of leaving a dead focus stop"
+    ],
+    "ai": {
+        "synonyms": [
+            "table of contents",
+            "toc",
+            "on this page",
+            "page outline",
+            "in this article",
+            "jump links",
+            "anchor nav",
+            "heading index",
+            "scroll spy",
+            "docs sidebar right rail"
+        ],
+        "avoid": [
+            "using <TableOfContents> for site navigation between pages — it only ever links within the current document; use <Navbar> or a docs sidebar for cross-page links",
+            "mounting it before the content it describes exists — the scan happens once, at construction, and an empty container yields a hidden, empty nav",
+            "pointing it at a container that holds the page chrome as well as the article — every h2/h3 in range is collected, including a heading inside a card or a form",
+            "setting maxLevel to 4+ on a long page — the outline becomes longer than the section it indexes",
+            "hand-rolling anchor links next to a <Prose> document — the ids, de-duplication, nesting, scroll-spy and reduced-motion handling are exactly what this component exists to own"
+        ],
+        "patterns": [
+            "Beside a Prose document, zero config: <TableOfContents /> then <Prose as=\"'article'\">…</Prose>",
+            "Explicit container: <TableOfContents container=\"'#docs-body'\" />",
+            "Deeper outline: <TableOfContents minLevel=\"2\" maxLevel=\"4\" />",
+            "Custom landmark name: <TableOfContents label=\"'Contents'\" />",
+            "Instant jumps for a dense reference page: <TableOfContents smoothScroll=\"false\" />"
+        ]
+    },
+    "designGuidance": {
+        "surface": "Transparent — the ToC sits on whatever surface the page gives it and adds no fill of its own. The only painted area is the hover tint, a --color-primary wash at the design-system hover opacity. Text is --color-text-muted at rest so the list recedes behind the article it indexes, and steps up to --color-text for the hovered and current entries.",
+        "depth": "Flat. No shadow, no elevation. A table of contents is a wayfinding aid beside the content, not a panel floating over it.",
+        "borders": "One border, used as a rail: a --border-width-medium inline-start edge on every link. It is present at all times (muted --color-divider at rest) so activation changes a colour rather than a box size — no reflow as the reader scrolls — and so the rail reads as a continuous track down the list. Only the inline-end corners are rounded, keeping the rail square against the track.",
+        "interactivity": "Every entry is a link, and nothing else is interactive. Hover raises the text colour, brightens the rail and adds the primary tint; :focus-visible surfaces the design-system focus ring. The current entry is the only persistent state, and it is doubled up (weight + accent rail) so it never depends on colour.",
+        "motion": "Colour, background and border transitions only, all inside prefers-reduced-motion: no-preference. The click-to-heading scroll is smooth by default and instant under reduced motion — that switch is read at click time, so a preference change mid-session takes effect immediately.",
+        "darkMode": "Nothing to do: every value is a --color-* token, so the muted/rest/current relationship inverts with the theme. The forced-colours block is the separate case — there the rail is redrawn with GrayText/Highlight because author colours are discarded outright.",
+        "bestPractices": "Reach for it on any page long enough that the reader needs to know where they are: docs, guides, changelogs, long-form posts. Pair it with <Prose> and leave `container` alone — the default '.u-prose' already points at the article. Keep the default 2-3 level window; a deeper outline competes with the page. The component is `position: sticky` with its own max block size, so drop it straight into a docs layout column and it will follow the reader and scroll internally when the outline is long. If the page is short enough to read without scrolling, prefer no ToC at all — the component will render one, but a two-entry outline is chrome, not navigation."
+    },
+    "examples": [
+        {
+            "id": "default",
+            "title": "Beside a Prose document",
+            "pithy": "<TableOfContents />",
+            "assertions": [
+                "renders <nav class='ui-toc' aria-label='On this page'>",
+                "collects h2 and h3 from the default .u-prose container",
+                "each entry is an <a href='#id'> inside an <li> inside a <ul>"
+            ]
+        },
+        {
+            "id": "nesting",
+            "title": "Nested outline",
+            "pithy": "<TableOfContents minLevel=\"2\" maxLevel=\"3\" />",
+            "assertions": [
+                "h3 entries render in a nested <ul> inside the preceding h2's <li>",
+                "an h3 before any h2 is promoted to the top level",
+                "each link records its source level on data-level"
+            ]
+        },
+        {
+            "id": "scroll-spy",
+            "title": "Scroll-spy",
+            "pithy": "<TableOfContents />",
+            "assertions": [
+                "the intersecting heading's link gains aria-current='location'",
+                "with several headings on screen the first in document order wins",
+                "the final heading becomes current once a scrollable page bottoms out",
+                "exactly one link carries aria-current at a time"
+            ]
+        },
+        {
+            "id": "custom-container",
+            "title": "Explicit container and label",
+            "pithy": "<TableOfContents container=\"'#docs-body'\" label=\"'Contents'\" />",
+            "assertions": [
+                "accepts a selector, an HTMLElement, or a () => HTMLElement getter",
+                "a container that matches nothing renders <nav hidden data-empty='true'> and DEV-warns"
+            ]
+        }
+    ]
+}