npm package: @marom31/qwiik-design-system
Description: Qwiik Design System - Enterprise B2B SaaS logistics React component library
Author: Qwiik
Latest version: 0.1.0

# 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/`](./docs) directory:

### Setup & Verification
- [Setup Verification](./docs/SETUP-VERIFICATION.md) – Step-by-step verification checklist for local setup
- [Verification Report](./docs/VERIFICATION-REPORT.md) – Latest system verification results

### Design System Guidelines
- [Design System Rules](./docs/DESIGN_SYSTEM_RULES.md) – Core principles and conventions
- [Design Token Naming Guide](./docs/DESIGN_TOKEN_NAMING_GUIDE.md) – Token taxonomy and naming standards
- [Figma Integration Guide](./docs/FIGMA_INTEGRATION_GUIDE.md) – Syncing tokens with Figma

### Development Guides
- [Agent Guidelines](./docs/AGENTS.md) – Instructions for AI assistants working on this codebase
- [Claude Guidelines](./docs/CLAUDE.md) – Specific guidance for Claude AI assistant

### Project History
- [Phase 2 Summary](./docs/PHASE-2-SUMMARY.md) – Overview of Phase 2 implementation

## Installation

```bash
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:

```javascript
// 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:

```javascript
// 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
```bash
# 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](./CONTRIBUTING.md) for details on:
- Development workflow
- Code quality standards
- Commit conventions
- Pull request process

## License

MIT © Qwiik - See [LICENSE](./LICENSE) for details.