npm package: @qodo/design-system
Description: The official design system powering Qodo's AI-driven development tools. Built with React, TypeScript, and Tailwind CSS to ensure our interfaces are as intelligent and intuitive as our code generation.
Latest version: 0.20.27

# Qodo Design System

The official design system powering Qodo's AI-driven development tools. Built with React, TypeScript, and Tailwind CSS to ensure our interfaces are as intelligent and intuitive as our code generation.

This isn't just another component library – it's the foundation that keeps our user experience consistent, accessible, and aligned with Qodo's mission to revolutionize how developers build software.

## 🚀 Getting Started

### Prerequisites

- Node.js 18+
- npm
- React 18+
- Tailwind CSS

### Installation

1. **Login to npm** (required for our private org packages):

```bash
npm login
```

2. **Install the design system**:

```bash
npm install @qodo/design-system
```

3. **Install peer dependencies** (if not already installed):

```bash
npm install react react-dom
```

### Setup

#### 1. Configure Tailwind CSS

Install Tailwind CSS in your project:

```bash
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p
```

#### 2. Import Styles

Add the design system styles to your main entry file (`src/index.css` or `src/globals.css`):

```typescript
@import "tailwindcss";
@import "@qodo/design-system/styles";
```

## 📦 Usage

### TLDR; Basic Usage

```typescript
import { Button } from "@qodo/design-system";

function App() {
  return (
    <Button variant="default">Click me</Button>
  );
}
```

The variant prop is optional and defaults to `default`.

### ⚠️ Strict Variant Usage – TypeScript-Protected

In the Qodo Design System, only specific variants are allowed. Using a variant that’s not explicitly defined will result in a TypeScript error at compile time. This ensures our components are always used correctly and consistently.

![variant-type-error](./assets/variant-type-error.png)

#### Sizes

```typescript
import { Button } from "@qodo/design-system";

function ButtonSizes() {
  return (
    <div className="flex items-center gap-2">
      <Button size="sm">Small</Button>
      <Button size="default">Default</Button>
      <Button size="lg">Large</Button>
      <Button size="icon">🚀</Button>
    </div>
  );
}
```

#### Custom Styling with className

You can extend styles using the `className` prop:

```typescript
import { Button } from "@qodo/design-system";

function CustomButton() {
  return (
    <div className="flex flex-col gap-2">
      {/* Add custom background */}
      <Button className="bg-purple-500 hover:bg-purple-600">
        Purple Button
      </Button>

      {/* Add custom spacing */}
      <Button className="px-8 py-3">
        Extra Padding
      </Button>

      {/* Add custom text styles */}
      <Button className="text-lg font-bold">
        Large Bold Text
      </Button>

      {/* Combine with variants */}
      <Button variant="outline" className="border-2 border-blue-500 text-blue-500">
        Custom Outline
      </Button>
    </div>
  );
}
```

### Running Storybook

```bash
npm run storybook
```

#### Qodo's Color Pallette

![storybook-1](./assets/storybook-1.png)

### Dark Mode

The design system supports dark mode through CSS variables. To enable dark mode, add the `dark` class to your HTML element:

```html
<html class="dark">
  <!-- Your app -->
</html>
```

## 🛠️ Local Development

When working on the design system locally, you have two main approaches to test your changes:

### Method 1: Using npm link (Recommended for active development)

This method creates a symlink between your local design system and your test project, allowing real-time updates.

**Setup (one-time):**

```bash
# In your design system directory
cd qodo-design-system
npm run build
npm link

# In your consuming project
cd your-project
npm link @qodo/design-system
```

**Development workflow:**

```bash
# Terminal 1: Design system with auto-rebuild
cd qodo-design-system
npm run dev  # This watches for changes and rebuilds automatically

# Terminal 2: Your consuming project
cd your-project
npm run dev  # Your app will automatically pick up changes
```

**Making changes:**

1. Edit your design system components
2. Save the file
3. The design system rebuilds automatically (if using `npm run dev`)
4. Your consuming project immediately sees the changes
5. No need to reinstall or relink!

**When to relink:**
Only relink when you change `package.json` exports or entry points:

```bash
# In design system directory
npm unlink
npm link

# In consuming project
npm unlink @qodo/design-system
npm link @qodo/design-system
```

**Cleanup when done:**

```bash
# In consuming project
npm unlink @qodo/design-system
npm install  # Reinstall the published version

# In design system directory
npm unlink  # Remove global link
```

### Method 2: Build and Install (For testing releases)

This method simulates the actual installation process and is useful for testing before publishing.

**Using npm pack:**

```bash
# In design system directory
npm run build
npm pack  # Creates qodo-design-system-0.1.0.tgz

# In consuming project
npm install /path/to/qodo-design-system-0.1.0.tgz
```

### Getting Help

If you encounter issues:

1. Check that you've followed all setup steps
2. Verify your Tailwind CSS configuration
3. Ensure you're using compatible versions of React and other dependencies
4. Reach out to the team on Slack

## 🚀 Deployment

The design system is automatically published to NPM through GitHub Actions. There are multiple ways to deploy new versions:

### Deployment

For more control over the release process:

0. **Prerequisites**: Bump version and commit to `main` branch (`npm version patch  # or minor, major`)
1. **Go to GitHub Actions** in your repository
2. **Select "Publish to NPM"** workflow
3. **Click "Run workflow"**
4. **Choose deployment type**:

#### New Version Deployment

- **Publish Type**: Select "New Version"
- **Version**: Choose `patch`, `minor`, `major`, or specify exact version (e.g., `1.2.3`)

#### Rollback/Republish Existing Version

- **Publish Type**: Select "Existing Tag"
- **Existing Tag**: Enter the tag to republish (e.g., `v1.0.0` or `1.0.0`)

### Before Deploying

Ensure your changes are ready:

```bash
# Test locally
npm run build
npm run lint
npm run format:check

# Test in Storybook
npm run storybook
```

### Deployment Requirements

**Setup Required (One-time):**

1. **NPM Token**: Create an automation token at [npmjs.com](https://www.npmjs.com/settings/tokens)
   - Go to your npm profile → "Access Tokens" → "Generate New Token"
   - Select "Automation" token type
   - Add as `NPM_TOKEN` secret in GitHub repository settings

2. **Slack Webhook** (Optional): Add `SLACK_WEBHOOK_URL` secret for notifications

**Package Access:**

- Ensure you have publish permissions to the `@qodo` npm organization
- The package name is `@qodo/design-system`

### Version Strategy

- **Patch** (`0.1.0` → `0.1.1`): Bug fixes, small improvements
- **Minor** (`0.1.0` → `0.2.0`): New components, new features, backward compatible
- **Major** (`0.1.0` → `1.0.0`): Breaking changes, API changes

### Rollback Process

If you need to rollback to a previous version:

1. Use the **"Existing Tag"** option in manual deployment
2. Enter the tag of the stable version (e.g., `v1.0.0`)
3. The workflow will republish that exact version

**Use cases for rollback:**

- Emergency fixes when current version has critical bugs
- NPM registry issues requiring republication
- Temporary rollback while investigating issues

### Post-Deployment

After deployment:

- Check the package is available: `npm view @qodo/design-system`
- Test installation in a test project
- Update dependent projects to use the new version
- Monitor for any issues in production

## 📚 What's Next

We're continuously expanding the design system. Coming soon:

- More component variants
- Additional components (Input, Modal, etc.)
- Storybook documentation
- Design tokens for animations and shadows