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:

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

For local development (monorepo):

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

Usage

// 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';

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

# 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 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

📦 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

# 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:

// 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';