Skip to main content

​
Theme Customization

This guide explains how to customize the MOOD MNKY documentation theme while maintaining compatibility with Mintlify’s requirements.

​
Current Theme Configuration

Our documentation uses a monochromatic black and white theme with agent-specific accent colors:
  • Primary colors: Black, white, and gray tones
  • Agent colors:
    • MOOD MNKY: Amber/gold (#FCD34D)
    • CODE MNKY: Blue (#93C5FD)
    • SAGE MNKY: Green (#86EFAC)
  • Typography: RocGroteskWide, RocGrotesk, Helvetica, and HelveticaRounded font families

​
Mintlify Configuration

The theme is configured in docs.json with these key settings: 
{
  "colors": {
    "primary": "#000000",
    "light": "#F5F5F5",
    "dark": "#333333"
  },
  "fonts": {
    "family": "Helvetica, sans-serif",
    "weight": 400
  },
  "css": [
    "/styles.css"
  ]
}
Important LimitationsMintlify has specific requirements for theme configuration:
  1. Only the properties shown above are supported in the colors object
  2. Font configuration is limited to family and weight
  3. Custom font files must be loaded via CSS
  4. Only woff and woff2 font formats are officially supported

​
Custom CSS Styling

We use a custom CSS file (styles.css) for additional styling beyond what Mintlify’s configuration allows: 
/* Agent-specific color variables */
:root {
  /* MOOD MNKY colors - amber */
  --mood-mnky-light: #FCD34D;
  --mood-mnky-medium: #F59E0B;
  --mood-mnky-dark: #92400E;
  
  /* CODE MNKY colors - blue */
  --code-mnky-light: #93C5FD;
  --code-mnky-medium: #3B82F6;
  --code-mnky-dark: #1E40AF;
  
  /* SAGE MNKY colors - green */
  --sage-mnky-light: #86EFAC;
  --sage-mnky-medium: #22C55E;
  --sage-mnky-dark: #15803D;
}

​
Typography System

The MOOD MNKY application uses a comprehensive typography system that combines brand identity with readability:

​
Font Families

​
Brand Fonts

  • RocGroteskWide

    Bold, distinctive typeface for headings, titles, and brand elements

  • RocGrotesk

    More condensed version with better readability for UI elements and text that maintains brand identity

​
Functional Fonts

  • Helvetica

    Clean, neutral typeface for body text and general content

  • HelveticaRounded

    Friendlier variant with rounded terminals for UI elements like buttons

​
Tailwind Font Utilities

The application uses Tailwind CSS for styling with custom font family utilities: 
// Excerpt from tailwind.config.ts
fontFamily: {
  sans: ['Helvetica', 'ui-sans-serif', 'system-ui', 'sans-serif'],
  display: ['RocGroteskWide', 'sans-serif'],
  heading: ['RocGroteskWide', 'sans-serif'],
  brand: ['RocGroteskWide', 'sans-serif'],
  body: ['Helvetica', 'ui-sans-serif', 'system-ui', 'sans-serif'],
  grotesk: ['RocGrotesk', 'sans-serif'],
  rounded: ['HelveticaRounded', 'Helvetica', 'sans-serif'],
}

​
Font Hierarchy and Usage

ElementFont ClassFont FamilyUse Case
H1-H3font-headingRocGroteskWideMajor headings, page titles, section headers
H4-H6font-groteskRocGroteskSubheadings, card titles, form section headers
Body Textfont-bodyHelveticaParagraphs, lists, general content
UI Elementsfont-roundedHelveticaRoundedButtons, important action items, calls to action
Brand Elementsfont-brandRocGroteskWideLogo treatments, feature callouts, brand statements

​
Authentication Pages Typography

The authentication pages (sign-in, sign-up) demonstrate best practices for typography implementation:
  • Page Headers: font-heading with tracking-wide for brand-consistent headings
  • Card Titles: font-heading to maintain brand identity in component headers
  • Card Descriptions: font-grotesk text-sm for better readability in smaller text while maintaining brand feel
  • Form Labels: font-grotesk font-medium for clear, legible labels
  • Buttons: font-rounded for action items with a friendly, approachable feel
  • Links: font-grotesk with font-medium for emphasized interactive elements
  • Legal Text: font-grotesk for better readability at small sizes
<h2 className="text-2xl font-bold mb-6 text-center font-heading tracking-wide">
  Welcome Back
</h2>
<Card className="w-full shadow-lg border-mnky-gray-700">
  <CardHeader className="pb-3">
    <CardTitle className="font-heading tracking-wide">Sign in</CardTitle>
    <CardDescription className="font-grotesk text-sm">
      Enter your email and password to access your account
    </CardDescription>
  </CardHeader>
  <CardContent>
    {/* Form elements */}
    <Label htmlFor="email" className="font-grotesk font-medium">Email</Label>
    <Input className="border-input/80" />
    
    <SubmitButton className="bg-mood-light text-black font-rounded">
      Sign in
    </SubmitButton>
  </CardContent>
  <CardFooter>
    <p className="text-sm text-muted-foreground font-body">
      Don't have an account?{" "}
      <Link className="text-primary font-medium font-grotesk" href="/sign-up">
        Sign up
      </Link>
    </p>
  </CardFooter>
</Card>

​
Using Agent-Specific Styling

Each agent has its own color scheme that can be applied to content using CSS classes: 
<div className="mood-mnky-section">
  <h2>MOOD MNKY Features</h2>
  <img 
    src="/images/mood-mnky-avatar.png" 
    className="agent-avatar mood-mnky-avatar" 
  />
  <div className="mood-mnky-card">
    Specialized content here
  </div>
</div>

​
Available CSS Classes

ClassPurpose
mood-mnky-sectionContainer for MOOD MNKY content with amber headings
mood-mnky-cardContent card with amber left border
mood-mnky-borderElement with amber border
mood-mnky-avatarAvatar image with amber border
code-mnky-sectionContainer for CODE MNKY content with blue headings
code-mnky-cardContent card with blue left border
code-mnky-borderElement with blue border
code-mnky-avatarAvatar image with blue border
sage-mnky-sectionContainer for SAGE MNKY content with green headings
sage-mnky-cardContent card with green left border
sage-mnky-borderElement with green border
sage-mnky-avatarAvatar image with green border

​
Modifying the Theme

If you need to update the theme, follow these guidelines:
  1. Mintlify Configuration: Edit only supported properties in docs.json
  2. Custom Styling: Make other changes in styles.css
  3. Testing: Use mintlify dev to test locally before deploying
Always validate your docs.json changes before deploying. Use mintlify dev to catch configuration errors.

​
Troubleshooting

​
Common Errors

​
Invalid Configuration Properties

#.colors: Unrecognized key(s) in object: 'background', 'anchors'
Solution: Remove unsupported properties from the colors object in docs.json.

​
Font Format Issues

#.fonts.heading.format: Invalid enum value. Expected 'woff' | 'woff2', received 'opentype'
Solution: Use the simplified font configuration in docs.json and handle detailed font loading in styles.css.

​
Path Issues

#.fonts.heading.source: Invalid url
Solution: Font loading via URL should be handled in CSS, not in the Mintlify configuration.