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

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.