# Design

## Overview

The platform web shell will support two first-party visual families:

- **黑色机甲**: default theme, dark tactical interface with angular frame lines, scanner glow, cockpit panels, and low-noise energy effects.
- **魔法少女**: selectable theme, pink moonlight menu treatment, rounded rail materials, stronger star-frame highlights, ribbons, and visible magic circles.

Both themes continue to use shared theme variables and shared CSS primitives. Page code should still reuse global shell and surface classes instead of adding page-local decoration.

## Theme Model

`theme/tokens.ts` will reduce the palette set to focused first-party palettes:

- `mecha-black`
- `magical-girl`

The default palette/background will become:

- `defaultThemePaletteId = "mecha-black"`
- `defaultThemeBackgroundId = "mecha-grid"`

The selectable magical-girl pairing will use:

- `magical-girl`
- `magic-stage`

Theme variables will include existing shared semantic tokens plus additional material tokens for theme-specific frames:

- `--frame-corner`
- `--frame-accent`
- `--menu-item-bg`
- `--menu-item-active-bg`
- `--menu-glyph-bg`
- `--ultimate-effect-alpha`

CSS selectors using `:root[data-theme-palette="..."]` can specialize shell/card materials while retaining shared class names.

## Navigation Structure

The shell menu will use the requested admin-sidebar reference structure:

- 平台概览
- 服务器管理
- 插件市场
- 用户管理
- AI 提供商管理
- 系统工具

Each group renders as a compact first-level sidebar item with:

- Icon rail affordance.
- Bold Chinese label.
- A collapsed icon-only state.
- An expanded full-label state.
- Active item frame.

Groups navigate directly to their first route. The shell includes a sidebar toggle that switches between a narrow icon rail and the full menu for the session.

## Particle Effects

`MagicalParticleLayer` will become theme-family aware:

- `mecha-black`: scanner sweeps, targeting rings, hex grid pulses, and energy-core arcs.
- `magical-girl`: large magic circle, star glints, ribbon sweep, and corner sparkle bursts with higher visibility.

The layer remains DOM-based, non-interactive, reduced-motion aware, and low-cost. It separates the full-workspace background image layer from the global particle layer. Page-local fixed decoration is still disallowed.

## Surface Treatment

Shared surfaces remain translucent enough to show the desktop background. Theme-specific differences:

- Mecha surfaces use dark panels, hard bevel lines, tactical grid overlays, clipped-corner accents, and cyan/amber status light.
- Magical surfaces use pink jelly glass, gold/pink star borders, magic-card active frames, rounded icon badges, and obvious moon/ribbon glow.

Repeated cards and panels keep radii at 8px or less unless they are native circular/pill controls.

## Documentation

Update `platform_web/AGENTS.md` and `platform_web/theme/README.md` to describe the new default black mecha style and optional magical-girl style.