{
  "version": "0.12.1",
  "description": "Component contract matrix \u2014 the states each component must ship and its accessibility notes. Enforced by tools/verify.py against core/*.css; rendered on the docs site (/components/catalog).",
  "lifecycle": {
    "stable": {
      "requires": [
        "selector coverage in core/*.css (enforced by tools/verify.py)",
        "behavioural regression coverage for the interactive states (tests/browser/run.py)",
        "documented a11y notes covering keyboard + assistive technology"
      ],
      "evidence": "Behavioural regression coverage exists \u2014 a real browser exercises the shipped interaction (focus, keyboard, contrast), not merely the presence of a selector."
    },
    "beta": {
      "requires": [
        "selector coverage in core/*.css",
        "documented a11y notes",
        "at least an example-page usage"
      ],
      "evidence": "Shipped and dogfooded, but no dedicated behavioural regression test yet; the public API may still change between minor versions."
    },
    "experimental": {
      "requires": [
        "documented intent and a11y notes",
        "selector or example-page presence"
      ],
      "evidence": "Exploratory: no stability guarantee, no regression coverage; must not be depended on by products yet."
    },
    "deprecated": {
      "requires": [
        "a stated replacement (or an explicit no-replacement note)",
        "a migration note in CHANGELOG.md"
      ],
      "evidence": "Superseded; retained for compatibility and scheduled for removal on a dated release."
    }
  },
  "components": [
    {
      "class": "btn",
      "name": "Button",
      "source": "base.css",
      "states": [
        "default",
        "hover",
        "active",
        "focus-visible",
        "disabled",
        "busy (guardApply)"
      ],
      "verify": [
        ".btn",
        ".btn:hover",
        ".btn:active",
        ".btn:disabled",
        ".btn:focus-visible"
      ],
      "a11y": [
        "Use a real <button> or <a>; never a clickable div.",
        "Icon-only buttons need aria-label.",
        "guardApply freezes and relabels the submit button until navigation."
      ],
      "status": "stable"
    },
    {
      "class": "iconbtn",
      "name": "Icon button",
      "source": "base.css",
      "states": [
        "default",
        "hover",
        "active",
        "focus-visible"
      ],
      "verify": [
        ".iconbtn",
        ".iconbtn:hover",
        ".iconbtn:active",
        ".iconbtn:focus-visible"
      ],
      "a11y": [
        "aria-label is mandatory (the glyph is aria-hidden).",
        "Minimum 44px on coarse pointers."
      ],
      "status": "stable"
    },
    {
      "class": "px-sw",
      "name": "Switch",
      "source": "base.css",
      "states": [
        "checked",
        "unchecked",
        "disabled",
        "focus-visible"
      ],
      "verify": [
        ".px-sw",
        ".px-sw input:checked",
        ".px-sw input:disabled",
        ".px-sw input:focus-visible"
      ],
      "a11y": [
        "The visible label wraps a real checkbox; hidden twin carries the off value.",
        "aria-label carries the verb: Enable/Disable <object>.",
        "Coarse pointers get a 44px hit area.",
        "Disabled state dims the track and blocks interaction."
      ],
      "status": "stable"
    },
    {
      "class": "menu-item",
      "name": "Menu item",
      "source": "base.css",
      "states": [
        "default",
        "hover",
        "danger",
        "armed",
        "focus-visible"
      ],
      "verify": [
        ".menu-item",
        ".menu-item:hover",
        ".menu-item.danger",
        ".arm-del.armed",
        ".menu-item:focus-visible"
      ],
      "a11y": [
        "Destructive items use .arm-del with data-arm-label naming the object.",
        "Escape and outside click disarm; details close disarms."
      ],
      "status": "stable"
    },
    {
      "class": "nav-item",
      "name": "Nav item",
      "source": "base.css",
      "states": [
        "default",
        "hover",
        "active(selected)",
        "focus-visible"
      ],
      "verify": [
        ".nav-item",
        ".nav-item:hover",
        ".nav-item.active",
        ".nav-item:focus-visible"
      ],
      "a11y": [
        "aria-current=\"page\" on the active item.",
        "Active rail is border-inline-start (mirrors in RTL)."
      ],
      "status": "stable"
    },
    {
      "class": "chip",
      "name": "Chip",
      "source": "base.css",
      "states": [
        "default",
        "hover",
        "active(selected)",
        "focus-visible"
      ],
      "verify": [
        ".chip",
        ".chip:hover",
        ".chip.active",
        ".chip:focus-visible"
      ],
      "a11y": [
        "Counts live in .n; the whole chip is the target (not just the label)."
      ],
      "status": "stable"
    },
    {
      "class": "index-row",
      "name": "Index row",
      "source": "patterns.css",
      "states": [
        "default",
        "hover",
        "active",
        "focus-visible"
      ],
      "verify": [
        ".index-row",
        ".index-row:hover",
        ".index-row:active",
        ".index-row:focus-visible"
      ],
      "a11y": [
        "54px minimum height; one row = one destination."
      ],
      "status": "stable"
    },
    {
      "class": "tbl",
      "name": "Table",
      "source": "base.css",
      "states": [
        "default",
        "row hover",
        "selected",
        "reflowed (mcards)"
      ],
      "verify": [
        ".tbl",
        ".tbl tr:hover",
        ".tbl tr.selected",
        ".tbl.mcards",
        ".tbl-records"
      ],
      "a11y": [
        "th scope where the header is meaningful; row checkbox needs aria-label.",
        "Hover-revealed row actions must also be reachable by keyboard focus."
      ],
      "status": "stable"
    },
    {
      "class": "bulkbar",
      "name": "Bulk bar",
      "source": "base.css",
      "states": [
        "hidden",
        "shown with selection"
      ],
      "verify": [
        ".bulkbar",
        ".bulkbar.on"
      ],
      "a11y": [
        "role=region with aria-label; count is text, not colour."
      ],
      "status": "stable"
    },
    {
      "class": "savebar",
      "name": "Save bar",
      "source": "base.css",
      "states": [
        "sticky",
        "keyboard-lifted (JS transform)"
      ],
      "verify": [
        ".savebar"
      ],
      "a11y": [
        "Lifts above the mobile keyboard via keyboard-fit.js (transform), not a class toggle.",
        "One primary action per card."
      ],
      "status": "stable"
    },
    {
      "class": "msg",
      "name": "Flash message",
      "source": "base.css",
      "states": [
        "ok",
        "warn",
        "err"
      ],
      "verify": [
        ".msg",
        ".msg.ok",
        ".msg.warn",
        ".msg.err"
      ],
      "a11y": [
        "role=status (or role=alert for errors) on the rendered banner.",
        "Colour is always paired with text."
      ],
      "status": "stable"
    },
    {
      "class": "toast2",
      "name": "Toast",
      "source": "base.css",
      "states": [
        "ok",
        "warn",
        "err",
        "auto-dismiss"
      ],
      "verify": [
        ".toast2",
        ".toast2.ok",
        ".toast2.warn",
        ".toast2.err"
      ],
      "a11y": [
        "#toasts is aria-live=polite; one toast at a time."
      ],
      "status": "stable"
    },
    {
      "class": "badge",
      "name": "Badge",
      "source": "base.css",
      "states": [
        "neutral",
        "ok",
        "warn",
        "err",
        "acc",
        "solid"
      ],
      "verify": [
        ".badge",
        ".badge.ok",
        ".badge.warn",
        ".badge.err",
        ".badge.acc",
        ".badge.solid"
      ],
      "a11y": [
        "Uppercase micro-label; never the only signal \u2014 pair with text that says the same thing."
      ],
      "status": "stable"
    },
    {
      "class": "empty",
      "name": "Empty state",
      "source": "base.css",
      "states": [
        "default"
      ],
      "verify": [
        ".empty",
        ".empty h4"
      ],
      "a11y": [
        "h4 + one-line reason + at most one action; never a bare blank area."
      ],
      "status": "stable"
    },
    {
      "class": "dlg",
      "name": "Dialog (native)",
      "source": "base.css",
      "states": [
        "open (showModal)",
        "backdrop",
        "wide variant"
      ],
      "verify": [
        ".dlg",
        ".dlg::backdrop",
        ".dlg.dlg-wide",
        ".dlg-h",
        ".dlg-b",
        ".dlg-f"
      ],
      "a11y": [
        "Native <dialog> + showModal(): top layer, inert background, Escape, focus restore \u2014 do not hand-roll a focus trap.",
        "aria-labelledby points at the heading; autofocus the first meaningful control, not the close button.",
        "Backdrop click closes unless the dialog is destructive.",
        "Backdrop close is suppressed for [data-dlg-static] / [data-danger] dialogs."
      ],
      "status": "stable"
    },
    {
      "class": "tip",
      "name": "Tooltip",
      "source": "base.css",
      "states": [
        "hover",
        "focus-visible"
      ],
      "verify": [
        ".tip",
        ".tip:hover",
        ".tip:focus-visible::after",
        ".tip::after"
      ],
      "a11y": [
        "Decorative tips only; essential text must be in the DOM. Pair with aria-describedby for screen readers."
      ],
      "status": "stable"
    },
    {
      "class": "spinner",
      "name": "Spinner",
      "source": "base.css",
      "states": [
        "spinning",
        "reduced-motion (slowed)"
      ],
      "verify": [
        ".spinner",
        "@keyframes tri-spin"
      ],
      "a11y": [
        "Indeterminate progress: keep the action label honest ('Queued\u2026'), and slow to 1s under prefers-reduced-motion."
      ],
      "status": "stable"
    },
    {
      "class": "field-err",
      "name": "Field error",
      "source": "base.css",
      "states": [
        "message",
        "aria-invalid input"
      ],
      "verify": [
        ".field-err",
        "input[aria-invalid=\"true\"]"
      ],
      "a11y": [
        "Focusable summary at the top + inline message per field, linked with aria-describedby; aria-invalid=true on the control (W3C ARIA21)."
      ],
      "status": "stable"
    },
    {
      "class": "tabs",
      "name": "Tabs",
      "source": "base.css",
      "status": "stable",
      "states": [
        "selected",
        "hover",
        "focus-visible",
        "overflow-scroll"
      ],
      "verify": [
        ".tab",
        ".tablist",
        ".tab[aria-selected=\"true\"]",
        ".tab:focus-visible"
      ],
      "a11y": [
        "tablist/tab/tabpanel roles wired by components.js with roving tabindex and Arrow/Home/End.",
        "Panels are hidden, not unmounted; one tab is always selected."
      ]
    },
    {
      "class": "crumbs",
      "name": "Breadcrumbs",
      "source": "base.css",
      "status": "stable",
      "states": [
        "default",
        "current"
      ],
      "verify": [
        ".crumbs",
        ".crumbs [aria-current=\"page\"]"
      ],
      "a11y": [
        "nav[aria-label=Breadcrumb] wraps an ordered list; plain text + separators.",
        "aria-current on the leaf; the last item is not a link."
      ]
    },
    {
      "class": "radio",
      "name": "Radio",
      "source": "base.css",
      "status": "stable",
      "states": [
        "checked",
        "unchecked",
        "focus-visible",
        "disabled"
      ],
      "verify": [
        ".radio",
        ".radio input:checked",
        ".radio input:focus-visible"
      ],
      "a11y": [
        "Native input inside the label; group with fieldset/radiogroup and a shared name."
      ]
    },
    {
      "class": "slider",
      "name": "Slider",
      "source": "base.css",
      "status": "stable",
      "states": [
        "default",
        "focus-visible",
        "disabled"
      ],
      "verify": [
        ".slider",
        ".slider:focus-visible::-webkit-slider-thumb"
      ],
      "a11y": [
        "aria-label on the range; the readout mirrors the value; keyboard steps come from the native input."
      ]
    },
    {
      "class": "cb",
      "name": "Combobox",
      "source": "base.css",
      "status": "stable",
      "states": [
        "closed",
        "open",
        "filtered",
        "selected",
        "multi-chips"
      ],
      "verify": [
        ".cb",
        ".cb.open .cb-list",
        ".cb-opt[aria-selected=\"true\"]",
        ".cb-chips"
      ],
      "a11y": [
        "aria-activedescendant listbox: focus stays in the input; options are filtered in place.",
        "Multi-select mirrors values into a hidden input and announces chips via aria-live."
      ]
    },
    {
      "class": "dp",
      "name": "Date picker",
      "source": "base.css",
      "status": "stable",
      "states": [
        "open",
        "today",
        "selected",
        "out-of-month",
        "disabled-day",
        "roving-focus (one tabbable cell)"
      ],
      "verify": [
        ".dp",
        ".dp.open .dp-pop",
        ".dp-d.sel",
        ".dp-d[aria-current=\"date\"]"
      ],
      "a11y": [
        "ISO value on the input; month/weekday names and full-date day labels via Intl (locale-aware).",
        "Roving tabindex: exactly one day cell is tabbable \u2014 the selected day in view, else today, else the first enabled day.",
        "Arrow keys move \u00b11/\u00b17 days, Home/End to week start/end, PageUp/PageDown change month; disabled days are skipped.",
        "Escape from anywhere inside the popup closes it and returns focus to the input; selecting a day does the same.",
        "min/max disable days; today carries aria-current=date.",
        "Clicking the input reopens the picker after a selection (the input is already focused, so no focus event fires)."
      ]
    },
    {
      "class": "acc",
      "name": "Accordion",
      "source": "base.css",
      "status": "stable",
      "states": [
        "closed",
        "open",
        "focus-visible"
      ],
      "verify": [
        ".acc",
        ".acc-h",
        "details.acc[open]>.acc-h::after"
      ],
      "a11y": [
        "Native details/summary \u2014 keyboard and find-in-page work for free; group with the details name attribute for exclusivity."
      ]
    },
    {
      "class": "avatar-sq",
      "name": "Avatar",
      "source": "base.css",
      "status": "stable",
      "states": [
        "initials",
        "image",
        "ink",
        "group"
      ],
      "verify": [
        ".avatar-sq",
        ".avatar-32",
        ".avatar-group",
        ".avatar-more"
      ],
      "a11y": [
        "Decorative avatars are aria-hidden; meaningful ones need alt/label. Groups carry an aria-label with the count."
      ]
    },
    {
      "class": "img",
      "name": "Image",
      "source": "base.css",
      "status": "stable",
      "states": [
        "16:9",
        "4:3",
        "1:1",
        "contain",
        "caption"
      ],
      "verify": [
        ".img",
        ".img-16x9",
        ".img img",
        ".img-cap"
      ],
      "a11y": [
        "alt is mandatory (TDS014); the frame reserves space so loading never shifts layout."
      ]
    },
    {
      "class": "drop",
      "name": "Upload / dropzone",
      "source": "base.css",
      "status": "stable",
      "states": [
        "idle",
        "dragover",
        "focus-visible",
        "file-list"
      ],
      "verify": [
        ".drop",
        ".drop.over",
        ".up-row",
        ".up-rm"
      ],
      "a11y": [
        "role=button + Enter/Space; announces files with name and size; removal is a labelled button."
      ]
    },
    {
      "class": "notif",
      "name": "Notifications",
      "source": "base.css",
      "status": "stable",
      "states": [
        "unread",
        "read",
        "empty",
        "mark-all"
      ],
      "verify": [
        ".notif-dot",
        ".notif-item.unread",
        ".notif-panel",
        ".notif-foot"
      ],
      "a11y": [
        "The summary's accessible name carries the unread count; unread uses background + a dot, never colour alone."
      ]
    },
    {
      "class": "cmd",
      "name": "Command palette",
      "source": "base.css",
      "status": "stable",
      "states": [
        "closed",
        "open",
        "filtered",
        "active-item",
        "empty"
      ],
      "verify": [
        ".dlg.cmd",
        ".cmd-item[aria-selected=\"true\"]",
        ".cmd-hint",
        ".cmd-empty"
      ],
      "a11y": [
        "Native dialog; Arrow/Enter/Escape inside, cmd/ctrl+K opens; items are buttons with listbox roles.",
        "A click executes the clicked item (both data-href and data-cmd-action paths); Enter executes the highlighted item."
      ]
    },
    {
      "class": "page-state",
      "name": "Full-page state",
      "source": "base.css",
      "status": "stable",
      "states": [
        "404",
        "500",
        "403",
        "offline",
        "maintenance"
      ],
      "verify": [
        ".page-state",
        ".ps-icon",
        ".ps-code",
        ".ps-actions",
        ".ps-meta"
      ],
      "a11y": [
        "One h2 per page state; the code is secondary; actions are the only focusable elements."
      ]
    },
    {
      "class": "pager-num",
      "name": "Numbered pagination",
      "source": "base.css",
      "status": "stable",
      "states": [
        "first",
        "middle",
        "current",
        "gap",
        "disabled"
      ],
      "verify": [
        ".pager-num",
        ".pgn[aria-current=\"page\"]",
        ".pgn-gap",
        ".pager-size"
      ],
      "a11y": [
        "aria-current marks the active page; range labels on prev/next; page-size select is labelled."
      ]
    },
    {
      "class": "tl",
      "name": "Timeline",
      "source": "base.css",
      "status": "stable",
      "states": [
        "default",
        "status-dots"
      ],
      "verify": [
        ".tl",
        ".tl-item",
        ".tl-dot.ok",
        ".tl-dot.err"
      ],
      "a11y": [
        "Ordered list; dots are decorative (the text carries the meaning)."
      ]
    },
    {
      "class": "diff",
      "name": "Diff",
      "source": "base.css",
      "status": "stable",
      "states": [
        "context",
        "added",
        "removed",
        "empty"
      ],
      "verify": [
        ".diff",
        ".diff-row",
        ".diff-add",
        ".diff-del",
        ".diff-empty"
      ],
      "a11y": [
        "role=table with labelled columns; +/- expressed as background tints plus repeated line numbers."
      ]
    },
    {
      "class": "sheet-end",
      "name": "Sheet dialog",
      "source": "base.css",
      "status": "stable",
      "states": [
        "side",
        "bottom"
      ],
      "verify": [
        ".dlg.sheet-end",
        ".dlg.sheet-bottom"
      ],
      "a11y": [
        "Same native-dialog contract as .dlg (top layer, Escape, focus restore); data-dlg-static still blocks backdrop close."
      ]
    }
  ]
}