harbor-net/.codex/skills/design-vpn-client-ui/SKILL.md

name, description

name

description

design-vpn-client-ui

Design, implement, review, or refine the client-facing VPN interfaces in this repository using the established calm monospace visual language and smooth state-driven motion. Use for the current macOS client and future end-user gateway client screens, especially power controls, subscriptions, traffic usage, proxy copy controls, server selection, responsive layout, hover feedback, transitions, and animation polish. Do not use for the administrative gateway UI unless the user explicitly asks to apply the client visual language there.

Design VPN Client UI

Preserve the repo's focused one-screen VPN client language: a centered primary action, quiet technical typography, mode-specific accents, and motion that makes live state and interaction legible without moving layout.

Workflow

1. Read PRODUCT.md and the complete client component and styles before editing.
2. Inspect supplied evidence and trace the real DOM and state change that causes the visual issue. Follow repository testing policy; do not launch manual or interactive visual testing unless the user explicitly requests it in the current prompt.
3. Read visual-language.md for layout, hierarchy, color, and typography work.
4. Read motion-and-interaction.md for animation, hover, refresh, input, copy, or state-transition work.
5. Reuse existing React state, CSS variables, formatters, and API paths. Prefer a narrow CSS/markup change over a new abstraction or dependency.
6. Keep geometry stable across every state. Reserve space before animating content.
7. Implement prefers-reduced-motion alongside every new animation.
8. Run npm test, npm run build, and git diff --check. Perform manual visual inspection only when explicitly requested.

Non-negotiable decisions

• Keep the power action on the screen's central vertical axis. Place subscription content to its right without shifting that axis.
• Keep the power hit target generous while rendering only the icon, never a large enclosing accent circle.
• Drive every active accent from the current mode token: Connect is blue-green; Gateway is orange. Keep inactive power gray, including hover, and preserve semantic warning/error colors.
• Never let labels, timers, feedback, icons, progress, or server rows shift neighboring content.
• Animate state, opacity, blur, glow, color, filter, and transform. Do not animate layout properties.
• Make live behavior visibly alive: running processes, changing values, mode changes, and interactive affordances should communicate through restrained motion instead of abrupt static replacement.
• Let every visible cycle finish and return to its resting coordinates before stopping. Never cancel a hover animation, spinner, or list exit at an arbitrary frame.
• Animate dynamic rows through complete enter and exit phases; keep a departing row mounted until its exit finishes, with immediate removal under reduced motion.
• Animate only what changed. Keep unchanged digits, labels, icons, and surrounding geometry stable.
• Keep tooltips outside transformed, rotating, glowing, or filtered controls. Show them quickly above the control as independent translucent cloud surfaces.
• Prefer one clear value over unsupported detail. Hide subscription fields the provider does not supply.
• Keep client UI compact and calm. Do not introduce dashboard cards, decorative chrome, or admin-console density.
• Do not use a modal, popup, or blocking backdrop unless the user explicitly asks for one. Prefer inline disclosure or a non-modal layer that preserves the main screen.
• Avoid borders, divider lines, and framed regions by default. Build hierarchy with spacing, typography, subtle surface changes, light, and depth; use a line only when it communicates an essential state.
• In client-side editors, prefer flat text controls and accessible custom pickers over browser-native menus when the native surface breaks the visual language. Do not append another blank row until the current row is complete.

Acceptance pass

Before handing off, verify:

• Power on/off is unmistakable without reading the label.
• Switching on/off preserves the exact positions of title, timer, and hint.
• Switching Connect/Gateway crossfades status in a fixed slot, changes the full accent palette, and clearly de-emphasizes data irrelevant to the active route.
• A timer tick animates only changed digits and reads as a soft flow, never a blink.
• Hover motion completes its current cycle and settles before stopping; ambient affordance motion remains subtle and infrequent.
• Tooltips remain upright, unfiltered, above adjacent content, and visually consistent across controls.
• Refresh and copy feedback cannot change element width or alignment.
• Server separators are compact and only slightly wider than their content.
• Repeated polling does not replay decorative list animations.
• Manual refresh has an obvious but non-jarring response.
• Keyboard focus remains visible even when the text caret is intentionally hidden.
• Narrow screens return to a simple single-column layout.