agentscope-ai / agentscope-ai/QwenPaw
[Design Proposal] Configurable theme/skin module (Task #1 from #2291)
- Lingua principale
- TypeScript
- Stelle
- 35k
- Fork
- 3.1k
- Merge medio
- 1g 13h
- PR unite (30g)
- 228
Descrizione
## Summary
Design proposal for **Task 1** from #2291 — a **configurable theme/skin module** to enhance product branding and appearance customization (P0).
This issue is opened to discuss the design before submitting a PR, per the contributing guide. I have already [commented to claim Task 1](https://github.com/agentscope-ai/QwenPaw/issues/2291#issuecomment-4927764231).
## Current state
- `console/src/contexts/ThemeContext.tsx` already provides **mode switching**: `light` / `dark` / `system`, persisted in `localStorage` (`qwenpaw-theme`), listening to `prefers-color-scheme`, toggling a `dark-mode` class on ``.
- `console/src/components/ThemeToggleButton/index.tsx` exposes a dropdown for those three modes, rendered in `console/src/layouts/Header.tsx`.
- In `console/src/App.tsx`, antd `ConfigProvider` mounts with `algorithm` driven by `isDark`, but `token.colorPrimary` is **hardcoded** to `#FF7F16`:
```tsx
theme={{
algorithm: isDark ? antdTheme.darkAlgorithm : antdTheme.defaultAlgorithm,
token: { colorPrimary: "#FF7F16" },
}}
```
So the brand color is fixed and not user-configurable; there is no concept of a "skin" beyond light/dark.
## Goal
Let users pick a **preset skin** (brand palette) in addition to light/dark/system — without breaking existing behavior and without a heavy free-form color picker.
## Proposed design — preset skin module
1. **Skins are preset objects**, e.g.:
```ts
type Skin = { key: string; colorPrimary: string; colorInfo?: string; ... };
const SKINS: Skin[] = [
{ key: "default", colorPrimary: "#FF7F16" }, // current orange, kept as default
{ key: "blue", colorPrimary: "#1677ff" },
{ key: "purple", colorPrimary: "#722ed1" },
{ key: "green", colorPrimary: "#52c41a" },
];
```
2. **Extend `ThemeContext`** with a `skin` field + `setSkin`, persisted to `localStorage` (`qwenpaw-skin`), defaulting to `default` (orange) so existing visuals are unchanged.
3. **Drive antd tokens from the skin** in `App.tsx` — `colorPrimary` (and optionally `colorInfo`/border tokens derived via antd's built-in palette generation) replace the hardcoded value. `algorithm` still follows `isDark`.
4. **Expose a CSS variable** `--qwenpaw-brand-primary` (and a couple of companions) on `:root`, updated when the skin or resolved theme changes, so non-antd surfaces (`.module.less` files) can opt in gradually without a big-bang rewrite.
5. **UI**: add a compact skin picker (swatches) alongside the existing `ThemeToggleButton` in `Header.tsx`, reusing its dropdown pattern.
6. **i18n + tests**: add `theme.skin.*` strings to all locales; extend `ThemeContext.test.tsx` to cover skin persistence and token/CSS-variable application.
## Out of scope (intentionally)
- Free-form custom color picker / hex input (can be a follow-up).
- Full design-token refactor / migrating every hardcoded color (too large for one PR; the CSS variable is the enabler for a later incremental migration).
- Per-agent skins.
## Alternatives considered
- **A. Free-form custom colors** — more powerful, but bigger UI surface, more validation/i18n/testing, and maintainers may prefer a curated set. Better as a follow-up.
- **B. Token-only refactor (no user-facing feature)** — useful long-term, but doesn't satisfy the "configurable" intent of Task 1 on its own.
## Test plan
- Unit: `ThemeContext` persists/restores `skin`; selecting a skin updates the exposed tokens and `--qwenpaw-brand-primary`.
- Manual: switching skin visibly changes the brand color across the Console; light/dark/system still works independently; selection survives reload.
- No regression: default skin reproduces today's `#FF7F16` look exactly.
Happy to adjust the preset list, the CSS-variable naming, or the picker placement based on feedback.
Guida per i contributori
Apri la guida per i contributori
Direzione di ricerca
Start by reading console/src/contexts/ThemeContext.tsx, console/src/App.tsx, console/src/layouts/Header.tsx, and console/src/components/ThemeToggleButton/index.tsx to understand the existing light/dark flow. Then inspect ThemeContext.test.tsx and the locale files before deciding how the proposed skin state, tokens, CSS variables, picker, and translations fit together. Done means preset selection persists, changes the antd tokens and brand CSS variable, preserves light/dark/system behavior, and passes the context tests.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Valutazione
- Stack tecnologico
- react, typescript
- Ambito
- design, frontend, internationalization, testing
- Tipo di issue
- Funzionalità
- Difficoltà
- 4/5
- Tempo stimato
- 3-5 giorni
- Stato di attività
- Tranquilla
- Chiarezza
- Abbastanza chiara
- Idoneità per principianti
- 38/100