1# Styling & Customization
2 
3See [customization.md](../customization.md) for theming, CSS variables, and adding custom colors.
4 
5## Contents
6 
7- Semantic colors
8- Built-in variants first
9- className for layout only
10- No space-x-* / space-y-*
11- Prefer size-* over w-* h-* when equal
12- Prefer truncate shorthand
13- No manual dark: color overrides
14- Use cn() for conditional classes
15- No manual z-index on overlay components
16 
17---
18 
19## Semantic colors
20 
21**Incorrect:**
22 
23```tsx
24<div className="bg-blue-500 text-white">
25  <p className="text-gray-600">Secondary text</p>
26</div>
27```
28 
29**Correct:**
30 
31```tsx
32<div className="bg-primary text-primary-foreground">
33  <p className="text-muted-foreground">Secondary text</p>
34</div>
35```
36 
37---
38 
39## No raw color values for status/state indicators
40 
41For positive, negative, or status indicators, use Badge variants, semantic tokens like `text-destructive`, or define custom CSS variables — don't reach for raw Tailwind colors.
42 
43**Incorrect:**
44 
45```tsx
46<span className="text-emerald-600">+20.1%</span>
47<span className="text-green-500">Active</span>
48<span className="text-red-600">-3.2%</span>
49```
50 
51**Correct:**
52 
53```tsx
54<Badge variant="secondary">+20.1%</Badge>
55<Badge>Active</Badge>
56<span className="text-destructive">-3.2%</span>
57```
58 
59If you need a success/positive color that doesn't exist as a semantic token, use a Badge variant or ask the user about adding a custom CSS variable to the theme (see [customization.md](../customization.md)).
60 
61---
62 
63## Built-in variants first
64 
65**Incorrect:**
66 
67```tsx
68<Button className="border border-input bg-transparent hover:bg-accent">
69  Click me
70</Button>
71```
72 
73**Correct:**
74 
75```tsx
76<Button variant="outline">Click me</Button>
77```
78 
79---
80 
81## className for layout only
82 
83Use `className` for layout (e.g. `max-w-md`, `mx-auto`, `mt-4`), **not** for overriding component colors or typography. To change colors, use semantic tokens, built-in variants, or CSS variables.
84 
85**Incorrect:**
86 
87```tsx
88<Card className="bg-blue-100 text-blue-900 font-bold">
89  <CardContent>Dashboard</CardContent>
90</Card>
91```
92 
93**Correct:**
94 
95```tsx
96<Card className="max-w-md mx-auto">
97  <CardContent>Dashboard</CardContent>
98</Card>
99```
100 
101To customize a component's appearance, prefer these approaches in order:
1021. **Built-in variants** — `variant="outline"`, `variant="destructive"`, etc.
1032. **Semantic color tokens** — `bg-primary`, `text-muted-foreground`.
1043. **CSS variables** — define custom colors in the global CSS file (see [customization.md](../customization.md)).
105 
106---
107 
108## No space-x-* / space-y-*
109 
110Use `gap-*` instead. `space-y-4` → `flex flex-col gap-4`. `space-x-2` → `flex gap-2`.
111 
112```tsx
113<div className="flex flex-col gap-4">
114  <Input />
115  <Input />
116  <Button>Submit</Button>
117</div>
118```
119 
120---
121 
122## Prefer size-* over w-* h-* when equal
123 
124`size-10` not `w-10 h-10`. Applies to icons, avatars, skeletons, etc.
125 
126---
127 
128## Prefer truncate shorthand
129 
130`truncate` not `overflow-hidden text-ellipsis whitespace-nowrap`.
131 
132---
133 
134## No manual dark: color overrides
135 
136Use semantic tokens — they handle light/dark via CSS variables. `bg-background text-foreground` not `bg-white dark:bg-gray-950`.
137 
138---
139 
140## Use cn() for conditional classes
141 
142Use the `cn()` utility from the project for conditional or merged class names. Don't write manual ternaries in className strings.
143 
144**Incorrect:**
145 
146```tsx
147<div className={`flex items-center ${isActive ? "bg-primary text-primary-foreground" : "bg-muted"}`}>
148```
149 
150**Correct:**
151 
152```tsx
153import { cn } from "@/lib/utils"
154 
155<div className={cn("flex items-center", isActive ? "bg-primary text-primary-foreground" : "bg-muted")}>
156```
157 
158---
159 
160## No manual z-index on overlay components
161 
162`Dialog`, `Sheet`, `Drawer`, `AlertDialog`, `DropdownMenu`, `Popover`, `Tooltip`, `HoverCard` handle their own stacking. Never add `z-50` or `z-[999]`.
163