# DESIGN.md — Monolith Design System
Version: 1.0.0

A dark, minimal design system built for developer tools and SaaS products. Sharp edges, monospace type for data, high contrast.

---

## Colour Palette

Use these exact values. Do not approximate or substitute.

| Token | Hex | Usage |
|---|---|---|
| `background` | `#080808` | Page background |
| `surface` | `#0D0D0D` | Cards, modals, sidebars |
| `surface-raised` | `#141414` | Inputs, secondary surfaces |
| `border` | `#1C1C1C` | Default borders |
| `border-strong` | `#2A2A2A` | Focused or hover borders |
| `text-primary` | `#F0F0F0` | Headlines, primary content |
| `text-secondary` | `#808080` | Body text, descriptions |
| `text-muted` | `#505050` | Labels, placeholders |
| `text-faint` | `#404040` | Disabled, metadata |
| `accent` | `#F0F0F0` | CTA buttons (inverted) |
| `accent-fg` | `#080808` | Text on accent backgrounds |
| `destructive` | `#FF4444` | Errors, delete actions |
| `success` | `#22C55E` | Confirmations |
| `warning` | `#F59E0B` | Caution states |

Never use opacity to create colour variants. Always use a named token.

---

## Typography

Font family: Geist Sans for UI, Geist Mono for code and data.

```
font-family: 'Geist Sans', ui-sans-serif, system-ui, sans-serif;
font-family: 'Geist Mono', ui-monospace, monospace; /* data only */
```

### Scale

| Role | Size | Weight | Line Height | Letter Spacing |
|---|---|---|---|---|
| Display | 3rem (48px) | 600 | 1.05 | -0.02em |
| Heading 1 | 2rem (32px) | 600 | 1.1 | -0.015em |
| Heading 2 | 1.25rem (20px) | 500 | 1.3 | -0.01em |
| Heading 3 | 1rem (16px) | 500 | 1.4 | 0 |
| Body | 0.875rem (14px) | 400 | 1.6 | 0 |
| Small | 0.75rem (12px) | 400 | 1.5 | 0 |
| Label | 0.625rem (10px) | 500 | 1 | 0.2em |

### Rules

- Labels above sections: `text-[10px] tracking-[0.25em] uppercase font-medium text-[#404040]`
- Section headings: `text-xs uppercase tracking-widest font-medium text-[#505050]`
- Prices and numeric data: always `font-mono`
- Never use font-weight above 600
- Never use italic except for emphasis within prose

---

## Spacing

Base unit: 4px. Use multiples.

| Step | Value | Tailwind | Use |
|---|---|---|---|
| 1 | 4px | `p-1` | Icon padding, tight gaps |
| 2 | 8px | `p-2` | Inline elements |
| 3 | 12px | `p-3` | Compact components |
| 4 | 16px | `p-4` | Standard component padding |
| 6 | 24px | `p-6` | Card padding |
| 8 | 32px | `p-8` | Section gaps |
| 12 | 48px | `p-12` | Large section padding |
| 16 | 64px | `p-16` | Page sections |

Page horizontal padding: `px-6 sm:px-10 lg:px-16`. Never use `container` or `max-w-*` — layouts are full-width.

---

## Border Radius

Use `rounded-sm` (2px) everywhere. This is the only permitted value.

- Never use `rounded`, `rounded-md`, `rounded-lg`, `rounded-xl`, `rounded-2xl`, or `rounded-full`
- Exception: circular avatar/icon buttons use `rounded-full`
- Pill badges are permitted on tags: `rounded-sm` still applies

---

## Borders

All borders use `border border-[#1C1C1C]` by default.

- Hover / focus: `border-[#2A2A2A]` or `border-[#444444]`
- Use border for separation, never background-color changes
- Dividers: `border-t border-[#1C1C1C]` — never use `<hr>` or box shadows
- Never use `divide-*` utilities — apply borders individually

---

## Shadows

Use sparingly. Only for floating elements (dropdowns, modals, tooltips).

```
box-shadow: 0 8px 32px rgba(0, 0, 0, 0.6);   /* dropdowns, popovers */
box-shadow: 0 24px 64px rgba(0, 0, 0, 0.8);  /* modals */
```

Never use Tailwind's named shadows (`shadow-sm`, `shadow-md`, etc.) — they are too light for dark backgrounds. Use arbitrary values only.

---

## Components

### Button — Primary

```tsx
<button className="px-5 py-2.5 bg-[#F0F0F0] text-[#080808] text-sm font-medium rounded-sm tracking-wide hover:bg-white transition-colors">
  Label
</button>
```

Rules:
- Primary button: inverted (light bg, dark text)
- Hover: `hover:bg-white` — never change bg to a colour
- Never use `shadow` on buttons
- `tracking-wide` always on button labels

### Button — Secondary

```tsx
<button className="px-5 py-2.5 border border-[#2A2A2A] text-[#808080] text-sm font-medium rounded-sm tracking-wide hover:text-[#F0F0F0] hover:border-[#444444] transition-colors">
  Label
</button>
```

### Button — Ghost

```tsx
<button className="px-3 py-1.5 text-sm text-[#505050] hover:text-[#F0F0F0] transition-colors">
  Label
</button>
```

### Input

```tsx
<input className="w-full px-3 py-2 bg-[#111111] border border-[#1C1C1C] rounded-sm text-sm text-[#F0F0F0] placeholder:text-[#404040] focus:outline-none focus:border-[#444444] transition-colors" />
```

Rules:
- Background: `#111111` (slightly lighter than surface)
- Focus: border lightens to `#444444`, no ring, no glow
- Placeholder: `#404040`
- Never use `focus:ring-*`

### Label (form)

```tsx
<label className="block text-xs uppercase tracking-widest text-[#505050] font-medium mb-2">
  Field name
</label>
```

### Card

```tsx
<article className="bg-[#0D0D0D] border border-[#1C1C1C] rounded-sm hover:border-[#333333] hover:shadow-[0_0_30px_rgba(255,255,255,0.03)] transition-all">
  {/* content */}
</article>
```

Rules:
- Cards never have a background brighter than `#141414`
- Hover: border lightens, subtle white glow (very low opacity)
- Use `<article>` for content cards, `<div>` for layout cards

### Badge / Tag

```tsx
<span className="text-[10px] tracking-widest uppercase px-2 py-0.5 bg-[#161616] border border-[#222222] rounded-sm text-[#606060]">
  Label
</span>
```

### Modal

```tsx
<div className="fixed inset-0 bg-black/70 backdrop-blur-sm z-50 flex items-center justify-center p-4">
  <div className="w-full max-w-md bg-[#0D0D0D] border border-[#1C1C1C] rounded-sm shadow-[0_24px_64px_rgba(0,0,0,0.8)] p-6">
    {/* content */}
  </div>
</div>
```

### Dropdown / Popover

```tsx
<div className="absolute right-0 top-[calc(100%+8px)] w-44 bg-[#0D0D0D] border border-[#222222] rounded-sm shadow-[0_8px_32px_rgba(0,0,0,0.6)] z-50 overflow-hidden">
  {/* items */}
</div>
```

### Code / Pre

```tsx
<pre className="bg-[#0D0D0D] border border-[#1C1C1C] rounded-sm p-4 text-xs font-mono text-[#808080] overflow-x-auto">
  {code}
</pre>
```

---

## Iconography

Use Lucide React. Size: 16px (UI), 20px (standalone/hero).

```tsx
import { ArrowRight } from 'lucide-react'
<ArrowRight size={16} />
```

Rules:
- Never use filled icons — outline only
- Colour matches surrounding text by default
- Interactive icons: `text-[#505050] hover:text-[#F0F0F0] transition-colors`
- Never add a background or border to an icon alone — only icon buttons get a container

---

## Navigation

```tsx
<nav className="sticky top-0 z-40 w-full border-b border-[#1A1A1A] bg-[#080808]/90 backdrop-blur-md">
  <div className="w-full px-6 sm:px-10 lg:px-16 h-14 flex items-center justify-between">
    {/* brand | links | actions */}
  </div>
</nav>
```

Rules:
- Height: `h-14` (56px)
- Sticky with `backdrop-blur-md` and 90% opacity background
- Nav links: `text-xs tracking-wide uppercase text-[#505050] hover:text-[#F0F0F0]`
- Brand: `text-base font-semibold tracking-[0.12em] uppercase text-[#F0F0F0]`

---

## Do / Don't

**Do:**
- Use `border` for visual separation, never background changes
- Use `font-mono` for all prices, IDs, counts, and code
- Use `text-[10px] tracking-[0.25em] uppercase` for overline labels
- Use `transition-colors` on every interactive element
- Use `rounded-sm` everywhere (exceptions: `rounded-full` for avatars only)
- Keep hover states subtle — a lightening of border/text, not a colour change

**Don't:**
- Don't use drop shadows on non-floating elements
- Don't use gradients — flat colour only
- Don't use `text-white` — use `text-[#F0F0F0]`
- Don't use `rounded-lg` or larger — this system is sharp
- Don't use background colour changes for hover on cards — use border and shadow
- Don't use more than 3 font weights in a single view
- Don't use animations other than `transition-colors` and `transition-all` with default duration