ui-design

name	ui-design
description	Use when creating or modifying any visible UI element, adjusting spacing or typography, reviewing visual consistency, or when Lighthouse Performance drops below 90.

UI/UX Design Skill

Canonical Sources

This skill references the following globals — read them BEFORE starting work:

• system/globals/typography.md — Font stack, heading scale, weights
• system/globals/spacing.md — Section padding, grids, container widths
• system/globals/effects.md — Border radius, shadows, card pattern
• system/globals/imagery.md — Image formats, alt text, optimization
• system/globals/responsiveness.md — Breakpoints, mobile-first rules

Domain

Visual Hierarchy, Spacing, Typography, OKLCH Color Theory, Layout Patterns

KPIs

Metric	Target	Measurement
Lighthouse Performance	>90	Lighthouse JSON → categories.performance.score * 100
First Contentful Paint	<1.8s	Lighthouse JSON → audits.first-contentful-paint
Largest Contentful Paint	<2.5s	Lighthouse JSON → audits.largest-contentful-paint
Cumulative Layout Shift	<0.1	Lighthouse JSON → audits.cumulative-layout-shift
Total Blocking Time	<200ms	Lighthouse JSON → audits.total-blocking-time

Design Consistency Checklist

• Heading hierarchy maintained (h1 → h2 → h3, no skipping)
• Consistent section paddings (py-20 px-6)
• Colors only via CSS variables (text-primary, not text-blue-500)
• Consistent border radius (rounded-xl)
• Mobile-first responsive (all breakpoints checked: 375px, 768px, 1024px, 1280px)
• Mobile navigation present (no hidden lg:block without mobile alternative)
• No horizontal overflow on mobile
• Dark mode tested

Non-Negotiable

These rules always apply — even under time pressure, even for "just a quick prototype":

• No commit without responsive check. "We'll make it responsive later" never works — it gets forgotten and users see a broken mobile version.
• Section padding is py-20 px-6. "A bit more room with py-32" destroys visual consistency across sections.
• Colors only via CSS variables. "Just bg-white here" breaks dark mode immediately — without anyone noticing until they toggle.
• No rounded-lg or rounded-md. The design system uses rounded-xl. Inconsistency is noticeable, even if individual deviations "look better."
• Mobile-first is mandatory. Desktop-first "and then adjust" produces overflow, undersized touch targets, and missing mobile navigation.

Before Applying

Read LEARNINGS.md in this directory to avoid known anti-patterns.