ui

UI

Design system reference and visual quality guidelines for the Devkit Vue stack.

This is not a standalone workflow. For full feature implementation, use /feature which automatically applies these guidelines when visual work is involved.

Invoke /ui directly only for pure design tasks (restyle, theme change, layout fix) that don't need the full /feature workflow.

This skill is an enforcer of the design system (Vuetify 4 + MD3 + theme helpers) and a craft baseline — the "Beauty pass" below is teachable, encodable craft (not taste-by-vibes), the difference between correct and beautiful. Net-new brand identity (a bold landing aesthetic, a new visual language) still belongs to creative direction outside this skill; the Beauty pass makes the everyday output stop looking generic.

References

Key rules (quick reminder)

• Typography: MD3 classes only (text-display-large, NOT text-h1). Responsive: text-display-small text-sm-display-medium
• Colors: Theme tokens via config or CSS variables (rgb(var(--v-theme-primary))), never hardcoded hex in templates
• Dark/light: Everything must work in both modes
• Config-driven: Prefer config options over hardcoded values
• CSS last resort: Prefer in order: Vuetify props (flat, elevation, variant, density) → Vuetify utility classes (pa-0, d-flex) → Vuetify transitions (v-fade-transition, v-scale-transition) → <style scoped> only if no Vuetify alternative exists
• Reuse: Check existing components before creating new ones
• Verify: Screenshot desktop+mobile, light+dark after visual changes

Beauty pass (correct → beautiful)

Consistency + accessibility make a UI correct; these seven rules make it beautiful. Each is a checkable rule with a named failure mode — the inverse of each is exactly what makes a layout read as generic. Apply on every visual surface; they need no bespoke CSS (Vuetify props, spacing classes, elevation, and theme tokens carry all seven). Deeper config levers to push past the generic Material look: references/design-system.md § "Beauty levers".

1. Whitespace first, then reduce. Start generous, don't fill the viewport; cramped padding is the #1 generic tell. Lean on pa-6/pa-8, section py-12+. Context-calibrate: dense dashboards tighten, but never start cramped.
2. Hierarchy by weight + color, not size alone. Cap ~3 type sizes per view; de-emphasize secondary/tertiary with a lighter text-medium-emphasis / muted color, not just smaller. Size-only hierarchy is a slop signature.
3. Spacing on the fixed scale only. Use the spacing classes (steps 0→16 = 4→64px); never an arbitrary inline margin: 13px. Off-scale spacing reads ad-hoc.
4. Color reserved for emphasis. Mostly-neutral base (tinted greys via surface/background, not pure grey); primary for the ONE action that matters, not spread across the screen. Even color spread = the default-Material generic look. Never grey text on a colored background.
5. Depth = soft, two-part elevation. Prefer low elevation-1/elevation-2 (Vuetify's shadows are already the layered contact+ambient pair) or elevation-0 + a subtle surface border; overlap elements to layer. One harsh high-contrast shadow reads cheap.
6. Proximity groups related items (Gestalt). A field label sits tight to its input; a card's title/body/action cluster with less gap inside than between cards. Uniform spacing everywhere destroys grouping.
7. Restraint over decoration. Fewer weights, one accent, generous rhythm — boring-and-consistent beats clever-and-busy. Delete an element before adding one.

These seven rules are the canonical craft baseline: name the visual intent when planning a surface, apply the rules while building, and score the rendered result against them in QA. This skill is where they're authored.

Anti-patterns

• text-h1..text-h6 → use MD3: text-display-large, text-headline-medium
• Hardcoded colors in templates → use theme variables
• New components for things existing ones already handle
• Ignoring dark mode
• Skipping visual verification
• Custom CSS when a Vuetify prop/class/transition covers the need
• Generic-look tells (Beauty pass inverses): cramped padding · hierarchy by size alone · color spread evenly instead of reserved for emphasis · one harsh shadow · arbitrary off-scale spacing · pure untinted greys · grey text on colored backgrounds