polarize-ui

Live Storybook → · Releases

The design system behind Polarize’s research tools. It is built for interfaces that show scientific data honestly: every measured, modelled or speculative value carries a label, and the label can never be hidden.

A label may never be hidden. Its explanation must be.

It comes in two forms that share one set of tokens:

• Zero-build CSS + custom elements — link a stylesheet, no npm, no bundler.
• React — shadcn/ui components on the same theme, plus publication layouts, evidence badges and visx charts.

How we choose and judge a view for scientific data (the question first, five things every view states, forms for common data, simulation views, demo-data rules): METHOD.md.

What is in it

Science: the charts and analysis views (the point of the library)

Source: src/science/. Every view is in the live Storybook under Science.

General UI

Using it

It is not published to npm. If there is enough interest we will happily turn it into a proper npm package. Until then, use it straight from this repository, always pinned to a release tag, or fork or clone it and make it your own.

In a React app (Vite + Tailwind v4)

npm install github:polarizetech/polarize-ui#v0.5.2     # or: yarn add github:polarizetech/polarize-ui#v0.5.2

/* your app's main stylesheet */
@import "tailwindcss";
@import "tw-animate-css";
@import "@polarizetech/polarize-ui/theme.css";
@source "../node_modules/@polarizetech/polarize-ui/src";

import { Heatmap, NullDistribution, LineChart, Tier, Button } from "@polarizetech/polarize-ui/react"

• The package ships TypeScript source and your bundler compiles it; there is no build step here. It is type-checked with noUnusedLocals/noUnusedParameters on, so it compiles under strict app settings.
• Dark mode is a .dark class on <html>.
• Importing from /react also loads the self-hosted fonts.

In a plain HTML page

Add it as a git submodule pinned to a tag, and link the files:

git submodule add https://github.com/polarizetech/polarize-ui.git design
git -C design checkout v0.5.2

<link rel="stylesheet" href="https://github.com/polarizetech/polarize-ui/blob/main/design/design.css">
<link rel="stylesheet" href="https://github.com/polarizetech/polarize-ui/blob/main/design/publication.css">   <!-- optional: blog layouts -->
<script type="module" src="https://raw.githubusercontent.com/polarizetech/polarize-ui/main/design/design.js"></script>
<body class="ui">

The full wiring guide, including how to serve the fonts, is INTEGRATION.md.

Staying up to date

• Watch → Custom → Releases on this repository to be told when a new version is out. Each release has notes listing what changed.
• To update, change the tag you pin: the #v… in your dependency, or git -C design checkout v… for a submodule.
• Read the release notes before crossing a minor version while we are below 1.0 (see below).

Versioning

Releases follow Semantic Versioning. While the version is below 1.0.0, the rule is the one npm applies to 0.x versions:

Covered by that promise (the public API):

• everything exported from @polarizetech/polarize-ui/react, and its props;
• the stylesheet entry points (design.css, publication.css, specimens.css, theme.css) and the ui-* class names and modifiers they define;
• the CSS custom properties (--background, --space-4, --tier-measured, …) and the keys in tokens.json;
• the custom elements in design.js and their attributes.

Not covered: exact colour values and spacing (a tweak is a patch release, not a breaking change), the stories, the build scripts, and anything under .storybook/ or .github/.

Removing or renaming anything in the public API always produces a breaking bump: scripts/api_surface.py lists that surface, and the release workflow compares it with the previous release. What was removed is listed at the top of the release notes. Changes it cannot see, such as a prop’s type or a component’s behaviour, have to be marked by whoever makes them, and the contributor guidance (AGENTS.md) requires it.

Every push to main is released automatically by .github/workflows/release.yml, which applies these rules: a commit whose subject has !: (for example refactor!: rename Label to Eyebrow) or a BREAKING CHANGE: line produces a breaking bump, and anything else produces a patch. Setting the version in package.json by hand always wins.

Working on it

npm install
npm run storybook        # http://localhost:6006
python3 dev_check.py     # tokens, contrast, the type rule, generated-file drift

Edit tokens.json, never design.css; regenerate with python3 build_css.py and python3 shadcn/build_shadcn.py. src/ uses relative imports only. An @/ import would resolve against the consuming app’s alias, and dev_check.py rejects it. The shadcn CLI writes @/ imports, so rewrite them after npx shadcn add.

The Storybook’s own interface follows the viewer’s light or dark setting, and so does its Theme toolbar button. The MCP add-on (@storybook/addon-mcp) lets coding agents find the components and their stories.

Where it is used

These Polarize repos track new releases automatically. A daily workflow in each one moves its pin to the newest tag, runs that repo’s own checks, and commits and deploys only if they pass.

Background and design decisions: CLAUDE.md. React specifics: shadcn/SHADCN.md.

Licence

Code: MIT (see LICENSE). Fonts: SIL Open Font License, texts in fonts/. Icons: Phosphor, MIT.