| name | semantic-coding |
| description | Replace hardcoded styles with semantic design tokens (colors, typography, spacing, sizing) across a codebase. Use when refactoring inline hex colors/px values to a design system, migrating to CSS variables or Tailwind theme tokens, or enforcing token consistency. |
Semantic Coding
Scan files, replace hardcoded styles with semantic design tokens (colors, typography, spacing, sizing), edit files directly.
Refactored from semantic-colors (color-only) into a comprehensive design system skill.
Usage
/semantic-coding [path]
DO NOT TOUCH (Non-Negotiable)
- Gradients:
from-*, via-*, to-*, bg-gradient-*, linear-gradient(), radial-gradient(), conic-gradient()
- SVG defs:
<linearGradient>, <radialGradient>, <stop>, url(#...), anything inside <defs>
- Glass morphism:
rgba(255,255,255,0.0x) overlays on gradient backgrounds
- Decorative shadows:
boxShadow glow effects tied to gradient LED/orb effects
- Animations:
@keyframes, animation timing values, transform values
- Template literals:
`border-${color}-500`, dynamic class construction
- Arbitrary values:
bg-[#hex], text-[14px], p-[20px] (JIT bracket syntax)
- Component props: Color/style values passed as non-className props (e.g.,
<Button color="red-500" />)
- Token source files:
globals.css, tailwind.config.*, tokens.ts, theme.ts
- Excluded dirs:
node_modules, .next, lib/generated, prisma/, dist/, __tests__/, *.test.*, *.spec.*
If a value is inside a protected context, skip and log ⚠ skipped (protected context).
Color Rules
Color Replacements
Note: Color-to-semantic mapping depends on your project's brand palette. The defaults below assume orange=brand, blue=info. If your brand uses blue/indigo/etc., map that family to brand instead and adjust accordingly.
| Hardcoded | Semantic |
|---|
text-red-*, text-rose-* | text-error |
text-green-*, text-emerald-*, text-teal-* | text-success |
text-yellow-*, text-amber-* | text-warning |
text-blue-*, text-cyan-* | text-info |
text-orange-* | text-brand |
text-indigo-*, text-violet-*, text-purple-* | text-primary |
text-pink-*, text-fuchsia-* | text-accent |
text-gray-*, text-slate-*, text-zinc-*, text-stone-*, text-neutral-*, text-ink-* | text-muted-foreground |
text-gray-900, text-slate-900, text-zinc-900 | text-foreground |
text-white (on semantic bg) | text-{bg-token}-foreground |
text-black | text-foreground |
bg-red-*, bg-rose-* (shade ≥500) | bg-error |
bg-red-*, bg-rose-* (shade <500) | bg-error/10 |
bg-green-*, bg-emerald-*, bg-teal-* (shade ≥500) | bg-success |
bg-green-*, , (shade <500) |
Foreground Pairing
| Background | Foreground |
|---|
bg-primary | text-primary-foreground |
bg-brand | text-brand-foreground |
bg-success | text-success-foreground |
bg-error | text-error-foreground |
bg-warning | text-warning-foreground |
bg-info | text-info-foreground |
Dark Mode Override Removal
Collapse light+dark pairs into one semantic token:
- className="text-green-600 dark:text-green-400"
+ className="text-success"
- className="bg-red-100 dark:bg-red-900/20 border-red-200 dark:border-red-800"
+ className="bg-error/10 border-error"
Typography Rules
Font Family
| Hardcoded | Semantic |
|---|
font-sans (body text) | font-body |
font-sans (headings) | font-heading |
font-mono | font-mono |
font-serif | font-display |
Inline fontFamily: 'Inter' | var(--font-body) |
Inline fontFamily: 'monospace' | var(--font-mono) |
Font Size (Text Scale)
| Hardcoded | Semantic | Use Case |
|---|
text-xs | text-caption | Labels, hints, timestamps |
text-sm | text-body-sm | Secondary content, metadata |
text-base | text-body | Body text, paragraphs |
text-lg | text-body-lg | Lead paragraphs, emphasis |
text-xl | text-heading-sm | Small headings, card titles |
text-2xl | text-heading-md | Section headings |
text-3xl | text-heading-lg | Page titles |
text-4xl, text-5xl | text-heading-xl | Hero headings |
text-6xl, text-7xl, text-8xl, text-9xl | text-display | Display/marketing headings |
Inline fontSize: '14px' | var(--text-body-sm) | |
Inline fontSize: '24px' | var(--text-heading-md) | |
Font Weight
| Hardcoded | Semantic | Use Case |
|---|
font-extralight (200) | font-thin | Decorative, display text |
font-light (300) | font-light | Subtle body text |
font-normal (400) | font-normal | Body text |
font-medium (500) | font-medium | Emphasis, labels |
font-semibold (600) | font-semibold | Subheadings |
font-bold (700) | font-bold | Headings, CTAs |
font-extrabold (800), font-black (900) | font-heavy | Display, marketing |
Line Height
| Hardcoded | Semantic | Use Case |
|---|
leading-none | leading-none | Display text, single-line |
leading-tight | leading-tight | Headings |
leading-snug | leading-snug | Subheadings |
leading-normal | leading-normal | Body text |
leading-relaxed | leading-relaxed | Long-form content |
leading-loose | leading-loose | Legal, fine print |
Letter Spacing
| Hardcoded | Semantic |
|---|
tracking-tighter | tracking-heading |
tracking-tight | tracking-heading |
tracking-normal | tracking-body |
tracking-wide | tracking-label |
tracking-wider | tracking-label |
tracking-widest + uppercase | tracking-overline |
Composite Typography Patterns
Match multi-class patterns before individual classes. Apply the first matching composite rule.
| Hardcoded Pattern | Semantic |
|---|
text-6xl+ font-bold/extrabold | text-display |
text-4xl font-bold tracking-tight | text-heading-xl |
text-3xl font-semibold | text-title |
text-2xl font-semibold | text-subtitle |
text-lg font-medium | text-lead |
text-base | text-body |
text-sm text-gray-* | text-muted |
text-xs uppercase tracking-wide | text-overline |
text-xs font-medium | text-label |
Spacing Rules
Semantic Spacing Scale
| Hardcoded | Semantic | Value |
|---|
p-1, m-1 | space-xs | 4px |
p-2, m-2 | space-sm | 8px |
p-3, m-3 | space-md | 12px |
p-4, m-4 | space-lg | 16px |
p-5, m-5 | space-xl | 20px |
p-6, m-6 | space-2xl | 24px |
p-8, m-8 | space-3xl | 32px |
p-10, m-10 | space-4xl | 40px |
p-12, m-12 | space-5xl | 48px |
Component Spacing Patterns
| Context | Recommended Token |
|---|
| Button padding | px-button py-button or p-4 |
| Card padding | p-card or p-6 |
| Section padding | p-section or py-12 px-6 |
| Input padding | px-input py-input or px-4 py-2 |
| Gap between items | gap-sm (8px), gap-md (12px), gap-lg (16px) |
| Stack spacing | space-y-sm, space-y-md, space-y-lg |
Sizing Rules
Width/Height
| Hardcoded | Semantic | Use Case |
|---|
w-4 h-4 | size-icon-xs | Small icons |
w-5 h-5 | size-icon-sm | Default icons |
w-6 h-6 | size-icon-md | Medium icons |
w-8 h-8 | size-icon-lg | Large icons |
w-10 h-10 | size-avatar-sm | Small avatars |
w-12 h-12 | size-avatar-md | Medium avatars |
w-16 h-16 | size-avatar-lg | Large avatars |
h-10, h-11 | h-input | Input/button height |
max-w-sm | max-w-form | Form container |
max-w-xl | max-w-content | Content container |
max-w-5xl | max-w-page | Page container |
Border Radius
| Hardcoded | Semantic | Use Case |
|---|
rounded | rounded-sm | Subtle rounding |
rounded-md | rounded-base | Default rounding |
rounded-lg | rounded-lg | Cards, modals |
rounded-xl | rounded-xl | Large cards |
rounded-2xl | rounded-2xl | Hero sections |
rounded-full | rounded-full | Pills, avatars |
Shadow Rules
| Hardcoded | Semantic | Use Case |
|---|
shadow-sm | shadow-sm | Subtle elevation |
shadow | shadow-base | Default elevation |
shadow-md | shadow-md | Cards |
shadow-lg | shadow-lg | Modals, dropdowns |
shadow-xl | shadow-xl | Popovers |
shadow-2xl | shadow-2xl | Floating elements |
shadow-success | shadow-success | Success glow |
shadow-error | shadow-error | Error glow |
Z-Index Rules
| Hardcoded | Semantic | Use Case |
|---|
z-0 | z-base | Default layer |
z-10 | z-dropdown | Dropdowns |
z-20 | z-sticky | Sticky headers |
z-30 | z-overlay | Overlays |
z-40 | z-modal | Modals |
z-50 | z-toast | Toasts, tooltips |
Inline Style Replacements
| Hardcoded | Semantic |
|---|
style={{ color: '#111827' }} | className="text-foreground" |
style={{ color: '#6b7280' }} | className="text-muted-foreground" |
style={{ backgroundColor: '#ffffff' }} | var(--color-background) |
style={{ fontSize: '14px' }} | var(--text-body-sm) |
style={{ fontWeight: 600 }} | className="font-semibold" |
style={{ padding: '16px' }} | className="p-4" or var(--space-lg) |
style={{ borderRadius: '8px' }} | var(--radius-base) |
Third-Party Config Pattern
When a library requires specific values at initialization, use runtime CSS variable resolution:
function cssVar(name, fallback) {
if (typeof window === 'undefined') return fallback;
return getComputedStyle(document.documentElement)
.getPropertyValue(name).trim() || fallback;
}
Initialize in useEffect (not module level) so CSS variables are available.
Scoped Token Pattern
When a page has a fixed dark background that doesn't change with theme, use var() with inline fallback:
color: 'var(--status-text-muted, #a1a1aa)'
Status Mapping
| Status | Semantic |
|---|
DRAFT | muted |
PENDING, SUBMITTED | warning |
CONFIRMED, SUCCESS, COMPLETED, PAID | success |
REJECTED, ERROR, CANCELLED | error |
INFO, SENT, RECEIVED | info |
Available Tokens Reference
Colors
Text: text-foreground, text-muted-foreground, text-primary, text-primary-foreground, text-brand, text-brand-foreground, text-accent, text-success, text-success-foreground, text-warning, text-warning-foreground, text-error, text-error-foreground, text-info, text-info-foreground
Background: bg-background, bg-card, bg-muted, bg-primary, bg-brand, bg-accent, bg-success, bg-warning, bg-error, bg-info, bg-overlay
Border: border-border, border-input, border-primary, border-brand, border-success, border-error, border-warning, border-info
Ring: ring-primary, ring-success, ring-error, ring-info
Shadow: shadow-success, shadow-error, shadow-info
Misc: divide-border, placeholder-muted-foreground
Typography
Font Family: font-body, font-heading, font-mono, font-display
Font Size: text-caption, text-body-sm, text-body, text-body-lg, text-heading-sm, text-heading-md, text-heading-lg, text-heading-xl, text-display
Composite: text-title, text-subtitle, text-lead, text-muted, text-overline, text-label
Font Weight: font-thin, font-light, font-normal, font-medium, font-semibold, font-bold, font-heavy
Letter Spacing: tracking-heading, tracking-body, tracking-label, tracking-overline
Line Height: leading-none, leading-tight, leading-snug, leading-normal, leading-relaxed, leading-loose
Spacing
Padding/Margin: space-xs, space-sm, space-md, space-lg, space-xl, space-2xl, space-3xl, space-4xl, space-5xl
Component: p-card, p-section, p-input, px-button, py-button
Gap: gap-xs, gap-sm, gap-md, gap-lg, gap-xl
Stack: space-y-sm, space-y-md, space-y-lg
Sizing
Icons: size-icon-xs, size-icon-sm, size-icon-md, size-icon-lg
Avatars: size-avatar-sm, size-avatar-md, size-avatar-lg
Containers: max-w-form, max-w-content, max-w-page
Input: h-input
Effects
Radius: rounded-sm, rounded-base, rounded-lg, rounded-xl, rounded-2xl, rounded-full
Shadow: shadow-sm, shadow-base, shadow-md, shadow-lg, shadow-xl, shadow-2xl
Z-Index: z-base, z-dropdown, z-sticky, z-overlay, z-modal, z-toast
Behavior
For each .tsx, .jsx, .ts, .js file in the target path (skip excluded dirs):
- Read the file
- Find hardcoded styles (colors, fonts, sizes, spacing)
- Check if inside protected context (gradient/SVG-def/animation)
- If safe → apply matching rule and edit immediately
- If protected context → skip, log as
⚠ skipped
After all files are done, re-scan to verify zero remaining violations. Print summary.
Summary Format
Semantic coding refactor: N files changed, M replacements
- file.tsx: colors (5), typography (3), spacing (2)
⚠ file.tsx:42 — skipped (gradient context)
⚠ file.tsx:88 — skipped (SVG defs)
