Theme Protocol

Little Tree Wallpaper Next supports adjusting the application’s color scheme and background style through custom theme files to enhance the visual experience. Theme files use JSON format, allowing developers to define colors, background images, component styles, and metadata for theme store display.

Storage Location

Default theme directory: %APPDATA%/Little-Tree-Wallpaper/Next/themes/ (Windows, actual path determined by app.paths.CONFIG_DIR).
Specify theme through configuration item ui.theme_profile:
- "default": Use built-in default theme.
- Custom theme: Provide relative path (such as "aurora.json") or absolute path.

If the directory does not exist, it will be automatically created when the application starts.

Theme File Structure

Theme files are JSON objects, recommended to include the following two types of content:

Metadata (for theme store display)
Style definitions (for runtime rendering)

{
  "name": "Aurora Green",
  "logo": "logo.png",
  "description": "A fresh and soft green theme inspired by aurora and forest.",
  "details": "This theme uses Material You dynamic color technology, adapting to dark and light modes. Background images use Unsplash HD materials, supporting transparent mask overlay to ensure text readability.",
  "author": "Little Tree Team",
  "website": "https://little-tree.dev/themes/aurora-green",

  "palette": {
    "mode": "seed",
    "seed_color": "#34d399",
    "preferred_mode": "dark",
    "use_material3": true
  },
  "background": {
    "image": "https://images.unsplash.com/photo-1469474968028-56623f02e42e",
    "opacity": 0.35,
    "fit": "cover",
    "alignment": "center",
    "repeat": "no_repeat"
  },
  "components": {
    "page": {
      "bgcolor": "#0f172a"
    },
    "app_bar": {
      "bgcolor": "#0f172a",
      "color": "#f8fafc"
    },
    "navigation_rail": {
      "bgcolor": "#111827",
      "indicator_color": "#34d399"
    },
    "navigation_container": {
      "bgcolor": "#111827"
    }
  }
}

Metadata Fields (optional but recommended)

These fields do not participate in runtime rendering and are only used for theme store display, search, and detail pages:

Field	Type	Description
`name`	String	Theme name (required, for display)
`logo`	String	Theme icon file name (relative to theme file path, such as `"logo.png"`; if exists, theme store will prioritize display)
`description`	String	Brief introduction (recommended ≤100 characters, for list summary)
`details`	String	Detailed introduction (supports markdown, for detail page)
`author`	String	Author or team name
`website`	String	Theme homepage or project link (optional)

All metadata fields can be omitted, but it is recommended to fill them completely to improve theme discoverability and user experience.

Style Definition Fields

Consistent with the original protocol, including three parts: palette, background, components, detailed below.

Color Scheme (`palette`)

Supports two modes:

seed mode: Generate complete color palette through a single primary color.
- seed_color: Hexadecimal color (such as #34d399), required.
- preferred_mode: light / dark / system (optional).
- use_material3: Boolean value, enable Material 3 style (optional).
custom mode: Directly provide complete color_scheme.
- color_scheme: Object containing primary, surface, on_primary and other fields.
- brightness: light or dark.

Color values support:

#RRGGBB or #AARRGGBB
rgb(255, 0, 0) / rgba(255, 0, 0, 0.5)
Flet color constants (such as "surface_container_highest", automatically convert underscores)

Background (`background`)

Field	Description
`image`	Image path or URL. Relative paths are searched in order: theme file directory → `themes/` → configuration directory. Leave empty for no background image.
`opacity`	0.0 ~ 1.0, default 1.0
`fit`	`cover` (default), `contain`, `fill`, `fit_width`, `fit_height`, `scale_down`, `none`
`alignment`	`center` (default), `top_left`, `bottom_right`, etc.
`repeat`	`no_repeat` (default), `repeat`, `repeat_x`, `repeat_y`

Background images are at the bottommost layer and displayed overlaid with content.

Component Styles (`components`)

Use component identifiers as keys, values are attribute dictionaries. Common components include:

page: Global page (ft.Page)
app_bar: Top application bar
navigation_rail: Side navigation bar
navigation_container: Content container
home_view: Home page view (supports overlay_color, overlay_opacity, force_bgcolor)

Attributes are written directly to Flet controls through setattr, field names need to be consistent with control attributes. Color fields are automatically parsed.

Manually Enable Custom Theme

Put the theme JSON file into the themes/ directory.

Modify config.json:

{
  "ui": {
    "theme_profile": "aurora.json"
  }
}

Restart the application or trigger theme reload.

If parsing fails, the application will fall back to the default theme and log a warning.

Example Theme

The project repository provides an example: docs/themes/xuan_niao.json. After copying to the configuration directory, set theme_profile to "xuan_niao.json" to use it.

Welcome to create your exclusive theme based on this template and submit it to the Little Tree Wallpaper Theme Store!