EpicNext-Cms/docs/superpowers/plans/2026-07-12-admin-theme-isolation.md

Admin Theme Isolation 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 every admin page, including all import workflows, readable in light and dark mode without inheriting unsafe public-theme color combinations.

Architecture: Generate a dedicated semantic --admin-* palette alongside the existing public variables, scope it to the admin layout, and migrate admin UI chrome to those tokens. A source-contract test prevents public structural tokens and unapproved literal palette colors from returning to /admin.

Tech Stack: Next.js 16, React 19, TypeScript, Tailwind CSS, CSS custom properties, Vitest.

Global Constraints

• Work directly in E:\Users\simol\Desktop\EpicNext-cms; do not create a worktree.
• Preserve and do not stage the existing local package.json modification.
• Cover the complete src/app/admin tree, including badge, clone, clothing, effects, furni, pets, and repair imports.
• Preserve literal colors that represent editable data or faithful content previews.
• Do not add runtime dependencies.

---

Task 1: Enforce the admin color boundary

Files:

• Modify: src/lib/admin-theme-source-audit.test.ts

Interfaces:

• Consumes: source files below src/app/admin

• Produces: a failing contract when UI chrome uses forbidden public or literal colors

• Step 1: Extend the source audit with explicit forbidden patterns and exception paths

Add checks for structural --color-background, --color-surface, --color-text, --color-text-muted, and palette utilities such as bg-zinc-400. Exempt the theme editor, favicon editor, user-editable banner/prefix/event/tag/team values, and faithful preview canvases.

• Step 2: Verify the test fails for the current admin sources

Run: pnpm vitest run src/lib/admin-theme-source-audit.test.ts

Expected: FAIL listing current public-token and hard-coded-color violations, including import pages.

• Step 3: Commit the failing contract

Run: git add src/lib/admin-theme-source-audit.test.ts && git commit -m "test: enforce admin theme isolation"

Task 2: Generate the semantic admin palette

Files:

• Modify: src/lib/theme-css.ts
• Modify: src/components/theme-vars.tsx
• Modify: src/components/theme-vars.test.ts
• Modify: src/lib/theme-contrast.test.ts

Interfaces:

• Consumes: ThemePalette, readableColor, and derived semantic foregrounds

• Produces: --admin-canvas, --admin-surface, --admin-surface-elevated, --admin-text, --admin-text-muted, --admin-border, --admin-accent, --admin-accent-foreground, status, sidebar, input, overlay, and focus variables

• Step 1: Add failing assertions for complete light and dark admin tokens

Assert that generated CSS contains every admin token and that readable foregrounds are derived rather than copied from unsafe public values.

• Step 2: Run focused tests and confirm the missing-token failure

Run: pnpm vitest run src/components/theme-vars.test.ts src/lib/theme-contrast.test.ts

Expected: FAIL because the admin palette has not been generated.

• Step 3: Generate the admin tokens using existing contrast helpers

Keep the public palette unchanged. Use stable neutral structural surfaces for each mode, allow the preset primary color to influence --admin-accent, and derive its foreground through readableColor.

• Step 4: Run focused tests

Run: pnpm vitest run src/components/theme-vars.test.ts src/lib/theme-contrast.test.ts

Expected: PASS.

• Step 5: Commit

Run: git add src/lib/theme-css.ts src/components/theme-vars.tsx src/components/theme-vars.test.ts src/lib/theme-contrast.test.ts && git commit -m "feat: add semantic admin palette"

Task 3: Migrate shared admin styling and layout

Files:

• Modify: src/app/globals.css
• Modify: src/app/admin/layout.tsx

Interfaces:

• Consumes: the --admin-* palette from Task 2

• Produces: admin layout, cards, tables, forms, navigation, dialogs, and focus states independent from public structural colors

• Step 1: Scope admin semantic aliases at the admin root

Apply the admin canvas/text variables at .admin-page and replace shared admin CSS references to public background, surface, text, muted text, border, and primary variables with their semantic admin equivalents.

• Step 2: Migrate sidebar and header classes in the admin layout

Use the sidebar, accent, surface, text, muted, and border admin variables; retain no public structural variable in layout chrome.

• Step 3: Run the source audit and CSS/theme tests

Run: pnpm vitest run src/lib/admin-theme-source-audit.test.ts src/components/theme-vars.test.ts src/lib/theme-contrast.test.ts

Expected: remaining failures point only to individual pages.

• Step 4: Commit

Run: git add src/app/globals.css src/app/admin/layout.tsx && git commit -m "fix: isolate shared admin styling"

Task 4: Migrate admin pages and import workflows

Files:

• Modify: violating files reported by src/lib/admin-theme-source-audit.test.ts below src/app/admin/**

Interfaces:

• Consumes: semantic admin variables and shared admin styles from Task 3

• Produces: zero unapproved source-audit violations across all admin routes

• Step 1: Replace structural public variables page by page

Map background to --admin-canvas or --admin-surface, text to --admin-text, muted text to --admin-text-muted, primary UI accents to --admin-accent, and status UI to the matching admin status token.

• Step 2: Replace hard-coded palette utilities in ordinary admin pages

Migrate catalog currency accents, offline indicators, alerts, modal overlays, and decorative gradients. Do not alter stored/user-entered color fields.

• Step 3: Migrate every import workflow

Replace status shadows, selection gradients, tooltips, dialog overlays, labels, and borders in badge, clone, clothing, effects, furni, pets, and repair imports. Preserve asset pixels and intentionally neutral preview canvases.

• Step 4: Run the source audit until it passes

Run: pnpm vitest run src/lib/admin-theme-source-audit.test.ts

Expected: PASS with no unapproved violations.

• Step 5: Commit

Run: git add src/app/admin && git commit -m "fix: use semantic colors across admin pages"

Task 5: Verify and publish

Files:

• Verify all committed files; do not stage package.json

Interfaces:

• Consumes: Tasks 1-4

• Produces: verified commits on main

• Step 1: Run formatting and whitespace checks

Run: git diff --check origin/main...HEAD

Expected: no output and exit code 0.

• Step 2: Run complete verification

Run: pnpm test && pnpm typecheck && pnpm build

Expected: all tests pass, TypeScript exits 0, and Next.js production build succeeds.

• Step 3: Confirm the dirty-file boundary

Run: git status --short

Expected: only M package.json.

• Step 4: Synchronize and publish main safely

Run: git fetch origin main --prune, verify origin/main is an ancestor of HEAD, then run git push origin main.

Expected: push succeeds without force.