---
name: privy-design-system
description: Build or update application UI using this shared Privy design system. Use when adopting its branding, tokens or catalogue patterns in another project, or maintaining the shared system and its consumer documentation.
---

# Privy Design System

Use the live design-system checkout as the authority. This skill is guidance for implementing UI in the target application's framework, not a runtime component library.

## Locate the current source

Run `python3 scripts/resolve_source.py --check` from this skill's directory (or use the script's absolute path). It follows the installed skill symlink and prints absolute source paths and the current source fingerprint. From a copied skill, pass `--source /path/to/design-system`. The complete checkout must be accessible; this skill does not bundle independent copies of fonts, components or branding.

If the check reports drift, inspect the listed changes. For a shared-system maintenance task, finish the relevant documentation and synchronization below. For a consumer-only task, report that the source is unsynchronized and distinguish inspected source from validated guidance; do not run `--note` just to bless someone else's changes. If the source is unavailable, identify the missing checkout instead of inventing tokens or assets.

Read the target project's `AGENTS.md` and design documentation, then the source's `GUIDELINES.md` for the affected pattern. Use [references/catalog.md](references/catalog.md) to locate relevant section IDs, guidance headings and source files. Read only the relevant HTML specimen, stylesheet, script and state requirements; do not load all domain guides. For assets use the source `assets/` directory, including original Privy logos and licensed DM Sans fonts.

## Implement in a consuming application

- Map semantic roles from `tokens.json` into the application's established styling system. Keep light/dark aliases, DM Sans, original logo assets and documented dimensions/states. Do not independently approximate token values.
- Adapt the actual specimen's behavior to the existing framework, routing and component architecture. Catalogue scripts, global resets, synthetic data and local-only simulations are not a production SDK. Import only the needed assets/styles after checking collisions and asset URLs.
- Preserve accessible names, focus restoration, keyboard behavior, loading/error/disabled states, narrow layouts and reduced motion relevant to the pattern. For example, copy the logout confirmation's cancellation contract, not its demo session result; distinguish HTTP errors from offline state; retain named links in collapsed sidebars.
- Keep the user's requested product scope. Do not rebrand unrelated screens, invent backend integrations or rewrite the shared source merely to accommodate a local exception. Catalogue UI and companion documentation are English; preserve the consuming application's established localization unless asked to change it.
- Update the consumer's existing design documentation in the same change. Record the source fingerprint from the resolver, adopted patterns, framework mappings and any intentional deviations. This records adoption; a new source fingerprint does not automatically migrate application code.
- Verify the affected interactions in both themes, keyboard navigation and narrow/wide viewports using the consumer's own checks. Report actual coverage and remaining limitations without claiming complete accessibility or production readiness.

## Maintain the shared design system

Follow the source `AGENTS.md`. Change tokens in `tokens.json`; update the relevant `GUIDELINES.md` rules and applicable consumer documentation with component changes. Update `components.json` and `states.json` when coverage or behavior changes.

From the source root, run:

```sh
python3 scripts/sync.py --note "Describe the specific change and reason"
python3 scripts/sync.py --check
```

The same command regenerates this skill's catalogue and source fingerprint as well as normal documentation. Do not hand-edit `references/catalog.md` or `references/source-state.json`. Edit this entrypoint only when the reuse workflow changes. Installed symlinks read the updated skill directly; no background watcher, remote publication or automatic consumer-code migration is implied.