Skip to main content
Themes let you define a reusable set of styles and instructions that data apps can pick up. They’re a good way to keep apps on-brand across your organization without having to re-prompt the agent for the same look and feel every time.

​
What’s in a theme

A theme is a bundle of resources the agent uses when it builds an app:
  • CSS rules. Instantiated at the root of the app. Global styles are picked up automatically, and class-targeted styles are available for the agent to apply to specific elements based on the theme’s instructions.
  • Fonts. Loaded into the app and available to the agent.
  • Images. Logos, imagery intended to be used in the app, design inspiration, or examples of component styles you’d like the agent to follow. The agent tries to guess each image’s intent from its name and content, but you can be explicit in the instructions.
  • skill.md. Free-form instructions for the agent on how to use the theme. This can describe a vibe, specific interactions, or tell the agent exactly how to use the other resources in the theme.
  • Extra instructions. A free-text field on the theme itself, edited inline from the theme detail panel. Useful for quick tweaks you don’t want to manage as a file. See Extra instructions below.
The quality of a theme depends largely on the specificity of the instructions in skill.md and the extra instructions field. The more concretely you describe how the agent should use the CSS, fonts, and images - and what the app should feel like - the more consistent your results will be.

​
Size limit

A theme’s files are streamed into the app sandbox. To keep things fast and predictable, themes have a hard limit of 100 MB total across all uploaded assets (fonts, images, and instruction files combined). Individual files are capped at 10 MB. The cap is on aggregate bytes, not file count — a theme with many small text files is cheap, but a handful of large images can blow past it. Compress or downscale image assets, or split them into a smaller curated set, if you’re near the limit.

​
Extra instructions

Each theme has an Extra instructions field that you can edit directly from the theme detail panel in Settings → Themes. These instructions are passed to the agent alongside any uploaded instruction markdown files when an app is built with the theme. Use extra instructions for:
  • Quick guidance you want to iterate on without uploading or re-uploading a file.
  • Overrides or additions that complement a stable skill.md.
  • Short, focused directives — for example, capitalization rules, layout preferences, or tone.
Example:
Extra instructions
Leave the field blank to disable it — empty values are ignored at build time.

​
Creating a theme

You create and manage themes from the Themes page in Settings. Bootstrapping a theme with an agent (for example, asking an LLM to draft CSS rules and a skill.md against these guidelines) is a quick way to get a usable first version. From there, iterate on the instructions until the agent produces apps that match what you have in mind.

​
Manage themes as code

You can download, version, review, and upload themes through the same organization content-as-code workflow used for custom roles, users, and groups:
This lets you move an existing UI-created theme into version control or create a theme locally. Organization download includes every theme and writes each one under its immutable slug:
The directory name must exactly match the manifest’s slug. Every manifest field is required; use null for an empty description or extra instructions:
lightdash/themes/acme-brand/lightdash-theme.yml
To create a new theme locally, choose a new lowercase, hyphenated slug, create this manifest and any asset folders you need, then run lightdash upload --organization. Upload creates or updates the theme by manifest slug. Treat the slug as immutable; change name when you only want to rename the theme for display.
Organization mode has no theme-only selector. Before uploading, review custom roles, users, and groups under the same lightdash/ directory as well as your themes.

​
Files and validation

The CLI validates every local theme before changing any organization resource. A theme package accepts:
  • .css files under css/
  • .woff, .woff2, .ttf, and .otf files under fonts/
  • .png, .jpg, .jpeg, .gif, .webp, and .svg files under images/
  • Markdown files under instructions/
Files must live directly inside one of these folders. Nested folders, symlinks, unknown paths, unsafe filenames, unsupported file types, empty files, and files whose contents don’t match their extension are rejected. The manifest is limited to 64 KiB, each asset to 10 MB, all assets combined to 100 MB, and the complete uncompressed package to 110 MB. Don’t commit or upload restricted Apple system-font binaries such as SF-family or New York fonts. Use a system font stack instead:

​
Synchronization behavior

  • A successful download replaces the complete local themes/ directory with the remote theme set. If any theme cannot be downloaded or validated, your previous local themes are preserved.
  • Upload preflights every local theme before applying custom roles, users, groups, or themes. One invalid theme prevents all organization changes in that run.
  • An existing slug is updated, a new slug is created, and a theme whose manifest and files already match is skipped as unchanged.
  • A missing or empty local themes/ directory is a no-op. Removing one local theme directory does not delete the remote theme.
  • Upload preserves each theme’s UUID and whether it is the organization default. Set the default or delete a theme in the Lightdash UI.
  • Each theme import is atomic, but a multi-theme upload is not one transaction. If a later import fails, themes that completed earlier remain applied and the CLI reports the partial failure.
There is no standalone lightdash themes command, theme-specific --only flag, or local theme preview. If an organization theme endpoint returns 404, check that the Lightdash CLI and server versions both support theme packages.

​
Evaluate your changes

Uploading proves the package is valid, but it doesn’t rebuild or restyle existing data app versions. To see whether you like a theme, select it when generating a new data app or apply it to an existing app from the theme picker above the prompt. Lightdash creates a new app version that you can compare with the previous version. If you edit themes with an AI coding agent, install or update the Lightdash agent skills. The existing developing-in-lightdash skill teaches the agent this package format and the safe organization download/upload workflow. The agent can verify the CLI round trip without browser access; you still evaluate the generated app visually in Lightdash.

​
Setting a default theme

You can mark one theme as the default for your organization. New data apps will use the default theme unless you pick a different one.

​
Using a theme in a data app

When you create a new data app, you can choose which theme to apply. The agent will use the theme’s CSS, fonts, images, and skill.md instructions as part of the context for the build.