# Get started

The ACRM Design System is the single source of truth for every CRM application and module.
The canon lives in this repository; the site you are reading renders it directly.

## For developers

1. Your repo keeps a **read-only mirror** of the canon (ACRM: `packages/ui/reference/screens/`). Never edit it by hand.
2. Refresh the mirror with a normal MR: `tools/refresh-mirror.sh <mirror-dir>` — downloads `/ds/_archive.tar.gz`, skips `screenshots/ uploads/ candidates/`, writes `MIRROR-VERSION.json` with the canon HEAD.
3. **Port 1:1**: same class names, values become tokens. Fidelity is measured by `ds:sync-check`, usage of canonical classes by `ds:validate` (see `acrm/acrm` → `.claude/skills/datamart-ds/`, `docs/DESIGN-SYNC.md`).
4. Before building anything, **look for the pattern in the canon** (search above, or grep classes). If it exists, use it. If not → propose a candidate; never a local variant.
5. **Visual baselines** (Ladle catalogue) are photographed only through `.e2e-pw` in the repo root, in the same Playwright version as the CI image `mcr.microsoft.com/playwright:v1.51.1-noble`: `npm install --prefix .e2e-pw playwright@1.51.1 pixelmatch@5.3.0 pngjs@7.0.0` and `npx --prefix .e2e-pw playwright install chromium`. Never through `/root/visual-tests` — an older Chromium draws glyph edges differently and every story shows a false pixel diff. Baselines are regenerated only in that environment, never as a by-product of a token or component MR.

## For designers

- Read the [Rules](/ds/rules) first — containment budget, one accent per screen, sentence case.
- Every card is a live HTML render; open it standalone (↗) to measure with the picker. The picker records the card name and canon version from the page title.
- New element → [Candidates](/ds/candidates): a card plus a short README (purpose, why the canon is not enough, measured values). The Art Director decides.

## For AI agents

- `/ds/_index.json` — machine-readable catalog (cards, categories, implementation per repo).
- `/ds/RULES.md` — binding rules. `/ds/_version.json` — canon HEAD. `/ds/_archive.tar.gz` — snapshot.
- Read cards fresh from the canon; never from memory or from a repo mirror.

## Ground rules

- The canon root is edited only by the Art Director. Other teams contribute through `candidates/`.
- An approved design is implemented exactly (measured, not estimated). Deviations are announced beforehand.
- A new canon **replaces**, it does not add: the old element disappears when the new one lands.