# Awwwards Designer

> Awwwards-level website builder powered by Google Stitch. Takes a brand brief, generates award-quality UI designs via Stitch MCP, then enhances the output with a bespoke animation and interaction layer — scroll effects, page transitions, 3D scenes, and signature interactions derived from the brand metaphor. Built on TanStack Start. Targets Awwwards SOTD/SOTM/SOTY. This is the unified orchestrator skill — it bundles animation standards, performance standards, visual design standards, and quality gate checks into one cohesive workflow.

- Skill: `masalale/awwwards-designer` (Agent Skill, multi-file: 32 files)
- Install (CLI): `npx skillmds@latest add masalale/awwwards-designer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/masalale/awwwards-designer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: Masalale (https://skillmd.com/u/masalale)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/masalale/awwwards-designer

---


# Awwwards + Stitch: Unified Execution Skill

## Hard Stops

These are non-negotiable. Violating any one is a build failure.

1. **No code before the Invention Gate completes.** The animation map and Stitch prompt must exist before any screen is generated or any code is written.
2. **TanStack Start only.** Do not use Astro, Next.js, or any other framework. Every project is built on TanStack Start with React and Tailwind CSS. This is not a choice offered to the user.
3. **`overflow: visible` on text elements.** Never `overflow: clip` (clip ignores padding-bottom). Display text >48px requires descender clearance. See `references/descender-safety.md`.
4. **`100dvh` not `100vh`.** Accounts for mobile address bar resize on full-screen sections.
5. **Never override native touch scroll.** Native touch scroll momentum is sacred. If a smooth scroll library is used, it must not intercept touch scroll (Lenis is preferred — ensure `smoothTouch: false`).
6. **Context7 before integrating any library.** Fetch current API docs via Context7 for every library you choose to use before writing integration code. Library APIs change. Training data is stale.
7. **Descender safety on display text >48px.** `padding-bottom: 0.18em` minimum on all display text. See `references/descender-safety.md`.
8. **Lucide icons exclusively.** Specify in Stitch brief. Stitch uses Lucide by default.
9. **Bun exclusively.** All package management, script execution, and tooling uses Bun. `bun add` not `npm install`. `bunx` not `npx`. `bun run build` not `npm run build`.
10. **GPU-accelerated properties only for animation.** Animate only `transform`, `opacity`, `filter`, `clip-path`. Never animate `width`, `height`, `top`, `left`, `margin`, `padding`, `font-size`, `border-radius`.
11. **No `transition: all` anywhere.** Never, for any reason, in any file.
12. **`prefers-reduced-motion` must be respected.** All animations must gracefully degrade or disable when the user preference is set. No broken state when reduced motion is on.
13. **Body text contrast must be ≥ 4.5:1.** Gray-500 (#6b7280) or darker on white. Never gray-400 or lighter for body text.
14. **Every animation must have a purpose.** If you can't state the reason in one sentence, remove it. No decoration-only animation.

---

## Phase 1: Brief Interview

Ask the user these 7 questions to extract everything the Invention Gate needs:

1. What is the brand or store name?
2. What does the brand do and what does it stand for?
3. Who is the target audience?
4. What tier of animation? (1: CSS-only | 2: JS-enhanced | 2.5: light 3D | 3: WebGL/shaders)
5. How many pages and what content on each?
6. Are there any interactive or data-driven sections — forms, logins, dashboards, listings, checkout flows? If yes, describe each briefly.
7. Any reference sites that capture the desired feel? (optional)

If the user provides brand colors, capture them exactly. If not, note that Stitch will choose.

**Output:** Structured interview answers passed to Phase 2.

---

## Phase 2: Invention Gate

The creative engine. Takes interview answers, produces two documents.

Read `references/invention-gate.md` for the full process.

### 2.1 Extract Brand Metaphor
Distill a physical/sensory metaphor from the brand identity. Must pass 3 quality gates:
- Grounding test (can you touch/feel it?)
- Continuity test (informs both visual and motion?)
- Distinctiveness test (unique to this brand?)

### 2.2 Derive Motion Language
Map the metaphor to speed, weight, texture, and response. Define 3 project easings.

### 2.3 Generate Animation Map
Following the schema in `references/animation-map.md`:
- Global settings (tier, easing, scroll behavior, page transitions, signature interaction)
- Per-page animation assignments for every section
- WebGL/3D overlay zones (Tier 2.5+) with mobile fallbacks
- Animated text targets (elements requiring character/word-level animation)
- Scroll-pinned sections

Read `references/technique-families.md` for interaction pattern options per tier.
Read `references/anti-patterns.md` before making any pattern decisions.

### 2.4 User Review Gate
**Do not generate the Stitch prompt yet.**

Present to the user:
- The three brand metaphors with quality gate results
- The motion language (speed, weight, texture, response → named easings)
- The signature interaction statement
- The animation map summarized per page

Ask: "Does this capture the brand correctly? Any changes before I write the Stitch prompt?"

Wait for explicit confirmation. Revise and re-present if needed. Do not proceed until the user confirms.

### 2.5 Translate to Stitch Prompt
Only after user confirms the animation map.

Write the Stitch prompt following `references/stitch-brief.md`. The Aesthetic Direction section is the creative core — inject the brand metaphors from the Invention Gate verbatim, then follow with the visual vocabulary and negative constraints each metaphor implies at rest. Include the actual brand name (not the creative codename) and define shared components (nav, footer) explicitly so they are consistent across all generated screens.

**Output:** Animation map (user-confirmed) + Stitch prompt.

**Gate:** Both documents must exist and the animation map must be user-confirmed before proceeding to Phase 3.

---

## Phase 3: Stitch MCP

Drive Google Stitch programmatically via MCP to generate the design and build the project. Stitch always outputs HTML with Tailwind CSS — it has no awareness of any JavaScript framework. The TanStack Start project structure is established in Phase 4.

### 3.1 Create Project
Call `create_project` via Stitch MCP. Once the project ID is returned, display the canvas link to the user:
```
Your Stitch canvas: https://stitch.withgoogle.com/project/{projectId}
```
Screens will appear here live as they are generated.

### 3.2 Generate Screens
Call `generate_screen_from_text` for each page using the Stitch prompt from Phase 2.
- Set `deviceType: "DESKTOP"`
- Screen generation takes 2-10 minutes per screen. After each call returns, immediately call `list_screens` to confirm the screen is present in the project before generating the next. This catches silent failures without retrying prematurely.
- After each screen is confirmed, tell the user: "✓ [Page name] screen is live on your canvas."
- Collect every screenId as screens are confirmed — all are needed for the harmonization pass.

### 3.3 Cross-Page Harmonization
`generate_screen_from_text` is always a single, independent call. It has no memory of the other pages generated in the same project. The harmonization pass corrects any inconsistencies that result from independent generation.

Call `edit_screens` once with **all screenIds** in `selectedScreenIds`. This single call gives Stitch visibility across every screen simultaneously, allowing it to reconcile shared visual properties across the entire site.

Harmonization prompt: "Unify all screens so that the navigation bar, footer, button styles, card styles, typography scale, and color usage are identical across every page. Fix any visual inconsistencies introduced by independent generation. Apply the design decisions established in the strongest screen to all others."

### 3.4 Review Gate
After the harmonization pass, prompt the user:
```
All screens are live at your Stitch canvas. Review them and make any edits directly on the canvas until you're happy, then reply here when you're ready to build.
```
Wait for explicit user confirmation before proceeding.

### 3.5 Build Site
Call `build_site` with the project ID and route mappings:
- Map each screen to its URL route (e.g., screenA -> "/", screenB -> "/work")
- Output: HTML pages with Tailwind CSS, one per route.

### 3.6 Extract Design Context
Call `extract_design_context` to get the Design DNA (fonts, colors, layouts).
Save as DESIGN.md in the project root.

**Output:** Project files + DESIGN.md.

---

## Phase 4: Enhancement Layer

The core execution phase. Takes the Stitch output and adds the animation/interaction layer.

### Prerequisites
Read before implementing:
- **DESIGN.md from Phase 3 — this is the single source of truth for all design decisions.** Every color, font, spacing, and component style must come from DESIGN.md. Do not invent or assume design values.
- The animation map from Phase 2 (for what moves and how)
- `references/tech-stack.md` for tier-appropriate library guidance
- `references/technique-families.md` for pattern implementation reference
- `references/page-transitions.md` for TanStack Router + GSAP transitions
- `references/descender-safety.md` for typography safety

Fetch current API docs via Context7 for every library before writing code.

### 4.0 Project Scaffolding
Stitch outputs plain HTML files — one per page. Phase 4 begins by establishing the TanStack Start project that the enhancement layer runs inside.

Use Context7 to fetch the current TanStack Start initialization command before running it — the CLI and package name evolve and a stale command will fail silently or scaffold the wrong structure. Initialize with React + Tailwind CSS.

Once the project is initialized:
- Replace the generated placeholder routes with the Stitch HTML pages, one route per page
- Preserve all Tailwind classes and structure from the Stitch output exactly — DESIGN.md is the design authority and the Stitch HTML is its implementation
- Do not restyle or restructure anything at this stage; the enhancement layer adds motion on top of the Stitch design, it does not replace it

### 4.1 Global Setup
Implement site-wide concerns first:
- Smooth scroll system (if required by the animation map tier — Lenis preferred, `smoothTouch: false`)
- Page transition system in root layout (`__root.tsx`) — see `references/page-transitions.md`
- Animation library initialization and plugin registration for whichever tools are chosen
- Animation cleanup on route change — all scroll triggers, instances, and contexts must be destroyed/reverted on navigation

### 4.2 Per-Section Animation
Walk through the animation map page by page, section by section:
- Match HTML sections to animation map assignments
- Implement the specified animation type (scroll_reveal, scroll_pin, webgl_overlay, static)
- Use the project easings from the animation map
- Animate text targets specified in the animation map with descender safety applied

### 4.3 WebGL/3D Overlays (Tier 2.5+ only)
For each overlay zone in the animation map:
- Create a canvas element positioned over the Stitch HTML section
- Implement the specified scene type using the most appropriate WebGL renderer for the scene (Three.js/R3F are proven defaults — choose based on scene complexity)
- Connect interaction handlers (cursor, scroll)
- Implement mobile fallback (hide canvas, show Stitch design)
- Ensure proper disposal and memory cleanup on route changes

### 4.4 Signature Interaction
Implement the one unique interaction specified in the animation map. This must feel native to the brand metaphor, not bolted on.

### 4.5 Site-Wide Pass
After all sections are enhanced:
- Test page transitions between all routes
- Verify smooth scroll behavior across all pages
- Verify animation cleanup prevents conflicts across route changes
- Test mobile at 375px width

**Output:** Enhanced site with full animation/interaction layer.

---

## Phase 5: Quality Gate

Run the pass/fail checklist in `references/quality-gate.md`.

Every item must pass:
- Page transitions present
- Signature interaction present
- Mobile responsive at 375px
- `100dvh` on full-screen sections
- No touch scroll hijacking
- Descender safety verified
- Icon system verified
- Core Web Vitals within tier targets
- Build succeeds, no dead routes, no broken assets

**All pass:** Site is ready to ship.
**Any fail:** Fix before shipping. No exceptions.

---

## Reference Files

| File | Purpose | When to Read |
|------|---------|-------------|
| `invention-gate.md` | Metaphor extraction + output generation | Phase 2 |
| `animation-map.md` | Animation map schema + easing derivation | Phase 2, Phase 4 |
| `stitch-brief.md` | How to write Stitch prompts | Phase 2 |
| `technique-families.md` | Interaction patterns by tier | Phase 2, Phase 4 |
| `anti-patterns.md` | Interaction/code anti-patterns | Phase 2 |
| `tech-stack.md` | Tier-based enhancement guidance | Phase 4 |
| `page-transitions.md` | Page transition patterns | Phase 4 |
| `descender-safety.md` | Typography clipping prevention | Phase 4 |
| `quality-gate.md` | Final quality gate | Phase 5 |
| `scroll-patterns.md` | Scroll-triggered reveals, galleries, parallax | Phase 4 |
| `text-animation.md` | SplitType, variable font animation, text reveals | Phase 4 |
| `micro-interactions.md` | Button arcs, magnetic effects, cursor | Phase 4 |
| `anim-anti-patterns.md` | Animation anti-patterns and code review | Phase 4 |
| `image-optimization.md` | Image formats, CDNs, lazy loading, blur-up | Phase 4, Phase 5 |
| `font-loading.md` | Preloading, font-display, subsets, size-adjust | Phase 4 |
| `css-performance.md` | Critical CSS, containment, will-change | Phase 4 |
| `testing.md` | Lighthouse, WebPageTest, CI budgets | Phase 5 |
| `typography.md` | Font pairing, type scale, fluid type math | Phase 2, Phase 4 |
| `color-systems.md` | 3-layer tokens, dark mode, OKLCH, WCAG contrast | Phase 2, Phase 4 |
| `responsive-design.md` | Mobile-first breakpoints, container queries | Phase 4, Phase 5 |
| `accessibility.md` | WCAG 2.1 AA checklist, ARIA, focus | Phase 5 |
| `scoring-guide.md` | Awwwards scoring, jury process, rejection reasons | Phase 5 |
| `design-audit.md` | Design quality deep-dive audit | Phase 5 |
| `usability-audit.md` | Navigation, mobile, touch, forms, 404 audit | Phase 5 |
| `technical-audit.md` | Build, routes, assets, semantic HTML, descender audit | Phase 5 |
| `animation-standards.md` | Full animation standards reference | Phase 4, Phase 5 |
| `performance-standards.md` | Full performance standards reference | Phase 4, Phase 5 |
| `visual-standards.md` | Full visual design standards reference | Phase 2, Phase 4 |
| *(included above)* | Quality gate scoring + 8 gates + pre-launch audit | *in quality-gate.md* |