Aixio documentation · Updated October 31, 2026

Aixio Design guide

Generate a visual mockup, recover editable layers and build websites, app screens, slide decks, print, social posts, ad banners or emails from Aixio MCP in your existing project, reviewing the mockup before anything is built.

Aixio Design gives a coding agent a visual reference and structured layers to build from. The hosted MCP pipeline generates a mockup and stops so you can review it; once you approve, it separates the mockup with Aixio’s Image to Layer model and returns an aixio.design/v1 specification with layer geometry, assets and text styling. The host agent implements it using your project’s own tools.

Aixio Design differs from asking an Aixio project’s agent to work in the project. Use ask_agent for work inside Aixio; use design, design_status and approve_design when the host will build the returned design.

Connect and install the agent skill

Follow the MCP quickstart. Discover design, design_status, approve_design, prepare_upload and balance. Then install the aixio-design skill (and the general aixio skill) as <skills folder>/<name>/SKILL.md: ~/.claude/skills for Claude Code, ~/.agents/skills for Codex, ~/.cursor/skills for Cursor; reload skills or restart the host if needed. For other hosts, follow their skill installation mechanism. The setup guide does all of this in one prompt. Installing instructions does not connect MCP or authorize paid work.

1. Choose one design reference and agree the paid scope

Mockups are best when one real design leads. Pick a single shipped page — a website, app screen, poster or slide that a studio actually made, not an AI concept or a board of several screens — that already has the sections you need. View it, crop away any surround, and use it only as design direction: never copy its brand name, logo, text, people or products. Your own logo, colours and product photos are brand assets that Aixio restyles into that design. Use one call per reference when comparing looks; never mix two style references in one call.

Write the brief in this order: one line on what to make and for whom; an IMAGE ROLES — follow strictly block (image 1 is the design reference with top priority; images 2–4 are only brand and product assets, restyled to match image 1’s photography, with the products kept the same); image 1’s sections in order, with their layout, palette, type and graphic devices; then the short exact copy, using only real facts. Leave out style adjectives that compete with image 1. Note the existing framework. Choose the target for what you are making (the full list is under “Decks, print, social, banners and email” below). Check balance and obtain authorization for both paid jobs: mockup generation and layer extraction. The current hosted pipeline selects its image model; do not promise a specific model or a fixed total price.

A design is two paid jobs, each started only by a call you make: design draws the mockup and approve_design cuts it into layers. design_status only reads. A new visual revision is another paid design; ordinary implementation repairs should reuse the existing result.

To explore several looks, draw one mockup per reference with design: it stops at the mockup. Review each against its reference, choose one, then approve and build only that one. Keep at most two or three paid jobs in flight.

2. Upload references in role order

Upload the design reference first, then up to three brand or product assets. For each PNG, JPEG or WebP file, call prepare_upload with the live schema, then PUT the actual file bytes to upload_url with the matching Content-Type and no Authorization header. Check upload success before passing source_url in reference_urls. Preparing an upload alone does not transfer the file. If the host cannot upload, report that limitation before submitting.

3. Submit once

The following is a tool-call argument example, not a REST endpoint. Use a unique request ID for each authorized design; keep the same ID and identical inputs if retrying a lost submission response.

{
  "request_id": "website-example-20261027-01",
  "target": "website",
  "brief": "<the brief below, as one string>",
  "reference_urls": ["<design reference>", "<logo>", "<mug photo>", "<bowl photo>"],
  "aspect_ratio": "2:3"
}

The brief:

Design a finished, high-end desktop homepage mockup (full scroll, flat, no device frame, no surround) for North Studio, an independent ceramics studio.
IMAGE ROLES — follow strictly:
- Image 1 is the DESIGN REFERENCE and has top priority. Reproduce its design system: the giant serif wordmark, the intro paragraph, the folder tabs, the 3 × 3 ruled product grid with rounded photos on warm backdrops, pill badges and tag pills, and the thin footer row. Same proportions, spacing and type pairing.
- Images 2–4 are ONLY North Studio’s brand content, not style: image 2 = its wordmark, images 3–4 = its real mugs and bowls. Re-shoot the same pieces in image 1’s photography. Take no layout or style from images 2–4.
- Do not copy image 1’s brand name, logo, text, people or products.
Copy to use: wordmark “North Studio”. Intro “Made slowly. Kept forever.” Grid: Ash Mug, Tide Bowl, Salt Pot …

Pass reference_urls in role order and leave style empty: image 1 carries the look. Save the returned design_id, request ID, target and exact inputs.

4. Review the mockup, approve it, then follow layers → done

Call design_status with the returned ID and the same target:

{
  "design_id": "<returned design_id>",
  "target": "website",
  "include_reference_image": true
}

Follow next_action and poll_after_seconds (its arguments carry the target, format, set and later the cut’s layers_job_id). At phase=review the mockup is done and nothing more runs: request the inline reference image once, view it (if reference_image_included is false, download it and view it with the host’s image tools; a URL is not visual inspection), and show it to the user.

On their changes, call approve_design with feedback: the mockup is redrawn as a new design to review. On their yes, call approve_design without feedback: it cuts that exact mockup, and calling it again returns the same cut, never a second charge. Approve without showing only when the user said to build without reviewing. For an image the user already approved, call design with mockup_url, mockup_width and mockup_height: it is cut as it is, with no redraw.

Approving, after the user said yes:

{
  "design_id": "<returned design_id>",
  "target": "website"
}

Continue with the same design ID after a timeout or disconnect. Never call design again merely because polling stopped. Stop on failed/cancelled jobs or admission errors, preserve the error and any completed mockup, and do not automatically start a new paid attempt.

Decks, print, social, banners and email

Targets: website, ios, macos, android, game, slide, deck, poster, flyer, brochure, business_card, packaging, social, ad_banner, email and other. Give a format for the real size: a preset (slide_16x9, a4, letter, trifold_letter, trifold_a4, business_card_us, ig_post, ig_story, youtube_thumbnail, leaderboard, email_600 and more in the tool schema) or width, height and unit (px, or mm/in for print with dpi, bleed and safe). Brochures take side outside or inside and come back with their panels; cards take front or back.

{
  "request_id": "clinic-trifold-outside-01",
  "target": "brochure",
  "format": { "preset": "trifold_a4", "side": "outside" },
  "brief": "<panels and copy>",
  "reference_urls": ["<design reference>", "<logo>"]
}

Pages of one set — the slides of a deck, both sides of a brochure or card, a carousel — share one look: approve the first page, then make every other page with style_from set to its design_id. The spec’s tokens (type scale, colours, margins and gaps, as CSS variables too) keep the build consistent.

The spec’s format gives the trim, bleed, safe area, pixel and point sizes and where the format sits in the mockup; outputs and how_to_build give the recipe: a PPTX with live text (pptxgenjs or python-pptx) for decks, a print PDF at trim plus bleed with TrimBox, BleedBox and crop marks for print, exact-size images for social and banners, and table-based HTML with inline CSS for email.

5. Build from the actual result

Require phase=done, status=succeeded and design.spec=aixio.design/v1. Read design.how_to_build and inspect actual layers and fallback information. A completed receipt can still contain flattened or partial results.

• Save the specification, mockup, layer images and available fonts locally. Signed links expire; refresh the same status to renew them.
• Reconstruct at the exact canvas width and height first. Preserve layer frames, z-order, rotation, opacity, crops and text metrics.
• Use live text and the supplied assets. Check OCR against the requested copy. Do not duplicate text already baked into the background.
• Use the cut layers — your products restyled — rather than the raw photos. Treat OCR text as a draft: replace invented prices, phone numbers, hours and handles with real facts, and do not present painted storefronts, products or people as real.
• For websites, build semantic sections with grid/flex and adapt the verified composition to smaller screens. Use native controls and accessible interactions.
• Verify each format in its own medium: convert a PPTX to PDF and compare each slide; rasterise a print PDF and check its size, boxes, crop marks, bleed, safe area and embedded fonts; render emails at 600 and 375 px; check images are exactly the format’s pixel size.
• Compare a rendered screenshot with the actual mockup before claiming fidelity. Repair fonts, metadata handling and layout with existing assets first.

Report missing text or assets, explicit fallbacks and any unavailable visual preview. Do not claim a single screenshot is an editable implementation. Return the project/artifact path, identifiers, actual reported charges and remaining limitations. Publication is a separate action.

Prompt to give your coding agent

Use Aixio Design through the connected MCP tools and the aixio-design skill. Use the page design I attached as the design reference (image 1) and my logo and product photos as brand assets (images 2–4). First check balance and confirm the brief and paid scope for one mockup plus one layer extraction. Show me the mockup and wait for my approval before cutting it. Use my existing framework. Build from the returned layers with live text, compare the result with the mockup, and report any fidelity limitations. Do not publish without my approval.