EpicNext-Cms/docs/superpowers/plans/2026-07-12-epicnext-multitheme.md

EpicNext Multitheme 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: Give every EpicNext preset complete, coherent light and dark palettes while retaining the visitor mode toggle and rebranding the CMS information popup.

Architecture: A canonical theme-key contract defines every persisted/runtime color. Presets provide complete light and dark palettes; ThemeVars emits both scopes and the existing toggle only selects a scope. Admin preset application persists both variants atomically and legacy unqualified settings remain the light-mode compatibility source.

Tech Stack: Next.js 16, React 19, TypeScript, CSS custom properties, Prisma website settings, Vitest.

Global Constraints

• Work directly in E:\Users\simol\Desktop\EpicNext-cms; do not create a worktree.
• Preserve the existing uncommitted package.json change and never stage it.
• Keep localStorage.theme limited to light or dark.
• Every built-in preset must define every canonical color key in both modes.
• Build, typecheck, and the complete test suite must pass before publication.

---

Task 1: Canonical complete preset model

Files:

• Modify: src/lib/theme-presets.ts
• Modify: src/lib/theme-contrast.test.ts

Interfaces:

• Produces: ThemeMode, ThemeColorKey, ThemePalette, ThemePreset, THEME_COLOR_KEYS, and PRESETS with { light, dark } variants.

• Consumes: existing color names used by ThemeVars and the admin editor.

• Add failing tests that iterate every preset/mode and require exact coverage of THEME_COLOR_KEYS, then run pnpm vitest run src/lib/theme-contrast.test.ts and confirm missing dark variants fail.

• Define the canonical keys and typed palette/preset interfaces, convert every preset to complete light/dark variants, and include buttons, links, borders, and gradients.

• Update contrast tests to evaluate both variants and run the targeted test to green.

• Commit only src/lib/theme-presets.ts and src/lib/theme-contrast.test.ts with feat: add complete light and dark presets.

Task 2: Runtime light/dark variables

Files:

• Modify: src/components/theme-vars.tsx
• Modify: src/app/globals.css
• Create: src/components/theme-vars.test.tsx

Interfaces:

• Consumes: complete ThemePreset and mode-qualified website settings.

• Produces: one server-generated style containing :root{...} and html.dark{...} variables.

• Add a failing render test that requires separate light/dark variable blocks and different preset-specific background values.

• Extract palette loading and CSS generation into testable helpers in theme-vars.tsx; read legacy keys for light fallback and <key>_dark for dark overrides.

• Remove hardcoded color declarations from html.dark while retaining input/table behavioral selectors.

• Run the new test and existing contrast suite to green.

• Commit the three files with feat: generate theme-aware light and dark variables.

Task 3: Complete admin persistence

Files:

• Modify: src/actions/admin-theme.ts
• Modify: src/app/admin/theme/page.tsx
• Create: src/lib/theme-settings.ts
• Create: src/lib/theme-settings.test.ts

Interfaces:

• Produces: settingKey(key: ThemeColorKey, mode: ThemeMode): string and presetSettings(preset: ThemePreset): Array<[string, string]>.

• Consumes: canonical preset model from Task 1.

• Add failing tests proving presetSettings returns every light key plus every _dark key with no duplicates.

• Implement pure setting mapping helpers and use them in applyPreset so a preset writes the full pair.

• Render light and dark color sections in the admin form and update saveTheme to persist both sets.

• Preserve legacy unqualified light keys and use _dark suffixes only for dark values.

• Run mapping, theme, action-contract, typecheck, and relevant UI tests.

• Commit the four files with feat: persist complete multitheme palettes.

Task 4: EpicNext popup and final verification

Files:

• Modify: src/components/cms-info-popup.tsx
• Modify: src/components/cms-info-popup.test.tsx

Interfaces:

• Consumes: semantic runtime CSS variables.

• Produces: EpicNext-branded footer trigger and modal copy.

• Change the popup test first to require EpicNext Info, EpicNext, and Modern Next.js CMS; run it and confirm it fails on AtomCMS copy.

• Replace AtomCMS branding and credits without introducing literal theme colors.

• Run popup and theme tests, then pnpm typecheck, pnpm test, and pnpm build.

• Inspect git diff --check and confirm package.json remains unstaged and unchanged by this implementation.

• Commit popup files with feat: rebrand CMS information as EpicNext.

• Push the completed commits to origin/main only after all verification succeeds.