fix: remove shadowed entries from 256-colour TTY tables

alecthomas · claude · alecthomas · commit 180daf7d28aa · 2026-07-05T15:52:40.000+10:00
Go map literals silently keep the last duplicate key, so the nine
system-colour entries (indices 0 and 8-15) whose RGB values also
appear in the 6x6x6 cube/greyscale ramp were dead code. The cube
codes were already the effective mappings, so behaviour is
unchanged; the table now says what it does. A test asserts the
entry counts so dropped or shadowed entries fail fast.

Co-Authored-By: Claude Fable 5 &lt;noreply@anthropic.com&gt;
diff --git a/formatters/tty_indexed.go b/formatters/tty_indexed.go
@@ -44,12 +44,15 @@ var ttyTables = map[int]*ttyTable{
 			c("#0000ff"): "\033[104m", c("#ff00ff"): "\033[105m", c("#00ffff"): "\033[106m", c("#ffffff"): "\033[107m",
 		},
 	},
+	// System colours 0 and 8-15 are omitted from the 256-colour tables: their
+	// RGB values duplicate colours in the 6x6x6 cube/greyscale ramp (indices
+	// 16, 244, 196, 46, 226, 21, 201, 51 and 231), and duplicate map keys
+	// silently overwrite each other. The cube/greyscale codes are preferred
+	// as terminal themes commonly remap the system colours.
 	256: {
 		foreground: map[chroma.Colour]string{
-			c("#000000"): "\033[38;5;0m", c("#800000"): "\033[38;5;1m", c("#008000"): "\033[38;5;2m", c("#808000"): "\033[38;5;3m",
+			c("#800000"): "\033[38;5;1m", c("#008000"): "\033[38;5;2m", c("#808000"): "\033[38;5;3m",
 			c("#000080"): "\033[38;5;4m", c("#800080"): "\033[38;5;5m", c("#008080"): "\033[38;5;6m", c("#c0c0c0"): "\033[38;5;7m",
-			c("#808080"): "\033[38;5;8m", c("#ff0000"): "\033[38;5;9m", c("#00ff00"): "\033[38;5;10m", c("#ffff00"): "\033[38;5;11m",
-			c("#0000ff"): "\033[38;5;12m", c("#ff00ff"): "\033[38;5;13m", c("#00ffff"): "\033[38;5;14m", c("#ffffff"): "\033[38;5;15m",
 			c("#000000"): "\033[38;5;16m", c("#00005f"): "\033[38;5;17m", c("#000087"): "\033[38;5;18m", c("#0000af"): "\033[38;5;19m",
 			c("#0000d7"): "\033[38;5;20m", c("#0000ff"): "\033[38;5;21m", c("#005f00"): "\033[38;5;22m", c("#005f5f"): "\033[38;5;23m",
 			c("#005f87"): "\033[38;5;24m", c("#005faf"): "\033[38;5;25m", c("#005fd7"): "\033[38;5;26m", c("#005fff"): "\033[38;5;27m",
@@ -112,10 +115,8 @@ var ttyTables = map[int]*ttyTable{
 			c("#d0d0d0"): "\033[38;5;252m", c("#dadada"): "\033[38;5;253m", c("#e4e4e4"): "\033[38;5;254m", c("#eeeeee"): "\033[38;5;255m",
 		},
 		background: map[chroma.Colour]string{
-			c("#000000"): "\033[48;5;0m", c("#800000"): "\033[48;5;1m", c("#008000"): "\033[48;5;2m", c("#808000"): "\033[48;5;3m",
+			c("#800000"): "\033[48;5;1m", c("#008000"): "\033[48;5;2m", c("#808000"): "\033[48;5;3m",
 			c("#000080"): "\033[48;5;4m", c("#800080"): "\033[48;5;5m", c("#008080"): "\033[48;5;6m", c("#c0c0c0"): "\033[48;5;7m",
-			c("#808080"): "\033[48;5;8m", c("#ff0000"): "\033[48;5;9m", c("#00ff00"): "\033[48;5;10m", c("#ffff00"): "\033[48;5;11m",
-			c("#0000ff"): "\033[48;5;12m", c("#ff00ff"): "\033[48;5;13m", c("#00ffff"): "\033[48;5;14m", c("#ffffff"): "\033[48;5;15m",
 			c("#000000"): "\033[48;5;16m", c("#00005f"): "\033[48;5;17m", c("#000087"): "\033[48;5;18m", c("#0000af"): "\033[48;5;19m",
 			c("#0000d7"): "\033[48;5;20m", c("#0000ff"): "\033[48;5;21m", c("#005f00"): "\033[48;5;22m", c("#005f5f"): "\033[48;5;23m",
 			c("#005f87"): "\033[48;5;24m", c("#005faf"): "\033[48;5;25m", c("#005fd7"): "\033[48;5;26m", c("#005fff"): "\033[48;5;27m",
diff --git a/formatters/tty_indexed_test.go b/formatters/tty_indexed_test.go
@@ -8,6 +8,25 @@ import (
 	"github.com/alecthomas/chroma/v3"
 )
 
+func TestTTYTableEntriesAreDistinct(t *testing.T) {
+	// The 256-colour palette has only 247 distinct RGB values; see the
+	// comment on ttyTables. A count below these values means an entry has
+	// been dropped or shadowed by a duplicate key.
+	tests := []struct {
+		colours  int
+		expected int
+	}{
+		{8, 16},
+		{16, 16},
+		{256, 247},
+	}
+	for _, test := range tests {
+		table := ttyTables[test.colours]
+		assert.Equal(t, test.expected, len(table.foreground))
+		assert.Equal(t, test.expected, len(table.background))
+	}
+}
+
 func TestClosestColour(t *testing.T) {
 	actual := findClosest(ttyTables[256], chroma.MustParseColour("#e06c75"))
 	assert.Equal(t, chroma.MustParseColour("#d75f87"), actual)
