# Examined Content Design System
## Version 1.0 — February 2026

---

# Principles

## Design Philosophy

**1. Substance Over Style**
Every design decision must serve a purpose. Remove the decorative. Keep only what works.

**2. Dark First**
The brand lives in darkness. Design for dark mode as the primary experience, then adapt for light.

**3. Precision Matters**
In finance, precision is trust. In design, precision is respect. 8px grids. Consistent spacing. Exact alignment.

**4. Hierarchy is Everything**
The most important element should dominate. Secondary elements support. Tertiary elements recede.

**5. Motion Has Meaning**
Animation should never be decorative. Every transition tells the user something is happening or changing.

**6. Accessibility is Non-Negotiable**
Design for everyone, everywhere, every time. WCAG 2.1 AA minimum.

**7. Code Is Design**
Design specs are useless if developers can't implement them. Spec everything in code.

---

# Foundations

## Color System

### Primary Colors

| Name | Hex | Usage |
|------|-----|-------|
| **Purple 600** | `#7c3aed` | Primary brand, CTAs, links |
| **Purple 500** | `#8b5cf6` | Hover states, accents |
| **Orange 500** | `#f97316` | Warnings, music player, highlights |
| **Orange 600** | `#ea580c` | Hover for orange elements |

### Neutral Colors

| Name | Hex | Usage |
|------|-----|-------|
| **Background** | `#080808` | Page background (dark mode) |
| **Surface** | `#111111` | Cards, panels |
| **Surface Elevated** | `#1a1a1a` | Modals, dropdowns |
| **Border** | `#222222` | Dividers, outlines |
| **Text Primary** | `#e0e0e0` | Headings, body |
| **Text Secondary** | `#888888` | Captions, hints |
| **Text Muted** | `#555555` | Disabled states |

### Semantic Colors

| Name | Light | Default | Dark | Usage |
|------|-------|---------|------|-------|
| **Success** | `#d1fae5` | `#10b981` | `#065f46` | Success states, positive |
| **Warning** | `#fef3c7` | `#f59e0b` | `#92400e` | Warnings, caution |
| **Error** | `#fee2e2` | `#ef4444` | `#991b1b` | Errors, destructive |
| **Info** | `#dbeafe` | `#3b82f6` | `#1e40af` | Information |

### Contrast Ratios

- **Text Primary**: 14.5:1 (AAA)
- **Text Secondary**: 5.7:1 (AA)
- **Text Muted**: 3.2:1 (AA Large)
- **Borders**: 1.2:1 (Decorative only)

---

## Typography

### Font Families

| Name | Stack | Usage |
|------|-------|-------|
| **Display** | `Space Grotesk, system-ui` | Headlines, logos |
| **Body** | `IBM Plex Mono, SF Mono, Menlo, monospace` | Body text, code |
| **UI** | `-apple-system, BlinkMacSystemFont, Segoe UI, system-ui` | Interface elements |

### Type Scale

| Level | Size | Line Height | Weight | Usage |
|-------|------|-------------|--------|-------|
| **xs** | 0.6875rem (11px) | 1.4 | 400 | Timestamps, labels |
| **sm** | 0.75rem (12px) | 1.4 | 400 | Secondary text |
| **base** | 0.875rem (14px) | 1.5 | 400 | Body text |
| **lg** | 1rem (16px) | 1.5 | 400 | Emphasized body |
| **xl** | 1.125rem (18px) | 1.4 | 500 | Section headers |
| **2xl** | 1.25rem (20px) | 1.3 | 500 | Page titles |
| **3xl** | 1.5rem (24px) | 1.2 | 600 | Major headings |
| **4xl** | 2rem (32px) | 1.2 | 600 | Hero text |
| **5xl** | 2.5rem (40px) | 1.1 | 700 | Display |

### Responsive Type

```css
/* Mobile (default) */
html { font-size: 14px; }

/* Tablet (768px+) */
@media (min-width: 768px) {
  html { font-size: 15px; }
}

/* Desktop (1024px+) */
@media (min-width: 1024px) {
  html { font-size: 16px; }
}
```

### Accessibility

- Minimum text size: 12px
- Line height minimum: 1.4
- Letter spacing: -0.02em to 0.05em
- Use `rem` units, not `px`
- Test with VoiceOver / NVDA

---

## Spacing System

### Base Unit
**8px** — All spacing multiples of 8

| Token | Value | Usage |
|-------|-------|-------|
| `space-1` | 0.125rem (2px) | Icon gaps |
| `space-2` | 0.25rem (4px) | Inline spacing |
| `space-3` | 0.5rem (8px) | Component internal |
| `space-4` | 0.75rem (12px) | Tight spacing |
| `space-5` | 1rem (16px) | Default spacing |
| `space-6` | 1.5rem (24px) | Section spacing |
| `space-7` | 2rem (32px) | Large gaps |
| `space-8` | 2.5rem (40px) | Section margins |
| `space-9` | 3rem (48px) | Page sections |
| `space-10` | 4rem (64px) | Major divisions |

---

## 12-Column Grid

### Configuration
- **Columns**: 12
- **Gutter**: 1.5rem (24px)
- **Margin**: 1rem (16px) mobile, 2rem (32px) desktop

### Breakpoints

| Breakpoint | Width | Columns | Margin |
|------------|-------|----------|---------|
| **xs** | < 640px | 4 | 1rem |
| **sm** | ≥ 640px | 4 | 1.5rem |
| **md** | ≥ 768px | 8 | 2rem |
| **lg** | ≥ 1024px | 12 | 2rem |
| **xl** | ≥ 1280px | 12 | 3rem |

### Column Classes

```html
<div class="grid">
  <div class="col-12">Full width</div>
  <div class="col-6">Half</div>
  <div class="col-6">Half</div>
  <div class="col-4">Third</div>
  <div class="col-4">Third</div>
  <div class="col-4">Third</div>
  <div class="col-3">Quarter</div>
  <div class="col-3">Quarter</div>
  <div class="col-3">Quarter</div>
  <div class="col-3">Quarter</div>
</div>
```

---

## Motion

### Duration

| Token | Value | Usage |
|-------|-------|-------|
| `duration-fast` | 75ms | Micro-interactions |
| `duration-default` | 150ms | Standard transitions |
| `duration-slow` | 300ms | Page transitions |
| `duration-slower` | 500ms | Major changes |

### Timing Functions

| Token | Value | Usage |
|-------|-------|-------|
| `ease-default` | `cubic-bezier(0.4, 0, 0.2, 1)` | Standard |
| `ease-in` | `cubic-bezier(0.4, 0, 1, 1)` | Entering |
| `ease-out` | `cubic-bezier(0, 0, 0.2, 1)` | Exiting |
| `ease-in-out` | `cubic-bezier(0.4, 0, 0.2, 1)` | Bidirectional |

---

# Components

## 1. Button

### Anatomy
- Container (border-radius, padding)
- Label (text, icon)
- States: default, hover, active, disabled, loading

### Variants

| Variant | Background | Text | Border | Usage |
|---------|------------|------|--------|-------|
| **Primary** | Purple 600 | White | None | Main CTAs |
| **Secondary** | Transparent | Purple 400 | Purple 400 | Secondary actions |
| **Ghost** | Transparent | Text Secondary | None | Tertiary |
| **Danger** | Error | White | None | Destructive |

### States

| State | Style |
|-------|-------|
| **Default** | As variant |
| **Hover** | Lighten 10%, scale(1.02) |
| **Active** | Darken 10%, scale(0.98) |
| **Focus** | Ring: 2px Purple 400, offset 2px |
| **Disabled** | Opacity 0.5, cursor-not-allowed |

### Specs

```css
.button {
  display: inline-flex;
  align-items: center;
  justify-content: center;
  gap: 0.5rem;
  padding: 0.75rem 1.5rem;
  border-radius: 0.5rem;
  font-family: IBM Plex Mono;
  font-size: 0.875rem;
  font-weight: 500;
  transition: all 150ms ease;
  cursor: pointer;
}
```

### Accessibility
- Minimum touch target: 44×44px
- Focus visible ring required
- Loading state: `aria-busy="true"`

---

## 2. Input

### Anatomy
- Container (border, background)
- Label (above, required indicator)
- Field (input, placeholder)
- Helper text (below)
- States: default, focus, error, disabled

### Specs

```css
.input {
  width: 100%;
  padding: 0.75rem 1rem;
  background: #111;
  border: 1px solid #222;
  border-radius: 0.5rem;
  color: #e0e0e0;
  font-family: IBM Plex Mono;
  font-size: 0.875rem;
}

.input:focus {
  outline: none;
  border-color: #7c3aed;
  box-shadow: 0 0 0 3px rgba(124, 58, 237, 0.2);
}
```

### States

| State | Border | Background | Text |
|-------|--------|------------|------|
| **Default** | #222 | #111 | #e0e0e0 |
| **Hover** | #333 | #1a1a1a | — |
| **Focus** | #7c3aed | #111 | — |
| **Error** | #ef4444 | #1a1a1a | #ef4444 |
| **Disabled** | #222 | #0a0a0a | #555 |

---

## 3. Card

### Anatomy
- Container (background, border, radius)
- Header (title, subtitle, action)
- Body (content)
- Footer (meta, actions)

### Specs

```css
.card {
  background: #111;
  border: 1px solid #222;
  border-radius: 1rem;
  padding: 1.5rem;
}

.card-elevated {
  box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.3);
}
```

---

## 4. Link

### Specs

```css
.link {
  color: #8b5cf6;
  text-decoration: none;
  border-bottom: 1px solid transparent;
  transition: border-color 150ms ease;
}

.link:hover {
  border-bottom-color: #8b5cf6;
}
```

---

## 5. Badge

### Variants

| Variant | Background | Text |
|---------|------------|------|
| **Default** | #1a1a1a | #888 |
| **Primary** | Purple 600/20% | Purple 400 |
| **Success** | Green 600/20% | Green 400 |
| **Warning** | Orange 600/20% | Orange 400 |
| **Error** | Red 600/20% | Red 400 |

---

## 6. Toggle

### Specs

```css
.toggle {
  width: 44px;
  height: 24px;
  background: #222;
  border-radius: 12px;
  cursor: pointer;
  transition: background 150ms ease;
}

.toggle[aria-checked="true"] {
  background: #7c3aed;
}
```

---

## 7. Select / Dropdown

### Anatomy
- Trigger (button showing selected)
- Menu (options list)
- Option (item with icon, label)
- States: closed, open, option hover, selected

---

## 8. Modal

### Specs

```css
.modal-overlay {
  position: fixed;
  inset: 0;
  background: rgba(0, 0, 0, 0.8);
  display: flex;
  align-items: center;
  justify-content: center;
  z-index: 1200;
}

.modal {
  background: #111;
  border: 1px solid #222;
  border-radius: 1rem;
  padding: 2rem;
  max-width: 32rem;
  width: 90%;
}
```

---

## 9. Tooltip

### Specs

```css
.tooltip {
  position: absolute;
  padding: 0.5rem 0.75rem;
  background: #1a1a1a;
  border: 1px solid #222;
  border-radius: 0.375rem;
  font-size: 0.75rem;
  color: #e0e0e0;
  z-index: 1400;
  animation: fadeIn 150ms ease;
}
```

---

## 10. Avatar

### Specs

```css
.avatar {
  width: 2rem;
  height: 2rem;
  border-radius: 50%;
  background: #1a1a1a;
  display: flex;
  align-items: center;
  justify-content: center;
  font-size: 0.75rem;
  font-weight: 600;
  color: #888;
}

.avatar-sm { width: 1.5rem; height: 1.5rem; font-size: 0.625rem; }
.avatar-lg { width: 3rem; height: 3rem; font-size: 1rem; }
```

---

## 11. Progress

### Specs

```css
.progress {
  height: 0.5rem;
  background: #1a1a1a;
  border-radius: 0.25rem;
  overflow: hidden;
}

.progress-bar {
  height: 100%;
  background: linear-gradient(90deg, #7c3aed, #f97316);
  border-radius: 0.25rem;
  transition: width 300ms ease;
}
```

---

## 12. Tabs

### Specs

```css
.tab-list {
  display: flex;
  gap: 0.5rem;
  border-bottom: 1px solid #222;
}

.tab {
  padding: 0.75rem 1rem;
  color: #888;
  cursor: pointer;
  border-bottom: 2px solid transparent;
  transition: all 150ms ease;
}

.tab:hover {
  color: #e0e0e0;
}

.tab[aria-selected="true"] {
  color: #7c3aed;
  border-bottom-color: #7c3aed;
}
```

---

## 13. Alert

### Variants

| Variant | Background | Border | Icon |
|---------|------------|--------|------|
| **Info** | Blue 600/10% | Blue 600 | ℹ |
| **Success** | Green 600/10% | Green 600 | ✓ |
| **Warning** | Orange 600/10% | Orange 600 | ⚠ |
| **Error** | Red 600/10% | Red 600 | ✕ |

---

## 14. Skeleton / Loading

### Specs

```css
.skeleton {
  background: linear-gradient(90deg, #1a1a1a 25%, #222 50%, #1a1a1a 75%);
  background-size: 200% 100%;
  animation: skeleton-loading 1.5s infinite;
  border-radius: 0.25rem;
}
```

---

## 15. Divider

```css
.divider {
  height: 1px;
  background: #222;
  margin: 1.5rem 0;
}

.divider-vertical {
  width: 1px;
  height: 1.5rem;
  background: #222;
}
```

---

## 16. Icon Button

```css
.icon-button {
  width: 2rem;
  height: 2rem;
  display: flex;
  align-items: center;
  justify-content: center;
  background: transparent;
  border: none;
  border-radius: 0.375rem;
  color: #888;
  cursor: pointer;
  transition: all 150ms ease;
}

.icon-button:hover {
  background: #1a1a1a;
  color: #e0e0e0;
}
```

---

## 17. Breadcrumb

```css
.breadcrumb {
  display: flex;
  align-items: center;
  gap: 0.5rem;
  font-size: 0.75rem;
  color: #888;
}

.breadcrumb-separator {
  color: #444;
}

.breadcrumb-link:hover {
  color: #e0e0e0;
}
```

---

## 18. Pagination

```css
.pagination {
  display: flex;
  gap: 0.25rem;
}

.page-button {
  min-width: 2rem;
  height: 2rem;
  display: flex;
  align-items: center;
  justify-content: center;
  background: transparent;
  border: 1px solid #222;
  border-radius: 0.25rem;
  color: #888;
  cursor: pointer;
}

.page-button:hover {
  border-color: #333;
  color: #e0e0e0;
}

.page-button[aria-current="true"] {
  background: #7c3aed;
  border-color: #7c3aed;
  color: white;
}
```

---

## 19. Tag / Chip

```css
.tag {
  display: inline-flex;
  align-items: center;
  gap: 0.25rem;
  padding: 0.25rem 0.75rem;
  background: #1a1a1a;
  border-radius: 9999px;
  font-size: 0.75rem;
  color: #888;
}

.tag-remove {
  width: 1rem;
  height: 1rem;
  display: flex;
  align-items: center;
  justify-content: center;
  cursor: pointer;
  border-radius: 50%;
}

.tag-remove:hover {
  background: #333;
}
```

---

## 20. Toast / Snackbar

```css
.toast {
  position: fixed;
  bottom: 2rem;
  right: 2rem;
  padding: 1rem 1.5rem;
  background: #1a1a1a;
  border: 1px solid #222;
  border-radius: 0.5rem;
  display: flex;
  align-items: center;
  gap: 0.75rem;
  z-index: 1300;
  animation: slideIn 300ms ease;
}
```

---

## 21. Table

```css
.table {
  width: 100%;
  border-collapse: collapse;
}

.table th,
.table td {
  padding: 0.75rem 1rem;
  text-align: left;
  border-bottom: 1px solid #222;
}

.table th {
  font-size: 0.75rem;
  font-weight: 600;
  color: #888;
  text-transform: uppercase;
  letter-spacing: 0.05em;
}

.table tr:hover td {
  background: #111;
}
```

---

## 22. Form Group

```css
.form-group {
  display: flex;
  flex-direction: column;
  gap: 0.5rem;
  margin-bottom: 1.5rem;
}

.form-label {
  font-size: 0.875rem;
  font-weight: 500;
  color: #e0e0e0;
}

.form-required {
  color: #ef4444;
  margin-left: 0.25rem;
}

.form-helper {
  font-size: 0.75rem;
  color: #888;
}

.form-error {
  font-size: 0.75rem;
  color: #ef4444;
}
```

---

## 23. Radio

```css
.radio {
  width: 1.25rem;
  height: 1.25rem;
  border: 2px solid #444;
  border-radius: 50%;
  cursor: pointer;
  transition: all 150ms ease;
}

.radio:checked {
  border-color: #7c3aed;
  background: #7c3aed;
  box-shadow: inset 0 0 0 3px #111;
}
```

---

## 24. Checkbox

```css
.checkbox {
  width: 1.25rem;
  height: 1.25rem;
  border: 2px solid #444;
  border-radius: 0.25rem;
  cursor: pointer;
  transition: all 150ms ease;
}

.checkbox:checked {
  border-color: #7c3aed;
  background: #7c3aed;
}

.checkbox:checked::after {
  content: "✓";
  display: block;
  color: white;
  font-size: 0.75rem;
  text-align: center;
  line-height: 1.25rem;
}
```

---

## 25. Slider

```css
.slider {
  width: 100%;
  height: 0.375rem;
  background: #222;
  border-radius: 0.1875rem;
  appearance: none;
  cursor: pointer;
}

.slider::-webkit-slider-thumb {
  appearance: none;
  width: 1rem;
  height: 1rem;
  background: #7c3aed;
  border-radius: 50%;
  cursor: pointer;
  transition: transform 150ms ease;
}

.slider::-webkit-slider-thumb:hover {
  transform: scale(1.1);
}
```

---

## 26. Accordion

```css
.accordion-header {
  display: flex;
  align-items: center;
  justify-content: space-between;
  width: 100%;
  padding: 1rem 0;
  border-bottom: 1px solid #222;
  cursor: pointer;
}

.accordion-icon {
  transition: transform 150ms ease;
}

.accordion-icon[aria-expanded="true"] {
  transform: rotate(180deg);
}

.accordion-content {
  padding: 1rem 0;
}
```

---

## 27. Menu / Context Menu

```css
.menu {
  position: absolute;
  min-width: 12rem;
  background: #111;
  border: 1px solid #222;
  border-radius: 0.5rem;
  padding: 0.25rem;
  z-index: 1000;
  box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.3);
}

.menu-item {
  display: flex;
  align-items: center;
  gap: 0.75rem;
  padding: 0.5rem 0.75rem;
  border-radius: 0.25rem;
  cursor: pointer;
  font-size: 0.875rem;
  color: #e0e0e0;
}

.menu-item:hover {
  background: #1a1a1a;
}

.menu-item-danger {
  color: #ef4444;
}

.menu-divider {
  height: 1px;
  background: #222;
  margin: 0.25rem 0;
}
```

---

## 28. Nav

```css
.nav {
  display: flex;
  flex-direction: column;
  gap: 0.25rem;
}

.nav-item {
  display: flex;
  align-items: center;
  gap: 0.75rem;
  padding: 0.75rem 1rem;
  border-radius: 0.5rem;
  color: #888;
  text-decoration: none;
  transition: all 150ms ease;
}

.nav-item:hover {
  background: #111;
  color: #e0e0e0;
}

.nav-item-active {
  background: rgba(124, 58, 237, 0.1);
  color: #8b5cf6;
}
```

---

## 29. Sidebar

```css
.sidebar {
  width: 16rem;
  height: 100vh;
  background: #111;
  border-right: 1px solid #222;
  display: flex;
  flex-direction: column;
  position: sticky;
  top: 0;
}

.sidebar-collapsed {
  width: 4rem;
}
```

---

## 30. Header

```css
.header {
  height: 4rem;
  background: #080808;
  border-bottom: 1px solid #222;
  display: flex;
  align-items: center;
  justify-content: space-between;
  padding: 0 1.5rem;
  position: sticky;
  top: 0;
  z-index: 100;
}
```

---

# Patterns

## Layout Patterns

### Centered Content
```html
<div class="container" style="max-width: 48rem; margin: 0 auto; padding: 2rem;">
  <!-- Content -->
</div>
```

### Two Column
```html
<div class="grid">
  <div class="col-4">Sidebar</div>
  <div class="col-8">Main</div>
</div>
```

### Card Grid
```html
<div class="grid">
  <div class="col-4"><div class="card">...</div></div>
  <div class="col-4"><div class="card">...</div></div>
  <div class="col-4"><div class="card">...</div></div>
</div>
```

---

# Do's and Don'ts

## Do

✓ Use semantic HTML elements  
✓ Maintain 8px grid alignment  
✓ Test at all breakpoints  
✓ Use proper contrast ratios  
✓ Include focus states  
✓ Animate for meaning  
✓ Use the design tokens  

## Don't

✗ Use arbitrary pixel values  
✗ Skip hover/focus states  
✗ Mix font families  
✗ Use more than 3 font weights  
✗ Animate without purpose  
✗ Ignore accessibility  
✗ Hardcode colors  

---

# Developer Guide

## Installation

```bash
npm install @examined/design-system
```

## Usage

```css
@import '@examined/design-system/dist/tokens.css';

.button {
  @extend .btn-primary;
}
```

## JavaScript

```javascript
import { createToast, createModal } from '@examined/design-system';

// Toast
createToast('Saved successfully', { type: 'success' });

// Modal
const modal = createModal({
  title: 'Confirm',
  content: 'Are you sure?',
  onConfirm: () => console.log('confirmed')
});
```

---

# Version History

- **1.0** (Feb 2026) — Initial release

---

*Examined Content Design System — Built with precision.*