Styling

• Semantic colors
• Built-in variants first
• className for layout only
• No space-x-* / space-y-*
• Prefer size-* over w-* h-* when equal
• Prefer truncate shorthand
• No manual dark: color overrides
• Use cn() for conditional classes
• No manual z-index on overlay components
• Use shimmer / scroll-fade utilities, not custom animations

Semantic colors

Incorrect:

Correct:

No raw color values for status/state indicators

For 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.

Incorrect:

Correct:

If 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).

Built-in variants first

Incorrect:

Correct:

className for layout only

Use 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.

Incorrect:

Correct:

To customize a component’s appearance, prefer these approaches in order:

1. Built-in variants — variant="outline", variant="destructive", etc.
2. Semantic color tokens — bg-primary, text-muted-foreground.
3. CSS variables — define custom colors in the global CSS file (see customization.md).

No space-x-* / space-y-*

Use gap-* instead. space-y-4 → flex flex-col gap-4. space-x-2 → flex gap-2.

Prefer size-* over w-* h-* when equal

size-10 not w-10 h-10. Applies to icons, avatars, skeletons, etc.

Prefer truncate shorthand

truncate not overflow-hidden text-ellipsis whitespace-nowrap.

No manual dark: color overrides

Use semantic tokens — they handle light/dark via CSS variables. bg-background text-foreground not bg-white dark:bg-gray-950.

Use cn() for conditional classes

Use the cn() utility from the project for conditional or merged class names. Don’t write manual ternaries in className strings.

Incorrect:

Correct:

No manual z-index on overlay components

Dialog, Sheet, Drawer, AlertDialog, DropdownMenu, Popover, Tooltip, HoverCard handle their own stacking. Never add z-50 or z-[999].

Use shimmer / scroll-fade utilities, not custom animations

For a live “thinking…” or loading-text shimmer, apply the shimmer utility. Don’t author a custom @keyframes or a bg-clip-text gradient sweep.

For 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.

Incorrect:

Correct: