Headspace Design System

A multi-platform design system for Headspace — React components for web, Flutter widgets for mobile, and a shared documentation site that serves as a single source of truth for engineers and designers across both platforms.

Packages

| Package | Platform | Registry | Latest | |---|---|---|---| | @headspace_designsystem/hsds-web-library | Web (React) | npm | v0.2.2 | | hsds_mobile | Mobile (Flutter) | pub.dev | v0.1.0 |

What's in this repo

/
├── src/                          Web component library (React + Emotion)
│   ├── tokens/
│   │   ├── primitives/           Raw palette — colors, typography, spacing, borders, shadows
│   │   └── semantic/             Intent-driven aliases (foreground, background, border, ...)
│   ├── theme/
│   │   ├── types.ts              HsdsTheme interface — the typed contract
│   │   ├── theme.ts              Assembled HsdsTheme object
│   │   └── ThemeProvider.tsx     React context that injects the theme
│   └── components/
│       └── Button/               11 variants, 5 sizes, loading + icon states
│
├── mobile/                       Flutter mobile library
│   ├── lib/src/
│   │   ├── components/           HsdsBottomNav, HsdsBottomNavItem
│   │   └── assets/icons/         SVG icon sets (5 tab configurations)
│   └── pubspec.yaml
│
└── docs/                         Next.js 14 documentation site (deployed on Vercel)
    ├── app/
    │   ├── page.tsx              Overview — Web + Mobile
    │   ├── getting-started/
    │   │   └── installation/     Installation guides — Web + Mobile
    │   └── components/
    │       ├── button/           Button docs with live Sandpack playground
    │       └── bottom-nav/       Bottom Navigation docs (Flutter)
    ├── config/
    │   ├── registry.ts           Component registry — maps components to web/mobile packages
    │   └── library.ts            Version + package name config (read from env at build time)
    └── components/
        ├── ComponentPlatformBadge.tsx   Platform badge/toggle per component page
        ├── LocalPlatformToggle.tsx      Web/Mobile toggle for overview + installation pages
        ├── PackageMeta.tsx             Package + version metadata block in MDX pages
        └── Sidebar.tsx                 Navigation sidebar

Web Library

React component library built with Emotion and TypeScript.

Install

npm install @headspace_designsystem/hsds-web-library @emotion/react @emotion/styled

Setup

import { HsdsThemeProvider } from '@headspace_designsystem/hsds-web-library';

export default function App({ children }) {
  return <HsdsThemeProvider>{children}</HsdsThemeProvider>;
}

Usage

import { Button } from '@headspace_designsystem/hsds-web-library';

<Button variant="primary">Save changes</Button>
<Button variant="secondary" size="small">Cancel</Button>
<Button variant="primary" isLoading>Saving…</Button>

Token Architecture

All visual decisions flow in one direction:

Primitive tokens   →   Raw Headspace palette (warmGrey100, blue200, ...)
Semantic tokens    →   Intent-driven aliases (foreground, background, border, ...)
HsdsTheme object   →   Typed Emotion theme assembled from semantic tokens
ThemeProvider      →   React context injecting the theme into the component tree
Components         →   Button, ... — all consume theme, never raw values

Publish

npm run publish:patch   # bug fix, no API change
npm run publish:minor   # new component or backwards-compatible feature
npm run publish:major   # breaking change

Each command: build → bump version → npm publish --access public → git tag + push.

Mobile Library (Flutter)

Flutter widget library for iOS and Android, published to pub.dev.

Install

# pubspec.yaml
dependencies:
  hsds_mobile: ^0.1.0

Or:

flutter pub add hsds_mobile

Usage

import 'package:hsds_mobile/hsds_mobile.dart';

HsdsBottomNav(
  selectedIndex: _selectedIndex,
  onItemTapped: (i) => setState(() => _selectedIndex = i),
  items: HsdsBottomNavIcons.mindfulMovement,
)

Publish

npm run publish:flutter:patch
npm run publish:flutter:minor
npm run publish:flutter:major

Documentation Site

Next.js 14 app in docs/, deployed on Vercel at every push to main.

Local dev

cd docs && npm install && npm run dev   # http://localhost:3000

Platform-aware docs

Each component page shows a platform badge (Web or Mobile) or a toggle (both platforms) inline with the component title. The ?platform= URL param is owned per-page — links are shareable and bookmarkable.

The component registry (docs/config/registry.ts) is the single source of truth for which components exist, which platforms they support, and what their docs paths are.

Version sync

Web version is read from NEXT_PUBLIC_LIB_VERSION (set at Vercel build time from package.json). Mobile version is read from NEXT_PUBLIC_MOBILE_LIB_VERSION (set from mobile/pubspec.yaml). No version strings are hardcoded in the docs.

Components

| Component | Web | Mobile | Docs | |---|---|---|---| | Button | ✅ v0.2.2 | — | /components/button | | Bottom Navigation | — | ✅ v0.1.0 | /components/bottom-nav |

Tech Stack

| Layer | Technology | |---|---| | Web library | React 18, TypeScript 5, Emotion 11, Vite 5 | | Mobile library | Flutter 3, Dart 3, pub.dev | | Docs site | Next.js 14 (App Router), MDX, Sandpack, Vercel | | Design source | Figma (shared design system, web + mobile) | | Tokens | Primitive → Semantic → HsdsTheme (typed) |