# DESIGN.md

## Brand

**Beaver — Taupe**

A calm editorial UI system focused on rhythm, hierarchy, and soft neutral contrast.  
Designed for AI-native tools, dashboards, and minimalist productivity software.

The interface emphasizes:

- Spacious layouts
- Soft grayscale surfaces
- Typography-first hierarchy
- Rounded geometry
- Quiet shadows
- Dense information with low visual noise

The visual tone should feel:

- thoughtful
- mature
- calm
- premium
- architectural
- editorial

Avoid:

- saturated colors
- hard borders
- sharp corners
- excessive gradients
- loud shadows
- playful illustration-heavy UI

---

# Colors

## Core Palette

| Token | Hex | Usage |
|---|---|---|
| background | `#F5F3F1` | Main app background |
| foreground | `#0B0B0B` | Primary text |
| primary | `#1D1715` | Primary actions |
| secondary | `#E5E2DF` | Secondary surfaces |
| muted | `#DDD9D6` | Muted backgrounds |
| accent | `#CAC5C0` | Borders / subtle emphasis |

---

## Neutral Scale

| Token | Hex |
|---|---|
| zinc-50 | `#F7F5F4` |
| zinc-100 | `#ECE8E5` |
| zinc-200 | `#D8D2CE` |
| zinc-300 | `#B8AEA8` |
| zinc-400 | `#8B7E77` |
| zinc-500 | `#6A5E58` |
| zinc-600 | `#4F4642` |
| zinc-700 | `#342E2B` |

---

## Semantic Colors

### Taupe

| Step | Hex |
|---|---|
| taupe-100 | `#E7E2DE` |
| taupe-300 | `#B8AEA8` |
| taupe-500 | `#8B7E77` |
| taupe-700 | `#5F5550` |

### Sage

| Step | Hex |
|---|---|
| sage-100 | `#E3E8E2` |
| sage-300 | `#B7C2B5` |
| sage-500 | `#869683` |
| sage-700 | `#657162` |

### Slate

| Step | Hex |
|---|---|
| slate-100 | `#E4E7EB` |
| slate-300 | `#BCC4CE` |
| slate-500 | `#8C96A3` |
| slate-700 | `#697281` |

---

# Typography

## Philosophy

Typography drives hierarchy.

The system should feel like a modern editorial publication mixed with a productivity dashboard.

Large headings use elegant serif typography.  
UI and body copy use neutral grotesk sans-serif typography.

---

## Font Stack

### Serif

```css
font-family: "Lora", Georgia, serif;
```

Used for:

- hero titles
- article headings
- marketing emphasis
- editorial sections

---

### Sans

```css
font-family: "Public Sans", Inter, sans-serif;
```

Used for:

- UI
- labels
- forms
- dashboards
- buttons
- navigation

---

## Type Scale

| Style | Size | Weight | Line Height |
|---|---|---|---|
| h1 | 48px | 600 | 1.1 |
| h2 | 36px | 600 | 1.15 |
| h3 | 28px | 500 | 1.2 |
| body-lg | 18px | 400 | 1.7 |
| body | 16px | 400 | 1.6 |
| small | 14px | 400 | 1.5 |
| mono | 13px | 500 | 1.4 |

---

# Radius

Rounded geometry should feel soft but architectural.

| Token | Radius |
|---|---|
| xs | 4px |
| sm | 8px |
| md | 12px |
| lg | 16px |
| xl | 24px |
| full | 999px |

Cards should primarily use:

```css
border-radius: 16px;
```

---

# Shadows

Shadows should be subtle and diffused.

Avoid strong elevation.

## Soft

```css
box-shadow:
0 1px 2px rgba(0,0,0,0.04),
0 6px 24px rgba(0,0,0,0.03);
```

## Floating

```css
box-shadow:
0 12px 40px rgba(0,0,0,0.06);
```

---

# Grid

## Layout

- 12-column grid
- Max width: `1280px`
- Horizontal padding: `32px`
- Large whitespace between sections

---

## Content Widths

| Type | Width |
|---|---|
| reading | 720px |
| dashboard | 1280px |
| modal | 480px |
| form | 560px |

---

# Spacing

Base unit:

```txt
4px
```

Spacing scale:

| Token | Value |
|---|---|
| 1 | 4px |
| 2 | 8px |
| 3 | 12px |
| 4 | 16px |
| 5 | 20px |
| 6 | 24px |
| 8 | 32px |
| 10 | 40px |
| 12 | 48px |
| 16 | 64px |

Use generous vertical rhythm.

Sections should breathe.

---

# Components

## Buttons

### Primary

- Dark background
- White text
- Pill radius
- Minimal shadow

```css
background: #1D1715;
color: white;
border-radius: 999px;
height: 40px;
padding: 0 16px;
```

### Secondary

```css
background: #ECE8E5;
color: #1D1715;
```

### Ghost

Transparent background with subtle hover fill.

---

## Cards

Cards are soft containers with quiet separation.

```css
background: rgba(255,255,255,0.7);
border: 1px solid rgba(0,0,0,0.04);
border-radius: 16px;
```

Avoid heavy borders.

---

## Inputs

Inputs should feel invisible until focused.

```css
background: #F7F5F4;
border: 1px solid transparent;
```

Focus:

```css
border-color: #8B7E77;
box-shadow: 0 0 0 3px rgba(139,126,119,0.12);
```

---

## Charts

Charts should use muted earthy tones.

Preferred palette:

- taupe
- sage
- slate

Avoid:

- neon colors
- bright blue dashboards
- rainbow charts

---

# Motion

Motion should be restrained and smooth.

Preferred easing:

```css
cubic-bezier(0.22, 1, 0.36, 1)
```

Preferred duration:

| Type | Duration |
|---|---|
| hover | 150ms |
| panel | 250ms |
| modal | 350ms |

---

# Layout Skeleton

Application layout:

- Left sidebar
- Large content canvas
- Floating top toolbar
- Soft dashboard cards
- Spacious internal padding

The UI should always feel:

- breathable
- editorial
- premium
- calm

Never dense or overly enterprise-looking.

---

# Design Keywords

Use these words when generating UI:

- editorial
- taupe
- soft neutral
- premium minimal
- typography-first
- architectural spacing
- calm dashboard
- quiet luxury
- modern serif
- subtle shadows
- muted grayscale
- sophisticated SaaS

---

# AI Agent Instructions

When generating UI:

1. Prioritize whitespace over density
2. Typography should create hierarchy
3. Use muted neutral palettes
4. Prefer soft cards over hard sections
5. Avoid excessive color usage
6. Keep interactions subtle
7. Use serif fonts sparingly for emphasis
8. Maintain premium visual restraint
9. Design should feel timeless rather than trendy
10. Every screen should feel breathable