Button
componentcomponent/btn
Action trigger. Use a real button or link; variants (primary/ghost/danger/small), busy state via guardApply. Never a clickable div.
class .btn
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.
aliases: button, cta, action button, submit button, primary action
/components/buttons
source: spec/states.json @ 2c701d2172
Icon button
componentcomponent/iconbtn
Square icon-only control for compact toolbars and rows; must carry an aria-label.
class .iconbtn
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.
aliases: icon button, icon-only button, kebab menu button, ellipsis button, overflow button
/components/buttons
source: spec/states.json @ 2c701d2172
Switch
componentcomponent/px-sw
The one boolean control for enabling/disabling an entity; auto-submits and announces.
class .px-sw
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.
aliases: toggle, switch, enable disable control, boolean control, on off control
/components/forms
source: spec/states.json @ 2c701d2172
Menu item
componentcomponent/menu-item
Item inside a dropdown menu; sentence case; destructive items carry 'menu-item danger arm-del'.
class .menu-item
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.
aliases: dropdown item, menu entry, menu option, context menu item
/components/navigation
source: spec/states.json @ 2c701d2172
Nav item
componentcomponent/nav-item
Sidebar/navigation link with icon, active rail state and aria-current.
class .nav-item
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).
aliases: navigation link, sidebar link, nav link, menu link
/components/navigation
source: spec/states.json @ 2c701d2172
Chip
componentcomponent/chip
Compact filter/selection token used in filter rows; distinct from badge (not a status).
class .chip
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).
aliases: filter chip, filter pill, facet, filter tag
/components/data
source: spec/states.json @ 2c701d2172
Index row
componentcomponent/index-row
Standard row for list/index pages: primary text, meta, optional actions.
class .index-row
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.
aliases: list row, index item, resource row, result row
/components/data
source: spec/states.json @ 2c701d2172
Table
componentcomponent/tbl
Data table with sticky headers; collapses to card rows (.mcards) on phones.
class .tbl
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.
aliases: table, data grid, data table, list table, grid
/components/data
source: spec/states.json @ 2c701d2172
Bulk bar
componentcomponent/bulkbar
Selection-only toolbar for batch operations; hidden until rows are selected.
class .bulkbar
states: hidden · shown with selection
verify: .bulkbar .bulkbar.on
a11y role=region with aria-label; count is text, not colour.
aliases: bulk actions, selection toolbar, action bar, batch toolbar
/components/data
source: spec/states.json @ 2c701d2172
Save bar
componentcomponent/savebar
Sticky footer for editors: primary Save plus Cancel; validation renders above, focused.
class .savebar
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.
aliases: sticky save, form footer, editor actions, save bar
/components/forms
source: spec/states.json @ 2c701d2172
Flash message
componentcomponent/msg
Banner for server/redirect feedback; exactly ok/warn/err kinds.
class .msg
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.
aliases: banner, alert, flash message, notice, inline alert, callout, error message, success message, server error
/components/feedback
source: spec/states.json @ 2c701d2172
Toast
componentcomponent/toast2
Transient in-place feedback (one at a time) from the shared toast host.
class .toast2
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.
aliases: toast, snackbar, transient notification, popup message
/components/feedback
source: spec/states.json @ 2c701d2172
Badge
componentcomponent/badge
Compact status label (uppercase micro-badge); pair colour with text, never colour alone.
class .badge
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 — pair with text that says the same thing.
aliases: status chip, lozenge, status label, state marker, pill, status badge, status indicator
/components/data
source: spec/states.json @ 2c701d2172
Empty state
componentcomponent/empty
Empty state anatomy: title, one-line reason, at most one primary CTA.
class .empty
states: default
verify: .empty .empty h4
a11y h4 + one-line reason + at most one action; never a bare blank area.
aliases: empty state, nothing to show, zero state, blank state, no results
/components/feedback
source: spec/states.json @ 2c701d2172
Dialog (native)
componentcomponent/dlg
Native dialog element for modals/confirms; static-backdrop variant available; dialog is the confirm primitive.
class .dlg
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 — 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.
aliases: modal, dialog, popup window, modal window, confirm window
/components/overlays
source: spec/states.json @ 2c701d2172
Tooltip
componentcomponent/tip
Tooltip for supplementary hints; hover/focus triggered.
class .tip
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.
aliases: tooltip, hint popup, help bubble
/components/overlays
source: spec/states.json @ 2c701d2172
Spinner
componentcomponent/spinner
Loading indicator for waiting states; pair with text describing what is loading.
class .spinner
states: spinning · reduced-motion (slowed)
verify: .spinner @keyframes tri-spin
a11y Indeterminate progress: keep the action label honest ('Queued…'), and slow to 1s under prefers-reduced-motion.
aliases: loading spinner, loader, activity indicator, loading indicator
/components/feedback
source: spec/states.json @ 2c701d2172
Field error
componentcomponent/field-err
Inline field validation message; form-level summary focuses at top.
class .field-err
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).
aliases: field error, inline validation, form error, error text under field
/components/forms
source: spec/states.json @ 2c701d2172
Tabs
componentcomponent/tabs
In-place view switcher; roving tabindex + arrow keys via components.js.
class .tabs
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.
aliases: tab bar, tabbed views, section switcher, tabs control
/components/navigation
source: spec/states.json @ 2c701d2172
Breadcrumbs
componentcomponent/crumbs
Breadcrumb trail for hierarchical navigation.
class .crumbs
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.
aliases: breadcrumb, breadcrumbs, trail, path indicator
/components/navigation
source: spec/states.json @ 2c701d2172
Radio
componentcomponent/radio
Square single-choice control.
class .radio
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.
aliases: radio button, single choice control, radio group
/components/forms
source: spec/states.json @ 2c701d2172
Slider
componentcomponent/slider
Range control with numeric readout.
class .slider
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.
aliases: range slider, seek control, range input
/components/forms
source: spec/states.json @ 2c701d2172
Combobox
componentcomponent/cb
Combobox: type-to-filter select, optionally multi-select with chips and a mirror input.
class .cb
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.
aliases: combobox, autocomplete, multi-select, tag input, typeahead, picker with search, searchable picker
/components/forms
source: spec/states.json @ 2c701d2172
Date picker
componentcomponent/dp
Date picker: text input plus calendar popover; min/max supported.
class .dp
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 — the selected day in view, else today, else the first enabled day. Arrow keys move ±1/±7 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).
aliases: date picker, datepicker, calendar input, date field
/components/forms
source: spec/states.json @ 2c701d2172
Accordion
componentcomponent/acc
Accordion/disclosure for collapsible sections.
class .acc
states: closed · open · focus-visible
verify: .acc .acc-h details.acc[open]>.acc-h::after
a11y Native details/summary — keyboard and find-in-page work for free; group with the details name attribute for exclusivity.
aliases: accordion, disclosure, collapsible section, expandable section
/components/data
source: spec/states.json @ 2c701d2172
Avatar
componentcomponent/avatar-sq
Square avatar chip for people. (avatar-sq)
class .avatar-sq
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.
aliases: avatar, profile image, user picture, user chip
/components/data
source: spec/states.json @ 2c701d2172
Image
componentcomponent/img
Image presentation with system borders; always alt text.
class .img
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.
aliases: image, media, thumbnail, attachment preview
/components/data
source: spec/states.json @ 2c701d2172
Upload / dropzone
componentcomponent/drop
Dropzone + file input for uploads; dispatches triage:files.
class .drop
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.
aliases: dropzone, upload, file drop, attach files, upload area
/components/forms
source: spec/states.json @ 2c701d2172
Notifications
componentcomponent/notif
Notifications panel with unread dot and mark-all-read.
class .notif
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.
aliases: notifications panel, notification centre, inbox dropdown, alerts menu
/components/feedback
source: spec/states.json @ 2c701d2172
Command palette
componentcomponent/cmd
Command palette dialog (cmd-k style) with input, items and triggers.
class .cmd
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.
aliases: command palette, command menu, quick switcher, command bar, cmdk
/components/overlays
source: spec/states.json @ 2c701d2172
Full-page state
componentcomponent/page-state
Full-page state (e.g. fatal/empty app shell) with message and action.
class .page-state
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.
aliases: full page state, error page, fatal state, whole page message, 404 state
/components/feedback
source: spec/states.json @ 2c701d2172
Numbered pagination
componentcomponent/pager-num
Numbered pagination with page-size control; phone-trimmed.
class .pager-num
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.
aliases: pagination, pager, page numbers, paging control
/components/data
source: spec/states.json @ 2c701d2172
Timeline
componentcomponent/tl
Timeline for histories (e.g. approval steps): ordered entries with markers, time, actor.
class .tl
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).
aliases: timeline, activity trail, history list, event feed, step history, approval history, approval steps, approval trail
/components/data
source: spec/states.json @ 2c701d2172
Diff
componentcomponent/diff
Diff presentation for before/after comparison.
class .diff
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.
aliases: diff view, change comparison, before after view
/components/data
source: spec/states.json @ 2c701d2172
Sheet dialog
componentcomponent/sheet-end
End sheet: slide-over dialog variant for secondary panels.
class .sheet-end
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.
aliases: side sheet, end sheet, slide-over panel, side panel, sliding panel, slide-in panel
/components/overlays
source: spec/states.json @ 2c701d2172
introduced in 0.13.1-experiment (aliases only)
cand/07 ACCEPT
triggered by dispute/20261008-134400-bcea20 (sliding panel mis-route)
Select (native)
componentcomponent/select
Native single-select for small fixed option sets; class .select for explicit citation (identical to the bare element); for the labelled assign flow (action + outcome) compose recipe/assign-picker; component/cb is the large/filtered-set option.
class .select
states: default · focus · invalid · disabled
verify: .select .select:focus .select[aria-invalid="true"]
a11y Native select: platform keyboard and screen-reader semantics; keep the visible <label for> association. 16px on phones (iOS anti-zoom) and the 44px minimum touch target come from the phone blocks in base.css. Never replace a small fixed enumeration with a JS listbox; component/cb is for large or filtered sets.
aliases: select, native select, single select, select control, owner picker, record picker, assign, reviewer
/components/forms
source: spec/states.json @ 2c701d2172
introduced in 0.13.0-experiment
cand/01-select-catalogue REVISE -> applied (03-review required actions 1-4)
triggered by G-01 / gap/20261007-034623-ee7a49 (c1)
triggered by G-01 / gap/20261007-042135-0f2dcf (c2)
triggered by G-01 / gap/20261007-054849-6c928b (c3)
Progress bar
componentcomponent/progress
Determinate progress bar; compose with badge + text readout via recipe/job-progress; indeterminate waits use component/spinner.
class .progress
states: determinate (aria-valuenow) · complete (100%)
verify: .progress .progress i
a11y role=progressbar with aria-valuemin/max/now on the track; aria-valuetext carries the human readout (e.g. '12 of 40 scanned'). Always pair with an adjacent visible text readout — never colour alone. Width transitions use --dur-progress; completion is announced via toast/banner.
aliases: progress bar, progress meter, progress track
/components/data
source: spec/states.json @ 2c701d2172
introduced in 0.13.0-experiment
cand/02-progress-catalogue REVISE -> applied (03-review required actions 1-3)
triggered by G-02 / gap/20261007-034622-19217d (c1)
triggered by G-02 / gap/20261007-054850-e336ee (c3)
triggered by G-02 / gap/20261007-063435-0e1da7 (c4)
Skip link
componentcomponent/skip
Skip link: first in body; hidden until focused, jumps to #main. Keeps keyboard users out of the nav.
class .skip
states: default · focus
verify: .skip .skip:focus
a11y First element in body; hidden until focused; focus moves it into view; jumps to #main.
aliases: skip link, skip to content, skip navigation, jump to content
/components/navigation
source: spec/states.json @ 2c701d2172
introduced in 0.13.1-experiment
cand/06-skip-catalogue REVISE -> applied (03-review required actions 1-5)
triggered by dispute/20261008-134355-5a90bd (skip link -> nav-item false RESOLVED)
triggered by gap/20261008-124813-ac670b (Duty build; .skip uncatalogued)