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 [email protected] [email protected] [email protected] 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 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: 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.

Source: site/get-started.md · GitLab