# Document Annotation Tool – UX Design Spec v2

## Theme: Warm Graphite (Modern Enterprise)

---

## 1. Design Principles (Updated)

1. **Clarity** – High contrast, but never pure black-on-white
2. **Warm Neutrality** – Slightly warm grays reduce visual fatigue
3. **Focus** – Content-first layouts with restrained accents
4. **Consistency** – Reusable patterns, predictable behavior
5. **Professional Trust** – Calm, serious, enterprise-ready
6. **Longevity** – No trendy colors that age quickly

---

## 2. Color Palette (Warm Graphite)

### Core Colors

| Usage | Color Name | Hex |
|------|-----------|-----|
| Primary Text | Soft Black | #121212 |
| Secondary Text | Charcoal Gray | #2A2A2A |
| Muted Text | Warm Gray | #6B6B6B |
| Disabled Text | Light Warm Gray | #9A9A9A |

### Backgrounds

| Usage | Color | Hex |
|-----|------|-----|
| App Background | Paper White | #FAFAF8 |
| Card / Panel | White | #FFFFFF |
| Hover Surface | Subtle Warm Gray | #F1F0ED |
| Selected Row | Very Light Warm Gray | #ECEAE6 |

### Borders & Dividers

| Usage | Color | Hex |
|------|------|-----|
| Default Border | Warm Light Gray | #E6E4E1 |
| Strong Divider | Neutral Gray | #D8D6D2 |

### Semantic States (Muted & Professional)

| State | Color | Hex |
|------|-------|-----|
| Success | Olive Gray | #3E4A3A |
| Error | Brick Gray | #4A3A3A |
| Warning | Sand Gray | #4A4A3A |
| Info | Graphite Gray | #3A3A3A |

> Accent colors are **never saturated** and are used only for status, progress, or selection.

---

## 3. Typography

- **Font Family**: Inter / SF Pro / system-ui
- **Headings**:
  - Weight: 600–700
  - Color: #121212
  - Letter spacing: -0.01em
- **Body Text**:
  - Weight: 400
  - Color: #2A2A2A
- **Captions / Meta**:
  - Weight: 400
  - Color: #6B6B6B
- **Monospace (IDs / Values)**:
  - JetBrains Mono / SF Mono
  - Color: #2A2A2A

---

## 4. Global Layout

### Top Navigation Bar

- Height: 56px
- Background: #FAFAF8
- Bottom Border: 1px solid #E6E4E1
- Logo: Text or icon in #121212

**Navigation Items**
- Default: #6B6B6B
- Hover: #2A2A2A
- Active:
  - Text: #121212
  - Bottom indicator: 2px solid #3A3A3A (rounded ends)

**Avatar**
- Circle background: #ECEAE6
- Text: #2A2A2A

---

## 5. Page: Documents (Dashboard)

### Page Header

- Title: "Documents" (#121212)
- Actions:
  - Primary button: Dark graphite outline
  - Secondary button: Subtle border only

### Filters Bar

- Background: #FFFFFF
- Border: 1px solid #E6E4E1
- Inputs:
  - Background: #FFFFFF
  - Hover: #F1F0ED
  - Focus ring: 1px #3A3A3A

### Document Table

- Table background: #FFFFFF
- Header text: #6B6B6B
- Row hover: #F1F0ED
- Row selected:
  - Background: #ECEAE6
  - Left indicator: 3px solid #3A3A3A

### Status Badges

- Pending:
  - BG: #FFFFFF
  - Border: #D8D6D2
  - Text: #2A2A2A

- Labeled:
  - BG: #2A2A2A
  - Text: #FFFFFF

- Exported:
  - BG: #ECEAE6
  - Text: #2A2A2A
  - Icon: ✓

### Auto-label States

- Running:
  - Progress bar: #3A3A3A on #ECEAE6
- Completed:
  - Text: #3E4A3A
- Failed:
  - BG: #F1EDED
  - Text: #4A3A3A

---

## 6. Upload Modals (Single & Batch)

### Modal Container

- Background: #FFFFFF
- Border radius: 8px
- Shadow: 0 1px 3px rgba(0,0,0,0.08)

### Drop Zone

- Background: #FAFAF8
- Border: 1px dashed #D8D6D2
- Hover: #F1F0ED
- Icon: Graphite gray

### Form Fields

- Input BG: #FFFFFF
- Border: #D8D6D2
- Focus: 1px solid #3A3A3A

Primary Action Button:
- Text: #FFFFFF
- BG: #2A2A2A
- Hover: #121212

---

## 7. Document Detail View

### Canvas Area

- Background: #FFFFFF
- Annotation styles:
  - Manual: Solid border #2A2A2A
  - Auto: Dashed border #6B6B6B
  - Selected: 2px border #3A3A3A + resize handles

### Right Info Panel

- Card background: #FFFFFF
- Section headers: #121212
- Meta text: #6B6B6B

### Annotation Table

- Same table styles as Documents
- Inline edit:
  - Input background: #FAFAF8
  - Save button: Graphite

### Locked State (Auto-label Running)

- Banner BG: #FAFAF8
- Border-left: 3px solid #4A4A3A
- Progress bar: Graphite

---

## 8. Training Page

### Document Selector

- Selected rows use same highlight rules
- Verified state:
  - Full: Olive gray check
  - Partial: Sand gray warning

### Configuration Panel

- Card layout
- Inputs aligned to grid
- Schedule option visually muted until enabled

Primary CTA:
- Start Training button in dark graphite

---

## 9. Models & Training History

### Training Job List

- Job cards use #FFFFFF background
- Running job:
  - Progress bar: #3A3A3A
- Completed job:
  - Metrics bars in graphite

### Model Detail Panel

- Sectioned cards
- Metric bars:
  - Track: #ECEAE6
  - Fill: #3A3A3A

Actions:
- Primary: Download Model
- Secondary: View Logs / Use as Base

---

## 10. Micro-interactions (Refined)

| Element | Interaction | Animation |
|------|------------|-----------|
| Button hover | BG lightens | 150ms ease-out |
| Button press | Scale 0.98 | 100ms |
| Row hover | BG fade | 120ms |
| Modal open | Fade + scale 0.96 → 1 | 200ms |
| Progress fill | Smooth | ease-out |
| Annotation select | Border + handles | 120ms |

---

## 11. Tailwind Theme (Updated)

```js
colors: {
  text: {
    primary: '#121212',
    secondary: '#2A2A2A',
    muted: '#6B6B6B',
    disabled: '#9A9A9A',
  },
  bg: {
    app: '#FAFAF8',
    card: '#FFFFFF',
    hover: '#F1F0ED',
    selected: '#ECEAE6',
  },
  border: '#E6E4E1',
  accent: '#3A3A3A',
  success: '#3E4A3A',
  error: '#4A3A3A',
  warning: '#4A4A3A',
}
```

---

## 12. Final Notes

- Pure black (#000000) should **never** be used as large surfaces
- Accent color usage should stay under **10% of UI area**
- Warm grays are intentional and must not be "corrected" to blue-grays

This theme is designed to scale from internal tool → polished SaaS without redesign.