Jeffrey Smith
ff19a1b4d3
All checks were successful
Co-authored-by: Jeffrey Smith <jasafpro@gmail.com> Co-committed-by: Jeffrey Smith <jasafpro@gmail.com>
228 lines
6.8 KiB
Markdown
228 lines
6.8 KiB
Markdown
# 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
|
|
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:**
|
|
```bash
|
|
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:**
|
|
```bash
|
|
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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
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:**
|
|
```bash
|
|
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:**
|
|
```bash
|
|
# 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:**
|
|
```bash
|
|
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
|