Content guidelines

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 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 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 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 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 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 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 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. 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.