webstudio-ai-agent: Instructions file for Codex

Webstudio AI Assistant Guide & Rules

Project Architecture & Workflow

This repository contains the Webstudio visual web builder and an AI agent design workflow.

AI Design & Cloud Sync Protocol:

1. Local State Source of Truth: All site pages, instances, and styles are stored in .webstudio/data.json.
2. Assets: All images and fonts reside in .webstudio/assets/.
3. Design Tokens as CSS Classes (DRY Styles): NEVER duplicate styles across repeating elements (buttons, cards, badges, headings). Always declare and attach reusable Design Tokens as CSS classes using ws:tokens={[token('<class-name>', css...)]} (e.g. btn-primary, card-surface, badge-success — do NOT prefix with token-).
4. Execution Skill: Always use the webstudio-ai-designer skill (.agents/skills/webstudio-ai-designer/SKILL.md) when creating or modifying Webstudio designs.
5. Native MCP Tools (100% Local): All 70+ official Webstudio MCP tools run locally via:

   npx webstudio mcp single-op-call <tool> --input-file <payload.json>
   # Setup once per project: npm i webstudio && node scripts/setup-local-mcp.mjs --local
   

6. Asset Upload & Cloud Sync Protocol:
   • CRITICAL INVARIANT — NEVER SKIP ASSETS: NEVER pass skipAssets: true during Cloud import/sync. Passing skipAssets causes Webstudio Cloud to wipe/delete all uploaded assets and custom fonts from the project in Cloud.
   • When generating or managing assets in .webstudio/assets/, always upload via session cookies:

     npm run upload-assets
     

     This automatically uploads images/fonts via the session cookie in .webstudio/session.json, remaps all asset src props in data.build.props, and syncs with Webstudio Cloud.
   • To manually push project structure with assets to Webstudio Cloud:

     npx webstudio import --to "<shareLink>"
     

7. Flexbox-First Layouts & Strict Breakpoint Rules:
   • Flexbox-First Policy: Always use Flexbox (display: flex; flex-wrap: wrap; gap: ...) for card containers, hero sections, stats bars, button strips, headers, and footers. Flexbox is simpler, more predictable, and much easier to adapt for mobile (flex-direction: column; width: 100%). Use CSS Grid ONLY for complex 2D layouts (like asymmetric Bento grids).
   • ONLY Standard Webstudio Breakpoints: Webstudio strictly supports 4 standard breakpoints:
     • Base (Desktop / default, no media query)
     • @media (max-width: 991px) (Tablet)
     • @media (max-width: 767px) (Mobile landscape / general mobile)
     • @media (max-width: 479px) (Mobile portrait)
   • CRITICAL: NEVER write arbitrary media queries (e.g. @media (max-width: 768px), @media (max-width: 640px), @media (max-width: 575px)). Any non-standard media query causes Webstudio to create unwanted custom breakpoints in the builder toolbar.
   • Mandatory Mobile Adaptation: Every section must be 100% responsive:
     • Multi-card flex rows collapse cleanly to flex-direction: column; width: 100%; on mobile (max-width: 767px).
     • Buttons and CTAs must be full-width (width: 100%) or neatly stacked in flex-direction: column on mobile screens.
     • Headings must scale down on mobile (Hero H1: 28-32px, Section H2: 24-26px, Body: 14-15px).
     • Containers must have width: 100%; box-sizing: border-box; and responsive horizontal paddings (16px on mobile, 24px on desktop) to prevent any horizontal scrolling.