Skip to content

Design System and Tokens

Ankit Upadhyay edited this page Aug 25, 2026 · 3 revisions

Design System and Tokens

How the UI stays consistent and on-brand across web and mobile. The live token layer is CSS-variable-driven in the web app (apps/frontend/src/app/globals.css) with a parallel palette on mobile (apps/mobileAppYC/src/theme/colors.ts); the umbrella plan is Frontend Convergence.

Where the tokens actually live

  • Web (source of truth): apps/frontend/src/app/globals.css - the :root warm-bone light layer plus the html[data-theme='dark'] espresso overrides. The live brand blue is #257bed. A per-component token reference sits beside the design system at apps/frontend/src/app/ui/tokens.md.
  • Mobile: apps/mobileAppYC/src/theme/colors.ts defines the app's own warm-bone light and espresso dark palettes, read through src/shared/hooks/useTheme.ts. src/theme/semanticTokens.ts is a hand-maintained naming approximation that application code does not import (its own header says so, and warns that it drifts) - it is not a binding to any shared contract.
  • packages/design-tokens is not the source of truth. The package exists but is unbuilt and unconsumed: its package.json entry points target a dist/ output that no workflow ever builds, no app source imports it (the web app declares it as a workspace devDependency but never uses it), and its palette is stale (brand #247aed, pure-white surfaces - both superseded by the warm-bone layer). Treat it as a known cleanup item, not a dependency; the one CI reference left is .github/workflows/chromatic.yml, which still lists the package as a path trigger/external. See Shared Packages.

The warm-bone redesign

The visual overhaul - internally the "warm-bone" palette - is live across web, mobile, desktop, and the transactional emails (the email templates moved onto it in 2026-08). The initial rollout landed via:

Surface Landed via Epic
Web PIMS (light + dark) PR #1799 (merged 2026-07-17), then the responsive tablet/phone rebuild #1912, 1:1 design pass #1916, side-modal redesign #1977, StatusPill convergence #1981, flat org sections #1984, and chat restyle #1874 #1798
Mobile app foundation PR #1792 (merged 2026-07-20) #1791
Public marketing site PR #1773 (merged 2026-07-18), follow-ups #1876/#1877/#1878 #1772

These share the same palette and conventions, carried per app rather than through a shared package (see above). A few themes that recur in the work:

  • Theme foundation first, then ripple. Each app's token layer lands first, then components swap to it (e.g. via the useTheme hook on mobile) so the change propagates rather than being re-implemented per screen.
  • Dark mode shipped with the redesign: the web PIMS ships light + dark (PR #1799), and mobile dark mode is live (espresso dark, useTheme returns darkModeLocked: false since PR #1792).
  • Static routes and CSP: on the web app, a nonce-based CSP breaks statically-generated public routes (no per-request nonce in pre-rendered scripts) - those routes keep unsafe-inline; app routes get the nonce/pre-paint treatment. Playwright's public suite catches regressions unit tests miss.

Component library and Storybook

Storybook is in place (apps/frontend/.storybook/, with *.stories.tsx co-located next to components under src/app/ui/ and feature directories), and Chromatic visual-regression runs in CI via .github/workflows/chromatic.yml (CI/CD Pipeline). The Frontend Convergence plan continues normalizing the web component library (Button, Card, Badge, and the rest). Component work follows the repo's frontend-design guidance (the design system, tokens, and styling conventions).

Accessibility is part of design

Color is never the sole carrier of meaning, interactive elements carry ARIA, and components ship a jest-axe check. The full standard is in Accessibility.

Design source

Product design lives in Figma.

Related

Product & Domain
Architecture
Applications
Design & Accessibility
Engineering Handbook
Decisions (ADRs)
Design Docs & Plans
Roadmap
Operations
Meta

Canonical code & docs: main repo · Auto-generated companion: DeepWiki

Clone this wiki locally