// Detailed instructions and examples for developing theme resources in Rill
| name | rill-theme |
| description | Detailed instructions and examples for developing theme resources in Rill |
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.
Themes can be applied in two ways:
rill.yaml:# rill.yaml
explores:
theme: brand
canvases:
theme: brand
# dashboards/sales.yaml
type: explore
metrics_view: sales_metrics
theme: brand
Themes support multiple color formats:
# (recommended): "#FF6A00", "#6366f1"#: FF6A00 (works but less explicit)blue, plum, darkgreen, seagreenhsl(180, 100%, 50%), hsl(236, 34%, 34%)For consistency and clarity, we recommend using quoted hex values with the # prefix.
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
color-qualitative-7: "#3b82f6" # Blue
color-qualitative-8: "#a855f7" # Violet
color-qualitative-9: "#ef4444" # Red
color-qualitative-10: "#14b8a6" # Teal
color-qualitative-11: "#84cc16" # Lime
color-qualitative-12: "#f97316" # Orange
color-qualitative-13: "#d946ef" # Fuchsia
color-qualitative-14: "#eab308" # Yellow
color-qualitative-15: "#0ea5e9" # Sky
color-qualitative-16: "#a855f7" # Purple alt
color-qualitative-17: "#22c55e" # Green
color-qualitative-18: "#fb923c" # Orange alt
color-qualitative-19: "#f43f5e" # Rose
color-qualitative-20: "#6366f1" # Indigo alt
color-qualitative-21: "#2dd4bf" # Teal alt
color-qualitative-22: "#facc15" # Yellow alt
color-qualitative-23: "#c084fc" # Violet alt
color-qualitative-24: "#4ade80" # Green alt
# Sequential palette for ordered data (optional, 9 colors)
# Used for heatmaps, choropleth maps, intensity scales
color-sequential-1: "#eef2ff" # Lightest
color-sequential-2: "#e0e7ff"
color-sequential-3: "#c7d2fe"
color-sequential-4: "#a5b4fc"
color-sequential-5: "#818cf8"
color-sequential-6: "#6366f1"
color-sequential-7: "#4f46e5"
color-sequential-8: "#4338ca"
color-sequential-9: "#3730a3" # Darkest
# Diverging palette for data with a meaningful midpoint (optional, 11 colors)
# Used for showing positive/negative deviation from a baseline
color-diverging-1: "#dc2626" # Negative extreme (red)
color-diverging-2: "#f87171"
color-diverging-3: "#fca5a5"
color-diverging-4: "#fecaca"
color-diverging-5: "#fee2e2"
color-diverging-6: "#f3f4f6" # Neutral midpoint
color-diverging-7: "#dbeafe"
color-diverging-8: "#93c5fd"
color-diverging-9: "#60a5fa"
color-diverging-10: "#3b82f6"
color-diverging-11: "#2563eb" # Positive extreme (blue)
# Dark mode colors
dark:
# Core brand colors (brighter for visibility on dark backgrounds)
primary: "#818cf8"
secondary: "#a78bfa"
# UI surface colors
background: "#0f172a" # Deep slate background
surface: "#1e293b" # Elevated surfaces
card: "#334155" # Card backgrounds
# KPI delta colors (optional)
# kpi-positive: "#4ade80" # Green for positive deltas (brighter for dark mode)
# kpi-negative: "#f87171" # Red for negative deltas (brighter for dark mode)
# Qualitative palette (adjusted for dark mode visibility)
color-qualitative-1: "#818cf8"
color-qualitative-2: "#a78bfa"
color-qualitative-3: "#f472b6"
color-qualitative-4: "#22d3ee"
color-qualitative-5: "#34d399"
color-qualitative-6: "#fbbf24"
color-qualitative-7: "#60a5fa"
color-qualitative-8: "#c084fc"
color-qualitative-9: "#f87171"
color-qualitative-10: "#2dd4bf"
color-qualitative-11: "#a3e635"
color-qualitative-12: "#fb923c"
color-qualitative-13: "#e879f9"
color-qualitative-14: "#facc15"
color-qualitative-15: "#38bdf8"
color-qualitative-16: "#c084fc"
color-qualitative-17: "#4ade80"
color-qualitative-18: "#fdba74"
color-qualitative-19: "#fb7185"
color-qualitative-20: "#818cf8"
color-qualitative-21: "#5eead4"
color-qualitative-22: "#fde047"
color-qualitative-23: "#d8b4fe"
color-qualitative-24: "#86efac"
# Sequential palette (reversed for dark mode)
color-sequential-1: "#312e81" # Darkest
color-sequential-2: "#3730a3"
color-sequential-3: "#4338ca"
color-sequential-4: "#4f46e5"
color-sequential-5: "#6366f1"
color-sequential-6: "#818cf8"
color-sequential-7: "#a5b4fc"
color-sequential-8: "#c7d2fe"
color-sequential-9: "#e0e7ff" # Lightest
# Diverging palette (adjusted for dark backgrounds)
color-diverging-1: "#ef4444"
color-diverging-2: "#f87171"
color-diverging-3: "#fca5a5"
color-diverging-4: "#fecaca"
color-diverging-5: "#fee2e2"
color-diverging-6: "#475569" # Neutral slate midpoint
color-diverging-7: "#bfdbfe"
color-diverging-8: "#93c5fd"
color-diverging-9: "#60a5fa"
color-diverging-10: "#3b82f6"
color-diverging-11: "#2563eb"
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"
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"
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
Detailed instructions and examples for developing the rill.yaml file
Detailed instructions and examples for developing metrics view resources in Rill
Detailed instructions and examples for developing canvas dashboard resources in Rill
Detailed instructions and examples for developing model resources in Rill
Detailed instructions and examples for developing connector resources in Rill
Detailed instructions and examples for developing explore dashboard resources in Rill
