Add userColor3 and userColor4 hat colors (#3206)

trillium · AndreasArvidsson · web-flow · commit 86da9f4a3d8e · 2026-03-12T16:40:29.000+01:00
## Add userColor3 and userColor4 hat colors

### Summary

Add two additional user-configurable hat colors (`userColor3` and
`userColor4`) to Cursorless. Currently only 2 user-defined colors exist
(`userColor1`/navy and `userColor2`/apricot), I use 4 colors and as a
result am building the extension locally from my personal fork. Would be
great if that step wasn't necessary.

### Changes

- **Talon**: Added `userColor3` and `userColor4` to color enablement
defaults and spoken forms
(`cursorless-talon/src/marks/decorated_mark.py`,
`cursorless-talon/src/spoken_forms.json`)
- **Type definitions**: Extended `HatColor` union type in all legacy
command type files (V0V1, V2, V3)
- **Spoken form generation**: Added default spoken form mappings for the
new colors
(`cursorless-engine/src/generateSpokenForm/defaultSpokenForms/marks.ts`)
- **VS Code extension**: Added the new colors to all relevant
`package.json` settings — light/dark color values, hat enablement
booleans, hat penalties, and color enum list. Default colors: olive
green (`#6b8e23`) and light gray (`#e0e0e0`)
- **Hat styles**: Added to the `HAT_COLORS` const array
(`hatStyles.types.ts`)
- **Docs**: Updated the user-facing color table in `README.md`

Both new colors are **disabled by default**, matching the pattern of
`userColor1`/`userColor2`.

## Test plan

- [x] Verify VS Code loads without errors with default settings
- [x] Enable `userColor3` and `userColor4` in settings and confirm hats
render with the configured colors
- [ ] Assign custom spoken form names to the new colors (e.g., "white" →
`userColor3`, "black" → `userColor4`) since the defaults are placeholder
names — users must name their colors to use them
- [x] Confirm existing colors (including userColor1/userColor2) are
unaffected
- [x] Run existing test suite

---------

Co-authored-by: Andreas Arvidsson &lt;andreas.arvidsson87@gmail.com&gt;
diff --git a/cursorless-talon/src/marks/decorated_mark.py b/cursorless-talon/src/marks/decorated_mark.py
@@ -51,6 +51,8 @@ def cursorless_decorated_symbol(m) -> DecoratedSymbol:
     "yellow": True,
     "userColor1": False,
     "userColor2": False,
+    "userColor3": False,
+    "userColor4": False,
 }
 
 DEFAULT_SHAPE_ENABLEMENT = {
diff --git a/cursorless-talon/src/spoken_forms.json b/cursorless-talon/src/spoken_forms.json
@@ -245,7 +245,9 @@
       "pink": "pink",
       "yellow": "yellow",
       "navy": "userColor1",
-      "apricot": "userColor2"
+      "apricot": "userColor2",
+      "user color three": "userColor3",
+      "user color four": "userColor4"
     },
     "hat_shape": {
       "ex": "ex",
diff --git a/packages/common/src/types/command/legacy/CommandV0V1.types.ts b/packages/common/src/types/command/legacy/CommandV0V1.types.ts
@@ -120,7 +120,9 @@ type HatColor =
   | "pink"
   | "yellow"
   | "userColor1"
-  | "userColor2";
+  | "userColor2"
+  | "userColor3"
+  | "userColor4";
 type HatNonDefaultShape =
   | "ex"
   | "fox"
diff --git a/packages/common/src/types/command/legacy/PartialTargetDescriptorV3.types.ts b/packages/common/src/types/command/legacy/PartialTargetDescriptorV3.types.ts
@@ -6,7 +6,9 @@ type HatColor =
   | "pink"
   | "yellow"
   | "userColor1"
-  | "userColor2";
+  | "userColor2"
+  | "userColor3"
+  | "userColor4";
 type HatNonDefaultShape =
   | "ex"
   | "fox"
diff --git a/packages/common/src/types/command/legacy/targetDescriptorV2.types.ts b/packages/common/src/types/command/legacy/targetDescriptorV2.types.ts
@@ -6,7 +6,9 @@ type HatColor =
   | "pink"
   | "yellow"
   | "userColor1"
-  | "userColor2";
+  | "userColor2"
+  | "userColor3"
+  | "userColor4";
 type HatNonDefaultShape =
   | "ex"
   | "fox"
diff --git a/packages/cursorless-engine/src/generateSpokenForm/defaultSpokenForms/marks.ts b/packages/cursorless-engine/src/generateSpokenForm/defaultSpokenForms/marks.ts
@@ -8,6 +8,8 @@ const hatColors: Record<string, string | null> = {
   yellow: "yellow",
   userColor1: "navy",
   userColor2: "apricot",
+  userColor3: "user color three",
+  userColor4: "user color four",
 
   default: null,
 };
diff --git a/packages/cursorless-org-docs/src/docs/user/README.md b/packages/cursorless-org-docs/src/docs/user/README.md
@@ -53,16 +53,18 @@ Combining this with an action, we might say `"take blue air"` to select the toke
 
 The following colors are supported. Note that to target the default (gray) hat you don't need to specify a color.
 
-| Spoken form | Color   | Internal ID  | Enabled by default? |
-| ----------- | ------- | ------------ | ------------------- |
-| N/A         | grey    | `default`    | ✅                  |
-| `"blue"`    | blue    | `blue`       | ✅                  |
-| `"green"`   | green   | `green`      | ✅                  |
-| `"red"`     | red     | `red`        | ✅                  |
-| `"pink"`    | pink    | `pink`       | ✅                  |
-| `"yellow"`  | yellow  | `yellow`     | ✅                  |
-| `"navy"`    | navy    | `userColor1` | ❌                  |
-| `"apricot"` | apricot | `userColor2` | ❌                  |
+| Spoken form      | Color   | Internal ID  | Enabled by default? |
+| ---------------- | ------- | ------------ | ------------------- |
+| N/A              | grey    | `default`    | ✅                  |
+| `"blue"`         | blue    | `blue`       | ✅                  |
+| `"green"`        | green   | `green`      | ✅                  |
+| `"red"`          | red     | `red`        | ✅                  |
+| `"pink"`         | pink    | `pink`       | ✅                  |
+| `"yellow"`       | yellow  | `yellow`     | ✅                  |
+| `"navy"`         | navy    | `userColor1` | ❌                  |
+| `"apricot"`      | apricot | `userColor2` | ❌                  |
+| `"user color 3"` | user 3  | `userColor3` | ❌                  |
+| `"user color 4"` | user 4  | `userColor4` | ❌                  |
 
 You can enable or disable colors in your VSCode settings, by searching for [`cursorless.hatEnablement.colors`](vscode://settings/cursorless.hatEnablement.colors) and checking the box next to the internal ID for the given shape as listed above. To navigate to your VSCode settings, either say "show settings", or go to File --> Preferences --> Settings.
 
diff --git a/packages/cursorless-vscode/package.json b/packages/cursorless-vscode/package.json
@@ -427,6 +427,12 @@
             },
             "userColor2": {
               "type": "string"
+            },
+            "userColor3": {
+              "type": "string"
+            },
+            "userColor4": {
+              "type": "string"
             }
           },
           "default": {
@@ -437,7 +443,9 @@
             "pink": "#E06CAA",
             "yellow": "#E5C02C",
             "userColor1": "#6a00ff",
-            "userColor2": "#ffd8b1"
+            "userColor2": "#ffd8b1",
+            "userColor3": "#6b8e23",
+            "userColor4": "#e0e0e0"
           },
           "additionalProperties": false
         },
@@ -469,6 +477,12 @@
             },
             "userColor2": {
               "type": "string"
+            },
+            "userColor3": {
+              "type": "string"
+            },
+            "userColor4": {
+              "type": "string"
             }
           },
           "default": {
@@ -479,7 +493,9 @@
             "pink": "#e0679f",
             "yellow": "#edb62b",
             "userColor1": "#6a00ff",
-            "userColor2": "#ffd8b1"
+            "userColor2": "#ffd8b1",
+            "userColor3": "#6b8e23",
+            "userColor4": "#e0e0e0"
           },
           "additionalProperties": false
         },
@@ -700,6 +716,12 @@
             },
             "userColor2": {
               "type": "boolean"
+            },
+            "userColor3": {
+              "type": "boolean"
+            },
+            "userColor4": {
+              "type": "boolean"
             }
           },
           "default": {
@@ -709,7 +731,9 @@
             "pink": true,
             "yellow": true,
             "userColor1": false,
-            "userColor2": false
+            "userColor2": false,
+            "userColor3": false,
+            "userColor4": false
           },
           "additionalProperties": false
         },
@@ -792,6 +816,12 @@
             },
             "userColor2": {
               "type": "number"
+            },
+            "userColor3": {
+              "type": "number"
+            },
+            "userColor4": {
+              "type": "number"
             }
           },
           "default": {
@@ -801,7 +831,9 @@
             "pink": 1,
             "yellow": 1,
             "userColor1": 1,
-            "userColor2": 1
+            "userColor2": 1,
+            "userColor3": 1,
+            "userColor4": 1
           },
           "additionalProperties": false
         },
@@ -1106,7 +1138,9 @@
               "pink",
               "yellow",
               "userColor1",
-              "userColor2"
+              "userColor2",
+              "userColor3",
+              "userColor4"
             ]
           }
         },
diff --git a/packages/cursorless-vscode/src/ide/vscode/hatStyles.types.ts b/packages/cursorless-vscode/src/ide/vscode/hatStyles.types.ts
@@ -7,6 +7,8 @@ export const HAT_COLORS = [
   "yellow",
   "userColor1",
   "userColor2",
+  "userColor3",
+  "userColor4",
 ] as const;
 
 export const HAT_NON_DEFAULT_SHAPES = [

Original file line number	Diff line number	Diff line change
`@@ -51,6 +51,8 @@ def cursorless_decorated_symbol(m) -> DecoratedSymbol:`
`51`	`51`	`"yellow": True,`
`52`	`52`	`"userColor1": False,`
`53`	`53`	`"userColor2": False,`
	`54`	`+ "userColor3": False,`
	`55`	`+ "userColor4": False,`
`54`	`56`	`}`
`55`	`57`
`56`	`58`	`DEFAULT_SHAPE_ENABLEMENT = {`