Documentation
Everything you need to publish, install, and update a design system on Claudesign.
Install in Claude Code
Open Claude Code in any repo. Paste the install URL and tell the agent to install:
https://claudesign.ai/ds/keysmith
→ "install this design system" The agent fetches the URL, follows the install protocol, and writes:
- An <code class="text-xs">@import</code> line in your CSS entry (auto-detects Tailwind v3/v4/vanilla, Next.js/Vite/etc.)
- <code class="text-xs">.claude/skills/<name>/</code> with SKILL.md, README.md, design-system.md, brand.md (if any), changelog.md, and preview HTMLs
- <code class="text-xs">.claudesign/manifest.json</code> pinning the installed version
Run <code class="text-xs">git diff</code> to review and commit normally.
Publish a design system
Three inputs:
- Claude Design zip — the .zip you downloaded from Claude Design. Contains SKILL.md, tokens.css, fonts, assets, preview HTMLs, optional component code.
- Brand context (optional, markdown) — tone of voice, photography style, brand language. Compiled into <code class="text-xs">brand.md</code>.
- Display name + URL slug + version — slug is lowercase letters/digits/hyphens (used in URLs); version is semver. Versions are immutable once published.
On publish, the platform extracts, content-hashes, dedupes (so the same font shared across versions only stores once), rewrites all relative paths to CDN URLs, and produces a complete versioned design system at one URL.
Auth & tokens
Anonymous publishing still works for public design systems — you don't need an account to use Claudesign. Sign in only to manage what you've published, mark systems private, or use the CLI / Claude Code push flow.
Sign-in is GitHub OAuth. Once signed in, generate a personal access token at /account/tokens for CLI / CI / push usage:
# In CI or CLI environments: export CLAUDESIGN_TOKEN=cs_pat_xxxxxxxx... # Or in a per-machine global file: mkdir -p ~/.claudesign echo 'cs_pat_xxxxxxxx...' > ~/.claudesign/auth chmod 600 ~/.claudesign/auth
API calls use <code class="text-xs">Authorization: Bearer cs_pat_...</code>. Tokens have scopes (<code class="text-xs">personal:read</code> / <code class="text-xs">personal:write</code>) and can be revoked at any time.
Private design systems
Toggle a system to private at /account/systems. Once private, both the install URL and CDN content require a valid PAT.
When pasting a private install URL into Claude Code, include the PAT:
# Claude Code prompt: "Install this design system: https://claudesign.ai/ds/private-name/1.0.0 Use this auth token when fetching: cs_pat_xxxxxxxx..."
The agent will set the Authorization header on subsequent fetches.
API reference
| Method | Path | Auth | Returns |
|---|---|---|---|
| GET | /api/health | none | Health check |
| GET | /api/systems | none | List public systems |
| POST | /api/publish | optional | Multipart: zip, name, version, display_name, brand? |
| GET | /auth/me | cookie / PAT | Current user or null |
| GET | /api/me/systems | required | Systems owned by current user |
| PATCH | /api/me/systems/:slug/visibility | required | Toggle public/private |
| GET | /api/tokens | required | List user's PATs |
| POST | /api/tokens | required | Create PAT (raw shown once) |
| DELETE | /api/tokens/:id | required | Revoke a PAT |
URL conventions
| URL | Returns |
|---|---|
| /ds/<name> | Latest install protocol (markdown) |
| /ds/<name>/<version> | Pinned install protocol |
| /ds/<name>/<version>/manifest.json | Machine-readable manifest |
| /ds/<name>/<version>/skill.md | Skill spec for AI agents |
| /ds/<name>/<version>/design-system.md | Synthesized token reference |
| /ds/<name>/<version>/brand.md | Brand context (if uploaded) |
| /ds/<name>/<version>/changelog.md | Token diff vs. previous version |
| /ds/<name>/<version>/preview/<gallery> | Live preview HTML |
| cdn.claudesign.ai/<name>/<version>/tokens.css | Layer-1 token stylesheet (CDN) |
| cdn.claudesign.ai/<name>/assets/<hash>/<file> | Content-addressed asset (immutable) |
The five layers
A design system is five layers, each delivered differently:
- 1. Tokens — CSS custom properties (colors, type, spacing). Loaded via CDN <code class="text-xs">@import</code>. SRI-verifiable.
- 2. Assets — Logos, icons, fonts, images. Content-hashed CDN URLs, deduped across versions.
- 3. Knowledge — SKILL.md, README, brand.md, design-system.md, preview HTMLs. Written into the consuming repo.
- 4. Components — JSX/TSX implementations. V2 — not in MVP.
- 5. Animations — Lottie JSON, motion tokens. V3 — not yet.
Troubleshooting
Your zip is missing a SKILL.md at the root. We use that to detect Claude Design exports. If you're trying to publish a non-Claude-Design system, that's V2 work — we don't accept other formats yet.
Versions are immutable. Bump the version in the form (e.g. 1.0.1) and try again.
Most likely your project's CSS entry isn't in the standard list (<code class="text-xs">app/globals.css</code>, <code class="text-xs">src/index.css</code>, etc.). After install, paste the @import line into your actual CSS entry manually. Tell us what shape your project is so we can extend the protocol's framework detection.
Check the network tab — font URLs should be content-hashed CDN URLs. If they're broken, the path-rewriter on publish missed something. Open an issue with the zip you uploaded.
FAQ
Do I need an account?
Not in MVP. Anyone can publish, all systems are public. Accounts + private systems land in V1.
Can I delete or edit a published version?
No — versions are immutable on purpose. Consuming repos pin to specific versions and shouldn't see content change underneath them. Publish a new version with a higher number.
What about components?
Layer 4 — V2. The plan is to ship two paths: (a) Claude Code generates framework-native components from the SKILL.md spec on demand, (b) for teams that want a versioned package, we publish framework-specific NPM packages per design system version.
What's the relationship to Claude Design?
Claude Design generates design systems. Claudesign distributes them — turns the zip from Claude Design into a live, versioned, CDN-backed system that consuming repos reference instead of copy. Complementary, not competitive.