dima/supabase
1
0 Fork 0
mirror of https://github.com/supabase/supabase.git synced 2026-10-06 18:05:11 +03:00
Code Issues Packages Projects Releases Wiki Activity
Files
chore/function-recent-errors
supabase/apps/design-system/content/docs/copywriting.mdx
T
Danny White 24be387cdb docs: use sign in terminology across guides and style guides (#49877) 
## What kind of change does this PR introduce?

Docs update. Aligns documentation and style guides with the **Sign in /
Sign out / Sign up** platform standard.

Closes DOCS-1328. Related to
[#49874](https://github.com/supabase/supabase/pull/49874).

## What is the current behavior?

Docs style guides prefer _login_ / _log in_. Guide prose uses mixed
login and sign in wording.

## What is the new behavior?

- [WORD_LIST.md](apps/docs/WORD_LIST.md) and
[copywriting.mdx](apps/design-system/content/docs/copywriting.mdx)
document the sign in standard
- Design-system auth examples updated
- Guide prose and API reference spec descriptions updated

### Terminology

**Standard:** Use _sign in_, _sign out_, and _sign up_ as verbs. Use
_sign-in_, _sign-out_, and _sign-up_ as nouns and adjectives. Match
Studio UI labels (**Sign in**, **Sign out**, **Sign up**).

**Preserved intentionally:**

| Category | Keep as-is | Example |
| -------- | ---------- | ------- |
| Feature name | social login | `/social-login`, `features.mdx` heading,
OAuth provider section |
| URL slugs | `login` in paths | `/phone-login`, `/login-flows`,
`choosing-login-flow` |
| CLI | `supabase login` / `supabase logout` | Reference ids
`supabase-login` / `supabase-logout`; executable commands unchanged |
| SDK methods | `logout()` | Kotlin/Swift method names in API reference
titles and examples |
| Third-party UI | Provider product labels | Facebook Login, Kakao
Login, portal **Login** buttons |
| Postgres | Database terminology | login privileges, login credentials,
login via role |
| Audit/logging | Log prose | "Generates the following **log** in the
Postgres Logs" |
| Code and routes | Paths and filenames | `app/login/`, `Login.tsx`,
`demos/android-login` |
| External URLs | Third-party login pages | `dash.cloudflare.com/login`,
`console.neon.tech/login`, `vercel.com/login` |
| API identifiers | Event and field names | Audit actions
`login`/`logout`, `should_logout_user` |

## To test

- Run `pnpm lint:mdx` in `apps/docs`
- Spot-check `features.mdx`, `social-login.mdx`, and a provider guide
(e.g. Facebook, Kakao)

<!-- This is an auto-generated comment: release notes by coderabbit.ai
-->
## Summary by CodeRabbit

* **Documentation**
* Standardized authentication terminology across guides, reference
material, CLI documentation, and copywriting guidance using “sign in,”
“sign out,” and “sign up.”
* Updated authentication instructions, headings, link text, examples,
and SSO guidance for clearer, more consistent wording.
* Corrected related grammar, spelling, hyphenation, and documentation
links while preserving established product names and implementation
commands.
* **Style**
  * Refined code examples with consistent import ordering and spacing.
* **Examples**
* Updated authentication button and menu labels to “Sign in” and “Sign
out.”
<!-- end of auto-generated comment: release notes by coderabbit.ai -->
2026-09-04 09:10:25 +10:00

258 lines
12 KiB
Plaintext
Raw Permalink Blame History

---
title: Copywriting
description: A concise guide for writing UI copy in Supabase.
---
Write UI copy that helps developers complete tasks quickly. Be direct, action-oriented, and respectful of developer time.
## Voice and tone
Supabase UI copy is:
- **Direct**: Say what something does, not what it "enables" you to do.
- **Action-oriented**: Focus on what happens, not what we built.
- **Technical without jargon**: Use precise terms but explain when necessary.
- **Pragmatic**: Acknowledge tradeoffs and limitations when relevant.
## Buttons and actions
### Use verbs, not nouns
<ComponentPreview name="copy-button-verbs" hideCode />
### Be specific about outcomes
| Bad | Good |
| ----------- | ---------------- |
| "Remove" | "Delete project" |
| "Change" | "Revoke access" |
| "Configure" | "Enable RLS" |
### Match button text to the action
| Action | Bad | Good |
| ----------------- | --------- | -------------- |
| Primary action: | "Submit" | "Create table" |
| Secondary action: | "Go back" | "Cancel" |
## Form labels and descriptions
### Labels describe the field, not the feature
<ComponentPreview name="copy-form-labels" hideCode />
| Action | Bad | Good |
| ------------ | ------------------------------------------------------------------------------------------------ | ---------------------------------------- |
| Label: | "Name your table" | "Table name" |
| Description: | "This field allows you to specify a name for your table using letters, numbers, and underscores" | "Letters, numbers, and underscores only" |
### Descriptions explain constraints, not concepts
| Bad | Good |
| --------------------------------------------------------------- | ---------------------------------- |
| "This ensures your table name is unique" | "Must be unique within the schema" |
| "You can enter up to 255 characters here" | "Maximum 255 characters" |
| "This field is required when using Row Level Security policies" | "Required for RLS policies" |
### Use present tense
| Bad | Good |
| -------------------------------------- | --------------------------------- |
| "Will store connection pool settings" | "Stores connection pool settings" |
| "This will limit query execution time" | "Limits query execution time" |
## Error messages
### State what went wrong, then how to fix it
<ComponentPreview name="copy-error-messages" hideCode />
| Bad | Good |
| ----------------------------------------- | ----------------------------------------------------- |
| "An error occurred" | "Table name already exists. Choose a different name." |
| "Something went wrong. Please try again." | "Invalid API key. Check your project settings." |
### Be specific about the problem
| Bad | Good |
| ------------------ | --------------------------------------------- |
| "Invalid input" | "Password must be at least 8 characters" |
| "Connection error" | "Connection failed: timeout after 30 seconds" |
### Avoid blame or apology
| Bad | Good |
| ---------------------------- | ------------------------------------------------ |
| "Sorry, we couldn't connect" | "Unable to connect to database" |
| "Oops! Something went wrong" | "Table creation failed: column name is reserved" |
## Success messages
### Confirm what happened
<ComponentPreview name="copy-success-messages" hideCode />
| Bad | Good |
| --------------------- | ---------------------------- |
| "Success!" | "Table created successfully" |
| "Done" | "API key revoked" |
| "Operation completed" | "Changes saved" |
### Keep it brief
| Bad | Good |
| ------------------------------------------------------------- | ------------------- |
| "Your backup has been successfully restored to your database" | "Backup restored" |
| "The migration has been applied successfully to your project" | "Migration applied" |
## Tooltips and help text
### Explain why, not what
<ComponentPreview name="copy-tooltips" hideCode />
| Bad | Good |
| ------------------------- | ------------------------------------------------ |
| "This is a toggle switch" | "Enables real-time subscriptions for this table" |
| "Click to delete" | "Prevents accidental deletions" |
### One sentence maximum
| Bad | Good |
| ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ |
| "Row Level Security restricts access based on user policies. When enabled, users can only access rows that match their policy conditions." | "Restricts access based on user policies" |
| "This setting controls the maximum number of concurrent connections that can be established to your database at any given time." | "Maximum number of concurrent connections" |
## Navigation and headings
### Use title case for page titles and global navigation
Use title case for page names in the main nav and document titles (e.g. "Database Settings", "Project Settings"). This distinguishes the page as a destination from section labels and in-page headings, which use sentence case.
### Use declarative page descriptions
Use a fragment with no trailing period, and prefer declarative over instructional. Describe what the page covers, not what the user should do.
| Good | Bad |
| ---------------------------------------------------------- | ---------------------------------------------------------------------- |
| "General configuration, domains, ownership, and lifecycle" | "Configure general options, domains, transfers, and project lifecycle" |
### Use sentence case for section labels and headings
| Bad | Good |
| ----------------------- | ----------------------- |
| "Set Up Authentication" | "Set up authentication" |
| "Database Settings" | "Database settings" |
| "Create New Project" | "Create new project" |
### Headings describe the page, not the feature
| Bad | Good |
| ------------------------------ | -------------------- |
| "Manage your API keys" | "API keys" |
| "Configure connection pooling" | "Connection pooling" |
| "Edit your tables" | "Table editor" |
## Empty states
### Explain what's missing, then how to add it
<ComponentPreview name="copy-empty-states" hideCode />
| Bad | Good |
| --------------------------------- | ---------------------------------------------------------- |
| "You don't have any tables" | "No tables yet. Create your first table to get started." |
| "There are no API keys available" | "No API keys. Generate a key to connect your application." |
### Include the action
| Bad | Good |
| ------------------------ | ------------------------------------------------- |
| "No buckets found" | "No buckets yet. [Create bucket] button" |
| "No functions available" | "No functions deployed. [Deploy function] button" |
## Loading states
### Describe what's happening
<ComponentPreview name="copy-loading-states" hideCode />
| Bad | Good |
| ---------------- | ----------------------- |
| "Please wait..." | "Creating table..." |
| "Loading..." | "Loading schema..." |
| "Processing..." | "Applying migration..." |
### Match the action verb
| Action | Bad | Good |
| --------------------------- | ---------------- | --------------------- |
| "Delete project" → Loading: | "Processing..." | "Deleting project..." |
| "Save changes" → Loading: | "Please wait..." | "Saving changes..." |
## Confirmations and dialogs
### State consequences clearly
<ComponentPreview name="copy-confirmations" hideCode />
| Bad | Good |
| ------------------------------------- | ----------------------------------------------------------------------------------------- |
| "Are you sure?" | "Delete this project? This action cannot be undone and will permanently delete all data." |
| "This action is permanent. Continue?" | "Revoke this API key? Applications using this key will stop working immediately." |
### Use active voice
| Bad | Good |
| ------------------------------------------------------------ | --------------------------------------------------- |
| "All data will be removed if this project is deleted" | "Deleting this project will remove all data" |
| "Existing connections will be broken if this key is revoked" | "Revoking this key will break existing connections" |
## Words to avoid
### Marketing language
| Bad | Good |
| ---------------------------- | -------------------- |
| "Easily create tables" | "Create tables" |
| "Simply configure settings" | "Configure settings" |
| "Powerful database features" | "Database features" |
### Vague verbs
| Bad | Good |
| ---------------- | -------------------------------- |
| "Manage tables" | "Create, edit, or delete tables" |
| "Handle errors" | "View and resolve errors" |
| "Work with data" | "Query and update data" |
## Authentication terminology
Use **Sign in**, **Sign out**, and **Sign up** for button and menu labels. Keep `login`, `logout`, and `logOut` in code, routes, URL slugs, and CLI commands only when they match existing implementation names.
## Capitalization
- **Sentence case** for all UI text (buttons, labels, section headings)
- **Title case** for page names in navigation
- **Product names:** Database, Auth, Storage, Edge Functions, Realtime, Vector
- **Postgres**, not PostgreSQL
- **Supabase** (capitalize except in code)
## Formatting
- **Bold for emphasis** only when necessary
- **Inline code** for technical terms: `RLS`, `API key`, `supabase init`
- **No italics** for emphasis
- **No exclamation marks** unless critical (e.g., destructive actions)
## Quick checklist
Before publishing UI copy, ask:
- Does it use an action verb?
- Is it specific about what happens?
- Can a developer complete the task without reading more?
- Does it avoid marketing language?
- Is it in sentence case?
- Is it one sentence or less (for labels, buttons, tooltips)?
Reference in new issue View Git Blame Copy Permalink