Design System Integration

The @arda-cards/design-system package (built in ux-prototype) is consumed by arda-frontend-app and any other downstream applications that import Arda UI primitives. Because design-system changes ripple into every consumer, the team supports several integration workflows depending on how tightly the change in the design system needs to be coordinated with the change in the consuming app.

This section catalogs the supported workflows, when to pick each one, and the contracts each side of the integration must honor.

Glossary

Term	Meaning
Stable version	A standard semver release like 4.12.0. Published from main of ux-prototype, tagged latest in GitHub Packages.
Pre-release version	A semver pre-release entry in CHANGELOG.md, format x.y.z-<author>-<id> (e.g. 4.12.0-alice-FD42).
Preview	The actual published artifact corresponding to a pre-release entry, e.g. @arda-cards/design-system@4.12.0-alice-FD42-3. The trailing -3 is github.run_number, ensuring uniqueness per push.
dist-tag	npm distribution tag derived from the pre-release entry (everything after the first -). Example: 4.12.0-alice-FD42-3 is published with --tag alice-FD42. The latest dist-tag is reserved for stable.
Series	All preview versions sharing a dist-tag, i.e. all preview versions for the same <author>-<id> pair.
Cleanup	The daily job that removes obsolete preview versions from GitHub Packages. See Cleanup contract.

Decision tree

Is the design-system change already merged to main?
├── YES → Workflow 1: Canonical release
│         (Consumer bumps to the new stable version)
│
└── NO  → Does the consumer need to validate against the design-system change?
          ├── NO  → Continue developing in ux-prototype only.
          │
          └── YES → How tightly do the two repos need to iterate?
                    ├── Loose (test against published artifact)  → Workflow 2: Preview publish
                    ├── Lockstep (consumer PR validates the preview in CI) → Workflow A: Coordinated multi-PR
                    └── Tight (rapid two-sided code editing)    → Workflow 3: Local side-by-side

Workflows

#	Workflow	When to use
1	Canonical release	Default. The design-system team ships a new stable version on its own cadence; consumers bump on theirs.
2	Preview publish	Consumer wants to validate against an in-progress design-system change without local linking.
A	Coordinated multi-PR	The change spans both repos and both PRs need to be open simultaneously and validated by CI.
3	Local side-by-side	Tight iteration with frequent two-sided code edits. Highest velocity, lowest CI fidelity.

Reference

The reference page covers cross-cutting concerns:

• Auth and tokens — GitHub PAT setup for consumers, CI secrets
• Version and tag conventions — semver, dist-tag rules, naming
• Cleanup contract — when previews are deleted and how to avoid breakage

Mirror in ux-prototype

A brief operational summary lives in ux-prototype/src/docs/workflows/preview-publishing.mdx (visible inside the Storybook docs). That page links here for the full contract.