# Semantic Theme Contrast Implementation Plan

> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.

**Goal:** Make ordinary public and admin text readable across every EpicNext light/dark preset by replacing concrete palette choices with tested semantic colors.

**Architecture:** Extend the runtime CSS generator with semantic foreground, solid-foreground, subtle-background, and border variables. Central CSS utilities expose those meanings to components. A scoped source audit prevents risky hard-coded admin text colors while allowing explicit graphical preview files.

**Tech Stack:** Next.js 16, TypeScript, CSS custom properties, Tailwind CSS 4, Vitest.

## Global Constraints

- Work directly on `main` in `E:\Users\simol\Desktop\EpicNext-cms`.
- Preserve and never stage the existing `package.json` modification.
- Maintain WCAG AA 4.5:1 for ordinary text.
- Do not recolor favicon, catalog-art, image, or color-picker previews.
- Verify the complete test suite, typecheck, and production build before publication.

---

### Task 1: Semantic contrast generation

**Files:** `src/lib/theme-contrast.ts`, `src/lib/theme-contrast.test.ts`, `src/lib/theme-css.ts`, `src/components/theme-vars.test.ts`

- [ ] Add failing tests for muted/subtle/disabled text, sidebar text, and success/warning/error/info pairs across every preset and mode.
- [ ] Extend `derivePublicForegrounds` and `themePaletteCss` to emit the tested variables.
- [ ] Run the four theme test files and commit with `feat: derive semantic theme contrast tokens`.

### Task 2: Semantic CSS utilities and admin shell

**Files:** `src/app/globals.css`, `src/app/admin/layout.tsx`, `src/components/admin/admin-nav-link.tsx`, `src/lib/admin-theme-source-audit.test.ts`

- [ ] Add a failing source-audit test that rejects risky fixed text colors in the admin shell.
- [ ] Add semantic utilities for text hierarchy, statuses, notices, sidebar, tables, and inputs.
- [ ] Replace the hard-coded admin sidebar and navigation palette with semantic variables.
- [ ] Run the audit and theme tests and commit with `feat: theme admin shell semantically`.

### Task 3: Admin-wide ordinary text migration

**Files:** ordinary UI files under `src/app/admin` and `src/components/admin`; exclude explicit graphical preview files in the audit allowlist.

- [ ] Expand the failing audit to reject `text-gray-400`, `text-gray-500`, `text-white`, and raw text hex colors outside the allowlist.
- [ ] Mechanically replace muted/disabled/status text utilities with semantic utilities and variables.
- [ ] Inspect status badges and notices to ensure their text/background use the same semantic family.
- [ ] Run audit, full test suite, and typecheck; commit with `refactor: use semantic colors across admin`.

### Task 4: Final verification and publication

**Files:** no additional production files.

- [ ] Run `pnpm test`, `pnpm typecheck`, and `pnpm build`.
- [ ] Run `git diff --check` and confirm `package.json` remains unstaged.
- [ ] Review the final diff for graphical preview exclusions and publish to `origin/main` after approval.