Using a generated library

A released design system is an ordinary npm package: React components, a theme, an icon module, type declarations, and a few files that explain the system without running anything. You do not need Milda to use it. This page is the consumer's side, from install to dark mode.

#Install

The package lives in the registry the system's owners chose: the hosted Milda registry, npm, GitHub Packages, or their own. Route only the scope there and leave everything else on the public registry. The Release dialog shows the exact lines for an organisation; the shape is always this:

# .npmrc
@acme:registry=https://registry.milda.app
# all other packages continue to resolve from npmjs

npm install @acme/design-system

A private registry needs a token in the same file; it is per user and per scope, so a token that installs one organisation's packages will not install another's. milda init --consumer @acme/design-system writes the routing for you.

#The theme

Every component's styles reference custom properties that theme.css declares. Import it once, at the root of the app. A component that renders unstyled is almost always a missing theme import.

import '@acme/design-system/theme.css'
import { Button } from '@acme/design-system'

#Colour scheme and other contexts

Each context group of the system is one data attribute. Set it on <html> for the whole app or on any subtree:

<html data-color-scheme="dark">
  …
  <aside data-density="compact">…</aside>

The theme carries a block per context that re-points the tokens that answer differently there, so switching costs one attribute and no re-render of your own. A component whose prop is a context (variant, size) sets the same attribute on its own root, for its own subtree only.

#Components

Props are typed exactly as the contract says: a context prop is a union of its contexts, a required-when is a type the compiler enforces, a one-of pair rejects both and neither. Events are on handlers. The generated code depends on React alone; there is no runtime of Milda's in your bundle and nothing calls home.

<Button label="Save" variant="secondary" onClick={save} />
<Button label="Save" loading />                  // error: loadingLabel is required when loading
<IconButton icon="Done" label="Mark as done" />  // exactly one of label | labelledBy

#Slots and children

A part the system declared as a slot is yours to fill. The default slot receives children; a named slot is a prop of the same name. The emission idiom is the system owner's choice per target: a props API, a compound API (<Dialog.Title>), or both, and the package's DESIGN.md says which.

#Icons

Icons are a generated Icon module keyed by the system's curated glyph names, vendored as data URIs. An icon prop takes one of those names, and a name that is not in the library is a type error rather than a broken image.

#What ships beside the code

A package is read by people and by agents, and only one of them can open the editor. So the release can write the system out in forms that need no tool, all generated from the same document on every release:

• DESIGN.md - every token, component, prop, event and slot, plus the usage rules, as readable markdown.
• AGENTS.md - how to build with the library: what the API is, what is closed, and the usage rules with their reasons. The file a coding agent reads before it writes a line.
• llms.txt - the conventional index an AI tool looks for first.
• design-system.json - the contract as data, for scripts.
• design-system.milda - the whole system in its own language.

#Usage rules

The system may say how it is meant to be composed: one primary button per form, no badge inside a button, colours only from tokens. Those rules are in AGENTS.md with their reasons and in design-system.json as data. Read them once; an agent reads them every time.

#Upgrading

Versions are computed from the contract, so the number tells you what to expect: a patch changes nothing you can observe, a minor adds optional surface, a major removed or narrowed something. milda diff lists the exact contract changes between your installed version and the latest, and milda diff --fail-on major is a CI gate. See The CLI.