OrgTJWater/next-tjwater-drainage-frontend

Fork 0

Files

T

jiang 72850761ce feat: migrate drainage frontend to Vite

2026-07-22 12:47:36 +08:00

40 KiB

Raw Permalink Blame History

Immersive Drainage Network WebGIS Design

Overview

This product is an immersive command workspace for drainage network dispatch, simulation, and Agent-assisted decision making. The interface should feel like entering a live operational map, not browsing a dashboard or a marketing page.

The map is the primary canvas. Pipes, junctions, incidents, affected districts, scenarios, and Agent recommendations are the visual subject. UI panels exist to help the operator understand the situation, preview consequences, confirm actions, and roll back decisions. They must never compete with the spatial context.

The visual direction is restrained technical immersion:

Full-screen spatial workspace by default.
Clear operational hierarchy over decorative spectacle.
Light engineering map as the default canvas.
Acrylic command instruments with strong reading surfaces.
Blue as the primary action and selection color.
Green/cyan for normal network flow, orange for risk, red for incident and impact, purple only for model or Agent inference.
Motion used to explain spatial change, simulation progress, and recommended actions.

The design should be suitable for long daily use by dispatchers and engineers while still feeling modern, spatial, and intelligent.

Experience Principles

Map First

The first viewport is always the working map. Do not introduce a landing page, marketing hero, decorative splash screen, or card-heavy overview before the operator reaches the map.

The map must answer:

What is happening now?
Where is it happening?
Which assets, districts, and users are affected?
What actions are recommended?
What will change if an action is applied?

UI As Command Instruments

Panels, controls, and toolbars should feel like instruments floating over the map. They should be available when needed, collapsible when not needed, and positioned to preserve the operator's spatial awareness.

Fixed UI must avoid long-term obstruction of critical map objects. The map camera should reserve safe padding for open panels, especially during locate, fit bounds, and scenario preview operations.

Explain Before Acting

Agent and simulation features must expose a decision chain:

Detect or receive task.
Explain current evidence.
Recommend one or more actions.
Preview spatial and service impact.
Ask for confirmation.
Apply with progress feedback.
Offer rollback or audit trail.

Never let the Agent directly mutate map state or operational state without an explicit preview and confirmation path.

Dense, Not Crowded

This is a command workspace, so information density is expected. Density should come from compact typography, clear grouping, and predictable layout. It should not come from tiny illegible controls, overlapping surfaces, or excessive decoration.

Restraint Over Spectacle

The product may feel technical and immersive, but it should not become a generic "sci-fi dashboard." Avoid gratuitous glow, animated circuit lines, decorative gradients, 3D ornaments, and full-screen dark neon themes unless a future mode explicitly requires them.

Visual Language

Tone

The interface should feel:

Operational
Spatial
Calm under pressure
Trustworthy
Technically precise
AI-assisted but human-controlled

It should not feel:

Like a marketing site
Like a generic admin dashboard
Like a decorative data wall
Like a chat app with a map attached

Canvas

Use a light engineering-map canvas as the default environment. The map may use a real basemap, a vector tile basemap, or a fallback grid, but it should remain quiet enough for drainage-network layers to dominate.

Recommended canvas colors:

Token	Value	Use
`canvas-map`	`oklch(94.5% 0.012 250)`	Fallback map background
`canvas-map-grid`	`rgba(37, 99, 235, 0.06)`	Subtle engineering grid
`canvas-page`	`#f8fafc`	Non-map support pages
`acrylic-navigation`	Adaptive 68-82% cool-blue tint	Workbench top bar
`acrylic-panel`	Adaptive translucent cool-blue tint over active basemaps	Agent, conditions, menus and focused panels
`acrylic-control`	Adaptive clean cool-white tint with light blue edge	Toolbar, zoom, scaleline and standalone compact controls
`surface-control`	95-98% cool-white, no blur	Headers, inputs and compact controls inside acrylic shells
`surface-well`	28-34% cool-gray overlay, no blur	Conversation wells and empty support regions
`surface-reading`	97-99% white, no blur	Dense text, forms, tables and messages
`glass-transient`	Adaptive 56-72% cool-blue acrylic	Active task ticker only

Color System

Core UI Colors

Token	Value	Use
`action-blue`	`#2563eb`	Primary actions, selected tools, active scenario
`action-blue-hover`	`#1d4ed8`	Hover and pressed primary action
`action-blue-soft`	`#dbeafe`	Selected background, low-emphasis active state
`ink`	`#0f172a`	Primary text
`ink-secondary`	`#334155`	Secondary labels and values
`ink-muted`	`#64748b`	Descriptions, metadata
`ink-disabled`	`#94a3b8`	Disabled controls
`border-soft`	`oklch(90.5% 0.009 250)`	Dividers and nested groups
`border-strong`	`oklch(86.5% 0.012 250)`	Floating surface border

Operational Colors

Token	Value	Use
`network-major`	`#0477bf`	Major pipes, DN600 and above
`network-medium`	`#0aa6a6`	Medium pipes, DN300-DN600
`network-minor`	`#3dbf7f`	Minor pipes, below DN300
`network-closed`	`#9ca3af`	Closed or inactive assets
`demand-low`	`#70c1b3`	Low demand junctions
`demand-medium`	`#247ba0`	Medium demand junctions
`demand-high`	`#f25f5c`	High demand junctions
`risk`	`#ff7a45`	Risk preview, warning glow
`incident`	`#ef4444`	Burst, outage, critical impact
`success`	`#22c55e`	Improved scenario, completed action
`agent`	`#7c3aed`	Agent/model inference only

Color must carry meaning. Do not use orange, red, green, or purple as decoration.

Typography

Use a system font stack that performs well for Chinese and English operational UI:

font-family: -apple-system, BlinkMacSystemFont, "SF Pro Text", "Segoe UI",
  "PingFang SC", "Noto Sans SC", "Microsoft YaHei", sans-serif;

Avoid negative letter spacing. This product should optimize for scanning dense operational data, not editorial display styling. Use tabular numbers for time, counters, coordinates and changing measurements.

Token	Size	Weight	Line Height	Use
`title-lg`	24px	600	1.25	Rare page or mode title
`title-md`	18px	600	1.35	Panel title
`title-sm`	16px	600	1.35	Section title
`body`	14px	400	1.55	Default UI text
`body-strong`	14px	600	1.45	Important labels and values
`caption`	12px	400	1.45	Metadata, descriptions
`caption-strong`	12px	600	1.35	Status labels, compact headers
`metric`	24px	600	1.1	Key numeric metric
`map-label`	12-14px	600	1.2	Map labels with halo

Use large display typography sparingly. In the command workspace, oversized headings waste spatial context.

Spacing

Use a 4px base unit with 8px as the main layout rhythm.

Token	Value	Use
`space-1`	4px	Micro gaps
`space-2`	8px	Control gaps
`space-3`	12px	Compact groups
`space-4`	16px	Panel padding
`space-5`	20px	Large panel padding
`space-6`	24px	Major groups
`space-8`	32px	Panel separation

Prefer compact layouts with predictable alignment. Do not nest cards inside cards unless the inner card is a repeated data item or a modal-like focus surface.

Radius

Token	Value	Use
`rounded-sm`	2px	Tiny state markers and very small swatches
`rounded-lg`	8px	Icon cells and compact visual anchors
`rounded-xl`	12px	Standard rows, readable blocks, compact controls, toolbar rails
`rounded-2xl`	16px	Major floating panels and toolbar function panels
`rounded-full`	9999px	Status pills, avatars, scenario chips

Rounded corners should imply function. Do not make every object pill-shaped.

Use a clear radius hierarchy over the map:

Major floating panels, including toolbar function panels, header dropdown menus, result panels, simulation panels, and feature detail popovers, use rounded-2xl.
Readable content blocks inside a major panel use rounded-xl.
Standard row buttons and compact control shells use rounded-xl.
Icon cells use rounded-lg, so they feel related to row buttons without becoming pill-like.
Always-visible compact instruments such as toolbar rails, zoom, floating basemap controls, and scaleline use rounded-xl.
Avoid arbitrary radius utilities such as rounded-[14px] unless a map-specific geometry requires a one-off value. Prefer Tailwind's default radius scale so inner and outer corners remain visually compatible.

Elevation

Elevation communicates operational hierarchy through adaptive acrylic outer shells, high-opacity reading surfaces and restrained shadows. The map may influence empty shell regions, but roads and satellite texture must not remain legible beneath operational text.

Surface Tokens

Tailwind owns layout and state. Global semantic classes own surface color, border and elevation. Do not reproduce their values inside components.

Class	Background	Intended use
`acrylic-navigation`	68% on light, 82% on satellite	Workbench top bar, blur 20-24px
`acrylic-panel`	Translucent cool-blue tint on light and satellite	Agent, conditions, menus, notices and focused popovers, blur 20-24px
`acrylic-control`	78% on light, 90% on satellite	Toolbar, zoom, scaleline and standalone compact controls, blur 16-20px
`surface-control`	95-98%, no blur	Headers, inputs and controls inside acrylic shells
`surface-well`	34% on light, 28% on satellite	Conversation wells and low-density empty regions
`surface-reading`	97-99%, no blur	Messages, reports, forms, tables and properties
`glass-transient`	56% on light, 72% on satellite	Active task ticker, blur 16-20px

Semantic classes are material-tone-info, material-tone-normal, material-tone-warning, material-tone-danger, and material-tone-agent. They communicate state only, never hierarchy, and never apply blur.

Component Mapping

Component category	Surface token
Workbench top bar	`acrylic-navigation`
Agent command shell and collapsed rail	`acrylic-panel`
Conversation background	`surface-well`
Zoom, toolbar and scaleline	`acrylic-control`
Inputs and internal headers	`surface-control` or `surface-reading`
Tool panels, conditions, menus, notices and popovers	`acrylic-panel`
Messages, reports, tables and property blocks	`surface-reading`
Active task ticker	`glass-transient`
Ticker stack cards	`surface-control`

The task ticker is always centered against the full viewport, independent of Agent or scheduled-condition panel widths. Hide it while the scheduled-condition detail is expanded instead of shifting it away from center.

Composition And Performance

Apply backdrop-filter only to the outermost acrylic shell. Descendants must use non-filtered surface classes.
Keep the acrylic shell as the first composited visual layer above the map. Positioning ancestors must not retain transform, filter, opacity, isolation or will-change: transform; presence motion belongs on the acrylic shell itself and must leave no persistent compositor hint after it settles.
Scheduled conditions use acrylic-panel only for the outer shell. Internal headers, filters, timeline rows, detail reports and KPI blocks use non-filtered content surfaces (surface-control or surface-reading) so the panel has one acrylic layer and readable upper content.
The acrylic recipe is blur plus controlled backdrop saturation, a cool tint, a luminosity layer, a low-opacity exclusion layer and fine monochrome noise. Blur and tint alone are only frosted glass and do not satisfy this contract.
Follow Microsoft Fluent acrylic principles: tint, blur, noise and layer purpose create the material. Do not use gray or muddy color casts to make glass feel deeper.
Acrylic regions may coexist only when they do not overlap. Tool panels replace the condition panel instead of stacking over it.
Floating acrylic panels use a translucent edge, an inset top highlight and one restrained shadow.
Light, satellite and no-basemap modes adjust acrylic opacity through data-basemap-tone; they do not alter component markup.
Separate adjacent regions with dividers or background steps instead of nested cards.
Use semantic color only for status, selection, device type or Agent inference.
Under prefers-reduced-transparency: reduce, all acrylic and glass surfaces become 98% opaque and remove blur.
Browsers without backdrop-filter support use the same high-opacity fallback.
Maintain WCAG AA contrast against the declared reading surface.

CSS Token Contract

src/styles.css is the single source of truth for surface values. src/features/workbench/layout/workbench-layout.ts is the single source for dock, condition, toolbar and ticker geometry used by both the rendered shell and map camera padding.

Motion

Motion should make operational change understandable.

Use motion for:

Locating an asset on the map.
Previewing affected areas.
Playing simulation time.
Expanding or collapsing command panels.
Showing Agent action preview and confirmation state.
Drawing attention to new incidents or warnings.

Avoid motion for:

Decorative background movement.
Constant pulsing on non-critical objects.
Large parallax effects.
Slow transitions that delay dispatch work.

Recommended durations:

Token	Duration	Use
`fast`	120-160ms	Button, hover, small controls
`normal`	180-260ms	Panel expand/collapse
`map-camera`	500-700ms	Fit bounds, locate feature
`simulation-step`	300-500ms	Time-step change

Workbench panel motion should use 180ms as the default speed when the component changes structural state, such as showing, hiding, expanding, collapsing, or changing columns. Use cubic-bezier(0.22, 1, 0.36, 1) for entrance and expansion, and cubic-bezier(0.5, 0, 0.2, 1) for exit. Keep micro-interactions such as hover states, row highlights, icon rotation, and compact button feedback at about 150ms.

For detail content that appears after a structural panel transition starts, use a short fade of about 140-150ms with no long delay. A delay around 60ms is enough for the content to feel attached to the layout motion; avoid waiting until the full panel transition is finished unless the content would otherwise overlap or jump.

Toolbar function panels should use a fast, quiet entrance and exit: fade in/out, move 4-8px from the tool rail, and optionally scale between 0.95-1. Keep the animation around 150ms so tool switching feels responsive.

Scaleline motion should stay informational. Only the internal scale bar width may transition over about 120-200ms; do not animate the outer auto-sized container or coordinate text.

For panels that expand from a compact list into a detail workspace, use the Collapsible Detail Panels pattern below: animate structure first, then reveal detail content after layout is stable.

Immersive Layout Model

Primary Regions

The workspace should be composed from five persistent regions:

Region	Role	Behavior
Map Canvas	Primary spatial context	Always visible, full viewport
Command Top Bar	System state	Thin, acrylic, status-oriented
Agent Command Panel	Reasoning and recommended actions	Left side, collapsible, task-focused
Analysis / Layer Rail	Tools, layers, results	Right side, icon-first, panels open on demand
Simulation Timeline	Scenario time and playback	Bottom dock, visible during simulation

Command Top Bar

The top bar is a status strip, not a marketing header.

It should contain:

Product or workspace mark.
Current data time.
Model or scenario version.
Active scenario.
Alert count and severity.
User/session controls.

It should not contain:

Large page title.
Promotional copy.
Decorative hero content.
Navigation unrelated to the current operation.

Recommended height: 56-68px.

Dropdown menus opened from the top bar behave as floating panels, not compact controls. Use rounded-2xl for the outer menu, rounded-xl for readable menu header blocks and rows, and rounded-lg for icon cells.

Collapsible Detail Panels

Use this pattern for persistent map instruments that start as compact lists and expand into a wider inspection surface.

Keep the compact state focused on the primary thing the operator is already scanning. Hide secondary groups until expanded if they would distract from the compact task.
Preserve the primary list DOM and scroll container across collapse and expansion. Do not replace a collapsed list with a separate expanded list if the user is expected to continue reading the same records.
Expand by changing shell width and internal column widths, not by pushing content vertically into place.
Delay detail content entrance until the width transition is complete. A short fade is acceptable after the layout is stable; vertical slide-in for dense text is not.
Keep the list column width and row typography consistent between collapsed and expanded states unless the task changes substantially.
The expanded state may add a left or right detail region, but the list should remain in a predictable position so selection context is not lost.

Agent Command Panel

The Agent panel is the main decision companion. It should make the Agent auditable and controllable.

On desktop, the Agent panel is a floating left-side instrument with 12px left, 96px top and 16px bottom offsets. Use 460px from 1280px through 1535px and 500px at 1536px and above. Below 1024px it becomes the existing single primary mobile panel.

The Agent panel is a persistent command instrument, so its outer shell should use the same control surface family as the map toolbar, zoom control, and scheduled-condition panel. It is not a low-opacity temporary glass panel.

Agent region	Surface	Use
Outer floating shell	`acrylic-panel`	Persistent command region with adaptive opacity and one outer blur
Header and action bands	`surface-control`	Quiet organizing bands
Conversation well	`surface-well`	Low-density scroll area behind messages
Message and recommendation surfaces	`surface-reading`	Assistant messages and primary readable content
Nested evidence/tool result blocks	`surface-control` or `surface-reading`	Choose by text density
Prompt input and secondary controls	`surface-reading`	Stable text-entry contrast
Active confirmation surface	warning tone	Agent action review and confirmation state

Keep the conversation well visibly darker than the reading surfaces. Operational text must never sit directly on the map or on a translucent layer.

Collapsed Agent state is a floating 72px compact instrument that keeps the Agent identity and expand action. Expanding and collapsing uses a short 150-180ms reveal with opacity and a small horizontal translation. The map updates padding without animating business layers.

Required sections:

Current task or operator prompt.
Evidence summary.
Step-by-step reasoning or plan.
Recommended actions.
Preview controls.
Confirmation controls.
Conversation or command input.

Empty Agent conversations use a centered readiness introduction with one identity mark and a compact 2-by-2 capability summary. Keep suggested questions in their existing action strip above the prompt input instead of turning capability cards into duplicate actions. The identity mark may use a slow orbit and low-amplitude core breathing animation, but it must become static under reduced-motion preferences.

Agent recommendation cards should show:

Action name.
Target assets or area.
Expected effect.
Risk or confidence.
Primary action: preview.
Secondary action: inspect details.

The Agent should use purple only for model identity or inference metadata. Primary operational action buttons should remain blue.

Scheduled Condition Panel

The scheduled-condition panel is a persistent right-side command instrument for live operational tasks. It should visually belong to the same family as the toolbar, zoom control, and Agent shell, not to temporary tool panels.

Use the adaptive acrylic outer-shell contract while preserving the established collapsible-detail geometry:

Outer shell: acrylic-panel in both states.
Outer radius: rounded-2xl, because the component reads as a major floating panel even when collapsed.
Header and compact controls: surface-control. Detail and report content: surface-reading.
Icon cells: rounded-lg, matching toolbar icon cells.
Rows and compact controls: rounded-xl.
Detail content blocks: rounded-xl where the block carries multi-line text or structured details.

Collapsed state:

Preserve the existing 432px compact width.
Keep the compact width list-focused, with enough height to reveal roughly six recent rows before scrolling.
Show recent conditions only. Do not show scheduled work orders in the collapsed state; they are secondary to the compact scanning task.
The header should reflect the compact content, such as recent-condition count. Avoid advertising hidden scheduled-work content unless the expanded state is open.
Use the same timeline row component and scroll container that the expanded state uses, so the operator does not lose list position when expanding.
Row text should use compact 12px typography, with time on the left, status on the right, and a visible timeline marker for temporal scanning.

Expanded state:

Preserve the existing 880px width and 960px width at 1536px and above.
Add a separate detail region beside the timeline list. The detail region may use the newly available horizontal space for evidence, Agent analysis, recommended options, and operational metadata.
Keep the timeline list column width and row typography close to the collapsed state. The list should feel like the same instrument after expansion.
Show scheduled work orders as a separate compact group above recent conditions only in expanded state. If there are many work orders, keep that group scrollable and height-limited.
Recent conditions sort newest to oldest. Today scheduled work sorts by start time.
Detail panel height should be content-driven within viewport limits; avoid large empty areas.

Details:

Historical condition details may include evidence, Agent recommendation, model/session metadata, risk, duration, and a continue-conversation action.
Running condition details should be compact. The continue-conversation action is disabled until the task completes.
Scheduled work orders are operational work details, not Agent sessions. Do not show model, session, Agent recommendation, or evidence chain for work orders.
Work orders should show start time, estimated duration, computed end time, work content, execution mode, and due-time action.

Behavior:

Hide the scheduled-condition panel when a right-side tool panel opens or when the operator performs a workspace action that would conflict spatially.
Mobile v1 should not show this panel unless a dedicated compact pattern is designed.
Show and hide the whole panel with a short instrument transition from the toolbar side: opacity, slight horizontal/vertical translation, and very small scale change at 180ms.
Collapse and expand the internal detail layout with a smooth width or grid-column transition around 180ms. Reveal detail content only after the layout has settled.

Analysis Panel

The analysis panel presents results of simulations, incidents, and selections.

For incident impact, prioritize:

Affected households.
Affected districts.
Critical assets.
Estimated recovery time.
Valves or pipe segments involved.
Confidence or data freshness.

Metric cards should be compact and comparable. Use one large numeric value, one short label, and one optional trend/status indicator.

Layer And Tool Rail

The tool rail should be icon-first and compact. Common tools stay visible; low-frequency tools go behind a menu.

Recommended persistent tools:

Layers
Measure
Analysis
Annotation
Locate/search
More

Each icon button must have aria-label and a tooltip. Active state must be visually obvious through color and background, not only by icon color.

Map Core Controls

Reusable controls under src/features/map/core/components should share one compact map-instrument language.

Control Surface

Zoom, toolbar, scaleline, and other always-visible map controls should use the control elevation level:

Surface: use acrylic-control for the outer instrument and solid internal buttons.
Edge: 1px cool-gray boundary.
Shadow: the shared restrained acrylic instrument shadow.
Backdrop blur: apply only to the outer control shell, never to its internal buttons.
Radius: rounded-xl for grouped controls; rounded-lg for internal icon buttons.
Do not stack a second shell around toolbar, zoom, Agent shell, or scheduled-condition shell.

Use semantic surface classes for hierarchy. Tailwind opacity utilities remain appropriate for transient hover and selected-state color, not for defining persistent surfaces.

Zoom Control

The zoom control should remain a small vertical instrument:

Width around 46px.
Icon buttons around 38px.
Buttons are flat and visually consistent.
Do not show zoom readout unless a future workflow explicitly needs it.
Use short centered horizontal separators between buttons.
Button hover uses a soft blue background and subtle ring; do not add per-button lift shadows.
The whole control, not each button, carries the elevation.

Tool Rail

The map toolbar should follow the same visual system as zoom:

Vertical rail width around 46px; horizontal rail uses the same button size.
Icon-only buttons, with aria-label and tooltip.
Use short centered separators: horizontal dashes for vertical rails, vertical ticks for horizontal rails.
Default buttons are flat; hover uses soft blue background and subtle ring.
Active tools use blue fill with white icon/text and no heavy shadow.
Badges may use red only for operational alerts or counts that require attention.
The rail shell uses acrylic-control and should not sit inside another elevated panel.

Opening a tool rail panel should not move the map camera by default. Treat tool panels as floating overlays unless they become persistent major panels that materially obstruct map work.

When a tool rail panel opens, closes, or changes active tool, animate the panel as a short instrument reveal or dismissal from the rail side. Use opacity, slight horizontal translation, and a very small scale change only; avoid large sliding drawers.

Layer And Basemap Panel

Layer visibility and basemap selection belong together in the Layers tool panel:

Business layer visibility appears first.
Basemap selection appears below business layers.
Toolbar function panels use acrylic-panel for the outer shell.
Internal list rows, panel headers, swatches, result blocks, and action rows use surface-reading or a flat divider layout.
MVT sources should keep bounds where available to avoid invalid tile requests. This must not be confused with map view extent; the map view itself should remain unrestricted unless a workflow explicitly requires a view constraint.

Scaleline

The scaleline should read as a map instrument, not a dashboard footer:

It may retain technical metadata such as zoom, projection, coordinates, and attribution when useful.
Width should be content-driven, not fixed.
When positioned at the bottom-right edge, it may touch the viewport edge directly.
If touching the bottom-right edge, only the top-left corner should be rounded.
Use the same acrylic-control surface as toolbar and zoom so the bottom-right instrument cluster reads as one family.
Coordinate readout should match the displayed projection. If the scaleline labels EPSG:3857, prioritize visible projected X/Y; longitude and latitude may remain as secondary debug context, not the primary readout.
Use only a short, smooth transition for the internal scale bar width. Keep metadata widths stable; do not animate the outer auto-sized container or coordinate text.

Simulation Timeline

The timeline appears when simulation or replay mode is active.

It should include:

Current simulation time.
Play/pause.
Previous/next step.
Speed.
Scenario selector.
Comparison summary.
Export/report action.

The timeline should read as a control deck over the map, not as a separate dashboard section.

Clicking or hovering a pipe, junction, valve, or district should open a compact spatial popover.

It should include:

Object type.
Object name or id.
Key status.
3-5 most important attributes.
Related actions such as locate, inspect, isolate, add to scenario, or ask Agent.

Do not open a large side panel for every selection unless the operator explicitly asks for details.

Map Layer Semantics

Pipes

Pipe color represents category or operational state. Width represents diameter or importance.

Pipe State	Color	Guidance
Major pipe	`network-major`	Strong blue, highest visual weight
Medium pipe	`network-medium`	Cyan/teal
Minor pipe	`network-minor`	Green
Closed pipe	`network-closed`	Muted gray
Hover/selected	Dark ink overlay or blue halo	Must remain legible over all basemaps
Risk preview	`risk` glow	Temporary, tied to preview state

Junctions

Junctions should remain smaller than pipes unless selected or critical. Use halo and stroke to preserve visibility.

Demand intensity may use a green to blue to red ramp:

Low: demand-low
Medium: demand-medium
High: demand-high

Incidents And Impact

Incidents require the strongest visual hierarchy.

Burst point: red point with white or pale red halo.
Impact area: red fill at low opacity, red dashed or solid outline.
Critical label: red text or red halo only where necessary.
Warning preview: orange glow, not red, until confirmed as an incident.

Red should be reserved for confirmed critical state. Overuse of red will reduce emergency legibility.

Labels

Map labels must remain readable on both basemap and fallback grid.

Use:

White halo for dark text.
Blue halo for white pipe labels.
12-14px text.
Overlap only for critical incident labels.

State Modes

The workspace should have clear visual modes.

Normal Mode

Purpose: monitor and inspect.

Light map canvas.
Network colors visible but calm.
Panels minimized or compact.
No persistent warning animation.

Alert Mode

Purpose: respond to active anomaly or incident.

Top bar alert indicator becomes prominent.
Related asset and area are emphasized.
Agent panel may open with incident context.
Red appears only around confirmed critical objects.

Simulation Mode

Purpose: compare future or hypothetical outcomes.

Bottom timeline appears.
Scenario chips become visible.
Simulation layers and impact overlays are enabled.
The user can scrub, pause, compare, and export.

Agent Preview Mode

Purpose: inspect an action before confirmation.

Proposed affected assets are highlighted.
Expected impact is shown as temporary overlay.
Confirmation controls become visible.
Existing operational state remains distinguishable from preview state.

Confirmation Mode

Purpose: prevent accidental operational change.

Use a focused confirmation surface.
Summarize action, target, impact, risk, and rollback availability.
Require explicit confirmation for destructive or irreversible actions.

Component Guidelines

Buttons

Primary buttons:

Blue fill.
White text.
40-44px height for important actions.
Used for confirm, preview, run simulation, export report.

Secondary buttons:

White or cool-gray solid fill.
Blue or slate text.
Border or subtle ring.
Used for inspect, cancel, locate, details.

Danger buttons:

Red only for destructive or emergency actions.
Must include confirmation for operational changes.

Icon buttons:

Prefer lucide icons.
Minimum 32px target; 40px for important map tools.
Always include accessible label and tooltip.

Cards

Cards are for repeated data items, metrics, recommendations, and compact summaries. Do not use cards as generic page sections.

Metric card structure:

Label.
Value.
Unit.
Optional trend/status icon.

Recommendation card structure:

Recommendation title.
Target.
Expected effect.
Risk/confidence.
Preview action.

Inputs

Inputs should be compact and command-oriented.

Use inputs for:

Agent prompt.
Asset search.
Scenario name.
Numeric simulation parameters.

Do not make the Agent input visually dominate the workspace. It is one command path, not the product itself.

Badges And Pills

Use pills for:

Status.
Severity.
Scenario.
Data freshness.
Model version.

Avoid pill-shaped decoration with no operational meaning.

Accessibility And Readability

Text on glass panels must pass practical contrast against busy map backgrounds.
Increase panel opacity when content density increases.
Do not rely on color alone; pair color with icon, label, shape, or position.
Maintain visible focus states for keyboard use.
Important controls should be reachable with predictable tab order.
Use aria-label for icon-only controls.
Avoid truncating critical identifiers without tooltip or detail access.

Responsive Behavior

Desktop Command Workspace

Default target: desktop and large tablet.

Full map remains visible.
Left Agent panel and right analysis/tool panel may be open simultaneously.
Bottom timeline appears in simulation mode.
Map camera respects open panel padding.

Medium Screens

Right analysis panel should collapse into tool rail.
Agent panel may become narrower or overlay on demand.
Timeline should reduce secondary controls behind menus.

Small Screens

Small screens are supported for inspection and lightweight response, not full dispatch.

One major panel open at a time.
Tool rail becomes bottom or side compact controls.
Timeline controls simplify to play/pause, current time, and scenario.
Avoid dense side-by-side metric grids.

Do's And Don'ts

Do

Make the map the first and strongest visual signal.
Use floating panels as operational instruments.
Preserve spatial context during Agent and simulation workflows.
Use red only for confirmed critical state.
Use orange for risk preview and warning state.
Keep typography compact and readable.
Use motion to explain spatial or temporal change.
Give every Agent action a preview and confirmation path.

Don't

Do not build a landing page as the first screen.
Do not use Apple-style product tiles, product photography, or oversized marketing typography.
Do not use decorative gradients, glowing ornaments, or animated backgrounds as a substitute for information hierarchy.
Do not let the Agent mutate state invisibly.
Do not bury map controls inside generic cards.
Do not use colors without operational meaning.
Do not allow fixed panels to permanently cover critical map areas.
Do not make the UI so transparent that text becomes hard to read.

Design Review Checklist

Use this checklist for future UI changes:

The map is visible and useful in the first viewport.
The main task can be understood within three seconds.
Critical incident, warning, normal, and preview states are visually distinct.
Open panels do not hide the target area without camera compensation.
Agent recommendations include evidence, preview, confirmation, and rollback/audit path.
Primary actions use blue unless they are destructive.
Red is reserved for confirmed incident or destructive action.
Text is readable over the map at desktop and mobile widths.
Icon-only controls have labels and tooltips.
Motion helps the user understand change.
No component adds decorative chrome without operational value.

Implementation Guidance

The codebase should eventually align to this document rather than letting current prototype components define the design language.

Recommended implementation direction:

Keep route files thin and move feature UI into src/features/workbench, src/features/map/core, and src/features/agent.
Keep adaptive acrylic shells and non-filtered reading surfaces behind shared semantic classes instead of repeating raw material values.
Keep MapLibre sources, layers, camera behavior, and interactions outside presentational React components.
Define operational colors as shared constants for both map layers and UI legends.
Treat Agent actions as typed data that the workbench can preview, validate, confirm, apply, and roll back.

Component Library Strategy

Use a headless or primitive component approach rather than adopting a fully styled application component library as the product's main UI system.

Recommended stack:

Use Radix UI primitives for accessibility, keyboard behavior, focus management, portals, menus, dialogs, tooltips, selects, accordions, and other reusable interaction patterns.
Use shadcn/ui-style copied components as a starting point when useful, but treat the copied source as project-owned code that must be restyled to this document.
Use Tailwind CSS and shared design tokens for the visual layer. Prefer Tailwind default classes for radius, type scale, spacing, opacity, shadows, and semantic UI colors. Keep explicit color strings only where the platform API requires them, such as MapLibre paint values, runtime dynamic styles, syntax-highlighting variables, or rare audited opacity cases that Tailwind defaults cannot express clearly.
Use lucide-react for iconography unless a domain-specific map symbol requires custom drawing.
Use headless engines for complex behavior when appropriate, such as TanStack Table for sortable, filterable, selectable operational tables.

Do not use MUI, Ant Design, Mantine, Chakra, or another fully styled component suite as the primary component library. Their default visual systems, spacing, radius, elevation, and layout assumptions conflict with the map-first command workspace and would require broad overrides.

Target component layering:

src/shared/ui
  Base typed controls built on Radix primitives, shadcn-style source, Tailwind tokens, and project-specific variants.

src/features/map/core/components
  Reusable map instruments such as toolbar, zoom, scaleline, layer panel, measure panel, annotation panel, and legend.

src/features/workbench/components
  Water-network workbench components composed from shared UI and map core controls.

src/features/agent/components
  Agent-specific command, message, permission, preview, and UIEnvelope surfaces composed from shared UI.

The goal is to avoid repeating interaction and accessibility work while keeping full control over the visual language defined here.

工况详情状态强调

生命周期和风险等级是独立语义：完成、执行中属于生命周期，正常、关注、高风险属于风险等级，二者不得通过同一套容器色相互继承。状态必须同时包含文字或图标，且只在最有用的层级表达一次。

禁止使用彩色侧边条、整卡状态底色和继承式彩色圆点。正常状态保持中性，仅用小型绿色完成标识表达生命周期结束；关注和高风险只在直接表达风险的徽标、图标或 KPI 表面使用橙色和红色。

完成报告按标题、生命周期徽标、结论、时间、关键指标和报告章节的顺序组织。报告、判断摘要和章节使用中性容器及列表符号，KPI 保留业务原始顺序，并以中性、浅橙、浅红表面对应正常、关注、高风险。

任务步骤只按流程状态着色：当前蓝色，完成绿色，待处理灰色，待人工确认橙色。主要操作使用蓝色，提交完成后使用绿色。

Known Open Decisions

Dark mode is not specified in this version. A future night-operations mode should be designed deliberately rather than generated by inverting colors.
Brand identity, logo, and exact Chinese product name are not finalized here.
Mobile dispatch workflows need product decisions before becoming a full design spec.
Real operational approval, audit, and rollback requirements should be validated with stakeholders before implementation.

40 KiB Raw Permalink Blame History