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.mdand theplot-*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 andstatus-*/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.pngon light backgrounds andhssm-logo-on-dark.pngon 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 shared visual language. Spine's docs-brand/ owns its
implementation for Material for MkDocs, and docs-sites.toml owns the six-site
distribution contract. The bundle vendors the design repo's tokens.json and
generates docs-brand/tokens.css from it with scripts/build_docs_brand.py,
resolving the theme values and aliases the export leaves to its consumers.
The bundle self-hosts IBM Plex and follows the MkDocs rules in 20-surfaces.md:
docs-primary header and tabs, text-link links, accent interaction states,
and slate on the dark theme values.
When the design repo changes its tokens, refresh and review the rendered docs in both schemes before distributing:
python scripts/build_docs_brand.py --from repos/hssm_design_system
python scripts/sync_docs_brand.py
--from refuses an export that drops a token the shared stylesheet uses. The
sync writes only to sites whose mkdocs.yml already uses the shared INHERIT
base; a site still on its own extra_css does not load tokens.css, so it is
reported as pending and left untouched. To move a site over, run
sync_docs_brand.py --repo <site> --adopt and switch its mkdocs.yml; the
bundle README describes the migration.
Edit the central bundle rather than its vendored copies. See the
documentation platform, the bundle's
docs-brand/README.md, and source ownership.
The navigation mark stays the existing white lockup on the indigo header until
the design repo ships its own white-only logo.
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.