Form

Layout

The default is a single column. Follow the Form component's header / content / footer structure, and place labels above their inputs (top-aligned). Cap the content width at 480–560px so no line runs too long.

Left rail (type selector). Use a left rail only when the form has mutually exclusive variants that change which fields appear , for example chart type (Line / Number) or monitor type (Cron / Heartbeat). Without variants, keep a single column and no rail.

Right side panel. Reserve the right panel for one thing: a preview. Avoid keep conceptual explanations (like "What is a heartbeat?") there. Move them to a one-line header description with a Learn more link.

 

Required markers

Mark required fields with Required to the right of the label, and apply it the same way in every form. Today, only Storage and Monitor show it, while Chart leaves it out, so the rule looks different from form to form.

Avoid mark optional fields. No Required means the field is optional.

 

Choosing the right control

Use the same control for the same job. Choose controls based on the decision people are making, not personal preference. The number of options, interaction pattern, and when a change takes effect should drive the choice.

Guideline

• Radio vs Select: If there are five or fewer options and seeing them all helps the choice, use a Radio group. For longer lists, or when the selection changes other content (filters a table, switches a view, updates dependent fields), use a Select.
• Checkbox vs Toggle: Inside a form that's saved on submit, use a Checkbox for on/off settings. Reserve toggle for settings that take effect the moment they're flipped.
• Avoid collect form data with a dropdown: A dropdown is for actions and menus. To store a chosen value as part of the form, use a Select.
• Give every radio and checkbox group a group label, and keep option labels short and parallel.

 

Field help

Keep guidance intentional. Before adding supporting text, ask whether someone can complete the field correctly without it.

1. If the field can't be filled correctly without it (format, constraints, result), use an explanation. Place it below the label or input, always visible. E.g. "Lowercase, numbers, _ and - only", "Stored encrypted". This is the default for help.
2. If it’s nice to know, but the field works without it, use a tooltip. Attach it to a single (i) icon next to the label. Never hide required guidance here. Drop the (?) icon and standardize on (i).
3. If it needs more context or a warning at the form or group level, use a Message component. Use the header description (1–2 sentences) or a ==Message==: beta notices, destructive-action warnings. Trim long explanations to one line with a Learn more link.
4. If it needs an example of what the value looks like, use a placeholder. Put an example value in the placeholder, prefixed with e.g. so it isn't mistaken for a real value, e.g. background_job. Never use a placeholder in place of a label or required guidance.

 

Previews

Add a preview panel only when both are true:

• The result is visual (charts, dashboards, notification templates).
• The relationship between input and result isn't obvious at a glance.

Don't add one for forms whose result is text or config (storage credentials, a monitor identifier). Keep the preview sticky on the right with the controls it needs (e.g. a time range). When empty, use the empty state pattern.

 

Dividers & grouping

First group the fields by meaning, then decide how to separate the groups.

• By shared purpose: put fields that do the same job (connection details, options, notifications) in one group.
• In task order: follow the natural order people fill things in. Required and frequently used groups go first.
• A section label per group: add a short label (e.g. Connection, Options) above each group.

 

 

Input sizing

Input width hints at how long the value should be. Don't put a short value like a number + unit in a full-width input.