> Production API availability: use /api/v1/help?view=guides and the resource operations catalog before following a recipe. Some localhost capabilities are not deployed yet; an absent operation is unavailable.
Start with the site contract
Design one section at a time. Read the existing brand settings, template registry, section CSS fields and mapped content before choosing a layout. The goal is a section that the visual editor and an agent can both maintain.
curl --fail-with-body "$API_URL/site-design-contract" \
-H "Authorization: Bearer $API_KEY"
curl --fail-with-body "$API_URL/databoards/$BOARD_ID/agent-context" \
-H "Authorization: Bearer $API_KEY"API_URL includes /api/v1. The global contract describes the common approach; the board context supplies the site-specific branding and reusable pieces. Keep a record of the template and classes selected for the change.
Choose the layer that owns the change
- Content modules: article text, Docs chapters, form configuration, products and uploaded assets.
- Databoard mapping: which source record fills a template field.
- Section CSS configuration: classes assigned to the native header, body/data and footer elements.
- Board Sass workspace: the site's visual identity and scoped site-specific rules.
- Shared Sass v2: reusable components, tokens and layout behavior used by multiple sites.
- Shared JavaScript modules: progressive enhancement when native HTML and CSS do not provide the required behavior.
Do not edit a generated CSS file to make one screenshot look right. Change its owning source and publish through the factory.
Select a real template
Read the template information exposed by site-design-contract and agent-context. If the needed schema is absent, request it from a maintainer. Reuse the matching template's CSS schema. The header/body/footer idea is consistent, but the exact keys vary: some templates use data as the body configuration. Do not invent a body key because it sounds plausible.
A CSS field has a class string, style configuration and sometimes attributes. This is a fragment of a compatible section CSS object, not a complete section:
{
"header": {
"h1": {
"css_class": "factory-guide-title",
"css_styles": { "style": "" },
"attributes": ""
}
}
}factory-guide-title is a proposed site class, not an existing utility. Define it in the site's Sass workspace before relying on it. Prefer an existing semantic class or utility when the current site contract already provides the intended typography.
Use the foundation tokens
The shared token definitions live in styles_antsand/sass_v2/foundation/_variables.scss. They include semantic colors, spacing, typography, radii and breakpoints. Reusable components should use those variables rather than hardcoding a different scale for each page.
// Illustrative shared component rule, compiled in the v2 entrypoint context.
.factory-guide-card {
padding: $antsand-space-4;
border: 1px solid $antsand-gray-200;
border-radius: $antsand-radius-md;
color: $antsand-gray-900;
}Do not assume those Sass variables are imported into every standalone board file. Inspect the board's import order and compile context. A shared component is imported from antsand-v2.scss; a site's branding belongs in its board Sass/design configuration. Default tokens can be overridden before they are consumed, but redefining a variable after component compilation does not change the emitted CSS.
Map content without embedding layout
Keep the heading, paragraph, CTA and image URL in structured fields supported by the renderer. Use uploaded SVGs or images as assets. Keep the source URL and useful alternative text in the mapped media data.
If a card needs a label/value list and the renderer has no such field, first check whether another registered template supports it. If none does, add a reusable renderer capability and its schema rather than duplicating custom HTML across boards. Document the missing field and the tests for the extension.
Compile and publish the correct layer
For a Databoard class or Sass edit, validate the board patch through dry-run, then call the utilities endpoint after saving the board:
curl --fail-with-body -X POST \
"$API_URL/databoards/$BOARD_ID/utilities/compile" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" --data '{}'Shared Sass v2 source changes require a maintainer release; the public API does not offer arbitrary source editing or build-command execution. An API-only agent can configure supported board styles and use the documented board compilation endpoint. Report missing shared components instead of assuming filesystem access.
Regenerate the intended website to deploy its templates and shared assets. A central asset build and a generated-site release are separate boundaries. Inspect the CSS actually served by the site.
Keep interaction small
A reading page, architecture diagram or content card usually needs no application framework. Use links, details/summary, buttons and forms where they fit. If behavior is needed, put it in styles_antsand/js_v2/modules and import it from the shared entrypoint. Keep templates free of inline application scripts.
For a new shared behavior, test the source/public module match, entrypoint import and template boundary. Then test actual keyboard interaction, touch sizing, reduced motion when animated, and the no-JavaScript path. Authorization remains on the server.
Review a section before repeating it
Check typography, contrast, spacing, image aspect ratio, focus visibility, desktop/mobile layout and long content. Confirm the mapper still shows where the content comes from. Only then reuse the pattern across other pages.
Read data mapping, agent patches and validation.