Figma Starter Spec

Overview

Punch's website workflow makes HTML/CSS the canonical design system — the sandbox/ folder is the source of truth. Figma is a token repository, a per-project visual exploration surface, and a handoff staging surface. The starter file is the scaffold that every per-client Figma file forks from.

Two files were built. A master starter with empty token slots, page-archetype wireframes, copy-naming conventions, and a handoff checklist. A sample client fork for a fictional architecture practice called Aldera, showing what the master looks like when populated.

The two Figma files

What's in the master

Every page exists for a specific reason. None are decoration.

The token schema

One Variables collection called Punch Tokens with 54 variables in a consistent dotted path: color/brand/primary, space/4, type/size/h1, etc. Master values are neutral placeholders (mostly grayscale, with a Punch red accent). Each client fork overrides values — never the structure.

What's in the Aldera fork

A fictional architecture practice in Portland called Aldera, with an emerald-and-cream editorial palette and a serif display font. Built to demonstrate four things every per-client fork does.

Three pages were intentionally left empty as slots the project team fills during work: Homepage Composition, Showcase · Case Study (Aldera), Handoff to Dev. The fork's tokens collection (Aldera Tokens) carries 54 variables identical in schema to the master, with values for emerald primary, cream surfaces, ink text, and clay accents.

How copy flows in

The strategist owns content. The designer owns visual structure. They never edit the same surface — that's how you stop overwrites.

The contract

Strategists write each page as a structured Markdown brief in the project's content/ folder. The schema is fixed: every section type (hero, intro, feature_grid, cta, etc.) has named keys that map exactly to Figma text-layer names.

page: homepage
url:  /
tier: showcase

hero:
  eyebrow:    ARCHITECTURE · PORTLAND
  headline:   Buildings that plant.
  subhead:    Civic architecture for a warming Pacific Northwest.
  cta_label:  See our work
  cta_url:    /projects

intro:
  headline:   A studio that reads its site.
  body:       Aldera is a 12-person practice in Portland.

The designer's job with the brief

The designer reads the brief, then in Figma names every text layer to match the brief keys: hero.headline, feature_grid.0.title, cta.cta_label. The visible text in the Figma file is fill-in. The brief stays the source of truth.

Keeping them in sync

A Claude prompt called punch-copy-sync reads the Markdown brief and the Figma frame, returns a diff: missing sections, extra sections, mismatched copy. Run it before per-batch QA (gate 4). The creative-qa skill already does this kind of comparison for visual deliverables — copy sync is the same idea applied to text.

Alignment with the Website Redesign Workflow

The Figma starter respects the workflow's first principle: HTML sandbox is canonical, Figma is exploration. A few specific alignments:

Handoff Checklist — replacement copy

The checklist page in the master Figma file (page 09) still reads against the old flow. Below is the replacement checklist, structured around the four moments where a real handoff happens in the new process. The art director (or whoever owns the Figma master) should paste this into the page on the next master pass.

① Before Production runs /website-design-amplifier:amplify

Triggered: end of Phase 1, after Gate 3 (Sitemap Revisit). Owner: Lead Designer + PM verify together.

• The homepage is built in code in sandbox/ and renders correctly at 1280 / 768 / 375.
• site-llm (or equivalent compact site description) is current and includes voice, big idea, tone notes, and any blog/thought-leadership content the amplifier should fold in.
• content/sitemap.yaml is final and matches what the client approved at Gate 3.
• Design tokens are exported from Figma to tokens.css via punch-token-export and the homepage is bound to them — no hardcoded brand values anywhere in the homepage source.
• The Punch Tokens collection in the Figma fork reflects the final brand values (the amplifier will read the exported tokens, not Figma directly, but they must match).
• PM has confirmed Production has access to the project repo and Claude Code is configured.

② Before Dev starts the CMS pilot

Triggered: start of Phase 2, in parallel with Production amplification. Owner: TDM + Dev.

• CMS target is confirmed (WordPress, HubSpot, Webflow, Sanity, etc.) and an empty instance is provisioned.
• One page is selected as the CMS pilot — usually a standard-tier page so the harder cases come later. PM has flagged the choice in Asana.
• The dev branch is set up, CI is green, and Production has a separate branch for amplified output so the two streams don't collide.
• Blog/thought-leadership content source is identified (existing CMS export, archive scrape, or content doc) so blog migration can begin in Phase 2.
• /website-to-static:convert has run on any reference material that needs to be ingested.

③ Before every gate (Phase 2 + Phase 3) — TDM QA against The Build

Triggered: every internal gate before showing the client. Owner: TDM, with Production support for amplified pages and Dev support for CMS-piloted pages.

• All pages render at 1280 / 768 / 375 without layout breaks.
• No hardcoded color, type, or space values — everything reads from tokens.css.
• Copy matches the latest content briefs (run punch-copy-sync on any page that's been edited since last gate).
• Brand voice is consistent — no boilerplate the amplifier may have invented that drifts from the client's tone.
• WCAG 2.1 AA baseline: color contrast, focus states, semantic headings, alt text. (Run design:accessibility-review for any showcase page.)
• Blog/thought-leadership pages are migrated and rendering with the new design system.
• Internal links resolve to pages that exist in sitemap.yaml.

④ Before Dev migrates everything to the CMS for final client preview

Triggered: end of Phase 3, after The Build has been client-approved (Gate 6). Owner: Dev, with Production polishing CMS-format edits afterward.

• Static preview is signed off — no outstanding visual or copy edits.
• CMS content model is built and mirrors the page structure (page types, block components, taxonomy).
• Dev has a rollback plan in case CMS migration introduces regressions vs The Build.
• Production is queued to run CMS-format polish after Dev's migration (typography fine-tunes, image asset handling, any CMS-specific copy edits that the static format didn't constrain).
• Forms, analytics, search, and any third-party integrations are configured and tested in the CMS.
• 301 redirects from the old site are in place for any URL changes since the original sitemap.

Gaps and next steps

These are the holes in v0.1 — worth knowing about before the team starts using it.

Onboarding course — parked

Designer onboarding is on the roadmap. The shape that fits Punch's culture is an interactive HTML walkthrough that mirrors the workflow doc's tone — a single self-contained file, not a PDF, with hands-on exercises rather than passive reading.

A working draft would include: a four-phase tour mapped to the workflow doc, a forking exercise where the designer duplicates the master and fills in Aldera-style tokens, a copy-naming drill matching Figma layer names to a sample brief, a per-batch QA simulation (designer is given a deliberately-broken design and has to find the issues), and a handoff exercise that produces a spec doc. The designer course lands first; strategist and dev courses share most of the workflow scaffolding with role-specific exercises swapped in.

This is a non-trivial build — probably a half-day to scaffold and another half-day to make it actually good. Pick this up after the v1.0 starter is in real use and you have a few real client projects to anchor the exercises against.