# Content guidelines

Voice, tone, terminology, and UX-pattern copy guidance — Actian DS.

> **Auto-generated** by `scripts/content/derive-content.js`. Do not edit this file directly — edit the per-section source files.
>
> **Scope:** cross-cutting writing guidance (voice, tone, capitalization, words to avoid) and UX-pattern topics. Component-scoped content guidance lives per-component in `components/dist/guidelines/{slug}.json` instead.
> **Sources** (24 sections): `content/src/{bucket}/{slug}.md` where bucket is one of writing, patterns, product (plus `global-guidelines.md` at the root).
> **Authoring guide:** `content/src/AUTHORING.md`

---

## Global guidelines

Actian Data Intelligence speaks to data professionals: engineers, analysts, and catalog administrators. The voice is direct, precise, and professional without being formal or stiff.

These guidelines define the writing principles, style, and word choices that apply to all product copy. See the sections below for specific guidance.

---

## Voice and tone

Actian Data Intelligence speaks to data professionals: engineers, analysts, and catalog administrators. The voice is direct, precise, and professional without being formal or stiff.

Apply these guidelines to all UI copy, including labels, tooltips, empty states, error messages, and notifications.

---

### Style

- Use active voice. "Export the dataset" not "The dataset can be exported."
- Use present tense. "Saves automatically" not "Will save automatically."
- Use sentence case for all UI text, including headings and button labels.
- Do not use exclamation points except in genuine success states.
- Do not use "please" or "sorry" — they add length without value.

### Do / Don't

| Do | Don't |
|---|---|
| Export the dataset | The dataset will be exported |
| Something went wrong | We're sorry, something went wrong |
| Log in | Sign in / Signin |

---

## Writing style

Use present, active tense in all possible cases. In some cases, you can use passive voice if the focus needs to be on a system instead of a person.

---

### Tense and voice

| Voice | When and how to use | Example |
|---|---|---|
| Active | All cases except where passive is needed | Only an administrator can create a warehouse. |
| Passive | Use only when focus is not on a person | The database needs to be shut down. |

### Tone

- Be direct, active, and consistent.
- Be friendly and helpful.
- Use the simplest terms. Don't try to "beautify" with alternatives.
- Do not personify the product as the subject of the text.
- Avoid humor; it rarely translates.
- Avoid idioms, sarcasm, metaphors, slang, colloquialisms, and jargon.
- Do not use racial, gender, or cultural-biased language.
- Use gender-neutral pronouns to help make text inclusive.
- Use the second person: "you." Don't use "I," "we," or "us" to refer to the user.

| Do | Don't |
|---|---|
| Submit form | Click here to submit the form |
### Personification

Do not personify the product as the subject of the text. Keep the user in focus, rather than the product.

| Do — User focus | Don't — Product focus |
|---|---|
| In the Delivery Information window, specify the name of the sender. | The Delivery Information window allows you to specify the name of the sender. |
| Use this menu to create diagrams. | This menu enables you to create diagrams. |

---

## Capitalization

Don't overuse capitalization — it makes copy harder to read and de-emphasizes the important content.

---

### When to use each case

| Title case | Sentence case | All caps |
|---|---|---|
| Top-level navigation | In-line and standalone links | Functional text |
| Main page headers only | Section headers, checkboxes, radios, badges, sliders, toggles, tooltips, tags, pills, toasts, loading indicators | Acronyms (API, not Api) |
| Menu titles | Placeholder text inside form fields | |
| Menu items | Labels | |
| Proper nouns | Buttons | |
| Names of people or products | Column headers | |

### Do / Don't

| Do | Don't |
|---|---|
| Add a row to the catalog. List it on the page. | Add a row to the Catalog. List it on the Page. |
| Add a row to the MyCatalog page. | Add a row to the MyCatalog Page. |
| Selects an item type. | Select an Item Type. |

---

## Words to avoid

Guidance on what content works best, including text, imagery, and messaging.

---

| Example | Do | Don't |
|---|---|---|
| Never say "Please" or "Sorry" — they are unnecessary. | Contact Support | Please Contact Support |
| Don't refer to Actian as "we" or "us." | Actian recommends | We recommend |
| Don't use "Execute" or "Abort." | The process was cancelled/stopped | The process was aborted. |
| Don't use "Master" or "Slave." | Primary and Secondary servers | Master and Slave servers |
| Don't use "Blacklist" or "Whitelist." | Add a row to the Allow/Deny List | Add a row to the Black/Whitelist |
| Don't use "Press" or "Type" as verbs. | Click "OK", Enter/Provide a name | Press "OK", Type a name |
| Never use developer-speak. | Click the **OK** button. | Click the OK CTA. |
| Don't use "Caution" or "Danger." | Remember: Restart the server first. | Danger: Stop the server first. |
| Don't use "Ensure." | Verify that the value is provided. | Ensure you provided the correct value. |
| Don't use "Disabled." | This setting is blocked/off | This setting is disabled |
| Don't use "Agnostic." | This feature is platform independent | This feature is platform agnostic |
| Don't use "Sign in" or "Signin." | Log in to begin | Signin to begin |

---

## Punctuation

To help readers scan text at a glance, avoid using punctuation in places where it isn't necessary.

---

### Ampersands ("&")

Avoid using ampersands in place of "and" except for common abbreviations (e.g. Q&A) or when the ampersand is part of an organization's formal name (e.g. H&R Block, AT&T). In those cases, follow the organization's formal spacing style.

| Do | Don't |
|---|---|
| Common abbreviations: Q&A. Organization formal names: H&R Block, AT&T | Using & in place of "and" in general copy |
### Periods (".")

Avoid using periods on solitary sentences within these UI elements:

| Use periods | Don't use periods |
|---|---|
| Multiple sentences | Labels |
| A sentence followed by a link | Hover text |
| Description text | Tooltips |
| | Placeholder text |
| | Radios |
| | Loading indicators |

### Commas (",")

Use a comma after the second-to-last item in a series, before the conjunction (serial/Oxford comma).

### Exclamation points ("!")

Use exclamation marks only positively, not negatively. Use no more than one exclamation mark per page or window.

---

## Numerical formatting

---

### Currency and phone numbers

- Currency: `$1,000,000.00`
- Phone numbers: `+1 (212) 123 4567`

### Dates and times

| Type | When and how to use | Example |
|---|---|---|
| Time | Within the current day, use uppercase AM or PM without periods | 2:00 PM |
| 24-hour clock | Display the time without AM/PM | 14:00 |
| Date | Show the date with the year. If it's within the current calendar year, don't show the year. | January 14 / Jan 3, 2012 / 10/23/2022 |
| Timestamp | Display an exact time | 2:36:17 PM PST |
| Approximate time | Round down to the largest and most recent date or time | In 5 minutes / 3 days ago |

---

## Prepositions

Prepositions indicate relationships between different elements, actions, or concepts. Proper use maintains clarity and precision; misuse leads to confusion.

---

### Conciseness — avoid overuse

Minimize unnecessary prepositions. Omit them when they don't add meaning.

| Do | Don't |
|---|---|
| Manage notification settings. | The settings for managing notifications on your profile. |
| Contact Support | Contact to Support |
### Accuracy and clarity

Use prepositions that clearly express the relationship between actions, objects, or concepts.

| Do | Don't |
|---|---|
| Upload to the server | Upload on the server |
| Details on how to configure settings | Information about settings |
### Keep prepositional phrases short

Avoid long prepositional chains — break them up for clarity.

| Do | Don't |
|---|---|
| Click the link in your email to view your order details. | Click on the link in the email for information about your order. |
### Consistency

Standardize common prepositional phrases and use them consistently throughout the product.

| Do | Don't |
|---|---|
| Save the changes to your profile. | Save the changes on your profile. |
| Drag the file into the folder | Drag the file to the folder |
| Tap the icon | Tap on the icon |

---

## Acronyms

Spell out an acronym the first time it's mentioned. On subsequent references, use the abbreviation. If the abbreviation isn't clearly related to the full version, specify it in parentheses after the spelled-out version in the first instance.

---

Fully capitalize all letters in abbreviations:

- PDF
- AM/PM
- FAQ
- HTML
- OK (not Ok or Okay)
- HCL

If there's a chance that an abbreviation might not be known to the target audience, spell it out in full the first time you use it. However, don't spell out commonly known abbreviations. If the abbreviation or acronym is well-known to the average client (for example, CIC or CDE), use it on the first reference without spelling it out.

---

## Plurals

Make sure items are correctly used as plural or singular nouns as appropriate.

Do not use "(s)" or "/s" after a noun to make it plural. If you must indicate both forms, use "one or more."

---

## Abbreviations and articles

---

### Abbreviations

Do not use "i.e." or "e.g." in UI copy. Avoid using a slash between two words to mean "and/or" — use the word "or" instead.

| Do | Don't |
|---|---|
| You can select green, blue, or both. | You can select green/blue. |
### Articles

Don't speak like a robot — use "a," "an," and "the" articles.

| Do | Don't |
|---|---|
| Use the default JRE to run a shell instance. | Use default JRE to run shell instance. |

---

## Empty and system states

System states communicate the current condition of the platform or a specific view. Clear, direct copy helps users understand what happened and what to do next.

---

### Empty state

Empty states appear when users have not yet created items, or when filters return no results. Clear copy and a direct CTA reduce friction and encourage engagement.

#### When to use

- When users have not yet created or uploaded items.
- When [filters](/components/form-input-selection/search-filters/) result in no visible results.
- To encourage engagement with a clear next action.

#### Style

- Use a short, instructive headline (noun phrase or imperative verb).
- Follow with one concise sentence that explains what the user can do.
- Provide one primary action (for example, **Create dataset**).
- Do not use `No results found` as a standalone message without guidance.

#### Do / Don't

| Do | Don't |
|---|---|
| No items found / Add your first dataset to start exploring. | No results. |
| Nothing here yet / Create a connection to get started. | There are no items to display at this time. |
#### Example

| Element | Example text |
|---|---|
| Title | No items found |
| Body | Add your first dataset to start exploring. |
| CTA | Create dataset |

---

### Error state

Error states communicate that something failed or a resource could not be loaded. Copy must be specific, non-blaming, and actionable.

#### When to use

- When something fails or a resource cannot be loaded.
- When a user action fails to complete.

#### Style

- Be specific about what went wrong where possible.
- Offer a resolution step or next action.
- Do not use technical error codes as the primary message.
- Do not blame the user.

#### Example

| Element | Example text |
|---|---|
| Title | Something went wrong |
| Body | There was an error creating your item. Try again or contact support if the problem continues. |
| Primary CTA | Try again |

---

### Maintenance state

Maintenance states inform users that part of the platform is temporarily unavailable due to planned or unplanned work.

#### Style

- Explain what is affected and for how long.
- Provide an estimated time to resolution when available.
- Include a single action if there is something the user can do (for example, **Refresh**).

#### Example

| Element | Example text |
|---|---|
| Title | Scheduled maintenance in progress |
| Body | Reports may be unavailable until 12:00 PM EST. |
| CTA | Refresh |

---

### Success state

Success states confirm that a user action completed. They often follow an action that previously triggered an empty state.

#### Style

- Confirm what was completed, not just that it succeeded.
- Keep copy brief. One line is usually sufficient.
- Offer a logical next action.

#### Example

| Element | Example text |
|---|---|
| Title | Items imported |
| Body | Your datasets are ready to explore. |
| Primary CTA | Open catalog |

---

## Forms

Forms collect or update user data. Consistent structure, clear labels, and helpful guidance reduce friction and prevent errors.

---

### When to use

- To collect user input that affects data, configuration, or permissions.
- To edit or update existing records or entities.
- To guide users through multi-step flows where input drives behavior.
- To allow users to provide comments and suggestions, or to confirm, approve, or reject requests that require context.

### Types of forms

| Type | Usage | Examples |
|---|---|---|
| Single page or simple form | Data entry for simple workflows | Editing a dataset name or description |
| Stepper or multi-page form | Task-based workflows | Creating a data connection or access request |
| Modal form | Short, focused tasks that require user confirmation | Adding a note or setting permissions |

---

### General form guidelines

#### How to use

- Be concise and directive: each label or helper text should clearly describe the required action.
- Use sentence case for labels and titles.

| Do | Don't |
|---|---|
| Group name | Group Name |
- Clarify optional vs. required fields: mark required fields consistently using the asterisk (*) symbol or text label.
- Avoid redundancy: if a section title already establishes context, field labels can be shorter.
- Provide context when needed: helper text should explain the "why," never just restate the label.
- Error text should guide correction.

| Do | Don't |
|---|---|
| Enter a valid date | Invalid input |
- Success or confirmation text should be brief, reassuring, and specific. For example, `The policy was successfully created`.
- Use progressive disclosure for field entry assistance: Label → Tooltip → Descriptive text → Link to docs.

#### Structure

- Group related fields together under sections.
- Always place the primary CTA at the bottom right for consistency.
- Avoid multi-column layouts when possible - single column is easier to read. Exceptions such as separate fields for first and last names are acceptable.

#### Behavior

- Labels should be visible even when the field is in focus.
- Include placeholder text only when it provides value - never to just repeat the label.
- The primary CTA should be disabled until all required fields are filled.
- Validate fields inline and provide red error text below the field. See [validation messages](validation-messages) for error text guidelines.

---

### Input labels and helper text

#### Style

- Labels describe the purpose of the field. They are always visible.
- Helper text provides brief instruction or clarification below the field. Use it sparingly.
- Placeholder text is a hint only - never a substitute for a label. It disappears when the user starts typing.

#### Do / Don't

| Do | Don't |
|---|---|
| Label: Connection name / Helper: Use a unique name to identify this connection. | Placeholder: Enter connection name (no visible label) |
| Helper: Must be 8–32 characters. | Helper: Please enter a valid password. |
---

### Dropdown

#### When to use

- For lists of 5 to 20 options.
- When the full list does not need to be visible at all times.

#### Style

- Label the dropdown clearly. The label should describe the category of options, not the action.
- Close after selection.
- Keep option phrasing consistent within the same dropdown.
- Use sentence case for all options.

---

### Calendar

The calendar component is used for any interaction involving date ranges, filtering, or scheduling.

#### When to use

For any interaction involving date ranges, filtering, or scheduling.

#### Style

- Use labels like `From` and `To`, or `Start date` and `End date` for range fields. Do not leave any fields unlabeled.
- Display date formats clearly (MM/DD/YYYY or regional format) with placeholders or hints where appropriate.
- Do not pre-fill dates for users.

#### Behavior

- Support both typing and calendar picking.
- Auto-close the calendar when the selection is complete.
- Highlight today, weekends, and blocked dates visually when appropriate.
- Visually display any selected range in the calendar.

---

### Toggle

#### Style

- Label the toggle next to or above the control. For example, **Enable alerts**.
- Show the label for the state that is currently active. For example, show `Off` when off, `On` when on - but not both at the same time.

#### Behavior

- The action should happen on toggle with no confirmation step.
- Left = off, right = on.
- Should update instantly unless a delay is unavoidable - show a loading indicator if delayed.
- Do not use toggles for destructive or irreversible actions.

#### Toggle vs Checkbox vs Radio button

**Use a toggle when:**
- The action takes effect immediately.
- It represents a system state (for example, ON/OFF, enabled/disabled).
- It is a binary setting that persists (for example, dark mode, notifications).

**Use a [checkbox](/components/form-input-selection/checkbox-with-label/) when:**
- The user is selecting one or more items.
- The action does not take effect immediately (typically part of a form or group submission).
- It is a yes/no decision that is reviewed later. For example, **Agree to terms and conditions** or **Subscribe to newsletter**.

---

### Radio button

#### When to use

- When the user must select exactly one option from a short visible list (typically two to six options).
- When all choices should be visible up front rather than hidden in a dropdown.

#### Style

- Use short, descriptive labels that clearly state each option.
- Write labels as direct answers to the group's prompt or question. For example, **Yes / No** instead of `Select yes if you agree`.
- Ensure the group label or question is always visible next to the options.
- Avoid jargon or abbreviations.
- Keep labels parallel in structure - all nouns, or all verb phrases.

---

### Radio button card format

Use card-format radio buttons instead of traditional radio buttons when each option needs rich context such as a title, description, image, metadata, or tags, and the selection should feel like a visual choice rather than a text label.

#### When to use

- Primary decision point: when the consequences of the choice are important, or they drive a main workflow or journey.
- Examples: pricing tiers, template selections (for example, use cases), or layout choices.

#### Behavior

- Indicate selected state visually (`Selected` highlight border, and so on).
- Click anywhere on the tile to toggle selection.
- For multi-select: use checkbox behavior. For single-select: use radio group behavior.
- Maintain selection across steps if part of a multi-step process.
- Title: short, descriptive, and consistent across tiles.
- Supporting text: use only in the large variant.

---

## Grid and spacing

Grid and spacing guidelines govern the visual rhythm of the interface. Consistent spatial decisions make the UI easier to scan and reduce cognitive load.

---

### Content implications

- Short labels and values work best in tight grid contexts. Avoid wrapping text in narrow columns.
- When content must appear in a constrained space, abbreviate predictably or truncate with a tooltip.
- Do not force content into a fixed width by using non-breaking spaces or artificial line breaks.

### Density considerations

- Default density is appropriate for most catalog views.
- Compact density is appropriate for power users working with large datasets where row count matters.
- Do not vary density within the same table or list view.

---

## Icons

Icons support communication by providing visual cues alongside or instead of text. They should reinforce meaning, not replace it, unless paired with a tooltip or accessible label.

---

### When to use

- To supplement a text label and help users scan faster.
- For icon-only controls (such as toolbar buttons) that have a visible tooltip or aria-label.
- Do not use an icon as the only affordance for a critical action - always pair with a text label or tooltip.

### Style

- Use icons from the approved Actian icon set only.
- Do not add decorative icons that have no functional meaning.
- Icon labels (tooltips or aria-labels) use sentence case and follow the same verb/noun conventions as button labels.

### Accessibility

- Every icon-only control must have an accessible name via aria-label or a visually hidden text label.
- Decorative icons must be marked `aria-hidden="true"` so screen readers skip them.
- Do not rely on color alone to convey the meaning of an icon.

---

## Lineage-specific UI

Lineage views display the origin, transformation history, and downstream dependencies of data assets. The UI uses graph-based visualizations with nodes and edges. Copy in this context must be precise and unambiguous to support data governance workflows.

---

### When to use

- On dataset and column detail pages where traceability is relevant.
- In audit and governance workflows where users need to trace data origin or impact.

### Node labels

- Use the exact asset name as the node label - do not paraphrase or abbreviate.
- Include the asset type as a secondary label below the name. For example, `Orders` with `Table` below it.
- Use sentence case for all labels.

### Edge and relationship labels

- Describe the relationship with a short verb phrase. For example, `Reads from`, `Writes to`, `Transforms`.
- Avoid technical jargon that non-engineer users will not understand.

### Terminology

| Term | Definition |
|---|---|
| Upstream | Assets that provide data to the selected asset |
| Downstream | Assets that consume data from the selected asset |
| Source | The originating system or dataset |
| Transformation | A processing step that modifies or aggregates data |
| Impact | The downstream effect of a change to this asset |

---

## Loading

---

### Loading indicator

#### When to use

During transitions, page loads, or background processes.

#### Style

- Use a loading message only when the wait is likely to exceed three seconds.
- Keep loading messages brief and present-tense. For example, `Loading datasets...`
- Do not use `Please wait`.

---

### Progress indicator

#### When to use

- For multi-step flows such as wizards or onboarding sequences.
- For file uploads or long-running background processes.

#### Style

- Label each step in a stepper with a short noun or verb phrase.
- Show current step and total step count. For example, `Step 2 of 4`.
- For upload progress, show percentage or file size transferred.

---

## Notifications and messaging

---

### Notification

Notifications inform users of updates, background task completions, or events that require their attention. They appear in the notification panel or dropdown.

#### When to use

- To inform users of updates, background task completions, or events that require their attention.

#### Style

- Use direct, concise language. One to two sentences.
- Include a timestamp.
- Include a link or action if the user must do something in response.
- Do not use generic text like `You have a new notification`.

---

### Notification toast

Toasts confirm that a background action completed, or surface non-critical errors and warnings that do not block the user.

#### When to use

- To confirm that a background action completed.
- To surface non-critical errors or warnings that do not block the user.
- Do not use toasts for actions that require user input.
- For routine confirmations that need persistence, use an [alert / banner](/components/feedback/alert-banner/) instead.

#### Style

- Keep to one short sentence.
- Include an undo action where relevant.

#### Examples

| Scenario | Toast text |
|---|---|
| Dataset deleted | Dataset deleted. Undo |
| Export complete | Export ready. Download |
| Connection failed | Connection failed. Try again |

---

### Tooltip

Tooltips provide short contextual help on hover or focus. They are best for icon-only controls that need a label, or for brief supplementary information that does not need to be persistently visible.

#### When to use

- To provide short contextual help on hover or focus.
- For icon-only controls that require a label.
- Do not use tooltips for critical information — users should not be required to hover to understand the UI.

#### Style

- Limit to a few words or one concise sentence.
- Do not repeat the label of the element being described.
- For multi-sentence explanations, use a [popover](/components/overlays/popover/) or inline help text instead.

---

## Object preview panels

Object preview panels display a summary of an asset's key attributes without requiring full navigation to the detail page. They appear as side panels or overlays and are used to support quick inspection workflows.

---

### When to use

- When a user hovers over or clicks an item in a list or search result and wants a quick view of its properties.
- To reduce context switching during browsing or review tasks.

### Style

- Panel title is the asset name. Use the exact name - do not rephrase.
- Use short attribute labels (one to two words) followed by their values.
- Group related attributes under a subheading where the panel is long.
- Include a **View full details** link at the bottom to navigate to the full detail page.

### Attribute label examples

| Use | Avoid |
|---|---|
| Owner | Assigned owner |
| Last modified | Date of last modification |
| Type | Object type |
| Description | Asset description |

---

## Onboarding

Onboarding helps users understand the platform and reach their first success quickly. Copy should be encouraging without being patronizing.

---

### When to use

- On first login or when a user accesses a new product area for the first time.
- As part of [wizard](wizards) flows for complex setup tasks.

### Style

- Lead with what the user can do, not what the product does.
- Keep each step focused on one task.
- Use action-oriented **CTAs**. For example, **Set up your first connection**.
- Do not use marketing language in onboarding flows.

### Wizard step titles

- Step titles are short imperative phrases. For example, `Choose a data source`, `Configure access`.
- Do not number the step in the title text - the stepper component handles that.

---

## Related content panels

Related content panels surface assets or resources connected to the currently viewed item. They help users discover relevant datasets, reports, lineage connections, or documentation without leaving their current context.

---

### When to use

- On asset detail pages to surface downstream or upstream dependencies.
- To show related documentation, reports, or catalog entries.
- Do not use related content panels for primary navigation - they are supplementary.

### Style

- Panel heading describes the relationship type. For example, `Related datasets`, `Used in reports`.
- Each item in the panel shows the asset name as a link, plus one or two metadata attributes (type, owner, or last modified).
- If the panel is empty, show a brief empty state message. For example, `No related datasets found`.

### Do / Don't

| Do | Don't |
|---|---|
| Related datasets | Other items |
| No related datasets found. | (empty panel with no message) |
| Used in 3 reports | Reports: 3 |

---

## Uploads

Upload components allow users to add files to the platform. They appear in dataset import flows, connection setup, and file attachment contexts.

---

### When to use

When users need to import data files, certificates, configuration files, or attachments.

### Style

- Drop zone label: use an action phrase plus the accepted file types. For example, "Drag and drop a CSV file, or browse."
- Browse link text: **Browse** or **Choose file** - not **Click here**.
- File type restrictions: list the accepted formats explicitly. For example, "Accepts `.csv`, `.json`, and `.xlsx` files."
- File size limit: state the limit in plain language. For example, "Maximum file size: `50 MB`".

### Progress and status

- During upload: show filename, progress bar, and percentage.
- On success: show filename with a success indicator. For example, "`data_export.csv` - Uploaded."
- On error: show filename with a specific error. For example, "`data_export.csv` - File exceeds the 50 MB size limit."

### Do / Don't

| Do | Don't |
|---|---|
| Drag and drop a CSV file, or browse. | Click here to upload your file. |
| Accepts .csv, .json, and .xlsx files. | Only certain file types are supported. |
| data.csv - File exceeds the 50 MB size limit. | Upload failed. |

---

## Validation messages

Validation messages appear inline with [form](forms) fields to help users correct input errors. They are the primary mechanism for communicating what went wrong and how to fix it.

---

### When to use

- On field blur (when the user leaves a field), not on every keystroke.
- On form submission when required fields are empty or invalid.
- Do not show validation errors before the user has interacted with a field.

### Style

- Be specific: say what is wrong and how to fix it.
- Use plain language - do not expose technical error codes or internal validation rule names.
- Keep messages to one sentence.
- Do not use "Invalid" as a standalone message - explain why it is invalid.
- Do not blame the user. Use neutral, factual language.
- Do not use "Please" - omit it.

### Do / Don't

| Do | Don't |
|---|---|
| Enter a valid email address. | Invalid email. |
| Connection name is required. | Please fill out this field. |
| Password must be 8–32 characters. | Password does not meet requirements. |
| This name is already in use. Choose a different name. | Duplicate entry error. |
| Select at least one data domain. | You must make a selection. |

---

## Wizards

Wizards are guided multi-step flows that walk users through complex setup or configuration tasks. They combine steppers, forms, and confirmation screens into a linear sequence with clear progression.

---

### When to use

- For complex setup tasks that cannot be completed on a single form - for example, creating a connection, configuring a pipeline, or onboarding a new dataset.
- When the steps have a natural sequence and later steps depend on earlier choices.
- Do not use a wizard for simple tasks that can be completed in a single form or modal.

### Step titles

- Short imperative verb phrases. For example, `Choose a connector`, `Set connection details`, `Test and save`.
- Parallel structure across all steps.
- Do not repeat the wizard title in each step title.

### In-step content

- Use a short paragraph at the top of each step to explain what the user is about to do and why.
- Keep explanatory text to two sentences maximum.
- Use inline help (popovers or helper text) for field-level guidance rather than long step-level explanations.

### Confirmation and summary step

- The final step before submission should present a summary of the user's choices.
- Label the summary step `Review` or `Review and create`.
- Use the same attribute labels as the preceding form fields - do not rephrase.
- Show an edit link next to each section so the user can go back and change specific settings.

### Navigation buttons

Follow the [stepper button terminology guidelines](/components/navigation/stepper/). Use **Back**, **Next**, and the appropriate object-specific verb for the final step (for example, **Create connection**).

### Do / Don't

| Do | Don't |
|---|---|
| Choose a connector | Connector selection step |
| Review and create | Confirmation |
| Create connection | Finish / Submit / Done |
| Connect to your data source. This will allow the platform to read and write data on your behalf. | Please complete all required fields in this step before proceeding. |