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

ADDED Requirements

Requirement: First-party routes provide accepted interaction polish

The platform_web console SHALL provide polished, scannable, API-backed interaction surfaces for the required first-party areas without changing product scope.

Scenario: Home route has clear operational hierarchy

• WHEN an operator opens 首页
• THEN the route MUST present loaded platform overview state, key resource/health signals, game/plugin counts or equivalent operational summaries, and a clear refresh or recovery affordance without visible overlap or clipped primary labels

Scenario: Server management route is action-oriented and scannable

• WHEN an operator opens 服务器管理
• THEN the route MUST make server identity, lifecycle state, run assignment, filtering, creation entry point, and drill-in affordance easy to scan without using a fixed left-list/right-detail master-detail layout

Scenario: Plugin marketplace route communicates trust and capability

• WHEN an operator opens 插件市场
• THEN the route MUST present plugin identity, installed state, manifest reference, lifecycle capabilities, platform-mediated permissions, bridge actions, and validation state in a readable structure without unsafe runtime transport details

Scenario: User management route supports account operations clearly

• WHEN an operator opens 用户管理
• THEN the route MUST present API-connected account data, roles/statuses, create/edit affordances, and empty/error/loading states with text labels and non-color-only status cues

Scenario: AI provider route keeps sensitive settings understandable

• WHEN an operator opens AI 提供商管理
• THEN the route MUST present provider identity, connection status, relay mode, model/default-model information, and redacted key references without exposing raw keys or making status dependent on color alone

Scenario: Management page counters stay secondary

• WHEN an operator opens 插件市场、用户管理, or AI 提供商管理
• THEN small summary counts such as installed plugins, bridge actions, validation failures, users, roles, pending reviews, providers, enabled providers, and models MUST render as compact contextual status instead of large framed KPI cards that displace the primary list, grid, table, search, or filter work surface

Requirement: Server detail workflows are polished without direct run access

The platform_web server detail route SHALL provide polished workflow surfaces for lifecycle, logs, config, plugin controls, AI assistant, and operation history while preserving platform-mediated boundaries.

Scenario: Server detail header and tabs show stable context

• WHEN an operator opens #/servers/server-local-debug or another server detail route
• THEN the route MUST keep server name, server ID, plugin version, run node, lifecycle state, and tab navigation visible and readable across desktop and mobile widths

Scenario: Lifecycle commands have safe feedback

• WHEN an operator views or triggers lifecycle controls
• THEN start/stop or equivalent controls MUST have clear labels, enabled/disabled states, confirmation or progress feedback where appropriate, and operation-history visibility without browser or plugin pages contacting run directly

Scenario: Logs, config, artifacts, and operation history remain traceable

• WHEN an operator uses detail tabs for logs, config, plugin controls, AI assistant, or operation history
• THEN each surface MUST show meaningful loaded/empty/error states, logical IDs or safe references, readable timestamps/statuses, and no raw host paths, sockets, credentials, or plugin-owned transport details

Requirement: Visual system contract is preserved during polish

The platform_web polish SHALL preserve the existing game operations visual direction and shared theme architecture.

Scenario: Shared theme primitives drive surfaces

• WHEN implementation changes route or component presentation
• THEN it MUST reuse or extend shared tokens/classes in theme/tokens.ts and theme/base.css rather than introducing page-local opaque card systems, one-off dark dashboards, or unrelated visual languages

Scenario: Black mecha and magical-girl themes stay distinct

• WHEN an operator uses the default black mecha theme or optional magical-girl theme
• THEN both themes MUST keep their theme-specific materials, readable translucent surfaces, grouped large-entry navigation, and background visibility while sharing the same product workflows

Scenario: Global decorative effects remain centralized

• WHEN implementation changes ambient or decorative effects
• THEN full-workspace theme-aware effects MUST remain in components/MagicalParticleLayer.tsx and MUST NOT use page-local fixed decorative DOM/CSS elements

Requirement: Responsive browser walkthrough proves polish acceptance

The polish change SHALL require browser verification across required routes and representative viewport sizes before completion.

Scenario: Desktop and mobile walkthroughs cover required routes

• WHEN implementation claims the polished UI is accepted
• THEN browser walkthrough evidence MUST cover 首页、服务器管理、插件市场、用户管理、AI 提供商管理, server detail workflows, and representative desktop and mobile viewport widths

Scenario: Walkthrough rejects layout regressions

• WHEN browser walkthroughs inspect accepted routes
• THEN they MUST reject visible overlap, clipped primary text, unreachable primary controls, unreadable loaded/error/empty states, and navigation states that hide required first-party areas

Scenario: Automated acceptance remains compatible

• WHEN polish implementation is complete
• THEN scripts/browser-acceptance.sh with the documented local debug environment MUST still pass and MUST continue proving API-backed content, fallback rejection, forbidden-fragment scanning, and platform-mediated plugin/server operation proof

Requirement: Polish verification commands are concrete

The OpenSpec tasks SHALL list reproducible commands that prove implementation quality.

Scenario: Verification commands are available

• WHEN contributors read implementation tasks
• THEN they MUST find concrete commands for platform_web typecheck/tests/build, automated browser acceptance, structure checks, and strict OpenSpec validation

Scenario: Evidence is recorded before task completion

• WHEN implementation tasks are marked complete
• THEN task evidence MUST record the browser walkthrough coverage, automated acceptance command output or evidence path, platform_web verification, scripts/check-structure.sh, and openspec validate polish-platform-interaction-design --strict