@arbor-education/design-system.components

The React component library for the Arbor design system. Components are built with TypeScript, styled with Sass, developed in Storybook, and tested with Vitest. This library serves millions of students and educators across the UK — handle with care.

Storybook

The component library is documented and previewed in Storybook.

Production Storybook (built on every push to main): https://main--68c3f2a09d95b22aa55a11e8.chromatic.com/

Per-PR Storybook previews: every pull request automatically triggers a Chromatic build. Once it completes, a bot will comment on your PR with links to both the Storybook preview and the Chromatic visual diff for that branch.

Consuming the package

If you're integrating this library into a consumer project, check out the guide on Confluence:

Consuming the design system NPM package

Local setup

Prerequisites

• nvm for Node version management
• yarn for package management

Steps

nvm use
yarn install
yarn storybook

Storybook will build and open in your browser with hot reloading ready for development.

Commands

Development

| Command | Description | |---------|-------------| | yarn storybook | Start Storybook dev server on port 6006 | | yarn watch | Watch mode — rebuilds and pushes to Yalc consumers on changes |

Building

| Command | Description | |---------|-------------| | yarn build | Full production build (TypeScript + tsc-alias + Sass) | | yarn tsc | TypeScript compilation only | | yarn check-types | Type check without emitting files |

Testing

| Command | Description | |---------|-------------| | yarn test | Run Vitest in watch mode | | yarn test:coverage | Run tests once with coverage report |

Linting

| Command | Description | |---------|-------------| | yarn style-lint | Lint SCSS files with stylelint |

ESLint runs automatically on staged TypeScript files via lint-staged on git commit.

Creating a new component

Use the scaffolding script to generate all necessary files for a new component:

yarn create-component <ComponentName>

This creates Component.tsx, Component.test.tsx, Component.stories.tsx, and component.scss, and automatically adds the exports to src/index.ts and src/index.scss.

Local development with a consumer project

This library uses Yalc for local linking.

First time setup — install Yalc globally:

npm i yalc -g

Link the library to a consumer project:

# In this repo — build and publish to the local Yalc store
yarn build
yalc publish

# In the consumer project — add the local package
yalc add @arbor-education/design-system.components

For active development with hot updates, use watch mode instead:

# In this repo — automatically rebuilds and pushes to Yalc on file changes
yarn watch

Version management

This library uses Changesets for versioning and changelog generation.

If your change affects the public API (new components, changed props, removed exports), create a changeset before opening your PR:

yarn changeset

Contributing

Before opening a PR, please read CONTRIBUTING.md. Key points:

• One PR, one thing — if the title needs "and" or "also", split it
• Keep meaningful code diffs under 400 lines
• All tests must pass (yarn test:coverage)
• All type checks must pass (yarn check-types)
• Use the PR template — fill in every section