next-tjwater-drainage-frontend/DESIGN.md

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.
• Floating translucent command surfaces with strong readability.
• 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:

1. Detect or receive task.
2. Explain current evidence.
3. Recommend one or more actions.
4. Preview spatial and service impact.
5. Ask for confirmation.
6. Apply with progress feedback.
7. 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	#eaf1f8	Fallback map background
canvas-map-grid	rgba(37, 99, 235, 0.06)	Subtle engineering grid
canvas-page	#f8fafc	Non-map support pages
canvas-panel	rgba(255, 255, 255, 0.76)	Default floating panel
canvas-panel-strong	rgba(255, 255, 255, 0.92)	Dense text or form surface
canvas-panel-soft	rgba(255, 255, 255, 0.58)	Low-density spatial overlay
surface-overlay	rgba(255, 255, 255, 0.72-0.86)	Floating menu or compact popover shell
surface-readable	rgba(255, 255, 255, 0.90-0.96)	Readable rows, menu headers, and content blocks inside translucent shells
surface-map-control	rgba(255, 255, 255, 0.92)	Always-visible and persistent map instruments: toolbar, zoom, scaleline, Agent shell, scheduled-condition shell
surface-tool-panel	rgba(255, 255, 255, 0.78)	Toolbar function panel outer shell

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	rgba(255, 255, 255, 0.62)	Glass panel border
border-strong	rgba(148, 163, 184, 0.34)	Dense control 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: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont,
  "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;

Avoid negative letter spacing. This product should optimize for scanning dense operational data, not editorial display styling.

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 should communicate interaction depth over the map.

Level	Treatment	Use
map	No shadow	Basemap and business layers
control	White 90-96%, soft border, small shadow	Zoom, basemap, tool buttons, persistent command shells
panel	White 58-82%, backdrop blur, blue-gray shadow	Toolbar function panels, temporary result panels, layer panels
focus	White 92-98%, stronger border and shadow	Popover, confirmation, detailed forms
modal	Scrim plus focused surface	Destructive or irreversible decisions

Recommended shadows:

• control: 0 14px 34px rgba(15, 23, 42, 0.18)
• panel: 0 24px 70px rgba(30, 64, 115, 0.20)
• focus: 0 30px 90px rgba(15, 23, 42, 0.26)

Use backdrop-filter: blur(20px) only where the panel remains readable. If the map beneath is visually busy, increase surface opacity instead of increasing blur.

Transparency Layering

Use consistent opacity tiers for floating UI over the map:

• Outer shells such as dropdown menus, compact popovers, and temporary command surfaces should use surface-overlay around rgba(255, 255, 255, 0.72-0.86).
• Persistent command instruments that remain visible while the operator works, such as the Agent shell and scheduled-condition shell, should use surface-map-control at rgba(255, 255, 255, 0.92) rather than a low-opacity panel shell.
• Inner readable content such as menu headers, selectable rows, status groups, and form blocks should use surface-readable around rgba(255, 255, 255, 0.90-0.96).
• Dense text, destructive confirmations, and detailed forms may use canvas-panel-strong around rgba(255, 255, 255, 0.92) when legibility matters more than map transparency.
• Do not put long text directly on a low-opacity shell. Give it a local readable surface, or increase the shell opacity.
• Keep readable content at least as opaque as its surrounding shell. Labels, values, and commands should sit on the more readable layer, not directly on a lower-opacity shell.

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, translucent, 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 may be wider than a utility side panel because it carries the auditable decision chain. Use a preferred width around 460px, with room to expand up to about 520px on wide command workstations when the map camera reserves matching left padding. Do not widen it on medium or small screens; there it should become narrower or overlay on demand.

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 surface	Opacity	Use
Outer shell	rgba(255, 255, 255, 0.92)	Main floating panel, collapsed rail, and mobile entry. Reuse the map control surface treatment: soft white border, compact control shadow, subtle dark ring, and backdrop blur.
Header, context strip, action tray, input band	rgba(255, 255, 255, 0.96)	Persistent readable bands that organize the command surface.
Conversation well	rgba(255, 255, 255, 0.34)	Low-density scroll area behind messages. Do not place text directly on this layer.
Message and recommendation surfaces	rgba(255, 255, 255, 0.94)	Assistant messages, recommendation groups, and primary readable content.
Nested evidence/tool result blocks	rgba(248, 250, 252, 0.90)	Evidence tiles, tool run rows, and compact structured outputs inside messages.
Prompt input and secondary controls	rgba(255, 255, 255, 0.96)	Text entry, secondary buttons, and controls that need crisp hit targets.
Active confirmation surface	rgba(255, 247, 237, 0.96)	Agent action review and confirmation state.

Do not return the Agent shell to a separate 0.78 panel treatment while the toolbar, zoom, and scheduled-condition panel use surface-map-control; those surfaces should read as one instrument family. Keep the conversation well lighter than the shell, and use readable local message surfaces for operational text. Do not use 0.58 or lower for any Agent region that contains operational text.

Collapsed Agent state should be content-sized, not full height. It should keep only the expand button, Agent identity, and pending status indicators. Expanding and collapsing should use a short 150-180ms reveal: opacity, 4-8px horizontal translation, and very small scale change. Do not animate the map camera when the Agent panel changes state.

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.

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 same shell treatment as surface-map-control:

• Outer shell: rgba(255, 255, 255, 0.92), soft white border, subtle dark ring, compact control shadow, and backdrop-blur-xl.
• Outer radius: rounded-2xl, because the component reads as a major floating panel even when collapsed.
• Header, list containers, rows, and detail cards: surface-readable or canvas-panel-strong, around 0.94-0.96.
• 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:

• 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:

• 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 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 surface-map-control, fixed at rgba(255, 255, 255, 0.92).
• Border: white at roughly 70-80% opacity plus a very subtle dark ring when extra definition is needed.
• Shadow: soft multi-layer map shadow, not card-like depth.
• Backdrop blur: use lightly, only when text and icons remain readable.
• Radius: rounded-xl for grouped controls; rounded-lg for internal icon buttons.
• Do not stack a command-panel or second glass wrapper around toolbar, zoom, Agent shell, or scheduled-condition shell.

Prefer Tailwind default opacity utilities for UI component surfaces, such as bg-white/95, bg-blue-50/95, and shadow-lg shadow-slate-900/20. Keep explicit color strings only for platform APIs such as MapLibre paint values, runtime dynamic style values, syntax-highlighting variables, or rare cases where an audited opacity cannot be represented clearly by Tailwind defaults.

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 surface-map-control (rgba(255, 255, 255, 0.92)) and should not sit inside another translucent 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 surface-tool-panel (rgba(255, 255, 255, 0.78)) for the outer shell.
• Internal list rows, panel headers, swatches, result blocks, and action rows use surface-readable, around 0.94-0.96, for readability.
• 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 surface-map-control opacity 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.

Feature Popover

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 translucent 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 features/workbench, features/map/core, and features/agent.
• Convert repeated glass surfaces, map controls, metric cards, status pills, and action cards into reusable typed components.
• 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:

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

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

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

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.

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.