# Design System — rmendes.net

## Palette

**Surfaces:** Warm stone — not yellow, not cold. The difference is felt, not seen.

| Token | Hex | Role |
|-------|-----|------|
| surface-50 | `#faf8f5` | Canvas (light) |
| surface-100 | `#f4f2ee` | Cards, elevated surfaces (light) |
| surface-200 | `#e8e5df` | Standard borders, dividers |
| surface-300 | `#d5d0c8` | Strong borders, input borders |
| surface-400 | `#a09a90` | Muted text, placeholders |
| surface-500 | `#7a746a` | Secondary text |
| surface-600 | `#5c5750` | Supporting text |
| surface-700 | `#3f3b35` | Dark mode borders |
| surface-800 | `#2a2722` | Cards, elevated surfaces (dark) |
| surface-900 | `#1c1b19` | Canvas (dark) |
| surface-950 | `#0f0e0d` | Deepest dark |

**Accent (Warm Amber):** Default interactive color — links, CTAs, focus rings.

| Token | Hex | Usage |
|-------|-----|-------|
| accent-400 | `#fbbf24` | Dark mode: links, hover |
| accent-500 | `#f59e0b` | — |
| accent-600 | `#d97706` | Light mode: links, buttons |
| accent-700 | `#b45309` | Light mode: hover, pressed |

## Domain Colors

Every post type and section has its own unique color identity. On collection pages, sparklines, card borders, icons, labels, hover states, and permalink links all use the domain color. No two post types share the same color.

### Post Type Colors (each unique — no sharing)

| Post Type | Tailwind color | Light text | Dark text | Icon | Pages |
|-----------|---------------|------------|-----------|------|-------|
| **Articles** | indigo | indigo-600 | indigo-400 | document | `/articles/` |
| **Notes** | teal | teal-600 | teal-400 | chat bubble | `/notes/` |
| **Bookmarks** | amber | amber-600 | amber-400 | bookmark | `/bookmarks/` |
| **Likes** | red | red-600 | red-400 | heart (filled) | `/likes/` |
| **Replies** | sky | sky-600 | sky-400 | reply arrow | `/replies/` |
| **Reposts** | green | green-600 | green-400 | refresh arrows | `/reposts/` |
| **Photos** | purple | purple-600 | purple-400 | camera | `/photos/` |

Each color is applied consistently across: sparkline wrapper, card `border-l`, SVG icon, label text, title hover, and permalink link.

### Section Colors (non-post-type pages)

| Section | Tailwind color | Light text | Dark text | Pages |
|---------|---------------|------------|-----------|-------|
| **Blog** (mixed) | amber | amber-600 | amber-400 | `/blog/` (sparkline only — individual cards use their post-type color) |
| **Code** | emerald | emerald-600 | emerald-400 | `/github/`, `/github/starred/` |
| **Music** | purple | purple-600 | purple-400 | `/funkwhale/`, `/listening/` |
| **Video** | red | red-600 | red-400 | `/youtube/` |
| **Reading** | orange | orange-600 | orange-400 | `/blogroll/`, `/podroll/`, `/readlater/` |
| **Neutral** | accent (amber) | — | — | `/` (home), `/about/`, `/cv/`, `/slashes/`, `/search/`, `/changelog/`, `/404` |

### Brand Colors (hardcoded hex — not domain colors)

These are third-party brand colors used in syndication badges and social widgets. Not part of the domain system.

| Brand | Hex | Where |
|-------|-----|-------|
| Mastodon | `#a730b8` | Syndication badges, social-activity widget |
| Bluesky | `#0085ff` | Syndication badges, social-activity widget |
| LinkedIn | `#0a66c2` | Syndication badges |
| IndieNews | `#ff5c00` | Syndication badges |
| Mastodon alt | `#6364ff` | Syndication badges |

### Domain Prominence (medium)

On a domain page, these elements adopt the domain color:
- **Page title** — tinted text or accent underline
- **Links** — `text-[domain]-600 dark:text-[domain]-400`
- **Hover states** — `hover:text-[domain]-700 dark:hover:text-[domain]-300`
- **Card borders on hover** — `hover:border-[domain]-400 dark:hover:border-[domain]-600`
- **Post-type badges** — domain-colored background/text

These stay neutral (accent or surface) regardless of domain:
- Header/navigation
- Sidebar widget containers
- Footer
- Global UI (search, theme toggle)

## Depth

**Subtle shadows.** One consistent shadow level for elevated surfaces. Borders + shadow together.

| Element | Treatment |
|---------|-----------|
| Cards, widgets | `shadow-sm` + `border border-surface-200 dark:border-surface-700` |
| Avatars, album art | `shadow-lg` (depth gives images presence against flat surfaces) |
| Modals | `shadow-xl` (overlay needs clear elevation) |
| Hover on cards | No shadow change — border color shift only |

**Gradients are allowed** for:
- Now-playing cards (domain color tinted: `bg-gradient-to-br from-[color]-500/10`)
- YouTube hero/live cards
- Icon containers in reading pages (`from-[color]-400 to-[color]-600`)

Gradients are NOT used for:
- Standard cards, widgets, or page backgrounds

## Typography

| Role | Style | Usage |
|------|-------|-------|
| Page titles | Inter, `text-2xl sm:text-3xl font-bold` | Main page headings |
| Section headings | Inter, `text-xl sm:text-2xl font-bold` | Widget titles, section headers |
| Subheadings | Inter, `text-lg font-semibold` | Card titles, list item titles |
| Body | Inter, `text-sm` or `text-base` | Paragraphs, descriptions |
| Labels | Inter, `font-medium` or `font-semibold` | Badges, nav items, metadata labels |
| **Dates/timestamps** | **`font-mono text-sm`** | Every `<time>` element, stat numbers, version numbers |
| Code | `font-mono` | Commit SHAs, code blocks, technical identifiers |
| Small text | `text-xs` | Metadata, secondary info, captions |

### Date treatment rule

Every rendered date (via `dateDisplay` or `date()` filter) gets `font-mono`. This adds technical texture throughout the site — like timestamps in a log.

### Weight scale

| Weight | Class | Frequency | Usage |
|--------|-------|-----------|-------|
| 400 | (default) | Body text | Paragraphs, descriptions |
| 500 | `font-medium` | 146x | Labels, metadata, nav items |
| 600 | `font-semibold` | 100x | Subheadings, emphasis |
| 700 | `font-bold` | 138x | Page titles, section headings |

## Spacing

Base: 4px (Tailwind default rem scale).

### Spacing scale (by frequency)

| Token | px | Frequency | Primary usage |
|-------|-----|-----------|---------------|
| `0.5` | 2px | 62x | Micro gaps (badge padding-y, icon margins) |
| `1` | 4px | 150x | Tight internal spacing |
| `1.5` | 6px | 45x | Button padding-y, small gaps |
| `2` | 8px | 350x+ | Standard small spacing (px, py, gap, m) |
| `3` | 12px | 180x | Standard medium spacing |
| `4` | 16px | 200x+ | Card padding, section gaps |
| `5` | 20px | 30x | Featured card padding |
| `6` | 24px | 80x | Section margins |
| `8` | 32px | 40x | Large section separation |
| `10` | 40px | 8x | Page-level vertical rhythm |
| `12` | 48px | 5x | Major section breaks |

### Common spacing patterns

| Pattern | Classes | Where |
|---------|---------|-------|
| Card padding | `p-4` | Standard cards, widgets |
| Compact padding | `p-3` | List items, tight cards |
| Featured padding | `p-5` | Hero cards, featured items |
| Tight list gap | `gap-2` | Inline elements, tag lists |
| Standard gap | `gap-3` | Card grids, form elements |
| Spacious gap | `gap-4` | Section-level grids |
| Section break | `mb-6` to `mb-8` | Between page sections |
| Badge padding | `px-2 py-0.5` | Small badges, pills |
| Pill padding | `px-3 py-1.5` | Larger pills, filter buttons |

## Border Radius

| Element | Radius | Frequency |
|---------|--------|-----------|
| Cards, inputs, buttons | `rounded-lg` | 154x (dominant) |
| Avatars, status dots, badges | `rounded-full` | 134x |
| Featured/hero cards | `rounded-xl` | 23x |
| Now-playing sections | `rounded-xl sm:rounded-2xl` | 2x |
| Audio players | `rounded-md` | — |

## Card Patterns

Five distinct card variants used across the site:

### Standard card (`.post-card`)
```
p-5 bg-surface-50 dark:bg-surface-800 rounded-lg border border-surface-200 dark:border-surface-700 shadow-sm
hover: border-[domain]-400 dark:border-[domain]-600
```
Used for: blog post listings, search results

### Widget card (`.widget`)
```
p-4 bg-surface-50 dark:bg-surface-800 rounded-lg border border-surface-200 dark:border-surface-700 shadow-sm
```
Used for: sidebar widgets, info panels

### Compact list card
```
p-3 bg-surface-50 dark:bg-surface-800 rounded-lg border border-surface-200 dark:border-surface-700 shadow-sm
```
Used for: list view items in news/podroll, compact listings

### Featured card
```
p-5 sm:p-6 bg-gradient-to-br from-[color]-500/10 rounded-xl border border-surface-200 dark:border-surface-700 shadow-sm
```
Used for: now-playing, YouTube hero, featured items

### Stat card
```
p-3 sm:p-4 bg-surface-50 dark:bg-surface-800 rounded-lg border border-surface-200 dark:border-surface-700 shadow-sm text-center
```
Used for: statistics grids (GitHub, Funkwhale, Last.fm)

## Button Patterns

Six button variants:

### Primary action
```
px-4 py-2 bg-accent-600 hover:bg-accent-700 text-white rounded-lg font-medium
focus:ring-2 focus:ring-accent-500 transition-colors
```
Used for: form submits, main CTAs

### Secondary action
```
px-3 py-1.5 bg-surface-100 dark:bg-surface-800 hover:bg-surface-200 dark:hover:bg-surface-700
border border-surface-200 dark:border-surface-700 rounded-lg text-sm font-medium
focus:ring-2 focus:ring-accent-500 transition-colors
```
Used for: filter toggles, view mode switches, secondary actions

### Icon button
```
p-2 rounded-lg hover:bg-surface-200 dark:hover:bg-surface-700
focus:ring-2 focus:ring-accent-500 transition-colors
```
Used for: theme toggle, menu toggle, refresh buttons

### Domain-colored button
```
px-3 py-1.5 bg-[domain]-600 hover:bg-[domain]-700 text-white rounded-lg text-sm font-medium
focus:ring-2 focus:ring-[domain]-500 transition-colors
```
Used for: domain-specific actions (e.g., orange "Load More" on podroll)

### Link button
```
text-[domain]-600 dark:text-[domain]-400 hover:text-[domain]-700 dark:hover:text-[domain]-300
hover:underline font-medium transition-colors
```
Used for: inline actions, "View all" links

### Pagination button
```
px-3 py-1 bg-surface-100 dark:bg-surface-800 hover:bg-surface-200 dark:hover:bg-surface-700
border border-surface-200 dark:border-surface-700 rounded-lg text-sm
focus:ring-2 focus:ring-accent-500 transition-colors
disabled:opacity-50 disabled:cursor-not-allowed
```
Used for: pagination controls

## Badge/Pill Patterns

Four badge variants:

### Post-type badge
```
px-2 py-0.5 text-xs font-medium rounded-full
bg-[domain]-100 dark:bg-[domain]-900/30 text-[domain]-700 dark:text-[domain]-300
```
Used for: post type indicators on cards

### Category tag
```
px-2 py-0.5 text-xs bg-surface-100 dark:bg-surface-800
text-surface-600 dark:text-surface-400 rounded-full
hover:bg-surface-200 dark:hover:bg-surface-700 transition-colors
```
Used for: category tags, hashtags

### Status badge
```
px-2 py-0.5 text-xs font-medium rounded-full
bg-emerald-100 dark:bg-emerald-900/30 text-emerald-700 dark:text-emerald-300
```
Variants: emerald (active/success), amber (warning), red (error)
Used for: status indicators, sync state

### Syndication badge
```
px-2 py-0.5 text-xs font-medium rounded-full text-white
bg-[brand-hex]
```
Used for: Mastodon/Bluesky/LinkedIn syndication indicators

## Layout Patterns

### Page layouts

| Layout | Classes | Usage |
|--------|---------|-------|
| Full-width | `max-w-7xl mx-auto px-4 sm:px-6` | Page container |
| With sidebar | `.layout-with-sidebar` = `grid grid-cols-1 lg:grid-cols-[1fr_320px] gap-6 lg:gap-8` | Blog, post pages |
| Content area | `.main-content` = `min-w-0` (prevents overflow in grid) | Main column |
| Sidebar | `.sidebar` = `space-y-4 lg:space-y-6` | Sidebar column |
| Centered narrow | `max-w-3xl mx-auto` | About, CV pages |

### Grid patterns

| Pattern | Classes | Usage |
|---------|---------|-------|
| Stats grid | `grid grid-cols-2 sm:grid-cols-4 gap-3` | Statistics panels |
| Card grid | `grid grid-cols-1 sm:grid-cols-2 gap-4` | Card view mode |
| Post list | `space-y-4` or `space-y-3` | List view mode |
| Widget stack | `space-y-4 lg:space-y-6` | Sidebar widgets |

### Responsive breakpoints

| Breakpoint | px | Frequency | Purpose |
|------------|-----|-----------|---------|
| `sm:` | 640px | 170x+ | Primary responsive step (dominant) |
| `md:` | 768px | 19x | Tablet-specific adjustments |
| `lg:` | 1024px | 6x | Sidebar layout switch |

**Mobile-first:** Base styles are mobile. `sm:` is the primary breakpoint for responsive changes. Most layouts switch from stacked to side-by-side at `sm:`.

## Interaction States

Every interactive element needs:
- **hover:** color shift (`transition-colors` — dominant at 131x)
- **focus:** visible ring (`focus:ring-2 focus:ring-accent-500` or domain equivalent)
- **active:** not currently implemented — add where it matters (buttons)

### Hover patterns

| Element | Hover treatment |
|---------|----------------|
| Text links | `hover:underline` (163x — dominant link hover) |
| Card borders | `hover:border-[domain]-400 dark:hover:border-[domain]-600` |
| Buttons (filled) | Background darken (`hover:bg-[color]-700`) |
| Buttons (ghost) | `hover:bg-surface-200 dark:hover:bg-surface-700` |
| Nav items | `hover:text-surface-900 dark:hover:text-surface-100` |

### Focus pattern

All interactive elements: `focus:ring-2 focus:ring-[domain]-500 rounded` (or `focus:ring-accent-500` on neutral pages).

### Transitions

Default: `transition-colors` (131x). No duration override — uses Tailwind default (150ms).

Exceptions:
- Collapsible widgets: `transition-all` for height animation
- Mobile menu: `transition-transform` for slide-in

## Dark Mode

- Class-based: `darkMode: "class"` — toggled via button in header
- Surfaces invert: light canvas (`surface-50`) -> dark canvas (`surface-900`)
- Cards: `surface-100` -> `surface-800`
- Domain colors shift to 400-weight (brighter) in dark mode
- Borders: `surface-200` -> `surface-700`
- Shadows remain `shadow-sm` (less visible but still present for subtle lift)

### Dark mode pairs (reference)

| Light | Dark |
|-------|------|
| `bg-surface-50` | `dark:bg-surface-900` (canvas) |
| `bg-surface-100` | `dark:bg-surface-800` (cards) |
| `bg-surface-200` | `dark:bg-surface-700` (hover bg) |
| `border-surface-200` | `dark:border-surface-700` |
| `text-surface-900` | `dark:text-surface-100` (primary text) |
| `text-surface-600` | `dark:text-surface-400` (secondary text) |
| `text-[domain]-600` | `dark:text-[domain]-400` (domain color) |
| `bg-[domain]-100` | `dark:bg-[domain]-900/30` (badge bg) |

## CSS Component Classes

Reusable utility classes defined in `css/tailwind.css`:

| Class | Definition | Usage |
|-------|------------|-------|
| `.widget` | `p-4 bg-surface-50 rounded-lg border shadow-sm` + dark | Sidebar widgets |
| `.widget-title` | `text-lg font-semibold` | Widget headings |
| `.widget-header` | `flex items-center justify-between mb-3` | Widget header row |
| `.widget-collapsible` | Alpine.js collapsible wrapper | Expandable widgets |
| `.post-card` | `p-5 bg-surface-50 rounded-lg border shadow-sm` + dark | Post listing cards |
| `.post-list` | `space-y-4` | Post list container |
| `.layout-with-sidebar` | `grid grid-cols-1 lg:grid-cols-[1fr_320px] gap-6 lg:gap-8` | Two-column layout |
| `.main-content` | `min-w-0` | Main column (prevents grid overflow) |
| `.sidebar` | `space-y-4 lg:space-y-6` | Sidebar stack |
| `.share-post-btn` | Blue share button | Post sharing |
| `.save-later-btn` | Accent save button | Read-later action |

## What Needs Implementation

Audit findings — remaining gaps between this system and the current code:

1. ~~**Domain colors on section pages**~~ — ✅ Done: all 7 post-type collections + blog.njk mixed view + recent-posts widget use per-type colors
2. **Active states** — add to buttons where appropriate
3. **Consistent card hover** — some older templates use `hover:border-surface-400` instead of domain-colored border hover