The architecture is the deliverable. The components are the evidence.
A 6–10 week engineering-architecture engagement: token pipeline, framework adapters, component contract template, AAA-bucket conformance floor, CEM authoring. Signed architecture document under principal-engineer attestation. Anchored on HELiX as the reference implementation.
$75,000–$150,000 Six to ten weeks · T&M with cap
A layered architecture diagram — primitive tokens → semantic tokens → component CSS custom properties → framework adapters (web components / React / Vue / Astro) → consumer apps. Each layer labeled, each interface contract sketched, AAA-bucket criteria threaded through every layer. Reads as "the architecture is the deliverable, not the components."Most 'design systems' are styled components plus a Figma file. That's not an architecture.
Component libraries fail in predictable ways: tokens were chosen for the first brand and never generalized; framework adapters were bolted on after the fact and break SSR; component contracts drift between authors because there’s no template; accessibility was added in retrofit and rots every release; the CEM was never authored, so AI tooling hallucinates props; the next brand requires a 6-month rewrite because the architecture didn’t anticipate it.
None of those failure modes are styling problems. They’re architecture problems — the layered contract that should sit beneath the components was never written down, never signed, never defended. When the team that authored the library leaves, the architecture leaves with them. When a new framework lands (React Server Components, Astro Islands, Vue 3.5), the library doesn’t survive the migration.
The Component Library Architecture engagement is the architecture-first version. Token pipeline authored in W3C DTCG, transformed through Style Dictionary, output as CSS custom properties + JS exports + Tailwind config. Framework adapters designed before any components ship, with SSR + bundle-size + interop tested as architectural invariants. Component contract template authored as the boilerplate every component in the library conforms to. AAA-bucket floor (the 9 + 2) threaded through every layer. CEM authoring as a first-class concern so HELiXiR can serve agent-readable component lookup. The architecture is signed; the reference components are the proof.
The accessibility floor is engineered, not editorialized. AAA is a per-criterion ladder, not a single conformance claim: 9 of the WCAG 2.2 AAA Success Criteria are component-shippable — they ship at the token and component layer (contrast, focus appearance, focus-not-obscured, target size, animation reduction, keyboard contracts) — while the other 19 are application-level or editorial (sign-language interpretation, reading-level rewrites) and never engineer at the token layer. The architecture engineers the 9 component-shippable SCs plus 2 industry-consensus peer standards (forced-colors support, APG-aligned keyboard contracts) into the token graph and the component contract, validated in CI. That produces per-criterion AAA-bucket conformance a procurement counterparty can verify and an accessibility lead can audit — not a blanket “AAA conformant” claim the WCAG specification does not support.
Anchored on HELiX — open-source, in production, readable end-to-end. The same architecture pattern, applied to your specific stack.
What ships
-
Architecture document — signed
The deliverable. A 30-to-60-page architecture document covering token pipeline, framework adapter strategy, component contract template, accessibility floor (WCAG 2.2 AA + the 9 AAA-bucket SCs), CI gates, versioning policy, deprecation policy, and CEM (Custom Elements Manifest) authoring. Signed under principal-engineer attestation through Clarity House LLC.
-
Token pipeline — W3C DTCG → Style Dictionary → CSS custom properties
Three-tier token graph: primitive (color scales, type ramps, spacing) → semantic (focus-ring-color, target-touch-min, danger-text) → component (button-padding-block, dialog-backdrop). Authored in <a href="https://www.designtokens.org/tr/drafts/format/">W3C DTCG format</a>, transformed via Style Dictionary, output as CSS custom properties + JS exports + Tailwind config. Rename plan + migration script when an existing library has token-shape regrets.
-
Framework adapter strategy
Web-component core + framework adapters (React, Vue, Angular, Astro, vanilla HTML) — same as <a href="/helixui">HELiX</a>. The architecture document specifies how adapters wrap the web-component primitives, how events / props / slots forward, how SSR works (Astro / Next), and how framework-specific upgrade paths land without breaking the core.
-
Component contract template
Every component in the library implements the same contract template: ARIA role + APG keyboard pattern + slot definitions + CSS parts + lifecycle events + per-criterion AAA-bucket fixtures. Template is the doc, not the implementation — your engineering team uses it to scaffold the next 50 components consistently after the engagement closes.
-
Reference component implementations
Three to five reference components built end-to-end against the new architecture (typically: button, input, dialog, menu, tabs — chosen by complexity coverage). The components are the proof-of-architecture, not the goal — your team builds the rest of the library following the pattern, not paying BST to build all 50.
-
Storybook + per-component a11y fixtures
Storybook configured with the framework adapters; per-component stories include a11y addon, keyboard-walkthrough scenarios, prefers-reduced-motion emulation, forced-colors emulation, focus-not-obscured occlusion fixtures. The fixtures are CI gates — components ship green or they don't ship.
-
CEM authoring + HELiXiR-ready surface
Custom Elements Manifest (CEM) generated for every component — props, attributes, slots, CSS parts, events, framework adapter mappings. CEM-compliant means the library is consumable by <a href="/helixir">HELiXiR</a> as an agent-readable surface — your engineers using Claude Code / Cursor / Copilot get accurate component lookup, not hallucinated props.
-
AAA-bucket conformance floor (the 9 + 2)
Per-criterion conformance for the 9 component-shippable WCAG 2.2 AAA SCs + 2 peer standards (forced-colors, APG-keyboard), engineered into the architecture from day one. Reference components ship at the AAA-bucket floor; the contract enforces it for every component your team builds after. The full per-criterion breakdown is below.
The AAA-bucket floor — engineered at the token layer, per criterion
-
1.4.6 — Contrast (Enhanced)
Text and images of text hold a contrast ratio of at least 7:1 (4.5:1 for large text). Engineered at the color-token layer: every foreground/background pair in the token graph passes 7:1 by construction, validated by axe-core color-contrast-enhanced + computed-style audit in CI.
-
1.4.9 — Images of Text (No Exception)
Images of text are only used for pure decoration or where a particular presentation is essential. Component contract: no rasterized text labels; icon-only components carry an aria-label or visually-hidden text node. CI audit confirms via DOM snapshot.
-
2.1.3 — Keyboard (No Exception)
All functionality is operable through a keyboard interface, with no specific timing for individual keystrokes. Per-component Playwright walkthrough: every interactive state reachable, no mouse-only timing, no path-based input. Failure blocks the component from shipping.
-
2.3.3 — Animation from Interactions
Motion animation triggered by interaction can be disabled, unless essential. Every transition / animation in the component CSS respects @media (prefers-reduced-motion: reduce). Validated with PRM-emulated Playwright runs in CI.
-
2.4.12 — Focus Not Obscured (Enhanced)
When a UI component receives keyboard focus, no part of the component is hidden by author-created content. WCAG 2.2 addition (added 2023-10-05). Playwright assertion: focus each interactive element under sticky-header / sticky-footer / overlay scenarios; assert no occlusion via getBoundingClientRect + elementFromPoint.
-
2.4.13 — Focus Appearance
Focus indicator has at least a 2 CSS px perimeter and 3:1 contrast ratio between focused and unfocused states. WCAG 2.2 addition. Engineered at the focus-ring-color + focus-ring-width token layer; the token contract is what guarantees the threshold, not per-component overrides.
-
2.5.5 — Target Size (Enhanced)
Pointer-input targets are at least 44×44 CSS pixels (with documented exceptions). We hold to the AAA bar at 44×44 — explicitly NOT the AA-level 2.5.8 (Minimum) at 24×24 added in WCAG 2.2. Engineered at the target-touch-min token; component minimum sizes derive from it, never from per-component magic numbers.
-
3.2.5 — Change on Request
Changes of context are initiated only by user request, or a mechanism is available to turn off such changes. No surprise navigations on focus, no auto-submit on selection change, no time-based re-renders without explicit opt-in. Audited per-component.
-
3.3.6 — Error Prevention (All)
For pages that cause information submission, submissions are reversible, checked for errors, or confirmable. Form components ship with the confirm-before-submit pattern when the action is non-reversible; data-loss-class actions surface a confirmation step before commit.
-
Forced Colors Mode Support (peer standard)
Industry-consensus peer standard (not a WCAG SC). Components remain operable and legible under Windows High Contrast / forced-colors-active. CSS uses system color keywords (CanvasText, ButtonText, Highlight, etc.) inside @media (forced-colors: active) blocks. Validated with forced-colors emulation in Playwright.
-
APG-Aligned Keyboard Contract (peer standard)
Pattern conformance with WAI-ARIA Authoring Practices Guide. Each component implements the keyboard contract documented in APG for its widget pattern (combobox, listbox, dialog, tabs, menu, etc.) — Tab, Arrow, Home / End, Escape, Enter / Space behavior matches the spec. Pattern conformance, not WCAG SC.
How it works
-
Discovery + audit
Week 1Deliverable Architecture audit + decision matrix
Read your existing library (or your existing framework choices, if greenfield), interview design + engineering + accessibility stakeholders, identify the constraints (which frameworks must be supported, which brands must be served, what regulatory exposure exists, what migration window is acceptable). Produce the architecture audit + decision matrix that gates the rest of the engagement.
-
Token pipeline + contract template
Week 2–3Deliverable Token graph, transform pipeline, component contract template
Three-tier token graph authored in W3C DTCG format. Style Dictionary transforms wired. CSS custom properties + JS / TS exports + Tailwind config generated. Component contract template drafted — the boilerplate every component in the library will conform to. AAA-bucket criteria threaded through both layers as enforced contracts.
-
Framework adapter scaffolding
Week 3–5Deliverable Working adapters for the in-scope frameworks
Web-component core scaffolded. Framework adapters built (React + Astro + vanilla HTML for compact tier; add Vue / Angular for standard / complex). SSR strategy implemented and tested. Adapter event / prop / slot forwarding patterns documented. Bundle-size budgets set per adapter. Each adapter ships with one reference component to prove the pattern.
-
Reference components + Storybook + a11y fixtures
Week 4–8Deliverable 3–5 reference components + Storybook + per-component CI fixtures
Reference components built end-to-end: button, text input, dialog, menu, tabs (or a coverage-equivalent set). Each ships with a complete contract — APG keyboard pattern, AAA-bucket conformance, CEM, framework adapters, Storybook story, per-criterion a11y fixtures. The components prove the architecture; your team uses them as the pattern for the rest.
-
Architecture document + signoff
Week 8–10Deliverable Signed architecture document + 60-min walkthrough
Architecture document finalized — 30-to-60 pages, principal-engineer-signed under Clarity House LLC. Walkthrough scheduled with engineering, design, accessibility, and (where present) counsel. Document covers everything: token pipeline, adapters, contract, AAA floor, CI gates, versioning policy, deprecation policy, CEM authoring, HELiXiR-readiness. The document is the deliverable; the components are the evidence.
Pricing
Engagement model Time & materials with not-to-exceed cap
Compact tier ($75K–$95K, 6 weeks): existing library rearchitecture, single brand, single framework adapter, AA + AAA-bucket floor. Standard tier ($95K–$120K, 7–8 weeks): multi-brand token mapping, two framework adapters, Storybook docs, per-component a11y fixtures. Complex tier ($120K–$150K, 8–10 weeks): greenfield architecture with full token pipeline, three+ framework adapters, multi-brand, AAA-bucket conformance matrix, principal-engineer-signed architecture document.
Anchor pricing reflects typical engagement ranges. Actual fees are scoped per engagement under time-and-materials with a not-to-exceed cap. Pricing shown does not constitute a binding offer.
Frequently asked questions
Why not just adopt HELiX directly?
What if my organization is on a framework HELiX doesn't anchor on?
How do I know the architecture will hold up?
How does CEM authoring tie into HELiXiR?
What does 'AAA-bucket floor' mean for buyer-supplied designers?
Do you retrofit AAA-bucket conformance into an existing library, or only design new ones?
Can I use this for a non-accessibility-anchored library?
Will the architecture document hold up under counsel review?
What happens after the engagement ships?
When architecture-grade isn't the right shape on its own
-
Accessibility Governance Retainer
When the library is the strategic asset and the buyer wants quarterly conformance maintenance from day one. The architecture engagement transitions directly into the retainer cadence on closeout.
-
Single Property Accessibility Audit
When a consuming property needs its own scored audit alongside the library rearchitecture — the architecture fixes the source, the property audit confirms the downstream delta.
-
Accessibility cluster overview
When the buyer is comparing across the cluster and architecture-grade is one of several possible shapes for the engagement.
We put your component library on a defensible architecture.
Six to ten weeks. Token pipeline, framework adapters, component contract, AAA-bucket floor, CEM, signed architecture document. Anchored on the HELiX reference implementation.