docs: plan semantic theme contrast work

docs/superpowers/plans/2026-07-12-semantic-theme-contrast.md

@@ -0,0 +1,53 @@
+# 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.