browser/openspec/changes/polish-platform-interaction-design/design.md

Context

The platform_web console already exposes the required first-party product areas and now has automated browser acceptance proving API-backed behavior across 首页、服务器管理、插件市场、用户管理、AI 提供商管理, server detail, and plugin controls. The next gap is not a new product capability; it is interaction quality. The console needs clearer hierarchy, denser-but-readable operational surfaces, stronger feedback, and responsive confidence while preserving its game operations visual contract.

This change should stay inside platform_web interaction and visual polish. It must not introduce new business workflows, billing/cloud host flows, provider marketplaces, direct run access, or plugin transport shortcuts. It should use existing API-backed data and existing route contracts.

Goals / Non-Goals

Goals:

• Turn UI dissatisfaction into objective acceptance criteria that implementation can complete and verify.
• Polish navigation, first-party route scanability, state feedback, command affordances, and server detail workflows.
• Keep the default black mecha console and optional magical-girl theme visually distinct while sharing the same layout and interaction model.
• Reuse theme/tokens.ts, theme/base.css, and shared surface classes before adding new styles.
• Require browser walkthrough evidence at desktop and mobile widths.
• Keep automated browser acceptance passing after polish.

Non-Goals:

• Do not change platform, run, plugin, AI provider, authorization, lifecycle, log, artifact, or config semantics.
• Do not add billing, cloud host sales, agent-provider/cloud-provider workflows, or unrelated SaaS marketplace features.
• Do not replace the visual direction with generic opaque SaaS cards, one-off dark dashboards, or unrelated gradients.
• Do not add page-local fixed decorative spans, sparkles, sigils, snowflakes, hearts, moons, or other one-off background DOM.
• Do not create a fixed left-list/right-detail master-detail layout for server or plugin details.
• Do not bundle third-party character art or recognizable external visual assets.

Decisions

1. Use accepted interaction criteria instead of taste-only language.

   Each polished page should have observable requirements: clear primary action, visible loaded/empty/error state, scannable hierarchy, no overlapping UI, readable status signals, responsive behavior, and preserved API-backed markers. This makes the implementation measurable in tests and browser walkthroughs.

2. Polish shared primitives first.

   The implementation should start with existing shared classes such as metric-card, overview-card, console-panel, catalog-card, server-card, server-detail-header, resource-table-wrap, provider-table-wrap, drawer-panel, confirm-panel, plugin-group, and operation-item. If a new reusable pattern is needed, it belongs in theme/base.css with token-driven styling, not inside page-local opaque card systems.

3. Preserve one route model across both themes.

   Black mecha and magical-girl should differ through tokens, frame treatments, materials, motifs, and MagicalParticleLayer, not through separate page implementations. The same route structure should remain usable and readable in both themes.

4. Favor operational clarity over decoration.

   Lifecycle actions, destructive confirmations, logs, diffs, config review, operation results, warnings, and AI recommendations must remain text-readable, traceable, and not color-only. Decorative theme effects must stay behind operational surfaces and respect reduced motion.

5. Use browser walkthroughs for acceptance, not screenshots alone.

   Completion requires exercising the actual routes and workflows in a browser at representative desktop and mobile widths. Screenshots can help debugging, but accepted evidence should focus on route behavior, visible controls, responsive layout, and absence of overlap or sensitive/fallback content.

Risks / Trade-offs

• Visual polish can drift into scope expansion -> Keep tasks limited to platform_web interaction and theme presentation; do not change platform/run/plugin semantics.
• Theme work can create duplicate styles -> Require shared token/classes first and update theme/README.md only when new shared patterns are introduced.
• Responsive polishing can break automated acceptance markers -> Require automated browser acceptance after changes.
• Dense game-console visuals can harm readability -> Require operational clarity for logs, tables, diffs, warnings, and command results.
• Browser checks can be flaky -> Use stable routes, loaded states, viewport checks, and the existing local debug acceptance command.

Migration Plan

1. Audit current first-party routes and server detail surfaces against the accepted interaction criteria.
2. Polish shared theme/layout primitives and route components in small focused batches.
3. Verify desktop and mobile browser walkthroughs across required routes and server detail workflows.
4. Run platform_web tests/build and automated browser acceptance.
5. Update task evidence and delivery stream pointers after verification passes.

Rollback is straightforward because the change should stay in platform_web presentation and interaction code. Revert affected styles/components if a polish pass harms usability or breaks acceptance.

Open Questions

• None currently. If implementation discovers a needed new product behavior, split it into a future OpenSpec instead of expanding this polish change.