Claude Design — ICN Setup and Workflow

How to use Claude for design work on ICN, reliably, without re-explaining the system every time.

There are two modes. Pick the one that matches the surface you're at.

1. External mode — claude.ai paste flow

1.1 Setup (one-time, ~2 minutes)

You will paste three things at the start of every Claude Design session. Have them ready as a project file, a snippet manager entry, or a saved gist:

1. `docs/design/CLAUDE_DESIGN_CONTEXT.md` — the briefing. Self-contained: brand position, tokens, vocabulary, surface inventory, kernel binding.
2. A "job card" — one paragraph stating what you want produced (artifact, audience, constraints, deliverable format). Templates in §1.3 below.
3. Reference attachments — the one or two reading-order docs from CONTEXT §9 that are most relevant to this specific job. Do not attach all seven; pick by need.

That's it. The briefing already tells Claude what kind of artifact to return and what to flag as assumptions.

1.2 Per-session workflow

1. New Claude.ai conversation.
2. Paste CLAUDE_DESIGN_CONTEXT.md.
3. Paste the job card (§1.3 templates).
4. Attach the 1–2 reference docs (§1.4 doc-to-job table).
5. Ask Claude to acknowledge constraints before producing.
   ("Before you start: list the three hard constraints that apply to this job.")
6. Review the deliverable. Flag anything that asserts capability the kernel can't prove
   (tier-1 truthfulness rule).
7. If the deliverable is worth keeping, route it through the asset lifecycle in [`assets/README.md`](assets/README.md) — register the asset in [`assets/ASSET_REGISTER.md`](assets/ASSET_REGISTER.md), write a brief under [`assets/briefs/`](assets/briefs/), and (for generated-image exploration) place sketches under that brief's own `sketches/` folder. Sketches are never load-bearing and never enter `website/src/assets/` — see [`ICN_VISUAL_EXPLAINER_BIBLE.md`](ICN_VISUAL_EXPLAINER_BIBLE.md) §11.

1.3 Job-card templates

Paste one of these after the context doc. Fill in <brackets>.

Visual design (new artifact)

JOB: Visual design — <surface name>.
TARGET: <breakpoint>, <theme>.
INCLUDES: <what must be on screen — e.g. "status pill, mandate line, primary action, secondary action, dismissed receipt link">
DELIVERABLE: <single PNG mock | annotated HTML/CSS | SVG composition>
RATIONALE: One paragraph explaining choices against §2 (Brand) and §3 (Constraints) of the briefing.
ASSUMPTIONS: Flag anything you assumed about data, capability, or behavior.
LABEL: <concept | UX direction | implementation-ready>  (per ADR-0033)

Component spec

JOB: Component spec — <component name from CONTEXT §6 "not yet built" list>.
FORMAT: Markdown spec — variants, states, props, accessibility notes, code example.
TOKENS: Use the tokens in CONTEXT §4. Do not invent new colors.
ACCESSIBILITY: WCAG 2.2 AA. Reduced motion. 44×44 tap targets. Color is not the only carrier.
DELIVERABLE: A single Markdown table block per section. No screenshots.

Copy review

JOB: Copy review.
INPUT:
  <paste the copy, one string per line>
RULES: Apply CONTEXT §5 vocabulary and CONTENT_STYLE_GUIDE.md voice rules.
DELIVERABLE: For each string — PASS | FLAG <reason> | REWRITE <new version>.
DO NOT REWRITE strings that already pass. Pass-through is signal.

Accessibility audit

JOB: Accessibility audit against WCAG 2.2 Level AA.
INPUT:
  <paste HTML or describe the surface>
RULES: Apply ACCESSIBILITY_BASELINE.md per-surface obligations + design-language/accessibility.md component rules.
DELIVERABLE: WCAG criterion | PASS | FAIL <evidence> | FIX <proposed change>
INCLUDE: Color contrast (with computed ratios), keyboard reachability, screen reader semantics, tap targets, motion handling, plain language.

Design critique

JOB: Critique against ICN design principles.
INPUT: <link or paste of the mockup>
RULES: Apply CONTEXT §2 (brand), §3 (constraints), §7 (kernel binding) and ICN_DESIGN_SYSTEM.md "Design principles (compact)" list.
DELIVERABLE: 3–5 specific, prioritized observations. Each observation cites the principle violated and proposes a fix.
DO NOT: produce a redesign. Critique only.

Concept exploration

JOB: Concept exploration for <unbuilt primitive from CONTEXT §6>.
DIRECTIONS: 3, each in a different visual register.
LABEL: All three are concept art, not implementation. Mark accordingly per ICN_VISUAL_EXPLAINER_BIBLE.md.
DELIVERABLE: For each direction — one composition + one paragraph rationale + one assumption flag.

1.4 Doc-to-job attachment table

Beyond the briefing, attach only what the job needs:

1.5 What to flag in the deliverable

Before saving anything Claude Design produces, scan for:

• Asserted capability the kernel can't prove → mark concept-only or remove (ADR-0032, ADR-0033)
• Forbidden vocabulary from CONTEXT §5 "Words to avoid"
• NYCN / Summit references on anything that isn't an institution package
• Color-only meaning (run grayscale preview mentally — or actually)
• Tap targets under 44×44
• Motion that doesn't honor prefers-reduced-motion
• A dangerous action without mandate / reversibility / receipt declared before confirm

A deliverable with any of these is a draft, not a ship.

2. Local mode — Claude Code design routing

Local mode runs design work inside Claude Code in this repo, with full file access. Unlike external mode, what's bundled by this repo and what comes from a Claude Code plugin are different surfaces. Be precise about which you're invoking.

2.1 What this repo ships (always available)

These are committed under .claude/ and work the moment you're in this worktree:

If you're working in this repo with Claude Code, the agent and rule above are loaded automatically — that alone is enough to do design review, copy review, accessibility review, and component spec work without any plugins.

2.2 What requires the design plugin (optional)

The richer /design:* slash commands — /design:design-system, /design:design-critique, /design:accessibility-review, /design:ux-copy, /design:design-handoff, /design:user-research, /design:research-synthesis — are not bundled by this repo. They come from a Claude Code plugin pack (the design plugin in the Claude Code marketplace).

If you have the plugin installed, you'll see those commands offered when you type /. If you don't, the commands won't resolve. To check what's available in your current session, run /help or type / and inspect the autocomplete.

Install path (if you want them):

# In Claude Code, from the marketplace UI:
#   Settings → Plugins → install "design"
# Or via CLI (varies by Claude Code version):
claude plugins install design

The plugin's design skills are generic (not ICN-aware). To bind them to ICN doctrine, prefix the invocation:

/design:design-critique Before critiquing, read docs/design/CLAUDE_DESIGN_CONTEXT.md
and docs/design/ICN_DESIGN_SYSTEM.md so your critique is bound to ICN doctrine.
Then critique: <paste mockup link or description>

Or — and this is the better path — just dispatch the icn-design-advisor agent described in §2.1 above. It already knows the doctrine.

2.3 Local-mode workflow (preferred — no plugins required)

1. Be in this repo. (Working directory matters — the design rule is path-scoped.)
2. Dispatch the icn-design-advisor agent, OR work directly with file edits and let
   the .claude/rules/design.md auto-load doctrine.
3. Hand the agent the artifact: a path, a paste, or a description.
4. The agent reads ICN doctrine docs and applies the hard constraints from §3 of
   CLAUDE_DESIGN_CONTEXT.md.
5. Review the result. If it touches a file, verify before commit (per CLAUDE.md).

2.4 When local mode is better than external mode

• The job needs to touch live files (component code, copy in the codebase, ADR draft).
• The job needs to verify against current implementation (token usage, content audit).
• The job is review-shaped (critique, audit, handoff) more than create-shaped.

2.5 When external mode is better than local mode

• The job is producing a visual composition (Claude Code is not a visual canvas).
• The job is concept exploration (multiple variants, no file touch needed).
• The job needs a long uninterrupted session with rich image attachments.

3. Mixing modes (the common pattern)

The realistic workflow is: explore externally, decide, then apply locally.

External: claude.ai paste flow → critique a mockup → get 3 directions
         ↓
You:      pick one
         ↓
Local:   dispatch icn-design-advisor agent → produce the spec in docs/design/components/<name>.md
         (or `/design:design-system extend` if the `design` plugin is installed)
         ↓
Local:   icn-design-advisor handoff mode → produce dev-ready spec for the website team
         (or `/design:design-handoff` if installed)
         ↓
Local:   icn-design-advisor accessibility-audit mode against the live preview
         (or `/design:accessibility-review` if installed)

If you only ever use one mode, the doctrine works. Mixing is more powerful for new primitives because external mode is faster for visual iteration and local mode is stricter about the rules.

4. Common failure modes and what they signal

5. The institution-package boundary

ICN design work is not NYCN design work, and not Summit design work. Those are institution packages that consume ICN primitives and tokens but bring their own brand, copy, and surfaces.

When using Claude Design for institution-package work:

• Do not paste CLAUDE_DESIGN_CONTEXT.md (it's the ICN substrate, not a package brand).
• Use the package's own brief from its private repo.
• ICN tokens, vocabulary, and accessibility floor still apply as inheritance, but the brand layer is the package's.

If you're not sure which one you're doing: if the surface ever ships to a member without an NYCN or Summit logo on it, it's ICN-substrate work, and CONTEXT.md applies.

6. Maintenance

Keep this doc and CLAUDE_DESIGN_CONTEXT.md in sync with:

• The token list in website/src/styles/global.css
• The concept vocabulary in docs/design-language/concept-map.md
• Surface state (built vs spec-only) in docs/design/ICN_DESIGN_SYSTEM.md
• New ADRs binding design (currently 0026, 0027, 0028, 0032, 0033)

Re-review on: any of the above changing, or quarterly, whichever is sooner.

7. See also

• CLAUDE_DESIGN_CONTEXT.md — the paste briefing
• ICN_DESIGN_SYSTEM.md — design system entry point
• ../DESIGN_PRINCIPLES.md — kernel-side counterpart
• ICN_VISUAL_EXPLAINER_BIBLE.md — for diagrams and infographics specifically
• assets/VISUAL_REVIEW_CHECKLIST.md — pre-ship review for visual deliverables