docs: add ui-uniformity plan with session-persistent progress tracker (12 steps)
This commit is contained in:
295
docs/superpowers/plans/2026-04-19-ui-uniformity.md
Normal file
295
docs/superpowers/plans/2026-04-19-ui-uniformity.md
Normal file
@@ -0,0 +1,295 @@
|
||||
# UI Uniformity Plan — aInventory
|
||||
|
||||
> **FOR EVERY SESSION:** Read this file first. Find the first unchecked step. Do ONLY that step. Mark it done. Commit. Stop.
|
||||
> This file is the source of truth. It survives session resets.
|
||||
|
||||
**Branch:** `refactor/ai-friendly-v2`
|
||||
**Goal:** All components of the same type look identical across all pages and modals.
|
||||
**Mode:** HOLD SCOPE — fix uniformity, no new features.
|
||||
**Last updated:** 2026-04-19
|
||||
|
||||
---
|
||||
|
||||
## Token Standard (reference — do not change)
|
||||
|
||||
The design tokens already exist in `frontend/tailwind.config.ts`. Use these and nothing else:
|
||||
|
||||
| Purpose | Class | Value |
|
||||
|---------|-------|-------|
|
||||
| Page/section title | `text-white font-black` | #F0F4F8 |
|
||||
| Primary body text | `text-foreground` | #F0F4F8 |
|
||||
| Secondary text | `text-secondary` | #C7D2E0 |
|
||||
| Muted/hint text | `text-muted` | #8B95AD |
|
||||
| Brand accent | `text-primary` | #3B82F6 |
|
||||
| Error | `text-error` | #EF4444 |
|
||||
| Success | `text-success` | #10B981 |
|
||||
|
||||
**Replace these hardcoded classes with the tokens above:**
|
||||
- `text-slate-100`, `text-slate-200` → `text-secondary` (secondary text)
|
||||
- `text-slate-300` → `text-secondary` (secondary text, slightly darker)
|
||||
- `text-slate-400`, `text-slate-500` → `text-muted` (muted/hint)
|
||||
- `text-slate-700` (on light bg) → keep as-is (inverted context)
|
||||
- `text-white` on headings → keep (page titles only)
|
||||
|
||||
**Font weight standard:**
|
||||
- Page titles (main heading per page): `text-2xl font-black` or `text-3xl font-black`
|
||||
- Section labels: `text-xs font-black text-muted`
|
||||
- Body text / list items: `text-sm font-bold`
|
||||
- Tiny hints / captions: `text-xs font-bold text-muted` or `text-[10px] font-bold text-muted`
|
||||
- Buttons: `font-black` (primary), `font-bold` (secondary)
|
||||
|
||||
---
|
||||
|
||||
## Progress Tracker
|
||||
|
||||
Mark each step `[x]` when complete. Commit the file with the step.
|
||||
|
||||
- [ ] **Step 1** — Audit & document all violations (no code changes)
|
||||
- [ ] **Step 2** — Fix: `app/login/page.tsx` text tokens
|
||||
- [ ] **Step 3** — Fix: `app/page.tsx` text tokens (scanner/main page)
|
||||
- [ ] **Step 4** — Fix: `app/inventory/page.tsx` text tokens
|
||||
- [ ] **Step 5** — Fix: `app/admin/page.tsx` + `app/logs/page.tsx` text tokens
|
||||
- [ ] **Step 6** — Fix: `components/AdminOverlay.tsx` text tokens
|
||||
- [ ] **Step 7** — Fix: `components/IdentityCheckOverlay.tsx` text tokens
|
||||
- [ ] **Step 8** — Fix: `components/Scanner.tsx` + `components/AIOnboarding.tsx`
|
||||
- [ ] **Step 9** — Fix: `components/admin/` (all 5 files)
|
||||
- [ ] **Step 10** — Fix: Modals (`CreateUserModal`, `ConfirmationModal`, `CategoryCreationModal`, `ItemComparisonModal`)
|
||||
- [ ] **Step 11** — Fix: `lib/` and remaining components
|
||||
- [ ] **Step 12** — Final build verification + visual smoke check
|
||||
|
||||
---
|
||||
|
||||
## Step Details
|
||||
|
||||
### Step 1 — Audit (no code changes)
|
||||
|
||||
Run this command and save the output to `docs/superpowers/plans/ui-uniformity-audit.txt`:
|
||||
|
||||
```bash
|
||||
cd frontend && grep -rn \
|
||||
"text-slate-[12345]00\|text-zinc-[12345]00\|text-gray-[12345]00" \
|
||||
app components \
|
||||
--include="*.tsx" \
|
||||
> ../docs/superpowers/plans/ui-uniformity-audit.txt 2>&1
|
||||
echo "Lines found: $(wc -l < ../docs/superpowers/plans/ui-uniformity-audit.txt)"
|
||||
```
|
||||
|
||||
Commit:
|
||||
```bash
|
||||
git add docs/superpowers/plans/ui-uniformity-audit.txt docs/superpowers/plans/2026-04-19-ui-uniformity.md
|
||||
git commit -m "docs: ui-uniformity step 1 - audit all text color violations"
|
||||
```
|
||||
|
||||
Mark this step `[x]` before committing.
|
||||
|
||||
---
|
||||
|
||||
### Step 2 — Fix: `app/login/page.tsx`
|
||||
|
||||
Replace all `text-slate-*`, `text-zinc-*`, `text-gray-*` with semantic tokens (see Token Standard above).
|
||||
|
||||
After edits:
|
||||
```bash
|
||||
cd frontend && npm run build 2>&1 | tail -5
|
||||
```
|
||||
|
||||
Must pass with zero errors.
|
||||
|
||||
Commit:
|
||||
```bash
|
||||
git add frontend/app/login/page.tsx docs/superpowers/plans/2026-04-19-ui-uniformity.md
|
||||
git commit -m "style: step 2 - uniform text tokens in login page"
|
||||
```
|
||||
|
||||
Mark this step `[x]` before committing.
|
||||
|
||||
---
|
||||
|
||||
### Step 3 — Fix: `app/page.tsx`
|
||||
|
||||
Replace all `text-slate-*`, `text-zinc-*`, `text-gray-*` with semantic tokens.
|
||||
|
||||
After edits:
|
||||
```bash
|
||||
cd frontend && npm run build 2>&1 | tail -5
|
||||
```
|
||||
|
||||
Commit:
|
||||
```bash
|
||||
git add frontend/app/page.tsx docs/superpowers/plans/2026-04-19-ui-uniformity.md
|
||||
git commit -m "style: step 3 - uniform text tokens in main page"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 4 — Fix: `app/inventory/page.tsx`
|
||||
|
||||
Replace all hardcoded text colors with semantic tokens.
|
||||
|
||||
After edits:
|
||||
```bash
|
||||
cd frontend && npm run build 2>&1 | tail -5
|
||||
```
|
||||
|
||||
Commit:
|
||||
```bash
|
||||
git add frontend/app/inventory/page.tsx docs/superpowers/plans/2026-04-19-ui-uniformity.md
|
||||
git commit -m "style: step 4 - uniform text tokens in inventory page"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 5 — Fix: `app/admin/page.tsx` + `app/logs/page.tsx`
|
||||
|
||||
Replace all hardcoded text colors in both files.
|
||||
|
||||
After edits:
|
||||
```bash
|
||||
cd frontend && npm run build 2>&1 | tail -5
|
||||
```
|
||||
|
||||
Commit:
|
||||
```bash
|
||||
git add frontend/app/admin/page.tsx frontend/app/logs/page.tsx docs/superpowers/plans/2026-04-19-ui-uniformity.md
|
||||
git commit -m "style: step 5 - uniform text tokens in admin and logs pages"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 6 — Fix: `components/AdminOverlay.tsx`
|
||||
|
||||
Replace all hardcoded text colors.
|
||||
|
||||
After edits:
|
||||
```bash
|
||||
cd frontend && npm run build 2>&1 | tail -5
|
||||
```
|
||||
|
||||
Commit:
|
||||
```bash
|
||||
git add frontend/components/AdminOverlay.tsx docs/superpowers/plans/2026-04-19-ui-uniformity.md
|
||||
git commit -m "style: step 6 - uniform text tokens in AdminOverlay"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 7 — Fix: `components/IdentityCheckOverlay.tsx`
|
||||
|
||||
Replace all hardcoded text colors.
|
||||
|
||||
After edits:
|
||||
```bash
|
||||
cd frontend && npm run build 2>&1 | tail -5
|
||||
```
|
||||
|
||||
Commit:
|
||||
```bash
|
||||
git add frontend/components/IdentityCheckOverlay.tsx docs/superpowers/plans/2026-04-19-ui-uniformity.md
|
||||
git commit -m "style: step 7 - uniform text tokens in IdentityCheckOverlay"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 8 — Fix: `components/Scanner.tsx` + `components/AIOnboarding.tsx`
|
||||
|
||||
Replace all hardcoded text colors in both files.
|
||||
|
||||
After edits:
|
||||
```bash
|
||||
cd frontend && npm run build 2>&1 | tail -5
|
||||
```
|
||||
|
||||
Commit:
|
||||
```bash
|
||||
git add frontend/components/Scanner.tsx frontend/components/AIOnboarding.tsx docs/superpowers/plans/2026-04-19-ui-uniformity.md
|
||||
git commit -m "style: step 8 - uniform text tokens in Scanner and AIOnboarding"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 9 — Fix: `components/admin/` (all 5 files)
|
||||
|
||||
Files: `AiManager.tsx`, `CategoryManager.tsx`, `DatabaseManager.tsx`, `IdentityManager.tsx`, `LdapManager.tsx`
|
||||
|
||||
After edits:
|
||||
```bash
|
||||
cd frontend && npm run build 2>&1 | tail -5
|
||||
```
|
||||
|
||||
Commit:
|
||||
```bash
|
||||
git add frontend/components/admin/ docs/superpowers/plans/2026-04-19-ui-uniformity.md
|
||||
git commit -m "style: step 9 - uniform text tokens in admin sub-components"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 10 — Fix: Modals
|
||||
|
||||
Files: `CreateUserModal.tsx`, `ConfirmationModal.tsx`, `CategoryCreationModal.tsx`, `ItemComparisonModal.tsx`, `LogsOverlay.tsx`
|
||||
|
||||
After edits:
|
||||
```bash
|
||||
cd frontend && npm run build 2>&1 | tail -5
|
||||
```
|
||||
|
||||
Commit:
|
||||
```bash
|
||||
git add frontend/components/CreateUserModal.tsx frontend/components/ConfirmationModal.tsx \
|
||||
frontend/components/CategoryCreationModal.tsx frontend/components/ItemComparisonModal.tsx \
|
||||
frontend/components/LogsOverlay.tsx docs/superpowers/plans/2026-04-19-ui-uniformity.md
|
||||
git commit -m "style: step 10 - uniform text tokens in modals"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 11 — Fix: Remaining (`lib/`, `BottomNav.tsx`, `PageShell.tsx`, `StatCard.tsx`)
|
||||
|
||||
After edits:
|
||||
```bash
|
||||
cd frontend && npm run build 2>&1 | tail -5
|
||||
```
|
||||
|
||||
Verify no hardcoded colors remain:
|
||||
```bash
|
||||
cd frontend && grep -rn "text-slate-[12345]00\|text-zinc-[12345]00" app components --include="*.tsx" | grep -v "//.*text-" | wc -l
|
||||
# Should be 0 or very close to 0
|
||||
```
|
||||
|
||||
Commit:
|
||||
```bash
|
||||
git add frontend/components/BottomNav.tsx frontend/components/PageShell.tsx \
|
||||
frontend/components/StatCard.tsx docs/superpowers/plans/2026-04-19-ui-uniformity.md
|
||||
git commit -m "style: step 11 - uniform text tokens in remaining components"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 12 — Final verification
|
||||
|
||||
```bash
|
||||
cd frontend && npm run build 2>&1 | tail -10
|
||||
cd frontend && npm run test -- --run 2>&1 | tail -5
|
||||
# Manually verify: login page, main page, inventory, admin, at least one modal
|
||||
```
|
||||
|
||||
Update this file: mark all steps done. Then update `dev_docs/SESSION_STATE.md`.
|
||||
|
||||
Commit:
|
||||
```bash
|
||||
git add docs/superpowers/plans/2026-04-19-ui-uniformity.md dev_docs/SESSION_STATE.md
|
||||
git commit -m "style: step 12 - ui uniformity complete, 291 frontend tests passing"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Session Continuity Instructions
|
||||
|
||||
**At the start of every session:**
|
||||
1. Read this file: `docs/superpowers/plans/2026-04-19-ui-uniformity.md`
|
||||
2. Find the first unchecked `[ ]` step in the Progress Tracker
|
||||
3. Read the Step Details for that step
|
||||
4. Execute exactly that step — no more, no less
|
||||
5. Mark it `[x]`, commit, stop
|
||||
|
||||
**Do not skip steps. Do not batch steps. One step = one session (or part of one).**
|
||||
Reference in New Issue
Block a user