# Mapbox · Design system migration spec

> Source: https://mapbox.com  ·  Curated by OpenDesign  ·  en

> Mapbox provides a definitive example of a high-end developer tool aesthetic, balancing technical power with visual restraint.

## 1. Identity DNA

Mapbox's identity is that of a precise instrument—a dark, calibrated environment where complex geospatial data becomes legible through deliberate restraint. Like a well-designed cartographer's table, the system prioritizes clarity and function, providing a stable foundation for developers to build layers of intelligence upon.

**One-liner:** The location platform of choice for developers, automakers, and innovators.
**Keywords:** geospatial · mapping · location · platform · navigation
**Analogy:** A powerful toolkit for builders who want to overlay intelligence on the physical world.

## 2. Color

The color system is a high-contrast dark mode built to make data visualization the primary spectacle. A deep charcoal background recedes, allowing the single, vibrant blue accent to act as a clear signal for interaction and key information.

| Token | Value | Use |
|---|---|---|
| `--bg` | `#0E1012` | main background |
| `--bg-soft` | `#15171B` | card background |
| `--ink` | `#FFFFFF` | body text |
| `--ink-soft` | `#A0AABA` | secondary text |
| `--muted` | `#333943` | placeholder |
| `--muted-soft` | `#566171` | weak hint |
| `--accent` | `#007AFC` | single accent |
| `--line` | `rgba(51, 57, 67, 1)` | divider |

**Color principle:** High-contrast dark mode designed to make colorful map data and blue accents stand out.

The principle is one of visual hierarchy through contrast, where a restrained palette creates a stage for dynamic content.

## 3. Typography

Typography is split between two complementary voices: a geometric sans-serif for authoritative headlines and a humanist sans-serif for approachable body text. This pairing balances technical precision with the clarity needed for documentation and interface copy.

- **Display:** geometric-sans
- **Body:** humanist-sans
- **Mono:** monospace

| Token | Size | Line-height | Weight | Letter-spacing | Use |
|---|---|---|---|---|---|
| display | 64px | 1.0 | 500 | -1px | Hero headline |
| body | 20px | 1.4 | 400 | 0px | Introductory text |

**Type rules:**
- Primary headlines use a geometric sans-serif.
- Body text relies on a legible humanist sans-serif.
- UI elements use standard sans-serif fallbacks.

## 4. Spacing

A standard 4px grid establishes a consistent, predictable rhythm throughout the interface, creating order in a system designed for complex information.

- **Base unit:** 4px
- **Scale:** 4 / 8 / 16 / 24 / 32 / 48 / 64 / 96 px
- **Rhythm:** Standard 4px grid base.

## 5. Surfaces

Depth is communicated through expansive, soft shadows and subtle, muted borders rather than elevation changes. This approach defines panels and cards without competing with the content they contain.

- **Radius:** sm 4px · md 8px · lg 24px · pill 100px
- **Shadows:**
  - 0px 0px 100px 50px rgb(14, 16, 18)
- **Borders:** Subtle 1px borders using muted dark gray (#333943) to define elements without harshness.

## 6. Layout

The layout is centered and spacious, a content-heavy structure typical of a SaaS platform. It is engineered to showcase technical documentation and large map previews without visual competition.

- **Container max:** 1280px
- **Paragraph max:** 680px
- **Grid:** 12 columns, gutter 24px
- **Breakpoints:** 768 / 1024 px

**Skeleton:** Centered, content-heavy layout typical of a SaaS platform.

## 7. Motion & Interaction

Motion is precise and understated, using smooth cubic-bezier transitions to signal state changes. The philosophy is to provide clear feedback without distraction, reinforcing the tool's professional and high-end feel.

- **Durations:** micro 150ms · small 400ms · medium 800ms
- **Easing:** `cubic-bezier(0.19, 1, 0.22, 1)`
- **Patterns:**
  - Smooth hover transitions on navigation and buttons.

- **Hover:** Subtle color shifts and opacity changes.
- **Click:** Immediate response with slight transform.
- **Transition:** Smooth color and box-shadow transitions over 0.4s.
- **Keyboard:** Standard focus outlines on interactive elements.

## 8. Voice & Don'ts

Voice is professional, technical, and authoritative, matching the platform's utility. Copy is concise and action-oriented, avoiding dense text and unexplained jargon in favor of clear, benefit-driven messaging.

- **Tone:** Professional, technical, and authoritative.
- **Headline style:** Concise, action-oriented, and bold.
- **CTA style:** Clear, benefit-driven, and inviting.
- **Avoid:** Jargon without context / Overly casual language / Hype without substance / Dense blocks of text in the hero

### Don'ts
- ❌ Don't use light backgrounds — screenshot shows a dark-themed interface.
- ❌ Don't use decorative serif fonts — screenshot shows clean sans-serif typography.
- ❌ Don't use sharp, square corners on buttons — screenshot shows pill-shaped buttons.
- ❌ Don't use neon or overly saturated colors — screenshot shows a focused blue accent.
- ❌ Don't use thin, delicate lines for borders — screenshot shows clear 1px borders.
- ❌ Don't overcrowd the hero section — screenshot shows generous whitespace and large type.

The system deliberately omits decorative serifs, light backgrounds, and neon colors to maintain its focused, builder-oriented aesthetic.

## System Prompt (paste into AI tool)

```
Mapbox is a premium SaaS developer platform for mapping and location intelligence. It uses a deep dark background (#0E1012) with crisp white text and a vibrant blue accent (#007AFC). Typography is primarily geometric and humanist sans-serif, with large, bold headlines and clear body text. The layout is spacious and centered. Critical don'ts: avoid light themes, serif fonts, square buttons, neon colors, thin borders, and cluttered hero sections.
```