npm package: @richard-netto/test-ds
Description: test-ds
Author: IORQ Team
Latest version: 0.1.10

# IORQ Design System

A comprehensive design system library for IORQ applications, providing reusable UI components, design tokens, and consistent styling.

## 🚀 Quick Start

### Installation

Install the design system from npm:

```bash
npm install iorq-ds
# or
yarn add iorq-ds
# or
pnpm add iorq-ds
```

**For local development (monorepo):**

```bash
npm install file:../iorq-ds
# or
yarn add file:../iorq-ds
# or
pnpm add file:../iorq-ds
```

### Usage

```typescript
// Import components
import { Button, Header, Page } from 'iorq-ds';
import type { ButtonProps, HeaderProps } from 'iorq-ds';

// Import global styles
import 'iorq-ds/styles/globals.css';
```

```tsx
export default function MyComponent() {
  return (
    <div>
      <Button variant="primary">Primary Button</Button>
      <Button variant="secondary">Secondary Button</Button>
    </div>
  );
}
```

## 📦 Available Components

- **Button**: Primary UI component with multiple variants (primary, secondary, tertiary)
- **Header**: Navigation header component
- **Page**: Base page layout component

## 🛠️ Development

### Tech Stack

- **React 19** - UI library
- **TypeScript** - Type safety
- **TailwindCSS 4** - Utility-first CSS framework
- **HeroUI** - Component foundation
- **Framer Motion** - Animation library
- **Hero Icons** - Icon system
- **Next.js 15** - Development framework
- **Storybook** - Component documentation
- **Vitest** - Testing framework
- **ESLint & Prettier** - Code quality

### Scripts

```bash
# Library Building
npm run build        # Build library for production
npm run build:fast   # Build library without type definitions (faster)
npm run clean        # Clean build artifacts

# Development
npm run dev          # Start Next.js dev server
npm run storybook    # Start Storybook dev server

# Testing
npm run test         # Run tests with coverage

# Code Quality
npm run lint         # Run ESLint

# Documentation
npm run build-storybook  # Build Storybook for production

# Publishing
npm run prepublishOnly   # Prepare package for publishing (auto-runs before publish)
```

### Project Structure

```
iorq-ds/
├── package/              # Component library source
│   ├── Button/          # Button component + tsconfig + tsup config
│   ├── Header/          # Header component + tsconfig + tsup config
│   ├── Page/            # Page component + tsconfig + tsup config
│   └── styles/          # Global styles and design tokens
├── dist/                # Built library files (generated)
├── stories/             # Storybook stories
├── app/                 # Next.js app (for development)
├── index.ts             # Main export file
├── tsup.config.ts       # Build configuration
└── package.json         # Package configuration
```

## 📖 Documentation

- **Storybook**: Run `npm run storybook` to view component documentation
- **Integration Guide**: See [DS_INTEGRATION.md](./DS_INTEGRATION.md) for setup instructions
- **Design Tokens**: Comprehensive color, typography, and spacing tokens available in global CSS

## 🎨 Design Tokens

The design system provides:

- **Colors**: Primary, secondary, tertiary, error, background, and surface colors
- **Typography**: Display, headline, title, label, and body text scales
- **Themes**: Built-in light and dark theme support
- **CSS Custom Properties**: For consistent theming across applications

## ✨ Features

- 🧪 **Comprehensive Testing** - Unit tests for all components
- 🎯 **Type Safety** - Full TypeScript support with exported types
- 📱 **Responsive Design** - Mobile-first responsive components
- 🌙 **Dark Mode** - Built-in light and dark theme support
- 🎨 **Customizable** - Extensive theming capabilities
- 📚 **Well Documented** - Storybook documentation for all components
- 🔧 **Developer Experience** - Hot reload, linting, and formatting

## 🤝 Contributing

### Creating New Components

1. Create a new folder in `package/` with the component name
2. Add the component file (e.g., `MyComponent.tsx`)
3. Add styles if needed (e.g., `myComponent.css`)
4. Export the component in `index.ts`
5. Create a Storybook story in `stories/`
6. Add tests for the component

### Styling Guidelines

- Use TailwindCSS utility classes for styling
- Follow the existing design token system
- Ensure components work in both light and dark themes
- [Storybook Theming Guide](https://storybook.js.org/docs/configure/user-interface/theming?renderer=react&ref=configure#create-a-theme-quickstart)

## 📦 Publishing to NPM

### Prerequisites

1. **Build the library**: `npm run build`
2. **Update version**: `npm version patch|minor|major`
3. **Login to npm**: `npm login`

### Publishing Steps

```bash
# 1. Clean and build
npm run clean && npm run build

# 2. Update version (choose one)
npm version patch    # 0.1.0 -> 0.1.1 (bug fixes)
npm version minor    # 0.1.0 -> 0.2.0 (new features)
npm version major    # 0.1.0 -> 1.0.0 (breaking changes)

# 3. Publish to npm
npm publish
```

### What gets published

- `dist/` folder (built components)
- `package/` folder (source components and styles)
- `README.md` and `DS_INTEGRATION.md`
- `package.json`

### Package Exports

The package provides a clean, simple import structure:

```typescript
// Import all components (tree-shaking friendly)
import { Button, Header, Page } from 'iorq-ds';
import type { ButtonProps, HeaderProps } from 'iorq-ds';

// Import styles
import 'iorq-ds/styles/globals.css';
```