# Medusajs Design System

> A high-density, developer-focused monochrome interface built on sharp borders, subtle gray scales, and tightly tracked Inter typography.

**Source:** https://medusajs.com | **Captured:** 2026-06-06 | **Pages analyzed:** 3
**Brand layer:** parent | **Related brands:** None

## TL;DR
Medusajs uses a strict monochrome palette anchored by `#ffffff` backgrounds and `#18181b` primary text and surfaces. The system relies heavily on subtle gray borders (`#e6e8eb`) and backgrounds (`#f3f4f6`) to delineate structure rather than elevation or color. Typography is exclusively Inter, utilizing tight negative letter-spacing (-1.638px at 64px) for display headings to create a technical, precise feel. Components favor sharp edges (0px radius is dominant) with occasional 6px or 8px softening for interactive controls and cards.

## Signature DNA
1. **Strict Monochrome Palette** (Relies on `#18181b` and `#ffffff` with gray scales like `#e6e8eb` for hierarchy. Saturated colors are reserved strictly for decorative tags, observed across all pages.)
2. **High-Density Technical Typography** (Inter at 500 weight for headings with aggressive negative tracking, such as -1.638px at 64px, creates a compact, engineered aesthetic.)
3. **Sharp Dominant Geometry** (With 917 occurrences of 0px border radius, the system leans heavily into sharp, grid-like layouts, reserving 6px and 8px radii only for specific inputs and cards.)

## Colors
### Foundation
| Token | Hex | Role | Occurrences | Confidence | Source |
|---|---|---|---|---|---|
| `--bg-base` | `#ffffff` | surface_bg, text, button_bg, border | 214 | 1.0 | computed_style, css_variable |
| `--fg-base` | `#18181b` | text, surface_bg, border | 179 | 1.0 | computed_style, css_variable |
| `--border-base` | `#e6e8eb` | border | 135 | 1.0 | computed_style, css_variable |
| `--fg-subtle` | `#52525b` | text, button_text | 72 | 1.0 | computed_style, css_variable |
| `--fg-muted` | `#71717a` | text, button_text | 44 | 1.0 | computed_style, css_variable |
| `--contrast-bg-base-hover` | `#27272a` | surface_bg | 6 | 1.0 | computed_style, css_variable |
| `--bg-subtle-hover` | `#f3f4f6` | border, surface_bg | 5 | 1.0 | computed_style, css_variable |
| `text-ui-fg-base` | `#313131` | text, button_text | 679 | 0.8 | computed_style |

### Accent
| Token | Hex | Role | Occurrences | Confidence | Source |
|---|---|---|---|---|---|
| `--tag-orange-text` | `#9a3412` | text | 1 | 1.0 | computed_style, css_variable (decorative_only) |

### Semantic
Not captured in rendered source colors (declared tokens exist but lack rendered evidence).

## Typography
### Fonts
| Family | Weights observed | Role | Open-source substitute | License |
|---|---|---|---|---|
| Inter | 400, 500, 600 | heading, body, display | Inter | OFL |

### Scale
| Token | Size | Line height | Letter spacing | Weight | Use | Evidence selector |
|---|---|---|---|---|---|---|
| `display-lg` | 64px | 73.6px | -1.638px | 500 | Hero headings | `h1.text-headers-h1.text-left` |
| `display-md` | 40px | 46px | -0.64px | 500 | Section headings | `h2.max-w-[360px].text-ui-fg-base` |
| `heading-sm` | 24px | 30px | -0.23px | 500 | Card titles | `p` |
| `heading-xs` | 24px | 32px | normal | 500 | Sub-section headings | `h4` |
| `body-lg` | 18px | 27px | normal | 500 | Lead paragraphs | `p.text-xlarge-plus.text-ui-fg-subtle` |
| `body-md-strong` | 16px | 24px | normal | 500 | Standard body emphasis | `p.text-[16px].font-medium` |
| `body-md` | 16px | 25.6px | normal | 400 | Standard body | `p` |
| `body-sm` | 14px | 21px | normal | 400 | Secondary text | `section.grow.relative` |
| `body-xs` | 13px | 20px | normal | 500 | Small links | `a.transition-fg.relative` |
| `caption-strong` | 12px | 20px | normal | 600 | Badges | `span.rounded-full.h-[18px]` |

### Principles
- **Negative tracking on display:** Headings at 64px use -1.638px letter spacing to create a dense, engineered look.
- **Medium weight dominance:** Headings and emphasized body text rely on weight 500 rather than bold (700).
- **Strict sans-serif:** Inter is used universally across all text roles.

## Spacing
**Base unit:** 8
| Token | Value | Occurrences |
|---|---|---|
| `spacing-1` | 1px | 4 |
| `spacing-4` | 4px | 8 |
| `spacing-6` | 6px | 40 |
| `spacing-8` | 8px | 4 |
| `spacing-12` | 12px | 17 |
| `spacing-16` | 16px | 42 |
| `spacing-24` | 24px | 5 |
| `spacing-32` | 32px | 8 |
| `spacing-48` | 48px | 3 |
| `spacing-64` | 64px | 4 |

## Border radius
| Token | Value | Use | Evidence |
|---|---|---|---|
| `radius-sharp` | 0px | Structural containers, primary buttons | 917 occurrences |
| `radius-input` | 6px | Cards, inputs | 20 occurrences |
| `radius-control` | 8px | Rounded buttons, specific cards | 24 occurrences |
| `radius-pill` | 9999px | Badges, tags | 17 occurrences |

## Elevation
| Level | Value | Use | Evidence |
|---|---|---|---|
| `shadow-subtle` | `rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0.12) 0px 1px 2px 0px, rgba(0, 0, 0, 0.08) 0px 0px 0px 1px` | Standard cards | 8 occurrences |
| `shadow-dark-inset` | `rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(255, 255, 255, 0.2) 0px 0.75px 0px 0px inset, rgba(0, 0, 0, 0.4) 0px 1px 2px 0px, rgb(24, 24, 27) 0px 0px 0px 1px` | Dark mode cards | 6 occurrences |
| `shadow-hover` | `rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0.08) 0px 0px 0px 1px, rgba(0, 0, 0, 0.08) 0px 1px 2px -1px, rgba(0, 0, 0, 0.04) 0px 2px 4px 0px` | Interactive elements | 2 occurrences |

## Components
### Tier 1: Foundational
#### Surface Sharp
**Role:** Primary structural container for layout regions.
**Pages observed:** https://medusajs.com, https://medusajs.com/pricing, https://medusajs.com/about
**Spec:** Background `#ffffff` / Text `#313131` / Border `#e6e8eb` / Radius 0px / Padding 0px / Typography 14px / Shadow none
**States observed:** Default | Disabled: not captured

#### Button Sharp
**Role:** Standard call-to-action within structural blocks.
**Pages observed:** https://medusajs.com
**Spec:** Background `#ffffff` / Text `#313131` / Border `#e6e8eb` / Radius 0px / Padding 24px 32px / Typography 14px / Shadow none
**States observed:** Default | Disabled: not captured

### Tier 2: Patterns
#### Card Light
**Role:** Feature and pricing tier containers.
**Pages observed:** https://medusajs.com, https://medusajs.com/pricing
**Spec:** Background `#ffffff` / Text `#18181b` / Border `#e6e8eb` / Radius 6px / Padding 6px 12px / Typography 13px / Shadow `rgba(0, 0, 0, 0.12) 0px 1px 2px 0px, rgba(0, 0, 0, 0.08) 0px 0px 0px 1px`
**States observed:** Default | Disabled: not captured

#### Card Dark
**Role:** High-contrast feature highlights.
**Pages observed:** https://medusajs.com, https://medusajs.com/pricing, https://medusajs.com/about
**Spec:** Background `#27272a` / Text `rgba(255, 255, 255, 0.88)` / Border `#e6e8eb` / Radius 6px / Padding 6px 12px / Typography 13px / Shadow `rgba(255, 255, 255, 0.2) 0px 0.75px 0px 0px inset, rgba(0, 0, 0, 0.4) 0px 1px 2px 0px, rgb(24, 24, 27) 0px 0px 0px 1px`
**States observed:** Default | Disabled: not captured

### Tier 3: Surface-specific
#### Rounded Button
**Role:** Secondary actions and toggles.
**Pages observed:** https://medusajs.com
**Spec:** Background `#ffffff` / Text `#313131` / Border `#e6e8eb` / Radius 8px / Padding 0px / Typography 14px / Shadow `rgba(0, 0, 0, 0.12) 0px 1px 2px 0px, rgba(0, 0, 0, 0.08) 0px 0px 0px 1px`
**States observed:** Default | Disabled: not captured

#### Transparent Surface
**Role:** Invisible hit areas or layout wrappers.
**Pages observed:** https://medusajs.com, https://medusajs.com/pricing
**Spec:** Background `rgba(0, 0, 0, 0)` / Text `#18181b` / Border `#e6e8eb` / Radius 4px / Padding 0px / Typography 13px / Shadow none
**States observed:** Default | Disabled: not captured

## Layout
| Property | Value |
|---|---|
| Max-width | ~1200px (observed in screenshots) |
| Grid | Multi-column feature grids (2-up, 3-up, 4-up) |

## Responsive
| Breakpoint | Width | Key changes |
|---|---|---|
| Mobile | 390px | Feature grids collapse to single column; navigation moves to hamburger menu. |

## Imagery & decoration
The brand relies on high-fidelity UI mockups and code snippets to communicate value. Decorative elements are restricted to soft gradient meshes in specific hero backgrounds. It avoids lifestyle photography or illustrative vectors entirely.

## Do's
- Do use Inter at weight 500 for all headings to maintain a technical feel.
- Do apply tight negative letter-spacing (-1.638px) to display text (64px).
- Do use 0px border radius for primary layout structures and containers.
- Do rely on `#e6e8eb` for borders to create subtle separation between monochrome areas.
- Do use `#18181b` for primary text to ensure high contrast against `#ffffff` backgrounds.

## Don'ts
- **Wrong:** Using `#3b82f6` (blue) as the primary brand color.
  **Right:** Using `#18181b` as the primary brand color.
  **Reason:** Medusajs is a monochrome parent brand; saturated colors like blue or orange are reserved for interactive states or sub-brand tags, not the parent identity.
- **Wrong:** Applying 16px border radius to structural cards.
  **Right:** Using 0px or 6px border radius.
  **Reason:** The brand geometry is intentionally sharp and technical.
- **Wrong:** Using a serif typeface for editorial warmth.
  **Right:** Using Inter exclusively.
  **Reason:** The brand identity relies on the engineered, neutral aesthetic of a modern sans-serif.

## Similar brands
- Vercel
- Stripe (Developer documentation)
- Linear

## Quick start
```css
:root {
  --bg-base: #ffffff;
  --fg-base: #18181b;
  --border-base: #e6e8eb;
  --fg-subtle: #52525b;
  --fg-muted: #71717a;
  --contrast-bg-base-hover: #27272a;
  --bg-subtle-hover: #f3f4f6;
  
  --font-inter: 'Inter', sans-serif;
  
  --radius-sharp: 0px;
  --radius-input: 6px;
  --radius-control: 8px;
  
  --shadow-subtle: rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0) 0px 0px 0px 0px, rgba(0, 0, 0, 0.12) 0px 1px 2px 0px, rgba(0, 0, 0, 0.08) 0px 0px 0px 1px;
}
```

## Agent prompt examples
- "Create a pricing card using a `#ffffff` background, a 6px border radius, and a subtle shadow (`rgba(0, 0, 0, 0.12) 0px 1px 2px 0px`). Use Inter 500 at 24px for the tier name."
- "Build a dark mode feature highlight section using `#27272a` as the background, an inset shadow for depth, and `rgba(255, 255, 255, 0.88)` for the text."
- "Generate a hero heading using Inter at 64px, weight 500, with -1.638px letter spacing and `#18181b` text color."

## Known gaps
Hover and focus states for interactive components were not fully captured in the rendered evidence, though CSS variables suggest their existence. Semantic colors (success, error) are declared in tokens but lack rendered occurrences in the analyzed pages.

## Provenance
| Page sampled | URL | Viewport | Capture time |
|---|---|---|---|
| Homepage | https://medusajs.com | Desktop 1440px, Mobile 390px | 2026-06-06T05:00:51.298Z |
| Pricing | https://medusajs.com/pricing | Desktop 1440px | 2026-06-06T05:00:51.298Z |
| About | https://medusajs.com/about | Desktop 1440px | 2026-06-06T05:00:51.298Z |