claude-design-premium-harness

Claude Design Premium Harness

Skill by ara.so — Design Skills collection.

Claude Design Premium is a context harness and skill pack for Claude Design Web that prevents design system amnesia. It binds your tokens, components, voice, and constraints into persistent artifacts (BOUND_DS.json, DESIGN.md) so Claude respects your system across sessions without re-briefing.

Zero npm dependencies. Scripts run inside Claude Design's canvas runtime. 13 skills cover setup, guardian checks, audits (a11y, mobile, copy, Tailwind), showcase assembly, and framework handoff.

What It Does

• Binds your design system via BOUND_DS.json (tokens, components, manifest paths)
• Enforces fidelity with design-system-guardian that checks every UI task against your system
• Assembles a living specimen (design-system.dc.html) from your DESIGN.md
• Runs targeted audits before handoff: accessibility, mobile-first, text integrity, visual originality, Tailwind alignment
• Supports two modes: Builder (you maintain the DS) and Consumer (you use a published bundle)

Installation

1. Download and Upload

# Download ZIP from GitHub
curl -L https://github.com/oalanicolas/claude-design-premium/archive/refs/heads/main.zip -o cdp.zip
unzip cdp.zip

Then upload the ZIP to your Claude Design Web project, or clone the repo directly if working locally.

2. Promote Harness Files

In Claude Design Web chat:

Copy all files from the claude-design-premium-main folder to the project root.
Keep existing _ds/ or root manifest files.

This moves:

• CLAUDE.md (skill router)
• skills/ (13 .md files)
• scripts/ (bootstrap .mjs files)
• pages/ (starter .dc.html files)
• README.md, PLAYBOOK.md, LIMITATIONS.md

3. Bootstrap

Open a new tab in the same project and send:

GO

The harness-auto-setup skill runs scripts/bootstrap-harness.mjs, detects builder or consumer mode, writes BOUND_DS.json, scaffolds design-system.dc.html, and generates .cdp/showcase-brief.json.

Key Configuration Files

DESIGN.md

Your canonical brief: voice, surfaces, constraints. Claude reads this before every UI task.

Builder mode (root):

# Design System Brief

## Voice & Tone
CDP:UNCONFIGURED — Replace with your brand voice rules

## Surfaces
- Dashboard (dense, data-first)
- Landing (spacious, conversion-focused)
- Settings (utility, clarity over beauty)

## Constraints
- Mobile-first grid, 4px base unit
- Tailwind utilities only, no arbitrary values unless documented
- WCAG AA minimum

## Token Reference
See `_ds_manifest.json` → colors, spacing, typography

Consumer mode (_ds/<bundle>/DESIGN.md):

# Design System: Acme SaaS Kit

## Voice
Professional, warm, no jargon. Active voice. Sentence case everywhere.

## Components
Dashboard cards, metric tiles, action sheets (see `_ds/acme/components/`)

## Tokens
`_ds/acme/_ds_manifest.json`

BOUND_DS.json

Written by bootstrap. Machine-readable binding.

{
  "mode": "builder",
  "design_md_path": "DESIGN.md",
  "manifest_path": "_ds_manifest.json",
  "components_dir": "components/",
  "tokens": {
    "colors": { "primary": "#3b82f6", "surface": "#ffffff" },
    "spacing": { "xs": "0.25rem", "sm": "0.5rem" }
  },
  "timestamp": "2026-06-18T22:14:04Z"
}

.cdp/showcase-brief.json

Inventory for the design system specimen:

{
  "sections": [
    { "id": "colors", "title": "Color Palette", "components": [] },
    { "id": "typography", "title": "Typography Scale", "components": [] },
    { "id": "buttons", "title": "Buttons", "components": ["primary", "secondary", "ghost"] }
  ],
  "meta": { "generated": "2026-06-18T22:14:04Z", "mode": "builder" }
}

Core Skills

harness-auto-setup

Trigger: First open or GO command.

Runs scripts/bootstrap-harness.mjs:

1. Detects mode (builder if _ds_manifest.json at root, consumer if _ds/<bundle>/ exists)
2. Writes BOUND_DS.json
3. Scaffolds design-system.dc.html
4. Generates .cdp/showcase-brief.json

User prompt:

GO

design-system-guardian

Trigger: Any UI creation task (dashboard, landing page, component mockup).

Checks:

• Token usage (colors, spacing, typography from BOUND_DS.json)
• Component existence (manifest components/ array)
• Voice alignment (DESIGN.md tone rules)

Example (in Claude Design Web):

Create a settings page for user preferences using our design system.

Guardian intercepts, validates tokens, suggests fixes:

✓ Tokens aligned
✗ "Toggle Switch" not in manifest — use "Checkbox" or add to components/
✓ Copy matches DESIGN.md voice

assemble-design-system-showcase

Trigger: After bootstrap, to complete the specimen.

Reads .cdp/showcase-brief.json, builds out each section in design-system.dc.html.

User prompt:

Assemble the full design-system showcase from the brief.

Produces a live, navigable specimen with:

• Token swatches
• Component examples with states
• Spacing/typography scales
• Real copy samples

Audit Skills

All run before handoff. Invoked via CLAUDE.md routing.

Skill	What It Checks
ui-audit	Hierarchy, layout, spacing consistency
visual-originality-audit	Generic template patterns, stock photo drift
text-integrity-audit	Copy vs DESIGN.md voice rules
mobile-first-audit	Responsive behavior, touch targets
accessibility-audit	WCAG AA contrast, keyboard nav, ARIA
tailwind-audit	Utility/token alignment, arbitrary value usage

Example prompt:

Run a mobile-first audit on this dashboard.

Claude applies skills/mobile-first-audit.md, reports breakpoint issues, touch target sizes.

framework-handoff

Trigger: Ready to export to React, Vue, Svelte, etc.

Generates notes mapping .dc.html to framework code.

User prompt:

Create a framework handoff for this landing page in React + Tailwind.

Output:

## Framework Handoff: Landing Page → React

### Components
- `Hero.jsx` — token: `text-primary`, spacing: `py-16`
- `FeatureGrid.jsx` — 3-col responsive, `gap-6` (token: `spacing.md`)

### Tailwind Config
Extend `tailwind.config.js`:
```js
module.exports = {
  theme: {
    extend: {
      colors: { primary: '#3b82f6', surface: '#ffffff' }
    }
  }
}

Missing in Manifest

• Icon component (suggest adding _ds_manifest.json → components: ["Icon"])

## Real Usage Patterns

### Pattern 1: Bootstrap a New Builder Project

You're the DS maintainer. Tokens and components are in this repo.

```bash
# Local validation (optional)
node scripts/bootstrap-harness.mjs
node scripts/context-signals.mjs

In Claude Design Web:

GO

Then configure DESIGN.md:

# Design System Brief

## Voice
Clear, confident, no marketing fluff. Active voice. Sentence case.

## Surfaces
- Dashboard: dense, data-forward
- Landing: spacious, conversion-focused

## Constraints
- Mobile-first, 4px base unit
- Tailwind utilities only
- WCAG AA minimum

## Token Reference
`_ds_manifest.json` → colors, spacing, typography

Assemble specimen:

Assemble the full design-system showcase from the brief.

Pattern 2: Consumer Mode (Published Bundle)

Your app uses a published DS bundle in _ds/acme/.

Upload harness ZIP, promote files:

Copy all files from the claude-design-premium folder to the project root.

New tab:

GO

Bootstrap detects _ds/acme/_ds_manifest.json, sets mode to consumer, binds to _ds/acme/DESIGN.md.

Build a screen:

Create a user settings page using the Acme design system.

Guardian checks _ds/acme/components/, validates tokens, enforces voice from _ds/acme/DESIGN.md.

Pattern 3: Audit Before Handoff

You've designed a dashboard. Run all audits:

Run a full audit pass on this dashboard: UI, mobile, accessibility, and Tailwind alignment.

Claude invokes:

1. ui-audit.md → hierarchy, spacing
2. mobile-first-audit.md → responsive, touch targets
3. accessibility-audit.md → contrast, ARIA
4. tailwind-audit.md → utility usage

Reports issues, you iterate, then:

Create a framework handoff for React + Tailwind.

Pattern 4: Maintain the Specimen

Your DS evolves. Update _ds_manifest.json (new components), then:

Update the design-system showcase with the new Button variants.

Claude reads updated manifest, rebuilds relevant sections in design-system.dc.html.

Bootstrap Scripts (Node.js, Optional Local Use)

Scripts in scripts/ are Node.js modules that run inside Claude Design's canvas when Claude reads and applies them. You can also run them locally for validation.

scripts/bootstrap-harness.mjs

import fs from 'fs';
import path from 'path';

// Detects mode, writes BOUND_DS.json, scaffolds showcase
const mode = fs.existsSync('_ds_manifest.json') ? 'builder' : 
             fs.existsSync('_ds') ? 'consumer' : 'unknown';

const binding = {
  mode,
  design_md_path: mode === 'builder' ? 'DESIGN.md' : '_ds/*/DESIGN.md',
  manifest_path: mode === 'builder' ? '_ds_manifest.json' : '_ds/*/_ds_manifest.json',
  timestamp: new Date().toISOString()
};

fs.writeFileSync('BOUND_DS.json', JSON.stringify(binding, null, 2));
console.log('✓ BOUND_DS.json written');

Run locally:

node scripts/bootstrap-harness.mjs
# Output: ✓ BOUND_DS.json written

Override mode:

node scripts/bootstrap-harness.mjs --mode builder

scripts/context-signals.mjs

Validates setup: checks for CLAUDE.md, DESIGN.md, BOUND_DS.json.

node scripts/context-signals.mjs
# Output:
# ✓ CLAUDE.md exists
# ✓ BOUND_DS.json valid
# ✗ DESIGN.md contains CDP:UNCONFIGURED placeholders

scripts/test-builder-bootstrap.mjs

Simulates full bootstrap in builder mode, writes test files.

node scripts/test-builder-bootstrap.mjs
# Creates .cdp/test-run/ with mock BOUND_DS.json, showcase-brief.json

Environment Variables

No API keys required. All logic runs inside Claude Design Web's canvas or locally via Node.js.

If you integrate external APIs (e.g., Figma token sync), reference:

const figmaToken = process.env.FIGMA_ACCESS_TOKEN;

Do not hardcode secrets in DESIGN.md or scripts.

Common Issues

"CDP:UNCONFIGURED" in Specimen

Cause: DESIGN.md still has placeholders.

Fix: Edit DESIGN.md, replace placeholders with your voice, surfaces, constraints. Then:

Reassemble the design-system showcase.

Guardian Rejects Valid Component

Cause: Component not in _ds_manifest.json components array.

Fix (builder mode): Add to manifest:

{
  "components": ["Button", "Card", "Toggle"]
}

Fix (consumer mode): Request bundle maintainer to publish update.

"Mode detection failed"

Cause: No _ds_manifest.json at root and no _ds/<bundle>/ folder.

Fix: Create a minimal manifest:

{
  "name": "my-system",
  "version": "1.0.0",
  "tokens": {},
  "components": []
}

Or place a published bundle in _ds/<name>/.

Showcase Scaffold Empty

Cause: Bootstrap ran, but assemble-design-system-showcase didn't.

Fix:

Assemble the full design-system showcase from the brief.

CLI Commands (Local Validation)

# Bootstrap (detect mode, write BOUND_DS.json)
node scripts/bootstrap-harness.mjs

# Validate setup
node scripts/context-signals.mjs

# Test builder bootstrap
node scripts/test-builder-bootstrap.mjs

# Override mode
node scripts/bootstrap-harness.mjs --mode consumer

File Structure

project-root/
├── CLAUDE.md                    # Skill router
├── DESIGN.md                    # Your voice, surfaces, constraints
├── BOUND_DS.json                # Machine-readable binding (generated)
├── _ds_manifest.json            # Builder mode: tokens, components
├── _ds/                         # Consumer mode: published bundles
│   └── acme/
│       ├── DESIGN.md
│       ├── _ds_manifest.json
│       └── components/
├── skills/                      # 13 .md skill files
│   ├── harness-auto-setup.md
│   ├── design-system-guardian.md
│   ├── ui-audit.md
│   └── ...
├── scripts/                     # Bootstrap .mjs
│   ├── bootstrap-harness.mjs
│   ├── context-signals.mjs
│   └── test-builder-bootstrap.mjs
├── pages/
│   ├── intro.dc.html
│   └── design-system.dc.html    # Scaffold → full specimen
└── .cdp/
    └── showcase-brief.json      # Section inventory

Integration with Claude Design Web

All skills are invoked via natural language in Claude Design Web. The CLAUDE.md router maps user intent to skill files.

Example routing (from CLAUDE.md):

• "create a dashboard" → design-system-guardian.md
• "audit for accessibility" → accessibility-audit.md
• "assemble showcase" → assemble-design-system-showcase.md

No manual skill selection. Paste your prompt; Claude applies the right skill.

Best Practices

1. Configure DESIGN.md immediately after bootstrap — remove all CDP:UNCONFIGURED placeholders.
2. Run audits before handoff — full pass (UI, mobile, a11y, Tailwind) catches issues early.
3. Keep _ds_manifest.json updated (builder mode) — guardian can't enforce components it doesn't know.
4. Assemble the specimen once, then update sections as the system evolves.
5. Use framework handoff when ready for code — don't skip this step or engineers guess token mappings.

Further Reading

• PLAYBOOK.md — Session flows for dashboard, landing, settings pages
• LIMITATIONS.md — What this harness does and doesn't guarantee
• docs/script-pipeline.md — Deep dive on bootstrap scripts
• docs/canvas-runtime.md — How .dc.html runs inside Claude Design Web
• docs/validation-method.md — Verify your setup

---

License: MIT
Community project — not affiliated with or endorsed by Anthropic. Claude Design Web is Anthropic's product.