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,225 @@
 
 </div>
 
+## Understanding color configuration
+
+The `colors` object in `docs.json` controls the color scheme of your documentation. Each theme applies these colors differently, so understanding how they work is essential for achieving the look you want.
+
+### Color properties explained
+
+You configure colors in `docs.json` using three properties:
+
+```json docs.json
+{
+  "colors": {
+    "primary": "#3B82F6",
+    "light": "#60A5FA",
+    "dark": "#1E40AF"
+  }
+}
+```
+
+<ResponseField name="primary" type="string" required>
+  The main accent color for your documentation. Used for emphasis in light mode, including links, buttons, and interactive elements. The specific usage varies by theme.
+</ResponseField>
+
+<ResponseField name="light" type="string">
+  The accent color for dark mode. When users switch to dark mode, this color replaces `primary` for emphasis elements. If not specified, `primary` is used in both modes.
+</ResponseField>
+
+<ResponseField name="dark" type="string">
+  The color for buttons, hover states, and secondary interactive elements across both light and dark modes. Some themes use this for additional emphasis or contrast.
+</ResponseField>
+
+### How themes use colors
+
+Different themes apply color properties in different ways:
+
+**Mint, Maple, and Palm** use `primary` for links and emphasis in light mode, `light` for links and emphasis in dark mode, and `dark` for button backgrounds and hover states.
+
+**Willow and Linden** apply `primary` more prominently to navigation elements and headings, with `dark` used for interactive states.
+
+**Almond and Aspen** use `primary` for card borders and accents, `light` for dark mode variants, and `dark` for button fills.
+
+**Sequoia** applies colors minimally, using `primary` sparingly for key interactive elements only.
+
+### Common color patterns
+
+Here are proven color combinations for different use cases:
+
+<CodeGroup>
+
+```json Blue theme
+{
+  "colors": {
+    "primary": "#3B82F6",
+    "light": "#60A5FA",
+    "dark": "#1E40AF"
+  }
+}
+```
+
+```json Green theme
+{
+  "colors": {
+    "primary": "#10B981",
+    "light": "#34D399",
+    "dark": "#059669"
+  }
+}
+```
+
+```json Purple theme
+{
+  "colors": {
+    "primary": "#8B5CF6",
+    "light": "#A78BFA",
+    "dark": "#6D28D9"
+  }
+}
+```
+
+```json Monochrome theme
+{
+  "colors": {
+    "primary": "#374151",
+    "light": "#9CA3AF",
+    "dark": "#1F2937"
+  }
+}
+```
+
+</CodeGroup>
+
+### Testing color combinations
+
+To ensure your colors work well across both light and dark modes:
+
+1. **Check contrast ratios** - Use a tool like [WebAIM's Contrast Checker](https://webaim.org/resources/contrastchecker/) to verify your colors meet WCAG AA standards (4.5:1 for normal text, 3:1 for large text).
+
+2. **Test in both modes** - Toggle between light and dark mode in your documentation to see how colors appear. The mode toggle is in the top navigation bar.
+
+3. **Preview on different screens** - Colors appear differently on various displays. Test on multiple devices if possible.
+
+4. **Use the CLI preview** - Run `mint dev` locally to see changes in real-time before deploying.
+
+### Troubleshooting contrast issues
+
+If you encounter white-on-white text or other contrast problems:
+
+<AccordionGroup>
+  <Accordion title="White button text on white background">
+    This typically happens when `primary` is too light. Button text color is automatically determined based on the background color.
+
+    **Solution:** Use a darker shade for your `primary` color, or specify a darker `dark` color for button backgrounds:
+
+    ```json
+    {
+      "colors": {
+        "primary": "#3B82F6",
+        "dark": "#1E40AF"
+      }
+    }
+    ```
+  </Accordion>
+
+  <Accordion title="Links are hard to read in dark mode">
+    If you only specify `primary` without `light`, the same color is used in dark mode, which may not have enough contrast.
+
+    **Solution:** Add a `light` color that's brighter and works well on dark backgrounds:
+
+    ```json
+    {
+      "colors": {
+        "primary": "#2563EB",
+        "light": "#60A5FA"
+      }
+    }
+    ```
+  </Accordion>
+
+  <Accordion title="Hover states are invisible">
+    This occurs when `dark` is too similar to your background color or when it's not specified.
+
+    **Solution:** Ensure `dark` has sufficient contrast with both light and dark backgrounds:
+
+    ```json
+    {
+      "colors": {
+        "primary": "#3B82F6",
+        "light": "#60A5FA",
+        "dark": "#1E40AF"
+      }
+    }
+    ```
+  </Accordion>
+
+  <Accordion title="Colors look different than expected">
+    Each theme interprets color properties differently based on its design system.
+
+    **Solution:** Preview your documentation with different themes to see how colors are applied. You may need to adjust values for your chosen theme:
+
+    ```bash
+    mint dev
+    ```
+
+    Then change the `theme` value in `docs.json` and refresh to compare.
+  </Accordion>
+</AccordionGroup>
+
+### Theme-specific color behavior
+
+Each theme has unique characteristics that affect how colors appear:
+
+**Mint** - Traditional documentation theme with high color saturation. Colors are prominent and used frequently throughout the interface.
+
+**Maple** - Modern, clean aesthetic with subtle color usage. Colors appear primarily on interactive elements and accents.
+
+**Palm** - Enterprise-focused with sophisticated color application. Uses colors for hierarchy and emphasis in complex layouts.
+
+**Willow** - Minimalist theme with restrained color usage. Colors are used sparingly for maximum impact.
+
+**Linden** - Retro terminal theme with monospace fonts. Colors are applied to mimic classic terminal interfaces.
+
+**Almond** - Card-based design with colors used for borders and subtle accents. Color application is gentle and non-intrusive.
+
+**Aspen** - Modern theme with bold color usage in navigation and components. Colors are used to create visual hierarchy.
+
+**Sequoia** - Content-first theme with minimal color application. Colors appear only on essential interactive elements.
+
+### Advanced color customization
+
+For more control over specific elements, you can use custom CSS:
+
+```css custom.css
+:root {
+  --primary: #3B82F6;
+  --primary-light: #60A5FA;
+  --primary-dark: #1E40AF;
+}
+
+/* Override specific elements */
+.docs-button {
+  background-color: var(--primary-dark);
+}
+
+.docs-link:hover {
+  color: var(--primary);
+}
+```
+
+Then reference your custom CSS file in `docs.json`:
+
+```json docs.json
+{
+  "styling": {
+    "css": "/custom.css"
+  }
+}
+```
+
+<Note>
+  Custom CSS is an advanced feature. Changes may affect your documentation's appearance in unexpected ways. Always test thoroughly before deploying.
+</Note>
+
 </div>