diff --git a/plugins/claude-design/skills/claude-design-facilitator/references/01-prompt-fundamentals.md b/plugins/claude-design/skills/claude-design-facilitator/references/01-prompt-fundamentals.md new file mode 100644 index 0000000..bb927fa --- /dev/null +++ b/plugins/claude-design/skills/claude-design-facilitator/references/01-prompt-fundamentals.md @@ -0,0 +1,265 @@ +# Prompt fundamentals — the five-layer stack + +**Last updated:** 2026-05-17 | **Verified:** research/03-prompt-patterns-intent-presets.md +**Status:** Beta (Labs research preview) +**Captured-on date:** 2026-05-16 + +This file documents the universal prompt framework an operator applies across every Claude Design intent preset. The five layers compose into one prompt block. Layers 1 to 3 are load-bearing for every preset; layers 4 and 5 are the refinement turn. + +Every authoritative claim cites an Anthropic primary source. Where community practice extends an Anthropic concept, the extension is labelled and attributed. + +--- + +## Layer 1 — Goal / Layout / Content / Audience (GLCA) + +Anthropic's verbatim framework for every Claude Design prompt. The framework is published in the get-started support article `https://support.claude.com/en/articles/14604416-get-started-with-claude-design`. Anthropic's framing: a good Claude Design prompt names the **Goal**, the **Layout**, the **Content**, and the **Audience**, in that order, before any aesthetic specification. + +The four canonical questions: + +- **Goal** — what is the artifact for? "An admin dashboard for monitoring API latency", "an onboarding flow for first-time users", "a landing page that converts free trial signups". One sentence. +- **Layout** — what is the page structure? Header / hero / metrics row / table / footer; or: hero / three-feature-grid / pricing table / CTA. Name the regions. +- **Content** — what fills the regions? Real data placeholders if you have them, named labels if not. Avoid generic "lorem ipsum" — the model defaults to convergent middle-ground content if you do not constrain it. +- **Audience** — who reads or uses this artifact? Internal team, external stakeholder, B2B procurement, B2C consumer, investor. Audience determines tone, density, and aesthetic. + +Anthropic publishes three verbatim canonical examples in the same support article: + +``` +Goal: An analytics dashboard for our customer success team +Layout: Top metrics row (4 KPIs), main chart panel, recent activity table +Content: Today's MRR, 30-day churn, NPS, expansion revenue; revenue chart; + the last 10 account events +Audience: Internal CS leads — they're in this thing every day, want density + and signal, not flashy +``` + +``` +Goal: A mobile onboarding flow for a new fitness app +Layout: Welcome screen, goal-selection (3 cards), motion preference, sign-in +Content: Headlines, single CTA per screen, accessible touch targets +Audience: First-time users, gym beginners, ages 25-45 +``` + +``` +Goal: A SaaS landing page that converts free trial signups +Layout: Hero, three-feature grid, social proof, pricing table, FAQ, footer CTA +Content: Product name placeholder "ProductX", real headline benefit copy, + three feature blurbs (icon + headline + line) +Audience: B2B technical buyers evaluating dev tools +``` + +The GLCA framework is sufficient on its own for a first prompt at intent preset `designs`. For other presets, GLCA composes with the per-preset pattern in `references/presets/.md`. + +Source: `https://support.claude.com/en/articles/14604416-get-started-with-claude-design`. + +--- + +## Layer 1.5 — Start simple, layer in complexity + +The same Anthropic get-started article publishes verbatim incremental-prompting advice: do not ship a 600-word first prompt. Ship a 120-word first prompt that names GLCA, see what Claude Design produces, then add complexity in turn two and turn three. + +Anthropic frames this as the dominant failure mode for first-time Claude Design operators: over-specifying the first prompt produces an output that is dense but generic. The remedy is staged — let Claude Design make its default choices, then react to what it produces with targeted constraints. + +This frames how the rest of the stack composes. In turn one, ship layers 1 + 2a (or 2b) + 3. In turn two, add layer 4. In turn three, add layer 5 emphasis-weighting. + +Source: `https://support.claude.com/en/articles/14604416-get-started-with-claude-design`. + +--- + +## Layer 2a — Concrete-alternative-spec house-style control + +The first of two Anthropic-documented house-style controls. Verbatim guidance from `https://platform.claude.com/docs/en/docs/build-with-claude/prompt-engineering/claude-4-best-practices`: name a concrete aesthetic family with explicit visual primitives rather than gesturing at a style. + +The Anthropic-published exemplar — the AEFRM (Anthropic Engineering Field Reference Material) example — is verbatim usable: + +``` +Aesthetic family: industrial-utilitarian, slate-monochrome +Color palette (CSS hex): + --color-bg: #E9ECEC + --color-surface: #C9D2D4 + --color-muted: #8C9A9E + --color-fg: #44545B + --color-ink: #11171B +Typography: square angular sans-serif (Söhne, Inter Variable as fallback); + no rounded glyphs; weight 500 for body, 700 for headers +Corner radius: 4px throughout — no fully rounded buttons, no pill shapes +Motion: transition: all 160ms ease-out on hover; no springy easing +Density: dense (table rows 32px tall; padding 8px on cards) +Surface: flat — no shadows, no glassmorphism +``` + +The control works because Claude Design reads this as a concrete brief and constrains its aesthetic decision space accordingly. Without an explicit concrete-alternative-spec, the model defaults to its convergent middle-ground aesthetic (rounded corners, generous spacing, friendly typography, gentle shadows — Anthropic's documented "AI-slop" default). + +The hex palette, corner radius, and motion timing are all required — naming "industrial-utilitarian" alone is gesturing, not specifying. + +Source: `https://platform.claude.com/docs/en/docs/build-with-claude/prompt-engineering/claude-4-best-practices`. + +--- + +## Layer 2b — Propose-options-before-building + +The second Anthropic-documented house-style control, also from `https://platform.claude.com/docs/en/docs/build-with-claude/prompt-engineering/claude-4-best-practices`. When the operator does not know exactly which aesthetic to brief, Anthropic publishes a verbatim prompt template asking Claude Design to propose four distinct visual directions before committing to one. + +The verbatim prompt: + +``` +Before building the dashboard, propose 4 distinct visual directions. +For each, give: + - bg hex + - accent hex + - typeface (named, not gestured) + - one-line rationale tying the direction to the audience and goal + +Wait for me to pick a direction before generating the artifact. +``` + +This forks the conversation: turn one returns four named directions, the operator picks one, turn two generates against the chosen direction. The cost is one extra round; the upside is the operator avoids the dead-end of generating against an aesthetic that does not fit and only finding out after generation. + +Use layer 2b when layer 2a is not feasible (the operator does not yet know the aesthetic). Use layer 2a when the aesthetic is known. + +--- + +## Layer 3 — AI-slop avoid-list (negative constraints) + +Anthropic publishes a verbatim banned-items list in `https://claude.com/blog/improving-frontend-design-through-skills` and reinforces it in the open-source frontend-design skill at `https://github.com/anthropics/skills/skills/frontend-design/SKILL.md`. The list names the convergent middle-ground patterns that Claude Design defaults to when underspecified. + +Anthropic's verbatim AI-slop fingerprints to avoid: + +- **Typography slop:** Inter, Roboto, Arial as default body font. Space Grotesk is flagged as overused. Default to a concrete-named typeface in the brief, not a generic sans-serif. +- **Color slop:** purple gradients on white backgrounds; solid-color hero backgrounds; convergent middle-ground palettes (the muted blue-and-grey "professional" default). +- **Layout slop:** cookie-cutter three-column feature grids; centered-hero-with-CTA defaults; full-width-image-with-text-overlay defaults. +- **Motion slop:** scattered micro-interactions; bouncy spring easing on hover; pulse animations on idle elements. +- **Complexity-to-vision mismatch:** ornate components on simple layouts; flat components on otherwise rich layouts. + +Operator-actionable copy-paste anti-prompt block (composes with layers 1 and 2): + +``` +Negative constraints — do not produce any of: + - Inter, Roboto, Arial, or Space Grotesk as the primary typeface + - Purple gradients on white backgrounds + - Solid-color hero backgrounds + - Three-column feature grids with icon + headline + line + - Centered-hero-with-single-CTA layout default + - Bouncy spring easing on hover transitions + - Pulse / breathing animations on idle elements + - Glassmorphism, neumorphism, or generic "modern SaaS" defaults + +If you find yourself defaulting to any of these, stop and ask me to +clarify the aesthetic before continuing. +``` + +Sources: `https://claude.com/blog/improving-frontend-design-through-skills` and `https://github.com/anthropics/skills/skills/frontend-design/SKILL.md`. + +--- + +## Layer 4 — Four design dimensions to optimize + +Anthropic's verbatim per-dimension guidance from `https://github.com/anthropics/skills/skills/frontend-design/SKILL.md`. Four dimensions to brief explicitly when refining beyond the first turn: + +- **Typography** — name typeface, modular scale (e.g., 1.250 minor third or 1.333 perfect fourth), weight palette, line-height palette, letter-spacing for headings. Anthropic's frontend-design SKILL.md publishes specific modular scales and weight palettes verbatim. +- **Color** — beyond palette hex, specify semantic roles (background, surface, accent, muted, error, success). Define interaction states explicitly (hover, active, disabled, focus). Anthropic's guidance: avoid relying on opacity for state changes; use explicit color tokens. +- **Motion** — name easing curves (ease-out, cubic-bezier values), name durations (120ms / 160ms / 240ms tiers), name what gets animated and what does not. Anthropic's guidance: motion should clarify hierarchy and confirm interaction; avoid decorative motion. +- **Backgrounds** — flat surface vs depth, when to layer surfaces, when shadows or borders define edges. Anthropic's guidance: backgrounds carry meaning; the bare-default-white background is rarely the right choice. + +In turn two of an iteration, add layer-4 dimension specs to the brief. In turn three, refine the dimension that drifted most from intent. + +Source: `https://github.com/anthropics/skills/skills/frontend-design/SKILL.md`. + +--- + +## Layer 5 — Four design grading criteria + +Anthropic publishes verbatim grading criteria for design quality in `https://anthropic.com/engineering/harness-design-long-running-apps`. Four criteria, used as emphasis weights: + +- **Design quality** — does the artifact look intentional, not defaulted? Is the aesthetic coherent across regions? +- **Originality** — does the artifact avoid the convergent middle-ground? Does it surprise without being weird? +- **Craft** — does the artifact feel detailed and considered at every level — typography, spacing, alignment, hierarchy, color? +- **Functionality** — does the artifact work for its goal and audience? Would it survive a usability test or a stakeholder review? + +Anthropic's emphasis-weighting recommendation: in the prompt, weight which criterion matters most for *this* artifact. A dashboard for internal use weights functionality and craft highest. A pitch deck for an external investor weights design quality and originality highest. A wireframe for early exploration weights functionality highest with craft and originality deprioritized. + +Operator-actionable layer-5 block: + +``` +Grading criteria for this artifact, in priority order: + 1. {craft|design quality|originality|functionality} — weight 0.4 + 2. {one of the others} — weight 0.3 + 3. {one of the others} — weight 0.2 + 4. {the remaining one} — weight 0.1 + +Optimize against this ordering. If the artifact has to trade off, +trade off the lowest-weighted criterion first. +``` + +The non-monotonic-improvement caveat applies — Anthropic notes that quality across iterations is not strictly increasing. If turn three is worse than turn two on a critical criterion, the recovery move is documented in `references/03-iteration-and-session.md` ("pivot to an entirely different aesthetic if the approach wasn't working"). + +Source: `https://anthropic.com/engineering/harness-design-long-running-apps`. + +--- + +## How the layers compose into one prompt + +A worked example for the `designs` intent preset, dashboard, three turns: + +### Turn 1 — layers 1 + 2a + 3 (the first prompt) + +``` +Goal: An admin dashboard for monitoring API latency by route, by region, + and by P50/P95/P99 +Layout: Header with environment switcher; top metrics row (4 KPIs: + global P95, error rate, throughput, active requests); main chart + (time series, P50/P95/P99 lines); routes table with sortable + latency columns; alerts sidebar +Content: KPI placeholders are real metric names; chart uses synthetic + 24-hour data; table has 12 routes with realistic paths + (/api/v1/users, /api/v1/orders, etc.) +Audience: Platform engineers, on-call rotation, ages 25-45, + comfortable with dense interfaces + +Aesthetic family: industrial-utilitarian, slate-monochrome +Color palette (CSS hex): + --color-bg: #E9ECEC + --color-surface: #C9D2D4 + --color-muted: #8C9A9E + --color-fg: #44545B + --color-ink: #11171B +Typography: square angular sans-serif (Söhne, Inter Variable fallback); + no rounded glyphs +Corner radius: 4px throughout +Motion: transition: all 160ms ease-out +Density: dense (32px table rows, 8px card padding) +Surface: flat — no shadows + +Negative constraints — do not produce any of: + - Inter, Roboto, Arial, or Space Grotesk as primary typeface + - Purple gradients on white backgrounds + - Pulse animations on idle elements + - Glassmorphism, neumorphism, generic "modern SaaS" defaults +``` + +### Turn 2 — add layer 4 dimensions + +Operator reacts to turn-1 output by adding typography modular scale, semantic color roles, motion easing, and surface-depth rules. + +### Turn 3 — add layer 5 weighting + +Operator specifies that craft and functionality are the two highest-weighted criteria for this dashboard; design quality is third; originality lowest. + +### Turn 4+ — Tweak panel takes over + +Most subsequent refinements happen in the Tweak panel (per-artifact Claude-generated controls; zero-token surgical edits) — see `references/03-iteration-and-session.md` for the surface cascade. + +--- + +## Source map + +The five layers anchor on four Anthropic primary sources plus one open-source skill: + +| Layer | Anthropic source | +|-------|------------------| +| 1, 1.5 | `https://support.claude.com/en/articles/14604416-get-started-with-claude-design` | +| 2a, 2b | `https://platform.claude.com/docs/en/docs/build-with-claude/prompt-engineering/claude-4-best-practices` | +| 3 | `https://claude.com/blog/improving-frontend-design-through-skills` + `https://github.com/anthropics/skills/skills/frontend-design/SKILL.md` | +| 4 | `https://github.com/anthropics/skills/skills/frontend-design/SKILL.md` | +| 5 | `https://anthropic.com/engineering/harness-design-long-running-apps` | + +Re-research trigger: any of the four URLs returning 404 or shifting content materially; Anthropic publishing a sixth layer or revising any of the five. Captured-on date 2026-05-16 — the layer-1 framework has been stable since the launch announcement.