Skip to content

Hardening Audit Guide

Jump to bottom
Cindy Zhang edited this page Jun 23, 2026 · 1 revision

Hardening Audit Guide

Design quality audit of all Astryx OSS components before external release. We want to catch visual bugs, inconsistencies, and gaps now — first impressions matter.

Tracker: Astryx Component Review Tracker

Target Date: Mar 24

Getting Started

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

How to Review

  1. Open both links in the tracker — the OSS Storybook link and the WWW component link
  2. Compare side by side — check visual correctness, states, and Storybook coverage
  3. File issues for anything that doesn't match or looks wrong
  4. Update your status in the tracker as you go

Time estimate: ~20-30 min per component, ~3-4 hours for your assigned group.

Filing Issues

Using Navi

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.

Filing Manually

Go to Issues and describe what's wrong. Add the hardening label.

Issue Format for Navi

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).

Title

Hardening: [Designer Name]'s Components ([count])

Body

## 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

**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]

Example

### 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
  - [ ] P3: 2px gap needed between page nav items
- [ ] Breadcrumbs
  - [ ] P1: Leaf node appears offset, not vertically centered
  - [ ] P1: Missing chevron variant
- [x] TopNav ✅

Labels

Apply: hardening

Inferring Details

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 — look up from the Component Review Tracker. The OS Component column has the Storybook link and the WWW Component column has the internal link.

If the designer reports issues across multiple sessions, Navi should update the existing issue rather than creating a new one.

Evaluation Criteria

Some components have been merged together, renamed, or have new props — the Changelogs column in the tracker notes these. Be mindful when comparing.

1. Visual Correctness

  • Does the component match the WWW equivalent? (accounting for intentional changes)
  • Are all states correct? (hover, focus, active, disabled, error)
  • Does it look right in both light and dark themes?
  • Is spacing/padding consistent with design system tokens?

2. Storybook Coverage

  • Does the component have stories for all key variants?
  • Are edge cases demonstrated? (empty state, long text, overflow)
  • Do interactive controls work correctly?

3. Responsive Behavior

  • Does the component handle different container widths?
  • Does text truncate/wrap appropriately?
  • Are touch targets adequate on mobile viewports?

Clone this wiki locally