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

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