EXTEND FLOWW

Theme System

Customize Floww's appearance with CSS custom properties.

Floww's entire visual layer is driven by CSS custom properties (variables). A theme is simply a set of variable overrides packaged with metadata. Themes can change colors, spacing, border radii, font sizes, and more — without touching any source code.

How Themes Work

Floww ships with a base stylesheet that defines every visual property as a CSS custom property on the :root element. When a theme is activated, Floww injects the theme's CSS overrides after the base styles, replacing the default values.

The layering order is:

1. Base styles — Floww's default theme (dark mode). Defines all variables with sensible defaults.
2. Theme overrides — your theme's CSS, which reassigns any variables you want to change.
3. User overrides — individual tweaks from the user's settings (if any).

Because themes only change variable values, they are always forward-compatible. When Floww adds new UI components, those components use the existing variables and automatically adopt the active theme.

Available CSS Variables

The following table lists all theme-able CSS custom properties. Override any of these in your theme file to change the appearance.

Backgrounds

Variable	Default	Description
--floww-bg-primary	#0e0e10	Main application background
--floww-bg-secondary	#1a1a1f	Sidebar, panel backgrounds
--floww-bg-tertiary	#24242b	Cards, dropdowns, tooltips
--floww-bg-canvas	#111115	Canvas background (behind the grid)
--floww-bg-node	#1e1e24	Node body background
--floww-bg-node-header	#282830	Node header bar
--floww-bg-input	#16161b	Text inputs, text areas
--floww-bg-hover	rgba(255,255,255,0.05)	Hover state overlay
--floww-bg-selected	rgba(99,102,241,0.12)	Selected item highlight

Text

Variable	Default	Description
--floww-text-primary	#e4e4e7	Primary body text
--floww-text-secondary	#a1a1aa	Secondary / muted text
--floww-text-tertiary	#71717a	Placeholder text, disabled labels
--floww-text-link	#818cf8	Hyperlinks
--floww-text-code	#c084fc	Inline code

Accent & Status

Variable	Default	Description
--floww-accent	#6366f1	Primary accent (buttons, active states)
--floww-accent-hover	#4f46e5	Accent hover state
--floww-success	#22c55e	Success / complete indicators
--floww-warning	#f59e0b	Warning indicators
--floww-error	#ef4444	Error indicators

Borders & Radius

Variable	Default	Description
--floww-border-color	#2e2e36	Default border color
--floww-border-radius-sm	4px	Small elements (badges, tags)
--floww-border-radius-md	8px	Cards, panels
--floww-border-radius-lg	12px	Modals, large containers
--floww-border-radius-node	10px	Node corners

Typography

Variable	Default	Description
--floww-font-family	'Inter', sans-serif	UI font stack
--floww-font-mono	'JetBrains Mono', monospace	Code / monospace font
--floww-font-size-sm	12px	Small labels
--floww-font-size-md	14px	Default body text
--floww-font-size-lg	16px	Headings, emphasis

Creating a Theme File

A theme is defined in a theme.json file that contains metadata and CSS variable overrides:

{
  "name": "Solarized Light",
  "version": "1.0.0",
  "author": "Your Name",
  "description": "A warm light theme based on Solarized.",
  "base": "light",
  "variables": {
    "--floww-bg-primary": "#fdf6e3",
    "--floww-bg-secondary": "#eee8d5",
    "--floww-bg-tertiary": "#e0dbc6",
    "--floww-bg-canvas": "#fdf6e3",
    "--floww-bg-node": "#eee8d5",
    "--floww-bg-node-header": "#ddd6c1",
    "--floww-bg-input": "#fdf6e3",
    "--floww-text-primary": "#073642",
    "--floww-text-secondary": "#586e75",
    "--floww-text-tertiary": "#93a1a1",
    "--floww-text-link": "#268bd2",
    "--floww-accent": "#2aa198",
    "--floww-accent-hover": "#1a8a82",
    "--floww-border-color": "#c5bfa7",
    "--floww-success": "#859900",
    "--floww-warning": "#b58900",
    "--floww-error": "#dc322f"
  }
}

Theme metadata fields

Field	Required	Description
name	Yes	Display name shown in the theme picker
version	Yes	Semver version string
author	No	Author name or handle
description	No	Brief description
base	No	"dark" or "light" — hints to Floww which scroll bar and system chrome to use
variables	Yes	Object mapping CSS variable names to values

Preview & Hot Reload

Floww includes a developer mode for theme creation that makes the process fast and iterative:

1. Open Floww and go to Settings → Appearance → Themes.
2. Click Open Theme Editor to enter dev mode.
3. Load your theme.json file or start from a blank template.
4. Every time you save the file, Floww reloads the theme instantly — no restart required.

You can also toggle between your in-progress theme and the default theme with the keyboard shortcut Ctrl+Shift+T (or Cmd+Shift+T on macOS) to compare.

Sharing Themes

Once your theme is ready, you can share it with others:

Export

From the theme editor, click Export Theme. This packages your theme.json into a .floww-theme file that others can import.

Import

Users install themes by opening a .floww-theme file or placing the theme.json directly in ~/.floww/themes/.

Community gallery

Submit your theme to the Floww community gallery for wider visibility. The submission process is similar to plugins:

1. Ensure your theme includes a name, version, author, and description.
2. Test on both large and small workflows to check for readability issues.
3. Submit via the floww publish --theme CLI command.
4. A reviewer checks for contrast and accessibility compliance before listing.