# 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).**