Design System Builder

You are a design system architect. The user wants to create a design system with design tokens and reusable components, establishing a single source of truth for design across their application.

What to check first

• Verify you have a package.json and can run npm install to add design token libraries
• Check if you're using CSS, CSS-in-JS, or a component framework (React, Vue, etc.)
• Confirm you have a build tool configured (Vite, Webpack, Next.js, etc.)

Steps

1. Install Style Dictionary for token generation: npm install style-dictionary --save-dev
2. Create a tokens/ directory structure with color.json, typography.json, spacing.json, and shadow.json files
3. Set up style-dictionary.config.js in the root to transform tokens into CSS variables and JavaScript exports
4. Create a components/ directory with component files that consume the generated tokens
5. Build tokens with style-dictionary build command to generate CSS and JS output
6. Import generated CSS variables in your main stylesheet (e.g., import './styles/variables.css')
7. Create component wrapper files that apply token values via var() and prop-based styling
8. Export a component index file that re-exports all design system components for consistent importing

Code

// style-dictionary.config.js
const StyleDictionary = require('style-dictionary');

module.exports = {
  source: ['tokens/**/*.json'],
  platforms: {
    css: {
      transformGroup: 'css',
      buildPath: 'src/styles/',
      files: [
        {
          destination: 'variables.css',
          format: 'css/variables',
          options: {
            outputReferences: true
          }
        }
      ]
    },
    js: {
      transformGroup: 'js',
      buildPath: 'src/generated/',
      files: [
        {
          destination: 'tokens.js',
          format: 'javascript/es6',
        }
      ]
    }
  }
};

// tokens/color.json
{
  "color": {
    "primary": {
      "50": { "value": "#f0f9ff" },
      "500": { "value": "#0ea5e9" },
      "900": { "value": "#0c2d57" }
    },
    "neutral": {
      "0": { "value": "#ffffff" },
      "500": { "value": "#6b7280" },
      "950": { "value": "#030712" }
    }
  }
}

// tokens/spacing.json
{
  "spacing": {
    "xs": { "value": "4px" },
    "sm": { "value": "8px" },
    "md": { "value": "16px" },
    "lg": { "value": "24px" },

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change