esplotter/ui-design

Skill: UI Design

This skill defines how to implement or review renderer UI so it looks unified with the existing app and follows a high-quality product design baseline.

Primary sources:

• docs/frontend/components.md
• docs/guidelines/code-standards.md

Scope

Use when

• Implementing or refining renderer UI components, pages, or visual states.
• Harmonizing new UI with existing app layout, spacing, typography, and interaction patterns.
• Validating design consistency before final review.

Do NOT use when

• Working on main/preload architecture without renderer UI impact.
• Defining test-suite routing or coverage strategy.

Design baseline

1. Vercel-inspired white theme direction
   • Bright base surfaces and subtle neutral layers.
   • Clean borders and restrained shadows.
   • High text contrast and clear hierarchy.
2. Repository-first consistency
   • Reuse existing Tailwind and shadcn patterns.
   • Respect established component behavior and spacing rhythm.
   • Prefer extending current primitives over introducing custom one-off controls.
3. UX quality requirements
   • Clear information hierarchy and predictable navigation.
   • Visible interactive states (hover, focus, active, disabled).
   • Keyboard-friendly flows for primary actions.
4. Accessibility defaults
   • Sufficient contrast in text and controls.
   • Focus states are always visible.
   • Meaning is not conveyed by color alone.
5. Responsive behavior
   • UI must remain usable on desktop and mobile for touched flows.
   • Avoid layout breakpoints that cause clipped content or inaccessible actions.

Implementation rules

• Use Tailwind classes and shadcn primitives as primary styling stack.
• Keep style tokens coherent: spacing, radius, border, and typography should match nearby screens.
• Prefer minimal purposeful motion; avoid decorative animation noise.
• Avoid inline styles for regular component styling.
• Do not introduce new visual language in isolated pages without explicit feature requirement.

Consistency checklist

For each changed UI file, verify:

1. Visual alignment
   • Matches surrounding pages and shared components.
2. Typography and spacing
   • Preserves hierarchy and spacing cadence.
3. Interaction quality
   • States are visible and behavior is predictable.
4. Accessibility
   • Focus, contrast, and keyboard path remain valid.
5. Responsive stability
   • Main flow remains functional on mobile and desktop.

Anti-patterns (blocker)

• New UI that ignores existing app visual language.
• Hard-to-read text or missing focus states.
• One-off style overrides that conflict with shared component patterns.
• Large decorative changes without product requirement.

Definition of done

• Changed UI is visually consistent with the app and follows white-theme baseline.
• Accessibility and responsive checks pass for touched behavior.
• Design adjustments are minimal, intentional, and scope-bounded.

Output contract

Return a structured YAML report including:

• status: ok | needs_clarification | error
• summary: short UI consistency and UX quality assessment
• scope: task IDs, files reviewed, assumptions
• decisions: key design decisions and rationale
• consistency_checks: checklist results by file or module
• findings: issues with severity, evidence, and minimal fix
• verdict: ready | ready_with_changes | not_ready
• next_actions: minimal action list
• warnings: unresolved risks or assumptions