Installation

Add the kit from npm, from pip for Python, or link the hosted files.

In this chapter 8 pages

JavaScript projects

The whole kit is one package on npm.

npm install @dario-loi/polytope

To install straight from GitHub instead, npm 12 needs the project to allow git dependencies, and the address needs quotes for zsh. Upgrading a git install means uninstalling first, so the registry is the easier path.

echo "allow-git=root" >> .npmrc
npm install "github:dario-loi/polytope#v0.6.3"

What the package exports:

Import path	What you get
`@dario-loi/polytope/css`	Everything: fonts, tokens, every component. One file.
`@dario-loi/polytope/tokens.css`	Only the custom properties, for projects that bring their own components.
`@dario-loi/polytope/css/button.css`	One component at a time. Needs `tokens.css`.
`@dario-loi/polytope/js/all.js`	The scripts: probability machine, copy buttons, theme toggle, on-this-page list.
`@dario-loi/polytope/astro`	Astro components.
`@dario-loi/polytope/tokens`	Tokens as a JavaScript module, with TypeScript types.
`@dario-loi/polytope/tokens.json`	Tokens as flat JSON, with light and dark values.

The other targets page lists the Tailwind, Sass, LaTeX, Figma, and editor exports.

Using Polytope with Impeccable

Impeccable is a design skill for AI coding agents such as Claude Code. It reads a project's visual system from DESIGN.md and .impeccable/design.json in its root. The package ships both, and one command copies them into a site:

npx @dario-loi/polytope            # copies DESIGN.md and .impeccable/design.json
npx @dario-loi/polytope --check    # fails if the copies are older than the installed Polytope

In a project that has Polytope installed, npx runs that copy. The command will not replace another system's DESIGN.md unless you pass --force. Copy the files again after upgrading Polytope, and add the check to the site's CI to catch a stale copy.

A site without npm, such as a static site built by a Python script, can fetch the same two files pinned to a release, and link the hosted stylesheet in its template:

curl -fsSLo DESIGN.md https://raw.githubusercontent.com/dario-loi/polytope/v0.6.3/DESIGN.md
mkdir -p .impeccable
curl -fsSLo .impeccable/design.json https://raw.githubusercontent.com/dario-loi/polytope/v0.6.3/.impeccable/design.json

With those files in place, Impeccable builds every new page inside Polytope and its design checker flags anything off the system, such as a font Polytope does not use. Then run /impeccable init in Claude Code so the site gets its own PRODUCT.md: who it is for, what it is for, and its real content.

Python

The figure and app themes are on PyPI as polytope-theme:

pip install polytope-theme
# with the libraries you use:
pip install "polytope-theme[matplotlib,plotly]"

No install at all

The docs site serves the built kit, so any static page can link it:

html

<link rel="stylesheet" href="https://dario-loi.github.io/polytope/kit/polytope.css">
<script type="module" src="https://dario-loi.github.io/polytope/kit/js/all.js"></script>

Working on the kit itself

git clone https://github.com/dario-loi/polytope
cd polytope
npm install          # build dependencies
npm run build        # rebuilds dist/; commit the result
npm run docs:dev     # rebuilds the kit, starts this site
npm run check:contrast

Edit tokens in tokens/tokens.json and styles in css/src/. Never edit dist/ by hand; the build overwrites it. Commit it after each build, because installs read it straight from the repository.