Principles
Only ask for what you need
Forms can become lengthy, reducing task completion rates. Before adding another form field, consider whether you already know the answer, it can be inferred, or the workflow can proceed without it.
If you must ask, ask once. Don’t make the user enter the same information in different formats.
Section fields by purpose
Group fields by the task they support, not by their data type. A “Machine connectivity settings” section describes what fields might be expected within more than a generic “Settings” legend.
Use a legend to name the section. Keep legends short as a noun phrase, not a full sentence. Follow form sectioning advice.
Machine connectivity settings
Settings
Set expectations before the form
If completing a form successfully has prerequisites (needing an API key, particular user permission, connected account), communicate it before the user starts filling it out, not after they hit submit or in the middle of the page:
Before you start, you’ll need an API key from your Octopus instance. [Get one]
When setting expectations, use an appropriate notification messaging approach.
Never imply names are invalid
Forms often ask for people’s names but handle diverse input poorly. If a name “fails” validation, the onus should be on us, not the name provided. Don’t tell anyone their name is “invalid” as it’s exclusionary. If the system genuinely can’t accept certain characters, say so and explain why.
Our system can only store letters, spaces, hyphens, and apostrophes. Contact support if your name uses other characters.
Your name is invalid
Write the field content before the field exists
Decide what each label, helper, placeholder, and validation message should say before you build the component. Drafting these together in plain text catches inconsistencies and ambiguities.
Don’t use form field content for marketing
Form field content exists to make the field easier to fill in. It’s not a place to promote features. If a field needs a longer explanation, include what something is, why it matters, how it interacts with the rest of the product, a link to help documentation in the helper text, or use a Popover.
The role you assign here applies to all environments in this project.
Roles are a powerful Octopus feature that let you control exactly who can do what across your projects, environments, and tenants. We recommend assigning roles thoughtfully because they're really important.
Anatomy
Form fields consist of several elements that each play a different role in a confident user interaction:
- Label (required)
- Indicator (optional)
- Popover (optional)
- Helper text (optional)
- Placeholder (optional)
- Empty selection text, in Select and MultiSelect (required)
- Validation message (optional)
In most cases, form fields are grouped into sections with legends. While legends aren’t a part of a singular form field anatomy, they’re included here as they encapsulate a summary of the fields contained in a section.
Label
Labels clearly summarize the key piece of information we’re asking for. They should always be visible, clear, jargon-free, and short. Avoid asking questions in labels, as they increase cognitive load. Use noun phrases.
Release version
API key maximum expiry
Email address
Version
What’s the API key maximum expiry?
Enter an email address
Indicator
Predefined indicators show what information is needed. Required and optional are placed in parentheses and located right after the label. The indicator content should not be changed.
Email address (required)
Email address*
Other form field elements shouldn’t be used to indicate whether a field is required, as they’re not well supported by assistive technology.
Helper text
Helper text sits between the label and the input field. It’s optional, but can be helpful when:
- The label alone leaves room for ambiguity
- The expected input format isn’t obvious
- The user might be worried about why we’re asking for certain information
Use semantic versioning, e.g. 2024.3.1
Enter the release version
Popover
Popovers should be used to provide contextual information about the field’s subject matter that isn’t covered by labels, helper text, or placeholders. Popovers can include information about a feature or help materials, but should be used very sparingly. Popover is located in the same row as the label and indicator (if present).
Placeholder
Placeholders are optional, and should be used only to show valid input examples, not to provide instructions. Only use placeholders if necessary, as they make forms busier and are not a reliable source of information due to disappearing on focus. Don’t repeat label or helper text content in placeholders.
Enter your Octopus Server URL
Empty selection text, in Select and MultiSelect
Selects always show a resolved state. Text entry fields can be blank, because a blank text field reads as ready for input. A blank select is ambiguous: the user can't tell whether it holds no value, is still loading, or is broken.
Empty selection text is what a Select or MultiSelect shows before anything is chosen. It's a value, not a hint, so assistive technology reads it as the field's current selection.
Use the standard text
- Select: Select an option
-
MultiSelect: Select options
Use the defined standard text: Select option or Select options
Repeat the label. The label is always visible directly above the field, so restating it adds no information, and screen reader users hear it twice.
Use long explanations it creates mental load and visual noise.
Use ellipses such as Select... this is purely aesthetic preference for consistency.
When no selection has a meaning, use a real option
If "nothing selected" changes what happens, that's a value, not an empty state. Add it to the list as an option and select it by default, so the field reports what it will actually do.
Common cases:
- A filter where selecting nothing shows everything
- A setting that falls back to a parent or project-level value
- A field that applies a default when the form is submitted
Write the defaulted selected option as the outcome, not as an instruction.
For example, our Featured categories is a valid initial selection. Other examples, could be None, Deploy to all targets or .
By default have an empty selection.
Validation message
Inline validation messages sit beneath the input and are triggered by the information entered into the form fields. Messages associated with form fields should be no more than one sentence long.
Follow Error Messages Content Guidelines for more details on crafting effective error guidance.
The release 2024.3.1 already exists in the Production environment.
This release already exists.
Legend
Legend is a title summarizing the contents of a form section. It consists of several words describing the sections’ contents and an optional marker (optional, required or pre-filled).
Branch settings
Advanced settings
Voice and tone
Use sentence case
Use sentence case for labels, helper text, placeholders, legends, and validation messages. Only capitalize product and product names, as per our Grammar rules.
Release version
Release Version
Default to noun phrases for labels and legends
A label like Release version is faster to scan than What’s your release version?. Use questions only when the form is genuinely conversational, like in a step-by-step setup flow or an onboarding survey. Stick to one pattern across the whole form: don’t mix approaches.
Be conversational, but not chatty
Aim to act as a colleague, helping fill something out—keep it approachable, plain, and short.
Use semantic versioning, e.g. 2024.3.1
Hey! We need a release version from you 👋
A release version must be provided in accordance with semantic versioning conventions.