314 lines
9.8 KiB
Markdown
314 lines
9.8 KiB
Markdown
# 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` in **label/secondary text context** → `text-secondary`
|
|
- `text-slate-300` in **placeholder/disabled/hint context** → `text-muted` ⚠️ check context first
|
|
- `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)
|
|
|
|
> **⚠️ slate-300 context rule:** `text-slate-300` serves two purposes. If it's on a label, heading, or value display → use `text-secondary`. If it's on placeholder text, a disabled input, or a loading skeleton → use `text-muted`. When in doubt, check whether the element is interactive/disabled.
|
|
|
|
**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.
|
|
|
|
- [x] **Step 1** — Audit & document all violations (no code changes)
|
|
- [x] **Step 2** — Fix: `app/login/page.tsx` text tokens (no violations found — already clean)
|
|
- [x] **Step 3** — Fix: `app/page.tsx` text tokens (scanner/main page)
|
|
- [x] **Step 4** — Fix: `app/inventory/page.tsx` text tokens
|
|
- [x] **Step 5** — Fix: `app/admin/page.tsx` + `app/logs/page.tsx` text tokens
|
|
- [x] **Step 6** — Fix: `components/AdminOverlay.tsx` text tokens
|
|
- [x] **Step 7** — Fix: `components/IdentityCheckOverlay.tsx` text tokens
|
|
- [x] **Step 8** — Fix: `components/Scanner.tsx` + `components/AIOnboarding.tsx`
|
|
- [x] **Step 9** — Fix: `components/admin/` (all 5 files)
|
|
- [x] **Step 10** — Fix: Modals (`CreateUserModal`, `ConfirmationModal`, `CategoryCreationModal`, `ItemComparisonModal`)
|
|
- [x] **Step 11** — Fix: `lib/` and remaining components
|
|
- [x] **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)"
|
|
```
|
|
|
|
**Then manually annotate `ui-uniformity-audit.txt` for each `text-slate-300` line:**
|
|
Add a comment at the end of the line: `# LABEL` (use text-secondary) or `# PLACEHOLDER` (use text-muted).
|
|
This takes 5 minutes and prevents contrast regressions in disabled form fields.
|
|
|
|
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
|
|
# Must: 0 build errors, 291 tests passing
|
|
```
|
|
|
|
**Visual smoke checklist (open the app, check each item):**
|
|
- [ ] Login page: disabled inputs look visibly dimmer than active inputs
|
|
- [ ] Login page: placeholder text is lighter than typed text
|
|
- [ ] Main page (scanner): section labels are clearly smaller/lighter than page title
|
|
- [ ] Inventory page: table row text reads at consistent weight/color throughout
|
|
- [ ] Admin page: error messages appear in red, not muted gray
|
|
- [ ] Any modal (e.g., Create User): modal title is clearly the largest text inside it
|
|
- [ ] `text-muted` elements are visibly lighter than `text-secondary` elements anywhere on same page
|
|
|
|
All 7 must pass visually before marking this step complete.
|
|
|
|
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).**
|