@code-forage/design-system

A modern React + TypeScript design system following Atomic Design principles, inspired by Material UI's component architecture. Built with Storybook for documentation, Tailwind CSS v4 for styling, and Webpack for packaging.

🎨 Design Philosophy

• Simplicity & Consistency: Prioritize clarity, spacing, and friendly motion
• Accessible by Default: Components follow WCAG & ARIA standards
• Theming & Tokens: Design tokens for colors, typography, spacing, and shadows
• Composability: Each component is atomic, testable, and documented
• Personality: Soft corners, subtle motion, elegant typography

🚀 Installation

npm install @code-forage/design-system

📦 Usage

import { Button, Input, Card } from '@code-forage/design-system';

function App() {
  return (
    <div>
      <Button variant="primary" size="md">
        Click Me
      </Button>
      
      <Input 
        label="Email" 
        type="email" 
        placeholder="[email protected]" 
      />
      
      <Card variant="elevated" padding="lg">
        <CardHeader>
          <CardTitle>Welcome</CardTitle>
        </CardHeader>
        <CardContent>
          This is a card component.
        </CardContent>
      </Card>
    </div>
  );
}

🧩 Components (Atomic Design)

This design system follows the Atomic Design methodology, organizing components into atoms, molecules, and organisms.

Atoms (Basic Building Blocks)

Button - Interactive button with variants and sizes

<Button variant="primary" size="md">Click Me</Button>

Input - Text input with label, error, and helper text

<Input label="Email" type="email" error="Invalid email" />

Label - Form label with optional required indicator

<Label required>Full Name</Label>

Badge - Status indicator badge

<Badge variant="success">Active</Badge>

Avatar - User avatar component

<Avatar src="..." alt="User" size="md" />

Spinner - Loading spinner

<Spinner size="md" variant="primary" />

Molecules (Simple Combinations)

Card - Container with header, title, and content

<Card variant="elevated" padding="lg">
  <CardHeader><CardTitle>Title</CardTitle></CardHeader>
  <CardContent>Content</CardContent>
</Card>

FormField - Input with integrated label and error handling

<FormField label="Email" type="email" required />

SearchBox - Search input with button

<SearchBox onSearch={(value) => console.log(value)} />

Alert - Notification message

<Alert severity="success" title="Success!" onClose={handleClose} />

Modal - Dialog/modal overlay

<Modal open={isOpen} onClose={handleClose} title="Dialog">
  Content here
</Modal>

Tabs - Tab navigation

<Tabs tabs={[{ id: '1', label: 'Tab 1', content: <div>...</div> }]} />

Organisms (Complex Components)

Header - Site/app header

<Header logo={<Logo />} navigation={<Nav />} user={{ name: 'John' }} />

Form - Complete form with multiple fields

<Form 
  fields={formFields}
  onSubmit={(data) => handleSubmit(data)}
/>

Navigation - Navigation menu

<Navigation items={navItems} orientation="horizontal" />

DataTable - Data table component

<DataTable columns={columns} data={rows} onRowClick={handleClick} />

🎨 Design Tokens

Access design tokens for colors, typography, and spacing:

import { colors, typography, spacing } from '@code-forage/design-system';

// Colors
colors.coral[500] // #FF5A5F
colors.gray[100]  // #F7F7F7 (warm gray)
colors.charcoal   // #2B2D2E

// Typography
typography.fontSize.base
typography.fontWeight.medium

// Spacing
spacing[4] // 1rem (16px)

🛠️ Development

Prerequisites

• Node.js 18+
• npm or yarn

Setup

# Install dependencies
npm install

# Start Storybook
npm run dev

# Build the package
npm run build

# Run tests
npm test

# Lint code
npm run lint

# Format code
npm run format

📚 Storybook

View all components and their variations in Storybook:

npm run dev

Then open http://localhost:6006

🧪 Testing

npm test

Tests are written with Jest and React Testing Library.

📦 Building

The package is built with Rollup and outputs:

• dist/index.cjs - CommonJS bundle
• dist/index.esm.js - ES Module bundle
• dist/index.d.ts - TypeScript declarations

🚢 Publishing

Manual Publishing

npm publish --access public

Automated Publishing

This package uses semantic-release for automated versioning and publishing. When you push to main:

1. Semantic commits are analyzed
2. Version is automatically bumped
3. CHANGELOG.md is updated
4. Package is published to npm
5. GitHub release is created

Commit Message Format:

• feat: - New feature (minor version bump)
• fix: - Bug fix (patch version bump)
• BREAKING CHANGE: - Breaking change (major version bump)

🎨 Brand Colors

• Coral: #FF5A5F - Primary brand color
• Warm Gray: #F7F7F7 - Background color
• Charcoal: #2B2D2E - Text color

📁 Project Structure (Atomic Design)

codeforage-design-system/
├── src/
│   ├── components/
│   │   ├── atoms/       # Basic building blocks
│   │   │   ├── Button/
│   │   │   ├── Input/
│   │   │   ├── Label/
│   │   │   ├── Badge/
│   │   │   ├── Avatar/
│   │   │   ├── Icon/
│   │   │   └── Spinner/
│   │   ├── molecules/   # Simple combinations
│   │   │   ├── Card/
│   │   │   ├── FormField/
│   │   │   ├── SearchBox/
│   │   │   ├── Alert/
│   │   │   ├── Modal/
│   │   │   └── Tabs/
│   │   ├── organisms/   # Complex components
│   │   │   ├── Header/
│   │   │   ├── Form/
│   │   │   ├── Navigation/
│   │   │   └── DataTable/
│   │   └── templates/   # Page layouts (future)
│   ├── theme/           # Design tokens
│   │   ├── colors.ts
│   │   ├── typography.ts
│   │   └── spacing.ts
│   └── index.ts
├── .storybook/          # Storybook configuration
├── tests/              # Test files
├── dist/                # Build output
└── webpack.config.js    # Webpack configuration

See ATOMIC_DESIGN.md for detailed documentation.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

📄 License

MIT

🔗 Links

• Storybook Documentation
• Tailwind CSS
• React