Now liveThe Skillselion MCP - thousands of ranked skills, loaded into your agent mid-task. No install.Get it →
samhvw8 avatar

Ui Design System

samhvw8/dot-claude

  • 3.2k installs
  • 10 repo stars
  • Updated December 9, 2025
  • samhvw8/dot-claude

Expertise in building and auditing production-ready UI component systems using TailwindCSS, Radix UI primitives, and shadcn/ui components with WCAG AA accessibility compliance and design system architecture.

About

Comprehensive UI/UX design, review, and improvement service for modern web applications using TailwindCSS, Radix UI, and shadcn/ui. Covers design system architecture with three-tier token systems, WCAG AA accessibility compliance, responsive mobile-first patterns, dark mode theming, and component composition. Provides systematic audits for component reusability, accessibility standards, performance optimization, design token consistency, and visual hierarchy. Implements production-ready interfaces following atomic design principles, semantic HTML, and progressive enhancement. Includes dark mode setup, form architecture with React Hook Form + Zod validation, and Core Web Vitals optimization strategies.

  • Three-tier design token system (primitive/semantic/component) with OKLCH color space
  • WCAG 2.1/2.2 AA accessibility audits with 4.5:1 text contrast enforcement
  • Mobile-first responsive design patterns with breakpoint strategy and container queries
  • Component composition from Radix primitives and shadcn/ui with customization strategies
  • Systematic UI/UX review framework covering architecture, performance, and design consistency

Ui Design System by the numbers

  • 3,158 all-time installs (skills.sh)
  • +9 installs in the week ending Jul 29, 2026 (Skillselion tracking)
  • Ranked #108 of 1,888 Design & UI/UX skills by installs in the Skillselion catalog
  • Security screen: MEDIUM risk (skills.sh audit)
  • Data as of Jul 29, 2026 (Skillselion catalog sync)
npx skills add https://github.com/samhvw8/dot-claude --skill ui-design-system

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

Listed on Skillselion
Installs3.2k
repo stars★ 10
Security audit2 / 3 scanners passed
Last updatedDecember 9, 2025
Repositorysamhvw8/dot-claude ↗

What it does

Build accessible, production-ready UI component systems with TailwindCSS, Radix UI, and shadcn/ui for React/Next.js applications.

Who is it for?

Building design systems and component libraries, implementing shadcn/ui in new projects, auditing existing UIs for accessibility and design consistency, creating responsive mobile-first interfaces, setting up dark mode t

Skip if: React/Next.js application architecture, state management patterns, server components, backend APIs, database design, DevOps infrastructure, or general web development unrelated to UI systems.

When should I use this skill?

Requesting UI/UX review or audit; designing component libraries or design systems; implementing accessibility improvements; setting up TailwindCSS, Radix UI, or shadcn/ui; creating responsive patterns; establishing desig

What you get

Developers deliver accessible, performant, customizable component libraries and design systems with documented design tokens, comprehensive accessibility coverage, responsive mobile-first layouts, and production-ready im

  • Design token system
  • Accessible UI components
  • Accessibility audit notes

By the numbers

  • Skill version 2.0.0 with 7 bundled reference guides
  • Three-layer architecture: TailwindCSS, Radix UI, and shadcn/ui

Files

SKILL.mdMarkdownGitHub ↗

UI/UX Design & Development Expert

Comprehensive UI/UX design, review, and improvement for modern web applications.

Production-ready implementations with TailwindCSS + Radix UI + shadcn/ui and modern React patterns.

Stack Architecture

The Three Pillars

Layer 1: TailwindCSS (Styling Foundation)

  • Utility-first CSS framework with build-time generation
  • Zero runtime overhead, minimal production bundles
  • Design tokens: colors, spacing, typography, breakpoints
  • Responsive utilities and dark mode support

Layer 2: Radix UI (Behavior & Accessibility)

  • Unstyled, accessible component primitives
  • WAI-ARIA compliant with keyboard navigation
  • Focus management and screen reader support
  • Unopinionated - full styling control

Layer 3: shadcn/ui (Beautiful Components)

  • Pre-built components = Radix primitives + Tailwind styling
  • Copy-paste distribution (you own the code)
  • Built-in React Hook Form + Zod validation
  • Customizable variants with type safety

Architecture Hierarchy

Application Layer
    ↓
shadcn/ui Components (Beautiful defaults, ready-to-use)
    ↓
Radix UI Primitives (Accessible behavior, unstyled)
    ↓
TailwindCSS Utilities (Design system, styling)

Key Principle: Each layer enhances the one below. Start with Tailwind for styling, add Radix for accessible behavior, use shadcn/ui for complete components.

Core Capabilities

UI/UX Review & Audit

Systematic evaluation of existing interfaces:

  • Component Architecture Review: Analyze component composition, reusability, and single responsibility
  • Accessibility Audit: WCAG 2.1/2.2 AA/AAA compliance, keyboard navigation, screen reader support
  • Performance Analysis: Core Web Vitals (LCP, FID, CLS), bundle size, render performance
  • Responsive Design Review: Mobile-first implementation, breakpoint usage, container queries
  • Design System Consistency: Token usage, spacing scale adherence, color palette compliance
  • Code Quality: React best practices, hooks usage, state management patterns
  • Visual Hierarchy: Typography scale, spacing rhythm, color contrast, focus indicators

UI/UX Design

Creating production-ready interface designs:

  • Component Design: Atomic design principles, composition patterns, variant systems
  • Layout Architecture: Grid systems, flexbox patterns, responsive containers
  • Interaction Design: Hover states, focus states, loading states, error states
  • Design Tokens: Three-tier token system (primitive → semantic → component)
  • Color Systems: OKLCH color space, accessible palettes, dark mode support
  • Typography Systems: Scale design, hierarchy, readability optimization
  • Animation & Transitions: Micro-interactions, loading feedback, state changes

UI/UX Improvement

Enhancing existing implementations:

  • Accessibility Enhancement: ARIA patterns, semantic HTML, keyboard navigation
  • Performance Optimization: Code splitting, lazy loading, virtualization, image optimization
  • Responsive Refinement: Breakpoint optimization, mobile-first improvements
  • Component Refactoring: Extract shared patterns, reduce complexity, improve reusability
  • Visual Polish: Spacing consistency, typography refinement, color harmony
  • State Management: Optimistic updates, error handling, loading states
  • Developer Experience: Component documentation, Storybook stories, type safety

Styling Integration

Framework-agnostic styling approaches:

  • Tailwind with Components: Utility-first styling for any framework
  • CSS-in-JS: emotion, styled-components, vanilla-extract
  • CSS Modules: Scoped styles without runtime overhead
  • Design System Integration: Token-based styling across frameworks

When to Use Each Layer

Use TailwindCSS Directly When:

  • Building custom layouts and spacing
  • Styling static content and containers
  • Rapid prototyping without complex interactions
  • Non-interactive UI elements

Example scenarios: Hero sections, grid layouts, cards without interaction, text styling

Use Radix UI Primitives When:

  • Building custom component libraries
  • Need accessibility but require custom design
  • shadcn/ui doesn't have the component you need
  • Full control over component structure required

Example scenarios: Custom date picker, unique navigation pattern, specialized modal behavior

Use shadcn/ui Components When:

  • Building standard UI components quickly
  • Need beautiful defaults with customization options
  • Enterprise application development
  • Form-heavy applications with validation

Example scenarios: Admin dashboards, CRUD applications, settings pages, data tables

Critical Design Principles

1. Progressive Enhancement

Start simple, enhance as needed: 1. Tailwind utilities for basic styling 2. Add Radix primitives for interaction 3. Use shadcn/ui for complete solutions 4. Customize components in your codebase

2. Composition Over Complexity

Build complex UIs from simple, reusable components:

  • Small, focused components (single responsibility)
  • Compose primitives rather than creating monoliths
  • Leverage component slots and children patterns

3. Accessibility First

Radix UI handles accessibility automatically:

  • ARIA attributes applied correctly
  • Keyboard navigation built-in
  • Focus management and trapping
  • Screen reader compatibility

Never override accessibility features - enhance them.

4. Design Token Consistency

Use Tailwind's design system consistently:

  • Stick to spacing scale (4, 8, 16, 24px)
  • Use color palette (50-950 shades)
  • Apply typography scale systematically
  • Avoid arbitrary values unless necessary

5. Mobile-First Responsive

Always design mobile-first, scale up:

  • Base styles for mobile
  • Use breakpoints (sm, md, lg, xl, 2xl) to enhance
  • Test on actual devices, not just browser resize

Setup Strategy

Installation Order

1. TailwindCSS - Foundation 2. shadcn/ui CLI - Includes Radix dependencies 3. Add components - Install only what you need 4. Configure theme - CSS variables + Tailwind config 5. Setup dark mode - Theme provider + toggle

Configuration Best Practices

Tailwind Config:

  • Use content paths correctly (scan all component files)
  • Extend theme with CSS variables, not hardcoded values
  • Enable dark mode with class strategy
  • Install tailwindcss-animate plugin

CSS Variables (Three-Tier System):

:root {
  /* Tier 1: Primitives (immutable) */
  --gray-50: 250 250 250;
  --gray-900: 24 24 27;
  --blue-500: oklch(0.55 0.22 264);

  /* Tier 2: Semantics (theme-aware) */
  --background: var(--gray-50);
  --foreground: var(--gray-900);
  --primary: var(--blue-500);

  /* Tier 3: Components */
  --button-height: 2.5rem;
  --card-padding: 1.5rem;
}

.dark {
  /* Only semantic tokens change */
  --background: var(--gray-900);
  --foreground: var(--gray-50);
}

Color Space Recommendation:

  • Modern: Use OKLCH for perceptual uniformity
  • Legacy support: Use HSL with fallbacks
  • Avoid: RGB/HEX for design tokens (not human-readable)

Token Storage:

  • Store in JSON for platform-agnostic distribution
  • Transform to CSS variables, Swift, XML using Style Dictionary
  • Version control tokens separately from component code

Path Aliases:

  • Configure @/components and @/lib in tsconfig
  • Ensure consistency between Next.js and TypeScript configs
  • Use aliases in imports for cleaner code

Integration Patterns

Pattern 1: shadcn/ui + Custom Tailwind

Use shadcn/ui components as base, customize with Tailwind classes:

  • Apply custom spacing, colors via className prop
  • Override default styles with Tailwind utilities
  • Maintain component accessibility

Pattern 2: Radix Primitives + Tailwind

Build custom components from scratch:

  • Use Radix for behavior (Dialog, Dropdown, etc.)
  • Style completely with Tailwind utilities
  • Full control over structure and appearance

Pattern 3: Hybrid Approach

Modify shadcn/ui components in your codebase:

  • Edit component files in components/ui/
  • Add new variants, sizes, or styles
  • Maintain type safety with CVA (Class Variance Authority)

Pattern 4: Component Composition

Combine multiple primitives for complex UIs:

  • Popover + Select for searchable dropdown
  • Dialog + Form for modal forms
  • Tabs + Cards for multi-section interfaces

Design Token Architecture

Use three-tier token system for scalable, maintainable design systems:

  • Tier 1 (Primitive): Raw values (gray-50, spacing-4)
  • Tier 2 (Semantic): Purpose-driven (background-primary, text-error)
  • Tier 3 (Component): Component-specific (button-height, card-padding)

Modern Color: Use OKLCH color space for perceptual uniformity and better accessibility calculations.

📖 See [DESIGN_TOKENS.md](references/DESIGN_TOKENS.md) for:

  • Complete three-tier token system implementation
  • OKLCH color space guide and examples
  • Token naming conventions and best practices
  • CSS variable configuration
  • Multi-theme support patterns

Responsive Design Strategy

Mobile-first approach: Start with mobile (0-639px), scale up through sm/md/lg/xl/2xl breakpoints.

Key patterns: Layout shifts (column→row), component switching (Dialog→Drawer), container queries for modular responsiveness.

📖 See [RESPONSIVE_PATTERNS.md](references/RESPONSIVE_PATTERNS.md) for:

  • Complete breakpoint strategy and implementation
  • Responsive component patterns and examples
  • Container queries guide
  • Image optimization strategies
  • Performance considerations for responsive design
  • Comprehensive testing checklist

Form Architecture

Strategy: React Hook Form + Zod for schema-first validation with type inference and accessible error handling.

📖 See [CUSTOMIZATION.md](references/CUSTOMIZATION.md#form-architecture) for:

  • Complete React Hook Form + Zod setup
  • Reusable field wrapper patterns
  • Multi-step form implementation
  • Accessibility requirements checklist

Performance Best Practices

Core strategies: Code splitting (React.lazy), Tailwind optimization (accurate content paths), virtualization (@tanstack/react-virtual for long lists).

📖 See [PERFORMANCE_OPTIMIZATION.md](references/PERFORMANCE_OPTIMIZATION.md) for:

  • Complete performance optimization guide
  • Core Web Vitals optimization strategies
  • Bundle analysis and tree shaking
  • Common pitfalls and solutions
  • Performance monitoring setup

Component Customization & Dark Mode

Customization Strategies

1. Direct Modification: Edit shadcn/ui files in your codebase 2. Variant Extension: Use CVA for type-safe variants 3. Wrapper Components: Add custom logic around base components 4. Theme Customization: Modify CSS variables globally

Dark Mode Setup

1. ThemeProvider with next-themes 2. Class strategy (class, not media query) 3. CSS variables in .dark class 4. Accessible toggle component

📖 See [CUSTOMIZATION.md](references/CUSTOMIZATION.md) for:

  • Complete customization strategies with examples
  • CVA variant implementation guide
  • Dark mode setup and configuration
  • Design considerations and testing
  • Form architecture patterns

Accessibility Standards

Radix UI Built-In Guarantees

  • ✅ ARIA attributes applied correctly
  • ✅ Keyboard navigation functional
  • ✅ Focus management and trapping automatic
  • ✅ Screen reader compatible

WCAG Contrast Requirements (Critical)

WCAG 2.1 Level AA (Legal Minimum):

  • Normal text: 4.5:1 minimum contrast ratio
  • Large text (18pt/14pt bold+): 3:1 minimum
  • UI components/graphics: 3:1 minimum
  • Industry standard: Most legal requirements specify AA

WCAG Level AAA (Enhanced):

  • Normal text: 7:1 contrast ratio
  • Large text: 4.5:1 contrast ratio
  • Best practice: Aim for AAA when design constraints allow

Measurement:

  • Contrast ratio range: 1:1 (white on white) to 21:1 (black on white)
  • Use tools: WebAIM Color Contrast Checker, browser DevTools
  • Test during design phase, not after implementation

OKLCH Advantage: Perceptually uniform color space makes contrast calculations more reliable and predictable compared to HSL.

Implementation Checklist

  • ✅ All text meets 4.5:1 minimum (AA standard)
  • ✅ Interactive elements meet 3:1 minimum
  • ✅ Provide descriptive labels (aria-label, <label>)
  • ✅ Test complete keyboard navigation flow
  • ✅ Verify visible focus indicators (not just browser default)
  • ✅ Test with screen readers (NVDA, JAWS, VoiceOver)
  • ✅ Use semantic HTML elements (<button>, <nav>, <main>)
  • ✅ Provide alternative text for images and icons
  • ✅ Ensure dark mode maintains contrast standards

Testing Strategy

1. Automated: Use contrast checkers during design 2. Manual: Tab through entire interface 3. Screen readers: Test with at least one screen reader 4. Real users: Include users with disabilities in testing

Common Pitfalls

Avoid these frequent issues: 1. Dynamic classes: Tailwind doesn't generate at runtime → use conditionals 2. Content config: Verify paths include all component files 3. Import paths: Check tsconfig.json aliases 4. Dark mode: Ensure ThemeProvider setup and CSS variables 5. Accessibility: Never remove ARIA attributes

📖 See [PERFORMANCE_OPTIMIZATION.md](references/PERFORMANCE_OPTIMIZATION.md#common-pitfalls) for complete troubleshooting guide with 10+ common issues and solutions.

Resources

Official Documentation

  • TailwindCSS: https://tailwindcss.com/docs
  • Radix UI: https://www.radix-ui.com/primitives
  • shadcn/ui: https://ui.shadcn.com | https://ui.shadcn.com/llms.txt

Authoritative Design System Sources

  • USWDS Design Tokens: https://designsystem.digital.gov/design-tokens/
  • Smashing Magazine Naming: https://www.smashingmagazine.com/2024/05/naming-best-practices/
  • OKLCH Color Space: https://evilmartians.com/chronicles/oklch-in-css-why-quit-rgb-hsl
  • WCAG Contrast: https://webaim.org/articles/contrast/

Reference Files (Detailed Guides & Patterns)

Core Concepts:

  • [DESIGN_TOKENS.md](references/DESIGN_TOKENS.md) - Three-tier token system, OKLCH, naming
  • [RESPONSIVE_PATTERNS.md](references/RESPONSIVE_PATTERNS.md) - Breakpoints, container queries, testing
  • [CUSTOMIZATION.md](references/CUSTOMIZATION.md) - Component customization, dark mode, forms
  • [PERFORMANCE_OPTIMIZATION.md](references/PERFORMANCE_OPTIMIZATION.md) - Performance, Core Web Vitals, pitfalls

Implementation References:

  • [TAILWIND_REFERENCE.md](references/TAILWIND_REFERENCE.md) - Complete utilities
  • [RADIX_REFERENCE.md](references/RADIX_REFERENCE.md) - Primitives with code
  • [SHADCN_REFERENCE.md](references/SHADCN_REFERENCE.md) - Components with install
  • [INTEGRATION_PATTERNS.md](references/INTEGRATION_PATTERNS.md) - Advanced patterns

Triggers & Use Cases

Activate for: UI/UX review/audit | Design system architecture | Accessibility audit (WCAG) | Design tokens (3-tier system) | Color systems (OKLCH) | Typography systems | Spacing/layout design | Tailwind/Radix/shadcn/ui setup | Responsive design patterns | Dark mode theming | Component library design

Do NOT activate for: React/Next.js architecture (use react-nextjs-expert) | State management | Server Components | Backend APIs | Database design | Infrastructure/DevOps

Behavioral Traits

Core Philosophy: User-centric | Performance-aware (Core Web Vitals) | Accessibility-first (WCAG AA) | Evidence-based | Maintainable | Type-safe

Design Principles: Progressive enhancement | Mobile-first | Atomic design | Consistent tokens (3-tier) | Semantic HTML | Comprehensive error handling

Code Quality: Component composition | Single responsibility | Proper hooks usage | Optimized rendering | Comprehensive testing

Response Approach

Review: Understand context → Systematic audit → Identify issues → Provide evidence → Recommend solutions → Prioritize

Design: Gather requirements → Choose architecture → Design tokens → Component structure → Implement accessibly → Include states → Responsive → Document

Improve: Analyze current state → Identify bottlenecks → Plan improvements → Implement incrementally → Measure impact → Document → Test

Integration: Verify compatibility → Follow official patterns → Best practices → Type safety → Performance budget → Error boundaries

Implementation Checklist

Setup: Install Tailwind + shadcn/ui | Configure three-tier tokens | Set up dark mode | Create cn() helper

Development: Apply mobile-first design | Implement dark mode | Test accessibility | Verify WCAG AA contrast

Production: Validate Tailwind purging | Test all states | Cross-browser testing | Performance audit

📖 Detailed checklists available in:

  • DESIGN_TOKENS.md
  • RESPONSIVE_PATTERNS.md
  • CUSTOMIZATION.md
  • PERFORMANCE_OPTIMIZATION.md

Best Practices Summary

Design Tokens: Three-tier system | OKLCH color space | Purpose-driven naming Accessibility: WCAG AA minimum (4.5:1 text, 3:1 UI) | Keyboard navigation | Screen readers Performance: Code splitting | Virtualization | Tailwind optimization Maintenance: Modular components | Documentation | Version control tokens

Skill Summary

Primary Functions: 1. Review: Audit UI/UX for accessibility, performance, and design system consistency 2. Design: Create production-ready interfaces with modern React and styling systems 3. Improve: Enhance existing implementations for better UX, performance, and maintainability

Technology Focus:

  • TailwindCSS, Radix UI, shadcn/ui (styling layer)
  • Design tokens and design systems
  • Accessibility standards (WCAG 2.1/2.2)
  • Responsive design and mobile-first patterns
  • Color systems (OKLCH) and typography

Activation Triggers:

  • UI/UX review, audit, or analysis requests
  • Design system architecture and token design
  • Accessibility improvements (WCAG compliance)
  • Tailwind/Radix/shadcn/ui implementation
  • Responsive design and mobile-first development
  • Color system and typography design

Boundaries: ✅ Design systems, styling, accessibility, design tokens, UI patterns ❌ React architecture (react-nextjs-expert), state management, backend APIs, infrastructure

---

Skill Version: 2.1.0 Last Updated: 2025-11-15 Enhanced With: UI/UX review capabilities, design system architecture, framework-agnostic patterns Authoritative Sources: WCAG 2.1/2.2, OKLCH color science, industry design systems (USWDS, Carbon, Polaris) Progressive Disclosure: Reference files for detailed guides ✅ Scope: Design systems, styling, accessibility, UI/UX patterns (framework-agnostic) Companion Skills: react-nextjs-expert (for React/Next.js architecture and state management)

Related skills

anthropicsFrontend DesignGenerate distinctive, production-grade frontend interfaces and components that avoid generic AI aesthetics.698k164kvercel-labsWeb Design GuidelinesAutomatically audit frontend code against the latest Vercel Web Interface Guidelines for consistency, accessibility, and UX quality.486k29.4klarksuiteLark WhiteboardGenerate valid Lark Whiteboard (Feishu Board) documents with correctly placed connectors, automatic routing, and proper schema compliance directly from agent inst382k15.8ksleekdotdesignSleek Design Mobile AppsGenerate mobile app screens and UI from plain English descriptions using the Sleek.design API.315k470leonxlnxDesign Taste FrontendOverride generic LLM frontend output with intentional, metric-driven UI/UX taste.284k66.9knextlevelbuilderUi Ux Pro MaxGet instant, high-quality UI/UX decisions, component recommendations, style guidance, and code improvements across web and mobile projects.282k109k

How it compares

Use ui-design-system for production React component systems with shadcn/ui; use canvas-design for single-page static poster or art PDF generation.

FAQ

What stack does ui-design-system standardize on?

ui-design-system targets TailwindCSS for styling, Radix UI for accessible primitives, and shadcn/ui for React components in Next.js apps. The skill version is 2.0.0 with framework-agnostic design patterns.

Which reference files ship with ui-design-system?

ui-design-system includes 7 progressive-disclosure guides: DESIGN_TOKENS.md, RESPONSIVE_PATTERNS.md, CUSTOMIZATION.md, PERFORMANCE_OPTIMIZATION.md, TAILWIND_REFERENCE.md, RADIX_REFERENCE.md, and SHADCN_REFERENCE.md.

Is Ui Design System safe to install?

skills.sh reports 2 of 3 security scanners passed. Review the Security Audits panel on this page before installing in production.

Design & UI/UXuiux
Browse by category
AI & AgentsFrontend & DesignBackend & DataDev ToolsAutomationTesting & ReviewSecurityMonitoring & CloudDocs & Planning
Design & frontend
Design systemsAnimation & motionAccessibility (a11y)CSS & TailwindUI designUXDesign to codeshadcn/uiLanding pagesBest design skills
Most searched skills
find-skillscavemanfrontend-designbrainstormingsystematic-debuggingstop-slopemil-design-engui-ux-pro-maxkarpathy-guidelinesweb-design-guidelinesreact-best-practicesgrill-meimprovemicrosoft-foundryagent-browser
Browse all listings
All agent skillsAll MCP serversAll marketplacesAll plugins

This week in AI coding

Five minutes, every Monday - the tools, releases and tactics for developers.

unsubscribe anytime.