# Use Design System

> Uses shared UI package primitives instead of hand-rolled markup, greps the source to verify class and component names, and sets page metadata on every page. Use when authoring UI in a repo with a shared UI package (e.g. @synthaembed/ui-fleet), when adding pages or components, or when unsure of a design token or class name.

- Skill: `jcdavis131/use-design-system` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add jcdavis131/use-design-system`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jcdavis131/use-design-system/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: jcdavis131 (https://skillmd.com/u/jcdavis131)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/jcdavis131/use-design-system

---


# Use Design System

A shared UI package encodes the design system. Primitives give cross-site consistency; hand-rolled markup drifts.

## The move

1. **Find the shared package** — `packages/ui-*`, `@repo/ui`, `@*/ui-fleet`. Read exports.
2. **Use primitives, not raw markup** — PageHeader, Card, Button from the package; raw `<div>` only when no primitive fits.
3. **Verify names in source** — grep before trusting memory:
   ```bash
   grep -n "bh-btn\|bh-card" packages/ui-fleet/src/components.css | head -6
   ```
4. **Set page metadata** — every page exports `metadata` (title for SEO/share cards).

## When a primitive doesn't fit

Closest primitive + constraints; add to shared package if 2+ sites need it (`lane-discipline`); one-off hand-roll with a comment explaining why.

## Extended patterns

Shared-vs-local decision, build order, SDK domain imports, barrel exports: [reference.md](reference.md)

## Anti-patterns

Hand-rolling for speed; trusting memory for class names; bypassing shared package "just once"; site-local instead of shared when reusable.

## Pair with

- `match-conventions` · `validate-gate` · `lane-discipline`