From 8d79f1e5dce095650afd650e6c5bbe11dd7c355c Mon Sep 17 00:00:00 2001 From: Kjell Tore Guttormsen Date: Mon, 18 May 2026 21:28:31 +0200 Subject: [PATCH] =?UTF-8?q?docs(claude-design):=20polish=20README=20?= =?UTF-8?q?=E2=80=94=20Why=20this=20exists=20+=20workflow=20example=20+=20?= =?UTF-8?q?recent=20versions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add three sections to bring README depth closer to marketplace standard (was 206 lines, smallest in marketplace; now 298): - "Why this exists" — names the convergent-middle-ground problem in Claude Design, cites Anthropic's frontend-aesthetics cookbook as primary source, explains the five-layer prompt scaffold and the plugin's interactive role - "Workflow example: from idea to prompt" — realistic 8-phase walkthrough against the slides preset (Q1 results all-hands deck), including a ~30-line sample prompt block showing what Phase 6 actually delivers - "Recent versions" — v0.1.0 summary + CHANGELOG.md pointer + v1.0 readiness criteria pointer to REMEMBER.md No feature changes; pure docs polish. verify.sh passes 41/0/1 (the 1 warn is the expected SC1 dogfood-missing advisory until operator runs first real Claude Design session). Co-Authored-By: Claude Opus 4.7 --- plugins/claude-design/README.md | 92 +++++++++++++++++++++++++++++++++ 1 file changed, 92 insertions(+) diff --git a/plugins/claude-design/README.md b/plugins/claude-design/README.md index 391e7ae..2473f93 100644 --- a/plugins/claude-design/README.md +++ b/plugins/claude-design/README.md @@ -18,6 +18,18 @@ A Claude Code plugin that ships one skill (`claude-design-facilitator`) plus a r --- +## Why this exists + +Claude Design has a strong gravitational pull toward convergent middle-ground output. A one-line prompt like *"make me a slide deck for Q1 results"* reliably produces what Anthropic's own cookbook for [prompting frontend aesthetics](https://platform.claude.com/cookbook/coding-prompting-for-frontend-aesthetics) names as the failure mode: Inter or Roboto typography, white-to-purple gradients, evenly-spaced cards, cramped layouts that read as AI-generated. The convergence is not random — it is what the model defaults to when prompts are underspecified. + +The fix is in the prompt itself, not in the artifact. Anthropic publishes a five-layer prompt scaffold across three primary sources — the Goal / Layout / Content / Audience framework in the [Claude Design launch post](https://anthropic.com/news/claude-design-anthropic-labs) and [Get started article](https://support.claude.com/en/articles/14604416-get-started-with-claude-design), the DESIGN.md anchor in the [design system article](https://support.claude.com/en/articles/14604397-set-up-your-design-system-in-claude-design), and the AI-slop avoid-list plus cultural-reference anchoring in the [aesthetics cookbook](https://platform.claude.com/cookbook/coding-prompting-for-frontend-aesthetics). Assembling a prompt that actually uses all five layers, with the right per-preset pattern, in the right order, takes deliberate scaffolding most operators do not do unprompted. + +This plugin does the scaffolding interactively. The `claude-design-facilitator` skill walks the operator through eight phases, surfaces the questions that produce a workable Goal / Layout / Content / Audience answer, anchors on DESIGN.md if one exists or extracts one if not, composes the five layers in the right order, and outputs a copy-paste prompt the operator pastes into `claude.ai/design`. The artifact gets built in Claude Design; this plugin produces the prompt. + +The output is honest about what it is. Every authoritative claim cites an Anthropic primary source inline. Community patterns are labelled and attributed. The `frontier-design` preset is flagged Experimental rather than dressed up as canonical. The plugin recommends Anthropic's official [`knowledge-work-plugins/design`](https://claude.com/plugins/design) for everything that happens after the artifact is generated — there is zero command overlap by design. + +--- + ## Scope and complementarity This plugin covers the **pre-design and during-design lifecycle** for `claude.ai/design`: idea → intent-preset selection → prompt engineering → copy-paste delivery → iteration coaching → ship-readiness check. @@ -95,6 +107,78 @@ Explicit invocation works too: the skill registers as the slash command `/claude --- +## Workflow example: from idea to prompt + +A realistic session against the `slides` preset — Q1 results deck for an internal engineering all-hands. + +**Operator:** *"I want to build a Q1 results slide deck for the engineering team in Claude Design."* + +The skill auto-fires (the phrase matches `.triggers.txt`). It walks the eight phases: + +**Phase 1 — Disambiguate the surface.** The skill confirms `claude.ai/design` is the intended surface, not classic Artifacts or Live Artifacts. The operator confirms. + +**Phase 2 — Name the intent preset.** Slide deck → `slides` preset. The skill notes this is one of three Anthropic-documented presets (evidence-grade label surfaced from `.coverage.md`). It opens [`references/presets/slides.md`](skills/claude-design-facilitator/references/presets/slides.md) and surfaces the five canonical Anthropic patterns (Q1 results, executive roadmap, customer-prep briefing, partner proposal, all-hands announcement). The operator picks pattern 1. + +**Phase 3 — Audience and destination.** Internal engineering team; deck stays in HTML preview during the meeting, optional PPTX export to share with adjacent leads afterward. The skill flags the PPTX-export trap from [`references/presets/slides.md`](skills/claude-design-facilitator/references/presets/slides.md) section (e): fonts substitute, master slides drop, charts may flatten to images. If a brand-compliant PPTX template exists, upload it to Claude Design as a project asset before prompting — Claude reads the slide master, layouts, fonts, and colour scheme and respects them ([PowerPoint-mode article](https://support.claude.com/en/articles/13521390-use-claude-for-powerpoint)). + +**Phase 4 — Anchor on DESIGN.md.** The operator has no DESIGN.md yet. The skill points at the brand-to-DESIGN.md extractor prompt in [`references/02-design-md.md`](skills/claude-design-facilitator/references/02-design-md.md): paste a brand-guidelines URL or PDF into Claude.ai, get back a DESIGN.md filling the nine canonical sections (typography, colour, spacing, layout primitives, motion, voice, imagery, density, accessibility). The operator runs the extractor against the company's brand site, gets a DESIGN.md, drops it into the Claude Design project assets. + +**Phase 5 — Draft the prompt.** The skill composes the five layers from [`references/01-prompt-fundamentals.md`](skills/claude-design-facilitator/references/01-prompt-fundamentals.md): Goal / Layout / Content / Audience (Layer 1) → start-simple-layer-complexity (Layer 2) → concrete-alternative-spec (Layer 3) → AI-slop negative constraints (Layer 4) → per-preset pattern from `presets/slides.md` (Layer 5). The skill produces a single copy-paste fenced block. The operator inspects it, optionally edits the Goal sentence, then proceeds. + +**Phase 6 — Deliver.** The skill outputs the prompt block. The structure of a realistic delivery for this scenario looks like: + +``` +**Goal:** Communicate Q1 engineering results to the all-hands — +where we started, what changed, what we shipped, what we learned, +what's next for Q2. The deck should land as confident but honest: +real numbers, named risks, no victory-lap framing. Audience is +~80 engineers across three teams. Density should be high enough +to skim later, low enough to follow live. + +**Layout:** 10–12 slides, slide-by-slide: +1. Title + Q1 in one sentence +2. The three things we shipped (one per row, screenshot + metric) +3. The two things that slipped (named honestly, with the why) +4. Hiring update (count + retention) +5. Reliability (incident count, MTTR trend) +6. Customer signal (NPS + 2 verbatim quotes) +7. Engineering health (PR throughput, review latency) +8. The big bet for Q2 (one slide, named) +9. Risks for Q2 (3 bullets, ranked) +10. Asks from the all-hands (1–3 specific asks) +11. Q&A placeholder + +**Content:** Use the metrics in DESIGN.md's `tone` section — direct, +specific, no marketing voice. Numbers are placeholder; I'll edit +before the meeting. + +**Audience:** Internal engineering all-hands, 80 people, ICs through +EM/Director level. They want to know: did we ship what we said, what +broke, what's next, can I help. + +**Avoid:** Inter or Roboto, white-to-purple gradients, evenly-spaced +generic card layouts, "exciting Q1!" framing, congratulatory tone, +stock-photo gradients, generic icon library defaults. + +**Anchor:** Match the DESIGN.md uploaded as a project asset. If our +brand voice reads as understated technical, push the deck that way — +not the convergent SaaS-marketing deck aesthetic. + +**Reference:** Treat this as the Q1 results pattern from +https://claude.com/resources/tutorials/using-claude-design-for-presentations-and-slide-decks +(pattern 1), with the Layout above overriding the tutorial's slide count. +``` + +That block is what gets pasted into `claude.ai/design`. The skill also surfaces three to five expected follow-up turns (e.g., *"the headline slide is too marketing, push it more technical"*, *"slide 5 reliability — show the MTTR trend as a sparkline, not a bar chart"*) so the operator knows what iteration looks like before starting. + +**Phase 7 — Iteration coaching.** Once Claude Design produces the first version, the skill points the operator at the Tweak → Comment → Chat cascade in [`references/03-iteration-and-session.md`](skills/claude-design-facilitator/references/03-iteration-and-session.md): Tweak panel for surgical zero-token edits (spacing, font size, colour), inline comments for component-scoped changes (rewrite slide 5), full chat regeneration as a last resort. Plus the session-break heuristic (after 4 substantive screens, start a fresh session with a verbal save-pattern carrying state forward) and the recovery prompt library when iteration gets stuck. + +**Phase 8 — Ship-readiness.** Before the all-hands, the skill runs the export validation checklist for the chosen destination (HTML preview → keep in Claude Design; PPTX → check fonts and master, charts may flatten). If the deck is being handed off to engineering for any reason, it recommends installing [`knowledge-work-plugins/design`](https://claude.com/plugins/design) for `/critique`, `/accessibility`, and `/handoff` — the post-design lane. + +The full output of the session is a single fenced markdown block (Phase 6) plus a short follow-up-turns list and an iteration-coaching pointer. That is the entire user-facing deliverable. + +--- + ## Skill surface | Skill | Triggers | Output | @@ -201,6 +285,14 @@ When a trigger fires, run `bash verify.sh --strict` after the update to confirm --- +## Recent versions + +**v0.1.0 — 2026-05-17.** Initial public release. Single skill (`claude-design-facilitator`) with eight-phase facilitation flow, 12 natural-language trigger phrases, 13 reference files (5 foundation + 8 per-preset with evidence-grade labels), `.coverage.md` preset manifest plus Authoritative-claims registry, five verification scripts under `tests/` enforcing structural integrity / scope fence / skill description quality / per-preset coverage / Anthropic-domain citation discipline / operator dogfood log format, top-level `verify.sh` roll-up with `--strict` and `--quick` flags, MIT license, GOVERNANCE.md fork-and-own model. + +Full release history: [`CHANGELOG.md`](CHANGELOG.md). The plugin follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html). The path from v0.1 to v1.0 is dogfood-driven — see the plugin's `REMEMBER.md` for the v1.0 readiness criteria (multi-preset breadth, auto-fire validation in real natural-language requests, two consecutive dogfood sessions with zero critical patches). + +--- + ## License [MIT](LICENSE). Fork it, modify it, ship your own version under your own name.