docs: plan admin theme isolation
This commit is contained in:
Simo committed
1 parent
907ac9bf5b
commit
1c581ca5df
1 file changed
+170
@@ -0,0 +1,170 @@
|
||||
# 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.
|
||||
Reference in new issue
Block a user