next-tjwater-drainage-frontend/.agents/skills/drainage-network-design/SKILL.md

name, description

name	description
drainage-network-design	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.