Configuration

Sugarcoat is configured through a sugarcoat.config.ts file in your project root. This file defines your theme, colors, and other design system settings.

Basic Configuration#

// sugarcoat.config.ts
import { defineConfig } from "@sugarcoat/core";
 
export default defineConfig({
  theme: {
    brandColor: "iris",
    accentColor: "teal",
    grayColor: "slate",
    borderRadius: "lg",
    additionalColors: "*",
  },
});

Theme Options#

brandColor#

Your primary brand color used for buttons, links, and primary actions.

theme: {
  brandColor: "iris", // default
}

Available colors: tomato, red, ruby, crimson, pink, plum, purple, violet, iris, indigo, blue, cyan, teal, jade, green, grass, bronze, gold, brown, orange, amber, yellow, lime, mint, sky

accentColor#

A secondary color for accents and highlights.

theme: {
  accentColor: "teal", // default
}

Accepts the same color options as brandColor.

grayColor#

The neutral gray scale used for text, borders, and backgrounds.

theme: {
  grayColor: "slate", // default
}

Available gray scales:

Scale	Description
`gray`	Pure neutral gray
`slate`	Cool gray with blue tint
`mauve`	Gray with purple tint
`sage`	Gray with green tint
`olive`	Gray with yellow-green tint
`sand`	Warm gray with brown tint

borderRadius#

The default border radius scale for components.

theme: {
  borderRadius: "lg", // default
}

Available options:

Value	Description
`none`	No border radius (0px)
`sm`	Small radius
`md`	Medium radius
`lg`	Large radius
`xl`	Extra large radius
`full`	Fully rounded (pill shape)

additionalColors#

Include extra colors beyond brand/accent/gray.

// Include all colors
theme: {
  additionalColors: "*",
}
 
// Include specific colors
theme: {
  additionalColors: ["red", "green", "blue", "orange"],
}
 
// No additional colors (smallest bundle)
theme: {
  additionalColors: [],
}

Other Options#

include#

Files to scan for CSS class extraction.

export default defineConfig({
  include: [
    "../src/**/*.{js,jsx,ts,tsx}",
    "../app/**/*.{js,jsx,ts,tsx}",
    "../components/**/*.{js,jsx,ts,tsx}",
  ],
});

prefix#

CSS class prefix for generated styles.

export default defineConfig({
  prefix: "sui", // default
});

importMap#

The import alias for generated CSS utilities.

export default defineConfig({
  importMap: "@/.sugarcoat", // default
});

This allows you to import like:

import { css, cx } from "@/.sugarcoat/css";

outdir#

Output directory for generated files.

export default defineConfig({
  outdir: ".sugarcoat", // default
});

panda#

Advanced Panda CSS configuration overrides.

export default defineConfig({
  panda: {
    // Any valid Panda CSS config options
    hash: true,
    minify: true,
  },
});

Full Example#

// sugarcoat.config.ts
import { defineConfig } from "@sugarcoat/core";
 
export default defineConfig({
  theme: {
    brandColor: "blue",
    accentColor: "cyan",
    grayColor: "slate",
    borderRadius: "md",
    additionalColors: ["red", "green", "orange", "yellow"],
  },
  include: [
    "./src/**/*.{ts,tsx}",
    "./app/**/*.{ts,tsx}",
  ],
  prefix: "ui",
  importMap: "@/styles",
  panda: {
    hash: process.env.NODE_ENV === "production",
  },
});

Generated Files#

After running sugarcoat codegen, your configuration generates:

.sugarcoat/
├── panda.config.ts     # Panda CSS config (uses your settings)
├── index.ts            # Barrel export
└── generated/
    ├── css/            # css(), cx(), cva() functions
    ├── tokens/         # Design tokens (colors, spacing, etc.)
    ├── patterns/       # Layout patterns (stack, flex, grid)
    ├── recipes/        # Component style recipes
    ├── jsx/            # JSX factory components
    └── styles.css      # Extracted CSS

Using Generated Utilities#

CSS Function#

import { css } from "@/.sugarcoat/css";
 
function MyComponent() {
  return (
    <div className={css({ bg: "brand.default", color: "white", p: "4" })}>
      Styled with Sugarcoat
    </div>
  );
}

Design Tokens#

import { token } from "@/.sugarcoat/tokens";
 
const primaryColor = token("colors.brand.default");

Recipes#

import { button } from "@/.sugarcoat/recipes";
 
function MyButton() {
  return (
    <button className={button({ variant: "primary", size: "md" })}>
      Click me
    </button>
  );
}

TypeScript Configuration#

Ensure your tsconfig.json includes the path alias:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/.sugarcoat": ["./.sugarcoat/generated"],
      "@/.sugarcoat/*": ["./.sugarcoat/generated/*"]
    }
  }
}

Regenerating After Config Changes#

After modifying sugarcoat.config.ts, regenerate the CSS artifacts:

sugarcoat codegen

Or keep it running in watch mode during development:

sugarcoat dev