# Adoption guide

The design system is intended to reduce repeated visual decisions without coupling product workflows.

## Stage 1: Reference

Use the reference site when creating or reviewing shared interface elements. Match the documented anatomy, states, dimensions, and semantic colors. Keep domain behavior in the application.

## Stage 2: Tokens

Import `@jprl/design-tokens` and replace duplicated foundation values with semantic variables. Adopt foundations before changing individual pages.

Recommended order:

1. typography and canvas;
2. content width and page panels;
3. controls and focus behavior;
4. statuses, identity, and tags;
5. navigation shell, Navigation switcher, and authentication-shell presentation;
6. standard and searchable selection behavior;
7. form-section cards and save boundaries;
8. registry tables, pagination, and collection states;
9. record-detail lists, breadcrumbs, and tabs;
10. action menus, dialogs, and record-lifecycle sections.

## Stage 3: Components

Extract a shared Vue primitive only when:

- it is used by at least two products;
- its API and behavior are already stable;
- it does not contain routes, permissions, tenancy, or product terminology;
- supported Tailwind and UI-library versions can consume it safely;
- keyboard, focus, disabled, loading, and responsive states are covered.

Until those conditions are met, treat examples as visual contracts rather than copy-and-paste production implementations.

## Exceptions

An application can diverge for a product need. Document the reason near the implementation and avoid changing a shared token to solve one product-specific case.