-
Notifications
You must be signed in to change notification settings - Fork 1.1k
Hardening Audit Guide
How a designer reviews a component by eye and turns what they find into issues someone can act on.
This page owns the designer's workflow and the issue format. It does not own the criteria — what "correct" means is Design Conventions, and how a finding is graded and scored is Component Audit Rubric.
The March 2026 pre-release sweep this page was written for is over. The workflow below is still the one to use for a design-quality pass on a component; the tracker document and target date it originally carried are gone.
Before you start your audit, paste this to your Navi:
Read the hardening audit guide and follow it when I ask you to file issues: https://github.com/facebook/astryx/wiki/Hardening-Audit-Guide
- Open the component in Storybook and walk every state it ships — rest, hover, focus, pressed, disabled, loading, each status, selected, empty, and long text — in both light and dark.
- Judge what you see against Design Conventions, especially §Consistent State Representations: a state should use one of the approved representations, not a new invention.
- File an issue for anything that looks wrong, with a screenshot.
Attach the screenshots. A visual finding without the image it came from is not reviewable, and the same screenshots are what Component Audit Rubric §5b needs to be gradeable at all.
Time estimate: ~20-30 min per component, ~3-4 hours for your assigned group.
Tell Navi what's wrong. Include the component name and what you see vs what you expect.
Examples:
"File: Badge height should be 20px but it's 24.5px. The font weight is also different from WWW."
"Issue — Button hover state on primary is too subtle, needs better differentiation between default and hover."
"File an issue for SideNav: the title should have the same 8px interactive area as nav items, currently it's only 4px from the edge."
"Issue: Collapsible arrows are pointing the wrong direction. They should point right when collapsed and down when expanded."
Navi will infer the severity and details from your description.
If you describe a bug without explicitly saying "file" or "issue," Navi will confirm before submitting.
Go to Issues and describe what's wrong. Add the hardening label.
One issue per designer. All findings for your assigned components go in a single issue, grouped by component with checkboxes. This matches how engineering tracks their hardening work (see #719 for reference).
Hardening: [Designer Name]'s Components ([count])
## How This Works
Each component has a checkbox. Check it off when **all** findings for that component are resolved.
Findings are listed under each component with a severity tag:
- **P0** = broken, crash, doesn't render
- **P1** = visual mismatch, quality gap, a11y violation
- **P2** = polish, cosmetic, missing story
These map onto the rubric's severities: P0 and P1 are **BLOCK**, P2 is **FIX** or **NIT**. Use whichever vocabulary the reader expects — a designer's issue and an audit scorecard are describing the same defect.
**When you fix something:** create a PR, link it next to the finding, check off the finding. When all findings for a component are done, check the component box.
---
### Category Name (count)
- [ ] ComponentName
- [ ] P0: Description of the issue
- [ ] P1: Description of the issue
- [ ] P2: Description of the issue
**Storybook:** [link from tracker]
**WWW:** [link from tracker]### Status & Feedback (4)
- [ ] Badge
- [ ] P1: Height should be 20px, currently 24.5px
- [ ] P2: Font weight and type are different from WWW
- [ ] P2: Dark mode color is too faint
- [ ] Spinner
- [ ] P0: Storybook description is weird AI-generated text
- [ ] P2: Should have a way to render the label together with the spinner
- [x] EmptyState ✅
- [x] Token ✅
### Navigation (3)
- [ ] SideNav
- [ ] P0: Using inline style={{width: 16}} instead of width={16} prop
- [ ] P0: Title should have same interactive area as nav items (8px from edge, not 4px)
- [ ] P2: Needs visual adjustment when icon is not provided in header
- [ ] P2: 2px gap needed between page nav items
- [ ] Breadcrumbs
- [ ] P1: Leaf node appears offset, not vertically centered
- [ ] P1: Missing chevron variant
- [x] TopNav ✅Apply: hardening
Navi should infer from the designer's description:
- Component — from the component name mentioned
- Severity — crash/broken = P0, visual mismatch or quality gap = P1, cosmetic or missing story = P2
- Links — the component's Storybook story, and a screenshot of what you saw.
If the designer reports issues across multiple sessions, Navi should update the existing issue rather than creating a new one.
Grade against Component Audit Rubric rather than an ad-hoc read. The three dimensions this guide used to enumerate map onto it directly:
| Was | Now |
|---|---|
| Visual correctness |
Component Audit Rubric §5 — §5a objective from source, §5b from screenshots (and §5b is not measured, never 0, without them) |
| Storybook coverage | §8 X9–X12, plus §6 V10 |
| Responsive behavior | §10 |
The rubric's evidence gate applies here too: a design-quality audit that files visual findings without attaching the screenshots they came from is not gradeable.