Skip to content

Component Hardening Protocol

Jump to bottom
Cindy Zhang edited this page Aug 11, 2026 · 8 revisions

Component Hardening Protocol

Hardening takes a shipped component and asks: is this correct, complete, and polished?

Most of this page moved. The checks that used to live here are now Component Audit Rubric — it owns what is checked, how it is verified, how severe a failure is, and how it scores. The scope rules (what counts as a hardening fix versus new capability, when an API change is allowed, and how naming disputes route) moved to Component Lifecycle §When Findings Route Back.

What is still only here is Layer 3: the human design review and its form. That is this page's job now.

The three layers

Layer Executor What it does Where it lives
1. Automated audit the nightly pass Convention checks — tokens, naming, theming, a11y contracts, exports Component Audit Rubric, the auto and semi items
2. Bug & visual fixes agent + human review Visual bugs, state coverage gaps, edge cases, internal consistency Component Audit Rubric §4, §5
3. Design review human, with preparation Proportions, interaction feel, composition quality, visual polish this page

Layers 1 and 2 should not need human attention: automate what is objective, fix what is clearly wrong, and escalate only what genuinely needs an eye.

What hardening is NOT

  • Matching another design system. Astryx is forward-looking; another system's behaviour is research input for the spec loop, not a hardening issue.
  • Adding features. Missing states, new props, new sub-components — those go through the Component Specification Protocol.
  • System-level design changes. Motion, edge compensation, spacing algorithms affect every component and need their own spec. Once settled they become a convention page the rubric cites, which is how the automated layers grow.

Layer 3: Design Review

Visual judgment from a human. Prepare the form, a human fills it out.

Layer 3 is scoped to visual and interaction quality. It does not cover naming, API shape, or whether a prop should exist — those are engineering and spec concerns.

The rubric's §5b grades the same territory from screenshots; this form is how a human records the call and routes what they find. Run it after Layers 1 and 2 are done, with the screenshots §5b already required.

The Hardening Review Form

Visual Quality

Does this look right on its own terms — not compared to any reference, but as a standalone component?

Proportions — sizes, spacing, typography feel balanced?

  • Looks right
  • Adjust: _______________

Interactive states — hover, focus, active, disabled feel visually distinct?

  • States feel right
  • Adjust: _______________ (which state, what feels off)

Density — appropriately compact or spacious for its use case?

  • Good density
  • Too dense / too spacious: _______________

Composition Quality

Does this play well with the rest of the system?

Inside Dialog:

  • Works well / [ ] Issue: _______________ / [ ] N/A

Inside Table:

  • Works well / [ ] Issue: _______________ / [ ] N/A

Inside Card / Layout:

  • Works well / [ ] Issue: _______________

With other components:

  • Composes cleanly / [ ] Issue: _______________

Scope Boundary

Did anything come up that's NOT a hardening fix?

  • No — everything is within hardening scope
  • Yes — filing spec issue(s) for:
  • Naming concern — queue vibe test for:

How the form gets used

  1. Prepare it after Layers 1 and 2 are complete, pre-filling what can be pre-filled: the composition contexts the stories cover, the states that apply, and the §5b screenshots.
  2. A human fills it out — boxes ticked, brief notes where adjustment is needed.
  3. Process the answers: "Adjust" items become Layer 2 fixes; "Naming concern" items go to the vibe-test queue; "Spec issue" items are filed against the Component Specification Protocol.
  4. Archive the form in the hardening issue as the record of what was decided — Component Audit Rubric L9 looks for it there.

Automation targets

The long-term goal is to push Layers 1 and 2 toward full automation. Layer 3 stays human — that is the point.

Check Current Target
Token usage the nightly pass CI check on every PR
themeProps the nightly pass CI check on every PR
Prop/type naming the nightly pass ESLint rule
State coverage manual checklist Storybook interaction tests
Visual regression manual — no VRT suite exists Playwright or Chromatic VRT
A11y contracts axe in the pr-a11y job, static DOM only keyboard and focus behaviour too
Keyboard nav manual + user-event unit tests Playwright keyboard tests
Story play: coverage 104 of 165 top-level story files every interactive component

Clone this wiki locally