Using sugarcube

As we have seen in both the quick start and initialization guides, there are a number of different ways to use sugarcube. You can use it with CUBE CSS or without, with components or without. You can bring your own design tokens or you can use a starter kit.

In this guide, we’ll look at how to use sugarcube in each of these different contexts, starting with the most basic.

At its core, sugarcube is a tool for generating CSS variables from tokens. These variables are ready to use in your CSS:

body {
  background-color: var(--surface-primary);
  color: var(--text-primary);
  font-size: var(--font-size-base);
}

When you need to change a variable’s value, you’ll update it in your token files rather than editing the generated CSS directly. This may seem strange at first, but it is a powerful and efficient pattern.

For example, to update var(--surface-primary), you would update the token file like this:

{
    "surface": {
        "primary": { "value": "{color.neutral.50}" },
        "primary": { "value": "{color.neutral.200}" },
    }
}

If you installed a plugin during setup, your CSS will update automatically. Otherwise, run:

pnpm dlx make-sugarcube generate

npx make-sugarcube generate

yarn make-sugarcube generate

bunx --bun make-sugarcube generate

This will update your CSS variables to the new values:

:root {
  --surface-primary: var(--color-neutral-50);
  --surface-primary: var(--color-neutral-200);
}

While design tokens and CSS variables are powerful, they don’t constitute a full frontend foundation. You still need a consistent and scalable way to write your styles. That’s where CUBE CSS comes in.

When you add CUBE CSS to your project, you’ll get a directory structure that reflects its philosophy:

styles/
├── global/      # Global styles that handle typography, colors, and basic elements
├── compositions/# Flexible, component-agnostic layout systems that work with the browser
├── utilities/   # Single-purpose classes that do one job well, often generated from design tokens
└── blocks/      # Component styles for elements like cards or buttons

This structure reflects CUBE’s approach: start with global styles that leverage CSS’s cascade to do as much work as possible, then use compositions to create flexible layouts that work with the browser rather than against it. Utilities provide single-purpose helpers that often map directly to your design tokens, and blocks contain the styles for your components.

For a more complete guide to CUBE CSS, including its philosophy and principles, check out our CUBE CSS documentation.

Components in sugarcube are built to work seamlessly with your design tokens and CUBE CSS. With the exception of Label and Input, each component ships with two CSS files. For example, the Button component has a button.css file and a button.variables.css file.

.button {
  background-color: var(--button-bg);
  color: var(--button-text);
}

:root {
  --button-bg: var(--surface-primary);
  --button-text: var(--text-primary);
}

Why these two files? We find it easier to draw a distinction between the place where we author the component styles (e.g. button.css) and the place where we adjust the component variables (e.g. button.variables.css). It also makes powerful theming patterns easier to implement as the variables are not scoped to the class.

Why not include button vars in our design tokens? If you would prefer to work that way, go for it. Simply create the tokens in your token source directory and they will be included in the generated CSS. It is for mainly pragmatic reasons (i.e. not knowing ahead of time what components you will install) that we separate the two.

Here’s a quick example of using a button component:

import { Button } from '@/components/ui/button'

export default function Page() {
  return (
    <Button data-variant="secondary">
      Click me
    </Button>
  )
}

If you didn’t add components during initialization, you can add them later using the components command:

pnpm dlx make-sugarcube@latest components

npx make-sugarcube@latest components

yarn make-sugarcube@latest components

bunx --bun make-sugarcube@latest components

This is just a quick overview of how components work in sugarcube. For more detailed information, check out:

• Components documentation - Learn about component principles, integration with design tokens, and theming
• Individual component guides - Detailed documentation for each component, including examples and API reference