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- Use shimmer / scroll-fade utilities, not custom animations
17 
18---
19 
20## Semantic colors
21 
22**Incorrect:**
23 
24```tsx
25<div className="bg-blue-500 text-white">
26  <p className="text-gray-600">Secondary text</p>
27</div>
28```
29 
30**Correct:**
31 
32```tsx
33<div className="bg-primary text-primary-foreground">
34  <p className="text-muted-foreground">Secondary text</p>
35</div>
36```
37 
38---
39 
40## No raw color values for status/state indicators
41 
42For 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.
43 
44**Incorrect:**
45 
46```tsx
47<span className="text-emerald-600">+20.1%</span>
48<span className="text-green-500">Active</span>
49<span className="text-red-600">-3.2%</span>
50```
51 
52**Correct:**
53 
54```tsx
55<Badge variant="secondary">+20.1%</Badge>
56<Badge>Active</Badge>
57<span className="text-destructive">-3.2%</span>
58```
59 
60If 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)).
61 
62---
63 
64## Built-in variants first
65 
66**Incorrect:**
67 
68```tsx
69<Button className="border border-input bg-transparent hover:bg-accent">
70  Click me
71</Button>
72```
73 
74**Correct:**
75 
76```tsx
77<Button variant="outline">Click me</Button>
78```
79 
80---
81 
82## className for layout only
83 
84Use `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.
85 
86**Incorrect:**
87 
88```tsx
89<Card className="bg-blue-100 text-blue-900 font-bold">
90  <CardContent>Dashboard</CardContent>
91</Card>
92```
93 
94**Correct:**
95 
96```tsx
97<Card className="max-w-md mx-auto">
98  <CardContent>Dashboard</CardContent>
99</Card>
100```
101 
102To customize a component's appearance, prefer these approaches in order:
1031. **Built-in variants** — `variant="outline"`, `variant="destructive"`, etc.
1042. **Semantic color tokens** — `bg-primary`, `text-muted-foreground`.
1053. **CSS variables** — define custom colors in the global CSS file (see [customization.md](../customization.md)).
106 
107---
108 
109## No space-x-* / space-y-*
110 
111Use `gap-*` instead. `space-y-4` → `flex flex-col gap-4`. `space-x-2` → `flex gap-2`.
112 
113```tsx
114<div className="flex flex-col gap-4">
115  <Input />
116  <Input />
117  <Button>Submit</Button>
118</div>
119```
120 
121---
122 
123## Prefer size-* over w-* h-* when equal
124 
125`size-10` not `w-10 h-10`. Applies to icons, avatars, skeletons, etc.
126 
127---
128 
129## Prefer truncate shorthand
130 
131`truncate` not `overflow-hidden text-ellipsis whitespace-nowrap`.
132 
133---
134 
135## No manual dark: color overrides
136 
137Use semantic tokens — they handle light/dark via CSS variables. `bg-background text-foreground` not `bg-white dark:bg-gray-950`.
138 
139---
140 
141## Use cn() for conditional classes
142 
143Use the `cn()` utility from the project for conditional or merged class names. Don't write manual ternaries in className strings.
144 
145**Incorrect:**
146 
147```tsx
148<div className={`flex items-center ${isActive ? "bg-primary text-primary-foreground" : "bg-muted"}`}>
149```
150 
151**Correct:**
152 
153```tsx
154import { cn } from "@/lib/utils"
155 
156<div className={cn("flex items-center", isActive ? "bg-primary text-primary-foreground" : "bg-muted")}>
157```
158 
159---
160 
161## No manual z-index on overlay components
162 
163`Dialog`, `Sheet`, `Drawer`, `AlertDialog`, `DropdownMenu`, `Popover`, `Tooltip`, `HoverCard` handle their own stacking. Never add `z-50` or `z-[999]`.
164 
165---
166 
167## Use shimmer / scroll-fade utilities, not custom animations
168 
169For a live "thinking…" or loading-text shimmer, apply the `shimmer` utility. Don't author a custom `@keyframes` or a `bg-clip-text` gradient sweep.
170 
171For scroll-aware edge fading on a scroll container, use `scroll-fade` (and the axis variants `scroll-fade-x` / `scroll-fade-b`). Don't hand-roll mask gradients. The chat components already apply these internally: `Attachment` shimmers its title during upload, and `MessageScrollerViewport` fades its edges.
172 
173**Incorrect:**
174 
175```tsx
176<span className="animate-pulse bg-gradient-to-r from-muted-foreground/40 via-foreground/70 to-muted-foreground/40 bg-clip-text text-transparent [animation:shimmer_1.6s_infinite]">
177  Thinking…
178</span>
179```
180 
181**Correct:**
182 
183```tsx
184<span className="shimmer">Thinking…</span>
185```
186