Initialization

The make-sugarcube init command automatically sets up your project with zero configuration required. This guide covers all the options and advanced scenarios.

npx make-sugarcube@latest init

That’s it! Sugarcube will auto-detect your project and set up everything.

Sugarcube automatically detects these frameworks:

Available starter kits for new projects:

• radix-fluid - Radix Design System with fluid spacing
• radix-fixed - Radix Design System with fixed spacing
• tailwind-fluid - Tailwind-inspired with fluid spacing
• tailwind-fixed - Tailwind-inspired with fixed spacing
• flexoki-fluid - Flexoki color system with fluid spacing
• flexoki-fixed - Flexoki color system with fixed spacing

If you have W3C-compliant token files, Sugarcube will detect and process them automatically.

Override the default directory structure:

npx make-sugarcube@latest init --tokens-dir=./tokens --styles-dir=./css

Choose a specific plugin:

npx make-sugarcube@latest init --plugin=vite
npx make-sugarcube@latest init --plugin=postcss
npx make-sugarcube@latest init --plugin=none

npx make-sugarcube@latest init --no-cube

Sugarcube supports two development workflows:

The plugin automatically regenerates CSS when you change tokens. This is the default approach.

Benefits of plugin-based:

• Instant feedback - See changes immediately in your browser
• Hot reload - CSS updates without page refresh
• Automatic management - _sugarcube.css regenerates when files are added/removed
• Seamless workflow - No manual commands needed during development
• Framework integration - Optimized for your build tool (Vite/PostCSS)

Perfect for dynamic development, rapid prototyping, and teams who want the smoothest possible workflow.

Skip plugin installation for a completely dependency-free workflow:

npx make-sugarcube@latest init --plugin=none
npx make-sugarcube@latest generate  # when you change tokens

Benefits of CLI-only:

• Zero runtime dependencies - No build tool plugins required
• Framework agnostic - Works with any project structure
• Simple CI/CD - Just run generate in your build process
• Full control - Regenerate exactly when you want to

Perfect for static sites, simple projects, or when you prefer manual control over automation.

After initialization, you can add pre-built UI components:

npx make-sugarcube@latest components

Available components include Button, Card, Dialog, Select, and more. Each component:

• Uses your design tokens automatically
• Includes CSS variables and utility classes
• Works with your chosen framework
• Installs any required dependencies

For more details, see the components guide.

After initialization, you’ll have:

your-project/
├── sugarcube.config.json     # Configuration
├── src/design-tokens/        # Token files
│   ├── colors.json
│   ├── spacing.json
│   └── typography.json
└── src/styles/              # Generated CSS
    ├── global/
    │   └── variables/
    │       └── tokens.variables.css
    ├── utilities/
    │   └── tokens.utilities.css
    └── _sugarcube.css       # CSS index file

The generated sugarcube.config.json is minimal and only includes settings that differ from defaults:

{
  "$schema": "https://sugarcube.sh/schema.json",
  "tokens": {
    "source": ["src/design-tokens/*.json"]
  },
  "utilities": {
    // Default utility configurations
  }
}

Only framework-specific paths or custom settings are included. Sugarcube uses sensible defaults for everything else.

If you have existing tokens and need to configure collections or themes, edit your sugarcube.config.json:

{
  "tokens": {
    "source": ["src/design-tokens/*.json"],
    "collections": {
      "core": {
        "source": ["colors.json", "spacing.json", "typography.json"],
        "themes": {
          "light": ["colors-light.json"],
          "dark": ["colors-dark.json"]
        }
      }
    }
  }
}

For detailed configuration options, see the configuration guide.

Sugarcube will use generic defaults. You can specify directories manually.

Install manually: npm install @sugarcube-org/vite or npm install @sugarcube-org/postcss

Sugarcube will overwrite existing files. Use --no-cube to skip CUBE CSS if you have existing CSS.

After initialization:

• Customize tokens
• Add components
• Configure collections
• Learn CUBE CSS