npm package: @ommakes/vois
Description: Vois Component Preview CLI — connect your project for live component previews
Latest version: 0.2.1

# @vois/cli

Command-line tool for syncing design tokens from Vois and generating code.

## Installation

```bash
npm install -g @vois/cli
# or
npx @vois/cli
```

## Commands

### `vois init`

Initialize Vois in your project. Creates a `vois.config.json` file.

```bash
vois init
```

Options:
- `-f, --force` - Overwrite existing config file

### `vois sync`

Sync design tokens from GitHub and generate code files.

```bash
vois sync
```

Options:
- `-c, --config <path>` - Path to config file (default: `vois.config.json`)
- `-o, --output <dir>` - Output directory override
- `--format <formats>` - Output formats (comma-separated: `tailwind,css,typescript`)
- `--dry-run` - Show what would be generated without writing files

## Configuration

Create a `vois.config.json` file in your project root:

```json
{
  "owner": "your-github-org",
  "repo": "your-design-system-repo",
  "branch": "main",
  "path": ".vois/system.json",
  "output": {
    "dir": "src/design-system",
    "formats": ["tailwind", "css", "typescript"]
  },
  "tailwind": {
    "configPath": "tailwind.config.ts",
    "prefix": ""
  },
  "css": {
    "selector": ":root",
    "darkModeSelector": ".dark"
  },
  "typescript": {
    "namespace": "tokens"
  }
}
```

### Configuration Options

| Option | Type | Description |
|--------|------|-------------|
| `owner` | string | GitHub organization or username |
| `repo` | string | Repository containing design tokens |
| `branch` | string | Branch to fetch from (default: `main`) |
| `path` | string | Path to system.json in repo (default: `.vois/system.json`) |
| `output.dir` | string | Directory for generated files |
| `output.formats` | array | Output formats to generate |
| `tailwind.configPath` | string | Path to Tailwind config |
| `tailwind.prefix` | string | Prefix for Tailwind classes |
| `css.selector` | string | Root selector for CSS variables |
| `css.darkModeSelector` | string | Dark mode selector |
| `typescript.namespace` | string | Namespace for TypeScript exports |

## Generated Files

### Tailwind Config (`tailwind.tokens.js`)

```javascript
// Generated by Vois CLI
module.exports = {
  colors: {
    primary: 'hsl(var(--color-primary))',
    secondary: 'hsl(var(--color-secondary))',
    // ...
  },
  spacing: {
    xs: '4px',
    sm: '8px',
    // ...
  },
};
```

Use in your `tailwind.config.ts`:

```typescript
import tokens from './src/design-system/tailwind.tokens.js';

export default {
  theme: {
    extend: {
      colors: tokens.colors,
      spacing: tokens.spacing,
    },
  },
};
```

### CSS Variables (`tokens.css`)

```css
/* Generated by Vois CLI */
:root {
  --color-primary: 220 90% 56%;
  --color-secondary: 262 83% 58%;
  --spacing-xs: 4px;
  --spacing-sm: 8px;
}

.dark {
  --color-primary: 220 90% 70%;
  --color-secondary: 262 83% 72%;
}
```

Import in your app:

```typescript
import './design-system/tokens.css';
```

### TypeScript Types (`tokens.ts`)

```typescript
// Generated by Vois CLI

export const tokensColors = {
  primary: 'hsl(220 90% 56%)',
  secondary: 'hsl(262 83% 58%)',
} as const;

export type TokensColor = keyof typeof tokensColors;

export const tokensSpacing = {
  xs: '4px',
  sm: '8px',
} as const;

export type TokensSpacing = keyof typeof tokensSpacing;

export function getColor(name: TokensColor): string {
  return tokensColors[name];
}

export function getSpacing(name: TokensSpacing): string {
  return tokensSpacing[name];
}
```

## Workflow

1. **Designer** updates tokens in Figma or web UI
2. **Vois** syncs changes to GitHub repository
3. **Engineer** runs `vois sync` to pull latest tokens
4. **Generated files** update Tailwind config, CSS, and types
5. **Code** automatically uses new design tokens

## CI/CD Integration

Add to your CI pipeline to keep tokens in sync:

```yaml
# .github/workflows/sync-tokens.yml
name: Sync Design Tokens

on:
  repository_dispatch:
    types: [design-tokens-updated]
  workflow_dispatch:

jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm install -g @vois/cli
      - run: vois sync
      - uses: peter-evans/create-pull-request@v5
        with:
          title: 'Update design tokens'
          commit-message: 'chore: sync design tokens from Vois'
```

## Troubleshooting

### "Design system not found"

- Verify the repository is public or you have access
- Check `owner` and `repo` in config are correct
- Ensure `.vois/system.json` exists in the repository

### "Configuration error"

- Run `vois init` to create a valid config file
- Check JSON syntax in `vois.config.json`

### "Failed to fetch"

- Check your internet connection
- Verify GitHub is accessible
- For private repos, set `GITHUB_TOKEN` environment variable

## License

MIT