---
title: Writing for product
description: Guidelines for in-app copy, buttons, error messages, and UI text
---

Source: https://clickhouse.design/brand/guidelines/writing-for-product

# Writing for product

Product copy helps users move fast. Every word should serve a purpose. See [Voice and tone](/brand/guidelines/voice-and-tone) for the foundation.

## General principles

1. **Be direct.** Tell users what to do, not what they can do.
2. **Be specific.** Name the exact thing being affected.
3. **Be brief.** Users scan interfaces, they don't read them.

## Language and spelling 🇺🇲

Use US English in all product copy — interface labels, error messages, empty states,
tooltips, and any text that ships in the product.

- color, not colour
- analyze, not analyse
- center, not centre
- dialog, not dialogue (in UI contexts)

This applies to all product surfaces regardless of the author's own English preference.

## Buttons and CTAs

Buttons should use action verbs that describe exactly what will happen. Avoid generic labels.

**✅ Do:**

- Create service
- Delete query
- Export as CSV
- Save changes

**❌ Don't:**

- OK
- Confirm
- Submit
- Yes

For destructive actions, be explicit about what's being destroyed:

**✅ Do:**
Delete "my-analytics-service"

**❌ Don't:**
Delete service

## Form labels and placeholders

Labels should clearly identify what information is needed. Placeholders should show format or provide an example—never use them as labels.

**✅ Do:**

- Label: "Email address"
- Placeholder: "[you@company.com](mailto:you@company.com)"

**❌ Don't:**

- Label: (none)
- Placeholder: "Email address" (using placeholder as label)

Mark required fields clearly. Don't make users guess.

## Error messages

Errors should tell users what happened and what to do. Be direct. Never blame the user. Skip the cutesy "oops."

### Structure

1. **What happened** (briefly)
2. **What to do next** (if actionable)

**✅ Do:**
Connection timed out. Check your network settings and try again.

**❌ Don't:**
Error: ETIMEDOUT

**❌ Don't:**
You entered an invalid value.

### What to avoid in errors

- **Blame**: "You entered..." → "The value..."
- **Cutesy language**: "Oops!" "Uh oh!" "Whoops!"
- **Vague apologies**: "Something went wrong."
- **Raw error codes**: Show them, but explain them

**✅ Do:**
Invalid API key. Generate a new key in Settings → API Keys.

**❌ Don't:**
Oops! We couldn't authenticate your request. Please try again later.

## Empty states

Empty states are opportunities to guide users. Tell them why it's empty and what action to take.

Note that an empty state and a blocked state are not the same thing — "no results" and "you don't have access" need different messages. See [Availability states](/click-ui/availability) for which to use.

**✅ Do:**
No queries yet. Run your first query to see results here.

**❌ Don't:**
No data.

## Tooltips and hints

Keep tooltips short—one sentence when possible. They should add context, not repeat what's already visible.

For tooltips that explain why a control is unavailable, see [Availability states](/click-ui/availability) — those have their own copy patterns and an accessibility requirement.

**✅ Do:**
Tooltip for "Memory limit": Maximum memory this query can use before being terminated.

**❌ Don't:**
Tooltip for "Memory limit": This is the memory limit setting.

## Confirmation dialogs

Confirmation dialogs prevent users from making irreversible or dangerous actions. For detailed guidance, see the [Confirmation dialogs](/brand/guidelines/confirmation-dialogs) page.

### Quick tips

- **Title**: Phrase as a question including the action and target
- **Actions**: Use specific verbs, not "OK" or "Confirm"
- **Description**: Explain consequences briefly (1-2 sentences)

**✅ Do:**

- Title: Delete "production-db"?
- Description: This will permanently delete the service and all its data.
- Actions: Cancel / Delete service

**❌ Don't:**

- Title: Are you sure?
- Description: This action cannot be undone.
- Actions: Cancel / OK

## Loading and progress states

Tell users what's happening during longer operations.

**✅ Do:**

- Creating service...
- Importing 1,234 rows...
- Connecting to database...

**❌ Don't:**

- Loading...
- Please wait...
- Processing...

## Success messages

Confirm what happened. Be specific but brief.

**✅ Do:**

- Service created successfully
- Query saved to "My Queries"
- API key copied to clipboard

**❌ Don't:**

- Success!
- Done.
- Operation completed successfully.

## Formatting in UI

Use **bold** for UI element names when writing instructions:

**✅ Do:**
Click the **Start** button.

**❌ Don't:**
Click the Start button.