From d9a2d080f76ee83572654f2eaac41e862db37c2d Mon Sep 17 00:00:00 2001
From: Keith Guerin <keithguerin@gmail.com>
Date: Thu, 26 Feb 2026 13:51:08 -0800
Subject: [PATCH] feat(ui): finalize /colors layout and improve interaction
 explanation

---
 .../src/ui/components/ColorsDisplay.test.tsx  |  3 ++
 .../cli/src/ui/components/ColorsDisplay.tsx   | 34 ++++++++++++++-----
 2 files changed, 28 insertions(+), 9 deletions(-)

diff --git a/packages/cli/src/ui/components/ColorsDisplay.test.tsx b/packages/cli/src/ui/components/ColorsDisplay.test.tsx
index 1cb9515896..9872f3ff2d 100644
--- a/packages/cli/src/ui/components/ColorsDisplay.test.tsx
+++ b/packages/cli/src/ui/components/ColorsDisplay.test.tsx
@@ -69,6 +69,9 @@ describe('ColorsDisplay', () => {
     // Check for title and description
     expect(output).toContain('/colors - Theme Colors Demo');
     expect(output).toContain('visualize how colors are used');
+    expect(output).toContain('How themes and terminals interact');
+    expect(output).toContain('TrueColor (Hex)');
+    expect(output).toContain('ANSI Names');
 
     // Check for active theme name
     expect(output).toContain('Test Theme');
diff --git a/packages/cli/src/ui/components/ColorsDisplay.tsx b/packages/cli/src/ui/components/ColorsDisplay.tsx
index 4c5fb2c307..d0845f7e2f 100644
--- a/packages/cli/src/ui/components/ColorsDisplay.tsx
+++ b/packages/cli/src/ui/components/ColorsDisplay.tsx
@@ -143,15 +143,31 @@ export const ColorsDisplay: React.FC = () => {
         <Box marginTop={1} flexDirection="column">
           <Text color={theme.text.secondary}>
             <Text bold color={theme.text.primary}>
-              Note on overrides:
-            </Text>{' '}
-            Hex values (TrueColor) are rendered exactly as shown and are
-            generally <Text italic>not</Text> affected by your Terminal
-            app&apos;s theme. Color names (like &apos;red&apos;,
-            &apos;green&apos;, &apos;gray&apos;) used in the ANSI theme{' '}
-            <Text italic>are</Text> overridden by your Terminal app&apos;s
-            palette.
+              How themes and terminals interact:
+            </Text>
           </Text>
+          <Box marginLeft={2} flexDirection="column">
+            <Text color={theme.text.secondary}>
+              • <Text bold>TrueColor (Hex):</Text> Modern terminals (iTerm2,
+              Ghostty, VSCode) render hex codes exactly. They are{' '}
+              <Text italic>not</Text> overridden by terminal app themes.
+            </Text>
+            <Text color={theme.text.secondary}>
+              • <Text bold>ANSI Names:</Text> Colors like &apos;red&apos; or
+              &apos;green&apos; (used in our ANSI theme) <Text italic>are</Text>{' '}
+              mapped to your terminal app&apos;s specific palette.
+            </Text>
+            <Text color={theme.text.secondary}>
+              • <Text bold>Default colors:</Text> When Name or Value is
+              &apos;(blank)&apos;, the app uses your terminal&apos;s default
+              foreground/background.
+            </Text>
+            <Text color={theme.text.secondary}>
+              • <Text bold>Compatibility:</Text> In terminals with limited color
+              (like older Mac Terminals), hex colors are automatically
+              approximated to the closest available ANSI color.
+            </Text>
+          </Box>
         </Box>
         <Box marginTop={1}>
           <Text color={theme.text.secondary}>
@@ -250,7 +266,7 @@ function renderBackgroundRow({ name, value }: BackgroundColorRow) {
   const description = COLOR_DESCRIPTIONS[name] || '';
 
   return (
-    <Box key={name} flexDirection="row" paddingX={1} marginBottom={1}>
+    <Box key={name} flexDirection="row" paddingX={1}>
       <Box
         width={VALUE_COLUMN_WIDTH}
         backgroundColor={value}