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
@importline in your CSS entry (auto-detects Tailwind v3/v4/vanilla, Next.js/Vite/etc.) .claude/skills/<name>/with SKILL.md, README.md, design-system.md, brand.md (if any), changelog.md, and preview HTMLs.claudesign/manifest.jsonpinning the installed version
Run git diff 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
brand.md. - 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 Authorization: Bearer cs_pat_.... Tokens
have scopes (personal:read /
personal:write) 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 (sets owner) | 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 (owner) | Body: {is_public: bool} |
| 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
@import. 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
Publish fails with "Doesn't look like a Claude Design export — no SKILL.md found"
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.
Publish fails with "Version 1.0.0 already published"
Versions are immutable. Bump the version in the form (e.g. 1.0.1) and try again.
Claude Code installs but the @import line doesn't end up in my CSS
Most likely your project's CSS entry isn't in the standard list (app/globals.css, src/index.css, 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.
Tokens load but fonts don't
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.
Where do I report bugs / request features?