Gruvbox

---
name: gruvbox
description: Apply the Gruvbox visual design system when building or restyling websites and UI. Use whenever the user asks to build, theme, restyle, or "make it look like" Gruvbox, mentions gruvbox dark, retro groove, warm terminal theme, or describes warm brown-charcoal base, cream and beige text, earthy retro accent set — even if they don't name the style explicitly. Do NOT use for non-visual tasks or when another named design system is requested.
license: MIT
---

# Gruvbox Design System

Retro groove: a warm brown-black base with cream text and earthy, slightly washed-out brights — orange, yellow, aqua, faded green. The analog-warmth counterpoint to cool dark themes, like a terminal printed on aged paper in the 1970s.

Apply this system holistically: colors, type, spacing, radius, borders, shadows, and motion together produce the look. Token values come from the officially published token set. When in doubt, match the reference sites listed at the end.

## When to use

- Building a new page or component that should read as Gruvbox.
- Restyling existing UI to this aesthetic.
- The user names the style, an alias (gruvbox dark, retro groove, warm terminal theme, vim gruvbox), or describes its traits: warm brown-charcoal base; cream and beige text; earthy retro accent set; signature orange highlight; analog 70s warmth.

## Design tokens

### Color palette

- Page background — gruvbox dark bg0: `#282828` (--color-bg)
- Hard-contrast recessed background, code wells — bg0_h: `#1d2021` (--color-bg-hard)
- Cards and panels — bg1: `#3c3836` (--color-surface)
- Borders and dividers — bg2: `#504945` (--color-border)
- Primary text, warm cream — fg1: `#ebdbb2` (--color-text)
- Secondary text — fg4: `#a89984` (--color-text-muted)
- Comments, disabled, faint UI — gruvbox gray: `#928374` (--color-gray)
- Primary accent, links and CTAs — bright orange: `#fe8019` (--color-accent)
- Secondary accent and highlights — bright yellow: `#fabd2f` (--color-accent-2)
- Success and additions — bright green: `#b8bb26` (--color-green)
- Errors and deletions — bright red: `#fb4934` (--color-red)
- Info, tags, alt accent — bright aqua: `#8ec07c` (--color-aqua)

### Typography

- Display / headings: IBM Plex Mono (fallback: Courier New, monospace)
- Body: IBM Plex Sans (fallback: Helvetica, Arial, sans-serif)
- Mono / data: IBM Plex Mono (fallback: Courier New, monospace)
- Type scale: 1.25 ratio, base 16px — computed steps: 16px / 20px / 25px / 31px / 39px / 49px (body / h5 / h4 / h3 / h2 / h1; scale further for display sizes)
- Headings: weight 700, line-height 1.25, letter-spacing 0
- Body: line-height 1.65, letter-spacing 0

### Spacing, radius, border

- Spacing scale (px): 4, 8, 16, 24, 32, 48, 64 — Workmanlike and even — gruvbox came from Vim, so lean on consistent rhythm and modest padding; it should feel like a well-organized workshop, not a gallery.
- Border radius: none 0px, sm 4px — Keep corners near-sharp; heavy rounding reads too soft for the retro register.
- Border treatment: 1px solid #504945 — bg2 hairlines; a 3px solid orange left border marks callouts and active nav items.

### Shadows

- none: `none` — Default everywhere — gruvbox is flat; the bg0_h/bg0/bg1/bg2 ladder handles depth
- modal: `0 8px 28px rgba(29, 32, 33, 0.6)` — Modals only, shadow tinted with bg0_h

### Layout

- Max content width: 1140px
- Depth via the published contrast ladder: bg0_h wells, bg0 page, bg1 cards, bg2 borders
- Orange is the single hero accent; yellow/aqua/green/red carry semantic or category color
- Docs-and-dashboard friendly: monospace headers with cream body text over warm surfaces

### Effects

- Code blocks on bg0_h #1d2021 with verbatim gruvbox syntax colors and a gray #928374 comment tone
- Callout blocks with 3px orange or aqua left borders on bg1

### Motion

- Easing: cubic-bezier(0.4, 0, 0.2, 1); durations 100ms / 180ms / 280ms
- Minimal, utilitarian motion — background-step hovers and instant focus rings
- No glows or springs; gruvbox predates and rejects neon effects

## CSS variables (drop-in)

```css
:root {
  --color-bg: #282828;
  --color-bg-hard: #1d2021;
  --color-surface: #3c3836;
  --color-border: #504945;
  --color-text: #ebdbb2;
  --color-text-muted: #a89984;
  --color-gray: #928374;
  --color-accent: #fe8019;
  --color-accent-2: #fabd2f;
  --color-green: #b8bb26;
  --color-red: #fb4934;
  --color-aqua: #8ec07c;
  --radius-none: 0px;
  --radius-sm: 4px;
  --shadow-modal: 0 8px 28px rgba(29, 32, 33, 0.6);
  --border-default: 1px solid #504945;
  --font-display: "IBM Plex Mono", "Courier New", monospace;
  --font-body: "IBM Plex Sans", Helvetica, Arial, sans-serif;
  --font-mono: "IBM Plex Mono", "Courier New", monospace;
  --text-base: 16px;
  --leading-heading: 1.25;
  --leading-body: 1.65;
  --tracking-heading: 0;
  --tracking-body: 0;
  --ease: cubic-bezier(0.4, 0, 0.2, 1);
  --duration-fast: 100ms;
  --duration-base: 180ms;
  --duration-slow: 280ms;
}
```

Google Fonts: `<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin><link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono:wght@400;600;700&family=IBM+Plex+Sans:wght@400;600&display=swap" rel="stylesheet">`

## Component recipes

- **Nav:** Flat bar on bg0 with a 1px bg2 bottom border; links in fg4 #a89984, active link in cream with a 3px orange underline block.
- **Hero:** IBM Plex Mono headline in cream on bg0 with one word in orange #fe8019; sub-copy in fg4; a terminal-style code sample on bg0_h anchors the fold.
- **Card:** bg1 #3c3836 panel, 4px radius, 1px bg2 border, 20px padding; category tag in aqua or yellow, title cream, meta in gray #928374.
- **Button (primary):** Orange #fe8019 fill with bg0_h #1d2021 text, 4px radius, 600 weight; hover shifts to yellow #fabd2f.
- **Button (secondary):** Transparent, 1px #665c54 border, cream text; hover fills bg1 and warms border to orange.
- **Form fields:** bg1 input with 1px bg2 border, 4px radius; focus border turns orange with no glow; placeholder in gray #928374.

Where this spec is silent (footers, responsive breakpoints, empty states), derive the treatment from the tokens above and the Do/Don't rules — never fall back to generic defaults. Every interactive element needs a visible keyboard focus state consistent with the style (use the accent color or the border treatment, not the browser default).

## Signature element

The warm collision of bright orange #fe8019 and mustard yellow #fabd2f against brown-black #282828 with cream #ebdbb2 text — a palette that feels sun-faded and analog where every other dark theme feels backlit and cold. Spend boldness here; keep everything else quiet.

## Do

- Stay warm: every neutral in gruvbox has a brown-yellow cast — never mix in cool grays
- Use the bright accent variants on dark backgrounds, as the published dark palette specifies
- Let orange be the one loud voice; everything else stays earthy and supporting
- Use bg0_h for code wells to get the published hard-contrast depth for free

## Don't

- Don't add blue-tinted surfaces or shadows — a single cool gray breaks the analog warmth instantly
- Don't use pure white text; cream #ebdbb2 (or #fbf1c7 for emphasis) is the ceiling
- Don't set meaningful text in gray #928374 — it is the comment tone, deliberately faint

## Accessibility notes

- Cream fg1 #ebdbb2 on bg0 #282828 is strong (~10:1); fg4 #a89984 passes AA (~5.3:1) for secondary text
- Gray #928374 on bg0 is ~4:1 — below AA for body text; reserve it for large text or decorative comment styling
- Bright accents (orange, yellow, green, aqua) all pass AA as text on bg0; red #fb4934 is ~5:1 and fine for error text
- Accent-filled buttons need the darkest neutral (#1d2021) as text; cream on orange fails AA
- A published light palette (cream backgrounds, faded accents) exists for a faithful light mode

## Reference sites

- Gruvbox GitHub repository: https://github.com/morhetz/gruvbox

For the exhaustive machine-readable spec, see references/tokens.md and tokens.json in this skill folder.

Install this skill

unzip gruvbox.zip -d ~/.claude/skills/

npx shadcn add https://claude-design-skills.convoke.software/r/gruvbox.json

Settings → Capabilities → Skills → Upload skill → gruvbox.zip