Use the design system

hssm_design_system is the core repository for HSSM's shared visual specification, design tokens, and brand assets. Use it when designing a website, documentation page, notebook figure, slide deck, or diagram. It contains specifications and reusable files; the React website and the implementations of those other surfaces live elsewhere.

This inventory was checked against commit 566f781 on 2026-10-15. The repository is private: contributors need GitHub access.

Get the checkout

From Spine, run ./setup.sh. It clones the design repo along with the other five core repositories and skips checkouts that already exist. The default path is repos/hssm_design_system; ./setup.sh --sibling places it beside Spine instead. All three agent launchers include it when present. There is no uv sync, npm install, or build command for this static repository.

What it contains

File or directory	Contents
README.md	Brand book: wave mark, palette, typography, layout, shapes, icons, motion, writing voice, and accessibility rules
10-landing-site.md	React/Tailwind landing-site specification: page sections, navigation, buttons, cards, install block, code panel, and figures
20-surfaces.md	Rules for MkDocs, marimo notebooks, scientific plots, Marp slides, Graphviz development graphs, and Mermaid roadmaps
30-status-and-open-items.md	Rollout status dated 2026-10-02 and remaining implementation/asset work
tokens.json	Version 3 token definitions, theme values, aliases, and usage notes
tokens.css	The 71 color tokens as CSS custom properties; dark default with light-theme overrides
assets/Logos/	Two transparent HSSM PNG lockups, for light and dark backgrounds, plus usage rules
assets/Partners/	Carney Institute JPG and Brown University PNG, plus usage rules
components/Cover/preview.html	A 960 × 288 cover illustration fragment using inline SVG and CSS

The JSON contains 71 colors, two font families, 15 typography styles (nine web, four docs, two slides), 11 spacing values, three radii, 16 layout settings, and five plot/demo settings. Color groups include the 16-stop wave palette, interface and code roles, observed/predicted plots, status, graph states, workstreams, and package identities. Colors may be hex values, {token-name} aliases, or objects with light and dark values. Typography lives under type.groups[].styles[]; the other groups have named token arrays.

Apply it to a website or interface

Copy tokens.css into the consuming project's stylesheet directory and record the source commit in that project's change. Import it before component styles, choose a theme on the root element, and use semantic color roles:

<html lang="en" data-theme="light">
  <head>
    <title>HSSM example</title>
    <link rel="stylesheet" href="tokens.css">
    <style>
      body { background: var(--surface); color: var(--ink); }
      a { color: var(--text-link); }
      button { background: var(--primary); color: var(--on-primary); }
      :focus-visible { outline: 3px solid var(--focus-ring); outline-offset: 4px; }
    </style>
  </head>
  <body><a href="https://lnccbrown.github.io/HSSM/">HSSM documentation</a></body>
</html>

Use data-theme="dark" for the dark palette. This is a color-wiring example; component geometry and behavior come from the brand book and landing-site specification. Load IBM Plex Sans and IBM Plex Mono separately and translate the typography, spacing, radius, and layout tokens into your app's styles or Tailwind theme. The CSS export contains colors only: it does not define --font-sans, --space-*, or --radius-*. Font files are not bundled.

The cover fragment also needs the token stylesheet and a --font-sans definition in its surrounding page. It is not a complete standalone preview application. The repository calls its CSS generated, but supplies no generator; a consumer introducing generation should make that step reproducible and resolve the JSON's theme values and aliases explicitly.

Apply it to plots, slides, and diagrams

• Plots: follow 20-surfaces.md and the plot-* tokens. The specification places observed data in blue (#1799d1) beneath predicted data in dark red (#ae043e), on white figure backgrounds with IBM Plex Sans. Prediction curves use 1.25-point lines; the 50% and 94% uncertainty bands are equal-tailed percentile bands, not HDIs. These are design values to implement in plotting code; the repo does not provide a Matplotlib style package.
• Slides: adapt the existing Marp theme using the slide typography, 1280 × 720 canvas, footer reserve, and status tokens. The repo specifies those choices but does not ship a Marp theme.
• Diagrams: use graph-* for Graphviz states and status-*/ws-* for Mermaid roadmaps, keeping labels and legends so meaning is not color-only. Diagram generators remain in their consuming projects.
• Logos: use hssm-logo-full-color.png on light backgrounds and hssm-logo-on-dark.png on dark navy. Follow each asset directory's README. The Carney lockup already names Brown and goes on a white plate on dark pages; the separate Brown mark is retained for other documents and slides.

For agent-assisted work, name the relevant source files explicitly, for example: “Use repos/hssm_design_system/README.md, tokens.json, and 20-surfaces.md to style this figure. Inspect the current plotting implementation and keep its statistical meaning intact.”

Relationship to Spine's existing branding

The design repo owns the intended shared visual language. Spine's docs-brand/ owns the implemented MkDocs bundle, and docs-sites.toml owns its six-site distribution contract. The existing bundle still uses Material's default Roboto and its earlier palette; registering this repository does not restyle the docs or add a seventh documentation site.

To adopt the specification in native docs, start a separate coordinated change to the shared bundle and affected site configuration. Review light/dark colors, font loading, contrast, and rendered pages, then distribute through scripts/sync_docs_brand.py. Edit the central bundle rather than its vendored copies. See the documentation platform and source ownership.

The upstream status file records the website alignment branch as ready for review on 2026-10-02 and lists docs, slides, plotting defaults, and diagrams as not yet migrated. That is a dated report, not verification of their current deployment. Missing assets include the SVG logo master, white-only logo, wave-only favicon, and reversed/vector Carney mark. There is no committed automated validation suite or license file in the inspected export; its accessibility assertions are specification claims, not checks run by Spine.

Spine declares the repo in estate/repos.toml with gather = false. Local core drift checks include it, but production weekly-report collection still requires a coordinated deployed allowlist change and token-access preflight.