# Form section cards

Use a form section card to organize related editable information under one save boundary. The card establishes hierarchy without adding decorative containers around every field.

## Anatomy

1. **Optional header** — a concise section title, short description, and occasionally one quiet contextual action.
2. **Form body** — fields and subsections constrained by `--form-content-max-width` (56rem).
3. **Optional subsections** — headings and dividers for meaningful groups that submit together.
4. **Action footer** — submission status, Cancel, and the primary Save action separated from the form body by a divider.

The outer card uses `--surface-panel` and `--radius-panel` on the neutral page canvas. It does not need an additional border or prominent shadow.

## Save boundaries

Use one card per save boundary. If every field submits together, keep the groups in one card and separate them with headings and subtle dividers. Use separate cards when sections:

- submit independently;
- have different permission requirements;
- can fail or enter loading states independently;
- represent a distinct workflow rather than a field group.

Record lifecycle and Danger zone actions always remain outside the normal form card, even when they appear on the same Edit page.

## Header

The card header is optional when the page title already identifies a short, single-purpose form. Include it when the page contains multiple cards or the fields need additional context.

- Use a noun phrase such as `Asset details` or `Notification settings`.
- Keep the description to one or two short lines.
- Put only a directly related quiet action in the header.
- Do not duplicate the page title word for word.

## Field layout

- Use one column by default and on small screens.
- Use two columns for related compact fields when the available width remains comfortable.
- Let descriptions, textareas, code editors, wide entity selectors, and complex controls span both columns.
- Keep source and dependent fields in reading order; do not place fields only to balance visual whitespace.
- Use 20–24px between rows and 24px between columns.
- Keep labels persistent and validation adjacent to the affected field.

Immutable information should be rendered as a description list or read-only content block. Avoid using disabled inputs merely to display values.

## Subsections

Introduce a subsection heading when a form contains more than one conceptual group or when a group needs explanatory text. A divider precedes each subsection after the first. Do not create a titled subsection for every pair of fields.

Choice cards may be used for consequential checkboxes or radio options when their descriptions are important. Ordinary boolean fields should remain compact checkbox rows.

## Action footer

- Separate actions from the form body with a subtle top border.
- Put Cancel before Save in DOM and reading order.
- Align the action group to the right on desktop.
- Use a secondary or quiet Cancel and the neutral filled primary for Save.
- Use specific labels such as `Save settings` or `Save asset` when `Save changes` would be ambiguous.
- Keep button dimensions stable while processing and block repeat submissions.
- Show concise success feedback beside the actions without moving the buttons.
- Disable Save when there are no changes only when the disabled state is reliably synchronized with form dirtiness.

On narrow screens, make both actions full width and place the primary Save action above Cancel visually while preserving a logical reading order.

## Errors and focus

Keep validation errors next to their fields and associate them using `aria-describedby`. When submission fails, move focus to an error summary only when multiple errors may be outside the viewport; otherwise focus the first invalid field. Do not clear valid user input after an unsuccessful submission.

## Long forms

Prefer multiple meaningful sections over a sticky action footer. A sticky footer is appropriate only when a form is unusually long and users must save frequently; it must not cover fields, validation, or mobile browser controls.