---
name: Theme Generation
description: Generate theme files from design tokens using style-dictionary
globs:
  - "**/tokens.json"
  - "**/theme.json"
  - "**/*.tokens.json"
  - "**/design-tokens/**"
alwaysApply: false
---

# Theme Generation

## Overview

This skill transforms design tokens into platform-specific theme files using Amazon Style Dictionary. Supports multiple output formats for different platforms and frameworks.

## When to Use

Use this skill when the user asks to:
- Generate CSS custom properties from tokens
- Create SCSS variables
- Export tokens to JSON
- Create JavaScript/TypeScript theme modules
- Build theme files for a design system

## Output Formats

### CSS Variables
```css
:root {
  --color-primary: #0066cc;
  --color-secondary: #6c757d;
  --spacing-sm: 8px;
  --spacing-md: 16px;
}
```

### SCSS Variables
```scss
$color-primary: #0066cc;
$color-secondary: #6c757d;
$spacing-sm: 8px;
$spacing-md: 16px;
```

### JSON Export
```json
{
  "color": {
    "primary": "#0066cc",
    "secondary": "#6c757d"
  },
  "spacing": {
    "sm": "8px",
    "md": "16px"
  }
}
```

### JavaScript Module
```javascript
export const color = {
  primary: '#0066cc',
  secondary: '#6c757d'
};

export const spacing = {
  sm: '8px',
  md: '16px'
};
```

## Workflow

1. **Prepare Tokens**
   - Ensure tokens are extracted or defined
   - Validate token structure
   - Organize by category

2. **Choose Format**
   - CSS for web projects with CSS custom properties
   - SCSS for projects using Sass
   - JSON for framework-agnostic export
   - JS for JavaScript/TypeScript projects

3. **Generate Theme**
   ```
   Use dss_generate_theme with tokens and format
   ```

4. **Review Output**
   - Check generated files
   - Verify variable names
   - Validate values

## Example Interaction

**User:** "Generate CSS theme files from the tokens we extracted"

**Assistant Response:**
```
I'll generate CSS theme files from your tokens.

[Uses dss_generate_theme with format: css]

**Generated Files:**

theme.css:
```css
:root {
  /* Colors */
  --color-primary: #0066cc;
  --color-primary-light: #3385d6;
  --color-primary-dark: #004c99;
  --color-secondary: #6c757d;

  /* Typography */
  --font-family-base: 'Inter', sans-serif;
  --font-size-base: 16px;
  --line-height-base: 1.5;

  /* Spacing */
  --spacing-xs: 4px;
  --spacing-sm: 8px;
  --spacing-md: 16px;
  --spacing-lg: 24px;
  --spacing-xl: 32px;
}
```

The theme file has been generated successfully. You can:
1. Import it directly into your main CSS
2. Use the variables in your components
3. Create dark mode variants

Would you like me to generate a dark mode theme as well?
```

## Theme Variants

### Light/Dark Mode
Generate separate themes for light and dark modes:
- `theme-light.css`
- `theme-dark.css`

### Brand Variants
Create multiple brand themes:
- `theme-brand-a.css`
- `theme-brand-b.css`

## Style Dictionary Features

| Feature | Description |
|---------|-------------|
| Transform Groups | Pre-defined transformations for each platform |
| Custom Transforms | Add custom value transformations |
| File Headers | Include comments and metadata |
| Filtering | Filter tokens by category or attributes |

## Related Tools

- `dss_generate_theme` - Main generation tool
- `dss_extract_tokens` - Get tokens first
- `dss_transform_tokens` - Convert between formats
- `dss_list_themes` - See available themes

## Best Practices

1. **Naming Convention**
   - Use consistent naming (kebab-case recommended)
   - Include category prefix (color-, spacing-, etc.)
   - Be descriptive but concise

2. **Token Organization**
   - Group by category
   - Use semantic names over values
   - Include descriptions for documentation

3. **Version Control**
   - Track generated files
   - Document token changes
   - Use semantic versioning