From af9b9b6da98785085cbcdf4357377513e9338253 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Tue, 17 Feb 2026 20:49:24 +0000
Subject: [PATCH] Update customize/themes.mdx
Co-Authored-By: mintlify[bot] <109931778+mintlify[bot]@users.noreply.github.com>
---
customize/themes.mdx | 221 +++++++++++++++++++++++++++++++++++++++++++
1 file changed, 221 insertions(+)
diff --git a/customize/themes.mdx b/customize/themes.mdx
index a3e5e9d11..e7420d37f 100644
--- a/customize/themes.mdx
+++ b/customize/themes.mdx
@@ -57,4 +57,225 @@ export const ThemeCard = ({ title, value, description, href }) => {
+## 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"
+ }
+}
+```
+
+
+ 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.
+
+
+
+ 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.
+
+
+
+ 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.
+
+
+### 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:
+
+
+
+```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"
+ }
+}
+```
+
+
+
+### 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:
+
+
+
+ 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"
+ }
+ }
+ ```
+
+
+
+ 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"
+ }
+ }
+ ```
+
+
+
+ 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"
+ }
+ }
+ ```
+
+
+
+ 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.
+
+
+
+### 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"
+ }
+}
+```
+
+
+ Custom CSS is an advanced feature. Changes may affect your documentation's appearance in unexpected ways. Always test thoroughly before deploying.
+
+
\ No newline at end of file