design-workflow

ilude's avatarfrom ilude

UI/UX design workflow guidelines. Activate when working with design systems, accessibility (WCAG), user interface patterns, or design tokens.

⭐5stars🔀0forks📁View on GitHub🕐Updated Dec 30, 2025

When & Why to Use This Skill

This Claude skill serves as a comprehensive UI/UX design and development framework, prioritizing accessibility (WCAG 2.1 AA), performance, and systematic consistency. It provides developers and designers with standardized guidelines for design tokens, responsive layouts, and inclusive component patterns to streamline the transition from design to production-ready code.

Use Cases

  • Ensuring full WCAG 2.1 AA compliance by implementing mandatory color contrast ratios, keyboard navigation logic, and ARIA-compliant focus management.
  • Establishing a single source of truth for visual styling through a design token system for colors, spacing, and typography across CSS and TypeScript.
  • Building accessible and responsive UI components such as focus-trapped modals, mobile-first form fields with error handling, and touch-optimized buttons.
  • Implementing advanced frontend features including system-aware dark mode, reduced motion support, and skeleton loading states for improved user experience.
  • Conducting design quality checks to maintain a Lighthouse accessibility score of 95+ and ensuring logical heading hierarchies for screen readers.
namedesign-workflow
descriptionUI/UX design workflow guidelines. Activate when working with design systems, accessibility (WCAG), user interface patterns, or design tokens.
locationuser

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

Design Workflow

Core Principles

  1. Clarity over decoration - Function before form
  2. Consistency over novelty - Reuse patterns
  3. Accessibility over convenience - WCAG 2.1 AA minimum
  4. Performance over polish - Fast > pretty
  5. Feedback over silence - Always show state
  6. Progressive disclosure - Show what's needed when needed

Accessibility Requirements

Accessibility is NOT optional. All implementations MUST achieve these standards.

Color Contrast (MUST Achieve)

  • Normal text: MUST have 4.5:1 contrast ratio minimum
  • Large text (18px+ or 14px+ bold): MUST have 3:1 contrast ratio minimum
  • UI components/focus indicators: MUST have 3:1 contrast ratio

Keyboard Navigation (MUST Achieve)

  • All interactive elements MUST be focusable via Tab key
  • Focus order MUST follow logical reading order
  • Custom components MUST implement appropriate ARIA roles
  • Escape key MUST close modals and dropdowns
  • Arrow keys SHOULD navigate within composite widgets
// Focus trap for modals - REQUIRED
const useFocusTrap = (containerRef: RefObject<HTMLElement>) => {
  useEffect(() => {
    const container = containerRef.current;
    if (!container) return;
    const focusables = container.querySelectorAll(
      'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])'
    );
    const first = focusables[0] as HTMLElement;
    const last = focusables[focusables.length - 1] as HTMLElement;
    const handleKeyDown = (e: KeyboardEvent) => {
      if (e.key !== 'Tab') return;
      if (e.shiftKey && document.activeElement === first) {
        e.preventDefault(); last.focus();
      } else if (!e.shiftKey && document.activeElement === last) {
        e.preventDefault(); first.focus();
      }
    };
    container.addEventListener('keydown', handleKeyDown);
    first?.focus();
    return () => container.removeEventListener('keydown', handleKeyDown);
  }, [containerRef]);
};

Focus Management (MUST Achieve)

  • Opening modal MUST move focus to modal; closing MUST return focus to trigger
  • Route changes SHOULD move focus to main content or heading
  • Error states MUST announce to screen readers

Screen Reader Testing (MUST Test With)

  • macOS/iOS: VoiceOver | Windows: NVDA/JAWS | Android: TalkBack
  • All images: meaningful alt text (alt="" for decorative)
  • Form inputs: associated labels | Headings: logical hierarchy
  • Dynamic content: aria-live regions | Interactive elements: accessible names

Reduced Motion (MUST Respect)

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

Lighthouse Score: MUST be >95

Run: npx lighthouse <url> --only-categories=accessibility


Design Tokens

Design tokens MUST be the single source of truth for visual styling.

:root {
  /* Colors - Semantic */
  --color-primary: #2563eb;
  --color-primary-hover: #1d4ed8;
  --color-secondary: #64748b;
  --color-success: #16a34a;
  --color-warning: #ca8a04;
  --color-error: #dc2626;
  /* Colors - Neutral */
  --color-neutral-50: #fafafa;
  --color-neutral-100: #f4f4f5;
  --color-neutral-200: #e4e4e7;
  --color-neutral-700: #3f3f46;
  --color-neutral-800: #27272a;
  --color-neutral-900: #18181b;
  /* Spacing - 4px base */
  --space-1: 0.25rem; --space-2: 0.5rem; --space-3: 0.75rem;
  --space-4: 1rem; --space-6: 1.5rem; --space-8: 2rem;
  --space-12: 3rem; --space-16: 4rem;
  /* Typography */
  --font-sans: system-ui, -apple-system, sans-serif;
  --font-mono: ui-monospace, 'Cascadia Code', monospace;
  --text-xs: 0.75rem; --text-sm: 0.875rem; --text-base: 1rem;
  --text-lg: 1.125rem; --text-xl: 1.25rem; --text-2xl: 1.5rem;
  --leading-tight: 1.25; --leading-normal: 1.5; --leading-relaxed: 1.75;
}

Dark Mode Implementation

:root {
  --bg-primary: #ffffff;
  --bg-secondary: #f4f4f5;
  --text-primary: #18181b;
  --text-secondary: #52525b;
  --border-color: #e4e4e7;
}
:root.dark {
  --bg-primary: #18181b;
  --bg-secondary: #27272a;
  --text-primary: #fafafa;
  --text-secondary: #a1a1aa;
  --border-color: #3f3f46;
}
@media (prefers-color-scheme: dark) {
  :root:not(.light) { /* Apply dark values */ }
}
  • MUST persist user preference (localStorage)
  • MUST respect prefers-color-scheme as default
  • MUST NOT flash wrong theme on load
  • SHOULD use color-scheme: dark for native elements

Component Patterns

Buttons

.btn {
  display: inline-flex; align-items: center; justify-content: center;
  gap: var(--space-2); padding: var(--space-2) var(--space-4);
  font-weight: 500; border-radius: 0.375rem;
  transition: background-color 150ms, box-shadow 150ms;
}
.btn:focus-visible { outline: 2px solid var(--color-primary); outline-offset: 2px; }
.btn:disabled { opacity: 0.5; cursor: not-allowed; }
  • MUST have visible focus state
  • MUST be minimum 44x44px touch target on mobile
  • MUST show loading state during async operations
  • SHOULD NOT rely on color alone to convey meaning

Forms

<div class="form-field">
  <label for="email">Email address</label>
  <input type="email" id="email" aria-describedby="email-error" aria-invalid="true" />
  <span id="email-error" role="alert">Please enter a valid email</span>
</div>
  • Labels MUST be visible (no placeholder-only labels)
  • Error messages MUST be associated via aria-describedby
  • Required fields MUST be indicated visually AND via aria-required
  • SHOULD validate on blur, NOT on every keystroke

Modals

  • MUST trap focus within modal
  • MUST close on Escape key
  • MUST return focus to trigger on close
  • MUST have accessible name (aria-labelledby or aria-label)
  • SHOULD use <dialog> element when possible
  • SHOULD prevent body scroll when open

Motion and Animation

Animation SHOULD be subtle and purposeful. Never use motion for decoration.

:root {
  --ease-out: cubic-bezier(0, 0, 0.2, 1);
  --ease-in-out: cubic-bezier(0.4, 0, 0.2, 1);
  --duration-fast: 150ms; --duration-normal: 200ms; --duration-slow: 300ms;
}
@keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }
@keyframes slideUp { from { opacity: 0; transform: translateY(8px); } to { opacity: 1; transform: translateY(0); } }
  • Keep durations under 300ms for UI feedback
  • Use ease-out for entering, ease-in for exiting elements
  • MUST respect prefers-reduced-motion

Responsive Design

Mobile-first approach is REQUIRED.

:root { --bp-sm: 640px; --bp-md: 768px; --bp-lg: 1024px; --bp-xl: 1280px; }
.container { padding: var(--space-4); }
@media (min-width: 768px) { .container { padding: var(--space-6); } }
@media (min-width: 1024px) { .container { padding: var(--space-8); max-width: 1200px; margin: 0 auto; } }
  • Touch targets MUST be minimum 44x44px on mobile
  • Text MUST be readable without horizontal scrolling
  • Images MUST be responsive (max-width: 100%)
  • SHOULD use CSS Grid/Flexbox over fixed widths

Loading and Error States

Every async operation MUST show appropriate feedback.

// Loading
<button disabled={isLoading}>
  {isLoading ? <><Spinner aria-hidden="true" /><span>Saving...</span></> : 'Save'}
</button>
<div aria-busy="true" aria-label="Loading content">
  <div class="skeleton skeleton-text" />
</div>

// Error
<div role="alert" class="error-banner">
  <ErrorIcon aria-hidden="true" />
  <div>
    <p class="error-message">Failed to save changes</p>
    <p class="error-detail">Please check your connection and try again</p>
  </div>
  <button onClick={retry}>Retry</button>
</div>
  • Loading MUST be indicated within 100ms of action
  • Errors MUST explain what went wrong and SHOULD suggest how to fix
  • Empty states MUST guide users to next action
  • MUST NOT show raw error messages to users