Perron
Perron is the design system of Mylder, a live map of Copenhagen's buses, S-tog, metro and regional trains. This repository holds all of it: the design tokens and the build that turns them into CSS, TypeScript and a Penpot file, the fonts, the icons and the Mylder mark, the guidelines in docs/foundations/, and 54 React components and 14 patterns on Base UI, with APIs shaped like MUI's and their own words in English, Danish, Swedish and Norwegian. Every Mylder screen is built from them.
Each component and pattern is built to the component contract by the factory loop of the roadmap: a spec goes in, and a loop of agents writes the code, the stories, the tests and the docs, with a code review as the gate.
Docs: marcin-sieradzki.github.io/perron, with the Storybook beside it. Packages: @mylder/perron and @mylder/perron-mcp on npm.
Use it
npm install @mylder/perron
import '@mylder/perron/perron.css'
import { Button, PerronProvider } from '@mylder/perron'
import { DepartureRow } from '@mylder/perron/patterns'
Load the stylesheet once at the app root, and wrap the app in PerronProvider to set the language of the words the components show on their own. Light is the default theme; data-theme="dark" on any element switches it. The package's README has the rest.
Agents can ask the MCP server, npx -y @mylder/perron-mcp over stdio, for Perron's tokens, docs and components and for the Base UI and MUI API of the versions a project installs; its README has the tools and the .mcp.json entry.
Standard
The tokens follow the Design Tokens specification 2025.10, the first stable version from the W3C Design Tokens Community Group: its Format module for the files, its Color module for colour values and its Resolver module for how base, light and dark combine.
The build checks every file against the format rule by rule (scripts/lib/spec.ts) before it writes anything, so a token that breaks the format fails npm run check. The format's $root tokens and $extends groups are not read by the build yet; the check reports them until it does.
What is here
| Path | What it is |
|---|
packages/perron/ | The @mylder/perron package, published to npm, which holds the next eight paths and data/, the tokens, docs and components as JSON for the MCP server |
packages/perron/src/ | The components, the patterns (exported from @mylder/perron/patterns), PerronProvider and the locales: en, da, sv and nb |
packages/perron/components.json | The registry: every component and pattern with its layer, status, Base UI parts and dependencies. npm run registry writes the barrels, exports and spec pages from it |
packages/perron/tokens/*.tokens.json | The token sources: base, a light and a dark theme, and motion-reduced overrides |
packages/perron/tokens/perron.resolver.json | How the files combine (the format's resolver module): base always, then light or dark, then full or reduced motion |
packages/perron/tokens/generated/ | Built from the sources: tokens.css, typography.css, tokens.ts, and penpot.tokens.json in the older flavour Penpot imports. Never edit by hand |
packages/perron/styles/perron.css | The one file an app loads: fonts, tokens, typography classes, the icon class and page defaults |
packages/perron/icons/ | The icons as SVG files, and icons.json, which lists them by category with the size and use of each |
packages/perron/logos/ | The Mylder mark, one file per theme, and logos.json |
packages/mcp/ | The @mylder/perron-mcp package, the MCP server for agents: tokens, docs and the pinned Base UI and MUI references |
.mcp.json | The MCP servers a session here gets: Perron's own, from source, and the hosted MUI and Base UI docs |
scripts/ | The token and docs build and its tests: the format, contrast, icon style and logo colours |
|
Releases
Both packages release from CI with Changesets. A PR that changes what a package ships adds a changeset (npx changeset): the packages it releases, the bump, and the changelog line. On main, .github/workflows/release.yml gathers the changesets into a "Version packages" PR. Merging that PR packs the new versions, installs the tarballs in a scratch Vite app (scripts/smoke-consumer.ts), and publishes the same tarballs to npm with provenance through npm trusted publishing, so no npm token is kept once the packages exist. The very first publish, before npm can trust the workflow, signs in with a short-lived NPM_TOKEN secret that is deleted afterwards.
Token names
Every token is --perron-<group>-<name> in CSS and <group>.<name> in the sources.
- Palette: raw colours,
palette.<hue>.<step>. A neutral ramp from 0 (white) to 950, and blue, green, orange, red and yellow at steps 100, 300, 500, 700 and 900. Only colour tokens read the palette.
- Colour: what a colour is for, per theme.
text, surface, border, status (success, warning, danger, info) and the brand colour for the interface; chart, transit (lines, modes, delays, severities), data-state and map for what Mylder shows. For example --perron-color-text-secondary, --perron-color-surface-warning, --perron-color-transit-line-a.
- Space: a 4 px base, named by count of 4 px units times 100:
space.050 is 2 px, space.200 8 px, space.800 32 px.
- Radius:
xs 4, sm 6, md 8, lg 12, xl 16 px and full.
- Type: 16 roles under
typography.* (display, heading-*, body, label, overline, stat, data-* and more), each a composite of family, weight, size, line height and tracking. Sizes use the spacing numbers: font.size.400 is 16 px.
- Borders and focus:
border.width.025 (1 px) and border.width.050 (2 px); focus.width and focus.offset for the focus ring.
- Icons:
icon.size.325, icon.size.400 and icon.size.450: 13, 16 and 18 px.
- Also
shadow, size, opacity, z-index, duration, easing, breakpoint, effect, vehicle-dot (the data-state dot's geometry) and map (canvas measures).
Commands
Node 22 or later.
npm install
npm run tokens # rebuild packages/perron/tokens/generated and the tables in docs/foundations
npm run check # generated files and tables up to date, typecheck, lint, format, tests
npm run storybook # the guideline pages in Storybook, at localhost:6006
npm run dev -w website # the website, at localhost:3000/perron/ (its path on GitHub Pages)
npm run storybook:build # Storybook in dist/storybook
npm run site:build # the docs site in dist/site, after npm run build -w website and storybook:build
npm run smoke # pack both packages and install them in a scratch Vite app
Storybook reads docs/ itself (scripts/lib/pages.ts), so its pages change with the markdown and the tokens. Each page has a two-line MDX file in storybook/pages/; a Light and Dark switch on every page sets the theme.
The docs site is deployed to GitHub Pages from main by the CI workflow, once the check passes: the website from website/ at the root, and this Storybook under storybook/. Beside them, scripts/build-site.ts writes what agents read: llms.txt with one line per page, a Markdown twin of every page at its path in this repository, and an AGENTS.md for apps that install Perron.
Vercel builds the same site from vercel.json on every push: at the root of its own address rather than under /perron/, because the build sets PERRON_SITE_URL to the project's production address, and website/lib/base-path.ts takes the base path and every absolute link from it. Pull requests get a preview there too. Only the Vercel build adds Vercel Web Analytics to the website's pages, which counts visits without cookies once Web Analytics is enabled on the project; Storybook and the GitHub Pages copy are not counted.
