UI Design

UI Design

Overview

Modern component library and design system engineering. Enforces design token hierarchies (spacing, radii, elevation), accessible component primitives (shadcn/ui, Radix), and responsive layout constraints.

When to Use

Activate when designing design systems, reusable UI component libraries, navigation bars, modals, data tables, and interactive dashboards.

Rules & Patterns

UI Design — Best Practices

Design System Foundations

Color

• Never use generic colors — curate a harmonious palette
• Always tint — no pure black (#000), no pure gray. Add a subtle warm or cool tint
• Color roles: primary (action), secondary (accent), neutral (text, borders), semantic (error, success, warning, info)
• Dark mode: design intentionally, not just invert. Surface hierarchy: background < surface < elevated
• Contrast: 4.5:1 minimum for body text, 3:1 for large text

Typography

• Never use browser defaults — choose a curated font (Inter, Outfit, Geist, Sora)
• Type scale: use a modular scale (1.25 ratio) — 12, 14, 16, 20, 24, 32, 40, 48
• Font weights: Regular (400), Medium (500), Semibold (600), Bold (700). Don't use all of them — pick 2-3
• Line height: 1.5 for body, 1.2 for headings, 1.6 for long-form text
• Max line width: 65-75 characters for readability

Spacing

• Use a 4px grid — all spacing should be multiples of 4
• Spacing scale: 4, 8, 12, 16, 20, 24, 32, 40, 48, 64, 80, 96
• Consistency — same spacing between similar elements
• Whitespace is design — don't fill every pixel

Layout

• Grid system: 12-column grid for desktop, 4-column for mobile
• Visual hierarchy: size, weight, color, spacing, position
• F-pattern/Z-pattern — for content-heavy pages
• Group related items — use proximity and boundaries

Component Patterns

Buttons

• Clear hierarchy: Primary > Secondary > Ghost/Text
• Consistent sizing: sm (32px), md (40px), lg (48px)
• States: default, hover, active, disabled, loading
• Always accessible: sufficient contrast, focus indicator

Forms

• Labels above inputs (not floating labels for critical forms)
• Clear error states with inline messages
• Logical tab order
• Progressive disclosure — don't show all fields at once

Cards

• Don't nest cards inside cards
• Clear visual hierarchy within the card
• Consistent padding and spacing
• Interactive cards need hover state

Navigation

• Maximum 7±2 items in primary nav
• Clear active state
• Mobile: bottom nav or hamburger (not both)
• Breadcrumbs for deep hierarchies

Animation Principles

• Purpose: guide attention, show relationships, provide feedback
• Duration: 150-300ms for micro-interactions, 300-500ms for transitions
• Easing: ease-out for entrances, ease-in for exits. Never bounce or elastic
• Reduce motion: respect prefers-reduced-motion

Anti-Patterns (from Impeccable)

• [FAIL] Gray text on colored backgrounds — destroys readability
• [FAIL] Pure black text on white (#000 on #fff) — too harsh, tint the black
• [FAIL] Cards nested inside cards — visual noise
• [FAIL] Bounce/elastic easing — feels dated
• [FAIL] Icon tile above every heading — SaaS template tell
• [FAIL] Purple-to-blue gradient on everything — overused
• [FAIL] Using Inter for everything — pick a font that matches your brand
• [FAIL] Rounded-square icons everywhere — lack of visual variety

Dark Mode

• Surface elevation through subtle lightening (not colored backgrounds)
• Reduce white contrast — use #E0E0E0, not #FFFFFF
• Shadows become less visible — use subtle borders or elevation changes
• Test all states in both modes

Code Examples

See EXAMPLES.md for detailed code examples.

Validation Checklist

What to verify during the review phase before completing the task.

Common Mistakes

Anti-patterns and things to explicitly avoid. See TROUBLESHOOTING.md.

Integration Notes

How this skill interacts with other skills.

ui-design Examples — Anti-patterns vs ContextOS Standard

Example 1: Component Token Consistency

Anti-pattern: Hardcoded Arbitrary Tailwind Utilities

// BAD: Inconsistent spacing, arbitrary colors, unmaintainable styling
<div className="p-[13px] bg-[#1a1b2e] rounded-[7px] text-[#99aab5] border border-[#2b2d42]">
  <button className="px-[15px] py-[7px] bg-[#5865f2] hover:bg-[#4752c4]">Action</button>
</div>

Best practice: ContextOS Standard (Semantic Theme Tokens)

// GOOD: Consistent scale utilities driven by Tailwind v4 @theme design tokens
<div className="p-4 bg-card rounded-lg text-muted-foreground border border-border">
  <Button variant="primary" size="md">Action</Button>
</div>

ui-design Troubleshooting & Common Mistakes

1. Z-Index Chaos

• Symptom: Tooltips rendered underneath dialog overlays, or dropdowns hidden behind sticky headers.
• Root Cause: Ad-hoc hardcoded values (z-50, z-[999], z-[9999]).
• Fix: Use Radix / shadcn Portals for floating elements so they render at root DOM level, or declare strict z-index tokens.

2. Inconsistent Component States

• Symptom: Buttons have hover states but lack focus-visible rings or disabled states.
• Root Cause: Styling only the default and hover states.
• Fix: Standardize state matrices for every interactive element: default, hover, focus-visible, active, disabled, loading.

3. Ignoring Empty and Error Component States

• Symptom: Tables or list views show a blank white box when there are 0 records.
• Root Cause: Developers only design for the "ideal data" case.
• Fix: Every data component must explicitly render designed EmptyState and ErrorState fallbacks.