Keysmith Design System v1.0.0

A live, versioned design system published with Claudesign. Install URL: https://claudesign.ai/ds/[email protected]

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:

@import "https://cdn.claudesign.ai/[email protected]/tokens.css" layer(design-system);

If the file uses Tailwind v4 (@import "tailwindcss"): Add immediately after the Tailwind import:

@import "tailwindcss";
@import "https://cdn.claudesign.ai/[email protected]/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:

@import "https://cdn.claudesign.ai/[email protected]/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:

<link rel="stylesheet" href="https://cdn.claudesign.ai/[email protected]/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/[email protected]/skill.md
`.claude/skills/keysmith/README.md`	https://claudesign.ai/ds/[email protected]/readme.md
`.claude/skills/keysmith/design-system.md`	https://claudesign.ai/ds/[email protected]/design-system.md
`.claude/skills/keysmith/changelog.md`	https://claudesign.ai/ds/[email protected]/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/[email protected]/preview/<gallery>

The full list of preview names is in the manifest at: https://claudesign.ai/ds/[email protected]/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:

{
  "name": "keysmith",
  "version": "1.0.0",
  "installed_at": "<current ISO timestamp>",
  "manifest_url": "https://claudesign.ai/ds/[email protected]/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/[email protected]/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.

Show the user a summary:

Files added (with full paths)
Files modified (with one-line diff snippets)

Recommended next step:

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/[email protected]/tokens.css if needed).

Build a diff in this shape:

{
  "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>):

Read the current installed version from .claudesign/manifest.json.
Diff against the new version's manifest at https://claudesign.ai/ds/keysmith@<new-version>/manifest.json.
Show the user what changed (token additions/removals, knowledge updates, new previews).
With user confirmation, repeat Steps 2–6 with the new version.
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/[email protected]

Or paste it into Claude.ai with a prompt:

Build a landing page using design context from https://claudesign.ai/ds/[email protected]

Preview the system at: https://claudesign.ai/ds/[email protected]/preview

Manifest

Machine-readable manifest: https://claudesign.ai/ds/[email protected]/manifest.json