[zoran995]

What this PR does

Adds the Terria design system: React components, icons and design tokens, with Storybook and visual tests. TerriaJS doesn't use it yet; we'll migrate gradually behind a feature flag.

Automated Copybara sync. Merge with a normal merge commit.

Packages

Package	Where	What it is	Published?
@terria/design-system	packages/design-system/components	67 React components built on React Aria, with their CSS and tokens	No, private (see below)
@terria/design-system-icons	packages/design-system/icons	Icons as React components and an SVG sprite, generated from Figma	No, private
@terria/design-system-storybook	packages/design-system/storybook	Storybook with every component's stories, in light and dark mode	No, private

The packages are private for now. TerriaJS will carry them inside its own npm package (bundleDependencies) instead of publishing them separately.

Design tokens

The tokens (packages/design-system/components/src/css/tokens.css) are generated automatically from the Figma variables. Don't edit tokens.css by hand: token changes come from Figma.

Dependencies

• react-aria, react-aria-components, react-stately, @internationalized/date and @react-aria/* are peer dependencies with ranges, so an app has one copy of each. The design system pins them in devDependencies for its own builds and tests.
• React 18 and 19 are supported.
• The Inter font (@fontsource-variable/inter) is a normal dependency.

Using it in an app

import "@terria/design-system/layers.css";
import "@terria/design-system/tokens.css";
import "@terria/design-system/reset.css";
import "@terria/design-system/base.css";
import "@terria/design-system/fonts.css";
import { Button } from "@terria/design-system";

All CSS is in cascade layers (terria-ds.*). Components are styled through data-tds attributes, so an app's own className never clashes. Components' own strings (like "Close") are in English, and an app can translate them with LocalizedStringsProvider.

Running it

From the repo root:

What	Command
Storybook (localhost:6006)	pnpm storybook
Build Storybook	pnpm build-storybook
Build the packages	pnpm --filter "@terria/design-system*" -r build
Rebuild while you work	pnpm --filter @terria/design-system dev
Tests (Vitest, in Chromium)	pnpm --filter "@terria/design-system*" -r test
Type-check and lint	pnpm --filter "@terria/design-system*" -r typecheck / -r lint

The first test run needs Playwright's browser: pnpm --filter @terria/design-system exec playwright install chromium.

Visual tests

Every component has screenshot tests (*.visual.tsx) for each state, in both themes.

• Locally: pnpm --filter @terria/design-system test:visual -u takes the references; pnpm --filter @terria/design-system test:visual compares.
• On a PR: a maintainer comments /terria-bot visual-test. It compares the PR's components with the base branch's and posts the differences on the PR. Comment again after new commits.

CI

• design-system-ci.yml: formats, lints, type-checks, runs the tests and builds Storybook. It runs on PRs that touch the design system.
• design-system-visual*.yml: the /terria-bot visual-test command, the comparison and the clean-up of its images.
• design-system-chromatic.yml is off until we have a Chromatic account; it can only be started by hand.

Test me

1. pnpm install
2. pnpm storybook and open http://localhost:6006. Check a few components in light and dark (toolbar toggle).
3. pnpm --filter "@terria/design-system*" -r build && pnpm --filter "@terria/design-system*" -r test

Checklist

• There are unit tests to verify my changes are correct or unit tests aren't applicable (if so, write quick reason why unit tests don't exist)
• I've updated relevant documentation in doc/.
• I've updated CHANGES.md with what I changed.
• I've provided instructions in the PR description on how to test this PR.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ zoran995
❌ Terria Bot

---

Terria Bot seems not to be a GitHub user. You need a GitHub account to be able to sign the CLA. If you have already a GitHub account, please add the email address used for this commit to your account.
_{You have signed the CLA already but the status is still pending? Let us recheck it.}