@nationaldesignstudio/react

React component library for the NDS Design System. Includes design tokens for Tailwind CSS v4 and React components.

Installation

npm install @nationaldesignstudio/react
# or
bun add @nationaldesignstudio/react
# or
pnpm add @nationaldesignstudio/react

Peer Dependencies

This package requires the following peer dependencies:

{
  "react": "^18.0.0 || ^19.0.0",
  "react-dom": "^18.0.0 || ^19.0.0",
  "tailwindcss": "^4.0.0"
}

Usage

1. Import Tokens

Import the tokens in your CSS file where you import Tailwind:

/* In your main CSS file (e.g., globals.css, styles.css) */
@import "tailwindcss";
@import "@nationaldesignstudio/react/tokens.css";

This imports:

• Design tokens as CSS variables (:root block)
• Tailwind CSS v4 @theme configuration
• Typography and spacing utility classes

2. Use Components

import { Button } from '@nationaldesignstudio/react'

function App() {
  return (
    <Button variant="primary" size="lg">
      Click me
    </Button>
  )
}

3. Use Design Tokens

The CSS includes all design tokens as CSS variables. Use them directly or via Tailwind classes:

// Using Tailwind classes (design tokens are registered in @theme)
<div className="text-blue-500 bg-gray-100 p-4">
  Content
</div>

// Using CSS variables directly
<div style={{ color: 'var(--color-blue-500)' }}>
  Content
</div>

Breakpoints

The design system uses three responsive breakpoints:

| Breakpoint | Min Width | Tailwind Prefix | |:-----------|:----------|:----------------| | sm | 320px | (default) | | md | 768px | md: | | lg | 1440px | lg: |

// Responsive padding
<div className="p-4 md:p-8 lg:p-12">Content</div>

Typography

Responsive Typography (Recommended)

Use responsive typography utilities that automatically scale across breakpoints:

<h1 className="typography-display-large">Responsive Display</h1>
<h2 className="typography-headline-medium">Responsive Headline</h2>
<p className="typography-body-medium">Responsive Body Text</p>

These classes automatically apply:

• Mobile (< 768px): brand-small typography
• Tablet (768px+): brand-medium typography
• Desktop (1440px+): brand-large typography

Available utilities:

| Category | Utilities | |:---------|:----------| | Display | typography-display-hero, typography-display-xl, typography-display-large, typography-display-medium, typography-display-small | | Headline | typography-headline-xl, typography-headline-large, typography-headline-medium, typography-headline-small | | Subheading | typography-subheading-large, typography-subheading-medium, typography-subheading-small | | Body | typography-body-large, typography-body-medium, typography-body-small | | Button | typography-button-large, typography-button-medium, typography-button-small | | Label | typography-label-large, typography-label-medium, typography-label-small | | Caption | typography-caption-large, typography-caption-small |

Weight variants: typography-headline-medium-semibold, typography-display-hero-regular, etc.

Static Typography

For fixed typography that doesn't change with screen size:

<h1 className="typography-brand-large-headline-medium">Always Large</h1>
<p className="typography-brand-small-body-medium">Always Small</p>

Components

Button

A versatile button component with multiple variants and sizes.

import { Button } from '@nationaldesignstudio/react'

// Variants
<Button variant="primary">Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="destructive">Destructive</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>
<Button variant="link">Link</Button>

// Sizes
<Button size="sm">Small</Button>
<Button size="default">Default</Button>
<Button size="lg">Large</Button>
<Button size="icon">Icon</Button>

// As child (polymorphic)
<Button asChild>
  <a href="/link">Link Button</a>
</Button>

Utilities

cn()

A utility function for merging Tailwind classes with proper precedence:

import { cn } from '@nationaldesignstudio/react'

<div className={cn('text-blue-500', isActive && 'text-red-500')}>
  Content
</div>

Package Exports

// Components
import { Button, buttonVariants } from '@nationaldesignstudio/react'
import type { ButtonProps } from '@nationaldesignstudio/react'

// Utilities
import { cn } from '@nationaldesignstudio/react'

/* Tokens (import in your CSS file) */
@import "@nationaldesignstudio/react/tokens.css";

Development

# Install dependencies
bun install

# Start Storybook for component development
bun run storybook

# Build the library
bun run build

# Type check
bun run type:check