diff --git a/src/content/docs/terminal/windows/tabs.mdx b/src/content/docs/terminal/windows/tabs.mdx
index be846837..6ba9712c 100644
--- a/src/content/docs/terminal/windows/tabs.mdx
+++ b/src/content/docs/terminal/windows/tabs.mdx
@@ -88,6 +88,29 @@ See our [Appearance > Tabs Behavior](/terminal/appearance/tabs-behavior/) docs f
 
 <VideoEmbed url="https://www.loom.com/share/84d15cc7eb5a4a668bb86be9e827f261?hide_owner=true&hide_share=true&hide_title=true&hideEmbedTopBar=true" title="Tabs Demo" />
 
+## Tab colors
+
+Color-code tabs to tell projects, environments, or long-running sessions apart at a glance. Colors come from your active [theme](/terminal/appearance/themes/), so they stay readable whichever theme you use.
+
+### Set a tab's color
+
+1. Right-click the tab you want to color.
+2. Click a color in the color row.
+
+To remove a color, right-click the tab and click the same color again, or pick the default (no color) option.
+
+:::note
+Coloring a tab that belongs to a [group](#tab-groups) sets the group's color, so every tab in the group changes together.
+:::
+
+### Cycle the active tab's color
+
+The **Cycle current tab color** action (`workspace:cycle_active_tab_color`) steps the active tab through the available colors, then back to no color. It has no default shortcut, so reach it from the [Command Palette](/terminal/command-palette/) or bind a key to it in **Settings** > **Keyboard shortcuts**.
+
+:::tip
+Warp can also color tabs automatically based on their working directory. See `directory_tab_colors` in the [all settings reference](/terminal/settings/all-settings/#tabs).
+:::
+
 ## Tab groups
 
 Organize related tabs into named, collapsible groups. A tab group keeps its member tabs together in the tab bar, can be given a name and a color, and can be collapsed to hide its members until you need them. Tab groups work in both the horizontal tab bar and the [vertical tabs](/terminal/windows/vertical-tabs/) panel.