Showpiece

showpiece

Studio-grade websites and presentations that a person will actually ship or send. This skill is an orchestrator: it does not replace frontend-design, it stands on top of it and adds the three things a one-shot prompt lacks: a real design decision before any code, design DNA pulled from concrete references, and a verify-loop where the model looks at its own rendered output and fixes it.

When this fires (and when it must not)

The boundary between this skill and frontend-design is ambition, not topic.

• Use showpiece for artifacts that get shipped or sent: a real website, a portfolio, a landing page, a client-facing deck, "make my X properly good".
• Use frontend-design (do not fire showpiece) for quick mockups, a single HTML snippet, a small UI tweak, or visualizing a report/research output. Those must stay fast and cheap.

If a request is ambiguous, ask one question: "is this a throwaway mockup or something you want to ship?" The answer decides.

The pipeline

Run these stages in order. Explain to the user which stage you are in; do not silently jump to code.

0. Lock the brief

Before any design or code, commit to the four frontend-design questions: Purpose, Audience, Tone, Differentiation. Write them down in one short block. A vague brief is the single biggest cause of generic output, so this is not optional even when the user is in a hurry.

Then collapse the brief into one Design Read line you can be held to: "Reading this as: for , in a language, leaning <system/aesthetic>." Ask at most one clarifying question; past that, decide with judgment and move. This turns "note four answers" into a testable declaration and avoids both guessing and question-dumps.

1. Decide the design system (taste + structure)

Two inputs combine here:

1. Structured options from the vendored UI/UX Pro Max database. Run its offline generator to get a full recommendation (layout pattern, palette with hex tokens, typography, spacing, plus the Variance/Motion/Density dials):

   cd ~/.claude/skills/showpiece
   python3 references/uupm/scripts/search.py "<one-line description of the site>" \
     --design-system --project-name <slug> --variance <1-10> --motion <1-10> --density <1-10>
   

   Run it from the skill root (the references/ path is relative). On Windows, use python (or py) instead of python3.

   Use --domain for a narrow lookup (valid in this vendored subset: style, color, chart, landing, product, ux, typography, icons, gsap, react, web) and --stack for framework-specific guidance. Full interface and examples: references/uupm-brain.md.

2. Taste and anti-slop from frontend-design. This is the arbiter. Where the database suggests something generic, frontend-design overrides it. Concretely: the UUPM generator will sometimes propose default fonts (Inter, Roboto) or a safe palette. frontend-design explicitly bans the generic AI look, so treat UUPM's palette/dials/layout as the skeleton and commit to a bold, specific typographic and color direction on top. Never ship Inter-on-white with a purple gradient.

Art-direction source: decide this explicitly on every ship-grade website run. Choose one of three sources and state the choice to the user before any code. The point is that showpiece makes this call, not the user's wording.

1. Claude Design amplifier run (the default proposal for real websites): freeze the copy first (FROZEN blocks), send a killer brief, and let the returned bundle BE the art direction that the following stages engineer. Run it per the claude-design-handoff skill's web track if that skill is installed. Proven on a real production portfolio build (2026-07): the code-only design was solid but unremarkable, the design run delivered the missing level, and running it AFTER the build cost a full re-port of all sections. It costs the user one paste into Claude Design plus sharing the link back, so put it in the plan as the default and let them opt out.
2. A known design system (Fluent, Material, Carbon, GOV.UK, USWDS, shadcn, Radix): use the official package (see the bullet below).
3. Self-directed (UUPM skeleton + frontend-design taste): when the user declines the design run, the artifact is a deck or internal, or the timeline cannot absorb the round-trip through the user.

When option 1 is chosen the pipeline reorders: lock brief -> freeze content -> design run -> stages 2-5 turn into engineering the bundle (MOTION comments to GSAP, real functionality, fallbacks, measured contrast). UUPM and reference DNA still run, but their output feeds the brief's locked design system instead of being the final art direction, and the stage-4 verify-loop compares the build against the bundle. The stage-6 hand-off link then only serves optional last-mile tweaks.

Two more decisions belong here:

• Set the three dials from the brief, not by default. Translate the vibe words into explicit numbers (calm editorial -> low variance, low-mid motion, low density; bold agency -> high across), pass them to the generator, and then hold every section to them. Ambition fixed in numbers before any code beats "make it nice" after.
• If the brief IS a known design system (Fluent, Material, Carbon, GOV.UK, USWDS, shadcn, Radix), use the official package rather than hand-rolling its look. UUPM gives a palette/type skeleton, not a faithful system, so do not reinvent one that already ships.

Persist the decision as design tokens (CSS variables) in the project so every section stays consistent. The UUPM generator can write a design-system/MASTER.md with --persist if useful.

2. Extract design DNA from references

Great output copies structure from great examples, not from imagination. If the user names or implies reference sites, or hands over a reference video, pull concrete DNA rather than describing it from memory:

• Live sites (Awwwards / Godly / Land-book / a competitor): scrape them or screenshot them with your browser tooling (Playwright MCP works), and read off real colors, type scale, spacing, and layout.
• A reference video the user gave you: extract a transcript plus frames with whatever video tooling is available, then read the frames. This is often the freshest signal, newer than any blog.
• Feed 2 to 3 references in as concrete artifacts, never as "make it modern".

Skip this stage only if the user gives no references and wants a purely original direction.

3. Build section by section

Build Hero, then the next section, then the next. Do not generate the whole page in one shot; it hides layout and spacing errors that only surface section by section. Keep to the persisted tokens.

For a real website (not a deck), motion is part of the build, not a nice-to-have. A static styled page reads as a slide; a site feels alive: scroll-driven parallax, a pinned/scrubbed section where content zooms or dissolves as you scroll, reveal-on-scroll, a living background (an animated canvas field, not a flat color). All of this is pure HTML/CSS/JS and needs no generated imagery, so do not wait on the stage-5 asset step to make a site feel cinematic. Only photographic hero art actually needs fal.ai. Always build the motion behind prefers-reduced-motion with a full static fallback, so reduced-motion and no-JS users get the calm version and everyone else gets the alive one.

The concrete menu (Lenis, GSAP pin/scrub, clip-path reveals, canvas image-sequence, WebGL), the skeletons, the gotchas, and the performance guardrails are in references/motion-patterns.md. A library (GSAP, Lenis, Three.js) is often the fastest path to the "half video" feel, but never add one without the user's explicit go, and show the official repo link first (a hard security rule in this skill). Moves 1-3 there already reach a high bar with pure code plus at most one library.

4. Verify-loop (the part a raw prompt skips)

This is where studio quality actually comes from. frontend-design has no self-review; showpiece adds it. After each meaningful section, and again for the whole page:

1. Render it and screenshot with the Playwright MCP (the standard QA tool for this pipeline).
2. Do not ask yourself "is this good?". Compare the screenshot against the design intent and the reference, and list the concrete deviations: wrong type scale, off palette, uneven spacing, broken alignment, weak hierarchy, accessibility/contrast issues.
3. Fix them, re-render, repeat. Two to three passes is the sweetspot; stop when the list is cosmetic. Screenshot only where it earns its cost.

Run the anti-slop pre-flight (references/anti-slop-checklist.md) as part of the deviation pass: a mechanical list of the tells that make a page read as machine-made (rationed eyebrows, fake-precise numbers, zigzag/marquee caps, contrast fails, default palettes). Include a copy self-audit: re-read every visible string and cut hallucinated "cute" copy and invented statistics.

Details and deviation checklists: references/verify-loop.md and references/anti-slop-checklist.md.

5. Assets (fal.ai, wired)

Generate the one or two moments that genuinely need photographic or illustrated art (a hero plate, a texture, an image-sequence source) via fal.ai. Pure CSS/canvas art needs none of this, so do not block the build on it. The committed model choice, the REST call, and the full generate-look-regenerate discipline are in references/image-gen.md. The core rule: think the prompt hard first, generate at most 2 attempts per image, look at the result and judge it against the intent, keep it if it matches or revise the prompt once if it clearly misses. The FAL_KEY is set by the user; never ask for it in chat.

6. Claude Design hand-off link

For a finished, ship-grade artifact, produce a Claude Design link at the end so the user can do optional last-mile fine-tuning themselves in Claude Design. The user never has to use it; it just sits ready. If stage 1 chose the Claude Design amplifier run, that run was the design phase and this link is pure last-mile polish; on the self-directed path the user does not touch Claude Design during the build at all. Either way showpiece does the build A to Z autonomously and only hands over the link at the finish.

The exact mechanism (the DesignSync tool via the user's claude.ai login, or driving Claude Design in the browser) is documented in references/claude-design-link.md. It is marked best-effort; validate it on your first real run before promising it as guaranteed.

Slides and presentations

Same pipeline, different substrate. For a premium one-off deck, build an HTML deck (Reveal.js) and run the same design-decision and verify-loop stages over it. If the user needs an editable handoff for a non-coder, prefer the official pptx skill instead of HTML. Decide by asking whether the recipient needs to edit it.

Guardrails

• Kill the generic AI look: no default fonts, no purple-on-white gradient, no filler copy. Commit to one strong aesthetic direction and hold it across every section.
• One idea per section plus one strong interaction moment beats effect soup.
• A ship-grade site is not a static styled page. If it reads like a slide, it is not done: build the scroll-driven motion (see stage 3). Do not lock one design direction as a default either; decide the aesthetic per project from the user's input plus your own judgment.
• Before declaring done, run the anti-slop pre-flight (references/anti-slop-checklist.md); the tells it lists are the difference between "styled" and "designed".
• Never pull in a third-party library or generated asset without the user's explicit consent, and show the official source first.
• Honesty over polish: if a section is not working, say so and fix it, do not declare done.
• No em-dash in any user-facing copy you generate (a hard rule in this skill).

Attribution

The references/uupm/ design database is vendored (as a trimmed subset) from nextlevelbuilder/ui-ux-pro-max-skill (MIT, see references/uupm/LICENSE). It is used as an offline data library only; its optional network features (Gemini image generation, npx shadcn) are not invoked by this skill.

The anti-slop heuristics in references/anti-slop-checklist.md and parts of the motion guidance are adapted (text only, no code executed, no plugin installed) from Leonxlnx/taste-skill (MIT), after a forensic source audit (verdict SAFE, 2026-07-08). Full details and license texts: NOTICE.md.