# Getting started

Build consistent interfaces with the Privy application design system. Start with the [HTML guide](getting-started.html), [component catalogue](index.html), or a [complete page example](index.html#page-examples).

## 1. Open the catalogue

Open `index.html` directly in a browser. No build or installation is required. Local assets work offline; DM Sans is bundled locally, including normal and italic variable fonts; the system font is a loading/error fallback.

For camera features or a local HTTP preview:

```sh
cd /Users/guritnoadisaputra/Documents/gas/design-system
python3 -m http.server 8080 --bind 127.0.0.1
```

Open `http://localhost:8080`. Camera permission is requested only after you select Enable camera. No business data is sent.

## 2. Find a pattern

Use the seven grouped menus in the top navbar, or press `/` outside an input to search the catalogue. On mobile, open the component-groups button to reveal the menu. Start with foundations, buttons, forms, and navigation. Application patterns include the navbar, member lists, searchable dropdowns, drawers, tables, upload, date ranges, and skeletons.

Inspect [Enterprise Account](examples/enterprise.html), [Knowledge & Macros](examples/knowledge.html), [Teams](examples/teams.html), and [Support Inbox](examples/support.html) to see patterns working together.

### Preview mobile and tablet layouts

Open [Responsive preview](responsive-preview.html), or select the phone icon in the catalogue header. Choose the catalogue or an example page, then select a screen-size preset. Rotate switches portrait/landscape; Width and Height plus Apply size support custom dimensions. Use Theme for light/dark and Zoom to fit the available space or inspect at 100%. Scroll and use controls inside the frame. Open page opens the chosen page separately. For touch and software-keyboard behavior, also use browser device tools or a real device.

## 3. Reuse the design

Read [GUIDELINES.md](GUIDELINES.md). Use semantic tokens from `tokens.json`, preserve the original logo and DM Sans typography, and check both themes. Implement the required interactions in your application's framework. Review global CSS collisions before importing styles; demo scripts are not a production SDK.

[PERSONA_COVERAGE.md](PERSONA_COVERAGE.md) maps the official Persona reference to local examples and explains boundaries. PDF placement, signature previews, upload progress, and connection states are local demonstrations, not real backend integrations.

## 4. Keep documentation synchronized

Update the relevant specimen and guideline together, then run:

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

Edit `tokens.json`, `components.json`, `states.json`, and `persona-coverage.json` as appropriate. Do not hand-edit generated token CSS, inventory data, state tables, or coverage tables.

### Use the skill in another application

Open the catalogue account menu and select **Download Skill** for a skill-only ZIP. Extract its `privy-design-system` folder into the target agent’s skill directory. The ZIP excludes application code and design-system assets. Keep the shared source accessible; from the extracted skill, run `python3 scripts/resolve_source.py --source /path/to/design-system --check`. The normal sync command rebuilds the ZIP; verify it with `python3 scripts/package_skill.py --check`. Downloaded packages are snapshots.

From this checkout, install and verify the shared skill:

```sh
python3 scripts/install_skill.py
python3 scripts/install_skill.py --check
python3 skills/privy-design-system/scripts/resolve_source.py --check
npm run test:skill
```

The installer creates `~/.agents/skills/privy-design-system` as a symlink to this repository's maintained skill. It refuses to overwrite an unrelated existing skill. For a project-scoped installation instead, use `python3 scripts/install_skill.py --skills-dir /path/to/app/.agents/skills`. Avoid installing the same skill in both scopes. User-level skills and symlink discovery follow the [official skill documentation](https://learn.chatgpt.com/docs/build-skills).

In the consuming project's Codex session, use a prompt such as:

```text
Use $privy-design-system to add a collapsible sidebar to this application.
Preserve its framework, routing and localization, and update its design documentation.
```

If the skill does not appear, restart the Codex session. Every normal `scripts/sync.py --note` operation also refreshes the skill catalogue and source fingerprint; `--check` rejects drift. There is no separate skill-update step or background watcher. Linked skills use the current checkout, while adopting code changes into a consuming app remains a separate requested task.

Keep the entire checkout accessible. For another machine, copy or clone this repository and run its installer there; a standalone copied skill can resolve that checkout with `scripts/resolve_source.py --source /path/to/design-system --check`. The skill is an implementation guide, not a UI package or a remotely published plugin.

## 5. Validate your change

For optional development checks:

```sh
npm ci
npx playwright install chromium firefox webkit
npm test
npm run test:all
```

Check keyboard behavior, narrow/wide layouts, both themes, and reduced motion. See [VALIDATION.md](VALIDATION.md) for tested scope and manual checks. The included GitLab CI file is a configuration template; it has not been activated on a remote repository.

For dashboard work, start with [Dashboard Overview](examples/dashboard.html) and the [dashboard guide](DASHBOARD_GUIDE.md). Choose the relevant KPI, chart, progress, activity, status, or action pattern instead of treating every card as a metric counter.

For analytics and downloads, use [Reporting & downloads](index.html#reporting). It demonstrates eight chart types with tables and filter-consistent exports. Print / Save as PDF uses the browser print dialog. Read the [reporting contract](DASHBOARD_GUIDE.md#reporting-workspace) before connecting real data.

## Search inside a select

Click a select field to open its custom list, then type to filter options. Arrow keys move through results, Enter selects, and Escape cancels without changing the value. This works in the catalogue, responsive-preview toolbar and full-page examples. Group headings and unavailable options remain visible.

For dashboard forms, open [Dashboard input patterns](index.html#dashboard-inputs) to try formatted amounts, international phone formatting, URL checks, numeric ranges, removable tags and clearable search. Values and validation are local previews.

## Complex forms and content editors

Open [Advanced form patterns](index.html#form-patterns) for repeatable contacts, channel-specific fields, dependent assignment, selection cards, ID checks, number steppers, reviewed saves and sticky actions. Switch Comfortable/Compact or expand **Try error states** to exercise lookup/save failure and retry.

Open [HTML & JSON editor](index.html#code-editors) for the dark code-field style, Code/Preview tabs, typed variables, sample data, JSON formatting and static preview. All examples stay local; preview strips interactive/remote content. Both sections are available in the Forms menu and component search. The catalogue now has 62 sections across seven groups.

Run targeted checks with `node scripts/form-patterns-check.mjs` and `node scripts/code-editors-check.mjs`; both are included in `npm test`.

## Search and recruitment patterns

The catalogue has **74 sections and seven full-page examples**. [Search with leading filters](index.html#filtered-search) adds status and field-scoped search with a left custom dropdown, combined results, Clear and Reset all.

[Recruitment workspace](examples/recruitment.html) combines scoped candidates, KPI definitions, stage pipeline, profile drawer and WIB interviews. [Job openings & forms](index.html#recruitment-jobs) and [Talent pool & saved pipeline](index.html#recruitment-talent) demonstrate publication, consent and follow-up rules. Read [RECRUITMENT_GUIDE.md](RECRUITMENT_GUIDE.md) before integrating. The page is available in Responsive preview. All values and actions are synthetic/local.

Run `node scripts/filtered-search-check.mjs` and `node scripts/recruitment-check.mjs` for focused verification; both are included in `npm test`.

## EBS table and heading patterns

The catalogue contains **74 sections**. Open [Table pagination & remote states](index.html#table-pagination) for Rows per page, result ranges, loading/error/empty states and simulated server filtering/sorting. Open [Compact page-heading summaries](index.html#heading-summaries) for labeled role counts and unavailable/loading values. Both are in Data & reports.

[FRAMEWORK_TABLE_GUIDE.md](FRAMEWORK_TABLE_GUIDE.md) maps the inspected Vue/Persona table wrapper, explains remote versus local pagination and records application adoption notes. Run `node scripts/ebs-patterns-check.mjs` for the targeted interaction checks; it is included in `npm test`.

## Contract lifecycle management

[Open the CLM workspace](examples/clm.html) for contract requests, repository/reporting, document versions, comments, approvals, signing preparation, obligations, renewal and amendments. Five catalogue sections cover fourteen patterns; see [CLM_GUIDE.md](CLM_GUIDE.md) for rules and demo limits. The seventh full-page example is available in Responsive preview. All actions are local and synthetic. Run `node scripts/clm-check.mjs` for focused checks.

## Bot messages and request recovery

The catalogue now includes 74 sections. [Bot messages & request recovery](index.html#bot-patterns) shows readable history for disabled bots, one-time secret handling, same-review recovery and Retry-After feedback. All specimen operations are local fixtures. The consuming Hermod application implements these patterns against the Broadcast and OA Bot contracts.