clientLanguages: "typescript,html,css" clientFrameworks: "preact" ``` This returns: - **Reference code** — HTML/CSS structure to adapt - **Screenshot** — visual reference - **Asset download URLs** — images used in the section ### 2.2 Also get the mobile variant If a mobile variant exists (separate frame), call `get_design_context` on the mobile node too. If there is no separate mobile frame, get a screenshot of the section and use responsive Tailwind classes to implement mobile behavior based on the desktop design proportions. ### 2.3 Create section file **Path:** `sections//.tsx` Follow the Deco section pattern: ```tsx import type { ImageWidget } from "apps/admin/widgets.ts"; /** @titleBy title */ export interface Props { /** @title Hero Image */ image?: ImageWidget; /** @title Title */ title?: string; /** @title Subtitle */ subtitle?: string; /** @title CTA Text */ ctaText?: string; /** @title CTA Link */ ctaHref?: string; } export default function HeroBanner({ image = "/placeholder.png", title = "Default Title", subtitle = "Default subtitle text", ctaText = "Shop Now", ctaHref = "/", }: Props) { return (

{/* Desktop */}

{/* Desktop layout */}

{/* Mobile */}

{/* Mobile layout */}

); } export function LoadingFallback() { return

; } ``` ### Rules for section creation 1. **Use `class` not `className`** — Preact + Deco convention 2. **Tailwind CSS only** — no inline styles, no CSS modules 3. **No client-side behavior in sections** — no hooks, no onClick, no useState. Use Islands for interactivity 4. **Typed props with JSDoc** — `@title` for admin labels, `@hide` for internal props 5. **Default values** — every prop must have a sensible default matching the Figma design 6. **Responsive** — use Tailwind breakpoints (`md:`, `lg:`) for desktop/mobile 7. **`LoadingFallback` export** — always include a skeleton loader matching section dimensions 8. **Widget types** — use `ImageWidget` for images, `TextArea` for rich text, `Color` for colors 9. **100% design fidelity** — match Figma spacing, colors, typography, and layout exactly ### 2.4 Islands for interactive elements When a section requires client-side behavior (carousel, accordion, tabs, dropdown menu), build the Island alongside the section: 1. Create the interactive part as an Island in `islands/.tsx` 2. Import and use the Island inside the section 3. Keep the Island minimal — only the interactive logic ```tsx // islands/Carousel.tsx import { useSignal } from "@preact/signals"; interface Props { children: preact.ComponentChildren; } export default function Carousel({ children }: Props) { const currentSlide = useSignal(0); // Client-side carousel logic } ``` --- ## Step 3: Download & Place Assets ### 3.1 Collect asset URLs From each `get_design_context` response, collect the `downloadUrls` map. This contains all images, icons, and illustrations used in the section. ### 3.2 Download images For each asset URL: ```bash curl -L -o /tmp/.png "" ``` ### 3.3 Upload to Deco assets Use the Deco **upload** tool to save assets to the site's asset library: ``` Tool: upload file: /tmp/.png ``` Record the returned asset URL (e.g., `https://deco-sites-assets.s3.sa-east-1.amazonaws.com/...`). ### 3.4 Place assets in sections Update each section's `defaultProps` or the page JSON block to reference the uploaded asset URL. The image must appear in the exact position shown in the Figma design. ### 3.5 Alternative: Figma "Export Original Images" plugin If the Figma file uses the "Export Original Images" plugin, assets may already be exported at original resolution. Prefer these over Figma's rendered exports when available — they preserve quality. --- ## Step 4: Configure Loaders ### 4.1 Add inline loaders for simple data ```tsx import type { AppContext } from "apps/site.ts"; export const loader = async (props: Props, _req: Request, ctx: AppContext) => { const products = await ctx.invoke.vtex.loaders.intelligentSearch.productList({ query: props.query, count: props.count ?? 12, }); return { ...props, products }; }; ``` ### 4.2 Use external loaders for reusable data When multiple sections need the same data, use an external loader and type-match the prop: ```tsx // In the section export interface Props { products?: Product[] | null; } ``` This lets the Admin user pick any loader that returns `Product[]`. ### 4.3 Ask user for integration details If the data source is unclear or requires API credentials, **ask the user**: - Which e-commerce platform? (VTEX, Shopify, VNDA, Wake) - API credentials or account name? - Specific collection IDs, category paths, or search terms? --- ## Step 5: Visual QA with Playwright ### 5.1 Capture Figma baselines For each section, capture Figma screenshots as baseline: ``` Tool: get_screenshot fileKey: nodeId:

``` Save to: ``` tests/visual-qa/baselines/desktop/-.png tests/visual-qa/baselines/mobile/-.png ``` ### 5.2 Capture implementation screenshots Use Playwright to screenshot each section at both viewports: ```typescript import { chromium } from "playwright"; const BASE_URL = "http://localhost:8000"; const VIEWPORTS = { desktop: { width: 1440, height: 900 }, mobile: { width: 375, height: 812 }, }; const PAGES = [ { name: "home", path: "/" }, { name: "plp", path: "/category" }, { name: "pdp", path: "/product/p" }, ]; async function captureAll() { const browser = await chromium.launch(); for (const [device, viewport] of Object.entries(VIEWPORTS)) { const context = await browser.newContext({ viewport }); const page = await context.newPage(); for (const p of PAGES) { await page.goto(`${BASE_URL}${p.path}`); await page.waitForLoadState("networkidle"); // Full page screenshot await page.screenshot({ path: `tests/visual-qa/actual/${device}/${p.name}-full.png`, fullPage: true, }); // Individual section screenshots const sections = await page.locator("[data-section]").all(); for (let i = 0; i < sections.length; i++) { const name = await sections[i].getAttribute("data-section") || `section-${i}`; await sections[i].scrollIntoViewIfNeeded(); await page.waitForTimeout(300); await sections[i].screenshot({ path: `tests/visual-qa/actual/${device}/${p.name}-${i}-${name}.png`, }); } } await context.close(); } await browser.close(); } captureAll(); ``` ### 5.3 Comparison criteria For each section, check these aspects against the Figma baseline: **Layout:** - Flex direction matches (row vs column) - Alignment matches (start, center, end, space-between) - Grid columns match (2-col, 3-col, 4-col) - Section max-width and centering - Content ordering matches top-to-bottom, left-to-right **Spacing:** - Padding inside the section - Margin between elements - Gap between grid/flex items - Section vertical spacing (padding-y) **Typography:** - Font family, size, weight, line height, letter spacing - Text color and alignment - Text transform (uppercase, capitalize) **Colors:** - Background, text, border, button, and link colors **Images:** - Correct image displayed, aspect ratio, object-fit, border radius, dimensions **Responsive:** - Desktop layout correct at 1440px - Mobile layout correct at 375px - Breakpoint transitions smooth (no layout jumps at 768px, 1024px) - Hidden elements properly hidden per viewport ### 5.4 Generate adjustment list Output a structured adjustment table: ```markdown ## Visual QA Adjustments ### Desktop (1440px) | # | Section | Issue | Expected | Actual | Fix | |---|---------|-------|----------|--------|-----| | 1 | HeroBanner | Title font size | 48px | 36px | Change text-4xl to text-5xl | | 2 | ProductShelf | Card gap | 24px | 16px | Change gap-4 to gap-6 | | 3 | Footer | BG color | #1a1a1a | #000000 | Change bg-black to bg-[#1a1a1a] | ### Mobile (375px) | # | Section | Issue | Expected | Actual | Fix | |---|---------|-------|----------|--------|-----| | 1 | Header | Menu icon missing | Present | Missing | Add MobileMenu Island | | 2 | HeroBanner | Image height | 300px | 400px | Add h-[300px] md:h-[400px] | ``` --- ## Step 6: Implement Adjustments For each item in the adjustment list: 1. Apply the fix to the section `.tsx` file 2. Re-screenshot with Playwright 3. Confirm the mismatch is resolved 4. Mark the adjustment as `Fixed` Repeat until all sections pass visual QA on both **desktop (1440px)** and **mobile (375px)** viewports. --- ## Step 7: Performance & Accessibility Audit Run the performance skills on every section created. ### 7.1 Image optimization Use skill: `.claude-performance/skills/image-optimizer/SKILL.md` - [ ] Above-fold images are preloaded (`loading="eager"`) - [ ] Below-fold images are lazy loaded (`loading="lazy"`) - [ ] Images have explicit `width` and `height` (CLS prevention) - [ ] Images use optimized formats (prefer AVIF > WebP > JPEG) - [ ] No oversized images (max 2x display size) ### 7.2 HTML size optimization Use skill: `.claude-performance/skills/html-size-optimizer/SKILL.md` - [ ] Section HTML is minimal (no unnecessary wrappers) - [ ] No inline base64 images - [ ] No unused Tailwind classes ### 7.3 Section-level performance - [ ] `LoadingFallback` is exported and matches section dimensions - [ ] No blocking resources in the section - [ ] Below-fold sections use deferred loading via Deco's render - [ ] Server-side data fetching is cached appropriately - [ ] No N+1 loader calls (use `deduplicate-loaders` skill if needed) ### 7.4 Accessibility - [ ] Heading hierarchy is correct (h1 > h2 > h3) - [ ] Images have alt text - [ ] Buttons have accessible labels - [ ] Color contrast meets WCAG AA (4.5:1 for normal text, 3:1 for large text and UI components) - [ ] Interactive elements are keyboard focusable - [ ] Skip navigation link (if applicable) --- ## Step 8: Functional E2E Testing Use skill: `.claude-deco/skills/e2e-testing/SKILL.md` ### 8.1 Header / Navigation **Desktop:** - [ ] Logo renders and links to home - [ ] Navigation items render with correct text and links - [ ] Mega menu opens on hover (if applicable) with categories/subcategories - [ ] Search bar is visible and functional - [ ] Cart icon shows item count - [ ] User account icon/link works - [ ] Sticky header works on scroll (if designed) **Mobile:** - [ ] Logo renders - [ ] Hamburger menu icon is visible and opens drawer - [ ] Menu items are tappable (44x44px minimum) - [ ] Nested categories expand/collapse - [ ] Menu closes on navigation and backdrop tap - [ ] Search icon opens search overlay - [ ] Cart icon visible and functional ### 8.2 Hero Banner - [ ] Background image loads - [ ] Title and subtitle render correctly - [ ] CTA button renders and links correctly - [ ] If carousel: arrows/dots work, autoplay works - [ ] Mobile: layout stacks or adjusts ### 8.3 Product Shelf **Desktop:** - [ ] Correct number of products shown (e.g., 4 per row) - [ ] Product image, name, and price render - [ ] Navigation arrows work (if applicable) - [ ] Click navigates to PDP **Mobile:** - [ ] Products show in scroll/swipe layout with swipe gesture - [ ] Product cards properly sized with adequate touch targets ### 8.4 Product Listing Page (PLP) - [ ] Products load and render in grid - [ ] Filters sidebar/dropdown works (mobile: opens as drawer/modal) - [ ] Sort dropdown works - [ ] Pagination or infinite scroll works - [ ] Product count and breadcrumb navigation displayed ### 8.5 Product Detail Page (PDP) - [ ] Product images load (main + thumbnails) with gallery navigation - [ ] Product name, description, price render - [ ] Size/variant selector works - [ ] Add to cart and quantity selector work - [ ] Mobile: images swipeable, sticky add-to-cart bar (if designed) ### 8.6 Search **Desktop:** Search input accepts text, suggestions appear, Enter navigates to results **Mobile:** Search icon opens overlay, keyboard opens automatically, suggestions appear, close button works ### 8.7 Cart / Minicart - [ ] Minicart opens on add-to-cart - [ ] Product appears with quantity update and remove - [ ] Subtotal calculates correctly - [ ] Checkout button links correctly - [ ] Mobile: minicart is drawer/modal ### 8.8 Footer - [ ] All link sections render with working links - [ ] Social media icons render and link - [ ] Newsletter signup works (if present) - [ ] Payment method icons render - [ ] Mobile: sections stack vertically ### 8.9 E-commerce flow Run the full e-commerce E2E flow on **both desktop and mobile**: ``` Home -> PLP -> PDP -> Add to Cart -> Minicart ``` ### 8.10 Mobile-specific checks - [ ] Touch targets are at least 44x44px - [ ] No horizontal scroll overflow - [ ] Text is readable without zooming (min 16px body) - [ ] Fixed/sticky elements don't overlap content - [ ] Hamburger menu closes when navigating - [ ] Bottom navigation (if present) doesn't overlap content --- ## Section Naming Convention Map Figma frame names to Deco section paths: | Figma Frame Name | Section Path | |------------------|-------------| | Header | `sections/Header/Header.tsx` | | Hero Banner | `sections/Hero/HeroBanner.tsx` | | Product Shelf | `sections/Product/ProductShelf.tsx` | | Category Grid | `sections/Category/CategoryGrid.tsx` | | Newsletter | `sections/Newsletter/Newsletter.tsx` | | Footer | `sections/Footer/Footer.tsx` | | Blog Posts | `sections/Blog/BlogPosts.tsx` | Use PascalCase for file names. Group related sections in subdirectories. --- ## Page Assembly After all sections are created, assemble pages by creating/updating page JSON blocks in `.deco/blocks/`: ```json { "name": "Home", "path": "/", "sections": [ { "__resolveType": "site/sections/Header/Header.tsx" }, { "__resolveType": "site/sections/Hero/HeroBanner.tsx", "image": "https://..." }, { "__resolveType": "site/sections/Product/ProductShelf.tsx", "title": "Best Sellers" }, { "__resolveType": "site/sections/Newsletter/Newsletter.tsx" }, { "__resolveType": "site/sections/Footer/Footer.tsx" } ] } ``` Repeat for each page (Home, PLP, PDP, Institutional, etc.). --- ## Review Checklist Before marking the implementation as complete, run through the review skill (`.claude-deco/skills/review/SKILL.md`): - [ ] No hardcoded text — all strings are configurable via props - [ ] No hardcoded CSS — using Tailwind tokens - [ ] No unused components or files - [ ] No exposed tokens or API keys - [ ] Loaders have caching and error handling - [ ] All sections export `LoadingFallback` - [ ] No breaking changes to existing sections - [ ] Desktop and mobile layouts match Figma - [ ] All images uploaded and placed correctly - [ ] Performance audit passed - [ ] E2E tests pass on desktop and mobile --- ## Related Skills | Skill | When to Use | |-------|-------------| | `e2e-testing` | Full e-commerce flow testing with performance metrics | | `image-optimizer` | Optimize images after asset placement | | `html-size-optimizer` | Reduce HTML payload per section | | `review` | Pre-publish code review | | `deduplicate-loaders` | Consolidate repeated loader calls | | `fix-bug` | Patch individual section issues |