# UI Guidelines

Rules for creating section and page files. Read before generating any layouts.

---

## Banned Layout Patterns

These patterns are generic and overused. Never use them.

**Heroes:**
- Text left, image right (50/50 split)
- Centered text with no other visual interest
- Stock photo background with text overlay
- Single image below centered headline

**Features:**
- 3-column cards with icons on top
- Numbered lists (01, 02, 03)
- Alternating left-right image/text blocks

**General:**
- Any layout that looks like a generic/template Squarespace, Webflow, or Framer output

If your first instinct is one of these patterns, find something else.

---

## CSS Rules

**Structure:**
- Use CSS Grid and Flexbox for layout
- Do not use `position: absolute` for layout structure (acceptable for decorative elements only)
- Avoid fixed pixel widths on containers
- No magic numbers or fragile hacks

**Responsiveness:**
- Layouts must work at all viewport widths
- Content must not break if text is longer or shorter than expected

**Z-index:**
- Use a consistent scale (10, 20, 30)
- No arbitrary values

**Squares:**
- Use `aspect-ratio: 1` or define width and height together

---

## Font Selection

Reference: `../FONTS/GOOGLE-FONTS.md`

**Rules:**
- Choose fonts appropriate to the brand tone and industry
- If the user dislikes the font choice, offer alternatives from the reference file

**Banned fonts** (overused, do not use unless explicitly requested):
- Roboto
- Open Sans
- Montserrat
- Poppins
- Lato
- Roboto Condensed
- Oswald
- Raleway
- Ubuntu
- Quicksand

### Typography CSS
- Use `text-wrap: balance` on headings
- Use `text-wrap: pretty` on body text
- Use `font-variant-numeric: tabular-nums` on numerical data
- Use `text-overflow: ellipsis` or `-webkit-line-clamp` for truncation
- Do not modify `letter-spacing` unless explicitly requested

---

## Color and Style
- Do not use gradients
- Do not use glow effects as primary affordances
- If `STYLE.md` exists in the project folder, use only colors from the confirmed style tokens
- Limit accent color to one per view
- If your design requires shadows, they must be subtle, nicely crafted shadows

---

## Text Content
- Use sentence case for all text (not Title Case)
- Empty states must have one clear next action

---

## Graphics and Images

**UI Elements:**
- All UI mockups must be technically accurate and visually polished
- Do not create placeholder UIs—if showing a UI, it must look production-ready

**Photos and Illustrations:**
- Never use stock photos, Unsplash images, or generic placeholder services
- Use a styled placeholder box that fits the page's color scheme
- Each placeholder must include a caption describing the ideal image

**Caption rules:**
- Be specific enough that a designer or photographer knows exactly what to capture
- Avoid generic corporate imagery (handshakes, people staring at cameras, pointing at screens)
- Reference modern visual trends: candid moments, motion blur, environmental context, asymmetric crops, editorial angles

**Caption examples:**
- ✗ Bad: "Team photo"
- ✓ Good: "Overhead shot of hands around a table with sketches and coffee cups, shallow depth of field, warm tones"
- ✗ Bad: "Product image"
- ✓ Good: "Product floating at slight angle with soft directional shadow, clean background matching brand palette"
- ✗ Bad: "Customer testimonial"
- ✓ Good: "Candid portrait, subject mid-laugh, natural window light, blurred workspace in background"

**Placeholder styling:**
- Background color should complement the page palette (muted tone, not distracting)
- Add a subtle border if needed for visibility against similar backgrounds
- Center the caption text inside the placeholder
- Caption text should be visually distinct from UI copy (smaller size, muted color)
