---

name: design-system-conventions description: Guide for UI styling with semantic design system classes. Never use gray-* colors or arbitrary Tailwind utilities.

Design System Conventions Skill

Purpose

Enforce consistent styling using semantic design system classes. Prevent arbitrary Tailwind utilities and ensure visual consistency.

⚠️ CRITICAL: Never Use Generic Grays

FORBIDDEN: text-gray-*, bg-gray-*, border-gray-*

USE INSTEAD: Semantic tokens from the design system.

Color Token Reference

Opacity Variants

Use /80, /70, /60 suffixes for opacity:

Copy// ✅ CORRECT
<p className="text-foreground/80">Secondary text</p>

// ❌ WRONG
<p className="text-gray-600">Secondary text</p>

Typography Classes

ALWAYS use semantic classes, NEVER arbitrary text-* utilities for typography.

Examples

Copy// ✅ CORRECT
<h1 className="heading-1">Page Title</h1>
<p className="body-normal">Content here</p>

// ❌ WRONG
<h1 className="text-3xl md:text-4xl font-bold">Page Title</h1>
<p className="text-base">Content here</p>

Button Classes

Use semantic button classes (component coming in Week 4):

Copy// ✅ CORRECT
<button className="btn-primary">Submit</button>

// ❌ WRONG
<button className="bg-primary text-whiteCorp px-6 py-3 rounded-xl hover:bg-primarydark">
  Submit
</button>

Card Classes

Copy// ✅ CORRECT
<div className="card-bordered">
  <div className="card-body">
    <h3 className="heading-3">Card Title</h3>
    <p className="body-normal">Content</p>
  </div>
</div>

Badge Classes

Layout Utilities

Replace repetitive flex patterns:

Copy// ✅ CORRECT
<div className="flex-center gap-element-gap">
  <Icon />
  <span>Text</span>
</div>

// ❌ WRONG
<div className="flex justify-center items-center gap-4">
  <Icon />
  <span>Text</span>
</div>

Spacing Tokens

Tailwind Spacing Exception

Allowed: One-off micro-spacing inside leaf components (gap-1, gap-2, p-1, p-2)

Not allowed:

• Section/page/layout spacing
• Card/button/input paddings
• Shared components

Rule: If repeated → create/extend a semantic token instead.

Border Radius Tokens

Deprecated Aliases - DO NOT USE

❌ primarydark, primarySoft, whiteCorp, darkCorp, blackCorp, fullBlackCorp, bColor

Use semantic tokens instead.

Migration Context

Current Phase: Week 0 - Foundation

When modifying existing components:

1. Prefer semantic classes over inline utilities
2. Keep changes incremental
3. Consult /docs/reference-data.md for priority
4. Use new semantic color tokens

Checklist Before Styling

• Using semantic typography classes? (not text-xl font-bold)
• Using semantic color tokens? (not gray-*)
• Using button classes? (not inline utilities)
• Using card classes? (not custom shadows/borders)
• Using layout utilities? (flex-center vs manual flex)
• Using spacing tokens? (for consistent spacing)

Files to Reference

• styles/globals.css - Design system classes
• tailwind.config.js - Theme tokens
• docs/design-system-overview.md - Full documentation
• docs/implementation-reference.md - Code examples