@pithyjs/pidl-catalog 0.1.0-beta.0

package/dist/specs/atoms/data/donut.pidl.json

@@ -0,0 +1,352 @@
+{
+    "kind": "component",
+    "id": "ui.donut",
+    "name": "Donut",
+    "displayName": "Donut Chart",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "data",
+    "bidi": true,
+    "description": "Parts-of-a-whole chart drawn as arcs on one stroked ring. Each segment is a full <circle> showing a single dash of its own share, positioned by stroke-dasharray/stroke-dashoffset, with the ring rotated -90° so segment one starts at twelve o'clock. The SVG is aria-hidden; a visually-hidden data table carries every value and share and is the chart's accessible representation. A colour key is built in and on by default — a segment is identified by its colour and by nothing else, and nobody can name a colour. Loading, empty (including an all-zero total), and error states are first-class.",
+    "props": [
+        {
+            "name": "label",
+            "label": "Accessible name",
+            "type": "string",
+            "required": true,
+            "placeholder": "Claims by confidence",
+            "description": "Captions the visually-hidden data table screen readers read instead of the graphic. Required — it is the chart's accessible name."
+        },
+        {
+            "name": "segments",
+            "label": "Segments",
+            "type": "DonutSegment[] | Signal<DonutSegment[]>",
+            "required": true,
+            "reactive": true,
+            "placeholder": [
+                { "label": "Verified", "value": 420 },
+                { "label": "Likely", "value": 260 },
+                { "label": "Speculative", "value": 130 }
+            ],
+            "description": "Slices in draw order. A value must be a finite number >= 0; anything else is counted as zero, warned about in DEV, and still listed in the accessible table.",
+            "itemSchema": {
+                "label": {
+                    "type": "string",
+                    "required": true,
+                    "description": "Category name. Becomes the row header in the accessible table."
+                },
+                "value": {
+                    "type": "number",
+                    "required": true,
+                    "description": "The quantity. Finite and >= 0."
+                },
+                "color": {
+                    "type": "string",
+                    "editor": { "type": "token-color" },
+                    "enum": [
+                        "primary",
+                        "secondary",
+                        "tertiary",
+                        "success",
+                        "info",
+                        "warning",
+                        "danger",
+                        "categorical-1",
+                        "categorical-2",
+                        "categorical-3",
+                        "categorical-4",
+                        "categorical-5",
+                        "categorical-6"
+                    ],
+                    "description": "Design-token name for this slice. Omit to take the categorical palette slot for the segment's index — the correct default for identity encoding."
+                }
+            }
+        },
+        {
+            "name": "total",
+            "label": "Centre value",
+            "type": "string | Signal<string>",
+            "reactive": true,
+            "placeholder": "1.2k",
+            "description": "Centre display value. Defaults to the formatted sum of the segments; override to show an abbreviated or externally computed figure."
+        },
+        {
+            "name": "caption",
+            "label": "Centre caption",
+            "type": "string | Signal<string>",
+            "reactive": true,
+            "placeholder": "claims",
+            "description": "Small uppercase caption under the centre value. Omitted entirely when unset. Dropped once the drawing is narrower than 8rem, on one threshold shared by every size — a caption is words, and words stop being readable below a width that has nothing to do with how big the chart was asked to be. `size='sm'` caps AT 8rem, so an `sm` chart never renders a caption at any width; that is deliberate (it is the stat-tile size, where the number alone is the point and the data table still names the unit), and setting both now warns in DEV instead of failing silently."
+        },
+        {
+            "name": "legend",
+            "label": "Colour key",
+            "editor": { "tab": "layout" },
+            "type": "enum",
+            "enum": ["end", "bottom", "none"],
+            "default": "end",
+            "description": "Where the colour key sits. 'end' puts it beside the ring and wraps it underneath when the row cannot hold both — intrinsically, with no breakpoint deciding. 'bottom' keeps it under the ring at every width. 'none' removes it, and is only correct when the colour-to-category mapping is carried elsewhere: a one-segment ring, or a row of donuts under one shared key."
+        },
+        {
+            "name": "size",
+            "label": "Size",
+            "editor": { "tab": "layout" },
+            "type": "enum",
+            "enum": ["sm", "md", "lg"],
+            "default": "md",
+            "description": "Caps the chart's inline extent, and floors it at 6rem — below that the ring is thinner than its own stroke and no centre label fits inside it, so the chart stops shrinking and lets the container overflow rather than degrading where nobody notices. Intrinsically fluid between the two, with no breakpoints. When a colour key is shown the cap applies to the DRAWING rather than to the figure: capping the pair at the drawing's size would take the space out of the ring. `size` sets the centre label's CEILING; the label itself is sized `clamp(floor, Ncqi, ceiling)` against the drawing's own inline extent, so it can never outgrow the ring hole and a larger size can never produce smaller text at the same width."
+        },
+        {
+            "name": "loading",
+            "label": "Loading",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "reactive": true,
+            "description": "Hides the drawing and the table, shows a pulsing skeleton in the drawing's slot, and sets aria-busy on the drawing's wrapper. The colour key keeps its box and loses its text, so the chart does not resize when data arrives. Outranks every other state."
+        },
+        {
+            "name": "error",
+            "label": "Error",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "reactive": true,
+            "description": "Hides the graphic and the table and shows the error message. Outranks the empty state — a failed fetch usually leaves an empty array behind it."
+        },
+        {
+            "name": "errorMessage",
+            "label": "Error message",
+            "editor": { "tab": "settings" },
+            "type": "string | Signal<string>",
+            "default": "Chart data unavailable",
+            "reactive": true,
+            "description": "Copy shown in the error state."
+        },
+        {
+            "name": "emptyMessage",
+            "label": "Empty message",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "default": "No data to display",
+            "description": "Copy shown when there are no segments, or when every segment is zero."
+        },
+        {
+            "name": "loadingLabel",
+            "label": "Loading message",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "default": "Loading chart…",
+            "description": "Copy shown in the loading state."
+        },
+        {
+            "name": "id",
+            "label": "ID",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Explicit element ID on the <figure> root."
+        }
+    ],
+    "events": [],
+    "slots": [],
+    "tokens": {
+        "track.stroke": "--color-surface-variant",
+        "segment.stroke": "--color-categorical-1 … --color-categorical-6",
+        "total.color": "--color-text",
+        "total.font": "--font-family-mono",
+        "total.size.ceiling": "--font-size-lg (the clamp's upper bound, not a fixed size)",
+        "total.size.floor": "--font-size-sm",
+        "caption.color": "--color-text-muted",
+        "caption.size": "--font-size-xs",
+        "legend.swatch.background": "--color-categorical-1 … --color-categorical-6 (the same token the swatch's own arc takes)",
+        "legend.name.color": "--color-text-muted",
+        "legend.value.color": "--color-text",
+        "legend.value.font": "--font-family-mono",
+        "legend.size": "--font-size-sm",
+        "legend.radius": "--radius-sm",
+        "legend.swatch.radius": "--radius-xs",
+        "legend.emphasis.background": "--color-surface-variant",
+        "legend.emphasis.motion": "--motion-transition-background",
+        "status.color": "--color-text-muted",
+        "status.error.color": "--color-danger",
+        "placeholder.background": "--color-surface-variant",
+        "placeholder.motion": "--motion-duration-slow"
+    },
+    "spacing": {
+        "internal": {
+            "graphic-to-status": { "relationship": "close_friends", "token": "sm" },
+            "total-to-caption": { "relationship": "lovers", "token": "xs" },
+            "graphic-to-legend": {
+                "relationship": "acquaintances",
+                "token": "lg",
+                "note": "Two different kinds of thing, read in turn. Drops to `md` when the key is placed below the ring, where it reads as a caption of the drawing."
+            },
+            "swatch-to-name": {
+                "relationship": "lovers",
+                "token": "xs",
+                "note": "A swatch means nothing apart from its name."
+            },
+            "legend-row-to-row": {
+                "relationship": "lovers",
+                "token": "xs",
+                "note": "Rows of one key. Each row also carries `xs` padding, so the hover background reads as a row rather than as a stripe behind the text."
+            }
+        }
+    },
+    "constraints": [
+        "Use logical properties only — no left/right, no width/height where inline-size/block-size applies",
+        "Colour is a design-token NAME, never a CSS value — there is no prop through which a hex code can reach a stylesheet",
+        "Series colour defaults to the categorical palette slot for the segment index; past the sixth slot the segment is painted neutral rather than repeating slot 1",
+        "The SVG is aria-hidden — the visually-hidden data table is the accessible representation, so `label` is required",
+        "A segment of zero is never drawn: with any linecap it would paint a stray mark for a share of nothing",
+        "A segment whose arc falls below half a user unit is omitted from the ring and kept in the table — clamping it up would push every later segment round the ring and misreport proportions",
+        "An all-zero total renders the empty state; the geometry never divides by zero",
+        "The drawing and the data table are hidden together in every non-ready state so the two cannot disagree about whether there is data. The KEY is not hidden with them: taking its height away resized the chart by 185px when data arrived, which is what the skeleton exists to prevent. It keeps its box and loses its text to skeleton bars, so it states nothing while reserving the space it will need",
+        "The chart's total is a <tfoot> row in the data table. The centre of the ring is aria-hidden, so without it the headline number reaches a screen reader nowhere at all — and under a `total` override it is not recoverable by summing the body rows either",
+        "A share that is greater than zero but rounds to zero reads '<0.1%', never '0%'. A component arguing that a chart must not round a segment out of the DATA cannot then report a segment that exists as nothing",
+        "An empty or whitespace-only segment label is a MISSING label and becomes 'Series N'. `??` let '' through and produced a blank row header and a blank key row — a category a reader can neither name nor look up",
+        "An overflowed total (finite values summing past Number.MAX_VALUE) renders the empty state. A total that is not a finite number is not a whole to take parts of, and the alternative was Infinity/Infinity — NaN in the markup of a chart still reporting itself ready",
+        "A multi-segment donut must carry a colour key — its own, or one shared on the page. Colour is the only thing identifying a segment (WCAG 1.4.1). `legend: 'none'` opts out of the built-in key, not out of the requirement",
+        "The key is text on screen, never a hover tooltip: hover has no touch and no keyboard equivalent, so a mapping that lives only there is a mapping some readers never get — and revealed content is then bound by WCAG 1.4.13",
+        "Labels are never drawn inside the arcs: the ring floors at 6rem, where arcs are a few device pixels tall, and the segments most in need of a label are the small ones with no room for one",
+        "Every segment gets a key row, including the ones the ring could not draw — a sub-pixel segment has no arc to point at and is exactly the one a reader cannot otherwise account for",
+        "One colour resolution feeds both the arc and its swatch; a key painted by a second call is a key that can disagree with the graphic, and disagree quietly",
+        "Hover emphasis grows the arc rather than dimming its neighbours — dimming a mark lowers its contrast against the surface, and WCAG 1.4.11 asks for 3:1 from every one of them"
+    ],
+    "a11y": [
+        "SVG carries aria-hidden='true' and focusable='false' — it is decoration over the real data",
+        "A <table class='u-sr-only'> carries every value and share, captioned with the required `label` prop",
+        "Table headers are scoped: <th scope='col'> in the head, <th scope='row'> per segment",
+        "Zero-value and sub-pixel segments appear in the table even though they are not drawn",
+        "Status messages live in a role='status' region present from first render — a live region inserted when it gains content is often not announced",
+        "aria-busy='true' while loading goes on the drawing's wrapper (.ui-chart-body), NEVER on the root. The role='status' region is a child of the root, and a live region inside an aria-busy subtree has its changes DEFERRED until busy clears — which happens in the same call that blanks the region, so the announcement an AT ends up processing is 'empty'. Four charts loading announced nothing on the way in and nothing on the way out",
+        "A chart mounted ALREADY in a non-ready state does not announce that state: the first render is synchronous with construction, so the region carries its message before the caller has appended the chart, and a live region arriving with content reads as an insertion. Every state change after mount does announce",
+        "forced-color-adjust: none on the drawing — in a chart the colour IS the data, so flattening six slots to one system colour would delete the encoding; the table remains authoritative",
+        "Centre label is aria-hidden — it repeats the table's <tfoot> total, which is where a screen reader gets it",
+        "The <tfoot> row carries the caption as its unit, so it reads as a summary and not as one more category: 'Total builds, 1.2k, 100%'",
+        "The legend is aria-hidden for the same reason: the table already carries every category, value and share, and exposing both would read the dataset twice, the second time in a flatter form",
+        "Nothing inside the legend is focusable, which is what makes hiding it from the accessibility tree safe",
+        "Hover emphasis carries no information — every category and share is already on screen — so it is free to be pointer-only; no keyboard or touch reader loses anything by never triggering it",
+        "Legend swatches keep forced-color-adjust: none for the same reason the drawing does, and gain a CanvasText border so they stay visible against a forced background"
+    ],
+    "ai": {
+        "synonyms": [
+            "donut chart",
+            "doughnut chart",
+            "ring chart",
+            "pie chart",
+            "breakdown chart",
+            "share of total",
+            "composition chart",
+            "chart legend",
+            "colour key",
+            "color key"
+        ],
+        "avoid": [
+            "Passing a CSS colour — the color field takes a design-token name",
+            "Encoding meaning with the semantic palette for arbitrary categories (danger for 'category 3' says category 3 is bad)",
+            "More than six uncoloured segments — fold the tail into an explicit 'Other' bucket",
+            "Relying on the graphic alone for accessibility — the table is the accessible representation and `label` captions it",
+            "Using a donut to compare values across charts; use it for parts of one whole",
+            "Setting legend='none' on a multi-segment donut with no other key on the page — that leaves colour as the sole carrier of meaning",
+            "Hand-rolling a legend beside the component: the swatch has to resolve its token exactly as the arc does, and a separately built key can drift from the graphic",
+            "Asking for a hover tooltip to carry the category names — it is unreachable by touch and by keyboard, and the key is already on screen"
+        ],
+        "patterns": [
+            "Basic: <Donut label=\"'Claims by confidence'\" segments=\"claims\" />",
+            "With centre caption: <Donut label=\"'Claims'\" segments=\"claims\" caption=\"'claims'\" />",
+            "Explicit colours: segments=[{ label: 'Passed', value: 900, color: 'success' }]",
+            "Live: <Donut label=\"'Traffic'\" segments=\"() => sources()\" loading=\"isFetching\" />",
+            "Abbreviated total: <Donut label=\"'Claims'\" segments=\"claims\" total=\"'1.2k'\" />",
+            "Key under the ring in a narrow column: <Donut label=\"'Claims'\" segments=\"claims\" legend=\"'bottom'\" />",
+            "Key suppressed because one is shared across a row of donuts: <Donut label=\"'Claims'\" segments=\"claims\" legend=\"'none'\" />"
+        ]
+    },
+    "examples": [
+        {
+            "id": "basic",
+            "title": "Three-segment breakdown",
+            "pithy": "<Donut label=\"'Claims by confidence'\" segments=\"claims\" />",
+            "assertions": [
+                "figure.ui-chart.ui-donut with data-status='ready'",
+                "one .ui-donut-segment per segment plus one .ui-donut-track",
+                "data-color runs categorical-1, categorical-2, categorical-3",
+                "no axe violations"
+            ]
+        },
+        {
+            "id": "zero-total",
+            "title": "Every segment is zero",
+            "pithy": "<Donut label=\"'Claims'\" segments=\"allZero\" />",
+            "assertions": [
+                "data-status='empty'",
+                "no NaN or Infinity anywhere in the markup",
+                "no arcs drawn"
+            ]
+        },
+        {
+            "id": "sub-pixel",
+            "title": "A segment too small to draw",
+            "pithy": "<Donut label=\"'Long tail'\" segments=\"[{label:'Bulk',value:100000},{label:'Speck',value:1}]\" />",
+            "assertions": [
+                "one arc drawn, two table rows",
+                "the omitted segment keeps its exact value in the table"
+            ]
+        },
+        {
+            "id": "legend-default",
+            "title": "The colour key is on by default",
+            "pithy": "<Donut label=\"'Claims by confidence'\" segments=\"claims\" />",
+            "assertions": [
+                "the figure carries data-legend='end'",
+                "one .ui-chart-legend-item per segment, in mark order",
+                "each swatch's data-color equals its own arc's data-color",
+                "the legend is aria-hidden='true', and the table still carries the numbers once"
+            ]
+        },
+        {
+            "id": "legend-keys-an-undrawn-segment",
+            "title": "A segment too small to draw still gets a key row",
+            "pithy": "<Donut label=\"'Long tail'\" segments=\"[{label:'Bulk',value:100000},{label:'Speck',value:1}]\" />",
+            "assertions": [
+                "one arc drawn, two legend rows, two table rows",
+                "the key row for the undrawn segment carries its exact value and share"
+            ]
+        },
+        {
+            "id": "legend-none",
+            "title": "No key",
+            "pithy": "<Donut label=\"'Claims'\" segments=\"claims\" legend=\"'none'\" />",
+            "assertions": [
+                "no data-legend attribute and no .ui-chart-legend",
+                "hovering an arc sets no emphasis — there is nothing to pair it with"
+            ]
+        },
+        {
+            "id": "loading",
+            "title": "Loading",
+            "pithy": "<Donut label=\"'Claims'\" segments=\"claims\" loading=\"true\" />",
+            "assertions": [
+                "aria-busy='true' on .ui-chart-body, and absent from the root",
+                "graphic and table both hidden",
+                "role='status' region reads 'Loading chart…'"
+            ]
+        },
+        {
+            "id": "error",
+            "title": "Error outranks empty",
+            "pithy": "<Donut label=\"'Claims'\" segments=\"[]\" error=\"true\" errorMessage=\"'Upstream timed out'\" />",
+            "assertions": [
+                "data-status='error'",
+                "the error message is shown, not the empty message"
+            ]
+        }
+    ],
+    "designGuidance": {
+        "surface": "No background of its own — the ring sits on whatever surface hosts it. The track uses --color-surface-variant so the unfilled remainder reads as a groove rather than a hole.",
+        "depth": "Flat. No shadow: a donut's depth cue is the ring's own thickness, and a drop shadow on a stroked arc muddies the boundary between adjacent slices.",
+        "borders": "None on the figure. In forced-colors the drawing opts out of colour substitution (forced-color-adjust: none) because the colour is the data; the placeholder gains a 1px CanvasText border so the reserved space stays visible.",
+        "interactivity": "Hover pairs a key row with its arc, in both directions: the arc thickens, the row takes a surface-variant background. That is emphasis, not disclosure — it restates what the key already says, which is precisely why it may be pointer-only. Nothing here is a route to information a keyboard or touch reader would otherwise miss, and nothing appears that WCAG 1.4.13 would then have to govern. Emphasis grows the arc rather than dimming its neighbours, so no mark's contrast against the surface ever drops. The centre label stays pointer-events: none so it can never intercept the hover.",
+        "bestPractices": "Use for parts of one whole, not for comparing across charts. Keep to six or fewer categories and fold the rest into 'Other' — the categorical palette guarantees separation for six. Leave colour unset unless a category has a genuine semantic (passed/failed); identity encoding is what the default is for. Keep the key: it is the only thing that turns a colour into a category, and the palette's CVD work guarantees the slots are DISTINGUISHABLE from each other, never that any one of them is identifiable. Reach for legend='bottom' in a narrow column, and legend='none' only when a shared key sits nearby. Always give a specific `label`: it is the caption a screen-reader user hears. Prefer an explicit `emptyMessage` that says what is missing ('No claims indexed yet') over the generic default."
+    }
+}

package/dist/specs/atoms/data/gauge.pidl.json

@@ -0,0 +1,274 @@
+{
+    "kind": "component",
+    "id": "ui.gauge",
+    "name": "Gauge",
+    "displayName": "Gauge Chart",
+    "version": "0.1.0",
+    "level": "atom",
+    "domain": "data",
+    "bidi": true,
+    "description": "One value's position within a range, drawn on a half circle. A full-length track path sits under a value path revealed by stroke-dasharray, so a short arc reads as 'short out of this much' rather than just 'short'. The arc is πr — half a circle, not a full one. The SVG is aria-hidden; a visually-hidden table carries the reading, the domain and the share of it. Colour is a prop: threshold-to-colour is application policy, not component behaviour.",
+    "props": [
+        {
+            "name": "label",
+            "label": "Accessible name",
+            "type": "string",
+            "required": true,
+            "placeholder": "Overall confidence",
+            "description": "Captions the visually-hidden data table screen readers read instead of the graphic, and names the reading's row. Required — it is the chart's accessible name."
+        },
+        {
+            "name": "value",
+            "label": "Value",
+            "type": "number | Signal<number>",
+            "required": true,
+            "reactive": true,
+            "placeholder": 55,
+            "description": "The reading. Clamped into the domain rather than allowed to overdraw — a gauge showing 140% would wrap past its own start and read as 40%. A non-finite value renders the error state, not a reading of zero."
+        },
+        {
+            "name": "min",
+            "label": "Minimum",
+            "editor": { "tab": "settings" },
+            "type": "number | Signal<number>",
+            "default": 0,
+            "reactive": true,
+            "description": "Domain floor."
+        },
+        {
+            "name": "max",
+            "label": "Maximum",
+            "editor": { "tab": "settings" },
+            "type": "number | Signal<number>",
+            "default": 100,
+            "reactive": true,
+            "description": "Domain ceiling. Must be greater than min; a degenerate or inverted domain renders the error state instead of dividing by zero."
+        },
+        {
+            "name": "color",
+            "label": "Colour",
+            "editor": { "type": "token-color" },
+            "type": "enum",
+            "enum": [
+                "primary",
+                "secondary",
+                "tertiary",
+                "success",
+                "info",
+                "warning",
+                "danger",
+                "categorical-1",
+                "categorical-2",
+                "categorical-3",
+                "categorical-4",
+                "categorical-5",
+                "categorical-6"
+            ],
+            "default": "primary",
+            "reactive": true,
+            "description": "Design-token name for the value arc. The component never picks a colour from the value — the same 30% is excellent for a defect rate and dire for uptime, so the threshold policy belongs to the call site. Reactive, because that policy is only useful if the colour follows the reading: pass an accessor and the arc recolours as the value crosses a threshold. It was documented as live and resolved once at construction, so a gauge sweeping from 40 to 92 kept its first colour the whole way."
+        },
+        {
+            "name": "caption",
+            "label": "Caption",
+            "type": "string | Signal<string>",
+            "reactive": true,
+            "placeholder": "verified",
+            "description": "Small uppercase caption under the percentage. Omitted entirely when unset. Dropped once the drawing is narrower than 8rem, on one threshold shared by every size — a caption is words, and words stop being readable below a width that has nothing to do with how big the chart was asked to be. `size='sm'` caps AT 8rem, so an `sm` chart never renders a caption at any width; that is deliberate (it is the stat-tile size, where the number alone is the point and the data table still names the unit), and setting both now warns in DEV instead of failing silently."
+        },
+        {
+            "name": "size",
+            "label": "Size",
+            "editor": { "tab": "layout" },
+            "type": "enum",
+            "enum": ["sm", "md", "lg"],
+            "default": "md",
+            "description": "Caps the chart's inline extent, and floors it at 6rem — below that no centre label fits over the arc at any legible size, so the chart stops shrinking and lets the container overflow rather than degrading where nobody notices. Intrinsically fluid between the two, with no breakpoints. `size` sets the label's CEILING; the label itself is sized against the drawing, so a larger size can never produce smaller text at the same width."
+        },
+        {
+            "name": "loading",
+            "label": "Loading",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "reactive": true,
+            "description": "Hides the arc and the table, shows a pulsing skeleton in the drawing's slot, and sets aria-busy on the drawing's wrapper. Outranks every other state."
+        },
+        {
+            "name": "error",
+            "label": "Error",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "reactive": true,
+            "description": "Hides the graphic and the table and shows the error message. A domain that makes no sense sets this state on its own."
+        },
+        {
+            "name": "errorMessage",
+            "label": "Error message",
+            "editor": { "tab": "settings" },
+            "type": "string | Signal<string>",
+            "default": "Chart data unavailable",
+            "reactive": true,
+            "description": "Copy shown in the error state."
+        },
+        {
+            "name": "empty",
+            "label": "Empty",
+            "editor": { "tab": "settings" },
+            "type": "boolean | Signal<boolean>",
+            "default": false,
+            "reactive": true,
+            "description": "Force the empty state — there is no reading yet, as distinct from a reading of zero. A gauge cannot infer this: 0 is a legitimate value."
+        },
+        {
+            "name": "emptyMessage",
+            "label": "Empty message",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "default": "No data to display",
+            "description": "Copy shown in the empty state."
+        },
+        {
+            "name": "loadingLabel",
+            "label": "Loading message",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "default": "Loading chart…",
+            "description": "Copy shown in the loading state."
+        },
+        {
+            "name": "id",
+            "label": "ID",
+            "editor": { "tab": "settings" },
+            "type": "string",
+            "description": "Explicit element ID on the <figure> root."
+        }
+    ],
+    "events": [],
+    "slots": [],
+    "tokens": {
+        "track.stroke": "--color-surface-variant",
+        "value.stroke": "--color-primary (or any semantic / categorical token)",
+        "percent.color": "--color-text",
+        "percent.font": "--font-family-mono",
+        "percent.size.ceiling": "--font-size-lg (the clamp's upper bound, not a fixed size)",
+        "percent.size.floor": "--font-size-sm",
+        "caption.color": "--color-text-muted",
+        "caption.size": "--font-size-xs",
+        "value.motion": "--motion-duration-normal",
+        "value.easing": "--motion-easing-standard",
+        "status.error.color": "--color-danger"
+    },
+    "spacing": {
+        "internal": {
+            "graphic-to-status": { "relationship": "close_friends", "token": "sm" },
+            "percent-to-caption": { "relationship": "lovers", "token": "xs" }
+        }
+    },
+    "constraints": [
+        "Use logical properties only",
+        "The arc is πr, not 2πr — a half circle",
+        "Colour is a design-token NAME chosen by the caller, never derived from the value inside the component",
+        "The SVG is aria-hidden — the visually-hidden data table is the accessible representation, so `label` is required",
+        "No value path is drawn while the percentage rounds to zero. The arc wears a ROUND linecap, which renders any dash as a capsule one stroke width longer than itself — a 0.578-unit arc (value 0.4 of 100) painted a ~9-unit blob beside a label reading '0%'. A graphic that contradicts its own label inside one component is worse than one that omits a reading too small to show",
+        "A degenerate domain (max <= min) or a non-finite value renders the error state — presenting broken configuration as a reading of zero would be a lie",
+        "The value path is reused across renders so its dash length genuinely interpolates; the sweep respects prefers-reduced-motion",
+        "The arc is SVG and scales with its viewBox; the centre label is HTML and does not. `size` is the author's intent, fixed when the component is written, so it sets a CEILING and the label is sized `clamp(floor, Ncqi, ceiling)` against the drawing's own inline extent — no rungs, and no schedule that can fire on one size and not another. The caption is the exception: it is dropped on one absolute threshold shared by every size, because a sentence's minimum width has nothing to do with how big the chart was asked to be"
+    ],
+    "a11y": [
+        "SVG carries aria-hidden='true' and focusable='false'",
+        "A <table class='u-sr-only'> gives the reading, the minimum, the maximum and the share of range — a value without its range means nothing",
+        "Table headers are scoped: <th scope='col'> in the head, <th scope='row'> per measure",
+        "Status messages live in a role='status' region present from first render",
+        "aria-busy='true' while loading goes on the drawing's wrapper (.ui-chart-body), NEVER on the root. The role='status' region is a child of the root, and a live region inside an aria-busy subtree has its changes DEFERRED until busy clears — which happens in the same call that blanks the region, so the announcement an AT ends up processing is 'empty'. Four charts loading announced nothing on the way in and nothing on the way out",
+        "A chart mounted ALREADY in a non-ready state does not announce that state: the first render is synchronous with construction, so the region carries its message before the caller has appended the chart, and a live region arriving with content reads as an insertion. Every state change after mount does announce",
+        "forced-color-adjust: none on the drawing so the value arc stays distinguishable from the track; the table remains authoritative",
+        "The centre percentage is aria-hidden — it repeats the table's share of range",
+        "Colour is never the only channel: the arc length carries the reading, and the exact number is in the table"
+    ],
+    "ai": {
+        "synonyms": [
+            "gauge",
+            "half donut",
+            "semicircle chart",
+            "dial",
+            "speedometer",
+            "progress arc",
+            "score meter",
+            "percentage ring"
+        ],
+        "avoid": [
+            "Expecting the component to colour itself by threshold — compute the token name at the call site and pass it in",
+            "Passing a CSS colour instead of a token name",
+            "Using a gauge for several series — it shows exactly one reading",
+            "Leaving min/max at 0–100 when the real domain is something else; the accessible table publishes the domain and a wrong one misinforms",
+            "Using `value: 0` to mean 'no reading' — set `empty` instead"
+        ],
+        "patterns": [
+            "Basic: <Gauge label=\"'Overall confidence'\" value=\"score\" />",
+            "With caption: <Gauge label=\"'Confidence'\" value=\"score\" caption=\"'verified'\" />",
+            "Caller-side threshold policy, live: color=\"() => score() > 80 ? 'success' : 'warning'\"",
+            "Custom domain: <Gauge label=\"'Latency budget'\" value=\"150\" min=\"100\" max=\"200\" />",
+            "No reading yet: <Gauge label=\"'Confidence'\" value=\"0\" empty=\"true\" />"
+        ]
+    },
+    "examples": [
+        {
+            "id": "basic",
+            "title": "A reading out of 100",
+            "pithy": "<Gauge label=\"'Overall confidence'\" value=\"55\" />",
+            "assertions": [
+                "figure.ui-chart.ui-gauge with data-status='ready'",
+                "track and value paths share the same d",
+                "stroke-dasharray is 'πr×0.55 πr'",
+                "centre reads '55%'",
+                "no axe violations"
+            ]
+        },
+        {
+            "id": "explicit-colour",
+            "title": "Colour supplied by the call site",
+            "pithy": "<Gauge label=\"'Confidence'\" value=\"92\" color=\"'success'\" />",
+            "assertions": [
+                "value path carries data-color='success'",
+                "the same component with value=5 and color='success' is still green — no threshold logic"
+            ]
+        },
+        {
+            "id": "zero",
+            "title": "A reading of zero",
+            "pithy": "<Gauge label=\"'Confidence'\" value=\"0\" />",
+            "assertions": [
+                "no .ui-gauge-value element at all",
+                "the track is still drawn",
+                "centre reads '0%'"
+            ]
+        },
+        {
+            "id": "degenerate-domain",
+            "title": "max equals min",
+            "pithy": "<Gauge label=\"'Broken'\" value=\"5\" min=\"10\" max=\"10\" />",
+            "assertions": [
+                "data-status='error'",
+                "no NaN or Infinity anywhere in the markup"
+            ]
+        },
+        {
+            "id": "custom-domain",
+            "title": "A domain that is not 0–100",
+            "pithy": "<Gauge label=\"'Latency budget'\" value=\"150\" min=\"100\" max=\"200\" />",
+            "assertions": [
+                "centre reads '50%'",
+                "table rows publish Minimum 100 and Maximum 200"
+            ]
+        }
+    ],
+    "designGuidance": {
+        "surface": "No background of its own. The track uses --color-surface-variant, which is what turns the value arc from 'a short arc' into 'a short arc out of this much'. Never drop the track to save ink — without it the reading has no scale.",
+        "depth": "Flat. No shadow on the arc: the stroke width is the depth cue, and a shadow blurs the boundary between track and value.",
+        "borders": "None on the figure. In forced-colors the drawing opts out of colour substitution so the value arc stays distinguishable from the track, and the placeholder gains a CanvasText border.",
+        "interactivity": "Non-interactive. The value arc transitions its dash length under motion-safe, so a changing reading sweeps rather than jumps; the centre label is pointer-events: none.",
+        "bestPractices": "Set min/max to the real domain — the accessible table publishes them, so a default 0–100 on a scale that is not 0–100 misinforms a screen-reader user directly. Choose the colour at the call site with an explicit threshold function, and keep that function in one place so two gauges of the same metric cannot disagree. Pair a gauge with a caption naming the unit — at `md` or `lg`, since `sm` never renders one and the component warns in DEV if you try. Keep that caption to a couple of words: the Gliora design puts a sentence there, which cannot wrap inside the arc at any size the component offers. Use `empty` for 'no reading yet' rather than showing a zero that looks like a measurement."
+    }
+}