Add color configuration guide to themes

customize/themes.mdx

@@ -27,8 +27,8 @@
         </div>
       </div>
     </a>
   );
 };
 
 <div className="pt-10 pb-24 px-4 px-4 max-w-3xl mx-auto prose prose-gray">
   <label className="eyebrow h-5 text-primary dark:text-primary-light text-sm font-semibold">Core Concepts</label>
@@ -57,4 +57,231 @@
 
 </div>
 
+<div className=\"mt-16 prose prose-gray dark:prose-invert max-w-3xl mx-auto\">
+
+## Understanding color configuration
+
+Each theme applies your color settings differently to create its unique visual identity. Understanding how the `primary`, `light`, and `dark` color properties work will help you achieve the exact look you want.
+
+### How color properties work
+
+Configure colors in your `docs.json` file under the `colors` object:
+
+```json docs.json
+{
+  "colors": {
+    "primary": "#3B82F6",
+    "light": "#60A5FA",
+    "dark": "#1E40AF"
+  }
+}
+```
+
+<ResponseField name="primary" type="string" required>
+  The primary accent color for your documentation. Generally used for emphasis in light mode, including links, active navigation items, and interactive elements. Each theme applies this color differently to match its design language.
+</ResponseField>
+
+<ResponseField name="light" type="string">
+  The accent color used in dark mode. When users switch to dark mode, this color replaces `primary` for emphasis elements. If not specified, the `primary` color is used in both modes.
+</ResponseField>
+
+<ResponseField name="dark" type="string">
+  The color used for buttons, hover states, and strong emphasis across both light and dark modes. This typically appears on primary buttons like "Get Started" in the navbar and other call-to-action elements.
+</ResponseField>
+
+### Common color patterns
+
+<AccordionGroup>
+  <Accordion title="Single color for all elements">
+    If you only specify `primary`, it applies to all color elements in both light and dark modes:
+
+    ```json docs.json
+    {
+      "colors": {
+        "primary": "#3B82F6"
+      }
+    }
+    ```
+
+    This is the simplest approach and works well for most documentation sites.
+  </Accordion>
+
+  <Accordion title="Different colors for light and dark modes">
+    Use `primary` for light mode and `light` for dark mode to optimize contrast:
+
+    ```json docs.json
+    {
+      "colors": {
+        "primary": "#2563EB",
+        "light": "#60A5FA"
+      }
+    }
+    ```
+
+    This ensures your accent color remains visible and accessible in both modes.
+  </Accordion>
+
+  <Accordion title="Distinct button colors">
+    Use `dark` to make buttons and CTAs stand out from regular links:
+
+    ```json docs.json
+    {
+      "colors": {
+        "primary": "#3B82F6",
+        "light": "#60A5FA",
+        "dark": "#1E40AF"
+      }
+    }
+    ```
+
+    This creates a clear visual hierarchy between navigation elements and action buttons.
+  </Accordion>
+</AccordionGroup>
+
+### Testing color combinations
+
+Follow these steps to ensure your colors work well across all scenarios:
+
+<Steps>
+  <Step title="Test both light and dark modes">
+    Toggle between light and dark modes using the theme switcher in your documentation. Verify that all interactive elements remain visible and maintain good contrast.
+  </Step>
+
+  <Step title="Check contrast ratios">
+    Use a contrast checker tool to ensure your colors meet [WCAG accessibility standards](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html):
+
+    - Text and links should have at least 4.5:1 contrast ratio
+    - Large text and UI components should have at least 3:1 contrast ratio
+  </Step>
+
+  <Step title="Test interactive states">
+    Hover over links, buttons, and navigation items to verify hover states are visible and distinct from default states.
+  </Step>
+
+  <Step title="Review across different themes">
+    If you're considering switching themes, preview your color configuration with different theme options to see how each theme interprets your colors.
+  </Step>
+</Steps>
+
+### Troubleshooting color issues
+
+<AccordionGroup>
+  <Accordion title="White text on white background (or similar contrast issues)">
+    This typically happens when the `dark` color is too light or when colors aren't optimized for both modes.
+
+    **Solution:**
+
+    1. Ensure your `dark` color has sufficient contrast against white backgrounds:
+       ```json docs.json
+       {
+         "colors": {
+           "primary": "#3B82F6",
+           "dark": "#1E40AF"  // Darker shade for better contrast
+         }
+       }
+       ```
+
+    2. If the issue persists in dark mode, add a `light` color optimized for dark backgrounds:
+       ```json docs.json
+       {
+         "colors": {
+           "primary": "#2563EB",  // For light mode
+           "light": "#60A5FA",    // Lighter shade for dark mode
+           "dark": "#1E40AF"      // For buttons in both modes
+         }
+       }
+       ```
+
+    3. Test your colors against both white (`#FFFFFF`) and dark (`#0A0A0A`) backgrounds.
+  </Accordion>
+
+  <Accordion title="Colors look different than expected">
+    Each theme applies colors differently based on its design system. The same hex code may appear in different locations or with different intensities across themes.
+
+    **Solution:**
+
+    1. Review the [theme previews](/customize/themes) to understand how each theme uses colors
+    2. Test your color configuration with your chosen theme in a preview deployment
+    3. Adjust your colors based on how they appear in your specific theme
+  </Accordion>
+
+  <Accordion title="Buttons are hard to see">
+    If your primary button (like "Get Started" in the navbar) has poor visibility, the `dark` color may need adjustment.
+
+    **Solution:**
+
+    ```json docs.json
+    {
+      "colors": {
+        "primary": "#3B82F6",
+        "dark": "#1E3A8A"  // Darker, more saturated color for buttons
+      }
+    }
+    ```
+
+    The `dark` color should be bold enough to stand out as a call-to-action element.
+  </Accordion>
+
+  <Accordion title="Links are hard to distinguish from regular text">
+    If links don't stand out enough, your `primary` color may be too subtle or too similar to your text color.
+
+    **Solution:**
+
+    1. Choose a more saturated or contrasting color:
+       ```json docs.json
+       {
+         "colors": {
+           "primary": "#2563EB"  // More saturated blue
+         }
+       }
+       ```
+
+    2. Ensure sufficient contrast between your primary color and text color (typically dark gray or black in light mode)
+  </Accordion>
+</AccordionGroup>
+
+### Theme-specific color behavior
+
+Different themes interpret color properties in unique ways:
+
+<CardGroup cols={2}>
+  <Card title="Mint" icon="leaf">
+    Uses `primary` for links and active states. The `dark` color appears on primary buttons and strong emphasis elements.
+  </Card>
+
+  <Card title="Maple" icon="leaf-maple">
+    Applies colors with subtle gradients and modern styling. The `light` color is prominently used in dark mode for a softer appearance.
+  </Card>
+
+  <Card title="Palm" icon="tree-palm">
+    Features bold color application with strong contrast. All three color properties are distinctly visible across the interface.
+  </Card>
+
+  <Card title="Willow" icon="tree">
+    Minimalist approach with restrained color usage. Colors appear primarily on interactive elements and active states.
+  </Card>
+
+  <Card title="Linden" icon="tree-deciduous">
+    Terminal-inspired theme where colors provide accent against monospace typography. High contrast is essential.
+  </Card>
+
+  <Card title="Almond" icon="seedling">
+    Card-based design where colors define boundaries and interactive zones. The `dark` color is used for card hover states.
+  </Card>
+
+  <Card title="Aspen" icon="tree-pine">
+    Modern theme with sophisticated color application. Colors adapt fluidly between light and dark modes.
+  </Card>
+
+  <Card title="Sequoia" icon="trees">
+    Content-focused theme with minimal color distraction. Colors appear strategically on navigation and CTAs.
+  </Card>
+</CardGroup>
+
+<Tip>
+  Preview your color configuration with different themes by visiting the [theme showcase](/customize/themes) and comparing how your colors would appear in each design system.
+</Tip>
+
+</div>
+
 </div>