Test the Punch system end-to-end

1 Scaffold the project

Open Cowork in a fresh folder where this client's repo should live. Run:

Initialize a new Punch project for [client name]. Slug: [kebab-case]. Project type: website.

Cowork will trigger punch-project-init. It'll ask for a couple of clarifications (slug, CMS target), then write the folder structure with stub files. Confirm you see:

• brand/copy-brief.md, brand/theme-notes.md
• content/sitemap.yaml, content/homepage.md, content/_brief-template.md
• sandbox/tokens.css, sandbox/components.html
• README.md

2 Fill in the stub files from your existing inputs

Open each file and replace the comment placeholders with your real content. Order matters:

2a · brand/copy-brief.md

Paste your Big Idea and "what it evokes" sentence. Fill in audience and voice characteristics. Banned + preferred words can wait if not yet decided — but the Big Idea must be there before the wireframe runs.

2b · brand/theme-notes.md

Capture the visual + verbal direction of your chosen creative theme. Palette, type, illustration approach, motion direction. This doesn't affect the wireframe (intentionally neutral) but it's the brief for the homepage design step.

2c · content/sitemap.yaml

List every page that will exist on the shipped site. Each entry needs url, title, page_type, and tier. Mark the homepage and the 2–4 most important pages as showcase; everything else standard.

2d · content/homepage.md

This is the one with the most paste work. Open your Google Doc with the homepage copy, and copy each section of prose into the corresponding field below. Section keys (hero, intro, feature_split_rows, etc.) map to design system components — keep them lowercase. Delete sections this homepage doesn't have.

2e · brand/visual-direction.md (decode any Webflow references first)

This file is the single most important spec for keeping visual direction consistent across pages — Cowork reads it on every compose call. If you're emulating any Webflow or reference template (Volio, Linear, etc.), do this two-step:

Step 1: Decode the reference template(s) first. For each reference, run punch-webflow-decode in Cowork:

Decode [template name] for the visual direction. URL: [URL]. Screenshots attached.

The skill requires both the URL AND screenshots (4-6, covering hero + key feature sections + stat strips + any distinctive blades). Without screenshots, the decode will be wrong. The output lands in decoded-references/[template-slug].md at the Process folder level (shared across all client projects).

Step 2: Write brand/visual-direction.md citing the decode(s). The template that punch-project-init created has the structure. Fill in:

• Overall character — one paragraph aligned with the Big Idea
• Reference templates — list each decoded reference and what's being borrowed from it
• Specific idioms we ARE borrowing — named idioms (e.g., "hairline-rule modular grid from Volio", "two-column intro pattern from Linear")
• Specific idioms we are NOT borrowing — the skip list (e.g., "pill buttons everywhere", "multi-color pill rotation")
• Palette + surface rules, typography rules, motion discipline

For your Auria rush test specifically: the corrected Volio decode is already in decoded-references/volio-saas-ui-kit-home-01.md, and Linear is in decoded-references/linear.md. You can cite either or both in Auria's brand/visual-direction.md based on which character fits better.

3 Export tokens from your Figma fork

If your creative theme is already in a Figma file with a Punch Tokens collection (or equivalent), run in Cowork:

Export the Punch Tokens collection from the [client] Figma file to sandbox/tokens.css.

This triggers punch-token-export. The resulting tokens.css is what the homepage design (Step 5) will read.

4 Build the wireframe

In Cowork:

Build the content-first wireframe for this project.

This triggers punch-wireframe. The skill reads content/sitemap.yaml and every brief in content/, then writes sandbox/wireframe/ with one HTML page per sitemap entry, plus _wireframe.css and _index.html.

Preview locally:

cd sandbox/wireframe
python3 -m http.server 8000
# open http://localhost:8000/_index.html

Click through every page. Read the homepage end-to-end like a client would. Note:

• Does the copy land in the right structural order?
• Does each section's content make sense without design dressing it up?
• Do CTAs go to pages that exist?
• Is the Big Idea readable through the wireframe alone? (If not, it's a copy problem, not a design problem.)

5 Iterate the wireframe (if needed)

When client feedback comes back:

• Copy changes: edit the relevant content/*.md brief, re-run punch-wireframe. The wireframe regenerates each time.
• Structure changes (section reorder, add/remove section): edit the brief, re-run.
• Sitemap changes (add/remove pages): edit sitemap.yaml, re-run. Missing briefs render as TBD placeholders.

Don't hand-edit anything in sandbox/wireframe/. It's regenerated every run; your edits will be lost.

6 Design the homepage against the wireframe

This is where Cowork composition enters. The wireframe is locked, the tokens are in place, the creative theme is decided. Now you compose the homepage as real designed code in sandbox/index.html, against the design system you'll be building as you go.

In Cowork:

Compose the homepage from content/homepage.md into sandbox/index.html.
Use the design system in sandbox/components.html and tokens.css.
Apply the visual direction in brand/visual-direction.md.
Big Idea is [the Big Idea] — favor [restrained / bold / etc.].

Pointing Cowork at brand/visual-direction.md is what makes the decoded reference idioms actually land in the output. Without that reference, Cowork composes against tokens alone and you'll see the generic SaaS gravitational pull take over.

Iterate using the patterns in Designer Onboarding Module 5 (the fidelity hierarchy: named tokens + components beat screenshots; annotate inspirations specifically; avoid the "Claude improved it" failure mode).

7 Evaluate and report back

Now the test is complete. Specifically check:

• Did punch-project-init produce the right structure? Anything missing? Any stub file that wasn't clear about what to fill in?
• Did the brief schema fit your real copy? Were there sections you had no key for? Were the YAML field names obvious enough?
• Did punch-wireframe render usefully? Was it readable end-to-end? Did the client engage with it the way the content-first hypothesis predicts?
• Did the homepage compose cleanly against tokens? Were there moments where Cowork couldn't pull from the design system and improvised?
• What did you spend more time on than expected? The friction points are where the next round of system work focuses.

Bring the answers back. Specific failure modes = specific skill improvements. This test is how we tighten the system, not just check a box.