Open source website builder and Webflow alternative. Webstudio is an advanced visual builder that connects to any headless CMS, supports all CSS properties, and can be hosted anywhere, including with us.
TypeScript accessibilityalternativecloudflarecloudflare-workersdesignfreefrontendopen-sourceradix-uireactremixweb-developmentwebflowwebsite-builderwebsite-developmentwebsiteswebstudio
// This file is generated by scripts/generate-docs.mjs.
// Edit markdown files in src/docs instead.
export const projectBuildDocs = {
"accessibility-review":
'<!-- Adapted for Webstudio MCP from Community-Access/accessibility-agents, web-accessibility-wizard/SKILL.md (MIT): https://github.com/Community-Access/accessibility-agents/blob/main/codex-skills/web-accessibility-wizard/SKILL.md -->\n\n# Webstudio Accessibility Review\n\nUse this workflow when creating or reviewing a page, component, form, menu,\ndialog, or responsive layout. It is an LLM-assisted review, not proof of WCAG\nconformance. Do not claim that a page is accessible solely because this review\nhas no findings.\n\n## Evidence First\n\n1. Read `meta.index` and use focused project tools. Do not inspect Webstudio\n source code or generated files for normal project reviews.\n2. Run `audit` with `{"scopes":["accessibility"]}` before changing\n anything. It detects deterministic metadata issues such as labels, landmark\n structure, positive tabindex values, invalid static ARIA states, and unmuted\n autoplay. Fix confirmed static findings first.\n3. Ask whether the user wants visual verification unless they explicitly\n requested it. Only after they opt in, use `preview.start` and capture each\n changed route with `screenshot` at desktop, tablet, and mobile widths. Use\n `waitForSelector` or `waitForTimeout` only when the page has an actual\n delayed ready state. If they do not opt in, continue with static evidence\n and mark visual findings as manual verification items.\n4. Use `get-page-by-path`, `list-instances`, `inspect-instance`, and focused\n prop/style reads to verify semantics and authored state that screenshots\n cannot prove.\n5. Make only supported, evidence-based fixes with semantic MCP tools. Recheck\n the affected route and the static accessibility search after every fix.\n\n## Review Areas\n\nReview these areas in priority order. Record the evidence for every finding.\n\n### 1. Names, Semantics, and Structure\n\n- Every image has purposeful alternative text or an explicitly empty alt when\n decorative. Image-submit inputs need a non-empty alt label describing their\n action.\n- For `missing-image-description` findings, inspect the rendered image in its\n page context and call `set-image-descriptions` with either a concise generated\n description or `decorative: true`. Re-run the audit after saving the decision.\n- Buttons, links, icon-only controls, and form controls have accessible names.\n- Prefer native HTML semantics over ARIA roles.\n- Non-native elements using `role="button"` or `role="link"` must be\n keyboard-focusable.\n- Use one sensible page h1, ordered heading levels, meaningful link text, and\n a main landmark.\n- Iframes have titles. Static HTML ids are unique, ARIA reference props point\n to real ids, and static boolean/select/numeric ARIA values are valid.\n- Focusable controls must not be hidden from assistive technology with\n `aria-hidden`.\n\n### 2. Keyboard and Focus\n\n- Interactive controls should be native or have a documented keyboard model.\n- Visible focus must not be removed without a visible replacement.\n- Hover-only information or controls need a keyboard-accessible equivalent.\n- Do not use positive tabindex values.\n- Mark keyboard behavior as **manual verification required** when the available\n evidence cannot prove tab order, Escape handling, or focus restoration.\n\n### 3. Dialogs, Menus, and Other Overlays\n\n- Dialogs need an accessible name and a close action.\n- Opening an overlay should move focus into it, trap focus where appropriate,\n and restore focus to its trigger on close.\n- Menus, popovers, disclosures, and tabs must expose their expanded/selected\n state and remain usable without a pointer.\n- If the current MCP/browser tools cannot exercise the interaction, report it\n as a manual verification item instead of guessing.\n\n### 4. Forms and Errors\n\n- Inputs have labels, required state, helpers, and errors associated with the\n right control.\n- Invalid controls expose `aria-invalid` when applicable.\n- Error, loading, and success feedback is not conveyed only by color or a\n transient visual toast.\n- Submit controls do not become unexplained dead ends when disabled.\n\n### 5. Visual, Responsive, Media, and Motion\n\n- At each target width, text remains readable, controls remain reachable, and\n no content is clipped, overlapped, or dependent on hover alone.\n- Do not rely only on color, position, shape, or iconography to convey meaning.\n- Keep non-text contrast, text contrast, focus indicators, and small text as\n visual review items unless measured evidence is available.\n- Videos with meaningful speech need captions; non-essential motion should\n respect reduced-motion preferences. Do not autoplay sound.\n\n### 6. Dynamic Content and Data\n\n- Loading, empty, error, and success states have understandable visible text.\n- Important dynamic updates and validation feedback need an appropriate\n announcement strategy.\n- Check repeated resource-driven content for unique labels, headings, ids, and\n meaningful empty states.\n\n## Findings and Fixes\n\nClassify every item as one of:\n\n- **Confirmed:** directly shown by `audit`, project data, or a rendered\n screenshot.\n- **Likely:** a credible issue inferred from rendered evidence; explain what\n would confirm it.\n- **Manual verification required:** needs keyboard, screen-reader, contrast, or\n interaction testing that the available tools cannot prove.\n\nFor each item include: severity (`critical`, `high`, `medium`, or `low`), page\npath, affected element or instance id when known, evidence, short user impact,\nand the smallest supported fix. Fix critical and high items first. Do not add\nARIA attributes, alt text, labels, or live regions when their meaning cannot be\nknown from the project; ask the user or report the missing context.\n\nFinish with a concise summary of fixed findings, remaining findings, and manual\nverification items. Use screenshots as evidence of the rendered state, not as\nproof of accessibility compliance.\n',
expressions:
'# Webstudio Expressions\n\nUse an expression only when a value must be computed at runtime from scoped\ndata. Use direct text and direct prop values for fixed content.\n\n## Source Format\n\nExpression-capable MCP fields receive JavaScript expression source as a JSON\nstring. Send one expression, without a `return` statement or surrounding\nfunction. For example:\n\n```json\n{ "binding": { "type": "expression", "value": "post.title ?? \\"Untitled\\"" } }\n```\n\nInside that string, use readable JavaScript syntax rather than serialized JSON.\nFor object expressions, leave identifier property names unquoted, for example\n`{ query: queryText, variables: { slug: system.params.slug } }`. Quote a property\nname only when JavaScript requires it, such as `{ "published-at": date }`. Do\nnot pass a JSON-stringified object as an expression.\n\nDo not send a fixed prop string as an expression. Use `update-props` with\n`type:"string"`. Page metadata fields contain expression source; for fixed text,\npass a quoted JavaScript string expression such as `"Plans"`. Resource URLs\naccept plain fixed strings and normalize them for storage. Expression-only resource headers, search parameters,\nand bodies accept `{ "type": "literal", "value": "fixed text" }` when the\nvalue is not dynamic.\n\n## Read and read-write bindings\n\nExpression bindings use `mode:"read"` by default. Use `mode:"readwrite"` only\nfor an exact direct path into the frontmatter of an MDX source connected to the\ncontaining Content Block, for example:\n\n```json\n{\n "binding": {\n "type": "expression",\n "value": "document.frontmatter.title",\n "mode": "readwrite"\n }\n}\n```\n\nThis lets Content mode save a direct edit back to that frontmatter field.\nComputed expressions, including fallbacks and concatenation, are always\nread-only. The mutation is rejected when the expression is not a direct path or\ndoes not belong to a connected Content Block document. Use the variable name\nreturned by `inspect-instance`; do not assume it is `document`.\n\nFor an MDX-backed article, use the query resource to select the Content Block\'s\nsource Asset, for example `post.data.id`. Inside the block, bind article fields\nto the block\'s document parameter, not `post.data.properties.title` or other\nequivalent query-result values. A query binding can display the correct value\nwithout supporting Content-mode edits.\n\nThe MDX body is editable through its source mapping. Designer-created elements\noutside that body, such as an article header, stay protected unless their text\nor supported props have writable frontmatter bindings. Containment in the\nContent Block alone is not enough. Use `update-text` with\n`expressionBindingMode:"readwrite"` for a designed heading\'s text, and\n`bind-props` with `binding.mode:"readwrite"` for a supported prop. These target\npersistent designed instances, not MDX-generated instances.\n\nUse direct paths for writable bindings, such as\n`document.frontmatter.title`; property access is already safe. Adding `??`\nfallbacks or formatting makes the expression read-only. Direct bindings through\nloaded Markdown or MDX `$ref` values ending in `#frontmatter` save to the\nreferenced file, with its write permissions enforced. For example, editing\n`document.frontmatter.author.name` updates the shared author file, affecting\nevery article using it while preserving the article\'s reference. JSON/body\nreferences remain read-only. Image replacement is a supported reference write,\nnot a write to shared resolved metadata; use the image recipe below.\n\n### Make an article image replaceable\n\nFor `featureImage: { $ref: "./images/hero.png" }`, bind the designed Image\'s\n`src` to `document.frontmatter.featureImage.src` with explicit `mode:"readwrite"`.\nThe default `read` mode renders the image but does not let the Content-mode\neditor replace it. A disabled resolved-URL input is expected; the active\n**Choose source** picker is the replacement control.\n\nUse `bind-props` with the actual Image instance ID and document variable name:\n\n```json\n{\n "bindings": [\n {\n "instanceId": "<imageInstanceId>",\n "name": "src",\n "binding": {\n "type": "expression",\n "value": "document.frontmatter.featureImage.src",\n "mode": "readwrite"\n }\n },\n {\n "instanceId": "<imageInstanceId>",\n "name": "alt",\n "binding": {\n "type": "expression",\n "value": "document.frontmatter.featureImage.description",\n "mode": "read"\n }\n }\n ]\n}\n```\n\nThe picker saves a new `$ref` in the article. It must not save a resolved URL\nstring or modify the original shared Asset. Shared alternative text uses\n**Choose source → asset actions → Settings → Description** instead.\n\nIf the picker is absent or disabled, first inspect the source binding\'s mode,\ndocument scope, loaded `$ref`, and permissions. Do not infer that replacement\nis unsupported from a correctly rendered image or the disabled URL input.\n\n### Verify the whole article, not just its body\n\nIf the user asks for full Content-mode editing, inventory every article field,\nincluding the designed header, hero image source, alternative text, captions,\nauthor details, dates, reading time, links, and custom-component content.\nVerify each field through its Content-mode UI, inspect the saved MDX or\nreferenced file, reload, then restore and verify the original value. A valid\nbinding, correct preview, or successful MCP edit is not a UI-editability test.\nReport each field as passed, failed, or not tested; do not call the article\nfully editable with required fields missing or untested.\n\nFor images, use the recipe above and verify the picker, changed `$ref`, reload,\nand restoration with an approved temporary replacement. Confirm unrelated MDX\nand the original shared Asset remain unchanged. A metadata edit or a disabled\nURL input does not test image replacement. If the replacement test is not\nauthorized, record it as not tested rather than passed.\n\n### Keep editable values separate from formatting\n\nWhen a field must be editable in Content mode, do not concatenate its value\nwith labels, units, or punctuation, or wrap it in a template literal, fallback,\nor formatting call. Keep the value in its own text element with one direct\nread-write binding. Put the fixed prefix and suffix in separate sibling text\nelements. Do not mix literal and expression children in the value element.\n\nFor example, display reading time as three inline siblings: fixed `— `,\nan element bound to `document.frontmatter.readingTime`, and fixed ` min read`.\nSet `expressionBindingMode:"readwrite"` on the middle element with `update-text`.\nThe number remains editable while the surrounding wording stays protected.\nPreserve spacing and the field\'s stored type. For dates, prefer a Date Time\ncomponent with its date prop bound directly and formatting configured separately.\n\nDo not silently choose a read-only expression to achieve the requested display.\nIf a required transformation has no editable presentation, explain the limitation\nand ask before making that field read-only. This does not extend the supported\nwrite targets or override permissions.\n\n## Scope\n\n- Data variables are available on their scope instance and descendants.\n- An inner variable with the same name masks the outer variable.\n- A scoped resource result is a variable. Read its payload from its result\n wrapper, usually `resourceName.data`; APIs may nest the desired value deeper.\n- Collection creates internal `collectionItem` and `collectionItemKey`\n parameters. They are available only to that Collection\'s descendants.\n Preserve those generated parameters and do not reuse encoded parameter ids\n copied from another Collection.\n- Array Collection iteration exposes the current item. Object iteration exposes\n the current key and value.\n- The built-in `system` context is available only where supplied by the runtime.\n Its documented fields are `system.origin`, `system.pathname`, `system.params`,\n and `system.search`. There is no `system.path`.\n- Actions expose only their declared arguments, such as `event`, plus data that\n is in scope.\n\nRead `list-variables`, `list-resources`, `inspect-instance`, and existing\nbindings before writing an expression. Do not guess identifier names. Syntax is\nvalidated when a mutation is submitted. A valid expression that references an\nidentifier unavailable in that scope is accepted with a structured warning\ncontaining the field path, source range, affected record, and remediation.\n\n## Supported Syntax\n\nExpressions support literals, arrays, objects, property and index access, unary\nand arithmetic operators, comparisons, logical operators, nullish coalescing,\nternaries, and template literals.\n\nWebstudio automatically makes property and index access safe when an\nintermediate value is missing. Always write direct access such as\n`post.author.name` or `formData.subject`; never add optional property access\n(`?.`) to an authored expression. The expression compiler inserts it into\ngenerated JavaScript, so do not copy that generated syntax into a binding. Use\nnullish coalescing when the expression needs a fallback value, for example\n`formData.subject ?? "New message"`.\n\nSupported string methods:\n\n{{allowedStringMethods}}\n\nSupported array methods:\n\n{{allowedArrayMethods}}\n\nOther values support `toString`. Arbitrary global functions and arbitrary\nmethod calls are not supported.\n\n## Unsupported Syntax\n\nDo not use statements, declarations, functions, arrow functions, classes,\n`new`, `this`, `await`, imports, tagged templates, sequence expressions,\nincrement/decrement, or destructuring assignment. Assignment is allowed only\ninside actions. Use an explicit assignment there rather than `++` or `--`.\n\n## Common Examples\n\n- Text: `post.title ?? "Untitled"`\n- Prop: `post.url`\n- Nested API array for Collection: `posts.data.items`\n- Resource URL: `"https://api.example.com/posts?tag=" + filters.tag`\n- Header: `"Bearer " + auth.token`\n- Search parameter: `String(filters.page ?? 1)` is not supported because global\n function calls are forbidden; use `(filters.page ?? 1).toString()` instead.\n- Resource body: `{ query: queryText, variables: { slug: system.params.slug } }`\n- Conditional: `featured ? "Featured" : "Standard"`\n- Nested access with a fallback: `post.author.name ?? "Unknown author"`\n\n## Collections\n\nWhenever an array or object should render repeated UI, call `insert-collection`\nwith the complete iterable and one repeated-item JSX root. Do not pass the\nresponse wrapper or one indexed item. The command creates the Collection and\nits private item parameters atomically, then renders the item root once per\nentry. Bind descendants with expressions such as `collectionItem.name`; for\nobject iteration, `collectionItemKey` contains the current key. Wrap multiple\nrepeated siblings in one lowercase HTML root such as `<div>`.\n\n## Verification\n\nInspect every returned expression warning. Correct warnings that indicate a\nmisspelled or unavailable variable, then run `verify-bindings` for persisted\nsyntax, scope, and reference integrity. A warning does not roll back the\nmutation, and successful static verification does not prove runtime data has\nthe expected shape. `verify-bindings` never executes external resources or\nresolves rendered values. Preview representative data, empty/null data, and\nCollection item counts; use `audit` for relevant structural findings.\n',
"mcp-startup-guidance":
'If you are inside the Webstudio monorepo, use the local CLI exactly as `node packages/cli/local.js ...` as your first command path. Do not use `packages/cli/bin.js` for local source-tree work; it is the packaged build entry and may use stale built output. Before editing a Webstudio project, do one small discovery step, then act. For delegated design-system or “use every component” tasks, the first MCP command is `workflow.next {"goal":"design-system-page"}`; report that returned checkpoint to the parent/user and stop until continued. For a simple authored/styled section, the intended path is literal: call `meta.index`, call `meta.get-more-tools` with `{"tools":["insert-fragment"]}`, read the target parent id with `list-pages`/`get-page-by-path`/`list-instances` only if needed, then call `insert-fragment`. Prefer `insert-fragment` for authored/styled sections; use `insert-component` only when inserting one automatic component template. Do not grep source files, dump full MCP resources, or write parser scripts before trying focused MCP calls. Good first calls are `meta.index` for orientation, `meta.guide` for a goal workflow, `workflow.next` for one bounded delegated phase, `meta.get-more-tools` for exact tool schemas, and `components.coverage-plan`, `components.coverage-insert-next`, `components.find`, or `components.get` for component work. Do not call every discovery tool up front. For delegated or non-streaming agents whose parent cannot see live stderr/stdout, treat each parent-visible checkpoint as the unit of work. If the parent asks for status within 30 seconds, run exactly one shortcut command such as `webstudio meta.index` or one explicit `webstudio mcp single-op-call` command, report its command/result, and wait for the parent before the next MCP command. Do not run long shell loops of shortcut or `webstudio mcp single-op-call` commands; they hide progress from the parent. Do not take a broad task such as creating a full design-system page as one execution unit. Instead call `workflow.next {"goal":"design-system-page"}`, report the returned phase/checkpoint to the parent, wait until the parent continues, call `checkpoint.ack {"reported":true,"continueAfterReport":true,"summary":"<what you reported>"}`, complete exactly that bounded phase, and return: discovery, page creation, one dry-run JSX section, one committed JSX section, one `components.coverage-insert-next` call, or one presentation pass. Phase commands do not include nextPhase in their own output. After the parent continues, acknowledge the previous checkpoint first, then call `workflow.next` with the next phase. For design-system or “use every component” tasks, start with `workflow.next`, acknowledge its checkpoint only after parent/user continuation, then run compact `components.coverage-plan`, checkpoint, create the page, checkpoint, then call `components.coverage-insert-next` once per coverage checkpoint, and finish with the `presentation-pass` workflow phase. Coverage 72/72 is necessary but not sufficient: the page must be organized into styled, real-world design-system examples instead of raw unstyled component dumps. Request component coverage details with `components.coverage-plan {"detail":"roots"}` or `components.coverage-plan {"detail":"parts"}` only when needed. `list-pages` does not accept `detail`; use `list-pages {}` or `get-page-by-path` for page lookup. Read overview resources such as `webstudio://project/guide`, `webstudio://project/tools-overview`, and `webstudio://project/components-overview` only when focused tools are insufficient. Do not dump or parse full resources such as `webstudio://project/tools` or `webstudio://project/components` unless the focused tools are insufficient. Run one-shot shortcut or explicit `webstudio mcp single-op-call` commands sequentially against the same linked `.webstudio` folder. For experiments, pass `--dry-run` to local-capable mutations. Copying a `.webstudio` folder is not an isolated project clone; `.webstudio/config.json` still points to the same remote project, so non-dry-run mutations can commit to that project. If a one-shot call returns checkpoint.required, the CLI persists `CHECKPOINT_REQUIRED` across later one-shot calls until you report the checkpoint, wait until continued, and call `checkpoint.ack {"reported":true,"continueAfterReport":true,"summary":"<what you reported>"}`. If you receive `PROJECT_SESSION_BUSY`, another CLI/MCP process is updating the local session; wait a moment and retry sequentially. Complete one bounded phase and return a checkpoint before continuing. Follow the guide: read ids and Builder breakpoints first, use focused component discovery for component ids, props, and content model composition, prefer semantic tools over `apply-patch`, use direct value tools for fixed text/props, use bindings only for dynamic expressions/resources/actions, fixed page metadata text requires a quoted string expression, while fixed resource URLs accept plain strings, put page/resource update fields under `values`, and do not edit generated files for normal content/design changes. Never run visual verification automatically: ask first unless the user explicitly requested screenshots, visual verification, or a rendered audit, and only then use `preview.start` plus screenshot/vision.\n\nWhen `report-issue` is available and the user explicitly asks to report a problem, call it once without requiring a GitHub login. Also call it automatically after a Webstudio-controlled tool crash, hang, malformed result, misleading success, repeated failure of the same documented operation, failed documented recovery, or required undocumented workaround. Do not automatically report expected confirmation/checkpoint flow, a clearly explained invalid input, missing permissions, `PROJECT_SESSION_BUSY`, a recovered version conflict, rate limiting, cancellation, or an offline environment. The LLM must write a complete technical report with the generalized user story, summary, attempted workflow, expected behavior, actual result, recovery attempts, user impact, technical context, acceptance criteria, exact model identifier, and reasoning effort. The CLI attaches the project ID and recognized entity IDs from the failed tool input; do not copy additional IDs into the authored text. Never include names, usernames, emails, phone numbers, organizations, domains, URLs, IP addresses, local paths, credentials, tokens, customer content, or other exact unique values. Do not copy raw tool inputs, outputs, or contextual errors; preserve only stable tool names, schema fields, error codes, CLI versions, and generalized input shapes. Use `unknown` instead of guessing unavailable model metadata.\n\nIf a mutation returns an unclear transport or response error, make one read-only check to see whether it committed and include that outcome in the report. For browser startup failures, include the selected browser family, whether fallback was attempted, and any shown exit signal or code, but never an executable path. The CLI adds bounded failure diagnostics automatically; do not paraphrase missing values as facts.\n\n## Content Block completion\n\nContent Block work is not complete after one editable heading works. For every creation, migration, or repair, with or without MDX, inventory all intended editor-owned fields and their write destinations before implementation. Use semantic controls (calendar for dates, image picker for image replacement), keep fixed wording separate from direct writable bindings, and preserve existing field types and wording. Verify each field through Content mode, saved data, and reload; restore test values. Report passed, failed, or not tested per field. Missing or read-only required controls are unfinished requirements. Never substitute a correct preview or MCP write for the UI test.\n\nFor MDX articles, include the designed header, reading time, dates, images, alternative text, links, author fields, and custom-component content—not just the body. For a designed Image, use `bind-props` with `src` bound directly to `document.frontmatter.featureImage.src` and explicit `binding.mode:"readwrite"`; the default read-only mode can render correctly while hiding replacement controls. **Choose source** changes the article\'s image `$ref`, not shared resolved Asset metadata; the disabled URL input is expected. Keep the `.description` alt binding read-only and edit shared Description through Asset settings. Inspect binding mode, document scope, loaded reference, and permissions before claiming image replacement is unsupported. Follow the expressions guide\'s image recipe and whole-article verification checklist before handoff.\n',
} as const;
export type ProjectBuildDocName = keyof typeof projectBuildDocs;