@headspace_designsystem/hsds-web-library 0.1.0

package/README.md

@@ -0,0 +1,184 @@
+# hsds_web_library
+
+HeadSpace Design System — Web Component Library
+
+A TypeScript-first design token library and React component system built with [Emotion](https://emotion.sh/) for CSS-in-JS. This library translates the HeadSpace design system directly into code, giving engineers production-ready, typed, accessible components and giving designers a single source of truth that flows from Figma to the browser.
+
+---
+
+## What this is
+
+| For designers | For engineers |
+|---|---|
+| Contribute styling changes directly in code, not just in Figma | Install components as a package — no building from scratch |
+| Token changes propagate automatically to all components | Full TypeScript autocomplete on every design token |
+| Components match Figma 1:1 | Versioned releases via npm — no stale, deprecated components |
+
+---
+
+## 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 tokens
+      ↓
+ThemeProvider           React context that injects theme into the tree
+      ↓
+Components              Button, Input, Card, ... — all read from theme
+```
+
+**Why two layers?**
+If the primary blue changes, you update one hex value in `primitives/colors.ts`. Every semantic token that references it (`Primary/primary`, `Foreground/foregroundLink`, etc.) picks it up instantly — no hunt-and-replace across 50 components.
+
+---
+
+## Quick Start
+
+### 1. Install
+
+```bash
+npm install @headspace/hsds-web-library
+```
+
+`react`, `react-dom`, `@emotion/react`, and `@emotion/styled` are peer dependencies — your app must already have them installed.
+
+### 2. Wrap your app with the ThemeProvider
+
+```tsx
+import { HsdsThemeProvider } from '@headspace/hsds-web-library';
+
+function App() {
+  return (
+    <HsdsThemeProvider>
+      <YourApp />
+    </HsdsThemeProvider>
+  );
+}
+```
+
+### 3. Access tokens in your own styled components
+
+```tsx
+import styled from '@emotion/styled';
+
+// theme is fully typed — autocomplete works, typos fail at compile time
+const MyCard = styled.div(({ theme }) => ({
+  backgroundColor: theme.colors.background.surface,
+  borderRadius: theme.borders.radius.medium,
+  padding: theme.spacing[4],
+  boxShadow: theme.shadows.raised,
+}));
+```
+
+---
+
+## Token Reference
+
+### Colors
+
+#### Primitive palette
+Raw color values. **Never use these in components directly** — use semantic tokens instead.
+
+Families: `warmGrey`, `coolGrey`, `blue`, `orange`, `yellow`, `green`, `pink`, `purple`, `indigo`, `winkle`, `red`
+
+#### Semantic colors
+
+| Category | Tokens |
+|---|---|
+| `colors.primary` | `primary`, `primaryStrong` |
+| `colors.background` | `background`, `backgroundStrong` |
+| `colors.surface` | `surface`, `surfaceStrong`, `surfaceStronger`, `surfaceStrongest`, `surfaceModal`, `surfaceOnModal` |
+| `colors.overlay` | `overlay60/40/20`, `overlayInverse60`, `overlayLightStatic{80/60/40/20}`, `overlayDarkStatic{80/60/40/20}` |
+| `colors.foreground` | `foreground`, `foregroundWeak`, `foregroundWeaker`, `foregroundWeakest`, `foregroundInverse`, `foregroundLink`, `foregroundLinkStrong`, `foregroundHighlight`, `foregroundCritical`, `foregroundSuccess` |
+| `colors.border` | `border`, `borderStrong`, `borderStronger`, `borderStrongest`, `borderInverse` |
+| `colors.interactive` | `interactive`, `interactiveStrong`, `interactiveStronger`, `interactiveStrongest`, `interactiveInverse`, `interactiveInverseStrong` |
+| `colors.contrast` | `contrastForeground`, `contrastBackground`, `contrastForegroundWeak/Weaker/Weakest`, `contrastBackgroundWeak/Weaker` |
+| `colors.status` | `statusCritical`, `statusSuccess`, `statusWarning`, `statusInfo`, `statusHighlight` (+ `*Strong` variants) |
+
+### Typography
+
+Font family: **Headspace Apercu** (primary), **Apercu Mono** (utility/code)
+
+Type scale categories: `heading` (3xl–s), `body` (l–3xs), `label` (l–3xs), `link` (l–3xs), `utility` (l–xs), `caption`
+
+```tsx
+const headingStyle = theme.typography.desktop.heading['2xl'];
+// → { fontFamily, fontSize: '56px', fontWeight: 700, lineHeight: '1.1', letterSpacing: '-3px' }
+```
+
+### Spacing
+
+16-step scale from `2px` to `128px`. Access via `theme.spacing[16]` → `'16px'`
+
+### Border Radius
+
+| Token | Value | Figma name |
+|---|---|---|
+| `sharp` | 0px | hs-border-radius-sharp |
+| `small2X` | 4px | hs-border-radius-small2X |
+| `smallX` | 8px | hs-border-radius-smallX |
+| `small` | 12px | hs-border-radius-small |
+| `medium` | 16px | hs-border-radius-medium |
+| `large` | 24px | hs-border-radius-large |
+| `largeX` | 32px | hs-border-radius-largeX |
+| `pill` | 999px | hs-border-radius-pill |
+| `circle` | 50% | hs-border-radius-circle |
+
+### Shadows
+
+`none`, `default`, `navigationTop`, `navigationBottom`, `raised`, `overlay`
+
+---
+
+## Repository Structure
+
+```
+src/
+├── tokens/
+│   ├── primitives/        Raw palette values (internal — do not import in components)
+│   │   ├── colors.ts      Warm grey, cool grey, blue, orange, green, red, ...
+│   │   ├── typography.ts  Font families, weights, line heights, letter spacing
+│   │   ├── spacing.ts     2px–128px scale
+│   │   ├── borders.ts     Border radii and widths
+│   │   └── shadows.ts     Elevation shadow strings
+│   └── semantic/          Intent-driven aliases (what components consume)
+│       ├── colors.ts      primary, background, surface, foreground, border, ...
+│       └── typography.ts  Desktop type scale objects
+├── theme/
+│   ├── types.ts           HsdsTheme interface — the stable typed contract
+│   ├── emotion.d.ts       Module augmentation (makes theme typed in styled())
+│   ├── theme.ts           Assembled HsdsTheme object
+│   └── ThemeProvider.tsx  React ThemeProvider wrapper
+└── components/            (Phase 2+)
+```
+
+---
+
+## Roadmap
+
+| Phase | Status | Scope |
+|---|---|---|
+| 1 — Foundation | Complete | Token files, HsdsTheme, ThemeProvider |
+| 2 — Core Components | Planned | Button, Text, Stack, Input, Badge, Card, Divider |
+| 3 — Storybook | Planned | Component docs, interactive playground |
+| 4 — Full Library | Planned | Modal, Tooltip, Tabs, Checkbox, Toast, Avatar, + more |
+
+---
+
+## Contributing (for designers)
+
+1. Clone this repository and run `npm install`
+2. Edit token files in `src/tokens/` to update values
+3. Run `npm run typecheck` — if it passes, the values are valid
+4. Open a PR
+
+---
+
+## Tech Stack
+
+- **React 18** + **TypeScript 5** + **Emotion 11** + **Vite 5**

package/dist/components/Button/Button.d.ts

@@ -0,0 +1,3 @@
+import { ButtonProps } from './Button.types';
+export declare function Button({ variant, size, isLoading, isFullWidth, leftIcon, rightIcon, disabled, children, ...rest }: ButtonProps): import("@emotion/react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=Button.d.ts.map

package/dist/components/Button/Button.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Button.d.ts","sourceRoot":"","sources":["../../../src/components/Button/Button.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAA6B,MAAM,gBAAgB,CAAC;AA8R7E,wBAAgB,MAAM,CAAC,EACrB,OAAmB,EACnB,IAAc,EACd,SAAiB,EACjB,WAAmB,EACnB,QAAQ,EACR,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,GAAG,IAAI,EACR,EAAE,WAAW,oDAuBb"}

package/dist/components/Button/Button.types.d.ts

@@ -0,0 +1,18 @@
+import { default as React } from 'react';
+export type ButtonVariant = 'primary' | 'secondary' | 'tertiary' | 'ghost' | 'black' | 'white' | 'critical' | 'success' | 'warning' | 'textPrimary' | 'textSecondary';
+export type ButtonSize = 'large' | 'mediumLarge' | 'medium' | 'small' | 'xSmall';
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Visual style of the button. @default 'primary' */
+    variant?: ButtonVariant;
+    /** Height and font size tier. @default 'large' */
+    size?: ButtonSize;
+    /** Replaces content with a spinner and sets disabled. @default false */
+    isLoading?: boolean;
+    /** Stretches the button to fill its container. @default false */
+    isFullWidth?: boolean;
+    /** Icon rendered before the label. */
+    leftIcon?: React.ReactNode;
+    /** Icon rendered after the label. */
+    rightIcon?: React.ReactNode;
+}
+//# sourceMappingURL=Button.types.d.ts.map

package/dist/components/Button/Button.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Button.types.d.ts","sourceRoot":"","sources":["../../../src/components/Button/Button.types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,MAAM,MAAM,aAAa,GACrB,SAAS,GACT,WAAW,GACX,UAAU,GACV,OAAO,GACP,OAAO,GACP,OAAO,GACP,UAAU,GACV,SAAS,GACT,SAAS,GACT,aAAa,GACb,eAAe,CAAC;AACpB,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,aAAa,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEjF,MAAM,WAAW,WAAY,SAAQ,KAAK,CAAC,oBAAoB,CAAC,iBAAiB,CAAC;IAChF,qDAAqD;IACrD,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,kDAAkD;IAClD,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,wEAAwE;IACxE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,iEAAiE;IACjE,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC3B,qCAAqC;IACrC,SAAS,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;CAC7B"}

package/dist/components/Button/index.d.ts

@@ -0,0 +1,3 @@
+export { Button } from './Button';
+export type { ButtonProps, ButtonVariant, ButtonSize } from './Button.types';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/Button/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/Button/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAClC,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/components/index.d.ts

@@ -0,0 +1,2 @@
+export * from './Button';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA,cAAc,UAAU,CAAC"}

package/dist/demo.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=demo.d.ts.map

package/dist/demo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"demo.d.ts","sourceRoot":"","sources":["../src/demo.tsx"],"names":[],"mappings":""}