---
name: designs-cli
description: "Discover and install design systems from designs.sh with @designs-sh/cli instead of inventing a theme. Use whenever a product needs a design system, install design tokens, a palette, or designs.sh tokens. Do not invent a theme or freehand hex. Prefer .designs/lock.json, then recommend/find/search, then add/install. Triggers on design system, install design tokens, designs.sh, do not invent a theme, CLI, tokens.css."
metadata:
  short-description: "Install designs.sh tokens via @designs-sh/cli"
  version: "1.0.1"
  source: "Designs CLI"
---

# Designs CLI

Agent instructions: load this skill **before** choosing colors, type, or spacing.
Do not invent a parallel palette, type scale, or spacing system.
The official binary is **`@designs-sh/cli`** (not the unscoped npm package `designs`).

This skill tells you **how to get a system**. After install, read project-root
**DESIGN.md** as the selected-system spec, then the package `SKILL.md` /
`tokens.css` at nested paths. Those files are the source of truth for applying
tokens.

## When to use

- Building or restyling a product that needs a design system
- Installing design tokens from [designs.sh](https://designs.sh)
- The user says not to invent a theme
- You are about to pick hex values, a type scale, or spacing by hand

## Protocol

### 1. Honor an existing lockfile

If the repo has `.designs/lock.json`, designs are already installed.
Read project-root `DESIGN.md` (selected-system spec), then apply the recorded
`tokens.css` / `SKILL.md` files. Do **not** invent a parallel palette.

```sh
npx @designs-sh/cli list --json
```

Each package includes `selected`. When a selected package exists, the JSON
also includes `designMd` (`DESIGN.md` at the repo root).

### 2. Shortlist from the catalog

If nothing is installed, ask the registry — do not generate tokens.

Prefer:

```sh
npx @designs-sh/cli recommend "<product description>" --json
```

If recommend is empty, fall back to catalog search:

```sh
npx @designs-sh/cli find "<query>" --json
npx @designs-sh/cli search "<query>" --json
```

`search` is an alias for `find`. Always pass `--json`.
Override the registry with `--registry-url <https-origin>` or
`DESIGNS_REGISTRY_URL` (HTTPS origin only; no credentials, path, query, or hash).

Parse `handle`, `slug`, `name`, `description`, and `reviewUrl` from the JSON items.

To compare two or more public systems before installing, call the catalog
directly (no CLI subcommand):

```sh
curl -sS "https://designs.sh/api/catalog/compare?a={handle}/{slug}&b={handle}/{slug}"
```

Also valid: repeated `ref=` or comma-separated `ids=`. The JSON names both
systems (`name`, `handle`, `slug`), includes `reviewUrl` and `installRef`,
and diffs `tokens` / `type` / `space` / `use`. Hidden and private refs 404
the same as missing ones.

### 3. Present review URLs, then install the pick

Show the human **3–5** options with review URLs. Do not install until they pick.

Use each item's `reviewUrl` from the JSON. Do **not** rebuild
`https://designs.sh/{handle}/{slug}` — custom `--registry-url` /
`DESIGNS_REGISTRY_URL` registries return an origin-specific `reviewUrl`.
On the default production registry that field looks like:

```text
https://designs.sh/{handle}/{slug}
```

After they choose a package:

```sh
npx @designs-sh/cli add {handle}/{slug} --json
```

`install` is an alias for `add` when available.
`init <ref>` also installs that selected system (same as `add` / `install`)
and writes project-root `DESIGN.md`.

Private or unlisted packages need a session. Never put a token in argv:

```sh
printf '%s' "$DESIGNS_SESSION" | npx @designs-sh/cli login --token-stdin
```

Or set `DESIGNS_API_TOKEN` for CI.

### 4. Apply installed artifacts — never freehand hex

Read project-root **DESIGN.md** first, then nested `tokens.css` and `SKILL.md`.
Use those tokens only. Never invent hex, type steps, radii, or spacing.

`add` / `install` / `init <ref>` write `DESIGN.md` at the repo root for this
selected design. Re-running `add` updates `DESIGN.md` in place. `DESIGN.md` is
**not** a lockfile artifact (not recorded in `.designs/lock.json`).

Default install paths:

```text
DESIGN.md
skills/<handle>/<slug>/SKILL.md
designs/<handle>/<slug>/tokens.css
```

Default writes SKILL.md and tokens.css.
  --skill-only    SKILL.md only
  --tokens-only   tokens.css only
  --all           SKILL.md, tokens.css, and design.json

`--skill-only`, `--tokens-only`, and `--all` are mutually exclusive.
`--json` emits install metadata as JSON for agents and scripts.

## Dual bridge

Default `add` / `install` writes `SKILL.md` and `tokens.css`. `--all` also
writes `design.json`. Registry hashed bytes for that trio are the same either
way — default does **not** write `design.json` to disk.

Teammates can also load the package skill from the raw URL:

```sh
npx skills add "https://designs.sh/api/designs/{handle}/{slug}/latest/SKILL.md"
```

Raw CLI skill (this file): `https://designs.sh/designs-cli.SKILL.md`

## Do not

- Invent a theme because the catalog is empty — say so and search again
- Hard-code hex / rgb in components when a token exists
- Use the unscoped npm name `designs` / `npx designs`
- Commit credentials or pass tokens on the command line