design-components

A homogenized, tokenized component library distilled from three existing Invela codebases. The goal: one shared set of primitives (Button, Input, Badge, …) that any surface can pull from, picked deliberately — one component at a time — from the best of what already exists.

Sources being harvested

| Source | Where it lives | Convention | Character | |---|---|---|---| | allspark | ../allspark/components/ui/<Name>/ | cva + Radix Slot, folder-per-component, shadcn-semantic tokens | The origin. Kitchen-sink variants, some stale hardcoded hex. | | warranty-prototype | ../warranty-prototype/components/ui/<Name>/ | same as allspark, refined | Pruned + a11y-hardened descendant of allspark. Token-pure, documented. | | bluebox (EvanCNavarro/blueboxagents) | packages/ui/src/<Name>.tsx + packages/brand | zero-dep hand-rolled, flat files, custom brand-token package | Independent lineage. Self-contained (no Radix/cva), Vite/react-router SPA. |

See SOURCES.md for the full component matrix and per-source design-system breakdown.

Governance Entry Points

This package is the canonical implementation source for Invela UI components. For ai-tools users, start with the installable design-system-governance skill at skills/foundation/design-system-governance/SKILL.md. That skill is a router into this package and prevents app-local or mockup-local component drift.

• Design/mockup work can reference this package through PDLC skills such as pdlc-design and ooda-framework.
• Implementation, Figma ingestion, package versioning, token decisions, Storybook proof, and app adoption use design-system-governance, then this package's .agents/skills/design-system-governance/SKILL.md.
• Figma-sourced component changes must follow FIGMA-INGESTION.md and record exact node evidence in FIGMA-SOURCES.md; screenshots alone are not sufficient.
• Consuming apps should depend on @invela/design-components; do not copy source files or redefine package tokens/components in the app.

The flow (one component at a time)

1. Locate the component across all three sources.
2. Compare — API, variants, tokens, dependencies, a11y — shown side by side (visual + code).
3. Bobby chooses — adopt one wholesale, or pick-and-choose features into a homogenized version.
4. Build the chosen version into this library (components/<Name>/), on the agreed token vocab.
5. Repeat.

Git / push path

This package now lives in Invela/ai-tools at .brain/references/design-components. The earlier Invela/hackathon-team-2/design-components copy was the incubation location; do not treat it as the package authority after this migration lands.

• Now: active source work should branch from Invela/ai-tools/main and modify this directory.
• On Bobby's go-ahead only: commit → push → PR to Invela/ai-tools. The push is the single gated act; everything before is local.
• Release flow: publish/version from this package directory only after the package workflow, release guard, changelog/version checks, npm auth, and explicit release approval are complete.

Consumer Adoption Contract

Use .agents/skills/design-system-governance/SKILL.md before changing this package for a consumer app or before changing a consumer app to ingest this package. The Claude entrypoint .claude/skills/design-system-governance/SKILL.md is only a shim back to the same canonical skill.

There are two valid ingestion modes:

• React consumers import components and token CSS from @invela/design-components.
• Static HTML/CSS consumers load the package-owned tokens/static-consumer.css projection and may use the package-owned .ui-* primitive classes. IRI is currently in this category; it is design-system-backed, but it is not literally rendering React Button/Input implementations.

For a package version update, the package package.json remains the version authority. Change the package, bump the version, run release gates, publish the new npm version, update each consumer's dependency/lockfile, regenerate any vendored static projection, and rerun static plus browser runtime proof. Do not simulate a design-system update with app-local visual CSS.

Status

Bootstrapped 2026-07-20. → For the live state and the single pick-up point, read HANDOFF.md.

As of 2026-08-05: 67 components + a shared XIcon built on the one token authority. Phases 0–6 (tokens · form/control primitives · badge/status/text · containers/overlays · data display · charts/flows · app-shell/infra) complete, including the #46 final library sweep. Dropdown, Menu, Pagination, FilterChips, TableFilterToolbar, ExportMenu, DataTable hardening, Stat, BandTable, SubTabs, ListItem, ChipInput, Slider, BarRows, Legend, StackedBar, TrendChart, StatusFlow, Trace, ProgressBar, Stepper, FactorSlider, Nav, Avatar, ErrorBoundary, RouteAnnouncer, SkipLink, NavigationProgress, ReconnectingBadge, and VersionChecker are browser-proven. The DS governance skill is now packaged for Codex/Claude and dogfood-validated against the current component surface, with a loop-state component audit for public barrels, helper tests, selected DOM/type coverage, and fixture/browser pairings plus an active-beat STOKE-plan guard. The package component build is complete. Storybook foundation is now present as a browsable design-documentation/workshop surface, with 60/60 public story directories covered: Button, #48 wave-1 text/status atoms, #48 wave-2a field-shell atoms, #48 wave-2b composed form controls, #48 wave-2c stateful controls, #48 wave-2d filter/control composites, #48 wave-2e data surfaces, and #48 wave-2f Menu/container/status surfaces, #48 wave-2g overlay surfaces, #48 wave-2h data-viz chart surfaces, and #48 wave-2i ordered-flow surfaces, #48 wave-2j app-shell/a11y surfaces, and #48 wave-2k async app-state surfaces, #48 wave-2l data-tail surfaces, and #48 final icons/XIcon shared-asset coverage. Root docs parity, primitive inventory governance, and single-authority token projection hardening are complete through DESIGN.md, PRIMITIVES.md, DESIGN-GOVERNANCE.md, AGENTS.md, and CLAUDE.md.

Current package state as of 2026-08-14: this source now lives in Invela/ai-tools/.brain/references/design-components as the canonical package authority. The npm package @invela/[email protected] is the current public registry baseline; this source tree is the 0.0.3 candidate and @invela/[email protected] is intentionally not visible on npm until the ai-tools PR lands and the explicit publish step completes. The next consumer proof target is Bluebox Storybook after 0.0.3 is published and visible. IRI/admin-portal release-retarget evidence remains historical/future-state and must not be claimed as 0.0.3 until its package manifest, lockfile, vendored static CSS, and browser proof are refreshed after the publish. Earlier AllSpark slices remain historical consumer-proof evidence, not the current app adoption target.

The remaining refinement arc is now tracked: #54 created GOVERNANCE-REFERENCE-MATRIX.md, #55 created TOKENIZATION-DECISIONS.md, and scripts/ds_reference_matrix_check.py, scripts/ds_tokenization_decisions_check.py, and scripts/ds_refinement_arc_check.py keep that sequence wired into loop-state before more token or app work. Completed pitstops are red-first TDD'd, strict-noUncheckedIndexedAccess-clean, and code-reviewed (superpowers) with all findings fixed.

• tokens/ — the one colour/radius value authority (tokens.ts), metadata and CSS projection naming helpers, the checked Tailwind tokens.css projection, plus source-backed package utilities such as Radix enter/exit, badgeIn animation, and the Button primary shadow effect.
• lib/ — category, cx (zero-dep class-join), dataViz, composeRefs, copyText, focusRing, number, tone, reactNode, rovingIndex, selection, a11y.
• components/ — 67 public components; complex/reusable styling, a11y, and normalization logic lives in pure helpers.ts files, with internal Overlay/CloseButton helpers + icons/ shared inline-SVG assets.
• index.ts — the public barrel (whole-library strict typecheck: 0 errors).

Planning/record docs: DESIGN.md (root design entrypoint), PRIMITIVES.md (primitive inventory and tokenization gap table), TOKENIZATION-HARDENING.md (#66 package-local tokenization hardening plan), STORYBOOK-COMPUTED-STYLE-INVENTORY.md (#67 rendered Storybook computed-style evidence), FIGMA-INGESTION.md (Figma MCP extraction steps, effects/icon proof, and Storybook computed proof requirements for Figma-derived component work), FIGMA-SOURCES.md (exact component Figma source ledgers), PUBLISHED-SURFACE.md (published docs/site and crawler-file decision map), CONSUMER-PROOF-SELECTION.md (current consumer-proof candidate choice and reusable/app-owned split), CONSUMER-PROOF-PATHWAYS.md (brownfield, greenfield, and webapp-gauge/testground consumer-proof graph), CONSUMER-APP-AUDIT-QUEUE.md (current consumer-app audit protocol and AI-Assessor/IRI evidence queue), RELEASE-POLICY.md (package versioning, semver, changelog, and change-marker rules), RELEASE-PROVENANCE.md (public npm, no provenance claim for the current lane, future provenance, and publish metadata rules), AGENTS.md / CLAUDE.md (agent entrypoints), BUILD-SEQUENCE.md (phased plan + progress), DESIGN-GOVERNANCE.md (DS authorities and page-adherence rules), SELECTIONS.md (per-component Bobby-approved picks), AUDIT-BUILD-PLAN.md (ingest-app gap audit), DEFERRALS.md (no open package deferrals; resolved DEF-1/2/3/5 kept as history), SOURCES.md (source matrix). Refinement docs: GOVERNANCE-REFERENCE-MATRIX.md now holds the source-linked reference corpus, and TOKENIZATION-DECISIONS.md holds the #55 token/Tailwind/app/future decision matrix. The #55/#56/#57 no-runtime batch is historical; the later Button Figma revision figma-2111-1901 is the current source-backed runtime token revision for primary action color. #58 completed the first /runs consuming-app surface slice and DB-backed browser proof. #59 DTCG projection is complete and adds createDtcgTokenProjection plus scripts/ds_dtcg_projection_check.py; it remains generated or validated from tokens/tokens.ts, not a second token authority or a committed static catalogue. #60 published docs and AI crawler surface planning is complete. PUBLISHED-SURFACE.md records that no package-owned published web root exists today, so root crawler files remain future-state until a later site beat proves a real docs/site origin. #61 refinement arc closeout is complete and guarded by scripts/ds_refinement_closeout_check.py; #62 consumer proof candidate selection is complete and guarded by scripts/ds_consumer_proof_selection_check.py. Historical consumer proof selected AllSpark /journeys as an app-agnostic evidence surface, and #63 completed that brownfield implementation pitstop before the current IRI/npm retarget lane. #64 completed greenfield starter ingestion with examples/greenfield-starter, tokens/tokens.css, and React/ReactDOM peer dedupe; #65 webapp-gauge testground adapter synthetic battle testing is complete and follows that starter contract. #66 TOKENIZATION-HARDENING.md is complete and guarded by scripts/ds_tokenization_hardening_check.py; #67 STORYBOOK-COMPUTED-STYLE-INVENTORY.md is complete and guarded by scripts/ds_storybook_computed_style_inventory_check.py; it samples rendered Storybook evidence before any new runtime token values. #68 candidate promotion is complete and guarded by scripts/ds_token_candidate_promotion_check.py; it authorizes no runtime token values. #69 disabled/inert visual-state authority cleanup is complete and guarded by scripts/ds_inert_state_authority_check.py; lib/inertState.ts owns the shared helper classes without moving token values. #70 package release-readiness is complete and guarded by scripts/ds_package_release_readiness_check.py; build:package, native Node ESM import proof, strict NodeNext declaration proof, React/Radix/Tailwind peer coverage, Tailwind v4 source coverage, npm pack, designSystemMarkerAttributes, and tests/browser/package-consumption-visual.test.ts prove a built package consumer can import the root barrel, token CSS, and design-system identity marker without a source alias. #71 release policy governance is complete and guarded by scripts/ds_release_policy_check.py; RELEASE-POLICY.md records that package.json is the version authority, CHANGELOG.md is the ledger for the next version bump, and designSystemMarkerAttributes exposes a checked runtime marker rather than a second version source. The current Figma-derived Button revision updates the package primary action token to #395eef, records exact source evidence in FIGMA-SOURCES.md, and proves the icon/effects stack through Storybook and CSS checks. #72 release provenance governance is complete and guarded by scripts/ds_release_provenance_check.py; RELEASE-PROVENANCE.md records the current public npm lane with no provenance claim, the future provenance lane, the monorepo design-components-release.yml verification workflow, and package metadata requirements without becoming a token or version authority. #73 consumer-app audit queue governance is complete and guarded by scripts/ds_consumer_app_audit_queue_check.py; CONSUMER-APP-AUDIT-QUEUE.md records the parallel read-only discovery, sequential verification, and current AI-Assessor-POV / iri-insurance-admin-portal evidence queue before any broad migration. #74 iri-insurance-admin-portal run-readiness is complete: IRI now has an app-local requirements manifest, readiness checker, and manifest-driven run script, and / simulator browser proof fixed standards mode, favicon, form labels, and mobile containment before the next route migration. #75 iri-insurance-admin-portal shared adapter/mobile-overflow is complete: the remaining measured mobile routes pass the app-local overflow checker and /qexport uses shared appheader.js. #76 iri-insurance-admin-portal first brownfield design-system page migration is complete for /qexport: the IRI static adapter now projects design-components tokens under checked --invela-ds-* variables, the shared header emits the runtime package/version/change marker plus active nav aria-current="page", and /qexport consumes shared .ui-* primitives. #76 also proves qexport data-backed rows/chips and all 13 shared-nav routes at 390px. #77 iri-insurance-admin-portal second brownfield design-system page migration is complete for /secondbrain: shared route proof now covers the graph page, .ui-* primitive adoption, Capital One graph rendering, linked-entity action, clean console/page errors, active nav aria-current="page", and no document overflow. #78 iri-insurance-admin-portal third brownfield design-system page migration is complete for /sampledata: shared route proof now covers .ui-* primitive adoption, /api/sampledata load, filter rows, keyboard row-open controls, ARIA dialog/focus restoration, stubbed non-persistent Generate/Score/Delete request wiring, zero legacy page chrome, clean console/page errors, active nav aria-current="page", and no document overflow. #79 iri-insurance-admin-portal fourth brownfield design-system page migration is complete for /settings: shared route proof now covers .ui-* primitive adoption, /api/settings, /data/model_priors.json, /api/iri/v1/config, and /api/engine/mode load, settings/model/prior/control rendering, safe external links, zero legacy page chrome, clean console/page errors, active nav aria-current="page", and no document overflow. #80 iri-insurance-admin-portal static consumer CSS authority unification is complete: the package owns tokens/static-consumer.css, IRI vendors the exact artifact, appui.css imports it and keeps only legacy aliases, and the adapter checker rejects vendored drift plus local canonical token or .ui-* redefinition. #81 iri-insurance-admin-portal fifth brownfield design-system page migration is complete for /customers: the package owns .ui-switch in tokens/static-consumer.css, IRI vendors the exact updated artifact, and Customers uses .ui-card, .ui-btn, .ui-input, .ui-table, .ui-chip, .ui-modal, and .ui-switch with desktop/mobile browser proof for customers/stats/sectors, accessible search, ARIA modal focus, zero legacy page chrome, zero customer mutating requests, and no document overflow. #82 iri-insurance-admin-portal sixth brownfield design-system page migration is complete for /validator: Validator uses .ui-card, .ui-btn, .ui-table, .ui-chip, .ui-tile, and .ui-banner with desktop/mobile browser proof for sims/methodology read-only GET endpoints, API-derived renderer escaping/ formatting, safe PDF link handling, zero legacy page chrome, zero passive validator/PDF/methodology mutation requests, and no document overflow. #83 iri-insurance-admin-portal seventh brownfield design-system page migration is complete for /scavenger: Scavenger uses .ui-card, .ui-btn, .ui-input, .ui-table, .ui-chip, .ui-tile, .ui-banner, and .ui-switch with desktop/mobile browser proof for datasets/coverage/config/staged read-only GET endpoints, safe external links, quote-safe renderer formatting, finite staged bitmask rendering, package-owned labeled switch sizing, zero legacy page chrome, zero passive Scavenger mutation requests, and no document overflow. #84 iri-insurance-admin-portal eighth brownfield design-system page migration is complete for /analysis: Analysis uses .ui-card, .ui-btn, .ui-input, .ui-table, .ui-chip, .ui-tile, and .ui-banner with desktop/mobile browser proof for /data/questions_mappings.json, MOE rows, lens rows, Q-export tab preview rows, safe links, quote-safe renderer formatting, finite numeric display, zero legacy page chrome, zero passive analysis/deck/whitepaper/export mutation requests, and no document overflow. #85 iri-insurance-admin-portal ninth brownfield design-system page migration is complete for /training: Training uses .ui-card, .ui-btn, .ui-input, .ui-table, .ui-chip, .ui-tile, .ui-banner, .ui-combo, .ui-modal, .ui-status-dot, .ui-tone, .ui-segmented, .ui-bar, .ui-table-scroll, and .ui-modal-close; reusable static gaps were promoted into package-owned tokens/static-consumer.css; desktop/mobile proof covers training config/MCP/models/book read-only responses, zero inline handlers, zero legacy page chrome, zero passive training/predict/remote-config mutation requests, and no document overflow. #86 iri-insurance-admin-portal tenth brownfield design-system page migration is complete for /compare: Compare uses .ui-card, .ui-btn, .ui-input, .ui-chip, .ui-banner, .ui-caption, .ui-help, .ui-on-tone-help, .ui-field-label, .ui-section-label, .ui-segmented, and .ui-combo; reusable caption/help/label text roles were promoted into package-owned tokens/static-consumer.css, matching training label/result/error and .small/.cap alias drift was collapsed into package-owned text primitives, and IRI vendors the exact updated artifact. Desktop/mobile proof covers app/GitHub/entity source responses, compare/book response paths, memory-only PAT handling with POST-body repo-list tokens and GET token-query rejection, combobox/listbox/option semantics, clicked-and-restored segmented aria-pressed, zero unlabeled controls, zero legacy page chrome, zero unsafe blank links, zero passive repo-analysis mutation requests, and no document overflow. #87 iri-insurance-admin-portal eleventh brownfield design-system page migration is complete for /mapping: Mapping uses .ui-card, .ui-btn, .ui-input, .ui-table, .ui-table-scroll, .ui-chip, .ui-caption, .ui-help, .ui-label, .ui-banner, .ui-segmented, .ui-bar, .ui-modal, and .ui-modal-close; reusable info/accent chip tones and .ui-sr-only hidden-label support were promoted into package-owned tokens/static-consumer.css, and IRI vendors the exact updated artifact. Desktop/mobile proof covers passive Mapping GET response paths, tab/modal a11y, zero unlabeled controls, zero nameless controls, zero unassociated labels, zero legacy page chrome, zero unsafe blank links, zero passive mapping/scavenger/connector mutation requests, and no document overflow. #88 iri-insurance-admin-portal twelfth brownfield design-system page migration is complete for scoped /individual simulator ingress: #orgcard and #pxcard use .ui-card, selected org/premium controls use .ui-btn and .ui-input, and simulator-specific CSS remains route-local layout glue. Desktop/mobile proof covers /individual, active nav aria-current, package marker #88, /api/engine/mode and /data/book.json response paths, zero selected card/control ID inline styles, zero scoped legacy card/button/input classes, zero passive classify/loss/save/lookup mutations, and no document overflow. #89 dependency-backed consumer hardening is complete: IRI declares and locks @invela/design-components, generates the served static CSS and manifest from the installed package export, and checks package name/version/hash drift before runtime proof. #143 active-routed premium calculator chrome residual closure is complete. Do now: #144 iri-insurance-admin-portal active-routed ladder chrome residual closure pitstop. #90 proved page-local .ui-* presentation overrides and dynamic companion restyling cannot pass the adapter checker unless promoted to package-owned static variants or kept as layout-only glue. #91 selected /backtest and migrated its static/shell simulator cards, KPI tiles, buttons, and table wrappers onto package-owned static primitives. #92 selected the generated Back-Test book renderer, promoted package-owned .ui-table .ui-num, synced IRI to marker #93 and cssSha256 3b78a81207e13ebbdb1457ea7a525a5843f574e69e080161472937ce21d69403, and moved row/chip/status/numeric cells onto .ui-chip, .ui-tone, .ui-num, .ui-table, .ui-table-scroll, and .ui-table-action without focusable/clickable table-row semantics. #93 selected the Back-Test entity-detail modal and moved dialog/anatomy/table/chip/tone rendering onto package .ui-modal-*, .ui-card, .ui-banner, .ui-table, .ui-table-scroll, .ui-chip, and .ui-tone primitives with keyboard/focus proof and zero local .em* modal chrome. #94 selected simulator static controls and moved RIAT, assurance, entity-class, generated indicator-tab, and generated book-tab controls through package .ui-segmented/.ui-btn compact with aria-pressed state, synced marker #94, and cssSha256 fc386de0bd47e31dc6110d75cf8fe9bd3f3e50e9a233f9b88ba9ee1bae7ebf66. #95 selected scalar simulator data-viz and moved selected pillar bars through package .ui-bar, .ui-bar-fill, .ui-bar-tick, and .ui-tone.brand, synced marker #95, and cssSha256 5417508c7ce6d9dae82f8305a9926f908646818e1425700540fe482a48ff2093. #96 selected stacked split data-viz, promoted package .ui-stack and .ui-stack-segment, synced marker #96, and cssSha256 201a9fabe8da91059f9feec2eda0c369d84c036e8c0ff39c43322e8baba97630, removing local .split visual authority while keeping dynamic percentages app-owned. #97 selected generated Back-Test narrative tone/help rendering, reused package .ui-tone and .ui-help, added safe source-link handling, and refreshed desktop/mobile plus all-route mobile evidence under marker/hash #97 / 201a9fabe8da91059f9feec2eda0c369d84c036e8c0ff39c43322e8baba97630. #98 completed the whole-app static frontend source residual inventory through docs/app-audit/evidence/iri-design-system-residuals-98/results.json; 913 residuals remained, including 608 high-severity items. #99 moved shared app-shell chrome to package-owned .ui-app-shell static-consumer primitives, refreshed route/mobile evidence under marker/hash #99 / f3ec7a9f7067930f8fa26ebabcc5187e4c42068cbc37d9bbac89cc93ce5b546c, and docs/app-audit/evidence/iri-design-system-residuals-99/results.json recorded the corrected bare-selector ledger: 961 residuals, including 652 high-severity items, with zero appheader residuals. #100 then closed the exact small/cap helper family through package .ui-caption, .ui-help, .ui-help.ds-mono, .ui-tone, and .ui-chip; docs/app-audit/evidence/iri-design-system-residuals-100/results.json now records 779 residuals, including 480 high-severity items, with zero exact small/cap residuals. #101 is the simulator visual-status/color-routing closure slice: local sim-*-text, sim-dot-*, and engbadge status classes were removed, simulator .style.color mutations were eliminated, and selected simulator status outputs now route through package .ui-tone, .ui-chip, and .ui-help. The current docs/app-audit/evidence/iri-design-system-residuals-101/results.json ledger records 672 residuals, including 432 high-severity items, with zero local simulator status/color classes. #102 then closed simulator legacy-token alias usage through existing package static-consumer variables without changing the package artifact; docs/app-audit/evidence/iri-design-system-residuals-102/results.json records 556 residuals, including 431 high-severity items, with zero simulator legacy-token residuals. #103 then removed dead simulator .themebtn/.btn local visual rules because actual controls already use package .ui-btn variants; docs/app-audit/evidence/iri-design-system-residuals-103/results.json records 551 residuals, including 426 high-severity items, with zero simulator legacy-token residuals and zero dead simulator local button/theme button residuals. #104 then closed simulator checkbox/switch residuals through existing package .ui-switch anatomy. #105 closed simulator numeric-alignment residuals through package .ui-num, #106 closed exact ui-tile metric generic-class drift through the namespaced package .ui-tile-metric modifier, and #107 closed simulator hint/help text through package .ui-help/.ui-caption. #108 closed simulator hidden/display state through semantic hidden plus package-owned [hidden] static-consumer enforcement, and #109 closed simulator inline separator/layout residuals through package-owned .ui-divider and .ui-flow-xs, #110 classified the remaining simulator local CSS residual authority, #111 closed simulator mini-switch duplicate residuals through package-owned .ui-switch.compact, #112 closed simulator importance-chip tones through package .ui-chip tone variants, #113 closed selected simulator KPI tiles through package .ui-tile.ui-tile-metric, .v.mono, and .ui-help, and #114 closed selected simulator utility chrome through package .ui-label, .ui-field-label, .ui-banner, .ui-divider, and .ui-help. #115 classified the index.html residual source into nine exact families. #116 then proved index.html is not a live route. #117 recalibrated the current 465 residuals into 321 active-routed, 0 shared-runtime, 50 generated/deferred, 94 unrouted-artifact, and 0 unknown residuals, then #118 closed active-routed document base typography/link ownership, #119 closed active-routed direct display-state ownership, #120 closed active-routed compact tile typography ownership, #121 closed active-routed marker/color ownership, #122 closed selected active-routed inline layout ownership, #123 closed selected active-routed dynamic style mutation ownership, #124 closed selected split/layout ownership, #125 closed selected visual-wrapper ownership, #126 closed selected tone/text ownership, #127 closed selected heading/action chrome ownership, #128 closed selected sortable/tab chrome ownership, #129 closed selected loading/print chrome ownership, #130 closed selected detail/claim chrome ownership, #131 closed selected Compare algorithm chrome ownership, #132 closed selected Compare source-card chrome ownership, #133 closed selected Compare numeric/banner chrome ownership, and #134 closed selected Q-Export/Analysis criteria chrome ownership through package-backed static primitives. This is static HTML consumption of package static-consumer.css, not a React component import migration. The current docs/app-audit/evidence/iri-design-system-residuals-134/results.json ledger records 317 residuals, including 233 high-severity items, 34 medium-severity items, and 50 deferred-fragment items, with zero simulator legacy checkbox/switch residuals, zero simulator inline right-align residuals, zero exact ui-tile metric residuals, zero simulator legacy hint residuals, zero simulator hidden/display residuals, and zero simulator inline separator residuals, zero simulator mini-switch residuals, zero simulator importance-chip residuals, zero selected simulator KPI tile residuals, zero selected simulator utility chrome residuals, and zero active-routed document-base residuals, zero active-routed direct display-state target residuals, zero selected compact tile typography residuals, zero selected marker/color residuals, zero selected active-routed inline layout residuals, zero selected dynamic style mutation residuals, zero selected split/layout residuals, zero selected visual-wrapper residuals, zero selected tone/text residuals, zero selected heading/action chrome residuals, zero selected sortable/tab chrome residuals, and zero selected loading/print chrome residuals, zero selected detail/claim chrome residuals, zero selected Compare algorithm chrome residuals, zero selected Compare source-card chrome residuals, zero selected Compare numeric/banner chrome residuals, and zero selected Q-Export/Analysis criteria chrome residuals. Zero selected Customers table/control chrome residuals are closed in #135, zero selected simulator detail-weight chrome residuals are closed in #136, zero selected Second Brain edge-label chrome residuals are closed in #137, zero selected compact eyebrow/app-shell print chrome residuals are closed in #138, and zero selected footer/fsl residuals are closed in #139, zero selected gauge residuals are closed in #140, zero selected graph node residuals are closed in #141, zero selected identity-detail residuals are closed in #142, and zero selected premium-calculator residuals are closed in #143. #144 is the next active-routed ladder chrome residual closure pitstop. This remains a progressive brownfield migration until the residual ledger reaches zero or explicitly app-owned future-state entries only. Agent skill entrypoints: .agents/skills/design-system-governance/SKILL.md for Codex and .claude/skills/design-system-governance/SKILL.md as the Claude shim.

Package Consumption

Build package output before packing or publishing:

npm run build:package

Consumers import components from the root package and load token CSS once:

import { Button, designSystemMarkerAttributes } from '@invela/design-components';
import '@invela/design-components/tokens/tokens.css';

export function AppShell() {
  return <main {...designSystemMarkerAttributes({ changeRef: '#70' })}><Button>Continue</Button></main>;
}

Tailwind v4 consumers that render built package components must scan the installed package output, for example with @source '../node_modules/@invela/design-components/dist/**/*.{js,jsx}' from the app CSS file. React, ReactDOM, Radix primitives, and Tailwind v4 are explicit peer dependencies. package.json is the version authority; designSystemMarkerAttributes exposes a checked design-system identity/version/change marker for rendered proof surfaces, and npm run test:package verifies the built dist/index.js can be imported by native Node ESM, the packed declarations typecheck in a strict NodeNext consumer, and source/declaration maps are not packed without source files. RELEASE-POLICY.md defines the semver decision rules, the pre-publish checklist, and the change-marker contract. Use data-invela-design-system-change for traceability to a task, PR, or release candidate; use package.json for the actual version. RELEASE-PROVENANCE.md defines the release path. The current lane is public npm from .brain/references/design-components in Invela/ai-tools with no provenance claim; after explicit approval the publish command is npm publish --access public from this package directory. design-components-release.yml is verification-only for this lane. Future trusted publishing/provenance must be added as a separate proven lane before any workflow publishes with provenance.

Storybook foundation exists at .storybook/, with package scripts and the first colocated components/Button/Button.stories.tsx / Button.examples.tsx pair. #48 wave 1 adds Storybook coverage for Abbr, Badge, StatusIndicator, StatusPill, Eyebrow, KeyValue, Link, Code, and CodeBlock, with shared examples only where they remove matrix duplication. #48 wave 2a adds FieldLabel, Input, Textarea, InputGroup, and FormField stories/examples, with smoke assertions for semantic label/control wiring and FormField helper/error wiring. #48 wave 2b adds NumberField, ViewablePassword, Combobox, Dropdown, and ChipInput stories/examples, with smoke assertions for numeric formatting/raw editing, reveal toggles, listbox behavior, dropdown single/multi/disabled states, and chip validation/removal/read-only states. #48 wave 2c adds Switch, SegmentedControl, and Slider stories/examples, with smoke assertions for switch click/keyboard/disabled behavior, radiogroup roving selection, Radix slider keyboard/disabled/hidden-output behavior, and token-painted state surfaces. #48 wave 2d adds Pagination, FilterChips, and FactorSlider stories/examples, with smoke assertions for paging changes, filter-chip single/multi selection, and FactorSlider slider/number-input synchronization. #48 wave 2e adds TableFilterToolbar, ExportMenu, and DataTable stories/examples, with smoke assertions for toolbar filtering/reset/live-status behavior, grouped export menus, sortable/paged tables, row actions, safe links, loading/error/empty/read-only states, sticky columns, and responsive cards. #48 wave 2f adds Menu, Card, Callout, Banner, EmptyState, and Loading stories/examples, with smoke assertions for Menu portal semantics, Card variant/clickable behavior, Callout/Banner/EmptyState/Loading a11y semantics, token-painted surfaces, and responsive containment. #48 wave 2g adds Dialog, Drawer, Toast, and Tooltip stories/examples, with smoke assertions for overlay portal geometry, Dialog/Drawer described and undescribed states, Toast live-region/action/dismiss behavior, Tooltip label/card/hidden/suppressed behavior, and overlay body containment. #48 wave 2h adds BarRows, Legend, StackedBar, and TrendChart stories/examples, with smoke assertions for data-viz group/list/table semantics, tone/category token paint, zero/invalid normalization states, Legend composition, hidden accessible chart tables, empty/error states, and responsive containment. #48 wave 2i adds ProgressBar, StatusFlow, Trace, and Stepper stories/examples, with smoke assertions for progress a11y/bounds/hidden chrome, ordered process semantics, Trace derivation semantics, safe-link fail-closed behavior, empty/error states, Stepper delegation to StatusFlow, token-painted surfaces, and responsive containment. #48 wave 2j adds Avatar, Nav, ErrorBoundary, RouteAnnouncer, and SkipLink stories/examples, with smoke assertions for identity fallback/image/tint states, Nav safe-link/current/action states, ErrorBoundary fallback/recovery states, RouteAnnouncer hidden-live-region behavior, SkipLink unsafe-target suppression and focus reveal, token-painted surfaces, and responsive containment. #48 wave 2k adds NavigationProgress, ReconnectingBadge, and VersionChecker stories/examples, with smoke assertions for fixed progress placement, active/idle progressbar semantics, click-through reconnecting chrome, offline actions, delayed reconnecting display, update/current/error version states, guarded reload callbacks, token-painted fixed badge surfaces, and responsive containment. #48 wave 2l adds Stat, BandTable, SubTabs, and ListItem stories/examples, with smoke assertions for Stat filter/tone semantics, BandTable current-row responsive-card parity, SubTabs tablist keyboard/scroll behavior, ListItem safe-link/disabled/active/trailing-control states, token-painted surfaces, and responsive containment. #48 final icon coverage adds icons/XIcon, with smoke assertions for intrinsic SVG sizing, stable viewBox, currentColor stroke, default decorative semantics, accessible SVG override, token-painted text states, and responsive containment. scripts/ds_storybook_audit.py --foundation --catalog is wired into loop-state, and npm run test:storybook builds the static Storybook and proves the covered story iframes over HTTP at desktop and mobile widths.

Loading Cluster API

• LoadingSpinner renders the token-coloured Invela spinner with size="xs" | "sm" | "md" | "lg", tone="primary" | "current", announced by default through label, and opt-out via decorative.
• Skeleton renders one shape-matching placeholder line/block; className replaces the default shape classes, and decorative opts out inside already-announced loading regions.
• SkeletonList renders a normalized stack/grid of decorative child skeletons while the list container owns the single loading announcement; extreme counts are capped and skeletonClassName replaces child skeleton shape classes.
• Loading composes EmptyState busy for compact loading messages, preserving EmptyState's live-region semantics.

Test / typecheck

# requires Node >=22.13.0

# first checkout only
npm install

# full package-owned verification: strict tsc, pure node:test suite, DOM/jsdom suite,
# loop-state governance, Storybook static build + HTTP smoke, Tailwind build, browser fixture smoke
npm run verify

# focused checks
npm run typecheck
npm run test:node
npm run test:dom
npm run test:css
npm run test:package
npm run build:fixtures
npm run build:css
npm run install:browser # one-time setup only if Chromium is missing
npm run test:browser
npm run test:storybook
npm run storybook
npm run build:storybook
python3 scripts/ds_storybook_audit.py --self-test --foundation --catalog
python3 scripts/ds_primitive_inventory_check.py --self-test
python3 scripts/ds_refinement_arc_check.py --self-test
python3 scripts/ds_reference_matrix_check.py --self-test
python3 scripts/ds_tokenization_decisions_check.py --self-test
python3 scripts/ds_dtcg_projection_check.py --self-test
python3 scripts/ds_published_surface_check.py --self-test
python3 scripts/ds_refinement_closeout_check.py --self-test
python3 scripts/ds_consumer_proof_selection_check.py --self-test
python3 scripts/ds_consumer_proof_pathways_check.py --self-test
python3 scripts/ds_package_release_readiness_check.py --self-test
python3 scripts/ds_figma_ingestion_check.py --self-test