rill-theme

name	rill-theme
description	Detailed instructions and examples for developing theme resources in Rill

Instructions for developing a theme in Rill

Introduction

Themes are resources that define custom color palettes for dashboards in a Rill project. They allow you to customize the visual appearance of explore and canvas dashboards to match your brand or design preferences.

Themes are lightweight resources with no reconciliation cost. When a theme file is saved, Rill validates it but performs no heavy operations. Themes are referenced from rill.yaml for project-wide styling or directly from individual explore or canvas dashboards.

Core Concepts

Referencing themes

Themes can be applied in two ways:

1. Project-wide via rill.yaml:

# rill.yaml
explores:
  theme: brand
canvases:
  theme: brand

2. Per-dashboard in an explore or canvas file:

   # dashboards/sales.yaml
   type: explore
   metrics_view: sales_metrics
   theme: brand
   

Color formats

Themes support multiple color formats:

• Hex with # (recommended): "#FF6A00", "#6366f1"
• Hex without #: FF6A00 (works but less explicit)
• Named CSS colors: blue, plum, darkgreen, seagreen
• HSL values: hsl(180, 100%, 50%), hsl(236, 34%, 34%)

For consistency and clarity, we recommend using quoted hex values with the # prefix.

Recommended Theme Structure

The recommended approach uses separate light: and dark: blocks to define mode-specific colors. This ensures your dashboards look great in both light and dark modes.

# themes/brand.yaml
type: theme

# Light mode colors
light:
  # Core brand colors (required)
  primary: "#6366f1"     # Primary actions, emphasis, selected states
  secondary: "#8b5cf6"   # Secondary elements, supporting colors

  # UI surface colors (optional - defaults used if omitted)
  background: "#f8fafc"  # Page background
  surface: "#ffffff"     # Elevated surfaces, panels
  card: "#f1f5f9"        # Card backgrounds

  # KPI delta colors (optional - controls comparison/change value colors)
  # kpi-positive: "#16a34a"  # Green for positive deltas (defaults to gray)
  # kpi-negative: "#dc2626"  # Red for negative deltas (defaults to red)

  # Qualitative palette for categorical data (optional, 24 colors)
  # Used for bar charts, pie charts, legend colors by category
  color-qualitative-1: "#6366f1"   # Indigo
  color-qualitative-2: "#8b5cf6"   # Purple
  color-qualitative-3: "#ec4899"   # Pink
  color-qualitative-4: "#06b6d4"   # Cyan
  color-qualitative-5: "#10b981"   # Emerald
  color-qualitative-6: "#f59e0b"   # Amber
      
      
      
     
     
     
     
     
     
     
     
     
     
     
     
     
     
     

  
  
      
   
   
   
   
   
   
   
      

  
  
       
   
   
   
   
       
   
   
   
   
      



  
   
   

  
     
        
           

  
  
  

  
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   
   

  
      
   
   
   
   
   
   
   
      

  
   
   
   
   
   
       
   
   
   
   
   

Minimal Theme Example

If you only need to set brand colors without customizing palettes, use this minimal structure:

# themes/brand.yaml
type: theme

light:
  primary: "#0369a1"
  secondary: "#06b6d4"

dark:
  primary: "#38bdf8"
  secondary: "#22d3ee"

Legacy Format

Older Rill projects may use a simpler format with a top-level colors: block. This format is still supported but deprecated in favor of the light:/dark: structure:

# Legacy format (deprecated)
type: theme
colors:
  primary: "#FF6A00"
  secondary: "#0F46A3"

Reference documentation

Here is a full JSON schema for the theme syntax:

allOf:
    - properties:
        colors:
            additionalProperties: true
            description: Color palette for the theme
            properties:
                primary:
                    description: Primary color
                    type: string
                secondary:
                    description: Secondary color
                    type: string
            type: object
        dark:
            description: Dark theme color configuration
            properties:
                kpi-negative:
                    description: Color for negative KPI delta values in dark theme. Defaults to red.
                    type: string
                kpi-positive:
                    description: Color for positive KPI delta values in dark theme. Defaults to fg-secondary (gray).
                    type: string
                primary:
                    description: Primary color for dark theme. Can have any hex, [named colors](https://www.w3.org/TR/css-color-4/#named-colors) or hsl() formats.
                    type: string
                secondary:
                    description: Secondary color for dark theme. Can have any hex, [named colors](https://www.w3.org/TR/css-color-4/#named-colors) or hsl() formats.
                    type: string
                variables:
                    additionalProperties:
                        type: string
                    description: Custom CSS variables for dark theme
                    type: object
            type: object
        light:
            description: Light theme color configuration
            properties:
                kpi-negative:
                    description: Color for negative KPI delta values in light theme. Defaults to red.
                    type: string
                kpi-positive:
                    description: Color for positive KPI delta values in light theme. Defaults to fg-secondary (gray).
                    type: string
                primary:
                    description: Primary color for light theme. Can have any hex, [named colors](https://www.w3.org/TR/css-color-4/#named-colors) or hsl() formats.
                    type: string
                secondary:
                    description: Secondary color for light theme. Can have any hex, [named colors](https://www.w3.org/TR/css-color-4/#named-colors) or hsl() formats.
                    type: string
                variables:
                    additionalProperties:
                        type: string
                    description: Custom CSS variables for light theme
                    type: object
            type: object
        type:
            const: theme
            description: Refers to the resource type and must be `theme`
            type: string
      required:
        - type
      title: Properties
      type: object
    - $ref: '#/definitions/common_properties'
description: |
    In your Rill project directory, create a `<theme_name>.yaml` file in any directory containing `type: theme`. Rill will automatically ingest the theme next time you run `rill start` or deploy to Rill Cloud.

    To apply that theme to a dashboard, add `default_theme: <name of theme>` to the yaml file for that dashboard. Alternatively, you can add this to the end of the URL in your browser: `?theme=<name of theme>`
examples:
    - dark:
        primary: '#818CF8'
        secondary: '#A78BFA'
      light:
        primary: '#4F46E5'
        secondary: '#8B5CF6'
      type: theme
    - dark:
        color-sequential-1: hsl(180deg 40% 30%)
        color-sequential-5: hsl(180deg 50% 50%)
        color-sequential-9: hsl(180deg 60% 70%)
        primary: 2DD4BF
        secondary: 34D399
      light:
        color-qualitative-1: hsl(156deg 56% 52%)
        color-qualitative-2: hsl(27deg 100% 65%)
        color-sequential-1: hsl(180deg 80% 95%)
        color-sequential-5: hsl(180deg 80% 50%)
        color-sequential-9: hsl(180deg 80% 25%)
        primary: '#14B8A6'
        secondary: '#10B981'
      type: theme
    - dark:
        kpi-negative: '#f87171'
        kpi-positive: '#4ade80'
        primary: '#818cf8'
        secondary: '#a78bfa'
      light:
        kpi-negative: '#dc2626'
        kpi-positive: '#16a34a'
        primary: '#6366f1'
        secondary: '#8b5cf6'
      type: theme
id: themes
title: Theme YAML
type: object