# Cloudflare forms

Use this reference when designing or reviewing forms.

Source study: [Cloudflare forms](https://design.thorbis.com/research/studies/cloudflare-forms). The repository study is `content/design/CLOUDFLARE_FORMS_REFERENCE.md`.

## Required decisions

1. Choose the form mode: simple, configuration, dense inline, or guided.
2. Use a visible label. Placeholder is format/example only.
3. Use native semantics before custom JS validation. Correct input types, labels, required state, and browser behavior remain the foundation.
4. Size the field to the data rather than making every input full-width.
5. Put help beside the choice it explains.
6. Keep validation local and specific.
7. Preserve final geometry while loading.
8. Use a consequence-naming commit action: `Save customer`, not `Submit`.
9. Protect unsaved work according to the existing Thorbis dirty-state rules.
10. Use the density and touch contract owned by [UI](https://design.thorbis.com/skills/ui#controls) and [Components](https://design.thorbis.com/components.md). Native apps follow [Native](https://design.thorbis.com/skills/native) under D-025; this web reference does not set native control sizes.

## Configuration form anatomy

```text
FormSection
  FormSectionInfo
    title
    description
    optional help link
  FormSectionFields
    FormField
      Label
      Input | Select | Textarea | Combobox
      HelpText | FieldError
```

Use the split anatomy only when the explanation benefits more than one field. A small form stays one column.

## Geometry follows the work

Use the existing field, spacing, and density tokens. This reference does not define another size scale.

- A short code field and a long address field need different widths.
- A textarea reserves room for the expected answer and grows without hiding its label or recovery action.
- Keep label, field, and help together; give separate groups more space. The operator should see which instruction belongs to which field.
- Keep durable configuration readable. A wide workbench is not a reason to stretch every field across it.
- Loading, focus, validation, and save feedback preserve the control's footprint.

The older copy's fixed gap, column, and textarea ranges remain in Git history. Current tokens and the component contract govern implementation; those examples are not a second scale.

## Visual grammar

- Thorbis field surface and border tokens.
- Thorbis radius, field surface, electric-blue focus, and existing type scale.
- Use semantic focus and selection tokens; action prominence follows DESIGN.md D-023.
- No Cloudflare orange, font, chrome, exact radii, or card styling.
- No card around every field.
- Surface fills follow DESIGN.md D-018.
- Error is local: danger rim + copy; do not wash the whole section red.

## Review failures

Fail the form if:
- placeholder is the only label,
- an error is only in a toast,
- every input is 100% width regardless of data,
- a technical choice requires leaving the workflow to understand it,
- the form uses generic `Submit`,
- a long durable workflow is squeezed into a modal,
- focus changes geometry,
- mobile simply shrinks a 32px desktop form,
- another product's colors or chrome are copied.