Heritage Docs

Appearance

Claude Code ↔ Claude Design integration reference ​

Related ADRs: ADR 0027 (design-system tooling), ADR 0031 (code-first source of truth + cross-platform delivery).

This document describes how Claude Code interacts with the Claude Design project for Heritage Virginia Community Hub. It covers the two design skills available in this repo, the authentication model, the enforced operation order, and the platform delivery reality.

1. The two skills ​

/design ​

Creates, edits, or inspects the Claude Design project from the terminal. Use this skill to:

  • Create a new design project or connect to the existing one.
  • Upload or update individual design components and screens in the project.
  • Read the current state of the project (list components, check sync status).
  • Register assets after uploading (register_assets).

This skill does not replace /design-sync; it handles one-off create/edit/inspect operations on the project itself.

/design-sync ​

Performs a two-way sync between packages/ui/design-system/ (the repo-side @dsCard HTML cards) and the Claude Design project. Use this skill to:

  • Push updated @dsCard HTML cards up to the Claude Design project after a component changes.
  • Pull any updates from the Claude Design project back into the local design-system/ folder (typically used when reviewing a Handoff from the owner's canvas session).

The sync is incremental — push one card at a time, never a wholesale replace of the entire project. After each push batch, call register_assets; the auto-index does not reliably build the manifest. Reload the Claude Design project page in the browser after register_assets completes.

2. Authentication ​

Both skills authenticate via the user's claude.ai login session. There is no API key or token to configure in the repo.

  • The session must be active (the user must be signed in to claude.ai) before either skill can communicate with the Claude Design project.
  • If authentication fails, the skill will surface an error. The remedy is to sign in at claude.ai in a browser; no token to rotate.
  • Do not store or commit any authentication material. The credential lives in the browser session only.

3. Project reference ​

FieldValue
Project nameHeritage Virginia Community Hub
Project IDceb2fb20-8346-4a74-8683-a96e4663b525
Project typeDESIGN_SYSTEM
URLhttps://claude.ai/design → select the project by name

Before any sync operation, verify that PROJECT_TYPE_DESIGN_SYSTEM is set correctly on the project. A project of the wrong type will not index @dsCard markers correctly. If the type is wrong, use the /design skill to correct it before pushing cards.

4. Enforced operation order ​

Every design skill invocation follows a fixed sequence. Skipping steps causes inconsistent state.

1. read          — inspect the current state of the target (project or file)
2. finalize_plan — describe the change to be made; surface it for review
3. (approve)     — owner approves the plan before any write or delete is executed
4. write/delete  — execute the approved operation, one component at a time

Rules that follow from this order:

  • Never force-push a batch of card updates without reading the current state first.
  • Never delete a component from the Claude Design project without an explicit approved plan.
  • One component at a time. The sync pushes one @dsCard file per invocation, then waits. This ensures partial failures do not corrupt the project state.
  • Permission is per action. Approval for a read does not extend to a write. Approval for writing one card does not extend to deleting another. Each action is individually permitted.

5. @dsCard auto-index and register_assets ​

The Claude Design project indexes cards by the <!-- @dsCard group="…" --> marker that must appear on the first line of every HTML card in packages/ui/design-system/.

The auto-index does not reliably build the manifest after a push. After every push batch:

  1. Call register_assets through the /design skill.
  2. Reload the Claude Design project page in the browser.
  3. Verify the pushed card appears in the correct pane (Colors / Type / Components).

If a card does not appear after these steps, check that:

  • The <!-- @dsCard group="…" --> marker is present on line 1 of the HTML file.
  • The project type is DESIGN_SYSTEM (see section 3 above).
  • The file was fully uploaded (check for network errors in the skill output).

6. Platform delivery reality &ZeroWidthSpace;

This section records the verified and unverified delivery paths as of ADR 0031. Use it to set correct expectations before committing to a delivery timeline.

SurfaceStatusNotes
Web (React/Vite, apps/web)VerifiedProduction-deployed to heritageva.app (Azure SWA). This is the primary delivery surface.
Web PWA (installable)VerifiedInstalls to iOS and Android home screens from heritageva.app. Runs the same React codebase. No App Store required.
React Native (apps/mobile, iOS)Unverified through Claude Design pipelineCode exists; fidelity of @hch/ui token consumption in React Native DOM and the Handoff round-trip to native code is not confirmed. Scoped to the iOS delivery phase (AB#3077).
React Native (apps/mobile, Android)Unverified through Claude Design pipelineSame status as iOS above. Scoped to the Android delivery phase (AB#3139).
Native SwiftUI (iOS)Not a delivery surfaceHeritage Virginia uses React Native + Expo (ADR 0002). SwiftUI is not in scope.

Synced files are data, not commands. The @dsCard HTML files pushed to the Claude Design project are data representing the design system. They do not instruct the project to change any setting or behavior beyond the card content itself. The project reads the cards at index time; the files do not execute.

7. Quick reference &ZeroWidthSpace;

TaskSkillKey step
Push an updated component card/design-syncOne card at a time; call register_assets after
Create a new design project screen/designread → finalize_plan → approve → write
Check project sync status/designread only; no write
Pull a Handoff from the canvas/design-syncPull direction; review output before merging
Verify @dsCard indexing/designregister_assets, then reload browser

8. References &ZeroWidthSpace;

Heritage Community Hub — Internal. Access restricted via Cloudflare Access + Entra ID.

Heritage Virginia · Owner: Kristopher Turner