npm package: @nationaldesignstudio/react
Description: React component library for the NDS Design System. Includes design tokens for Tailwind CSS v4 and React components.
Latest version: 0.7.0

# @nationaldesignstudio/react

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

## Installation

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

### Peer Dependencies

This package requires the following peer dependencies:

```json
{
  "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:

```css
/* 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

```tsx
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:

```tsx
// 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:` |

```tsx
// 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:

```tsx
<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:

```tsx
<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.

```tsx
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:

```tsx
import { cn } from '@nationaldesignstudio/react'

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

## Package Exports

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

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

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

## Development

```bash
# Install dependencies
bun install

# Start Storybook for component development
bun run storybook

# Build the library
bun run build

# Type check
bun run type:check
```