DOL Figma Semantic Token Naming Convention
DOL Figma Semantic Token Naming
Section titled “DOL Figma Semantic Token Naming”Canonical rule cho naming semantic tokens trong Figma DS files. Decoupled theo usage context - không dùng feature names, không hardcode hex.
1. Four token categories by usage
Section titled “1. Four token categories by usage”DOL DS tokens split theo where they’re applied, không theo color alone. Mỗi category có prefix riêng:
| Prefix | Applied to | Example (role = info) |
|---|---|---|
fill/* | Background of frame, shape, auto-layout container | fill/info-dim (subtle tint), fill/info-soft (hover) |
text-color/* | Text node fills | text-color/info-primary |
icon-color/* | Icon vector fills - separate from text | icon-color/info-primary |
border-color/* | Stroke fills | border-color/progress-secondary (focus ring) |
Rule: pick prefix by the target property, not by visual result. Icon vector rendered same color as adjacent text → still uses icon-color/*, not text-color/*.
2. Semantic role mapping
Section titled “2. Semantic role mapping”Tokens never reference feature names (no cause-bg, effect-text). Always semantic role:
| Domain type | Semantic role | Rationale |
|---|---|---|
| Descr (description) | info | Informational content |
| Cause | warning | Attention/alert tone |
| Effect | success | Positive outcome |
Other domain types map tương tự theo tone. Rule of thumb:
- Neutral informational →
info - Cautionary / draws attention →
warning - Positive / confirmation →
success - Error / destructive →
danger - Brand identity →
brand(rarely in semantic context; see code UI rules for Brand ≠ Danger)
3. Intensity modifiers
Section titled “3. Intensity modifiers”Suffix sau role name để chọn shade:
| Modifier | Usage |
|---|---|
dim | Subtle tint - default background cho tags, pills, quiet states |
soft | 1 notch bolder - hover state, active state background |
primary | Main strong shade - text, icons, emphasis elements |
secondary | Alternate shade - focus ring stroke, subtle emphasis |
Full token name format: {prefix}/{role}-{modifier}.
Examples:
fill/info-dim- subtle info background (default)fill/info-soft- info hover backgroundtext-color/info-primary- info text contentborder-color/progress-secondary- global focus ring (progress = active state)
4. Rationale
Section titled “4. Rationale”- Decoupling fill / text / icon / border means a single semantic role can have different shades per usage context (text-primary ≠ bg-dim, both “info”).
- Feature-name tokens explode when same role applies to new features. Semantic roles are stable across feature evolution.
- Focus ring uses global
border-color/progress-secondary(not type-specific) → keeps focus UX consistent across all interactive elements regardless of component type.
5. Guardrails
Section titled “5. Guardrails”- Never bind a
text-color/*var to a background fill - check prefix matches target property. - Icon vectors get
icon-color/*, nottext-color/*- even if rendered same color as text. - When adding UI state (hover/disabled/focus), look for matching intensity modifier before inventing hex. Intensity scale is the design answer.
- If a needed token doesn’t exist (e.g., hover state for amber role):
- First: ask user / add to DS-Token
- Last resort: documented hex fallback
- Hex is a workaround, not a pattern - don’t repeat.
- When building from a reference component, extract its
boundVariablesto learn which semantic tokens it uses - shortest path to DS alignment.
6. Anti-patterns
Section titled “6. Anti-patterns”🛑 Match-and-refuse (Figma variant of DIRECTION §10 M&R): nếu bạn sắp bind token kiểu dưới, STOP - don’t normalize the workaround; flag missing token to user/DS team instead. Figma token drift has higher blast radius than code drift (many files inherit).
<dol_anti_pattern scope=“figma-naming-6-binding”>
| ID | ❌ PATTERN | Vì sao | ✅ REWRITE |
|---|---|---|---|
| 01 | Hardcoded hex in fills when matching token exists | Breaks DS-Token cascade; loses dark-mode + KID-mode variant propagation | Extract boundVariables from reference; bind semantic token |
| 02 | text-color/* applied to icon vectors (prefix mismatch) | Semantic category wrong - icons need icon-color/* even if same hex (enables future icon-specific mode variants) | Use icon-color/* for icon nodes (§1 4-category rule) |
| 03 | Feature-named tokens (cause-bg-color, effect-text-color) | Couples DS to feature naming; one rename in code breaks token linkage; semantic intent lost | Use role: info/warning/success/danger/brand (§2) |
| 04 | Inconsistent focus ring (per-component color) | Focus ring = global accessibility affordance; per-component variation breaks keyboard-nav visual consistency | Single global: border-color/progress-secondary across ALL components |
| 05 | Inventing new intensity modifier (e.g., “semi-soft”, “extra-dim”) | DS team not consulted → token never standardized; becomes orphan reference | Stop, ask user/DS team. If genuinely new, flag as DS-extension request; don’t ship inventions |
</dol_anti_pattern>
Related
Section titled “Related”- Sessional source:
ai-memory/lessons/dol-figma-semantic-token-naming.md(historical observation record) - Code-side color reference:
../../docs/tailwind-color-guideline.md - Design intent:
../ds-guideline/color.md - AI entry:
../ai-entry/FIGMA-AI.md