# Design guardrails for this project

These rules apply to all UI and frontend work. Follow them without exception unless I explicitly override one for a specific reason.

---

## Components and libraries

- Do not use shadcn/ui default styles without modification. If you use it, customize the theme tokens before using any component.
- Do not leave Tailwind utility defaults untouched. Define a real color palette and type scale in `tailwind.config` before reaching for utility classes.
- Do not use the default indigo, violet, or slate color ramps as the visual identity of the product. These are placeholders, not design decisions.
- Do not copy-paste component patterns from documentation examples. Adapt them to the product context.

---

## Spacing and layout

- Do not apply uniform spacing across unrelated elements. Use proximity to communicate relationship. Things that belong together should be closer. Things that don't should breathe.
- Do not default to full-width stacked layouts for every screen. Consider composition. Not everything is a list.
- Do not skip empty states, zero data states, and loading states. These are part of the product. Design them.

---

## Color

- Do not build a color system with a single accent color and a gray scale. Define surface colors, semantic colors, and tonal relationships.
- Do not implement dark mode as a simple background inversion. Dark mode needs its own considered palette.
- Do not apply accent colors at the same opacity everywhere. Active states, hover states, backgrounds, and text have different needs.

---

## Typography

- Do not use Inter, Roboto, or system fonts as the default without a deliberate reason. Choose a typeface with a point of view.
- Do not stop at bold headings and regular body copy. Build a real type hierarchy with weight contrast, size contrast, and spacing that communicates structure.
- Do not ignore line height, letter spacing, or measure. These affect readability and voice as much as the font choice does.

---

## Iconography

- Do not mix icon libraries within the same product.
- Do not use icons at inconsistent sizes. Pick a base size and scale deliberately.
- Do not use icons as decoration. Every icon should carry meaning or aid comprehension.

---

## Interactive states

- Do not ship components with only hover states. Every interactive element needs hover, focus, active, and disabled states.
- Do not use the browser default focus outline as the only focus indicator.
- Do not use a spinner as the only loading treatment. Consider skeleton states for content-heavy components.
- Do not use red text as the only error treatment. Error states need context, not just color.

---

## Motion and microinteraction

- Do not add animation for its own sake. Every transition should reinforce the action being taken.
- Do not use the same duration and easing for every animation. Quick actions feel quick. State changes feel considered.
- Always include `prefers-reduced-motion` media query support when adding animation.

---

## General

- Do not generate a design and move on. Ask if the visual direction feels right before building on top of it.
- Do not make a visual decision without being able to defend it. If I ask why something looks the way it does, there should be a reason.
- Do not add inline custom styling unless necessary, adhere to and enhance the library and design language.
- When in doubt, do less and do it better rather than more done generically.