Customization & Configuration

Customize Colors and Typography

Fine-tune your documentation site's visual appearance by customizing brand colors, text colors, and typography for optimal readability and brand consistency.

Fine-tune your documentation site's visual appearance by customizing specific color elements and typography. This guide focuses on detailed color customization beyond basic theme setup to achieve perfect brand alignment.

These site-wide color settings work together with page-level front matter to create a cohesive brand experience across all documentation pages.

Prerequisites

Basic understanding of theme and color setup
Your brand color palette or style guide
Access to your documentation.json file
Understanding of hex color codes and contrast ratios

Customize Brand Colors

Follow these steps to align your documentation colors with your brand identity.

Step 1: Identify your color requirements

Gather your brand colors in hex format:

Primary brand color (for buttons, links, call-to-actions)
Text hierarchy colors (headings vs body text)
Ensure colors work for both light and dark backgrounds

Step 2: Configure light theme colors

In your documentation.json, customize the light theme colors:

{
  "colors": {
    "light": {
      "brand": "#3143e3",
      "heading": "#1a1a1a", 
      "text": "#374151"
    }
  }
}

Configure each color property:

brandstring

Set your primary brand color for interactive elements. Use hex format (e.g., #3143e3).

headingstring

Choose a strong color for headings and titles. Default: #1a1a1a.

textstring

Select a readable color for body text. Ensure good contrast. Default: #374151.

Step 3: Configure dark theme colors

Add complementary colors for dark mode that maintain brand consistency:

{
  "colors": {
    "dark": {
      "brand": "#85a1ff",
      "heading": "#f2f2f2",
      "text": "#c1c1c1"
    }
  }
}

Dark theme considerations:

brandstring

Use a lighter/brighter version of your brand color. Use hex format (e.g., #85a1ff).

headingstring

Choose high contrast colors for readability in dark mode. Default: #f2f2f2.

textstring

Ensure sufficient contrast against dark backgrounds. Default: #c1c1c1.

Step 4: Test color combinations

Save your configuration
Deploy or preview your changes
Test both light and dark modes
Check text readability in various lighting conditions
Verify brand colors maintain visual hierarchy

Typography Best Practices

The Documentation.AI platform automatically handles typography optimization, but consider these guidelines when choosing colors:

Contrast Requirements

Maintain WCAG AA compliance (4.5:1 contrast ratio minimum)
Test colors with accessibility tools
Ensure readability for users with visual impairments

Brand Consistency

Use your brand's primary color for interactive elements
Maintain consistent color relationships between themes
Consider your brand's tone (professional, friendly, technical)

Visual Hierarchy

Make headings distinctly different from body text
Use your brand color strategically to guide user attention
Ensure navigation elements stand out appropriately

Advanced Color Customization

Step 5: Test across devices

View on different screen sizes (mobile, tablet, desktop)
Test in various lighting conditions
Check color accuracy across different displays
Verify accessibility with screen readers

Step 6: Document your color choices

Keep a record of your color decisions:

Brand color hex codes and their usage
Contrast ratio measurements
Any accessibility considerations
Brand guideline compliance notes

Verify Your Color Setup

Visual check: Compare with your brand guidelines
Contrast test: Use tools like WebAIM Contrast Checker
User testing: Get feedback on readability
Cross-browser testing: Ensure consistency across browsers
Accessibility audit: Test with screen readers and accessibility tools

Troubleshooting Common Issues

Low contrast: Darken light theme text or lighten dark theme text
Brand mismatch: Adjust colors to better match your style guide
Poor readability: Increase contrast between text and background colors

What's Next

Color customization is entirely optional. Documentation.AI provides carefully designed defaults that meet accessibility standards. Only customize colors if you need specific brand alignment or have particular visual requirements.