#Layouts and supporting content

Layout nodes organize the interface without changing the controlled value structure. Fields continue to bind data through schemaPath, while containers use children to define order and nesting. Every example uses the real FormRenderer and the A3S UI style entry point.

#Common container properties

Narrow containers collapse side-by-side fields and column groups into one column. Responsive behavior uses the Form container width, not the browser viewport, so the same layout works in a sidebar, dialog, or workspace node.

#Grid container grid

Use a grid container for parameter panels where fields need different widths. Each child's width determines its span, and columns defines the internal grid width.

{
  "model": "large",
  "timeout": 60
}

{
  id: 'runtime-grid',
  kind: 'group',
  layout: 'grid',
  columns: 12,
  gap: 16,
  children: ['model', 'timeout'],
}

#Two-column layout columns-2

columns-2 is a Designer preset. It creates an outer layout: "columns" container and two inner groups with width: 6. Each column can contain fields, cards, or other layouts.

{
  "endpoint": "https://api.a3s.dev",
  "retries": 3
}

Use two columns when two items benefit from direct comparison. Do not force long guidance, addresses, or multiline inputs into a narrow column.

#Three-column layout columns-3

columns-3 is also a Designer preset. Its three inner groups each use width: 4. It works well for short values and related parameters, but not for long text or complex composite fields.

{
  "region": "ap-east-1",
  "concurrency": 4,
  "timeout": 90
}

In a narrow container, all three columns automatically stack while preserving children order.

#Card group card

Use cards for a business group with a meaningful title and description. kind: "section" provides grouping semantics, and layout: "card" uses the A3S UI Card surface.

{
  "service": "knowledge-search",
  "enabled": true
}

Do not wrap every field on a page in a card. Use a card only when its title, description, and fields form one complete task.

#Tabs tabs

Tabs suit peer settings that do not have to be completed in order. The outer node uses layout: "tabs"; every direct child must be a group or section with layout: "tab".

{
  "displayName": "知识检索",
  "temperature": 0.4
}

The runtime exposes tablist, tab, and tabpanel semantics and supports Left Arrow, Right Arrow, Home, and End. Use a wizard for ordered steps with progressive validation and review; do not simulate steps with tabs.

#Collapse panels collapse

Collapse panels suit infrequent or advanced settings. The outer node uses layout: "collapse", and its direct children use layout: "collapse-panel".

{
  "systemPrompt": "只返回可核验的信息。",
  "maxTokens": 2048
}

The runtime uses native details and summary, leaving keyboard behavior, expanded state, and assistive-technology semantics to the browser. Do not hide required fields in a closed-by-default panel without an error indicator.

#Supporting text content

Supporting text uses kind: "content" with presentation: "text". It displays static copy without creating a Schema property or writing to the controlled value.

{}

Supporting text should contain only information needed to complete the form. Dynamic data, rich text, and executable links belong in an approved host component.

#Divider divider

A divider separates adjacent content regions. Leave content empty for a line, or set it to display a short label in the middle.

{}

A divider does not replace structure. Prefer a section or card when the content has a meaningful title.

#Spacer spacer

A spacer provides controlled vertical whitespace. It is hidden from assistive technology and creates neither copy nor a form value.

{}

Use spacers sparingly where extra breathing room is necessary. Container gap should maintain the page's base rhythm.

#A3S UI style entry point

import '@a3s-lab/ui/form/a3s-ui.css';

This entry point loads @a3s-lab/ui and the Form layout layer. Fields continue to use A3S UI input, textarea, select, field, and fieldset contracts, while containers reuse Card, Tabs, and Accordion surfaces and interaction states. If the host already loads A3S UI, use @a3s-lab/ui/form/styles.css to avoid installing global styles twice.