495 lines
12 KiB
Markdown
495 lines
12 KiB
Markdown
# /specweave-frontend:design-system-init
|
|
|
|
Initialize a complete design system with Atomic Design principles, design tokens, and component library.
|
|
|
|
You are an expert design system architect who creates scalable, maintainable component libraries.
|
|
|
|
## Your Task
|
|
|
|
Create a production-ready design system foundation with design tokens, theming, and Atomic Design component structure.
|
|
|
|
### 1. Design System Architecture
|
|
|
|
**Atomic Design Hierarchy**:
|
|
```
|
|
src/components/
|
|
├── atoms/ # Basic building blocks
|
|
│ ├── Button/
|
|
│ │ ├── Button.tsx
|
|
│ │ ├── Button.test.tsx
|
|
│ │ ├── Button.stories.tsx
|
|
│ │ └── index.ts
|
|
│ ├── Input/
|
|
│ ├── Text/
|
|
│ └── Icon/
|
|
├── molecules/ # Simple component groups
|
|
│ ├── FormField/ # Label + Input + Error
|
|
│ ├── SearchBar/ # Input + Button
|
|
│ └── Card/
|
|
├── organisms/ # Complex components
|
|
│ ├── Header/
|
|
│ ├── Footer/
|
|
│ ├── Form/
|
|
│ └── Navigation/
|
|
├── templates/ # Page layouts
|
|
│ ├── DashboardLayout/
|
|
│ ├── AuthLayout/
|
|
│ └── MarketingLayout/
|
|
└── pages/ # Full pages (if not using framework routing)
|
|
```
|
|
|
|
### 2. Design Tokens
|
|
|
|
**tokens/colors.ts**:
|
|
```typescript
|
|
export const colors = {
|
|
// Brand colors
|
|
brand: {
|
|
primary: {
|
|
50: '#eff6ff',
|
|
100: '#dbeafe',
|
|
500: '#3b82f6',
|
|
600: '#2563eb',
|
|
900: '#1e3a8a',
|
|
},
|
|
secondary: {
|
|
50: '#f0fdf4',
|
|
500: '#22c55e',
|
|
900: '#14532d',
|
|
},
|
|
},
|
|
// Neutral colors
|
|
neutral: {
|
|
white: '#ffffff',
|
|
black: '#000000',
|
|
50: '#fafafa',
|
|
100: '#f5f5f5',
|
|
500: '#737373',
|
|
900: '#171717',
|
|
},
|
|
// Semantic colors
|
|
semantic: {
|
|
success: '#22c55e',
|
|
warning: '#f59e0b',
|
|
error: '#ef4444',
|
|
info: '#3b82f6',
|
|
},
|
|
} as const;
|
|
```
|
|
|
|
**tokens/typography.ts**:
|
|
```typescript
|
|
export const typography = {
|
|
fontFamily: {
|
|
sans: ['Inter', 'system-ui', 'sans-serif'],
|
|
mono: ['Roboto Mono', 'monospace'],
|
|
},
|
|
fontSize: {
|
|
xs: '0.75rem', // 12px
|
|
sm: '0.875rem', // 14px
|
|
base: '1rem', // 16px
|
|
lg: '1.125rem', // 18px
|
|
xl: '1.25rem', // 20px
|
|
'2xl': '1.5rem', // 24px
|
|
'3xl': '1.875rem', // 30px
|
|
'4xl': '2.25rem', // 36px
|
|
},
|
|
fontWeight: {
|
|
normal: 400,
|
|
medium: 500,
|
|
semibold: 600,
|
|
bold: 700,
|
|
},
|
|
lineHeight: {
|
|
none: 1,
|
|
tight: 1.25,
|
|
normal: 1.5,
|
|
relaxed: 1.75,
|
|
},
|
|
} as const;
|
|
```
|
|
|
|
**tokens/spacing.ts**:
|
|
```typescript
|
|
export const spacing = {
|
|
0: '0',
|
|
1: '0.25rem', // 4px
|
|
2: '0.5rem', // 8px
|
|
3: '0.75rem', // 12px
|
|
4: '1rem', // 16px
|
|
5: '1.25rem', // 20px
|
|
6: '1.5rem', // 24px
|
|
8: '2rem', // 32px
|
|
10: '2.5rem', // 40px
|
|
12: '3rem', // 48px
|
|
16: '4rem', // 64px
|
|
20: '5rem', // 80px
|
|
} as const;
|
|
```
|
|
|
|
**tokens/index.ts**:
|
|
```typescript
|
|
export { colors } from './colors';
|
|
export { typography } from './typography';
|
|
export { spacing } from './spacing';
|
|
export { breakpoints } from './breakpoints';
|
|
export { shadows } from './shadows';
|
|
export { radii } from './radii';
|
|
export { transitions } from './transitions';
|
|
```
|
|
|
|
### 3. Theme Configuration
|
|
|
|
**theme/index.ts**:
|
|
```typescript
|
|
import { colors, typography, spacing } from '../tokens';
|
|
|
|
export const theme = {
|
|
colors,
|
|
typography,
|
|
spacing,
|
|
components: {
|
|
Button: {
|
|
variants: {
|
|
primary: {
|
|
bg: colors.brand.primary[500],
|
|
color: colors.neutral.white,
|
|
hover: {
|
|
bg: colors.brand.primary[600],
|
|
},
|
|
},
|
|
secondary: {
|
|
bg: 'transparent',
|
|
color: colors.brand.primary[500],
|
|
border: `1px solid ${colors.brand.primary[500]}`,
|
|
hover: {
|
|
bg: colors.brand.primary[50],
|
|
},
|
|
},
|
|
ghost: {
|
|
bg: 'transparent',
|
|
color: colors.neutral[700],
|
|
hover: {
|
|
bg: colors.neutral[100],
|
|
},
|
|
},
|
|
},
|
|
sizes: {
|
|
sm: {
|
|
height: '32px',
|
|
px: spacing[3],
|
|
fontSize: typography.fontSize.sm,
|
|
},
|
|
md: {
|
|
height: '40px',
|
|
px: spacing[4],
|
|
fontSize: typography.fontSize.base,
|
|
},
|
|
lg: {
|
|
height: '48px',
|
|
px: spacing[6],
|
|
fontSize: typography.fontSize.lg,
|
|
},
|
|
},
|
|
},
|
|
},
|
|
} as const;
|
|
|
|
export type Theme = typeof theme;
|
|
```
|
|
|
|
### 4. Component Template (Button)
|
|
|
|
**components/atoms/Button/Button.tsx**:
|
|
```typescript
|
|
import React from 'react';
|
|
import { cn } from '@/lib/utils';
|
|
|
|
export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
|
|
variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
|
|
size?: 'sm' | 'md' | 'lg';
|
|
isLoading?: boolean;
|
|
leftIcon?: React.ReactNode;
|
|
rightIcon?: React.ReactNode;
|
|
}
|
|
|
|
export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
|
|
(
|
|
{
|
|
children,
|
|
variant = 'primary',
|
|
size = 'md',
|
|
isLoading = false,
|
|
leftIcon,
|
|
rightIcon,
|
|
className,
|
|
disabled,
|
|
...props
|
|
},
|
|
ref
|
|
) => {
|
|
const baseStyles = 'inline-flex items-center justify-center font-medium rounded-lg transition-colors focus:outline-none focus:ring-2 focus:ring-offset-2';
|
|
|
|
const variants = {
|
|
primary: 'bg-blue-600 text-white hover:bg-blue-700 focus:ring-blue-500',
|
|
secondary: 'border border-blue-600 text-blue-600 hover:bg-blue-50 focus:ring-blue-500',
|
|
ghost: 'text-gray-700 hover:bg-gray-100 focus:ring-gray-500',
|
|
danger: 'bg-red-600 text-white hover:bg-red-700 focus:ring-red-500',
|
|
};
|
|
|
|
const sizes = {
|
|
sm: 'h-8 px-3 text-sm',
|
|
md: 'h-10 px-4 text-base',
|
|
lg: 'h-12 px-6 text-lg',
|
|
};
|
|
|
|
return (
|
|
<button
|
|
ref={ref}
|
|
className={cn(
|
|
baseStyles,
|
|
variants[variant],
|
|
sizes[size],
|
|
(disabled || isLoading) && 'opacity-50 cursor-not-allowed',
|
|
className
|
|
)}
|
|
disabled={disabled || isLoading}
|
|
{...props}
|
|
>
|
|
{isLoading && <LoadingSpinner className="mr-2" />}
|
|
{!isLoading && leftIcon && <span className="mr-2">{leftIcon}</span>}
|
|
{children}
|
|
{!isLoading && rightIcon && <span className="ml-2">{rightIcon}</span>}
|
|
</button>
|
|
);
|
|
}
|
|
);
|
|
|
|
Button.displayName = 'Button';
|
|
```
|
|
|
|
**components/atoms/Button/Button.test.tsx**:
|
|
```typescript
|
|
import { render, screen, fireEvent } from '@testing-library/react';
|
|
import { Button } from './Button';
|
|
|
|
describe('Button', () => {
|
|
it('renders correctly', () => {
|
|
render(<Button>Click me</Button>);
|
|
expect(screen.getByText('Click me')).toBeInTheDocument();
|
|
});
|
|
|
|
it('handles click events', () => {
|
|
const onClick = vi.fn();
|
|
render(<Button onClick={onClick}>Click me</Button>);
|
|
fireEvent.click(screen.getByText('Click me'));
|
|
expect(onClick).toHaveBeenCalledTimes(1);
|
|
});
|
|
|
|
it('shows loading state', () => {
|
|
render(<Button isLoading>Click me</Button>);
|
|
expect(screen.getByRole('button')).toBeDisabled();
|
|
});
|
|
|
|
it('applies variant styles', () => {
|
|
const { rerender } = render(<Button variant="primary">Primary</Button>);
|
|
expect(screen.getByRole('button')).toHaveClass('bg-blue-600');
|
|
|
|
rerender(<Button variant="secondary">Secondary</Button>);
|
|
expect(screen.getByRole('button')).toHaveClass('border-blue-600');
|
|
});
|
|
});
|
|
```
|
|
|
|
### 5. Storybook Integration
|
|
|
|
**components/atoms/Button/Button.stories.tsx**:
|
|
```typescript
|
|
import type { Meta, StoryObj } from '@storybook/react';
|
|
import { Button } from './Button';
|
|
|
|
const meta: Meta<typeof Button> = {
|
|
title: 'Atoms/Button',
|
|
component: Button,
|
|
tags: ['autodocs'],
|
|
argTypes: {
|
|
variant: {
|
|
control: 'select',
|
|
options: ['primary', 'secondary', 'ghost', 'danger'],
|
|
},
|
|
size: {
|
|
control: 'select',
|
|
options: ['sm', 'md', 'lg'],
|
|
},
|
|
},
|
|
};
|
|
|
|
export default meta;
|
|
type Story = StoryObj<typeof Button>;
|
|
|
|
export const Primary: Story = {
|
|
args: {
|
|
variant: 'primary',
|
|
children: 'Primary Button',
|
|
},
|
|
};
|
|
|
|
export const Secondary: Story = {
|
|
args: {
|
|
variant: 'secondary',
|
|
children: 'Secondary Button',
|
|
},
|
|
};
|
|
|
|
export const Loading: Story = {
|
|
args: {
|
|
variant: 'primary',
|
|
isLoading: true,
|
|
children: 'Loading...',
|
|
},
|
|
};
|
|
|
|
export const WithIcons: Story = {
|
|
args: {
|
|
variant: 'primary',
|
|
leftIcon: <IconPlus />,
|
|
children: 'Add Item',
|
|
},
|
|
};
|
|
```
|
|
|
|
### 6. Utility Function (cn)
|
|
|
|
**lib/utils.ts**:
|
|
```typescript
|
|
import { clsx, type ClassValue } from 'clsx';
|
|
import { twMerge } from 'tailwind-merge';
|
|
|
|
export function cn(...inputs: ClassValue[]) {
|
|
return twMerge(clsx(inputs));
|
|
}
|
|
```
|
|
|
|
### 7. TailwindCSS Configuration
|
|
|
|
**tailwind.config.ts**:
|
|
```typescript
|
|
import type { Config } from 'tailwindcss';
|
|
import { colors, typography, spacing } from './src/tokens';
|
|
|
|
const config: Config = {
|
|
content: ['./src/**/*.{js,ts,jsx,tsx,mdx}'],
|
|
theme: {
|
|
extend: {
|
|
colors: {
|
|
brand: colors.brand,
|
|
neutral: colors.neutral,
|
|
},
|
|
fontFamily: typography.fontFamily,
|
|
fontSize: typography.fontSize,
|
|
spacing,
|
|
},
|
|
},
|
|
plugins: [],
|
|
};
|
|
|
|
export default config;
|
|
```
|
|
|
|
### 8. Documentation Template
|
|
|
|
**components/atoms/Button/README.md**:
|
|
```markdown
|
|
# Button Component
|
|
|
|
A versatile button component with multiple variants and sizes.
|
|
|
|
## Usage
|
|
|
|
\`\`\`tsx
|
|
import { Button } from '@/components/atoms/Button';
|
|
|
|
<Button variant="primary" size="md" onClick={handleClick}>
|
|
Click me
|
|
</Button>
|
|
\`\`\`
|
|
|
|
## Props
|
|
|
|
| Prop | Type | Default | Description |
|
|
|------|------|---------|-------------|
|
|
| variant | 'primary' \| 'secondary' \| 'ghost' \| 'danger' | 'primary' | Button style variant |
|
|
| size | 'sm' \| 'md' \| 'lg' | 'md' | Button size |
|
|
| isLoading | boolean | false | Shows loading spinner |
|
|
| leftIcon | ReactNode | - | Icon before text |
|
|
| rightIcon | ReactNode | - | Icon after text |
|
|
|
|
## Examples
|
|
|
|
See Storybook for interactive examples.
|
|
```
|
|
|
|
### 9. Essential Dependencies
|
|
|
|
```json
|
|
{
|
|
"dependencies": {
|
|
"clsx": "^2.0.0",
|
|
"tailwind-merge": "^2.0.0"
|
|
},
|
|
"devDependencies": {
|
|
"@storybook/react": "^7.6.0",
|
|
"@testing-library/react": "^14.0.0",
|
|
"tailwindcss": "^3.4.0"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 10. Component Checklist
|
|
|
|
For each component, ensure:
|
|
- [ ] TypeScript props interface with JSDoc
|
|
- [ ] Accessibility (ARIA labels, keyboard navigation)
|
|
- [ ] Unit tests (>80% coverage)
|
|
- [ ] Storybook stories
|
|
- [ ] README documentation
|
|
- [ ] Responsive design
|
|
- [ ] Dark mode support (if applicable)
|
|
- [ ] Performance optimized (React.memo if needed)
|
|
|
|
## Workflow
|
|
|
|
1. Ask about design system requirements (brand colors, components needed)
|
|
2. Generate design tokens (colors, typography, spacing)
|
|
3. Set up theme configuration
|
|
4. Create component structure (Atomic Design)
|
|
5. Implement essential atoms (Button, Input, Text, Icon)
|
|
6. Add Storybook for component documentation
|
|
7. Configure Tailwind with design tokens
|
|
8. Provide usage guidelines and examples
|
|
|
|
## Example Usage
|
|
|
|
**User**: "Initialize a design system with blue brand color and Atomic Design"
|
|
|
|
**Response**:
|
|
Creates complete design system with:
|
|
- Design tokens (colors, typography, spacing)
|
|
- Theme configuration
|
|
- Atomic Design component structure
|
|
- Button, Input, Text components
|
|
- Storybook setup
|
|
- TailwindCSS integration
|
|
- Testing setup
|
|
- Documentation templates
|
|
|
|
## When to Use
|
|
|
|
- Starting new design systems
|
|
- Standardizing component libraries
|
|
- Rebranding existing applications
|
|
- Creating white-label products
|
|
- Building component libraries for teams
|
|
|
|
Build scalable, maintainable design systems with Atomic Design principles!
|