@pithyjs/pidl-catalog 0.1.0-beta.0

package/dist/specs/atoms/content/image.pidl.json

@@ -0,0 +1,227 @@
+{
+    "kind": "component",
+    "id": "ui.image",
+    "name": "Image",
+    "displayName": "Image",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "content",
+    "bidi": true,
+    "description": "Accessible, optimized image component. Mobile-first with lazy loading and async decoding by default. Enforces alt text for accessibility. Supports <picture> with multiple <source> elements for format negotiation (AVIF, WebP, fallback). Use width/height to prevent layout shift (CLS = 0).",
+    "props": [
+        {
+            "name": "src",
+            "reactive": true,
+            "label": "Image source",
+            "type": "string | Signal<string>",
+            "required": true,
+            "placeholder": "https://placehold.co/600x400?text=Replace+me",
+            "description": "Image source URL (required)",
+            "editor": { "type": "image" }
+        },
+        {
+            "name": "alt",
+            "reactive": true,
+            "label": "Alt text",
+            "type": "string | Signal<string>",
+            "kind": "alt-text",
+            "required": true,
+            "placeholder": "Replace this image and update the alt text",
+            "description": "Alt text for accessibility — REQUIRED. Use \"\" only for purely decorative images."
+        },
+        {
+            "name": "width",
+            "label": "Width",
+            "editor": { "tab": "layout" },
+            "type": "number",
+            "description": "Intrinsic width in pixels — prevents layout shift (CLS). Provide both width and height."
+        },
+        {
+            "name": "height",
+            "label": "Height",
+            "editor": { "tab": "layout" },
+            "type": "number",
+            "description": "Intrinsic height in pixels — prevents layout shift (CLS). Provide both width and height."
+        },
+        {
+            "name": "loading",
+            "label": "Loading",
+            "editor": { "tab": "settings" },
+            "type": "enum",
+            "enum": ["lazy", "eager"],
+            "default": "lazy",
+            "description": "Loading strategy — use 'eager' for above-the-fold / LCP images"
+        },
+        {
+            "name": "decoding",
+            "label": "Decoding",
+            "editor": { "tab": "settings" },
+            "type": "enum",
+            "enum": ["async", "sync", "auto"],
+            "default": "async",
+            "description": "Decoding strategy — async by default for non-blocking rendering"
+        },
+        {
+            "name": "fetchPriority",
+            "label": "Fetch priority",
+            "editor": { "tab": "settings" },
+            "type": "enum",
+            "enum": ["high", "low", "auto"],
+            "default": "auto",
+            "description": "Fetch priority hint — use 'high' for LCP images, 'low' for below-fold images"
+        },
+        {
+            "name": "aspectRatio",
+            "label": "Aspect ratio",
+            "editor": { "tab": "layout" },
+            "type": "enum",
+            "enum": ["16/9", "4/3", "1/1", "3/2", "21/9", "3/4", "2/3", "9/16"],
+            "description": "Aspect ratio of the image box. Leave empty for the image's natural ratio."
+        },
+        {
+            "name": "sizing",
+            "label": "Sizing",
+            "editor": { "tab": "layout" },
+            "type": "enum",
+            "enum": ["auto", "fill"],
+            "default": "auto",
+            "description": "Width behaviour — 'auto' (natural size, capped at container) or 'fill' (full container width)"
+        },
+        {
+            "name": "fit",
+            "label": "Fit",
+            "editor": { "tab": "layout" },
+            "type": "enum",
+            "enum": ["contain", "cover", "fill", "none", "scale-down"],
+            "default": "cover",
+            "description": "Object-fit — how the image fills its container"
+        },
+        {
+            "name": "sizes",
+            "label": "Sizes",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Responsive sizes attribute (e.g. '(max-width: 600px) 100vw, 50vw')"
+        },
+        {
+            "name": "srcset",
+            "label": "Srcset",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Srcset for responsive resolution switching (e.g. 'img-400.jpg 400w, img-800.jpg 800w')"
+        },
+        {
+            "name": "sources",
+            "label": "Sources",
+            "editor": { "tab": "settings" },
+            "type": "ImageSource[]",
+            "description": "Additional <source> elements for <picture> — enables AVIF/WebP with fallback. Each source has src, type, media, and srcset."
+        },
+        {
+            "name": "rounded",
+            "label": "Rounded",
+            "editor": { "tab": "effects" },
+            "type": "boolean | RadiusLevel",
+            "default": "none",
+            "description": "Border radius — true for 'md', or explicit level: 'xs', 'sm', 'md', 'lg', 'xl', 'full'"
+        }
+    ],
+    "events": [],
+    "tokens": {
+        "border.forced-colors": "--border-width-hairline solid CanvasText",
+        "radius": "--radius-{rounded} (via u-radius-* utility)",
+        "max-inline-size": "100% (logical property, not max-width)"
+    },
+    "spacing": {
+        "internal": "No internal spacing — image fills wrapper",
+        "image-to-caption": "--space-sm (close friends — image and caption are tightly coupled)",
+        "image-in-card": "--space-md (friends — image and card content are related)"
+    },
+    "constraints": [
+        "alt prop is REQUIRED — TypeScript enforces this at build time",
+        "Use alt='' ONLY for purely decorative images (sets role='presentation')",
+        "Always provide width + height to prevent layout shift (CLS)",
+        "Use loading='eager' + fetchPriority='high' for LCP images — never lazy+high (contradictory)",
+        "Use logical CSS properties only (max-inline-size, not max-width; inline-size, not width; block-size, not height)",
+        "Must handle forced-colors mode — thin CanvasText border for visibility",
+        "Must handle reduced motion — pause CSS animations on images"
+    ],
+    "a11y": [
+        "alt text is required via TypeScript — build error if omitted",
+        "Decorative images (alt='') get role='presentation' for older screen readers",
+        "width/height prevent layout shift for sighted users and magnification users",
+        "Forced-colors: thin border ensures image boundaries are visible",
+        "Reduced motion: CSS animations on images are paused (does not stop GIF/APNG playback)"
+    ],
+    "ai": {
+        "synonyms": [
+            "photo",
+            "picture",
+            "img",
+            "hero image",
+            "thumbnail",
+            "avatar image",
+            "banner"
+        ],
+        "avoid": [
+            "raw <img> tag — use <Image> component for optimization and a11y",
+            "missing alt text — always provide descriptive alt or alt='' for decorative",
+            "missing width/height — always provide both to prevent CLS",
+            "loading='lazy' with fetchPriority='high' — contradictory, use loading='eager'",
+            "hardcoded border-radius — use rounded prop with design system level"
+        ],
+        "patterns": [
+            "Hero image (LCP): <Image src=\"'/hero.jpg'\" alt=\"'Hero banner'\" width=\"1200\" height=\"600\" loading=\"'eager'\" fetchPriority=\"'high'\" aspectRatio=\"'16/9'\" />",
+            "Card thumbnail: <Image src=\"'/thumb.jpg'\" alt=\"'Product'\" width=\"400\" height=\"300\" rounded=\"'md'\" />",
+            "Avatar: <Image src=\"'/avatar.jpg'\" alt=\"'User photo'\" width=\"64\" height=\"64\" rounded=\"'full'\" />",
+            "Multi-format (AVIF/WebP): <Image src=\"'/photo.jpg'\" alt=\"'Photo'\" width=\"800\" height=\"600\" :sources=\"[{src:'/photo.avif',type:'image/avif'},{src:'/photo.webp',type:'image/webp'}]\" />",
+            "Decorative: <Image src=\"'/pattern.svg'\" alt=\"''\" />"
+        ]
+    },
+    "examples": [
+        {
+            "id": "basic",
+            "title": "Basic image with dimensions",
+            "pithy": "<Image src=\"'/photo.jpg'\" alt=\"'A sunset over the ocean'\" width=\"800\" height=\"600\" />",
+            "assertions": [
+                "has alt text",
+                "has width/height attributes",
+                "loading='lazy'",
+                "decoding='async'"
+            ]
+        },
+        {
+            "id": "lcp-hero",
+            "title": "LCP hero image (eager + high priority)",
+            "pithy": "<Image src=\"'/hero.jpg'\" alt=\"'Welcome banner'\" width=\"1200\" height=\"600\" loading=\"'eager'\" fetchPriority=\"'high'\" aspectRatio=\"'16/9'\" />",
+            "assertions": [
+                "loading='eager'",
+                "fetchpriority='high'",
+                "aspect-ratio set on wrapper"
+            ]
+        },
+        {
+            "id": "rounded-avatar",
+            "title": "Rounded avatar image",
+            "pithy": "<Image src=\"'/avatar.jpg'\" alt=\"'Jane Doe'\" width=\"100\" height=\"100\" rounded=\"'full'\" />",
+            "assertions": ["has u-radius-full class", "width=100", "height=100"]
+        },
+        {
+            "id": "picture-sources",
+            "title": "Multi-format with AVIF/WebP fallback",
+            "pithy": "<Image src=\"'/photo.jpg'\" alt=\"'Nature scene'\" width=\"800\" height=\"600\" :sources=\"[{src:'/photo.avif',type:'image/avif'},{src:'/photo.webp',type:'image/webp'}]\" />",
+            "assertions": [
+                "renders <picture> element",
+                "has <source> for AVIF",
+                "has <source> for WebP",
+                "fallback <img> for JPEG"
+            ]
+        },
+        {
+            "id": "decorative",
+            "title": "Decorative image (hidden from AT)",
+            "pithy": "<Image src=\"'/pattern.svg'\" alt=\"''\" />",
+            "assertions": ["alt=''", "role='presentation'"]
+        }
+    ]
+}

package/dist/specs/atoms/content/prose.pidl.json

@@ -0,0 +1,183 @@
+{
+    "kind": "component",
+    "id": "ui.prose",
+    "name": "Prose",
+    "displayName": "Prose",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "content",
+    "studioReady": false,
+    "bidi": true,
+    "description": "Long-form content wrapper for docs and articles. A thin semantic container that applies the design-system .u-prose utility (plus the .u-prose-{size} measure variant) and projects its children. All element-level typographic treatment — vertical rhythm, links, inline code, blockquote, tables, figures, description lists — lives in .u-prose in @pithyjs/design-system, not in the component, so the same treatment is available to consumers who use the utility class without the component.",
+    "props": [
+        {
+            "name": "content",
+            "label": "Content",
+            "editor": {
+                "tab": "content",
+                "multiline": true
+            },
+            "type": "string",
+            "required": false,
+            "placeholder": "Long-form body copy.",
+            "description": "Optional body, for callers that build the document in TypeScript rather than as projected children. The TypeScript API also accepts a Node or a { el, destroy } ui-kit component. Strings are inserted as text (never HTML) — avoids injection and stray {{ }} interpolation. Rendered AFTER any projected children; both are rendered, nothing is dropped. NOTE: `content` is plain text, so it cannot produce headings, paragraphs or lists — authoring a document through this field is not possible. That, plus a `slots.accepts` list that admits only CodeBlock/Callout/Image, is why `studioReady` is false: Prose is a developer-facing wrapper until it has a real builder authoring path (see BACKLOG #12)."
+        },
+        {
+            "name": "size",
+            "label": "Size",
+            "type": "enum",
+            "enum": ["sm", "md", "lg", "xl"],
+            "default": "md",
+            "description": "Reading measure and type size. 'md' (default) is the base .u-prose measure (65ch at --font-size-body) and emits NO variant class — .u-prose-md does not exist. 'sm' = 60ch/0.875rem, 'lg' = 70ch/1.125rem, 'xl' = 75ch/1.25rem."
+        },
+        {
+            "name": "as",
+            "label": "Element",
+            "editor": {
+                "tab": "settings"
+            },
+            "type": "enum",
+            "enum": ["div", "article", "section", "main", "aside"],
+            "default": "div",
+            "description": "Semantic element to render. Default 'div' contributes no implicit role, so a generic prose wrapper can never invent a spurious landmark or article region. Use 'article' when the content genuinely is a self-contained composition. Values outside this whitelist fall back to 'div' (a persisted document must not be able to choose the tag name)."
+        },
+        {
+            "name": "ariaLabel",
+            "label": "ARIA label",
+            "editor": {
+                "tab": "settings",
+                "visibleWhen": {
+                    "prop": "as",
+                    "in": ["article", "section", "main", "aside"]
+                }
+            },
+            "type": "string",
+            "required": false,
+            "description": "Accessible name for the container. ONLY applied when as is article | section | main | aside — the editor hides the field at any other `as` (visibleWhen), because the component drops it there and a saved value would persist in the document while the published page has no accessible name. At the default as='div' the element is role=generic, where ARIA-in-HTML prohibits aria-label and browsers/AT ignore it — the component drops it with a DEV warning rather than implying the region is named. Pair it with as='section' or as='aside', where a name is what promotes the element to a navigable landmark."
+        }
+    ],
+    "slots": [
+        {
+            "name": "default",
+            "displayName": "Document",
+            "description": "The primary authoring path: raw semantic HTML (h1-h6, p, ul/ol, blockquote, pre, table, figure, dl, hr, a, code, strong/em) and nested ui-kit components. MUST be named 'default': the block renderer only inlines the 'default' slot into the construction-time injection that <Prose> consumes via captureChildren() — a differently-named slot is wrapped in an inert <template data-slot=\"…\"> and, because the injection is still consumed, the projectRenderedSlots() fallback never runs and the content renders as nothing. Children render before the `content` prop. ui.heading and ui.text are deliberately NOT accepted: prose IS raw HTML, and routing headings through <Heading> would inject document hierarchy the author did not write — see ai.avoid, which this field must not contradict.",
+            "accepts": ["ui.code-block", "ui.callout", "ui.image"]
+        }
+    ],
+    "tokens": {
+        "measure": "65ch base; 60ch (sm) / 70ch (lg) / 75ch (xl) via .u-prose-{size} — set as max-inline-size",
+        "typography": "--font-size-body + --line-height-body (base), --font-weight-semibold (strong, dt, thead th), --font-family-mono (code, pre), --inline-code-font-size / --inline-code-padding-block / --inline-code-padding-inline / --inline-code-margin-inline (inline code chrome)",
+        "color": "--color-text (body, strong, dt, thead th), --color-text-muted (blockquote, figcaption, caption, dd), --color-primary + --color-primary-hover (links, blockquote accent), --color-surface-variant (inline code + pre fill), --color-border (code/pre/table rules), --color-divider (hr)",
+        "border": "--border-width-hairline (code, pre, table cells, hr), --border-width-thin (thead rule), --border-width-medium (blockquote accent bar)",
+        "radius": "--radius-xs (inline code), --radius-md (pre, images)",
+        "focus": "--focus-ring-width / --focus-ring-offset / --ring-color via the a11y focus-ring mixin on link :focus-visible",
+        "motion": "--motion-transition-color, --motion-duration-normal, --motion-easing-standard on link color/underline, inside prefers-reduced-motion: no-preference"
+    },
+    "spacing": {
+        "rhythm-unit": "em, not --space-* — every rhythm value is relative to the container's own font-size, so the sm/lg/xl measures get proportionally tighter/looser spacing for free. A rem/token scale would hold the rhythm fixed while the type grew.",
+        "heading-block-start": "1.5em (h2) / 1.25em (h3) / 1em (h4-h6) — a heading binds to the section it opens, not to the paragraph above it",
+        "heading-block-end": "0.75em (h1, h2) / 0.5em (h3-h6) — close friends, heading to its first line",
+        "paragraph-block-end": "1.25em (friends — sibling paragraphs in one flow)",
+        "list-item-block-end": "0.5em; nested lists 0.5em block (lovers — a sub-list belongs to its own bullet)",
+        "block-elements": "1.5em block margin on pre, blockquote, figure, img/video, table; 2.5em on hr (strangers — a rule separates whole passages)",
+        "container-edges": "the first/last flow child has its outer block margin zeroed, so the container's own box owns the outer spacing"
+    },
+    "constraints": [
+        "Purely presentational container — it adds no interactivity of its own; any links/controls come from the projected content",
+        "Element-level treatment lives in the design-system .u-prose utility, NOT in the component's SCSS — do not fork it into ui-kit",
+        "All descendant rules are wrapped in :where(), so they carry zero added specificity — a component's own rule wins on any property it declares",
+        "Descendant rules additionally skip any nested ui-kit component ROOT and its internals (matched prefix-anchored as [class^='ui-'] / [class*=' ui-'], scoped under .u-prose, with prose's own .ui-prose hook excepted): a component owns its own box, including the properties it never declares (border, radius, block margin, overflow). Both mechanisms are load-bearing — :where() alone does NOT prevent that bleed",
+        "A component that HOSTS a nested <Prose> does not exclude that prose's content (the descendant terms carry :not(:has(.u-prose))), so <Prose><Tabs><Prose> keeps the inner document's element rules; a component inside that inner prose still excludes its own internals",
+        "Add the .u-not-prose class to opt an arbitrary subtree out of prose treatment entirely. The opt-out is scoped UNDER .u-prose, so a <Prose> rendered inside a .u-not-prose region (a shared layout that knows nothing about the marker) is unaffected",
+        "pre code is explicitly reset so a code block never gets inline-code chrome on top of its own",
+        "String content is inserted as text (textContent/createTextNode), never HTML",
+        "as is whitelisted to div | article | section | main | aside; anything else falls back to div and DEV-warns",
+        "size='md' (and an omitted size) emit no .u-prose-* class — .u-prose-md does not exist in the design system",
+        "Children render before the content prop; both are rendered, neither is dropped",
+        "destroy() drains the projected-children disposer and any content component's destroy, then empties the element; a second call is a no-op"
+    ],
+    "a11y": [
+        "Default element is div — no implicit role, so a generic wrapper cannot invent a landmark or an article region inside a page that already has real ones",
+        "as='section' / 'aside' / 'main' / 'article' create nameable roles — pair them with ariaLabel so the landmark is named and navigable. ariaLabel is applied ONLY on those; on the default role=generic <div> it is dropped with a DEV warning, because ARIA-in-HTML prohibits it there",
+        "ariaLabel is trimmed; a whitespace-only value is ignored rather than producing an empty accessible name",
+        "Heading hierarchy is the author's: Prose never injects a heading and never renders <Heading>, so projected h1-h6 keep their document order",
+        "Links use the design-system link-underline treatment: a real text-decoration underline (never color alone, WCAG 1.4.1) plus the design-system focus ring on :focus-visible",
+        "Link color/underline transitions are wrapped in prefers-reduced-motion: no-preference",
+        "Forced-colors needs no override for prose's STATIC chrome: the mode substitutes system colors for every color/background-color/border-color prose sets, and every block (inline code, pre, blockquote, table cells) is drawn with a real border rather than fill alone, so each stays perceivable once fills are dropped. The link FOCUS RING is the exception and does need one — the a11y focus-ring mixin draws it as a box-shadow over `outline: none`, and forced-colors drops box-shadow without restoring the suppressed outline, so the link rule adds an explicit `outline: … solid Highlight` under (forced-colors: active) (WCAG 2.4.7). The prose rule cannot fall back to the global a:focus-visible outline: at (0,2,0) it outranks both the element-level a:focus-visible (0,1,1) and the global :focus-visible (0,1,0)"
+    ],
+    "ai": {
+        "synonyms": [
+            "prose",
+            "article body",
+            "long-form",
+            "rich text",
+            "markdown body",
+            "typography wrapper",
+            "readable content",
+            "docs body",
+            "measure",
+            "reading column"
+        ],
+        "avoid": [
+            "using <Prose> for a short label, caption or single line — use <Text>; Prose exists to set a reading measure and vertical rhythm over a whole document",
+            "wrapping app chrome (nav, toolbars, forms) in <Prose> — the element-level rhythm will fight the components' own spacing",
+            "re-styling elements inside prose from the page's own CSS — add .u-not-prose to the subtree instead",
+            "using <Heading> for the document's headings inside Prose — raw h1-h6 are correct here; prose IS raw HTML"
+        ],
+        "patterns": [
+            "Basic: <Prose><h2>Title</h2><p>Body copy.</p></Prose>",
+            "Semantic article: <Prose as=\"'article'\"><h1>Post title</h1><p>…</p></Prose>",
+            "Wider measure: <Prose size=\"'lg'\"><p>Longer reading column.</p></Prose>",
+            "Named landmark: <Prose as=\"'section'\" ariaLabel=\"'Release notes'\">…</Prose>",
+            "Opt a subtree out: <Prose><div class=\"u-not-prose\">…custom layout…</div></Prose>"
+        ]
+    },
+    "designGuidance": {
+        "surface": "The container itself is transparent — it inherits the page surface and sets only measure, base type size, line-height and text color. Visual weight comes from the elements inside it: inline code and pre sit on --color-surface-variant, blockquote is a muted, italic passage behind a --color-primary accent bar, tables are ruled with hairline --color-border cell borders.",
+        "depth": "Flat — no shadow anywhere. Prose is a reading surface; depth would compete with the text.",
+        "borders": "Hairline rules only, except two deliberate accents: the blockquote's --border-width-medium inline-start bar and the --border-width-thin rule under a thead. Images and pre share --radius-md; inline code takes --radius-xs so it stays a chip inside a text line.",
+        "interactivity": "Only links. They carry a real underline at rest (never color alone), shift to --color-primary-hover on hover/focus, and surface the design-system focus ring on :focus-visible. Everything else in prose is inert.",
+        "motion": "Static except the link color/underline transition, which is gated behind prefers-reduced-motion: no-preference.",
+        "bestPractices": "Reach for Prose whenever a block of authored content is longer than a couple of sentences: docs pages, blog posts, changelogs, rendered markdown, CMS bodies. Keep the default measure — 65ch is the readable band; go 'lg'/'xl' only for hero-weight editorial, 'sm' for dense reference material in a sidebar. Author the document with raw semantic HTML and let .u-prose do the styling; drop in ui-kit components (CodeBlock, Callout) freely — prose both loses on specificity (:where()) and skips their subtrees outright, so they keep their own chrome. If a subtree needs bespoke layout, mark it .u-not-prose rather than fighting the rhythm with page CSS."
+    },
+    "examples": [
+        {
+            "id": "default",
+            "title": "Document body",
+            "pithy": "<Prose><h2>Reactive signals</h2><p>Components never re-render.</p></Prose>",
+            "assertions": [
+                "renders <div class='ui-prose u-prose'>",
+                "no u-prose-* variant class at the default size",
+                "projected children are rendered inside the container"
+            ]
+        },
+        {
+            "id": "sizes",
+            "title": "Measure variants",
+            "pithy": "<Prose size=\"'lg'\"><p>A wider reading column.</p></Prose>",
+            "assertions": [
+                "sm/lg/xl add .u-prose-sm / .u-prose-lg / .u-prose-xl",
+                "md (and an omitted size) add no variant class"
+            ]
+        },
+        {
+            "id": "semantic-element",
+            "title": "Semantic element",
+            "pithy": "<Prose as=\"'article'\" ariaLabel=\"'Release notes'\"><h1>0.1.0</h1></Prose>",
+            "assertions": [
+                "renders an <article> element",
+                "aria-label is set from the trimmed ariaLabel",
+                "an unknown `as` falls back to <div>"
+            ]
+        },
+        {
+            "id": "text-content",
+            "title": "Text content prop",
+            "pithy": "<Prose content=\"'Plain body copy, inserted as text.'\" />",
+            "assertions": [
+                "content is inserted with textContent — <b>markup</b> stays literal",
+                "a { el, destroy } content handle mounts and its destroy is chained"
+            ]
+        }
+    ]
+}

package/dist/specs/atoms/content/stat.pidl.json

@@ -0,0 +1,158 @@
+{
+    "kind": "component",
+    "id": "ui.stat",
+    "name": "Stat",
+    "displayName": "Stat",
+    "version": "0.1.0",
+    "level": "molecule",
+    "domain": "content",
+    "bidi": true,
+    "description": "Display statistic — a large value over a caption/label, with optional smaller supporting description. Non-interactive display primitive reusable across landing pages, dashboards, and marketing sections.",
+    "props": [
+        {
+            "name": "value",
+            "reactive": true,
+            "label": "Value",
+            "type": "string | Signal<string>",
+            "required": true,
+            "placeholder": "100",
+            "description": "The large display value (e.g. \"100\", \"0.8 KB\", \"AAA\"). Rendered prominently at --font-size-2xl."
+        },
+        {
+            "name": "label",
+            "reactive": true,
+            "label": "Label",
+            "type": "string | Signal<string>",
+            "required": true,
+            "placeholder": "Components",
+            "description": "Caption shown directly under the value. Body-sized text."
+        },
+        {
+            "name": "description",
+            "reactive": true,
+            "label": "Description",
+            "type": "string | Signal<string>",
+            "placeholder": "up 12% this month",
+            "description": "Optional smaller supporting text below the label."
+        },
+        {
+            "name": "color",
+            "label": "Color",
+            "editor": { "type": "token-color" },
+            "type": "enum",
+            "enum": [
+                "primary",
+                "secondary",
+                "tertiary",
+                "success",
+                "info",
+                "warning",
+                "danger"
+            ],
+            "description": "Semantic color for the value — maps to --color-* tokens via --_stat-value-color. Omit for the normal text color."
+        },
+        {
+            "name": "align",
+            "label": "Alignment",
+            "editor": { "tab": "layout" },
+            "type": "enum",
+            "enum": ["start", "center", "end"],
+            "default": "start",
+            "description": "Text/box alignment — logical values (start/center/end) for RTL support."
+        },
+        {
+            "name": "id",
+            "label": "Anchor ID",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Optional element id."
+        }
+    ],
+    "events": [],
+    "tokens": {
+        "value.font-size": "--font-size-2xl",
+        "value.font-weight": "--font-weight-bold",
+        "value.color": "--color-{color} (via --_stat-value-color; defaults to --color-text)",
+        "label.font-size": "--font-size-body",
+        "label.font-weight": "--font-weight-medium",
+        "description.font-size": "--font-size-sm",
+        "description.color": "--color-text-muted"
+    },
+    "spacing": {
+        "value-to-label": "--space-sm (close friends — value and label read as one unit)",
+        "label-to-description": "--space-xs (lovers — the caption's supporting note)"
+    },
+    "constraints": [
+        "value and label are required",
+        "Colors are semantic only (primary/secondary/tertiary/success/info/warning/danger) — omit for normal text color",
+        "Alignment uses logical values (start/center/end), never physical left/right",
+        "Reading order is fixed: value, then label, then description",
+        "Non-interactive — no hover/focus/click behavior"
+    ],
+    "a11y": [
+        "Renders plain display text in logical reading order (value → label → description)",
+        "No ARIA roles needed — it is static content, not a control",
+        "Forced-colors: value falls back to CanvasText for visibility",
+        "Color is decorative emphasis — the label carries the meaning, so semantic color is not the only signal"
+    ],
+    "ai": {
+        "synonyms": [
+            "stat",
+            "statistic",
+            "metric",
+            "kpi",
+            "number",
+            "figure",
+            "count",
+            "big number",
+            "data point"
+        ],
+        "avoid": [
+            "Badge for a statistic — Badge is a nowrap inline pill that clips long values; use Stat for a value-over-label block",
+            "raw font sizes — the value size comes from --font-size-2xl",
+            "hardcoded colors — use the color prop",
+            "physical text-align left/right — use align start/center/end"
+        ],
+        "patterns": [
+            "Plain stat: <Stat value=\"'100'\" label=\"'Components'\" />",
+            "With supporting text: <Stat value=\"'0.8 KB'\" label=\"'Core size'\" description=\"'min + gzip'\" />",
+            "Semantic color + centered: <Stat value=\"'AAA'\" label=\"'Accessibility'\" color=\"'success'\" align=\"'center'\" />"
+        ]
+    },
+    "designGuidance": {
+        "surface": "Transparent by default — Stat is a text block, not a card. Place several in a Grid/Stack for a stats row, or inside a Card for a contained metric.",
+        "depth": "Flat. No shadow or border; the value's size and optional color carry the emphasis.",
+        "borders": "None.",
+        "interactivity": "Non-interactive display content — no hover, focus, or click.",
+        "bestPractices": [
+            "Use for a single headline number with a short caption; keep the value terse (a number, size, grade)",
+            "Reach for the description only for a small qualifier (delta, unit, timeframe) — full sentences belong in Text",
+            "Semantic color is decorative emphasis; never rely on it alone to convey meaning — the label must stand on its own",
+            "In a row of stats, keep alignment consistent and lay them out with Grid/Stack, not manual margins"
+        ]
+    },
+    "examples": [
+        {
+            "id": "plain",
+            "title": "Plain stat",
+            "pithy": "<Stat value=\"'100'\" label=\"'Components'\" />",
+            "assertions": [
+                "has ui-stat class",
+                "value in .ui-stat-value",
+                "label in .ui-stat-label"
+            ]
+        },
+        {
+            "id": "with-description",
+            "title": "Stat with supporting description",
+            "pithy": "<Stat value=\"'0.8 KB'\" label=\"'Core size'\" description=\"'min + gzip'\" />",
+            "assertions": ["renders .ui-stat-description"]
+        },
+        {
+            "id": "colored-centered",
+            "title": "Semantic color, centered",
+            "pithy": "<Stat value=\"'AAA'\" label=\"'Accessibility'\" color=\"'success'\" align=\"'center'\" />",
+            "assertions": ["data-color='success'", "data-align='center'"]
+        }
+    ]
+}