# Themes

Retype's theme system allows you to customize the visual appearance of your website by overriding theme variables. With themes, you can adjust colors, spacing, typography, and other design elements to match your brand or project preferences.

Pro Feature

The theme functionality requires a Retype Pro key or adding the following pro trial mode setting into your project retype.yml configuration file:

start
  pro: true

# Quick Start

The quickest way to customize your site's appearance is by adding a theme configuration to your retype.yml file and setting a custom base-color theme variable.

theme:
  base:
    base-color: "#8839ef"

# Configuration Structure

The theme configuration supports two main sections:

# `base` theme

The base theme controls the light mode appearance and serves as the foundation for your project's visual style:

theme:
  base:
    base-color: "#8839ef"
    base-bg: "#eff1f5"
    base-link-weight: 500
    image-rounded: 0.75rem

# `dark` theme

The dark theme specifically targets dark mode appearance. When the website is switched to dark mode, the dark theme variables override the base theme variables. The following demonstrates how to configure the dark theme variables:

theme:
  dark:
    base-color: "#ca9ee6"
    base-bg: "#303446"

# Examples

# Brand Color Customization

To match your brand colors:

theme:
  base:
    base-color: "#ff6b35"  # Orange brand color

# Typography Adjustments

To better match your project style and user-experience requirements:

theme:
  base:
    base-link-weight: 500            # Slightly bolder links
    nav-item-text-active-weight: 700 # Bold active navigation
    heading-text: "#1a202c"          # Darker headings

# Dark Mode Optimization

To adjust the dark mode:

theme:
  dark:
    base-bg: "#0a0e1a"              # Very dark blue background
    sidebar-left-bg: "#1a1f2e"      # Slightly lighter sidebar
    base-text: "#e2e8f0"            # Light grey text
    heading-text: "#ffffff"         # Pure white headings
    base-border: "#2d3748"          # Subtle borders

# Component Styling

To customize component colors and other elements:

theme:
  base:
    # Rounded images
    image-rounded: 0.75rem
    
    # Custom variant colors
    primary: "#8caaee" # Blue
    success: "#a6d189" # Green
    danger: "#e78284"  # Red
    warning: "#e5c890" # Yellow    

# Best Practices

When customizing your Retype theme, it’s best to start with small changes and gradually build up. Here are some guidelines to help you maintain a clean, accessible, and consistent design.

# 1. Start with the `base-color`

Begin by tweaking a few brand colors before diving into full theme customization. This keeps things manageable and easier to approve before moving on to further theme refinements.

theme:
  base:
    base-color: "#8839ef" #your-brand-color

# 2. Prioritize readability and contrast

Contrast between text and background is important for readability and accessibility. Avoid color combinations that are too similar and do not provide enough contrast.

theme:
  base:
    base-text: "#4c4f69"     # A strong neutral text color
    base-bg: "#ffffff"       # Clean light background

Use online contrast checkers to validate your color palette against WCAG standards.

# 3. Check light and dark modes

If you are customizing both the base and dark themes, be sure to test your changes in each mode. A color that works well in light mode might look washed out or harsh in dark mode, and require further refinement.

theme:
  base:
    base-color: "#8839ef"
  dark:
    base-color: "#ca9ee6"

# 4. Use Semantic variables where possible

Instead of hardcoding colors everywhere, use the built-in semantic theme variables. It keeps your theme consistent and easier to maintain.

theme:
  base:
    nav-item-text-active: "var(--base-500)"  # Uses a consistent brand tone

Following these practices helps ensure your site looks good, stays accessible, and is easy to maintain as it grows.

# Troubleshooting

# Theme Not Applied

Ensure you have a valid Retype Pro license or add start.pro: true
Check that the syntax is correct in your retype.yml file
Verify theme variable names match exactly

# Dark Mode Issues

Remember that dark theme variables only apply in dark mode
Test with the theme switcher on your website
Some variables may need both base and dark configured to provide proper contrast

# Variable Names

All variable names use kebab-case (hyphens, not underscores)
Variables are case-sensitive
Don't include the -- prefix in your configuration