claude-design-premium-harness

# Claude Design Premium Harness > Skill by [ara.so](https://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 ```bash # 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: ```text 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: ```text 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): ```markdown # 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`): ```markdown # 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. ```json { "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: ```json { "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:** ```text 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):** ```text Create a settings page for user preferences using our design system. ``` Guardian intercepts, validates tokens, suggests fixes: ```text ✓ 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:** ```text 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:** ```text 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:** ```text Create a framework handoff for this landing page in React + Tailwind. ``` Output: ```markdown ## 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: ```text GO ``` Then configure `DESIGN.md`: ```markdown # 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: ```text 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: ```text Copy all files from the claude-design-premium folder to the project root. ``` New tab: ```text GO ``` Bootstrap detects `_ds/acme/_ds_manifest.json`, sets mode to `consumer`, binds to `_ds/acme/DESIGN.md`. Build a screen: ```text 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: ```text 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: ```text Create a framework handoff for React + Tailwind. ``` ### Pattern 4: Maintain the Specimen Your DS evolves. Update `_ds_manifest.json` (new components), then: ```text 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` ```javascript 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: ```bash node scripts/bootstrap-harness.mjs # Output: ✓ BOUND_DS.json written ``` Override mode: ```bash node scripts/bootstrap-harness.mjs --mode builder ``` ### `scripts/context-signals.mjs` Validates setup: checks for `CLAUDE.md`, `DESIGN.md`, `BOUND_DS.json`. ```bash 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. ```bash 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: ```javascript 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: ```text Reassemble the design-system showcase. ```