A design token and Storybook workspace for the Arizona Digital design system. This repo contains the source token definitions, generated token output, component-package contributor guides, and a Storybook environment for reviewing and validating the system.
This is an npm workspaces monorepo with four packages:
├── packages/
│ ├── components-html/ # @az-digital/components-html — Arizona Bootstrap markup for Storybook (library `html`, not released)
│ ├── components-react-bootstrap/ # contributor guide for the React Bootstrap implementation
│ ├── components-web/ # @az-digital/components-web — custom elements (library `web`, preview)
│ ├── tokens/ # @az-digital/tokens — design token source and build output
│ │ ├── tokens.json # source DTCG token definitions
│ │ ├── style-dictionary.config.mjs
│ │ ├── dist/ # generated output (committed, built by Style Dictionary)
│ │ │ ├── tokens.css # CSS custom properties (--az-color-brand-*, etc.)
│ │ │ ├── tokens.scss # Sass variables
│ │ │ ├── tokens.vars.js # JS module of var(--…) references
│ │ │ └── tokens.vars.d.ts # types for tokens.vars.js
│ │ └── package.json
│ ├── contracts/ # @az-digital/contracts — component contracts and their check
│ │ ├── contract.schema.json # what a contract may say
│ │ ├── contracts/ # one <component>.contract.json per component
│ │ ├── scripts/build.mjs # the check, which also writes dist/contracts.json for docs and contract checks
│ │ └── README.md
│ ├── storybook-addon-tokens/ # @az-digital/storybook-addon-tokens — token doc blocks and Tokens tab
│ │ ├── src/ # addon source (preset, Tokens tab, doc blocks)
│ │ └── README.md
│ ├── storybook-addon-libraries/ # @az-digital/storybook-addon-libraries — Library toolbar; the contract for component libraries
│ │ ├── src/ # addon source (preset, toolbar, story helper, doc blocks)
│ │ ├── library.schema.json # the azDesign.library manifest
│ │ └── README.md
│ └── storybook/ # @az-digital/storybook — private Storybook preview
│ ├── src/ # token catalog logic and tests
│ ├── stories/ # Storybook stories
│ ├── .storybook/ # Storybook config
│ └── package.json
├── patches/ # changes to Arizona Bootstrap's source, one per pull request for it
├── package.json # workspace root
├── README.md # this file
└── .gitignore
components-html and components-web are component libraries: each registers itself with an azDesign.library manifest in its package.json (see the library addon's README). components-react-bootstrap provides contributor documentation only; its source package is added with its implementation work.
| Package | Path | Purpose |
|---|---|---|
@az-digital/tokens |
packages/tokens/ |
Source token definitions and Style Dictionary build pipeline |
@az-digital/contracts |
packages/contracts/ |
Component contracts: each component's parts, and the token or value that sets each part's design properties (README) |
@az-digital/storybook-addon-tokens |
packages/storybook-addon-tokens/ |
Storybook addon: token doc blocks and the Tokens tab, driven by the Style Dictionary config (README) |
@az-digital/storybook-addon-libraries |
packages/storybook-addon-libraries/ |
Storybook addon: the Library toolbar, which switches component stories between registered libraries, and the contract a library meets to register (README) |
@az-digital/components-html |
packages/components-html/ |
Arizona Bootstrap markup for each component, shown in Storybook; never released (README) |
@az-digital/components-web |
packages/components-web/ |
Custom elements for each component, in preview (README) |
@az-digital/storybook |
packages/storybook/ |
Storybook UI for token review and documentation |
- Node.js 20+
- npm 10+
# from the repo root
npm install
# start Storybook
npm run dev:storybookStorybook will be available at http://localhost:6006.
All scripts can be run from the repo root:
| Command | Description |
|---|---|
npm run dev:storybook |
Start the Storybook development server |
npm run build:storybook |
Build Storybook for production output |
npm run build:tokens |
Build token output using Style Dictionary |
npm run build:contracts |
Check the component contracts against the tokens, and write their data for docs and contract checks |
npm run test:storybook |
Run the Storybook package tests, including every story in Chromium and any contract checks |
npm run lint |
Run ESLint for every package |
npm run lint:storybook |
Run ESLint for the Storybook package |
npm run typecheck |
Type-check every package with TypeScript |
npm run build:all |
Build token output, check the contracts, and build Storybook |
- Update token values in
packages/tokens/tokens.json. - Run the token build script:
npm run build:tokens- If a component's tokens changed, update its contract in
packages/contracts/contracts/and check it:
npm run build:contracts- Review the generated token catalog in Storybook.
npm run build:tokens runs Style Dictionary (packages/tokens/style-dictionary.config.mjs) against tokens.json and writes generated output to packages/tokens/dist/. The output is committed, so rebuild and commit it with every token change:
tokens.css— CSS custom properties (e.g.--az-color-brand-blue: #0c234b;) for stylesheets.tokens.scss— Sass variables (e.g.$az-color-brand-blue: #0c234b;) for Sass-based builds.tokens.vars.js/tokens.vars.d.ts— a JS/TS module exporting the same tokens asvar(...)reference strings (e.g.az.color.brand.blue→"var(--az-color-brand-blue)"), so code can reference the generated CSS variable names instead of reconstructing them.
In tokens.css and tokens.scss, a token that aliases another is written as a reference to it (outputReferences), not a copied value: a token whose $value is {color.brand.red} comes out as var(--az-color-brand-red) (or $az-color-brand-red). The alias chain from tokens.json survives into the output, and overriding one variable updates everything built on it.
tokens.json is written the way Tokens Studio reads it, since it's also Tokens Studio's sync file. The top-level az is its token set, so references leave it out ({color.brand.red}); the Style Dictionary config adds it back before resolving them, so every token keeps its az. name in the build, the contracts and Storybook. Sizes are strings ("8px") and font families are one comma-separated string: Tokens Studio doesn't read DTCG 2025.10's { "value": 8, "unit": "px" } objects or font lists yet.
Never edit files in dist/ directly — they're regenerated on every token build.
The published @az-digital/tokens package includes the source tokens.json alongside dist/, for tools that consume DTCG tokens directly (Figma / Tokens Studio, or another team's own Style Dictionary build): @az-digital/tokens/tokens.json. Generated files are imported by path, e.g. @az-digital/tokens/dist/tokens.css.
A component's contract (packages/contracts/contracts/<component>.contract.json) records its anatomy, independent of any platform: the parts it's made of, and what sets each part's design properties at rest, in its states (hover, focus-visible…) and from its breakpoints: a token from tokens.json, or the component's own value.
The contract points each part at the token it uses, named the way the Naming page (Foundations › Tokens › Naming) describes. What's specific to one component, such as its sizes and timings, is a value in its contract, written like a DTCG token with a description of what it's for. Contracts generate nothing for any platform: each implementation writes those values its own way, and a contract check renders the implementation and fails if it differs from its contract.
npm run build:contracts refuses a contract, naming the problem, when it doesn't match contract.schema.json, references a token that doesn't exist, or leaves one of its component's own tokens (az.component.<component>.*) unused. It also flags component tokens that only point at another token, so they can be removed. Component docs pages show the contract as an Anatomy table. See the contracts README.
The Storybook package renders the design token catalog, groups nested token values, and provides a review surface for design decisions and naming conventions.
It also includes small validation tests covering token grouping and metadata parsing so token structure changes are caught early.
The token UI (token tables, the token details drawer with its alias tree, the component token index, and the Tokens tab) comes from @az-digital/storybook-addon-tokens. The brand color swatches on the Tokens page (packages/storybook/stories/Primary/Foundations/Tokens/ColorSwatchGrid.tsx) are this site's own, and embed the addon's token pill. It reads packages/tokens/style-dictionary.config.mjs, so the details for each token show exactly what each output file derives from it. See its README.
Each published release is hosted on digital.arizona.edu by version:
https://digital.arizona.edu/design/<version>/— every release, e.g./design/0.0.1/https://digital.arizona.edu/design/latest/— the highest stable release (prereleases such as1.0.0-rc.1never become latest);/design/redirects here
To publish, bump version in package.json (keep the workspace packages in sync), merge to main, then publish a GitHub release tagged v<version> (e.g. v0.0.1). .github/workflows/publish-docs-site.yml checks that the tag matches package.json and sends an az_design_release event to az-digital/digital.arizona.edu, which verifies the tag, builds that commit (npm run build:all), and commits the output to docs/design/<version>/.
Unreleased work on main and pull requests is only on the review site.
Storybook styles its components with Arizona Bootstrap compiled from its own Sass source, installed from GitHub at a release's tag, now v5.3.0 (packages/storybook/.storybook/arizona-bootstrap.scss). Nothing in this repo overrides Arizona Bootstrap's values or adds CSS rules to it. When a contract needs Arizona Bootstrap to change, the change is a patch to its source that its maintainers can apply as a pull request.
patch-package keeps each patch in patches/arizona-bootstrap+<version>+<number>+<name>.patch, one per change, and the root postinstall script applies them in order on every npm install. <version> is the version in Arizona Bootstrap's package.json: the release the patch was made against.
To make a patch:
- Edit the file under
node_modules/arizona-bootstrap/scss/. Write the change the way Arizona Bootstrap would, with its own variables ($gray-200, not$az-color-brand-gray-200), so it can be applied as it is. - From the repo root, run
npx patch-package arizona-bootstrap --append <name>, where<name>says what the change is, such aswhite-buttons-hover-and-active. To change the newest patch instead, runnpx patch-package arizona-bootstrapwithout--append. - Restart Storybook and check the component.
- Commit the patch with the contract change it supports. In the pull request, say which Arizona Bootstrap issue or pull request it's for.
Each patch is a diff of Arizona Bootstrap's own files, so a maintainer applies it to a branch from that release with:
git apply -p3 arizona-bootstrap+5.3.0+001+white-buttons-hover-and-active.patchOnce an Arizona Bootstrap release includes a change, point packages/storybook/package.json at that release's tag, run npm install, and delete the patch. npm install fails if a patch no longer applies to the new release: redo the change on the new source and make the patch again, with the new version in its name.
The background images that Arizona Bootstrap's Sass refers to (url("img/...")) don't load in Storybook: the package ships them only beside its released CSS, not its Sass.
Storybook includes @storybook/addon-mcp, which exposes a local Model Context Protocol server while the Storybook dev server is running. See AGENTS.md for how coding agents should use it.
This project follows the broader design token ecosystem and aligns with the Design Tokens Technical Reports, including the specification work that informs structured token definitions and interoperability.
- Tokens are authored in a structured JSON format and stored in
packages/tokens/tokens.json. - The token package builds output through Style Dictionary.
- Component contracts say which token or value sets each part of a component, and a check keeps them in step with the tokens.
- Storybook reads the token source and renders grouped token cards for review.
- The package test suite verifies that nested token paths are flattened and grouped correctly.
When updating tokens or Storybook behavior:
- Keep the token structure intentional and consistent.
- Use Storybook to review the rendered output.
- Run the relevant tests before shipping changes.
This repo is intended to support both token authoring and visual review in one place, with Storybook acting as the primary design review surface.
When adding a component or implementation package, follow Components → Contributing. Libraries register themselves with the library addon, and the Components Overview renders each registered library's README directly, so keep the relevant HTML, React Bootstrap or Web Components guide current. Agent-specific workflow is in design-system-component/SKILL.md.
Use the Storybook token pages to find assets, import tokens, or contribute changes:
- Tokens > Downloads
- Tokens > How to Use
- Tokens > Contributing