A DesignMD user

Generated May 19, 2026

DESIGN.md for openspec.dev

openspec.dev

Preview

the generated design system

Switch between the rendered Visual preview and the Raw DESIGN.md.

Design System Inspired by OpenSpec

1. Visual Theme & Atmosphere

OpenSpec's design embodies a minimalist, technical aesthetic grounded in precision and clarity. The system prioritizes readability and spec-driven structure through monospaced typography, ultra-thin borders, and high-contrast layouts on a near-black backdrop. The visual language feels like reading technical documentation—clean, unburdened, and direct—while selective accent colors (blue, lime green, and coral) provide semantic meaning without visual noise. This is a design system built for developers, by developers, where every pixel serves the specification rather than decoration.

Key Characteristics

Pure technical minimalism with zero ornamental elements
Monospaced typography as the primary design voice
High-contrast dark backgrounds with crisp, thin 2px borders
Semantic color coding for status and interactive states
Extreme restraint in padding and spacing—every element precisely justified
Grid-based layouts with no visual filler
Clear information hierarchy through size and weight alone

2. Color Palette & Roles

Primary

Deep Background (#09090B): Primary container background for the entire interface, creating maximum contrast for content
Off-Black (#000000): Pure black accents and text on light surfaces, strongest possible contrast

Accent Colors

Cyan Blue (#60A5FA): Primary interactive accent for links, highlights, and focal points; represents action and emphasis
Lime Green (#7EE787): Success and positive states; used for accepted specs and passing scenarios
Coral Red (#FFA198): Warning and cautionary states; indicates potential issues or deprecated items
Error Red (#F85149): Critical errors and failed states; strongest semantic warning

Interactive

Ghost Button Text (#A1A1AA): Neutral interactive text for navigation, secondary actions, and borderless buttons
Button Active (#E8E8E8): Light neutral for active button states and hover effects
Input Border (#3F3F46): Subtle borders on form inputs and cards, providing definition without harshness

Neutral Scale

Surface Light (#FFFFFF): Pure white text and minimal highlights on dark backgrounds
Subtle Gray (#F4F4F5): Very light background accents and secondary surfaces
Border Gray (#E8E8E8): Card and container borders, large-use neutral element
Mid Gray (#71717A): Secondary text and muted content
Dark Gray (#27272A): Tertiary backgrounds and recessive elements

Surface & Borders

Card Border (#27272A): 2px borders defining card and container boundaries
Border (#3F3F46): Primary border color for inputs, dividers, and structural elements
Near-Black (#0A0A0A): Deepest background layer for nested or floating content

Semantic / Status

Success State (#2EA043): Primary success indicator for validated specs and positive outcomes
Success Bright (#22C55E): Brighter success color for prominent success messaging and scenarios
Warning State (#C8E64A): Warning color for cautions and advisory information
Error State (#EF4444): Error indicator for failed specs and blocking issues

3. Typography Rules

Font Family

Primary: 'JetBrains Mono', 'Courier New', monospace
A technical monospaced font chosen for its precision and developer familiarity. Every measurement feels intentional.

Secondary: Arial, 'Helvetica Neue', sans-serif
Used for button labels where slightly more neutrality is required.

Hierarchy

Role	Font	Size	Weight	Line Height	Letter Spacing	Notes
Display H1	JetBrains Mono	18.8px	400	1.2	0px	Main page headline; large but restrained
Heading H2	JetBrains Mono	16.45px	700	normal	0px	Section headers; only role using weight 700
Heading H3	JetBrains Mono	14.1px	400	normal	0px	Subsection headers and feature titles
Body / Paragraph	JetBrains Mono	18.8px	400	1.6	0px	Primary content text; generous default line height
Body Large	JetBrains Mono	16.45px	400	1.5	0px	Links and interactive text
Button	Arial	13.3333px	400	normal	0px	Button labels; slightly smaller than body
Caption / Small	JetBrains Mono	15.04px	400	1.8	0px	List items and secondary content
Code / Meta	JetBrains Mono	14.1px	400	normal	0px	Inline code and metadata text

Principles

All typography is monospaced to enforce consistency and technical credibility
Font weights are minimal—use size and semantic color to establish hierarchy, not weight
Line heights default to normal (1.0) except for body text and lists, which use 1.6–1.8 for readability
No letter-spacing is applied; monospaced alignment is exact
Typography scale follows a rational progression: 13.3 → 14.1 → 15.04 → 16.45 → 18.8px
Every font size value is preserved from extraction to ensure pixel-perfect fidelity

4. Component Stylings

Buttons

Primary Button (Light Fill)

background-color: #E8E8E8
color: #09090B
font-family: 'JetBrains Mono', monospace
font-size: 16.45px
font-weight: 400
padding: 14.1px 28.2px
border: 1px solid #E8E8E8
border-radius: 0px
box-shadow: none
height: auto
line-height: normal

Hover State:

background-color: #FFFFFF
border-color: #FFFFFF

Secondary Button (Ghost)

background-color: transparent
color: #A1A1AA
font-family: 'JetBrains Mono', monospace
font-size: 14.1px
font-weight: 400
padding: 23.5px
border: 0px none
border-radius: 0px
box-shadow: none
height: auto
line-height: normal

Hover State:

color: #E8E8E8

Ghost Button (Minimal)

background-color: transparent
color: #A1A1AA
font-family: 'JetBrains Mono', monospace
font-size: 14.1px
font-weight: 400
padding: 0px
border: 0px none
border-radius: 0px
box-shadow: none
height: auto
line-height: normal

Hover State:

color: #60A5FA

Cards & Containers

Card (Default)

background-color: #09090B
color: #FFFFFF
font-family: 'JetBrains Mono', monospace
font-size: 18.8px
font-weight: 400
padding: 0px
border: 2px solid #27272A
border-radius: 0px
box-shadow: rgb(39, 39, 42) 0px 0px 0px 2px, rgba(0, 0, 0, 0.05) 0px 1px 2px 0px
line-height: normal

Card (With Padding)

background-color: #09090B
color: #FFFFFF
font-family: 'JetBrains Mono', monospace
font-size: 18.8px
font-weight: 400
padding: 37.6px
border: 2px solid #27272A
border-radius: 0px
box-shadow: rgb(39, 39, 42) 0px 0px 0px 2px, rgba(0, 0, 0, 0.05) 0px 1px 2px 0px
line-height: normal

Container (Large)

background-color: #09090B
color: #FFFFFF
font-family: 'JetBrains Mono', monospace
font-size: 18.8px
font-weight: 400
padding: 0px
border: 2px solid #27272A
border-radius: 0px
box-shadow: rgb(39, 39, 42) 0px 0px 0px 2px, rgba(0, 0, 0, 0.05) 0px 1px 2px 0px
line-height: normal

Inputs & Forms

Text Input

background-color: transparent
color: #E8E8E8
font-family: 'JetBrains Mono', monospace
font-size: 16.45px
font-weight: 400
padding: 14.1px 18.8px
border: 1px solid #3F3F46
border-radius: 0px
box-shadow: none
height: 52.1875px
line-height: normal

Focus State:

border-color: #60A5FA
color: #FFFFFF

Placeholder:

color: #71717A

Navigation

Vertical Navigation

background-color: transparent
color: #FFFFFF
font-family: 'JetBrains Mono', monospace
font-size: 18.8px
font-weight: 400
padding: 0px
border: 0px none
border-radius: 0px
box-shadow: none
line-height: normal

Link in Navigation:

color: #A1A1AA
text-decoration: none

Active Link:

color: #60A5FA

Links

Text Link

background-color: transparent
color: #E8E8E8
font-family: 'JetBrains Mono', monospace
font-size: 16.45px
font-weight: 400
padding: 0px
border: 0px none
border-radius: 0px
box-shadow: none
text-decoration: none
line-height: normal
cursor: pointer

Hover State:

color: #60A5FA
text-decoration: underline

Code Block

background-color: #000000
color: #E8E8E8
font-family: 'JetBrains Mono', monospace
font-size: 14.1px
font-weight: 400
padding: 16px
border: 1px solid #3F3F46
border-radius: 0px
box-shadow: none
line-height: 1.6
overflow-x: auto

Status Badge

Success

background-color: #2EA043
color: #FFFFFF
font-family: 'JetBrains Mono', monospace
font-size: 14.1px
font-weight: 400
padding: 4px 8px
border: 0px none
border-radius: 0px
line-height: normal

Warning

background-color: #C8E64A
color: #09090B
font-family: 'JetBrains Mono', monospace
font-size: 14.1px
font-weight: 400
padding: 4px 8px
border: 0px none
border-radius: 0px
line-height: normal

Error

background-color: #EF4444
color: #FFFFFF
font-family: 'JetBrains Mono', monospace
font-size: 14.1px
font-weight: 400
padding: 4px 8px
border: 0px none
border-radius: 0px
line-height: normal

5. Layout Principles

Spacing System

Base Unit: 4px

Scale:

4px: Micro spacing for internal padding in small elements
8px: Tight spacing for button padding, small gaps
12px: Not explicitly extracted but inferred for small gaps
16px: Standard padding for most containers
20px: Comfortable spacing between sections
24px: Generous spacing for major sections
28px: Large section dividers
32px: Extra-large container padding
36px: Massive padding for sprawling content areas
76px: Page-level gutters and margins
188px: Hero section and full-bleed spacing

Usage Context:

Input padding: 14.1px (between 8px and 16px)
Card padding (standard): 37.6px (between 32px and 76px)
Button padding: 28.2px horizontal, 14.1px vertical
Navigation padding: 23.5px for list-item spacing

Grid & Container

Max Width: No hard constraint; layout is full-bleed with side padding
Columns: Implicit single-column layout on mobile, multi-column grids on desktop via CSS Grid or Flexbox
Gutters: Horizontal padding of 76px on pages; reduced to 20px–24px on smaller viewports
Sections: Full-width containers stacked vertically with 24px–36px gaps
Card Width: Cards span full container width (typically 1100px on desktop)

Whitespace Philosophy

Whitespace in OpenSpec is structural, not decorative. Every pixel of space is justified by content flow and readability. The system avoids bloat by using tight padding within cards (0px in some cases) while maintaining generous margins between major sections. This creates visual breathing room without appearing empty—the monospaced text and thin borders provide sufficient visual weight.

Border Radius Scale

0px: All elements use sharp, right-angle corners—no rounding
50%: Reserved for circular elements (avatars, icon buttons) if needed, but generally avoided

6. Depth & Elevation

Level	Treatment	Use
Base	`none`	Default surface background (near-black)
Raised (Small)	`rgb(39, 39, 42) 0px 0px 0px 2px, rgba(0, 0, 0, 0.05) 0px 1px 2px 0px`	Cards, containers, subtle elevation
Raised (Medium)	`rgb(39, 39, 42) 0px 0px 0px 2px, rgba(0, 0, 0, 0.5) 0px 4px 24px 0px`	Modals, dropdowns, prominent overlays
Overlay	`0px 12px 28px rgba(0, 0, 0, 0.8)`	Floating elements, tooltips (inferred)
Inline	`none`	Text, buttons, inline controls

Shadow Philosophy:

OpenSpec's elevation system is restrained and technical. Rather than soft, photorealistic shadows, the design uses crisp, geometric borders (2px solid) paired with minimal drop shadows. The small shadow (0px 1px 2px) creates subtle depth for cards, while the larger shadow (0px 4px 24px) reserves itself for modal overlays. This approach maintains the minimalist aesthetic while providing just enough visual separation to prevent UI elements from feeling flat or merged.

7. Do's and Don'ts

Do

Use #09090B as the default background for all surfaces—maintain this consistent deep-black foundation
Apply the 2px #27272A border to every card and container to create clear visual boundaries
Reserve all color accents (#60A5FA, #7EE787, #FFA198) for semantic meaning: links, success, warnings
Maintain monospaced typography throughout; font-family should always reference JetBrains Mono as primary
Use #A1A1AA for secondary/ghost button text and navigation items to indicate lower action priority
Set border-radius to 0px globally; no rounded corners anywhere in the system
Apply precise padding values from the scale (14.1px, 23.5px, 37.6px) without deviation
Use the small shadow (0px 0px 0px 2px, rgba(0, 0, 0, 0.05) 0px 1px 2px 0px) for standard cards
Pair line-height: normal with monospaced text for tight, technical appearance
Use #E8E8E8 for primary button background fill; use #E8E8E8 for input borders

Don't

Never apply border-radius values other than 0px or 50%
Never use sans-serif fonts where JetBrains Mono is specified; preserve monospace hierarchy
Avoid colored backgrounds on cards—stick to #09090B or deepest background layers
Don't use drop shadows without the accompanying 2px border; shadows must follow the pair format
Never apply letter-spacing or additional font-weight modifications to typography scale
Avoid light gray text (#E8E8E8) on light backgrounds; always maintain high contrast
Don't deviate from the extracted hex values—all colors must match exactly
Never add rounded corners to buttons, inputs, cards, or containers
Avoid mixing accent colors within a single component; each semantic use should stand alone
Don't add unnecessary padding or margin outside the documented scale values
Avoid hover states that alter color significantly; use subtle brightness shifts or underlines instead

8. Responsive Behavior

Breakpoints

Breakpoint Name	Width	Key Changes
Mobile	320px–767px	Reduce side padding to `20px`, stack cards vertically, hide non-essential navigation
Tablet	768px–1023px	Increase padding to `24px–32px`, layout cards in 2-column grids where applicable
Desktop	1024px+	Full padding (`76px` sides), multi-column layouts, expanded card widths (1100px target)
Ultra-wide	1400px+	Maintain max-width of ~1200px for cards, center layout, increase side margins

Touch Targets

Minimum Touch Target: 44px × 44px (standard mobile accessibility)
Button Height: Maintain 52.1875px height for all interactive buttons on touch devices
Link Spacing: Ensure 16px minimum gap between clickable link elements
Input Height: Preserve 52.1875px minimum height for form inputs to allow comfortable thumb interaction

Collapsing Strategy

Navigation: Convert vertical sidebar navigation to hamburger menu at 768px breakpoint
Cards: From full-width to 2-column grid at 768px; revert to single-column below 480px
Padding: Reduce container padding from 37.6px to 20px below 768px to preserve screen real estate
Typography: Keep font sizes constant; use line-height adjustments to manage reading rhythm on narrower screens
Grid Layout: Switch from multi-column to single-column stack below 480px; maintain 24px gaps between sections
Hero/Landing: Reduce side padding from 76px to 24px below 768px; adjust section width constraints accordingly

9. Agent Prompt Guide

Quick Color Reference

Primary CTA / Link: Cyan Blue (#60A5FA)
Success State: Success (#2EA043) or Bright Success (#22C55E)
Warning State: Warning Yellow (#C8E64A)
Error State: Error Red (#EF4444)
Background: Deep Black (#09090B)
Card Border: Dark Gray (#27272A)
Primary Text: White (#FFFFFF)
Secondary Text / Ghost Button: Mid Gray (#A1A1AA)
Input Border: Zinc 700 (#3F3F46)
Button Fill: Light Gray (#E8E8E8)

Iteration Guide

All backgrounds are #09090B (near-black). Every surface, card, container, and section uses this as the foundation. No light backgrounds.
Every card and container has a 2px border in #27272A. Never omit this; it defines all structural boundaries. The border always pairs with the small shadow: rgb(39, 39, 42) 0px 0px 0px 2px, rgba(0, 0, 0, 0.05) 0px 1px 2px 0px.
Typography is 100% monospaced (JetBrains Mono primary, Arial for buttons only). No variable-width fonts. Every text element references the extracted font-family and font-size exactly.
Font sizes are precise and non-negotiable: Display 18.8px, Heading H2 16.45px, Heading H3 14.1px, Button 13.3333px, Caption 15.04px. Scale in this exact sequence; never interpolate.
All corner radii are 0px. No rounding anywhere. Pure right angles on buttons, inputs, cards, modals, badges—everything.
Padding uses the scale: 4px, 8px, 16px, 20px, 24px, 28px, 32px, 36px, 76px, 188px. For hybrid values like button padding (14.1px, 28.2px), use the extracted values exactly. Never round or substitute.
Semantic colors are strict: Links = #60A5FA, Success = #2EA043 or #22C55E, Warning = #C8E64A, Error = #EF4444. Use these only for their intended semantic purpose; never deviate.
Interactive text is #A1A1AA by default (secondary/ghost). Primary button text is dark (#09090B) on light button background (#E8E8E8). Links in body are #E8E8E8 until hover, then #60A5FA.
Inputs and form elements: background-color: transparent, border: 1px solid #3F3F46, color: #E8E8E8, padding: 14.1px 18.8px, height: 52.1875px. No rounding, no background fill.
Line-height defaults to normal (1.0) except body text (1.6), lists (1.8), and captions (1.8). Maintain readability in long-form content while preserving tight monospaced alignment elsewhere.
No letter-spacing, no font-weight variation beyond the scale (400 or 700 for H2 only). Hierarchy comes from size and color, not weight.
Hover states are minimal: Links underline or change color to #60A5FA. Buttons shift background brightness. Ghost buttons reveal the blue accent. Never apply dramatic transforms or heavy transitions.
For elevation, use only two shadow patterns: Small (cards) = rgb(39, 39, 42) 0px 0px 0px 2px, rgba(0, 0, 0, 0.05) 0px 1px 2px 0px; Medium (modals) = rgb(39, 39, 42) 0px 0px 0px 2px, rgba(0, 0, 0, 0.5) 0px 4px 24px 0px. Always pair with the 2px border.
Responsive breakpoints: Mobile 320–767px (reduce padding to 20px), Tablet 768–1023px (expand to 24–32px), Desktop 1024px+ (full 76px gutters). Below 480px, stack everything single-column.
Status colors are self-contained: Success badge = #2EA043 background, white text; Warning = #C8E64A with dark text; Error = #EF4444 with white text. Each is a complete mini-component; no mixing.

Want a DESIGN.md like this for your own website?