# How to Add Brand Colors to a Plugin in the OpenAI Plugins Repository

> Learn to add brand colors to your OpenAI plugin. Define design tokens, generate a Tailwind theme, and use utility classes for custom colors in your components.

- Repository: [OpenAI/plugins](https://github.com/openai/plugins)
- Tags: how-to-guide
- Published: 2026-06-28

---

**To add brand colors to a plugin, define them in the `designTokens` JSON within [`references/DESIGN_SYSTEM.md`](https://github.com/openai/plugins/blob/main/references/DESIGN_SYSTEM.md), let the Composer generate a Tailwind `@theme` block in [`src/styles/global.css`](https://github.com/openai/plugins/blob/main/src/styles/global.css), and consume them via utility classes like `bg-primary` and `text-accent` in your components.**

The OpenAI Plugins monorepo implements a strict design-system split that treats brand colors as versioned tokens rather than ad-hoc CSS classes. When you add brand colors to a plugin, you participate in a three-step pipeline that validates tokens at build time and guarantees zero runtime overhead.

## Step 1: Define Brand Colors in DESIGN_SYSTEM.md

The **Designer role** creates the single source of truth by editing [`references/DESIGN_SYSTEM.md`](https://github.com/openai/plugins/blob/main/references/DESIGN_SYSTEM.md) within the skill directory. This file must contain a JSON object called `designTokens` with a `colors` section mapping semantic names to hex values.

For example, in [`plugins/wix/skills/wix-headless/references/DESIGN_SYSTEM.md`](https://github.com/openai/plugins/blob/main/plugins/wix/skills/wix-headless/references/DESIGN_SYSTEM.md):

```json
{
  "designTokens": {
    "colors": {
      "primary": "#FF6B6B",
      "accent": "#2C3E50",
      "neutral": "#FFF5E6"
    },
    "font": { "display": "Inter", "body": "Roboto" },
    "spacing": { "md": "1rem", "lg": "2rem" }
  }
}

```

The Designer never writes to [`global.css`](https://github.com/openai/plugins/blob/main/global.css) directly; the JSON serves as the contract that downstream steps consume.

## Step 2: Emit the @theme Block via Composer

The **Composer role** reads the `designTokens` JSON and emits CSS custom properties into [`src/styles/global.css`](https://github.com/openai/plugins/blob/main/src/styles/global.css). According to the mapping logic in [[`COMPOSE.md`](https://github.com/openai/plugins/blob/main/COMPOSE.md)](https://github.com/openai/plugins/blob/main/plugins/wix/skills/wix-headless/references/COMPOSE.md), the Composer generates a Tailwind `@theme` block that transforms each token into a CSS variable:

```css
@layer theme {
  :root {
    --color-primary: #FF6B6B;
    --color-accent: #2C3E50;
    --color-neutral: #FFF5E6;
  }
}

```

This step occurs at build time, ensuring the runtime only processes standard Tailwind utilities.

## Step 3: Consume Tokens in Components

**Page and component authors** use Tailwind utilities derived from the theme tokens. The **Styling guide** [[`STYLING.md`](https://github.com/openai/plugins/blob/main/STYLING.md)](https://github.com/openai/plugins/blob/main/plugins/wix/skills/wix-headless/references/shared/STYLING.md) enforces a decision tree that requires token-based utilities over ad-hoc class names.

In an Astro component:

```astro
---
// plugins/wix/skills/wix-headless/astro/pages/home.astro
---
<section class="bg-primary text-neutral py-4xl">
  <h1 class="font-display text-2xl">Welcome to My Brand</h1>
  <p class="mt-2 text-accent">Our brand colors shine here.</p>
</section>

```

For one-off decorative elements that cannot use utilities, co-locate styles using the CSS variables directly:

```astro
<section class="relative py-4xl">
  <div class="hero-stamp">Made in small batches</div>
</section>

<style>
  .hero-stamp {
    position: absolute;
    bottom: var(--spacing-lg);
    right: var(--spacing-lg);
    background: rgba(27, 26, 23, 0.75);
    color: var(--color-primary);
    padding: 0.5rem 0.875rem;
    font-family: var(--font-display);
    font-style: italic;
  }
</style>

```

## Build-Time Validation and Safety

The architecture provides **build-time safety** by inlining the token contract into every prompt. If a component references a token not defined in `designTokens`—such as `bg-undefined`—the build triggers a `MISSING_TOKEN` error rather than silently dropping the class.

The separation of concerns ensures:

- **Single source of truth**: Colors defined once in [`DESIGN_SYSTEM.md`](https://github.com/openai/plugins/blob/main/DESIGN_SYSTEM.md)
- **Zero runtime overhead**: `@theme` variables are resolved at build time
- **Enforced consistency**: The decision tree in [`STYLING.md`](https://github.com/openai/plugins/blob/main/STYLING.md) prevents custom class proliferation

## Summary

- **Define** brand colors in [`references/DESIGN_SYSTEM.md`](https://github.com/openai/plugins/blob/main/references/DESIGN_SYSTEM.md) within the `designTokens.colors` JSON object.
- **Generate** the Tailwind `@theme` block automatically via the Composer step described in [`COMPOSE.md`](https://github.com/openai/plugins/blob/main/COMPOSE.md), which outputs to [`src/styles/global.css`](https://github.com/openai/plugins/blob/main/src/styles/global.css).
- **Consume** colors via Tailwind utilities (`bg-primary`, `text-accent`) in components, following the token-as-utility policy in [`STYLING.md`](https://github.com/openai/plugins/blob/main/STYLING.md).
- **Validate** tokens at build time; missing tokens trigger a `MISSING_TOKEN` error instead of silent failures.
- **Exception** handling for one-off styles uses co-located CSS with `var(--color-*)` references.

## Frequently Asked Questions

### Where do I define brand colors for my plugin?

You define them in the [`references/DESIGN_SYSTEM.md`](https://github.com/openai/plugins/blob/main/references/DESIGN_SYSTEM.md) file within your specific skill directory, such as [`plugins/your-plugin/skills/your-skill/references/DESIGN_SYSTEM.md`](https://github.com/openai/plugins/blob/main/plugins/your-plugin/skills/your-skill/references/DESIGN_SYSTEM.md). Create a JSON object called `designTokens` with a `colors` section containing your brand hex codes.

### Can I edit global.css directly to add new colors?

No. The [`src/styles/global.css`](https://github.com/openai/plugins/blob/main/src/styles/global.css) file is generated by the Composer based on the `designTokens` JSON. Direct edits would be overwritten. Always modify the `designTokens` in [`DESIGN_SYSTEM.md`](https://github.com/openai/plugins/blob/main/DESIGN_SYSTEM.md) and let the Composer regenerate the CSS.

### What happens if I use a color token that doesn't exist?

The build system will throw a `MISSING_TOKEN` error. Because the token contract is inlined into every prompt, the compiler validates that all referenced utilities (like `bg-primary`) have corresponding entries in `designTokens` before generating the site.

### How do I use brand colors for one-off decorative elements?

For elements that cannot use standard Tailwind utilities, use co-located styles within your component. Reference the CSS variables directly using `var(--color-primary)` or `var(--spacing-lg)`, as permitted by the co-location rule in [`STYLING.md`](https://github.com/openai/plugins/blob/main/STYLING.md).