Agent skill

design-system-foundation

Use when starting a new React Native or Next.js project to establish design system foundation - creates design tokens, folder structure, component architecture, and documentation scaffolding for consistent UI development

View SKILL.md on GitHub Repository
Stars 22
Forks 3

Install this agent skill to your Project

npx add-skill https://github.com/apexscaleai/claude-ui-design-system/tree/main/foundation/design-system-foundation

SKILL.md

Design System Foundation

Overview

Establishes complete design system foundation for greenfield projects, including token system, folder structure, and base component architecture.

When to Use

  • Starting new React Native app
  • Starting new Next.js project
  • Establishing design system for new product
  • Setting up component library from scratch
  • Need design tokens and theme system

When NOT to Use

  • Refactoring existing projects (use ui-refactoring-workflow instead)
  • Adding single component (use component-library-scaffolder instead)
  • Just documentation (use design-documentation-generator instead)

Foundation Setup Process

Phase 1: Design Token Creation

Creates complete token system with:

  • Colors: Semantic color system (brand, UI, feedback)
  • Typography: Font families, sizes, weights, line heights
  • Spacing: Consistent spacing scale
  • Shadows: Elevation system
  • Border Radius: Rounding scale
  • Animation: Timing and easing functions

Example Token Structure:

typescript
// tokens/colors.ts
export const colors = {
  // Brand colors
  brand: {
    primary: '#0066FF',
    secondary: '#00D9FF',
    accent: '#FF3366',
  },

  // UI colors
  ui: {
    background: {
      primary: '#FFFFFF',
      secondary: '#F8F9FA',
      tertiary: '#E9ECEF',
    },
    border: {
      light: '#DEE2E6',
      medium: '#CED4DA',
      dark: '#ADB5BD',
    },
    text: {
      primary: '#212529',
      secondary: '#495057',
      tertiary: '#6C757D',
      inverse: '#FFFFFF',
    }
  },

  // Feedback colors
  feedback: {
    success: '#28A745',
    warning: '#FFC107',
    error: '#DC3545',
    info: '#17A2B8',
  }
}

// tokens/spacing.ts
export const spacing = {
  0: 0,
  1: 4,
  2: 8,
  3: 12,
  4: 16,
  5: 20,
  6: 24,
  8: 32,
  10: 40,
  12: 48,
  16: 64,
  20: 80,
  24: 96,
}

// tokens/typography.ts
export const typography = {
  fontFamily: {
    sans: 'Inter, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto',
    mono: 'JetBrains Mono, Menlo, Monaco, "Courier New"',
  },
  fontSize: {
    xs: 12,
    sm: 14,
    base: 16,
    lg: 18,
    xl: 20,
    '2xl': 24,
    '3xl': 30,
    '4xl': 36,
    '5xl': 48,
  },
  fontWeight: {
    light: '300',
    normal: '400',
    medium: '500',
    semibold: '600',
    bold: '700',
    black: '900',
  },
  lineHeight: {
    tight: 1.25,
    normal: 1.5,
    relaxed: 1.75,
  }
}

// tokens/shadows.ts
export const shadows = {
  sm: {
    shadowColor: '#000',
    shadowOffset: { width: 0, height: 1 },
    shadowOpacity: 0.05,
    shadowRadius: 2,
    elevation: 1,
  },
  md: {
    shadowColor: '#000',
    shadowOffset: { width: 0, height: 4 },
    shadowOpacity: 0.07,
    shadowRadius: 6,
    elevation: 3,
  },
  lg: {
    shadowColor: '#000',
    shadowOffset: { width: 0, height: 10 },
    shadowOpacity: 0.1,
    shadowRadius: 15,
    elevation: 6,
  },
}

// tokens/radius.ts
export const radius = {
  sm: 4,
  md: 8,
  lg: 12,
  xl: 16,
  full: 9999,
}

Phase 2: Project Structure

Creates organized folder structure following atomic design:

src/
├── theme/
│   ├── tokens/
│   │   ├── colors.ts
│   │   ├── spacing.ts
│   │   ├── typography.ts
│   │   ├── shadows.ts
│   │   ├── radius.ts
│   │   ├── animation.ts
│   │   └── index.ts
│   ├── ThemeProvider.tsx
│   ├── useTheme.ts
│   └── createTheme.ts
│
├── components/
│   ├── atoms/           # Basic building blocks
│   │   ├── Button/
│   │   ├── Input/
│   │   ├── Text/
│   │   └── ...
│   ├── molecules/       # Simple combinations
│   │   ├── FormField/
│   │   ├── Card/
│   │   └── ...
│   ├── organisms/       # Complex components
│   │   ├── Header/
│   │   ├── Form/
│   │   └── ...
│   └── templates/       # Page layouts
│       ├── PageTemplate/
│       └── ...
│
├── design-system/
│   └── [Component folders with README.md]
│
└── docs/
    ├── DESIGN_SYSTEM.md
    ├── COMPONENT_GUIDELINES.md
    ├── STYLE_GUIDE.md
    ├── ACCESSIBILITY.md
    └── DESIGN_TOKENS.md

Phase 3: Theme System Setup

For React Native:

typescript
// theme/ThemeProvider.tsx
import React, { createContext, useContext } from 'react'
import { tokens } from './tokens'

interface Theme {
  colors: typeof tokens.colors
  spacing: typeof tokens.spacing
  typography: typeof tokens.typography
  shadows: typeof tokens.shadows
  radius: typeof tokens.radius
}

const ThemeContext = createContext<Theme | undefined>(undefined)

export const ThemeProvider: React.FC<{ children: React.ReactNode }> = ({ children }) => {
  const theme: Theme = {
    colors: tokens.colors,
    spacing: tokens.spacing,
    typography: tokens.typography,
    shadows: tokens.shadows,
    radius: tokens.radius,
  }

  return <ThemeContext.Provider value={theme}>{children}</ThemeContext.Provider>
}

export const useTheme = () => {
  const context = useContext(ThemeContext)
  if (!context) {
    throw new Error('useTheme must be used within ThemeProvider')
  }
  return context
}

For Next.js with Tailwind:

typescript
// tailwind.config.ts
import type { Config } from 'tailwindcss'
import { tokens } from './src/theme/tokens'

const config: Config = {
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
  theme: {
    extend: {
      colors: {
        brand: tokens.colors.brand,
        ui: tokens.colors.ui,
        feedback: tokens.colors.feedback,
      },
      spacing: tokens.spacing,
      fontSize: tokens.typography.fontSize,
      fontWeight: tokens.typography.fontWeight,
      borderRadius: tokens.radius,
    },
  },
}

export default config

Phase 4: Documentation Generation

Automatically generates:

  1. DESIGN_SYSTEM.md

    • Design philosophy
    • Token system overview
    • Component architecture
    • Usage guidelines

  2. COMPONENT_GUIDELINES.md

    • How to create components
    • Naming conventions
    • File structure
    • Testing requirements

  3. STYLE_GUIDE.md

    • Visual design principles
    • Color usage
    • Typography guidelines
    • Spacing system

  4. ACCESSIBILITY.md

    • WCAG standards
    • Testing checklist
    • Common patterns
    • Best practices

  5. DESIGN_TOKENS.md

    • Complete token reference
    • Usage examples
    • Migration guide

Phase 5: Preset Application

User selects design preset to apply:

  • minimalist-modern
  • bold-brutalist
  • soft-neumorphic
  • glass-aesthetic
  • timeless-classic
  • bleeding-edge-experimental

All tokens automatically configured to match selected preset.

Integration with Other Skills

  • After foundation setup, use component-library-scaffolder to create base components
  • For documentation updates, use design-documentation-generator
  • For preset selection, use design-preset-system

Quality Checklist

Before completing, verify:

  • ✓ All token files created
  • ✓ Folder structure established
  • ✓ Theme provider configured
  • ✓ Documentation generated
  • ✓ Design preset applied
  • ✓ TypeScript types defined
  • ✓ Example components work with tokens

Common Patterns

Using Tokens in Components

React Native:

typescript
import { useTheme } from '@/theme'

const MyComponent = () => {
  const theme = useTheme()

  return (
    <View style={{
      backgroundColor: theme.colors.ui.background.primary,
      padding: theme.spacing[4],
      borderRadius: theme.radius.md,
      ...theme.shadows.md,
    }}>
      <Text style={{
        fontSize: theme.typography.fontSize.lg,
        fontWeight: theme.typography.fontWeight.semibold,
        color: theme.colors.ui.text.primary,
      }}>
        Hello World
      </Text>
    </View>
  )
}

Next.js with Tailwind:

tsx
const MyComponent = () => {
  return (
    <div className="bg-ui-background-primary p-4 rounded-md shadow-md">
      <h2 className="text-lg font-semibold text-ui-text-primary">
        Hello World
      </h2>
    </div>
  )
}

Real-World Impact

Teams using this foundation report:

  • 70% faster component development
  • 90% reduction in style inconsistencies
  • Complete design token coverage
  • Easy design preset switching
  • Better developer experience

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

apexscaleai/claude-ui-design-system

aesthetic-excellence

Use when improving visual quality of existing UI - applies 2025 design principles for hierarchy, spacing systems, color theory, and typography excellence to elevate aesthetic appeal and user experience

22 3
Explore
apexscaleai/claude-ui-design-system

ui-refactoring-workflow

Use when refactoring existing React Native, Next.js, or TypeScript UI code to apply modern design principles and aesthetic excellence - analyzes current implementation, applies design presets, maintains functionality while elevating visual quality

22 3
Explore
apexscaleai/claude-ui-design-system

design-preset-system

Use when applying or switching design styles across UI components - provides preset design systems with tokens, patterns, and guidelines for different aesthetic approaches from timeless classics to bleeding-edge experimental styles

22 3
Explore
mattpocock/skills

handoff

Compact the current conversation into a handoff document for another agent to pick up.

111,310 9,758
Explore
mattpocock/skills

setup-pre-commit

Set up Husky pre-commit hooks with lint-staged (Prettier), type checking, and tests in the current repo. Use when user wants to add pre-commit hooks, set up Husky, configure lint-staged, or add commit-time formatting/typechecking/testing.

111,310 9,758
Explore
mattpocock/skills

obsidian-vault

Search, create, and manage notes in the Obsidian vault with wikilinks and index notes. Use when user wants to find, create, or organize notes in Obsidian.

111,310 9,758
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results