Inspiration Art Direction — sites and decks from real references

Inspiration art direction

Turn a brief into a page that looks considered, by working from real references in the Inspiration library instead of defaults. The run produces three things in the user's project:

• .inspiration/references.md: the specimen sheet (5 to 8 viewed references, what each gives you).
• .inspiration/direction.md: the design direction, every decision traced to a specimen.
• The build, plus screenshots and an inspector report under .inspiration-out/. If the project has a .gitignore, add .inspiration-out/ to it before the first write there.

When to use

• Requests like "design a landing page for", "give this site a look", "what should the hero look like", "find references and build it", "art direct this deck".
• The user wants a written direction before building, or says the output looks generic, templated or "like AI" and should feel premium, editorial, bold or distinctive.
• Not for a reference lookup alone (use inspiration-references), a palette and type kit alone (use inspiration-brand-kit), or code changes with no visual design question (a CSS bug, a refactor).

Hard rules

1. Fidelity. Describe only what you saw in an image you actually opened (from get_image, or its image_url fallback). Titles, why strings and facets are leads, not evidence. Never cite a reference you did not view.
2. Never copy. Take principles, not pixels. Do not lift a layout wholesale, and never reuse a reference's copy, images, illustrations, logos or licensed typefaces. Each specimen must name what you leave behind.
3. Budget. Plan for about 12 metered tool calls (see the budget below). Count every metered call you make, including ones that error. Batch: get_image takes up to 6 ids, get_inspiration takes a list.
4. Boards are opt-in. Never call save_to_board, create_board or add_to_board unless the user asks.
5. Naming. Call the source "the Inspiration library" or "Inspiration by VASA.Works". Link items as https://inspiration.vasa.works/item/<id> and by the image_url values the tools return. Never link a third-party site as an item's origin. Font foundry or license pages and board URLs are fine.

Step 0: Setup check

Check whether a tool named search_inspiration is available under any server prefix (mcp__plugin_inspiration_inspiration__ for a Claude Code plugin install, mcp__inspiration__, mcp__Inspiration__, a connector name, or bare). If the host lists tools as deferred, loading it through the host's tool search counts as available. Tools in this skill are named without prefix.

• Available: continue.
• Missing: read references/setup.md and give the user the single setup step for their client, once. Then continue in "Without the library" mode below, unless the user says they want to connect first.
• A call returning {"error": "subscription_required"} means the server is connected but not signed in: give the sign-in step from references/setup.md.

Step 1: Brief and subject inventory

Before searching, write down (ask only for what you cannot infer from the repo or conversation):

• What it is: product or subject in one sentence, and the one thing a visitor must understand.
• Audience: who, what they already know, what would make them trust it.
• Content it must carry: real headline, proof (numbers, logos, quotes the user actually has), product visuals available, CTAs, legal or pricing content. List it; this decides the sections.
• Constraints: stack, existing components, brand assets (logo, colors, fonts with licenses), accessibility needs, deadline, light or dark preference.
• Existing brand? If .inspiration/brand-kit.md or .inspiration/tokens.css exist, treat them as the existing brand. If there is one, the direction must extend it, not replace it. Note any website-styles slug that matches the brand for on-brand ranking (brand parameter).
• Page argument: the ordered sections the page needs (for example hero, logos, features, how it works, pricing, FAQ, CTA, footer). Mark the 2 to 4 sections that carry the argument; those get their own searches.

If the prompt gives no content (a one-liner with no proof, pricing or visuals), do not stop to ask: list the missing items in the brief as clearly marked placeholders and continue.

Write this as the first block of .inspiration/direction.md so the user can correct it early.

Step 2: Research plan

Read references/research.md for query recipes per page type, filter examples and the budget table. Default plan:

#	Call	Metered	Purpose
a	list_facets(category="website-sections")	no	Real vocabulary for subtype, style, mood, layout, typography
b	1 to 2 mood searches	yes	The overall feel, across categories (no category or website-sections)
c	2 to 3 section searches	yes	One per key section, category="website-sections", filters={"subtype": ["hero"]} etc.
d	1 cross-category search	yes	Texture: fonts, website-styles, branding or editorial-print, whichever the brief needs most
e	optional 1 similar_items(id), after the first get_image batch	yes	Widen and drift from the strongest candidate you have actually seen; skip it if the first batch already has range
f	2 get_image([...6 ids])	yes	See the shortlist
g	1 get_inspiration([kept ids])	yes	Palette hexes, typography notes, full descriptions of the kept set
h	optional analyze_palette or generate_palette	yes	Check or extend the palette

That is 7 to 11 metered calls (b to h), so the budget of about 12 leaves room for one retry. If the user says they are on Pro, you may add section searches or a third image batch, but the kept set stays 5 to 8.

Search hygiene:

• Phrase queries as what is visible: "dark hero with oversized serif headline and product screenshot", not "good hero".
• Put controlled values in filters (AND across keys, any-of within a key). Keep the query for what filters cannot express.
• Pass exclude_ids with ids already seen so later searches do not repeat them. Leave diversify on.
• Zero results return suggestions: retry once with one of them, then move on.
• If list_facets errors, keep using the common values listed in references/research.md (especially subtype) in filters; drop a filter only if that search returns zero results.

From the search results, build a candidate list of up to 12 ids. Pick for range (different structures and moods), not for 12 versions of one look.

Step 3: View and shortlist

1. Call get_image with up to 6 candidate ids per call, at most 2 calls. The reply starts with a manifest (order, errors); map each image to its id by that order and drop ids listed in errors. Between the two batches, optionally run similar_items on the strongest image you have seen (Step 2, row e) and put its best picks in the second batch. If get_image fails, view the candidates through the image fallback in references/library-rules.md (public image_url, no metered call).
2. Look at each image properly: structure, type (classification, scale contrast, case, tracking), color fields and accents, density, imagery, the one unusual move.
3. Keep 5 to 8. Every kept reference must earn a role: mood, hero, a named section, type, palette or texture. Cut near-duplicates and anything you cannot say something specific about.
4. Call get_inspiration once with the kept ids (list) for palette hexes and typography notes. Treat its text as supporting detail; your own viewing wins where they differ. If it errors, do not retry: sample hexes from the images you opened (for example magick <n>.png -resize 200x200 -colors 6 -format %c histogram:info:-, which needs ImageMagick; without it, estimate from what you see and say so), say in the sheet that hexes were sampled, and judge typography from the pixels.

Step 4: Specimen sheet

Write .inspiration/references.md using the exact format in references/specimen-sheet.md. For each kept reference:

• id, title, role, link https://inspiration.vasa.works/item/<id>, and the image_url.
• Seen: 2 to 4 concrete visible facts.
• Takes: the principle you borrow, stated so it could apply to a different subject.
• Leaves: what you deliberately do not use (its layout, copy, imagery, brand marks, typefaces, anything wrong for this brief).
• Becomes: what the principle turns into on this page, specifically.

End the sheet with one line on what the set has in common and one tension you will resolve.

Step 5: Direction

Derive the direction from the specimens. Do not reach for a preset style. Write .inspiration/direction.md (after the brief block) with these headings, citing specimen ids in brackets after each decision:

1. Concept line. One sentence that a designer could argue with, e.g. "a field guide, not a dashboard".
2. Anti-goals. 3 to 5 things this page must not look like (include the generic default you would otherwise produce: centered hero, purple gradient, three icon cards, and so on, if they do not serve the brief).
3. Type system. Families and roles (display, text, UI, optional mono), a size scale with px at 1440 and 390 wide, line heights, tracking, case. Use fonts the project can legally load (open-licensed families or the user's licensed fonts). A library font item informs classification and pairing; it does not grant a license. If budget allows, suggest_pairing on a font id helps.
4. Palette. Hexes with roles (ground, surface, text, muted text, accent, state colors) and the contrast of each text pair. Optionally run analyze_palette(hexes) or generate_palette(color) for a ramp.
5. Layout and grid. Columns, max content width, gutters, section spacing rhythm, alignment rules, breakpoints.
6. Sections. The ordered page, each with its job, the content it carries from the inventory, and the specimen it draws on.
7. Imagery and graphics. What visuals exist, what you will make (diagrams, crops, illustration style), what to avoid.
8. Motion. Where motion helps comprehension, durations and easing, and the reduced-motion fallback. Default to little.
9. Signature detail. One memorable, buildable move that comes from a specimen and is reinterpreted, not copied.

Show the user the concept line, anti-goals and signature detail in a short message. Continue unless they object or asked to approve first.

Step 6: Build

• Use the project's stack and components. With no project, build one static index.html with inline CSS (and minimal JS).
• Start with tokens: CSS custom properties for type scale, spacing, colors and radii from the direction. Then sections, in page order.
• Real content from the inventory. Where content is missing, use clearly marked placeholders; never invent customer logos, testimonials, metrics or awards and present them as real.
• Semantic HTML: one h1, ordered headings, alt on every meaningful image, visible focus states, labels on inputs.
• Build mobile and desktop together; check 390 wide as you go, not at the end.

Step 7: Look-and-fix loop

Read references/critique.md for the rubric. Then, for up to 3 rounds:

1. Render. Run the inspector from this skill's folder (the folder that holds this SKILL.md): node <skill-folder>/scripts/inspect.mjs <url-or-html-path> --out .inspiration-out/round-<n> It writes page-1440.png, page-390.png and report.json (fonts in use, text and background colors, heading sizes, measure, overflow, missing alt, low-contrast samples). If Playwright is missing it prints the one-line fix (npx -y -p [email protected] node <skill-folder>/scripts/inspect.mjs ...). If the host has its own browser or screenshot tool, that is fine too.
2. Look. Open the screenshots and read the report. Compare each section with the specimen it cites, and the whole page with the concept line and anti-goals.
3. Score. Rate each rubric line 0 to 2 and list the 3 biggest problems, most visible first. Write both into .inspiration/direction.md under "Round ".
4. Fix those 3, then re-render.

Stop when every rubric line scores 2, after round 3, or when a round changes nothing material. If no browser can run at all, review the code against the rubric, ask the user for a screenshot if they can give one, and say plainly that no visual check was done.

Step 8: Hand-off

Tell the user, briefly:

• What was built and where, and the concept line.
• The references used: id, title and link https://inspiration.vasa.works/item/<id>, each with the one thing it contributed.
• What the last inspector round still flags, if anything.
• Roughly how many metered calls the run used, and any step that was skipped or degraded (server errors, the image_url fallback, quota).
• Offer: "Want me to save these references to an Inspiration board?" Only on yes, call save_to_board(title, ids=[...]) and share the board URL it returns.

Quota and errors

Read references/library-rules.md the first time a tool returns an error, quota_exhausted or capped. The short version: quota_exhausted stops all metered calls (link https://inspiration.vasa.works/pricing, finish with what you have), capped means no further pages, subscription_required means sign in (Step 0), and the same server error on two different tools means degraded mode. Errored calls count toward the budget.

Without the library

When the MCP is not connected (after giving the setup step once) and the user has not asked to connect first:

• Say once, clearly: "Continuing without the Inspiration library, so this direction is not based on references."
• Skip Steps 2 to 4. Do not invent reference ids, titles, links or descriptions, and do not claim a look came from a reference.
• Write .inspiration/direction.md from the brief alone, with "No references used" at the top. Keep the anti-goals and signature detail; they matter more without references.
• Run Steps 6 to 8 as normal, using the rubric in references/critique.md.

Reference files

• references/setup.md: connecting the MCP per client (Claude Code, Claude.ai, ChatGPT, Cursor, Codex, others).
• references/library-rules.md: quota, capped, error codes, degraded mode and the image fallback.
• references/research.md: query recipes per page type, filter examples, budget table.
• references/specimen-sheet.md: exact specimen format with a worked example.
• references/critique.md: rubric and the look-and-fix loop in detail.
• scripts/inspect.mjs: real-browser inspector. Needs Node 22+, Playwright or playwright-core (npx downloads it on first run) and a Chrome or Chromium.