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

To add brand colors to a plugin, define them in the designTokens JSON within references/DESIGN_SYSTEM.md, let the Composer generate a Tailwind @theme block in 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 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:

{
  "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 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. According to the mapping logic in [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:

@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/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:

---
// 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:

<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
• Zero runtime overhead: @theme variables are resolved at build time
• Enforced consistency: The decision tree in STYLING.md prevents custom class proliferation

Summary

• Define brand colors in references/DESIGN_SYSTEM.md within the designTokens.colors JSON object.
• Generate the Tailwind @theme block automatically via the Composer step described in COMPOSE.md, which outputs to src/styles/global.css.
• Consume colors via Tailwind utilities (bg-primary, text-accent) in components, following the token-as-utility policy in 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 file within your specific skill directory, such as 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 file is generated by the Composer based on the designTokens JSON. Direct edits would be overwritten. Always modify the designTokens in 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}