Themes & Styling¶

Control the visual appearance of your dashboard globally or per-chart.

Themes¶

Dataface includes 18+ built-in themes that apply consistent styling across your entire dashboard - charts, tables, variables, titles, and backgrounds all respond to the selected theme.

Using a Theme¶

Add theme: at the top level of your dashboard:

title: "Sales Dashboard"
theme: dark

queries:
  sales: SELECT * FROM sales

layout:
  - chart: revenue_chart

Available Themes¶

Theme	Description	Background
`light`	Clean default theme	White
`dark`	Dark mode with blue-gray tones	Dark blue-gray
`minimal`	Clean with no gridlines or borders	White
`excel`	Microsoft Excel style	White
`ggplot2`	R's ggplot2 style	Light gray
`quartz`	Quartz design style	Off-white
`vox`	Vox Media design	White
`fivethirtyeight`	FiveThirtyEight style	White
`latimes`	LA Times newspaper style	White
`urbaninstitute`	Urban Institute style	White
`googlecharts`	Google Charts style	White
`powerbi`	Microsoft Power BI style	White
`carbon-white`	IBM Carbon Design (light)	White
`carbon-g10`	IBM Carbon (slightly darker)	#f4f4f4
`carbon-g90`	IBM Carbon (dark)	#262626
`carbon-g100`	IBM Carbon (darkest)	#161616
`vintage`	Florence Nightingale-inspired	Antique white

Theme Examples¶

Dark Theme:

title: "Analytics Dashboard"
theme: dark

layout:
  - chart: daily_metrics
  - chart: revenue_breakdown

FiveThirtyEight Theme:

title: "Election Results"
theme: fivethirtyeight

layout:
  - chart: poll_results

What Themes Control¶

Themes automatically style:

✅ Dashboard background - Overall page background color
✅ Chart colors - Bars, lines, areas, points
✅ Axis styling - Grid lines, labels, titles
✅ Tables - Header backgrounds, borders, stripes
✅ Variables - Input backgrounds, borders, labels
✅ Titles - Text color and contrast

Custom Themes¶

You can create custom themes in your dataface.yml config file:

# dataface.yml
themes:
  my-brand:
    background: "#f8f9fa"
    title:
      color: "#2c3e50"
    axis:
      gridColor: "#ecf0f1"
      labelColor: "#7f8c8d"
    bar:
      fill: "#3498db"
    range:
      category:
        - "#3498db"
        - "#e74c3c"
        - "#2ecc71"
        - "#f39c12"

Then use it:

theme: my-brand

Theme Inheritance¶

Themes can extend other themes using extends:

# dataface.yml
themes:
  my-dark-brand:
    extends: dark
    bar:
      fill: "#e74c3c"  # Override just the bar color
    range:
      category:
        - "#e74c3c"
        - "#3498db"

Global Styling¶

Set styling options for the entire dashboard:

style:
  palette: "category10"         # Color scheme name
  font: "Inter"                  # Font family
  grid_lines: true               # Show grid lines by default
  background: "#f5f5f5"          # General background color
  backgrounds:                   # Format-specific backgrounds
    svg: transparent
    png: "#ffffff"
    pdf: "#ffffff"
  css: "assets/custom.css"       # Import custom CSS file

Style Options¶

palette: Color scheme (e.g., "category10", "viridis", "blues")
font: Font family name
grid_lines: true or false to show/hide grid lines by default
background: General background color (hex, rgb, name, or "transparent")
backgrounds: Format-specific backgrounds (svg, png, pdf)
css: Path to a custom CSS file (relative to dashboard file or public root)

CSS Scope & Limitations¶

The style.css file styles the Dashboard Shell (HTML), but has limitations regarding internal Chart elements (SVG).

What CSS Can Style (HTML)¶

Layout: Rows, columns, grids, margins.
Typography: Section titles, markdown text, KPI cards, headers.
Interactive Elements: Filter inputs, buttons, tabs.
Backgrounds: Page background, section borders, shadows.

What CSS Cannot Style (Charts)¶

Chart Internals: Bars, lines, axes, legends inside the Vega-Lite charts.
PDF Exports: Static exports use a different rendering path where external CSS may not apply fully.

Recommendation: - Use Style Options (style.palette, chart.style) for chart colors and axes. - Use Custom CSS for layout, typography, and branding of the surrounding page.

Chart-Level Styling¶

Override theme for specific charts:

charts:
  custom_chart:
    title: "Custom Styled Chart"
    query: queries.sales
    type: bar
    x: month
    y: total_revenue
    style:
      palette: "viridis"          # Different color scheme
      legend: show                # Show legend
      grid_lines: false           # Hide grid lines
      labels: show                # Always show labels

Style Options¶

Color Palettes¶

Choose from built-in color palettes:

category10 - Default categorical palette (10 colors)
viridis - Perceptually uniform sequential palette
blues - Blue sequential palette
reds - Red sequential palette
greens - Green sequential palette
grays - Grayscale palette

Choosing a palette: - Categorical data: Use category10 or other categorical palettes - Sequential data: Use viridis, blues, reds, greens - Accessibility: Consider colorblind-friendly palettes

Legend¶

Control legend display:

style:
  legend: show    # Always show legend
  legend: hide    # Hide legend

Grid Lines¶

Show or hide grid lines:

style:
  grid_lines: true   # Show grid lines
  grid_lines: false  # Hide grid lines

Labels¶

Control axis label display:

style:
  labels: auto   # Auto-label placement (default)
  labels: show   # Always show labels
  labels: hide   # Hide labels

Typography¶

Set the font family via the top-level style configuration:

style:
  font: "Inter"  # Font family name

Common font choices: - Inter - Modern, readable sans-serif - Roboto - Google's Material Design font - Open Sans - Friendly, readable sans-serif - Lato - Humanist sans-serif

Board-Level Styling¶

Apply CSS-like styles to any board or nested layout section:

rows:
  - title: "Styled Section"
    style:
      background: "#f0f4f8"
      border: "2px solid #667eea"
      border-radius: "8px"
      padding: "16px"
      color: "#333"
    cols:
      - chart: my_chart

Supported Style Properties¶

Property	Example	SVG	HTML	Description
`background`	`"#f5f5f5"`	✅	✅	Background color (hex, rgb, named)
`border`	`"2px solid #ddd"`	✅	✅	Border shorthand (width style color)
`border-radius`	`"8px"`	✅	✅	Corner rounding
`color`	`"#333"`	✅	✅	Text color
`padding`	`"16px"`	✅	✅	Inner spacing (affects content layout)
`margin`	`"8px 16px"`	❌	✅	Outer spacing
`gap`	`"12px"`	✅	✅	Override gap between child items

Padding & Sizing¶

Padding is accounted for in layout calculations. When you add padding to a board:

The board's children have less available space
Content is properly inset from the border
Height calculations include the padding

# Padding formats (CSS-style)
style:
  padding: "16px"           # All sides equal
  padding: "8px 16px"       # Vertical, horizontal
  padding: "8px 16px 12px"  # Top, horizontal, bottom
  padding: "8px 16px 12px 4px"  # Top, right, bottom, left

Border Styling¶

Borders support the CSS shorthand format:

style:
  border: "2px solid #667eea"  # width style color
  border-radius: "8px"         # Rounded corners

Example: Styled Cards¶

Create card-style sections with backgrounds and borders:

cols:
  - content: "### Success Card"
    style:
      background: "#c8e6c9"
      border: "2px solid #4caf50"
      border-radius: "12px"
      color: "#1b5e20"

  - content: "### Warning Card"
    style:
      background: "#fff3e0"
      border: "2px solid #ff9800"
      border-radius: "12px"

Layout Sizing¶

Automatic Sizing¶

Dataface automatically calculates sizes based on content:

Charts: 300px default height (KPIs: 100px, Tables: 250px)
Titles: Height based on font size and text length
Markdown content: Height based on rendered text with word-wrapping

User-Specified Widths¶

In cols layouts, specify widths for individual items:

cols:
  - width: "30%"    # 30% of available width
    chart: sidebar_chart
  - width: "70%"    # 70% of available width
    chart: main_chart

Supported formats: - Percentages: "30%", "70%" - Pixels: "200px", "400px" - Auto (default): Remaining space divided equally

Gap Control¶

Control spacing between items:

# Per-section gap override
rows:
  - title: "Compact Section"
    style:
      gap: "8px"  # Smaller gap between children
    cols:
      - chart: a
      - chart: b

Content-Aware Heights¶

Heights are calculated based on content type:

Content Type	Default Height
Standard chart	300px
KPI card	100px
Table	250px
Title	Based on text
Markdown	Based on rendered content

In cols layouts, all items get the same height (maximum of their content heights) for proper alignment.

Best Practices¶

Consistent Styling¶

Use the same color palette throughout a dashboard
Keep font choices consistent
Use grid lines consistently (all on or all off)

Accessibility Considerations¶

Choose colorblind-friendly palettes
Ensure sufficient contrast
Use labels and legends for clarity

Color Choices¶

Categorical data: Use distinct colors (category10)
Sequential data: Use gradient palettes (viridis, blues)
Avoid: Too many colors (5-7 max for clarity)

Performance¶

Styling has minimal performance impact
Use global style when possible (more efficient)
Override only when necessary

Charts - Chart styling options
Boards - Layout and organization
Configuration - Custom themes in dataface.yml

Themes & Styling¶

Themes¶

Using a Theme¶

Available Themes¶

Theme Examples¶

What Themes Control¶

Custom Themes¶

Theme Inheritance¶

Global Styling¶

Style Options¶

CSS Scope & Limitations¶

What CSS Can Style (HTML)¶

What CSS Cannot Style (Charts)¶

Chart-Level Styling¶

Style Options¶

Color Palettes¶

Legend¶

Grid Lines¶

Labels¶

Typography¶

Board-Level Styling¶

Supported Style Properties¶

Padding & Sizing¶

Border Styling¶

Example: Styled Cards¶

Layout Sizing¶

Automatic Sizing¶

User-Specified Widths¶

Gap Control¶

Content-Aware Heights¶

Best Practices¶

Consistent Styling¶

Accessibility Considerations¶

Color Choices¶

Performance¶

Related¶