Qwiik Design System

Token-driven UI library for Qwiik's B2B logistics products. The repository currently focuses on establishing a reliable design token pipeline and iterating on the first wave of component prototypes.

Project status

• ✅ Design tokens compile to CSS variables, JS, Tailwind, and TypeScript via pnpm build:tokens
• ✅ Storybook runs locally with prototype components that consume the token set
• ✅ Generated stylesheet bundle (dist/styles.css) is now available for distribution
• ✅ Package entry point exports core components and utilities for consumption
• 🚧 Automated tests beyond the cn helper have not been authored yet

Documentation

Comprehensive guides and references are available in the docs/ directory:

Setup & Verification

• Setup Verification – Step-by-step verification checklist for local setup
• Verification Report – Latest system verification results

Design System Guidelines

• Design System Rules – Core principles and conventions
• Design Token Naming Guide – Token taxonomy and naming standards
• Figma Integration Guide – Syncing tokens with Figma

Development Guides

• Agent Guidelines – Instructions for AI assistants working on this codebase
• Claude Guidelines – Specific guidance for Claude AI assistant

Project History

• Phase 2 Summary – Overview of Phase 2 implementation

Installation

npm install @qwiik/design-system
# or
pnpm add @qwiik/design-system
# or
yarn add @qwiik/design-system

Usage

Option 1: With Pre-built Styles (Recommended)

Import the pre-built CSS bundle for instant use without Tailwind configuration:

// Import the stylesheet
import '@qwiik/design-system/dist/styles.css';

// Import components
import { Button, Input, Card } from '@qwiik/design-system';

function App() {
  return (
    <Button tone="brand" level="primary">
      Click me
    </Button>
  );
}

Option 2: With Tailwind Configuration (Advanced)

For advanced customization, configure Tailwind in your project to process the design system:

// tailwind.config.js
module.exports = {
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@qwiik/design-system/**/*.{js,ts,jsx,tsx}',
  ],
  // ... your config
};

Working locally

Prerequisites

• Node.js ≥ 18
• pnpm ≥ 9

Setup

# Install dependencies
pnpm install

# Start Storybook for component development
pnpm dev

# Regenerate tokens after editing files in design-tokens/ or components.json
pnpm build:tokens

Available scripts

• pnpm dev – Launch Storybook at http://localhost:6006
• pnpm build:tokens – Run the Style Dictionary pipeline and refresh generated artifacts
• pnpm build – Transform tokens, bundle JavaScript with tsup, and generate CSS bundle (dist/styles.css)
• pnpm lint – ESLint over src
• pnpm type-check – Run tsc --noEmit
• pnpm test / pnpm test:coverage – Vitest test runner (currently minimal coverage)
• pnpm test:e2e – Playwright suite scaffold

Token workflow

1. Update raw tokens in design-tokens/ or components.json
2. Execute pnpm build:tokens
3. Consume the generated outputs:
   • src/tokens/variables.css
   • src/tokens/tokens.js
   • src/tokens/tailwind-tokens.js
   • src/tokens/types.d.ts
   • tailwind.config.ts

Next steps

• Publish the core primitives from src/components once their APIs settle
• Expand automated tests to cover critical components and token usage scenarios
• Add comprehensive component documentation and examples

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Development workflow
• Code quality standards
• Commit conventions
• Pull request process

License

MIT © Qwiik - See LICENSE for details.