---
title: DOL Design System - AI Color Context
updated: 2026-04-30
status: active
ds_topic: color
related_docs:
  - repo: DS-Token
    path: docs/tailwind-color-guideline.md
    role: code-reference
  - repo: DS-Token
    path: docs/DS-Tailwind-Bridge-Guide.md
    role: narrative-entry-point
  - repo: DS-Token
    path: design-guideline/ui-style-guide/CORE.md
    role: unified-rule-reference
  - repo: DS-Token
    path: docs/color-system-rules.md
    role: decision-framework
---

# DOL Design System - AI Color Context

Paste this into any AI coding tool (Figma Make, Google AI Studio, v0, Cursor, etc.) as system prompt or context file so the AI uses DOL colors correctly.

---

## §1 Color System Rules

You are building UI for DOL Education platform using **Tailwind CSS v4**. All TW classes map to DS-Token CSS vars at build time - you write standard Tailwind, the build handles theming.

### Core convention

- **Numeric scale 50-950** for all colors (TW standard naming)
- **DOL canonical = `-600`** (NOT `-500` like TW default). DOL brand chuẩn = `bg-brand-600`.
- **Opacity modifiers** (`/80`, `/50`) work on all colors (TW v4 `color-mix()`)
- **Intent mapping:**
  - Brand = `bg-brand-*` (custom class - NOT `bg-red-*`)
  - Error/Danger = `bg-red-*`
  - Success = `bg-green-*`
  - Warning = `bg-amber-*`
  - Info = `bg-blue-*`
  - Special = `bg-purple-*`
  - **AI features / Smart actions = `bg-sky-*`** (per CORE §2.4 + playground code convention)
- **English skill semantic colors** (per CORE §2.4): Reading=`emerald-*`, Listening=`blue-*`, Writing=`amber-*`, Speaking=`rose-*`, Full Test=`purple-*`, AI=`sky-*`

---

## §2 Complete TW → DS-Token Mapping Table

Every Tailwind class below resolves to a DS-Token CSS var. Use these class prefixes instead of raw DS variable names in `className`.

### Shade scale mapping

| TW shade | DS shade | Role |
|----------|----------|------|
| `50` | `05` | Dimmest background |
| `100` | `10` | Soft background |
| `200` | `20` | Light accent / border |
| `300` | `40` | Medium-light |
| `400` | `60` | Medium |
| `500` | `80` | Medium-dark |
| **`600`** | **`100`** | **Canonical - brand/primary usage** |
| `700` | `120` | Hover / darker |
| `800` | `140` | Pressed / deep |
| `900` | `160` | Very dark |
| `950` | `180` | Darkest |

### Color families - ✅ SAFE to use

| TW class prefix | DS-Token family | Identity hex (-600) | Intent / khi nào dùng |
|----------------|-----------------|--------------------|-----------------------|
| **`brand-*`** | `primary-pr` | `#D42525` | DOL brand red - logo, CTA chính, accent |
| **`danger-*`** | `red-r` | `#E24B19` | Semantic alias for error/delete/alert |
| **`success-*`** | `green-g` | `#329546` | Semantic alias for correct/complete |
| **`warning-*`** | `yellow-y` | `#E0A011` | Semantic alias for caution/deadline |
| **`info-*`** | `blue-b` | `#2B52D4` | Semantic alias for link/active/info |
| **`special-*`** | `purple-p` | `#5B37D2` | Semantic alias for premium/gamification |
| `slate-*` | `neutral-n` | `#6C7885` | Text, borders, backgrounds - primary neutral |
| `red-*` | `red-r` | `#E24B19` | Danger/error. Brand is `brand-*`, not `red-*` |
| `orange-*` | `orange-or` | `#FB8D15` | True orange. Error is `red-*` / `danger-*` |
| `amber-*` | `yellow-y` | `#E0A011` | Warning, warm accent |
| `yellow-*` | `golden-gd` | `#DCB700` | Gold tones, award, achievement |
| `green-*` | `green-g` | `#329546` | Success, positive, nature |
| `blue-*` | `blue-b` | `#2B52D4` | Info, link, active state |
| `sky-*` | `deepsky-ds` | `#27A3CD` | **AI features / Smart actions** (per CORE §2.4) - primary class for AI UI |
| `cyan-*` | `wave-blue-wb` | `#00B3FF` | Bright cyan tech accent - alternative palette, prefer `sky-*` for AI features |
| `teal-*` | `teal-tl` | `#4DBAA9` | Teal accent |
| `purple-*` | `purple-p` | `#5B37D2` | Special, premium |
| `violet-*` | `purple-p` | `#5B37D2` | Alias of purple |
| `indigo-*` | `navy-blue-nb` | `#2FA5FF` | Navy/deep blue accent |
| `fuchsia-*` | `magenta-ma` | `#BF2598` | Magenta accent |
| `pink-*` | `pink-pi` | `#D94B67` | Pink, feminine accent |
| `rose-*` | `pink-pi` | `#D94B67` | Speaking skill / rose accent |
| `lime-*` | `lemon-le` | `#BBD015` | Lemon/lime accent, non-standard DS scale |
| `emerald-*` | `green-g` | `#329546` | Alias of green |
| `gray-*` | `neutral-n` | - | Alias of slate (prefer `slate-*`) |
| `zinc-*` | `neutral-n` | - | Alias of slate (prefer `slate-*`) |
| `stone-*` | `neutral-n` | - | Alias of slate (prefer `slate-*`) |
| `neutral-*` | `neutral-n` | - | Alias of slate (prefer `slate-*`) |

### DOL-specific first-class families

Use these when a DS color does not map cleanly to a standard Tailwind family.

| TW class prefix | DS-Token family | Identity hex (-600) | Intent / khi nào dùng |
|----------------|-----------------|--------------------|-----------------------|
| `cabaret-*` | `cabaret-ca` | `#D75F1E` | Cabaret / streak accent |
| `golden-*` | `golden-gd` | `#DCB700` | Golden highlight, awards |
| `deepsky-*` | `deepsky-ds` | `#27A3CD` | Explicit deepsky access |
| `wave-blue-*` | `wave-blue-wb` | `#00B3FF` | Wave blue / AI identity accent |
| `navy-blue-*` | `navy-blue-nb` | `#2FA5FF` | Navy/deep blue accent |
| `magenta-*` | `magenta-ma` | `#BF2598` | Magenta accent |
| `pink-pi-*` | `pink-pi` | `#D94B67` | Explicit DS pink access |
| `lemon-*` | `lemon-le` | `#BBD015` | Explicit lemon access |
| `paper-*` | `paper-pp` | `#DC934E` | Warm reading/paper accent |
| `dol-orange-*` | `orange-or` | `#FB8D15` | Legacy explicit true-orange alias |
| `bronze-*` | `bronze-bz` | `#EC983B` | Bronze / achievement tier |
| `plum-*` | `plum-pl` | `#CF91DA` | Plum accent |

### Special values

| TW class | DS-Token var | Behavior |
|----------|-------------|----------|
| `white` | `--neutral-n00` | Theme-aware: white in light, dark in dark mode |
| `black` | `--neutral-n200` | Theme-aware: dark in light, white in dark mode |
| `text-on-inverse-primary` | `--white-w100` | Always `#FFFFFF` - for text on colored bg |
| `text-on-inverse-secondary` | `--white-w70` | Always `rgba(255,255,255,0.7)` |
| `text-on-inverse-disabled` | `--white-w30` | Always `rgba(255,255,255,0.3)` |

### Raw DS token names are not Tailwind class prefixes

Do not write raw token names as classes (`bg-primary-pr100`, `bg-cabaret-ca100`, `text-red-r100`). Use the mapped Tailwind family instead (`bg-brand-600`, `bg-cabaret-600`, `text-red-600`).

Alpha families (`*-alpha-*`) are not exposed as Tailwind numeric families. Use opacity modifiers (`bg-brand-600/20`) first; use `var(--primary-alpha-pra50)` only in CSS when a semantic alpha token is explicitly required.

---

## §3 Standard Tailwind Usage

### Text hierarchy (neutral)

| Tailwind | Dùng cho |
|----------|----------|
| `text-slate-950` | Hero heading (emphasis only) |
| `text-slate-900` | Body text, card title, page title (default) |
| `text-slate-700` | Subtitle, secondary info, metadata |
| `text-slate-600` | Helper text, dim info, category label |
| `text-slate-500` | Placeholder, hint, disabled text |

### Surface hierarchy

| Tailwind | Dùng cho |
|----------|----------|
| `bg-white` | Card, modal, main content |
| `bg-slate-50` | Page background, subtle section, tab container |
| `bg-slate-100` | Skeleton, hover state, input background |
| `border-slate-200` | Default white surface border |
| `border-slate-100` | Subtle divider only |

### Text on colored backgrounds

CRITICAL: Use `text-on-inverse-primary` (always white) instead of `text-white` (swaps in dark mode).

```
text-on-inverse-primary    = always #FFFFFF (for text on brand/status bg)
text-on-inverse-secondary  = always rgba(255,255,255,0.7)
text-white                 = theme-aware white (becomes dark in dark mode!)
```

| Background | Text class | Reason |
|-----------|------------|--------|
| Vivid (500-600): `bg-brand-600`, `bg-blue-600` | `text-on-inverse-primary` | Fixed white, doesn't swap |
| Dark neutral (700+): `bg-slate-800` | `text-slate-50` or `text-white` | Theme token, swaps in dark |
| Light tint (50-200): `bg-blue-50` | `text-blue-700` or `text-slate-900` | Dark text on light bg |

### Focus & interaction

- Focus ring: `ring-blue-500` (NOT brand color)
- Shadow: `shadow-xs` (tiny), `shadow-sm` (small), `shadow-md` (medium), `shadow-lg` (large)

---

## §4 Common Patterns

```html
<!-- Card (flat, border-only) -->
<div class="bg-white border border-slate-200 rounded-xl">

<!-- Primary (brand) button -->
<button class="bg-brand-600 text-on-inverse-primary hover:bg-brand-700 rounded-lg px-4 py-2">

<!-- Secondary button -->
<button class="bg-white text-slate-900 border border-slate-200 hover:bg-slate-50 rounded-lg px-4 py-2">

<!-- Success badge -->
<span class="bg-green-50 text-green-600 px-2 py-1 rounded-full text-xs font-medium">

<!-- Error alert -->
<div class="bg-red-50 border border-red-100 text-red-700 p-3 rounded-lg">

<!-- Warning banner -->
<div class="bg-amber-50 border border-amber-100 text-amber-800 p-3 rounded-lg">

<!-- Header on brand bg -->
<header class="bg-brand-600 text-on-inverse-primary p-6">
  <h1 class="text-xl font-bold">Title</h1>
  <p class="text-on-inverse-secondary text-sm">Subtitle</p>
</header>

<!-- Input -->
<input class="border border-slate-200 bg-white text-slate-900 placeholder:text-slate-500
  focus:border-blue-600 focus:ring-2 focus:ring-blue-500 rounded-lg px-3 py-2">
```

---

## §5 DO NOT

- ❌ `bg-(--token)` or `var(--token)` in class attributes
- ❌ `bg-red-*` for brand color → use `bg-brand-*`
- ❌ `bg-orange-*` for error → use `bg-red-*` or `bg-danger-*`
- ❌ `text-white` for fixed-white on colored bg → use `text-on-inverse-primary`
- ❌ `gray-*`, `zinc-*`, `neutral-*` → use `slate-*`
- ❌ Hardcoded hex in class names (`bg-[#D42525]`)
- ❌ Semantic level names (`bg-brand-primary`) → use numeric (`bg-brand-600`)
- ❌ `-500` as canonical → DOL canonical is **`-600`**
- ❌ `shadow-sm` for tiny shadow → TW v4 renamed: use `shadow-xs` (tiny), `shadow-sm` (small)
- ❌ Raw DS token names as TW classes (`bg-cabaret-ca100`, `bg-primary-pr100`) → use mapped families (`bg-cabaret-600`, `bg-brand-600`)

---

## §6 Config Files Quick Reference

| What | Playground | Wiki | DS-Token (source) |
|------|-----------|------|-------------------|
| TW config | `tailwind.config.cjs` | `tailwind.config.ts` | - |
| Token CSS | `styles/tokens/tokens.generated.css` | `src/styles/tokens/tokens.generated.css` | `tokens/v4/color-base.css` |
| Remap CSS | `styles/tokens/palette-remap.generated.css` | - (inline in TW config) | `dist/css/dol-palette-remap.css` |
| Token regen | `npm run tokens:gen` | `npm run tokens:gen` | `npm run build` |
| Full color reference | - | - | `docs/tailwind-color-guideline.md` |
| Color system rules | - | - | `docs/color-system-rules.md` |
| UI style guide | - | - | `../ui-style-guide/CORE.md` (this repo) |

**Adding a new color family to a repo:**
1. Add mapping entry in the repo's `tailwind.config` (cjs/ts)
2. Run `npm run tokens:gen` - tree-shaker auto-includes referenced vars
3. Verify with build