core/docs/USABILITY-SURVEY.md

Armature Usability Survey — Automated Checklist

Purpose: Machine-auditable quality gate for the Armature UI. Run all scripts first, then walk each section. A FAIL in any section blocks release.

---

Prerequisites

Run these scripts from the project root and save their output:

bash scripts/generate-ui-inventory.sh > ui-inventory.json
bash scripts/check-contrast.sh > contrast-report.txt
bash scripts/generate-coverage-matrix.sh > coverage-matrix.md
bash scripts/audit-touch-targets.sh > touch-targets-report.txt

---

Section 1: Viewport Correctness

Pass criteria:

• No CSS file uses 100vh (should be 100% or 100dvh)
• .sw-shell uses height: 100%, not 100vh
• All extension surfaces use height: 100%
• No transform: scale() for zoom (should use CSS zoom)

Files to inspect:

• src/css/sw-shell.css
• src/css/layout.css
• packages/*/css/main.css

How to check:

grep -rn '100vh' src/css/ packages/*/css/ --include='*.css'
grep -rn 'transform.*scale' src/css/ packages/*/css/ --include='*.css'

Result: PASS if zero matches. FAIL if any 100vh or transform: scale() for layout sizing.

---

Section 2: Banner Integration

Pass criteria:

• Banners are in-flow (no position: fixed on banner elements)
• --banner-top-height and --banner-bottom-height are defined in :root
• Shell layout accounts for banner height via CSS variables, not hardcoded px
• No surface hardcodes 28px or other banner height values

Files to inspect:

• src/css/sw-shell.css
• src/css/variables.css (:root block)
• src/js/sw/shell/app-shell.js

How to check:

grep -n 'position.*fixed' src/css/sw-shell.css | grep -i banner
grep -n '28px' src/css/ -r --include='*.css'
grep -n 'banner-top-height\|banner-bottom-height' src/css/variables.css

Result: PASS if banners are in-flow and height is variable-driven. FAIL if fixed positioning or hardcoded heights.

---

Section 3: Responsive Behavior

Pass criteria:

• Kernel CSS uses 768px (mobile) and 1024px (tablet) breakpoints
• No hardcoded widths that break below 768px (except intentional min-widths on dialogs)
• Sidebar collapses on mobile
• Extension surfaces adapt to narrow viewports

Files to inspect:

• src/css/layout.css
• src/css/surfaces.css
• packages/*/css/main.css

How to check:

# Verify breakpoints used
grep -rn '@media.*max-width' src/css/ --include='*.css' | grep -v '768\|1024'
# Check for hardcoded widths
grep -rn 'width:.*[0-9]\+px' src/css/layout.css | grep -v 'max-width\|min-width\|--'

Result: PASS if only 768px and 1024px breakpoints. WARN if other breakpoints exist but are justified. FAIL if layout breaks below 768px.

---

Section 4: Styling Consistency

Pass criteria:

• All spacing uses --sp-* tokens (no raw px for padding/margin/gap > 3px)
• All border-radius uses --radius-sm, --radius, or --radius-lg
• All font-family uses var(--font) or var(--mono)
• No external font CDN imports (@import url( or Google Fonts references)
• No stale fallback colors (#b38a4e or other non-token hex in property values)

Files to inspect:

• All src/css/*.css
• packages/*/css/main.css

How to check:

# Raw px spacing (padding/margin/gap > 3px, not inside var())
grep -rnE '(padding|margin|gap):\s*[0-9]+(px|rem)' src/css/ packages/*/css/ --include='*.css' | grep -v 'var(--' | grep -v '0px\|1px\|2px\|3px'
# Raw border-radius
grep -rn 'border-radius:' src/css/ packages/*/css/ --include='*.css' | grep -v 'var(--radius'
# External fonts
grep -rn '@import url\|fonts.googleapis' src/css/ --include='*.css'
# Stale fallback gold color
grep -rn '#b38a4e' src/css/ packages/*/css/ --include='*.css'

Result: PASS if zero non-token values (excluding reset/keyframe contexts). WARN for 1-3 edge cases with justification. FAIL for systematic violations.

---

Section 5: Accessibility — Contrast

Pass criteria:

• contrast-report.txt shows all PASS for normal text (4.5:1 ratio)
• No FAIL results in either dark or light theme

Files to inspect:

• contrast-report.txt (generated above)

How to check:

grep 'FAIL' contrast-report.txt

Result: PASS if zero FAIL lines. FAIL if any contrast violation.

---

Section 6: Accessibility — Touch Targets

Pass criteria:

• touch-targets-report.txt shows zero violations
• All close buttons have min-width: 44px; min-height: 44px in @media (max-width: 768px)
• Menu items have min-height: 44px on mobile (already done in sw-primitives.css)

Files to inspect:

• touch-targets-report.txt (generated above)
• src/css/sw-primitives.css — close button rules

How to check:

grep 'FAIL\|MISSING' touch-targets-report.txt

Result: PASS if zero violations. FAIL if any close button lacks mobile touch target.

---

Section 7: Accessibility — Focus Indicators

Pass criteria:

• All interactive primitives have :focus-visible styles
• No outline: none without a replacement focus indicator
• Focus ring is visible on both dark and light themes

Files to inspect:

• src/css/sw-primitives.css
• src/css/primitives.css
• src/css/variables.css

How to check:

# Check for focus-visible on key primitives
for cls in sw-btn sw-input sw-dropdown__trigger sw-menu__item sw-tabs__tab; do
  echo -n "$cls: "
  grep -c "\.${cls}.*:focus-visible\|\.${cls}:focus-visible" src/css/sw-primitives.css src/css/primitives.css 2>/dev/null || echo "0"
done
# Check for outline:none without replacement
grep -n 'outline.*none\|outline.*0' src/css/*.css | grep -v 'focus-visible\|focus-within'

Result: PASS if all 5 key primitives have :focus-visible. WARN if outline:none exists with adequate replacement. FAIL if missing focus indicators.

---

Section 8: Component Uniformity

Pass criteria:

• coverage-matrix.md shows no deprecated component usage (no ⚠ in the deprecated row)
• All surfaces use sw-* primitives, not old .btn-*, .toast, .popup-menu

Files to inspect:

• coverage-matrix.md (generated above)

How to check:

grep '⚠' coverage-matrix.md

Result: PASS if zero ⚠ markers. FAIL if any deprecated component still in use.

---

Scoring

Section	Weight	Result
1. Viewport Correctness	Required
2. Banner Integration	Required
3. Responsive Behavior	Required
4. Styling Consistency	Required
5. Contrast	Required
6. Touch Targets	Required
7. Focus Indicators	Required
8. Component Uniformity	Required

Overall: PASS requires all sections PASS or WARN. Any FAIL blocks the release.

---

After the Survey

1. Fix all FAIL items
2. Re-run affected scripts to confirm fixes
3. Re-run the full survey
4. Tag v0.6.16 only after a clean survey pass