@nathangosselin/design-system NPM

Design System

A modern, accessible, and customizable design system for React applications.

Features

🎨 Modern and consistent design language
♿️ Accessible components following WCAG guidelines
🎯 Fully typed with TypeScript
📦 Tree-shakeable and optimized bundle
🎭 Storybook documentation
🔧 Highly customizable theming
📱 Responsive by default
🧩 Built with a powerful component registry system

Installation

npm install @nathangosselin/design-system
# or
yarn add @nathangosselin/design-system

Usage

import { Button, Container, Grid, UIHeader } from '@nathangosselin/design-system';
import '@nathangosselin/design-system/styles.css';

// Add ThemeProvider to your app root
import { ThemeProvider } from '@nathangosselin/design-system';

function App() {
  return (
    <ThemeProvider>
      <Container>
        <Grid>
          <UIHeader level={2}>Welcome</UIHeader>
          <Button variant="primary">Click me</Button>
        </Grid>
      </Container>
    </ThemeProvider>
  );
}

CSS Usage

The design system includes all necessary styles in a single CSS file. Import it in your application's entry point:

// Example in a JavaScript/TypeScript entry file (e.g., main.jsx, _app.js)
import '@nathangosselin/design-system/styles.css';

// Your application code...

This import includes:

Base styles and CSS reset
Design tokens and CSS variables
Tailwind utility classes
Component-specific styles

Component Registry System

This design system uses a component registry approach to manage components. This provides several benefits:

Discoverability: Easily find available components and their documentation
Extensibility: Extend components with custom functionality
Consistency: Maintain a consistent API across all components
Documentation: Access metadata about each component

Component Categories

Components are organized into the following categories:

Layout: Components for page structure
- Container: Main container with max-width constraints
- ContentContainer: Container optimized for content areas
- FormContainer: Container optimized for forms
- ModalContainer: Container for modal dialogs
- CardContainer: Container for card-like elements
- MetricContainer: Container for metric displays
- Stack: Vertical stack layout
- Grid: Flexible grid system
- TwoColumnGrid, ThreeColumnGrid, FourColumnGrid: Pre-configured grid layouts
- ResponsiveGrid: Responsive grid with breakpoint control
Forms: Components for user input
- Button: Interactive button component
- Input: Text input field
- NewsletterSignup: Newsletter subscription form
Typography: Components for text styling
- Article Components: ArticleTitle, ArticleSubtitle, ArticleHeader, ArticleText, ArticleList, ArticleListItem, ArticleQuote
- Inline Components: Code, ColoredText, Emphasis, Strong, FootnoteText, FootnoteItem
- UI Components: UIHeader, UIDescription, Caption, MetaText, NavText, UIText
Navigation: Components for navigation
- Link: Navigation link component
Display: Utility components
- Icon: Icon component with built-in icon set

Using Component Metadata

You can access component metadata for your application:

import { componentRegistry } from '@nathangosselin/design-system';

// Get information about the Button component
const buttonInfo = componentRegistry.button;

console.log(buttonInfo);
// {
//   name: 'Button',
//   description: 'Interactive button component with multiple variants, icons, and loading states',
//   category: 'forms',
//   path: '../forms/button'
// }

Component Resolver

For advanced use cases, you can use the component resolver:

import { resolveComponent, getComponentsByCategory } from '@nathangosselin/design-system';

// Resolve a component by name
const Button = resolveComponent('button');

// Get all components in a specific category
const layoutComponents = getComponentsByCategory('layout');
// Returns metadata for Container, ContentContainer, FormContainer, ModalContainer,
// CardContainer, MetricContainer, Stack, Grid, and other layout components

function App() {
  return <Button>Click me</Button>;
}

Documentation

For full documentation, visit our Storybook.

Workflow Guides

We provide comprehensive guides for common workflows:

Component Migration Guide - How to migrate components from another project
Publishing Guide - How to publish updates to the NPM package
Consuming Guide - How to import and use the design system

For a complete list of guides, see the Guides Index.

Development

Prerequisites

Node.js >= 16
npm or yarn

Setup

Clone the repository

git clone https://github.com/nathangosselin/design-system.git
cd design-system

Install dependencies

npm install
# or
yarn install

Start development environment

npm run dev
# or
yarn dev

Commands

npm run dev - Start Storybook development environment
npm run build - Build for production
npm run test - Run tests
npm run storybook - Start Storybook
npm run lint - Run linting
npm run format - Format code

Local Testing

We use yalc for testing the package locally in other projects. This allows you to test your changes before publishing to npm.

Build and publish to local yalc store:

npm run test-local

In your test project, add the package:

yalc add @nathangosselin/design-system

For development with hot-reload:

# In design-system project
npm run watch-local

# In your test project
npm run dev # or your development command

The watch-local command will automatically push updates to all projects using yalc whenever you make changes.

To remove the package from your test project:

yalc remove @nathangosselin/design-system
npm install # or yarn install to restore original dependencies

Version Control

We use conventional commits to automate versioning and changelog generation. Commit messages should follow this format:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types:

feat: New feature
fix: Bug fix
docs: Documentation changes
style: Code style changes (formatting, etc)
refactor: Code refactoring
perf: Performance improvements
test: Adding or updating tests
chore: Maintenance tasks

Example:

feat(button): add size variants to Button component

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Font Installation

This design system includes custom fonts that need to be installed in your project. We've made this process as simple as possible:

# If the package is installed in your project:
npx designsystemfonts

# Or use the full package name:
npx @nathangosselin/design-system designsystemfonts

For automatic installation when dependencies change, add to your package.json:

"scripts": {
  "postinstall": "designsystemfonts"
}

This will copy all necessary font files to your project's public/fonts directory.

Running Storybook Locally

To run the Storybook documentation locally:

npm run dev

Theming

The design system supports multiple themes and primary colors:

<ThemeProvider
  theme="light" // 'light' | 'dark' | 'white' | 'system'
  primaryColor="ocean" // 'ocean' | 'sunset' | 'sun' | 'marine'
>
  <App />
</ThemeProvider>

Primary colors are defined using HSL values for consistent theming: