Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

docs(style-guide): add rules for list lead-ins and UI instruction order (#51632)

Alexis Aguilaradd223d7b31c
diff --git a/apps/docs/style-guide/02-elements.md b/apps/docs/style-guide/02-elements.md
index ea9085ba8f5..28e7b5868fe 100644
--- a/apps/docs/style-guide/02-elements.md
+++ b/apps/docs/style-guide/02-elements.md
@@ -146,6 +146,17 @@ Use an ordered list for steps taken in sequence, and an unordered list when orde
doesn't matter. Use Arabic numerals (`1`, `2`, `3`) for ordered lists and dashes (`-`)
for unordered lists.
+#### Point forward to a list with _the following_
+
+When a sentence refers to a list but another sentence sits between it and the list, use
+_the following_. _These_ reads as pointing back at something already on the page, so the
+reader can't tell which items it means. When the referring sentence is directly before
+the list, either word works.
+
+- **Recommended**: `To open Supabase Studio, start from either of the following tabs. Each one opens a different page in Supabase:`
+- **Recommended**: `Start from either of these tabs:`
+- **Not recommended**: `To open Supabase Studio, start from either of these tabs. Each one opens a different page in Supabase:`
+
#### Prefer a paragraph to a single-item list
A list of one signals content that was meant to grow and didn't. Exceptions: layout
@@ -185,8 +196,12 @@ to need one.
The format makes that expectation explicit.
Write sequential actions as an ordered list. **Begin each step with an imperative verb,
-and include one action or a closely related set of actions per step.** Give the reader
-enough context to know where to act.
+or with a short location phrase followed by one, and include one action or a closely
+related set of actions per step.** When a step says where to act, put the location
+first. Give the reader enough context to know where to act.
+
+- **Recommended**: `Next to Supabase, click **Manage**, then click **Open in Supabase**.`
+- **Not recommended**: `Click **Manage** next to Supabase, then click **Open in Supabase**.`
For how many steps to present at once and when to split a procedure into phases, see
chunking in [`03-page-structure.md`](./03-page-structure.md).