Claude Design Sync

Claude Design Sync

Use this skill to move design systems and design deliverables between a local repo and Claude Design. A project deliverable can be saved into a Claude Design folder you specify, or into a new folder you create for it — both are supported. The skill keeps reusable design systems clean and never writes deliverables into this skill's own install folder.

Core Model

Separate these surfaces every time:

• Design system: reusable brand tokens, typography, components, layout patterns, slide templates, anonymized examples.
• Project deliverable: a specific deck, landing page, prototype, report, or one-pager for a specific customer, campaign, product, or internal task.
• Upload bundle: a newly created folder for one Claude Design upload/return cycle. It is temporary working material, not the source of truth.

Save a project deliverable wherever the user wants it in Claude Design — an existing folder they name, or a new folder created for it. Both are first-class. The one hard rule: never write project files into the installed skill folder such as ~/.codex/skills/claude-design-sync, ~/.agents/skills/claude-design-sync, or this repository's claude-design-sync/ directory. Build the upload bundle inside the working repo or project folder, then upload it to the chosen Claude Design destination.

When a deliverable is saved next to reusable design-system parts, sanitize it first (see "Before You Sync") so customer names, prices, and NDA details do not leak into reusable templates.

Before You Sync

1. Identify the source of truth:
   • design-system source: tokens, components, templates, brand assets
   • deliverable source: the project/client/campaign folder
2. Check sensitivity:
   • remove or generalize company names, customer names, NDA details, prices, internal notes, and unresolved deal terms before adding examples to a design system
   • keep sensitive deliverables inside their project folder unless the user explicitly approves broader sharing
3. Choose the direction:
   • local repo -> Claude Design
   • Claude Design -> local repo
   • design system refresh
   • one-off visual editing upload bundle

Upload Destination Confirmation

Creating a local upload bundle is low risk and can proceed without interruption. Uploading that bundle to Claude Design is an external transfer and requires an explicit destination check first.

Before any upload, present a short destination plan and wait for confirmation:

Upload destination plan
- Source of truth: <local canonical file/folder>
- Local upload bundle: <path to new folder>
- Claude Design target: <new project/folder name, or existing target>
- Writes into a reusable design system: no / yes (then sanitize)
- Sensitive data handling: <kept, removed, or generalized>
- Return path: <where Claude Design output will be saved locally>

Chosen destination: existing folder "<name>", or a new folder "<artifact-slug>".

Pick the destination with the user:

1. If the user names an existing Claude Design folder, save the deliverable there.
2. Otherwise, create a new folder for it.
3. Either way, sanitize sensitive data before it lands next to reusable design-system parts.

Both destinations are first-class; the confirmation step exists so the destination is chosen on purpose, not to force new folders.

Local Repo -> Claude Design

Use this when local code, HTML, slides, or components need to appear in Claude Design.

1. Prefer syncing reusable design-system assets first:
   • tokens
   • component examples
   • templates
   • brand assets
   • anonymized reference examples
2. Keep project-specific deliverables in their original folder.
3. Create a new upload bundle folder in the working repo or project folder. Do not create it inside this skill's install folder.

<project-or-client-folder>/
  claude-design-uploads/
    <artifact-slug>/
      index.html
      assets/
      prompt.md
      source-map.md
      _ds_manifest.json
      returned/

4. Copy or transform the source files into the upload bundle:

   • use index.html for the primary HTML entrypoint
   • put images/fonts/local dependencies in assets/
   • put the Claude Design instruction in prompt.md
   • put source paths and reconstruction notes in source-map.md
   • put any card metadata in _ds_manifest.json — the file the Design System pane reads its cards from (see step 9)

5. Use generic names:

   • client-proposal-v1
   • campaign-landing-v2
   • ops-report-v1
   • product-demo-flow-v1

6. Avoid company names in reusable card names. Use role/category labels such as:

   • Client proposal deck
   • Sales operations report
   • Service overview deck
   • Product demo flow

7. Stop and confirm the upload destination using the plan in "Upload Destination Confirmation".

8. After confirmation, upload the whole <artifact-slug>/ folder to the chosen Claude Design destination — the existing folder the user named, or a new one. With the DesignSync tool this is finalize_plan (localDir = the bundle, writes = its files, deletes = [] when nothing is removed) then write_files (each file by localPath).

9. If files uploaded with write_files do not appear in the Design System pane, the card index is the cause, not the upload. The pane builds its cards from _ds_manifest.json, which the app compiles from each preview HTML's first-line <!-- @dsCard group="..." --> marker. When that auto-compile does not run, add the card by hand with the DesignSync tool:

   • get_file _ds_manifest.json to read the current index
   • append one entry to its cards array (the object below)
   • finalize_plan with writes including _ds_manifest.json (and deletes = [])
   • write_files to overwrite it

   This object is one element of the _ds_manifest.json cards array, and its viewport is a string:

{
  "path": "uploads/client-proposal-v1/index.html",
  "group": "Slides",
  "viewport": "1280x720",
  "subtitle": "temporary upload bundle, not design-system source",
  "name": "Client proposal deck"
}

10. Adding the <!-- @dsCard group="Slides" --> first-line marker lets the app's self-check pick the card up on its next scan; editing _ds_manifest.json directly is the reliable fallback when the scan does not run. Treat either as a workaround, not the normal write_files flow.

Claude Design -> Local Repo

Use this when the canvas output needs to become a local artifact or production input.

1. Export or hand off from Claude Design as HTML, PDF, PPTX, or a Claude Code handoff bundle.
2. Save the raw return under the upload bundle's returned/ folder.
3. Diff against the repo-local source of truth.
4. Move only accepted changes into the canonical file.
5. Regenerate final outputs locally:
   • PDF
   • screenshots/page images
   • PPTX when required
6. Verify visually before calling the work complete.
7. If the result contains reusable patterns, extract an anonymized template into the design system. Do not move the customer-specific deliverable itself.

Design System Refresh

Use this when the user wants Claude Design to learn or update a brand/system.

1. Sync only reusable sources:
   • tokens.css, Tailwind config, theme files
   • component library examples
   • slide templates
   • brand guidelines
   • logos and approved assets
2. Exclude:
   • customer folders
   • pricing proposals
   • contracts
   • private research notes
   • raw meeting transcripts
3. Include one or two anonymized finished examples if they express the brand better than specs alone.
4. After syncing, create or inspect a small test project to confirm the system produces on-brand output.

Output Discipline

When reporting a sync plan or result, include:

• source of truth
• sync direction
• files written or expected
• whether any workaround was used
• sensitivity handling
• what still needs visual verification

Tradeoffs

• Saving into an existing Claude Design folder is convenient and fully supported; just sanitize sensitive data so it does not leak into reusable templates in the same folder.
• Creating a new folder keeps a deliverable isolated, at the cost of one extra packaging step.
• Project-specific Claude Design outputs are useful for iteration, but final deliverables should be rebuilt and verified from the local repo when the repo is the operational source of truth.