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