# Berlin Bytes — Design System

**Version 1.0 · May 2026**

A full reference of tokens, components and rules for the Berlin Bytes brand. Pair this with `css/berlin-bytes.css` (full stylesheet) / `dist/tokens.css` (tokens only — generated from `tokens/tokens.json`), the cards in `/examples/` (the visual specimens) and the components in `/ui/react/` (the React building blocks).

---

## Document scope and ownership

Use this file as the **canonical long-form human reference** for the Berlin Bytes
design system.

- Start with `brand/BRAND.md` when you need a fast portable brief.
- Use this file for the full visual and component rules.
- Use `brand/DESIGN.md` when tooling expects machine-readable DESIGN.md format.

Governance:
- Narrative/system guidance lives in `brand/BRAND.md` + this file.
- Token values live in `tokens/tokens.json` and generated artifacts.
- `brand/DESIGN.md` is generated and should not be hand-edited.

---

## 1 · Brand pillars

| Pillar | What it means |
|---|---|
| **Sharpness & clarity** | Geometric typography (Space Grotesk) and a fixed two-corner radius signal forward thinking. |
| **Depth & focus** | Soft, grainy radial "spotlights" bring ideas into focus literally — bokeh as metaphor. |
| **Vibrant trust** | Mustard-on-ink screams clarity. The spark of innovation cutting through. |
| **Our unique touch** | **Bearnie** — the friendly grape bear with a mustard cursor. The human, approachable face. |

---

## 2 · Color

The palette is **four families × six steps**. Anything outside this list is off-brand.

### 2.1 The brand step

| Family | Brand step | Hex | Use |
|---|:---:|:---:|---|
| Honey Mustard *(main)* | **400** | `#FBCB12` | Primary spark, brand accent |
| Grape *(main)* | **400** | `#B8256A` | Secondary, Bearnie body, accents on dark |
| Sapphire *(secondary)* | **400** | `#1E1655` | Deep night surface |
| Elephant *(secondary)* | **400** | `#1A3B40` | Muted teal-charcoal |

### 2.2 Full ramps

```
Honey Mustard
  100  #FFF2CC    200  #FFE599    300  #FFD963
  400  #FBCB12 ★  500  #E4A814    600  #C9861E

Grape
  100  #E3A8C3    200  #D47CA6    300  #C65188
  400  #B8256A ★  500  #8A1C50    600  #5C1335

Sapphire
  100  #8C83C4    200  #6155B8    300  #372B91
  400  #1E1655 ★  500  #1C1A3B    600  #181729

Elephant
  100  #4E98AC    200  #3A798A    300  #265A68
  400  #1A3B40 ★  500  #012429    600  #001519
```

### 2.3 Neutrals

| Token | Hex | Purpose |
|---|:---:|---|
| White | `#FFFFFF` | Inset surfaces, button text on dark |
| Cream | `#F6F5F2` | **Workhorse off-white** — almost every leaf card sits on cream |
| Grey 100 → 700 | `#F7F8F7` → `#767676` | Borders, rules, secondary text |
| Charcoal | `#3C3C3C` | Tertiary text |
| Ink | `#1A1A1A` | Body text, headlines |
| Black | `#000000` | Wordmark only |

### 2.4 Usage rules

✓ Default to **two colors per surface**. Mustard on cream/white, or mustard on indigo/sapphire.
✓ Use tints and shades from the official ramp for hover/press states.
✗ Never invent colors. No off-ramp tints.
✗ Never use mustard for body text or icons — its contrast on white fails accessibility.

**Dark surfaces.** The dark backgrounds in use are: **Black `#000000`** (e.g. the website
homepage), **Sapphire/indigo `#1E1655`**, and the **deep grape (dark red) `#5C1335`–`#882654`**
family. Ink `#1A1A1A` is primarily a text color but may also serve as a near-black surface.
On any dark surface, keep the two-colors-max rule (typically mustard as the single accent).

---

## 3 · Typography

### 3.1 Three faces

| Face | Role | Weights | Use for |
|---|---|---|---|
| **Space Grotesk** | Headline | Regular, SemiBold | Headlines, titles, **short** impactful statements only |
| **Inter** | Body / UI | Regular, Medium, Bold | Body text, captions, buttons, all general content |
| **Space Mono** | Numeric / data | Bold | Large metrics, labels, code snippets — **rarely** |

### 3.2 Type rules

✓ **Maintain hierarchy**: Space Grotesk for headlines, Inter for paragraphs, Space Mono for metrics.
✓ **Sentence case** for everything — display, headlines, body.
✗ **No uppercase.** Anywhere. Ever.
✗ **No Space Grotesk for body copy** — readability drops in long text.
✗ **No unapproved fonts, no font effects, no stretching, no distortion.**

### 3.3 Scale (1080 canvas — scale proportionally for product UI)

```
Display     Space Grotesk Regular     96 / 72 / 56
H1          Space Grotesk SemiBold    48
H2 / H3     Space Grotesk Regular     36 / 30

Lead        Inter Regular             22
Body LG     Inter Regular             18
Body        Inter Regular             16
Caption     Inter Regular             13

Metric      Space Mono Bold           60
Label       Space Mono Bold           13
```

---

## 4 · Radii — the leaf system

### 4.1 Position rule

Berlin Bytes' signature: **top-left + bottom-right** are rounded. **Top-right + bottom-left** are always `0`. This creates the leaf silhouette.

```
  ┌─────┐ ┐         ╭─────┐
  │     │ │   not   │     │
  └ ────┘ ┘         └─────╯
```

### 4.2 Three sizes

| Token | Size | Use |
|---|:---:|---|
| `--radius-leaf-sm` | **4 px** | Chips, pills, internal slots |
| `--radius-leaf-md` | **24 px** | Cards, image frames *(default)* |
| `--radius-leaf-lg` | **80 px** | Hero blocks, full-bleed sections |

### 4.3 Section override

Full-width web sections (e.g. the dark advantages block) round **all four corners at 80px**:
```css
--radius-section: 80px;
```

Pills + capsules use `999px`.

---

## 5 · Backgrounds — the spotlight blur

The brand's most distinctive treatment. A grainy radial that docks to a canvas edge, suggesting a distant spotlight or bokeh.

### 5.1 Two gradient flavors

| Surface | Gradient | Stops |
|---|---|---|
| **Light** (white / cream) | Honey Mustard | `#FFEB9E → #FBCB12` |
| **Dark** (sapphire / grape) | Grape | `#FF406F → #882654` |

### 5.2 Specs

| Spec | Value | Notes |
|---|---|---|
| Coverage | **20–40 %** | Of the canvas area |
| Docking | **≥ 1 edge** | Must touch at least one side of the canvas |
| Gradient angle | **90°** | Always — the linear stop angle |
| Shape angle | **steps of 30°** | -60, -30, 0, 60, 90, 120, 150 — pick what reads best |
| Shape | **oval** | Proportions of `assets/Blur_mustard.png` (~5:3) — use the file as-is, never stretch it into a circle; most of it bleeds off-canvas |
| Grain texture | **size 1.7 · radius 100** | Required — never use the gradient raw |

### 5.3 The 5-layer system

Designs simulate a 3-dimensional perspective:

1. **BG color** — base surface (white, cream, sapphire, grape)
2. **Blur shape** — this card. Docks an edge.
3. **Content** — copy, body imagery, buttons
4. **Shapes & illustrations** — brand sparks, Bearnie. **Never** in background.
5. **Navigation** — sticky chrome, topmost

### 5.4 Rules

✓ Use blur shapes for **prominent** pages, slides, sections — title slides, hero sections.
✓ Use brand shapes to highlight text-heavy areas — but don't overdo it.
✗ Don't put multiple shapes in one area — one focal blur per surface.
✗ Don't place brand shapes (sparks, Bearnie) in the background layer.

---

## 6 · Image masks

There is **only one image mask** — the leaf shape. Same TL+BR rounded geometry as the radius system.

### 6.1 The General image

- **Rounded**: top-left, bottom-right
- **Square (0)**: top-right, bottom-left
- **Radius**: 24px (default) or 80px (hero)

### 6.2 Team set cards (canonical usage)

The leaf mask is the foundation of team setcards: portrait crop → name (Space Grotesk Medium 24) → role (Inter 13, pipe-separated) → "Background" label + description (Inter 13).

### 6.3 Rules

✓ Apply the leaf shape to every photo — products, team, case studies, hero.
✓ If a background shape sits behind the image, use **the same shape every time**. Never vary.
✗ **No circles.** Not even for avatars.
✗ No other mask shapes — no curves, no diagonal cuts, no organic blobs.

---

## 7 · Components

### 7.1 Buttons

All buttons are full **pill** (`border-radius: 999px`). Three variants:

| Variant | Background | Text | Use |
|---|---|---|---|
| **Primary** | Mustard `#FBCB12` | Ink | CTAs, primary actions |
| **Ghost** | Transparent + 1.5px ink border | Ink | Secondary actions; hover fills ink |
| **Dark** | Ink `#1A1A1A` | White | Tertiary actions, dark surfaces |

Padding: `14px 22px`. Font: Inter Medium 15. Arrow glyph `→` for forward motion.

### 7.2 Pills & chips

Solid **fills only** — no outlines, ever. Four flavors:

- **White** on cream surfaces
- **Cream** on white surfaces
- **Brand** (mustard, grape, sapphire) for "Featured / New / Beta" status
- **Dark** (ink) on light surfaces; with a mustard dot for "Live" status

Font: Inter Regular 14, `letter-spacing: +0.02em`.

### 7.3 Stat cards

**Canonical default (use this unless there's a reason not to):** a cream leaf card with a
large grape numeral.

| Element | Style |
|---|---|
| Container | Cream surface, 24px leaf radius, generous padding |
| Metric | **Space Mono Bold** (grape-500), `-0.02em` tracking — big (42px UI → 96px+ on slides) |
| Label | Inter Medium, grape-400. Sits **top-left** (stacked above the number) or **inline** to the right of the number |
| Accent | A mustard brand **star/symbol** (sun, 8-star, isotoxal…) in the **top-right** corner |

The numeral signature: `+100`, `+50`, `95%`, `400+`, `4.97/5` — `+` for "more than".

#### Variants (observed in production — colors are used more freely than the strict 2-color rule)

| Surface | Card | Numeral | Label | Accent |
|---|---|---|---|---|
| **Cream (default)** | Cream leaf card *or* no chrome flat on cream | Grape | Grape (or charcoal inline) | Mustard star, top-right |
| **Dark — indigo cards** | Lighter sapphire/indigo leaf card on darker indigo | Cream / mustard-light | White | Mustard star, top-right |
| **Dark — no chrome** | Flat on indigo, separated by thin 1px divider rules | Mustard | Grey-300 | Optional |

> Practical note: on the live site, stat blocks bend the "two colors per surface" rule for
> emphasis. That's allowed for hero stat moments — but the **cream card + grape numeral**
> default is what to reach for first, especially for new/templated work.

### 7.4 Leaf content cards

Default to **plain leaf cards** (cream fill, no blur). Reach for blur-shape variants **consciously** — one per row, only to highlight a featured item.

| Variant | When to use |
|---|---|
| **Plain** | Default for any content block |
| **No-chrome block** | Painpoints, feature lists — set on a cream surface, no card chrome |
| **Blur-shape** | Featured items, single hero card in a row |
| **Image card** | Case studies, work highlights — image + caption + status chip |

**Text alignment in cards**: always **left-aligned**. Never right or centered.

### 7.5 Brand symbols

14 hand-drawn mustard glyphs (sun, 8-star, 12-star, isotoxal, 4-circles, quote, play, equal, curve, brush, sun-heavy, 8-star-thin, plus invertibles).

✓ Use at large sizes (60–240 px). They read as confident graphic accents.
✗ Never as small UI icons — at small size they read as blobs.

For UI affordances (nav, settings, controls), use the brand UI icon set: **Material Symbols / Material Icons** (Google). See the BB Brand Styleguide in Figma for the canonical set. CDN: `https://fonts.google.com/icons` (Material Symbols). The hand-drawn brand symbols above are **not** UI icons — never mix the two roles.

---

## 8 · Bearnie — the mascot

A friendly grape bear holding a mustard cursor speech bubble. The human, approachable face of the brand.

### 8.1 Six emotional variations

| Variation | Vibe |
|---|---|
| **Default** | Neutral, watchful |
| **Laughing** | Joy, celebration |
| **Winking** | Playful, in-the-know |
| **Determined** | Focus, commitment |
| **Worried** | Concern, caution |
| **Cyber** | Tech, futuristic |

### 8.2 Rules

**Bearnie is for internal & team-facing contexts only.** Use Bearnie when the subject is
the Berlin Bytes team or internally-directed communication — internal slides and
presentations, team/culture/office moments, and internal assets (merch, hoodies, standees,
wayfinding/signage, etc.).

✓ Use for team, office, culture, and internal communications.
✓ Place in the **bleed** — peeking from the top-right or bottom edge of the canvas.
✗ **Never in external communication or marketing.** Bearnie does not appear on the website, in customer-facing campaigns, sales material, or ads.
✗ **Don't combine Bearnie with the Berlin Bytes wordmark** in the same composition. Bearnie *is* the brand mark in those contexts.

---

## 9 · Logo

The wordmark is custom: **"Berlin"** in ink, **"Bytes"** in mustard (the two B's and the *y* are mustard; the other letters are ink/black).

- Primary: `assets/logo-berlinbytes.svg`
- Inverse (dark surfaces): `assets/logo-berlinbytes-inverse.svg`
- Sizes: ~200×40 px (web), ~245×45 px (slide)
- Placement (default): **top-left** (website, Word docs, templates, entry slides)
- Placement (exception): **bottom-left** on follow-up slides (non-opener slides)
- Placement (exception): **bottom-right** on all social media visuals (e.g. LinkedIn post creatives) — the post is shared by Berlin Bytes or a team member, so the platform already shows the brand top-left

There is **no B-symbol mark** — the wordmark *is* the logo. Don't invent one.
The logo is always used directly on the surface, **without** a separate background container/box.

---

## 10 · Voice

**Two registers, kept strictly apart.** See `voice-and-tone.md` for the full guide.

- **External** (marketing, sales, website, customers): **German, formal "Sie"**, professional, confident, precise. Orient on berlin-bytes.de ("Launchen Sie ein Produkt, das Ihr Unternehmen voranbringt." · "Vorausschauend, präzise, transformativ."). No Bearnie, no emoji, no cheek.
- **Internal** (team, culture, internal assets): **always English**, warm and free to be cheeky, funny, even ironic ("Talking straight without layers, decisions happen fast.").

Both registers: short sentences, direct verbs, no buzzwords. **Never** third-person corporate.

**Pronouns**: external German uses formal "Sie / Ihr"; internal English uses "we" / "you".

**Language policy**: website default and all customer/sales communication → **German**; internal communication → **always English**.

**Casing**:
- Display headlines → sentence case
- UI labels & pills → Title Case
- All other copy → sentence case
- **Never ALL CAPS** (the eyebrow label is the one exception)

**Numerics**: big bold Space Mono numerals — `+100`, `+50`, `95%`, `400%`. `+` prefix for "more than".

**Emoji**: used **sparingly**, only in internal/Slack-y comms. Never in external/marketing surfaces.

---

## 11 · Animation

The brand language is calm and confident.

- **Easing**: `cubic-bezier(0.22, 1, 0.36, 1)` (ease-out-quart)
- **Duration**: 200–400ms for UI; up to 600–800ms for hero reveals
- **Effects**: opacity + small `translateY(8–16px)` on entry
- **No bouncy springs, no parallax, no scroll-jacking**

---

## 12 · Shadows & strokes

Used **sparingly** — the system relies on color and shape for separation.

```
--shadow-sm: 1px 1px 4px 0 rgba(0,0,0,0.10)   // tooltips, floating UI
--shadow-md: 0 4px 16px 0 rgba(0,0,0,0.08)    // modals, popovers
```

Strokes: 1–2 px solid in `#C1C1C1`, `#D7D7D7`, or ink `#1A1A1A`. Never coloured strokes.

---

## 13 · Spacing

8-based scale. Use generously — the brand breathes.

```
4 · 8 · 16 · 24 · 32 · 40 · 64 · 80 · 104 · 128
```

Slide layouts use 80px margins and 64px gutters by default.

---

## 14 · Quick checklist (before shipping any artwork)

- [ ] Two colors max per surface, both from the official ramp
- [ ] Headlines = Space Grotesk; body = Inter; numerics = Space Mono
- [ ] No uppercase, no font effects, no third typeface
- [ ] Leaf radius: TL + BR rounded; TR + BL = 0
- [ ] All text left-aligned
- [ ] Photos use the leaf mask, **no circles**
- [ ] Blur shape (if present) docks an edge, covers 20–40 %, has grain
- [ ] One focal blur per surface — never multiple
- [ ] Bearnie not paired with the wordmark
- [ ] Logo placement follows rule: default top-left, follow-up slides bottom-left, social media always bottom-right, and never in a separate background box

---

## 15 · File index

| Path | Purpose |
|---|---|
| `tokens/tokens.json` | Single source of truth — design tokens (W3C DTCG) |
| `dist/tokens.css` | Generated CSS custom properties — import for tokens only |
| `css/berlin-bytes.css` | Full stylesheet — fonts + tokens + `.bb-*` helpers |
| `dist/tokens.ts` · `dist/tailwind.preset.js` | Generated TS map + Tailwind preset |
| `brand/BRAND.md` | Portable quick brief (fast rules + pre-ship guardrails) |
| `brand/DESIGN.md` | Auto-generated machine projection for DESIGN.md-compatible tools |
| `brand/VISUAL-PROMPT-PACK.md` | Brand pack for image/video generators |
| `brand/guidelines/` | This document + voice-and-tone (deep human guidance) |
| `skill/SKILL.md` · `AGENTS.md` · `llms.txt` | Agent entry points |
| `assets/` | Logo, Bearnie variants, brand symbols, blur asset |
| `examples/` | Design-system specimen cards |
| `ui/react/` | React components — hero, header, stat row, case-study card, event banner, footer |

---

*Maintained by the RevOps team — questions to Maike or any RevOps member.*