Configuration

When you initialize sugarcube, it creates a sugarcube.config.json file in your project root. This file is your control center for customizing how your design tokens are processed and where files are output.

Whether you want to change color output formats, adjust fluid typography settings, or reorganize your output directories, this is where you’ll do it.

Your configuration file is a JSON object with three main sections:

{
  "$schema": "https://sugarcube.style/schema.json",
  "tokens": {
    // Token configuration
  },
  "options": {
    // Global options
  },
  "output": {
    // Output configuration
  }
}

Let’s explore what each section does.

The tokens object tells sugarcube where to find your design tokens and how to organize them. You can set up collections (groups of related tokens) and themes (like dark mode) here.

Note: When you initialize sugarcube, this section is automatically configured for you:

• If you choose a starter kit, it sets up the token sources for you
• If you use your own tokens, the CLI guides you through organizing them into collections and themes

You only need to modify this section manually if you want to change how your tokens are organized after initialization.

Sugarcube offers two ways to organize your tokens:

1. Simple setup: A flat structure
2. Collections: Groups of related tokens

All your tokens live in a flat structure. Sugarcube uses glob patterns to automatically include all JSON files in your tokens directory:

{
  "tokens": {
    "source": ["src/design-tokens/*.json"],
    "type": "starter-kit",
    "themes": {
      "dark": [
        "src/design-tokens/dark.json"
      ]
    }
  }
}

Benefits of glob patterns:

• Automatically includes new token files (including component tokens)
• No need to manually update the config when adding files
• Cleaner, more maintainable configuration

This generates a single CSS file with theme variations:

:root {
  --color-primary: #0066cc;
  --spacing-small: 1rem;
}

[data-theme="dark"] {
  --color-primary: #66b3ff;
}

Collections let you group related tokens together:

{
  "tokens": {
    "base": {
      "source": [
        "src/design-tokens/base/colors.json",
        "src/design-tokens/base/spacing.json"
      ],
      "type": "custom",
      "themes": {
        "dark": [
          "src/design-tokens/base/dark/colors.json"
        ]
      }
    },
    "components": {
      "source": [
        "src/design-tokens/components/button.json"
      ],
      "type": "custom"
    }
  }
}

By default, this generates one CSS file per collection:

styles/
├── base/
│   └── tokens.variables.css
└── components/
    └── tokens.variables.css

If you set css.separate: true in your output configuration, each token file gets its own CSS file:

styles/
├── base/
│   ├── colors.variables.css
│   ├── spacing.variables.css
│   └── dark.variables.css
└── components/
    └── button.variables.css

Note: Collection names (like base and components above) are used as directory names in your CSS output. For example, tokens from the components collection will be generated in src/styles/global/variables/components/.

Note: Theme names (like dark above) are used as values in the data-theme attribute. For example, dark becomes data-theme="dark". See the Themes documentation for more about theming.

Note: Sugarcube will not overwrite your files. It will only ever create new files. That means that you will have to manually delete tokens.variables.css files if you toggle separate to true. Similarly, if you toggle separate back to false, you will have to manually delete the *.variables.css files that separate: true created.

Pro tip: Use the ** wildcard to include all files in a directory:

{
  "source": ["src/design-tokens/**/*.json"]
}

For more on collections and themes, see the Collections and Themes documentation.

When you install components using the components command, their design tokens are automatically integrated into your configuration:

Simple Mode: Component tokens are automatically picked up by glob patterns, so no config changes are needed.

Collections Mode: Component tokens are added to a dedicated components collection:

{
  "tokens": {
    "base": {
      "source": ["src/design-tokens/colors.json", "src/design-tokens/spacing.json"],
      "type": "custom"
    },
    "components": {
      "source": ["src/design-tokens/button.json", "src/design-tokens/card.json"],
      "type": "custom"
    }
  }
}

This ensures that component tokens are properly organized and CSS variables are generated for them automatically.

For more on collections and themes, see the Collections and Themes documentation.

The options section lets you configure global settings that affect how your tokens are processed. Here you can control things like color output format and fluid typography settings.

Configure how colors are handled and how fluid size and spacing works:

{
  "options": {
    "fluid": {
      "min": 320,  // Minimum viewport width in pixels (default: 320)
      "max": 1200  // Maximum viewport width in pixels (default: 1200)
    },
    "colorFallbackStrategy": "native" // Options: "native" | "polyfill" (default: "native")
  }
}

Sugarcube now supports the W3C Design Token Color Module specification with modern color spaces and the "none" keyword for missing color components.

Color fallback strategies:

• "native" (default): Outputs modern color formats directly. Best for modern browsers.
• "polyfill": Provides hex fallbacks with progressive enhancement using @supports. Best for maximum browser compatibility.

Supported color formats:

• Hex strings: "#ff0000", "#ff000080" (with alpha)
• W3C color objects: Modern color spaces with optional "none" components

{
  "colorSpace": "oklch",
  "components": [0.7, 0.3, 270],
  "alpha": 0.8,
  "hex": "#ff0000" // Optional fallback for polyfill mode
}

Supported color spaces:

• "oklch": Perceptually uniform color space
• "display-p3": Wide gamut color space
• "srgb": Standard RGB color space
• "hsl": Hue, saturation, lightness

The output object controls where and how your files are written. You can specify output directories and control how CSS files are organized.

{
  "output": {
    "directories": {
      "tokens": "src/design-tokens",
      "css": "src/styles",
      "components": "src/ui/components"
    },
    "css": {
      "separate": false
    }
  }
}

When css.separate is false (default), sugarcube generates one CSS file per collection. This is ideal for most projects as it keeps related tokens together. If, however, you prefer to have one CSS file per token file, you can set css.separate to true.

After updating your configuration, run:

pnpm dlx make-sugarcube@latest generate

npx make-sugarcube@latest generate

yarn make-sugarcube@latest generate

bunx --bun make-sugarcube@latest generate

This will:

1. Process your design tokens
2. Generate CSS variables
3. Update your CSS files

Note: If you’re using a plugin (like the Vite plugin), you may need to restart your development server for configuration changes to take effect. Plugins typically watch token files but not the configuration file.

Here’s a complete reference of all configuration options:

W3C Color Objects:

• "oklch": Perceptually uniform color space (e.g., oklch(0.628 0.225 27.23))
• "display-p3": Wide gamut color space (e.g., color(display-p3 1 0 0))
• "srgb": Standard RGB color space (e.g., rgb(255 0 0))
• "hsl": Hue, saturation, lightness (e.g., hsl(0 100% 50%))

Legacy formats (still supported):

• Hex strings (e.g., #ff0000, #ff000080)

Special features:

• "none" keyword: Use for missing color components (e.g., [0.7, "none", 270])
• Progressive enhancement: Polyfill mode provides hex fallbacks with @supports queries
• Alpha support: All color spaces support optional alpha values