---
name: drainage-network-design
description: Use when designing, redesigning, or adjusting visual styles, layout, motion, spacing, typography, map panels, workbench UI, Agent UI, tool panels, timeline/list/detail panels, or any component styling in drainage-network. Also use when a user makes substantial component UI changes that should be captured back into DESIGN.md.
---

# Drainage Network Design

This skill keeps UI work aligned with the project design guide.

## Required Workflow

1. Before changing component layout, styling, motion, density, copy hierarchy, or interaction shape, read `DESIGN.md` from the `drainage-network` repo root.
2. Apply the guide as the source of truth for map-first layout, command instruments, surface opacity, radius, typography, motion, and panel behavior.
3. Prefer existing local style helpers and component patterns over new one-off visual systems.
4. After implementing a substantial UI adjustment, update `DESIGN.md` when the change establishes a reusable rule, corrects an outdated rule, or resolves a repeated design tradeoff.
5. Keep `DESIGN.md` updates behavior-level and reusable. Do not document one-off class names unless they represent an intentional design token or pattern.

## What Counts As Substantial

Update `DESIGN.md` when the work changes any of these:

- A reusable component pattern, such as collapsed-to-expanded detail panels, timeline rows, persistent map instruments, or Agent decision surfaces.
- Visual hierarchy rules for shells, readable surfaces, rows, detail cards, or action areas.
- Motion rules, including when content should enter, whether lists should remount, or how scroll position is preserved.
- Information architecture, such as what appears in collapsed versus expanded states.
- Common responsive behavior for map overlays or side panels.

Do not update `DESIGN.md` for small bug fixes, minor spacing tweaks, copy corrections, or purely local implementation cleanup unless the guide is already contradicted by the current UI.

## Implementation Defaults

- Keep the map as the primary canvas. Floating UI should behave like operational instruments, not generic dashboard cards.
- Use `surface-map-control` treatment for persistent map instruments and readable inner surfaces for dense text.
- Avoid decorative chrome, oversized headings, nested cards, and visual effects without operational meaning.
- Use short motion that explains state change. Separate layout motion from dense content entrance when expanding detail panels.
- Preserve list identity and scroll position when a collapsed list expands into a detail workspace.
- Validate frontend UI changes with `pnpm lint` and `pnpm typecheck`; run `pnpm build` when CSS, Tailwind classes, routing, or build-time behavior could be affected.