From 9572a1582b921b46993476e0e0f0018ca93faa6d Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 6 Aug 2026 05:24:58 +0000 Subject: [PATCH 01/10] docs: scope the Control Plane theming engine Research + architecture scoping for switchable UI themes (colors, fonts, icon packs, component personality) across the Control Plane: - Audit of existing foundations (shadcn-style tokens, next-themes, Tailwind v4 @theme inline) and the gaps blocking multi-theming - Recommended token-driven architecture: data-theme scopes, semantic abstraction, next/font family switching, org/user persistence - OSS evaluation: tweakcn, Iconify, @fluentui/react-icons, material-color-utilities, daisyUI, Style Dictionary (adopt/borrow/skip) - Example Fluent (Microsoft) and Material (Google) theme manifests - Phased implementation plan with estimates Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01SyTtr9JJXCS8xNkzW5Fny5 --- docs/THEMING_ENGINE_SCOPE.md | 236 +++++++++++++++++++++++++++++++++++ 1 file changed, 236 insertions(+) create mode 100644 docs/THEMING_ENGINE_SCOPE.md diff --git a/docs/THEMING_ENGINE_SCOPE.md b/docs/THEMING_ENGINE_SCOPE.md new file mode 100644 index 00000000..e483f805 --- /dev/null +++ b/docs/THEMING_ENGINE_SCOPE.md @@ -0,0 +1,236 @@ +# CommandCenter Theming Engine — Scoping Document + +**Status:** Scoping / research — no implementation yet +**Scope:** `workbench/control_plane` (Next.js 16 · React 19 · Tailwind CSS v4) +**Goal:** A theming engine that can restyle the entire Control Plane — colors, +fonts, radii, shadows, icon packs, component "personality" — switchable on the +fly from Settings, with company-wide defaults. Example target themes: the +current RapidTool look, a Microsoft Fluent/Metro ("Lumia") look, a Google +Material look. + +--- + +## 1. What we already have (audit) + +The codebase is unusually well-positioned for this. The hard prerequisite for +a theming engine — *components reference semantic tokens instead of raw +values* — is already largely true. + +| Building block | Current state | +|---|---| +| **Color tokens** | shadcn/ui-compatible semantic CSS custom properties (`--primary`, `--background`, `--card`, `--muted-foreground`, …) in `src/app/globals.css`, mapped to Tailwind utilities via v4 `@theme inline`. Dark is `:root`, light is `.light`. | +| **Theme switching** | `next-themes` already installed and mounted in `Providers.tsx` (`attribute="class"`, dark/light only). | +| **Radius** | Tokenized: `--radius` drives `rounded-lg/md/sm` via `@theme inline`. One variable changes the roundness of the whole app. | +| **Fonts** | Geist Sans/Mono via `next/font`, exposed as `--font-geist-sans` / `--font-geist-mono` and wired to `font-sans` / `font-mono`. | +| **Icons** | `lucide-react`, imported **directly in ~160 files**, ~115 unique icons. This is the biggest migration surface. | +| **Design system doc** | `workbench/control_plane/DESIGN_SYSTEM.md` mandates tokens, shared components, and layout patterns — agents already follow it. | +| **Settings infra** | `/settings/*` pages + `/api/settings/*` API routes that persist to the backend. An "Appearance" section slots right in. | + +### Gaps that block multi-theming today + +1. **Only 2 themes are modeled.** `next-themes` is configured for `dark`/`light` + classes only; there is no concept of a *style* (RapidTool / Fluent / + Material) orthogonal to *mode* (dark / light). +2. **Icons are hard-imported.** 160 files `import { X } from "lucide-react"` — + no indirection layer, so an icon-pack swap currently means editing every file. +3. **Hardcoded values outside the token system.** `tech-glass`, `tech-glow`, + `chat-shimmer-text`, scrollbars, and the ProseMirror selection color embed + raw `hsl(...)` values in `globals.css`; a handful of components use inline + hex/hsl. +4. **No shared `