From eea63b061247a356867d51dd17821dd7ecadaa11 Mon Sep 17 00:00:00 2001 From: Daniel Bedeleanu Date: Sun, 19 Apr 2026 11:24:55 +0300 Subject: [PATCH] docs: add ui-uniformity plan with session-persistent progress tracker (12 steps) --- .../plans/2026-04-19-ui-uniformity.md | 295 ++++++++++++++++++ 1 file changed, 295 insertions(+) create mode 100644 docs/superpowers/plans/2026-04-19-ui-uniformity.md diff --git a/docs/superpowers/plans/2026-04-19-ui-uniformity.md b/docs/superpowers/plans/2026-04-19-ui-uniformity.md new file mode 100644 index 00000000..88964970 --- /dev/null +++ b/docs/superpowers/plans/2026-04-19-ui-uniformity.md @@ -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).**