68 lines
5.4 KiB
Markdown
68 lines
5.4 KiB
Markdown
## 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.
|