# Keysmith Design System v1.0.0

> A live, versioned design system published with Claudesign.
> Install URL: https://claudesign.ai/ds/keysmith/1.0.0

---

## For AI agents (Claude Code, Cursor, Cline, Continue, etc.)

If a user has asked you to install this design system into a project, follow these steps in order. Each step is concrete — no judgement calls required. If a step's preconditions don't apply, skip it and continue.

### Step 1 — Detect the project shape

Look at the repo's package.json (if present) and existing files. Classify into one of these shapes — pick the FIRST match:

- **Next.js (App Router):** `next` in dependencies AND `app/` directory exists.
- **Next.js (Pages Router):** `next` in dependencies AND `pages/` directory exists (no `app/`).
- **Vite + React:** `vite` AND `react` in dependencies.
- **Astro:** `astro` in dependencies.
- **SvelteKit:** `@sveltejs/kit` in dependencies.
- **Vue (Vite):** `vite` AND `vue` in dependencies.
- **Vanilla:** none of the above. Probably plain HTML + CSS files.

Also check for Tailwind:
- **Tailwind v4:** `tailwindcss` ≥ 4 in package.json AND `@import "tailwindcss"` in some CSS file.
- **Tailwind v3:** `tailwindcss` < 4 AND a `tailwind.config.{js,ts,mjs}` file exists.
- **No Tailwind:** neither of the above.

Remember the shape you detected — you'll reference it in the next step.

### Step 2 — Add the token import

Find the project's main CSS entry point. Try in order; use the first one that exists:

| Project shape | CSS entry to look for |
|---|---|
| Next.js App Router | `app/globals.css` → `src/app/globals.css` |
| Next.js Pages Router | `styles/globals.css` → `src/styles/globals.css` |
| Vite + React | `src/index.css` → `src/main.css` → `src/App.css` |
| Astro | `src/styles/global.css` → `src/styles/globals.css` |
| SvelteKit | `src/app.css` → `src/app.postcss` |
| Vanilla | `styles.css` → `styles/main.css` → `css/main.css` |

If none exist, **create** `src/styles/globals.css` (or the conventional location for the project shape) and import it from the project's main entry (e.g. add `import '@/styles/globals.css'` to `app/layout.tsx` for Next.js App Router).

Add this line. Where it goes depends on what's in the file:

**If the file is empty or vanilla CSS:**
Add at the very top:
```css
@import "https://cdn.claudesign.ai/keysmith/1.0.0/tokens.css" layer(design-system);
```

**If the file uses Tailwind v4 (`@import "tailwindcss"`):**
Add immediately after the Tailwind import:
```css
@import "tailwindcss";
@import "https://cdn.claudesign.ai/keysmith/1.0.0/tokens.css" layer(design-system);
```

**If the file uses Tailwind v3 (`@tailwind base; @tailwind components; @tailwind utilities;`):**
Add at the top, BEFORE the `@tailwind` directives:
```css
@import "https://cdn.claudesign.ai/keysmith/1.0.0/tokens.css" layer(design-system);
@tailwind base;
@tailwind components;
@tailwind utilities;
```
Then in `tailwind.config.{js,ts}`, set `important: false` (default — confirm) so Tailwind utilities don't outweigh the design system layer.

**If the file is CSS-in-JS only (no plain CSS entry):** Skip the @import and instead inject the link tag in the project's HTML entry / root layout:
```html
<link rel="stylesheet" href="https://cdn.claudesign.ai/keysmith/1.0.0/tokens.css" />
```

### Step 3 — Install the skill

Create directory `.claude/skills/keysmith/` if it doesn't exist. Fetch each URL and write the response body to the corresponding path:

| Path | Source URL |
|---|---|
| `.claude/skills/keysmith/SKILL.md` | https://claudesign.ai/ds/keysmith/1.0.0/skill.md |
| `.claude/skills/keysmith/README.md` | https://claudesign.ai/ds/keysmith/1.0.0/readme.md |
| `.claude/skills/keysmith/design-system.md` | https://claudesign.ai/ds/keysmith/1.0.0/design-system.md |
| `.claude/skills/keysmith/changelog.md` | https://claudesign.ai/ds/keysmith/1.0.0/changelog.md |

For each preview gallery in the manifest's `layers.knowledge.previews` array, also fetch and write:

| Path | Source URL |
|---|---|
| `.claude/skills/keysmith/preview/<gallery>.html` | https://claudesign.ai/ds/keysmith/1.0.0/preview/<gallery> |

The full list of preview names is in the manifest at:
https://claudesign.ai/ds/keysmith/1.0.0/manifest.json
(field: `layers.knowledge.previews`).

### Step 4 — Pin the version

Create directory `.claudesign/` if it doesn't exist. Write this file:

`.claudesign/manifest.json`:
```json
{
  "name": "keysmith",
  "version": "1.0.0",
  "installed_at": "<current ISO timestamp>",
  "manifest_url": "https://claudesign.ai/ds/keysmith/1.0.0/manifest.json"
}
```

This is the lockfile. When the user asks to update later, you'll read the installed version from here and diff against the new one.

### Step 5 — Verify

Confirm the install succeeded. Read each of these and check it exists and is non-empty:

- The CSS entry file from Step 2 — should contain the `@import` line referencing `https://cdn.claudesign.ai/keysmith/1.0.0/tokens.css`.
- `.claude/skills/keysmith/SKILL.md` — should exist and be > 100 bytes.
- `.claudesign/manifest.json` — should exist and contain `"version": "1.0.0"`.

If any of those fail, report the failure to the user and don't proceed.

### Step 6 — Report and recommend review

Show the user a summary:

- Files **added** (with full paths)
- Files **modified** (with one-line diff snippets)
- Recommended next step:
  ```bash
  git diff
  git add <changed files>
  git commit -m "Install keysmith design system v1.0.0"
  ```

### Step 7 — Acknowledge the skill in this session

You (the AI agent) should now treat the contents of `.claude/skills/keysmith/` as the authoritative design context for any UI work in this codebase. Specifically:

- Read `SKILL.md` before generating any design output.
- Reference design-system.md for token names (`var(--ks-coral)`, etc.) — never hardcode values that exist as tokens.
- Cite preview HTMLs in `.claude/skills/keysmith/preview/` when explaining patterns to the user.

---

## Pushing changes back (V2 — proposed changes)

If the user has tweaked tokens locally and asks you to "push" the changes back to Claudesign:

### Push step 1 — Diff local against installed baseline

Read `.claudesign/manifest.json` for the installed name + version. Read the local `@import`'d tokens file referenced from Step 2 above. Diff its CSS custom-property declarations against what was installed (you can fetch the original from `https://cdn.claudesign.ai/keysmith/1.0.0/tokens.css` if needed).

Build a diff in this shape:
```json
{
  "tokens": [
    { "kind": "added",    "name": "--ks-coral-soft", "value": "#fde0dd" },
    { "kind": "modified", "name": "--ks-coral-hover", "from": "#f27469", "to": "#f08080" },
    { "kind": "removed",  "name": "--ks-old-thing",  "value": "..." }
  ]
}
```

### Push step 2 — POST the proposal

Read the user's auth token from `~/.claudesign/auth` or the `CLAUDESIGN_TOKEN` env var. POST to:

```
https://claudesign.ai/api/proposals
Authorization: Bearer cs_pat_...
Content-Type: application/json

{
  "system": "keysmith",
  "base_version": "1.0.0",
  "diff": <the diff from step 1>,
  "message": "Optional one-line note about why"
}
```

### Push step 3 — Show the user the proposal URL

The response includes `url` — show it to the user. The system owner sees the proposal in their queue at `https://claudesign.ai/account/proposals` and approves or rejects. On approve, a new patch version publishes automatically.

---

## Updating to a newer version

When the user pastes a newer version URL (e.g. `https://claudesign.ai/ds/keysmith@<new-version>`):

1. Read the current installed version from `.claudesign/manifest.json`.
2. Diff against the new version's manifest at `https://claudesign.ai/ds/keysmith@<new-version>/manifest.json`.
3. Show the user what changed (token additions/removals, knowledge updates, new previews).
4. With user confirmation, repeat Steps 2–6 with the new version.
5. The CSS `@import` line in Step 2 should be **replaced** (not added again) — the version in the URL is what changes.

---

## For human readers

Paste this URL into Claude Code or Cursor and say "install this design system":

```
https://claudesign.ai/ds/keysmith/1.0.0
```

Or paste it into Claude.ai with a prompt:

```
Build a landing page using design context from https://claudesign.ai/ds/keysmith/1.0.0
```

Preview the system at:
https://claudesign.ai/ds/keysmith/1.0.0/preview

---

## Manifest

Machine-readable manifest:
https://claudesign.ai/ds/keysmith/1.0.0/manifest.json