@headspace_designsystem/hsds-web-library

Headspace Design System

A TypeScript-first, Emotion-based React component library. Two-layer token architecture (primitives → semantic) ensures rebranding only touches primitive values — all components pick up changes automatically.

11Color Families
60+Semantic Tokens
28Type Styles
11Button Variants
React 18Emotion CSS-in-JSTypeScriptVite 5ESM + UMD

Colors

Primitive palette — 11 color families, each with 4–8 shades. Components always reference semantic tokens, never these directly.

Primitive Palette

Warm Grey
100#f9f4f2
200#e2ded9
300#c6c1b9
400#a8a5a0
500#63605d
600#44423f
700#2d2c2b
800#141313
Cool Grey
100#e5e7ec
200#d2d5de
300#9da5b8
400#7580a3
500#545f82
600#2a2d55
700#101340
800#050726
Blue
100#00a4ff
200#0061ef
300#0040ea
400#0000db
Orange
100#ffa500
200#ff7300
300#fc5500
400#f72900
Yellow
100#ffe14f
200#ffce00
300#ffb700
400#ff9900
Green
100#31cc66
200#01a652
300#02873e
400#0b662a
Pink
100#ffcae7
200#ffa1cc
300#ff76b8
400#ff52a5
Purple
100#ad85d1
200#9e65c6
300#8144a8
400#5f2b89
Indigo
100#5431a5
200#3b197f
300#281466
400#1a0c54
Winkle
100#727ce5
200#6666cc
300#524aa5
400#383a82
Red
100#ff5a5a
200#ef3c3c
300#e01919
400#bf0000

Semantic Tokens

Intent-driven color aliases — use these in components.

Primary
primary#0061ef
primaryStrong#0040ea
Background
background#ffffff
backgroundStrong#f9f4f2
Foreground
foreground#2d2c2b
foregroundWeak#44423f
foregroundWeaker#63605d
foregroundWeakest#a8a5a0
foregroundLink#0061ef
foregroundCritical#e01919
foregroundSuccess#02873e
foregroundHighlight#ff7300
Status
statusCritical#e01919
statusSuccess#02873e
statusWarning#ffb700
statusInfo#0040ea
statusHighlight#ff7300
Border
border#e2ded9
borderStrong#c6c1b9
borderStronger#63605d
borderStrongest#2d2c2b
Contrast
contrastBackground#050726
contrastForeground#e5e7ec
contrastForegroundWeak#9da5b8

Typography

Desktop type scale using Headspace Apercu (sans) and Apercu Mono (utility). All styles include font-size, weight, line-height, and letter-spacing.

Heading

Heading 3XL64px / 700 / lh 1.0 / ls -0.03em
The quick brown fox
Heading 2XL56px / 700 / lh 1.1 / ls -0.03em
The quick brown fox
Heading XL48px / 700 / lh 1.1 / ls -0.03em
The quick brown fox
Heading L40px / 700 / lh 1.2 / ls -0.03em
The quick brown fox
Heading M32px / 700 / lh 1.2 / ls -0.03em
The quick brown fox
Heading S24px / 700 / lh 1.2 / ls -0.03em
The quick brown fox

Body

Body L20px / 400 / lh 1.5 / ls 0
The quick brown fox
Body M18px / 400 / lh 1.5 / ls 0
The quick brown fox
Body S16px / 400 / lh 1.5 / ls 0
The quick brown fox
Body XS14px / 400 / lh 1.5 / ls 0
The quick brown fox
Body 2XS12px / 400 / lh 1.5 / ls 0
The quick brown fox
Body 3XS10px / 400 / lh 1.5 / ls 0
The quick brown fox

Label

Label L20px / 700 / lh 1.2 / ls -0.03em
The quick brown fox
Label M18px / 700 / lh 1.2 / ls -0.03em
The quick brown fox
Label S16px / 700 / lh 1.2 / ls -0.03em
The quick brown fox
Label XS14px / 700 / lh 1.2 / ls -0.03em
The quick brown fox
Label 2XS12px / 700 / lh 1.2 / ls -0.03em
The quick brown fox
Label 3XS10px / 700 / lh 1.2 / ls -0.03em
The quick brown fox

Utility (Mono)

Utility L14px / 400 / lh 1.5 / ls 0.04em
The quick brown fox
Utility M12px / 400 / lh 1.5 / ls 0.04em
The quick brown fox
Utility S10px / 400 / lh 1.5 / ls 0.04em
The quick brown fox
Utility XS8px / 400 / lh 1.5 / ls 0.04em
The quick brown fox

Spacing

16-step spacing scale from 2px to 128px.

2
2px
4
4px
8
8px
12
12px
16
16px
24
24px
32
32px
40
40px
48
48px
56
56px
64
64px
72
72px
80
80px
96
96px
120
120px
128
128px

Borders

9 border radius tokens, from sharp (0) to circle (50%).

sharp0px
small2X4px
smallX8px
small12px
medium16px
large24px
largeX32px
pill999px
circle50%

Shadows

6 elevation levels — all use warmGrey800 at varying opacity.

noneFlat surface, no depthnone
defaultSubtle bottom shadow — buttons0px 2px 0px 0px rgba(20,19,19,0.20)
navigationTopTop nav bar — casts downward0px 2px 4px 0px rgba(20,19,19,0.08)
navigationBottomBottom nav — casts upward0px -2px 4px 0px rgba(20,19,19,0.08)
raisedCards, popovers, floating UI0px 2px 4px 0px rgba(20,19,19,0.20)
overlayModals, drawers, full-screen0px 0px 12px 0px rgba(20,19,19,0.20)

Button

11 variants × 5 sizes. All use border-radius: 999px, font-weight 700, and letter-spacing −0.03em. Built with Emotion styled components.

Variants

Primary
Secondary
Tertiary
Ghost
Black
White
Critical
Success
Warning
Text primary
Text secondary

Sizes — Primary

56px
48px
40px
32px
24px

States — Primary Large

Default
Hover
Active
Disabled
Loading