@qodo/design-system

v0.19.2

Published

14 days ago

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.

Qodo Design System

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

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

npm login

Install the design system:

npm install @qodo/design-system

Install peer dependencies (if not already installed):

npm install react react-dom

Setup

1. Configure Tailwind CSS

Install Tailwind CSS in your project:

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

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

📦 Usage

TLDR; Basic Usage

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

Sizes

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:

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

npm run storybook

Qodo's Color Pallette

storybook-1

Dark Mode

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

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

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

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

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

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

# In design system directory
npm unlink
npm link

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

Cleanup when done:

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

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

Check that you've followed all setup steps
Verify your Tailwind CSS configuration
Ensure you're using compatible versions of React and other dependencies
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:

Prerequisites: Bump version and commit to main branch (npm version patch # or minor, major)
Go to GitHub Actions in your repository
Select "Publish to NPM" workflow
Click "Run workflow"
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:

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

# Test in Storybook
npm run storybook

Deployment Requirements

Setup Required (One-time):

NPM Token: Create an automation token at npmjs.com
- Go to your npm profile → "Access Tokens" → "Generate New Token"
- Select "Automation" token type
- Add as NPM_TOKEN secret in GitHub repository settings
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:

Use the "Existing Tag" option in manual deployment
Enter the tag of the stable version (e.g., v1.0.0)
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