opencode-agent-kit/template/.opencode/skills/building-components/references/design-tokens.mdx

Multi-stack OpenCode agent toolkit — 33+ specialized AI agents, 200+ skills, 46 commands, 8 MCP servers (Nuxt, React, Node.js, Laravel, CI3, Android, Flutter, DevOps, SEO, SonarQube, and more)

---
title: Design Tokens
description: How semantic naming conventions and design tokens create a flexible, maintainable theming system.
type: conceptual
summary: Semantic CSS variable architecture for theming with layers of abstraction that separate what something is from how it looks.
prerequisites:
  - /styling
related:
  - /data-attributes
---

One of the core foundations of modern component libraries lies in their thoughtful approach to styling. Rather than hardcoding colors or creating rigid class systems, we can employ a semantic naming convention that separates the concerns of theme, context, and usage.

This semantic naming convention is known as design tokens. This architectural decision creates a maintainable, flexible system that scales beautifully across applications.

## The Philosophy of Semantic CSS Variables

Traditional CSS approaches often couple color values directly to their usage contexts, creating brittle systems that are difficult to maintain. Design tokens take a different approach by creating layers of abstraction that separate what something is from how it looks.

## Understanding the Variable Architecture

Let's examine how we can structure our CSS variables to create this flexible system:

```css title="globals.css"
@import "tailwindcss";
@import "tw-animate-css";

@custom-variant dark (&:is(.dark *));

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
}

:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
}

.dark {
  --background: oklch(0.145 0 0);
  --foreground: oklch(0.985 0 0);
  --primary: oklch(0.922 0 0);
  --primary-foreground: oklch(0.205 0 0);
}
```

In the above example, we have four design tokens:

- `--background`, which is used for background colors (primarily the background of the page)
- `--foreground`, which is used for foreground colors (the general text color)
- `--primary`, which is used for primary colors (the main color of the brand)
- `--primary-foreground`, which is used for primary foreground colors (the text color, as seen against the primary color)