# Balsa · Design system migration spec

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

> This site is a great example of a clean, focused SaaS design that uses a minimal color palette and strong typography to convey professionalism and clarity.

## 1. Identity DNA

Balsa's design system is built like a focused workspace: every element serves a purpose, clearing away visual noise so product teams can concentrate on what matters. The identity is defined by a stark, high-contrast foundation where typography and structure do the communicative work, not decoration.

**One-liner:** A documentation and project tracking tool for building software.
**Keywords:** docs · workflow · roadmap · team · software
**Analogy:** A clean, focused workspace for aligning product teams on goals and tasks.

## 2. Color

The color system is fundamentally achromatic, relying on the polarity of pure black and pure white. A single, high-chroma yellow accent functions as a deliberate signal, drawing the eye to interactive cards and key callouts without polluting the neutral backdrop.

| Token | Value | Use |
|---|---|---|
| `--bg` | `#FFFFFF` | main background |
| `--bg-quiet` | `#F7F7F7` | quiet area |
| `--ink` | `#000000` | body text |
| `--muted` | `#939393` | placeholder |
| `--accent` | `#FFB700` | single accent |
| `--line` | `rgba(0,0,0,0.09)` | divider |

**Color principle:** High-contrast black and white with a single, high-chroma yellow accent for highlighting key UI cards and callouts.

The principle is restraint: use the full, vibrant power of one accent color only where functional emphasis is required.

## 3. Typography

Typographic voice is split between two categories: bold grotesques for authoritative, all-caps headlines and clean humanist sans-serifs for readable body text. The scale prioritizes clear hierarchy, with heavy weights and tight tracking on primary headlines.

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

| Token | Size | Line-height | Weight | Letter-spacing | Use |
|---|---|---|---|---|---|
| display | 48px | 1.0 | 700 | -1.5px | Main headline 'DOCS FOR BUILDING SOFTWARE' |
| heading | 24px | 1.2 | 700 | 0px | Sub-headlines and UI card titles |
| body | 16px | 1.5 | 400 | 0px | Main descriptive text |
| caption | 12px | 1.4 | 400 | 0px | UI elements, labels, and metadata |

**Type rules:**
- Use uppercase for UI labels and status indicators.
- Main headlines use heavy weights and tight letter-spacing.

## 4. Spacing

Rhythm is established on a strict 4px grid, creating predictable vertical and horizontal spacing. This mathematical consistency supports the system's clean, organized feel, especially in the generous whitespace of the hero area.

- **Base unit:** 4px
- **Scale:** 4 / 8 / 12 / 16 / 24 / 32 / 48 / 60 / 96 px
- **Rhythm:** Consistent 4px grid base with generous whitespace in the hero section.

## 5. Surfaces

Surfaces are treated with subtle, layered shadows that create a gentle sense of depth, lifting cards and key components off the flat, white canvas. Thin, low-opacity borders provide just enough separation between elements without creating harsh divisions.

- **Radius:** sm 6px · md 8px · lg 12px · pill 999px
- **Shadows:**
  - rgba(0,0,0,0.05) 0px 1px 0px 0px
  - rgba(0,0,0,0.15) 0px 0.7px 0.7px -0.625px, rgba(0,0,0,0.145) 0px 1.8px 1.8px -1.25px, rgba(0,0,0,0.05) 0px 30px 30px -3.75px
- **Borders:** Thin, low-opacity black borders (rgba(0,0,0,0.09)) for subtle separation.

## 6. Layout

The layout skeleton is a single, centered column for the marketing site, creating a focused narrative flow. This simplicity contrasts with the complex multi-column grids used within the product UI screenshots, showcasing the tool's actual capability.

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

**Skeleton:** Single-column centered layout for the marketing site, with a complex multi-column grid for the product UI screenshots.

## 7. Motion & Interaction

Motion is understated and functional, used to reinforce interactivity rather than to ornament. CSS transitions provide smooth feedback on hover and focus states, maintaining a professional and predictable feel throughout the interface.

- **Durations:** micro 220ms · small 400ms · medium 800ms
- **Easing:** `cubic-bezier(0.4, 0, 0.2, 1)`
- **Patterns:**
  - Smooth transitions on hover and focus states.

- **Hover:** Subtle color changes or shadow shifts on interactive elements.
- **Click:** Immediate visual feedback via state changes.
- **Transition:** Consistent use of CSS transitions for UI state changes.
- **Keyboard:** Standard focus ring visibility for accessibility.

## 8. Voice & Don'ts

The editorial voice is direct and professional, mirroring the system's visual clarity. Headlines are bold, high-contrast, and action-oriented, while supporting text avoids casual language or unnecessary complexity.

- **Tone:** Direct, professional, and focused on team efficiency.
- **Headline style:** All-caps, bold, and high-contrast.
- **CTA style:** Clear, action-oriented, and often contained in pill-shaped buttons.
- **Avoid:** Casual language / Complex jargon / Overly dense text blocks

### Don'ts
- ❌ Don't use a busy background — screenshot shows a clean, solid white (#FFFFFF) background.
- ❌ Don't use a low-contrast accent color — screenshot shows a high-chroma yellow (#FFB700) for emphasis.
- ❌ Don't use a light or grey primary text color — screenshot shows pure black (#000000) for main headlines.
- ❌ Don't use sharp, square corners — screenshot shows rounded corners (12px) on primary cards and containers.
- ❌ Don't use a dark mode interface — screenshot shows a predominantly white/light theme.
- ❌ Don't use decorative, script, or overly stylized fonts — screenshot shows clean, functional sans-serif and monospace categories.

The system deliberately avoids dark mode, decorative typography, and busy backgrounds to preserve its core tenet of uncluttered focus.

## System Prompt (paste into AI tool)

```
This is a clean, professional SaaS landing page for a project documentation tool. It features a stark black-and-white palette with a single, high-chroma yellow (#FFB700) accent used for highlighting feature cards. The typography uses bold, grotesque-sans categories for headlines and humanist-sans for body text. Critical constraints: maintain high contrast, avoid dark mode, use solid white backgrounds, and keep UI elements rounded. The layout is centered and spacious, focusing on product screenshots.
```