browser/platform_web/AGENTS.md

AGENTS.md for platform_web

This file applies to platform_web/.

Frontend Scope

Build the actual management console, not a marketing site. Required first-party areas are 首页、服务器管理、插件市场、用户管理、AI 提供商管理.

Structure Rules

Do not define API clients, shared DTOs, route definitions, schemas, or bridge contracts inside page components. Put them in dedicated directories.

Interaction Rules

Management list pages must keep the primary list, grid, or table as the full-width working surface. Do not add permanent right-side create/edit/detail panes or fixed left-list/right-form master-detail layouts for users, plugins, AI providers, servers, or similar management resources. Use modals, drawers, or detail routes for create, edit, and detail workflows unless a future OpenSpec change explicitly requires an inline split layout.

Visual Style Rules

The platform_web visual system is a game operations console, not a generic SaaS dashboard. The default theme is black mecha; the selectable alternate theme is magical-girl. Future UI work must preserve the current style contract:

• Use the shared theme tokens in theme/tokens.ts and shared styles in theme/base.css; do not add page-local opaque card systems, one-off dark dashboards, or unrelated visual languages.
• Keep major surfaces translucent enough for the selected desktop/background to remain visible: side navigation, account/profile controls, metric cards, console panels, server cards, server detail headers, tables, drawers, dialogs, plugin groups, and operation history.
• Preserve theme-specific materials: black mecha uses dark cockpit panels, angular clipped frames, cyan scanner lines, and amber energy accents; magical-girl uses pink jelly glass, gold star frames, ribbon glow, and visible magic-circle motifs.
• Theme changes must be isolated and complete. Switching from magical-girl to black mecha must clear previous magical variables and update root theme marker, sidebar subtitle, active navigation frame, swatch strip, and shared surface accessories together.
• Do not double-frame nested content. A .state-view inside an already framed shared parent such as a console panel, card, table wrapper, plugin group, or operation item is content only; the parent owns the visible border and accessory layer.
• Keep the primary menu as a compact admin sidebar with two states: expanded text menu and collapsed icon rail. Do not reintroduce the single-column / double-column menu toggle. The same route order should render as a restrained dark mecha operations rail in black mecha and as a semi-transparent pink frosted-glass rail with star-framed active states in magical-girl.
• Use components/MagicalParticleLayer.tsx for full-workspace theme-aware ultimate effects. Each theme should have a distinct low-cost “大招” scene, not a dense field of tiny rotating particles. Do not reintroduce hardcoded fixed decorative DOM/CSS elements such as page-local sparkles, hearts, moons, snowflakes, or sigils.
• Built-in backgrounds must stay original CSS/generated motif desktops. Do not bundle recognizable third-party character art. User-uploaded backgrounds are allowed and must render behind readable contrast overlays.
• Uploaded backgrounds take precedence over built-in desktop presets; the selected preset remains the fallback after the upload is removed.
• Non-dangerous commands may use theme-appropriate lucide icons. Destructive, failed, warning, and safety-critical operations must retain familiar warning/status iconography and text.
• Status, errors, operation results, logs, configuration diffs, and LLM review output must remain readable, traceable, and not color-only.
• Cards and framed repeated items should keep 8px-or-less radii unless a native control shape requires a pill or circle.

See theme/README.md before changing theme tokens, shared CSS surfaces, page chrome, account/theme settings, or background behavior.

Verification Rules

If a change touches UI pages or interactions, verify the key workflow in a browser before claiming acceptance.

For theme, frame, or uploaded-background changes, the browser walkthrough must include both directions of theme switching and must explicitly check that nested empty/loading/error states do not render a second border or accessory.