# Privy Application Design System

A standalone HTML catalogue and implementation guide aligned with `official-account-hermod`.

**Start here:** [Getting started](getting-started.html) · [Component catalogue](index.html) · [Guidelines](GUIDELINES.md)

## Preview

Open `index.html` directly. No installation or build is required. Assets are local; DM Sans is bundled locally, including normal and italic variable fonts; the system font is a loading/error fallback.

For a loopback HTTP preview:

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

Open `http://localhost:8080`. The server serves static files only. Camera access depends on browser permission/security context and begins only after an explicit action.

## Explore

- [Application navbar](index.html#app-navbar), [Member lists](index.html#member-lists), and [Skeleton & shimmer](index.html#skeletons).
- Full pages: [Enterprise Account](examples/enterprise.html), [Knowledge & Macros](examples/knowledge.html), [Teams](examples/teams.html), and [Support Inbox](examples/support.html).
- [Persona coverage](PERSONA_COVERAGE.md): all 80 reference entries, local counterparts, and implementation boundaries.
- [State matrix](STATE_MATRIX.md), [validation results](VALIDATION.md), and [changelog](CHANGELOG.md).

All catalogue interface copy and companion documentation use English. Proper names and product terms are preserved. These are local UI demonstrations; no account creation, message delivery, real session handling, or digital signing is performed.

## Files

| File | Purpose |
| --- | --- |
| `index.html` | Interactive component catalogue. |
| `getting-started.html`, `GETTING_STARTED.md` | First-use guide in HTML and Markdown. |
| `examples/` | Five standalone application-page examples. |
| `tokens.json` | Canonical light/dark colors, dimensions, and typography metadata. |
| `tokens.css` | Generated CSS tokens. |
| `design-system.css`, `advanced.css`, `persona-patterns.css` | Foundations and companion pattern styles. |
| `app.js`, `advanced.js`, `persona-patterns.js` | Local demonstration behavior. |
| `components.json`, `catalog-data.js` | Section metadata and generated HTML inventory. |
| `states.json`, `STATE_MATRIX.md` | State requirements and their generated table. |
| `persona-coverage.json`, `PERSONA_COVERAGE.md` | Reference mappings and their generated table. |
| `GUIDELINES.md`, `AGENTS.md` | Usage and mandatory maintenance instructions. |
| `scripts/sync.py`, `sync-state.json` | Documentation generation and file fingerprints. |
| `skills/privy-design-system/` | Shared skill, live-source resolver and generated component references. |
| `scripts/sync_skill.py`, `scripts/install_skill.py` | Skill-reference generation and non-overwriting symlink installation. |
| `scripts/*-check.mjs` | Browser and accessibility regression checks. |
| `package.json`, `package-lock.json` | Locked optional development dependencies. |
| `.gitlab-ci.yml` | Standalone CI configuration. |
| `assets/` | Original project branding and local preview assets. |

## Make a change

Update the affected specimen and the relevant rule in `GUIDELINES.md`, then run:

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

The generator updates tokens, inventories, state/coverage tables, revision notes, changelog, skill references and fingerprints. It cannot infer behavior or write explanatory guidelines for you. No background process changes your files.

## Use the shared skill in another application

Run `python3 scripts/install_skill.py` to link [privy-design-system](skills/privy-design-system/SKILL.md) into your local user skill directory. In another project's Codex session, invoke `$privy-design-system` and describe the UI to implement. The skill reads the live source, preserves framework boundaries and records adoption in the consumer's design documentation.

The normal sync workflow updates the skill references automatically. Linked installations share those changes; it does not automatically rewrite consumer code. See [Getting started](GETTING_STARTED.md#use-the-skill-in-another-application) for setup, verification and use on another machine.

The original product implementation is in `../official-account-hermod/app/assets/styles/main.css` and related Vue components. The corporate proposal remains in `../official-account-hermod/docs/design-system/PRIVY_DESIGN_SYSTEM.md`; this kit follows the actual application's DM Sans and patterns without rewriting that proposal.

## Development checks

```sh
npm ci
npx playwright install chromium firefox webkit
python3 scripts/sync.py --check
npm test
npm run test:all
```

`DS_BROWSER` selects the browser engine. `DS_PLAYWRIGHT_MODULE` can override Playwright's location; `DS_CHROMIUM_EXECUTABLE` can point to a local Chromium binary. Screenshots/reports go to a temporary directory or `DS_SCREENSHOT_DIR`. Advanced checks use a temporary loopback server; basic checks also cover opening HTML directly.

The GitLab CI configuration gates browser jobs on documentation synchronization. It runs only after this folder is placed in a repository with CI enabled. No remote pipeline or branch protection has been configured, and the Hermod runner is not assumed to have this sibling directory.

## Dashboard and workspace additions

Use [Dashboard Overview](examples/dashboard.html) for a complete composition and [DASHBOARD_GUIDE.md](DASHBOARD_GUIDE.md) for card selection, metric semantics, responsive rules, and integration requirements. The [follow-up audit](COVERAGE_AUDIT.md) documents eleven added groups: eight workspace patterns, dashboard cards, reporting/downloads, and top-menu navigation. Local DM Sans assets keep the catalogue and all five example pages consistent offline.

Reporting includes eight chart types, linked period/channel filters, accessible data tables, real local CSV/SVG/PNG downloads, browser print/Save as PDF, and a recent-download list. See [the reporting guide](DASHBOARD_GUIDE.md#reporting-workspace). The catalogue now has **46 sections and five full-page examples**.

Use [Top navbar & menu bar](index.html#top-menu-bar) for a header with horizontal page navigation, dropdown groups, active-page styling, and a mobile Menu disclosure. This extends the catalogue to 46 sections.

The catalogue uses seven grouped top-navbar menus instead of a long flat sidebar. Search and deep links continue to work across every section.

## Operational workflow demos

The catalogue now includes 59 sections. The 13 newest sections implement the workflow patterns described in [OPERATIONAL_PATTERNS.md](OPERATIONAL_PATTERNS.md), including imports, jobs, permissions, approvals, reports and recovery. All operations are synthetic and memory-only. Run `node scripts/workflow-check.mjs` for their focused checks.

## 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.