Godot Ui Theming
- 300 installs
- 454 repo stars
- Updated July 28, 2026
- thedivergentai/gd-agentic-skills
godot-ui-theming is a Godot 4.x UI theming skill that implements Theme resources, StyleBoxes, and dynamic theme switching for developers building consistent game interface styling.
About
godot-ui-theming from thedivergentai/GD-Agentic-Skills is an expert blueprint for Godot 4.x UI themes using Theme resources, StyleBoxes, custom fonts, and theme overrides for consistent visual styling. It covers StyleBoxFlat and StyleBoxTexture, theme inheritance, dynamic theme switching, font variations, RTL mirroring, and DPI scaling. The skill bundles 12 GDScript reference scripts including global_theme_manager.gd, theme_swapper.gd, ui_scale_manager.gd, crisp_ui_scaler.gd, and rtl_theme_mirroring.gd. It documents NEVER rules such as avoiding per-node StyleBox instantiation, skipping theme inheritance, hardcoding colors, using add_theme_override for global styles, and defining StyleBoxes inside _draw loops. Developers reach for godot-ui-theming when implementing consistent UI styling, supporting dark mode or high-contrast themes, or applying theme_type_variation for semantic button styles in Godot 4.5+ game projects.
- godot-ui-theming
Godot Ui Theming by the numbers
- 300 all-time installs (skills.sh)
- +15 installs in the week ending Jul 27, 2026 (Skillselion tracking)
- Ranked #1,322 of 4,347 Backend & APIs skills by installs in the Skillselion catalog
- Data as of Aug 5, 2026 (Skillselion catalog sync)
npx skills add https://github.com/thedivergentai/gd-agentic-skills --skill godot-ui-themingAdd your badge
Show developers this skill is listed on Skillselion. Paste this into your README.
| Installs | 300 |
|---|---|
| repo stars | ★ 454 |
| Last updated | July 28, 2026 |
| Repository | thedivergentai/gd-agentic-skills ↗ |
How do you theme Godot 4 UI with Theme resources?
Use godot-ui-theming for development tasks
Who is it for?
Godot 4.x game developers implementing shared Theme resources, StyleBox patterns, and runtime theme switching across Control nodes.
Skip if: Non-Godot engines or 2D gameplay logic without Control-node UI theming requirements.
When should I use this skill?
A developer implements Godot UI styling, Theme resources, StyleBoxFlat, dark mode switching, or theme_type_variation patterns.
What you get
.theme resource files, StyleBox configurations, GDScript theme managers, and runtime dark-mode or RTL theme switching setup.
- .theme resource files
- theme manager GDScript
- StyleBox configuration patterns
By the numbers
- Bundles 12 GDScript theming reference scripts
- Documents 11 NEVER-do UI theming anti-patterns
- Part of GD-Agentic-Skills library targeting Godot 4.5+
Files
UI Theming
Theme resources, StyleBox styling, font management, and override system define consistent UI visual identity.
Available Scripts
global_theme_manager.gd
Expert theme manager with dynamic switching, theme variants, and fallback handling.
ui_scale_manager.gd
Runtime theme switching and DPI/Resolution scale management.
theme_swapper.gd
Dynamic Dark/Light mode implementation using cascading theme root propagation.
danger_button_assignment.gd
Expert use of theme_type_variation for semantic UI styling without scene duplication.
dynamic_stylebox_color.gd
Safe runtime StyleBox modification. Demonstrates the critical duplicate() pattern for isolated overrides.
procedural_theme_safe.gd
Reliable theming for generated UI elements using NOTIFICATION_THEME_CHANGED.
custom_chart_drawing.gd
Pattern for reading active Theme properties (colors, fonts) in custom _draw() logic.
theme_isolation.gd
Ensuring HUD consistency by isolating nodes from parent themes and referencing Project Defaults.
pulsating_ui_theme.gd
Animating UI styles via Tweens. Targets StyleBox properties directly after duplication.
crisp_ui_scaler.gd
High-quality resolution-independent scaling using content_scale_factor to maintain font crispness.
memory_safe_custom_drawing.gd
Fixing the "disappearing stylebox" bug by caching resources at the class level for the RenderingServer.
rtl_theme_mirroring.gd
Bi-directional (RTL/LTR) UI support. Swaps theme variants dynamically based on layout direction.
NEVER Do in UI Theming
- NEVER create StyleBox in `_ready()` for many nodes — Instantiating
StyleBoxFlat.new()100 times creates 100 unique objects. Use a Theme resource for shared heritage. - NEVER forget theme inheritance — Parent themes are ignored if a child has its own theme. Apply themes at the root and use
theme_type_variationfor specific overrides. - NEVER hardcode colors in StyleBox — Use
theme.get_color()to maintain a single source of truth for your palette. - NEVER use `add_theme_override` for global styles — This is brittle. Define styles in a Theme resource for automatic propagation across the project.
- NEVER modify theme resources during `_draw()` OR `_process()` — Frequent layout recalculations will severely degrade performance.
- NEVER assign `StyleBoxEmpty` to focus styles without a fallback — This invisibly breaks controller/keyboard navigation [1]. Always provide a visible alternative (e.g. scale change).
- NEVER use standard `set()` for theme properties — Calling
node.set("font_color", red)fails. You MUST use the dedicatedadd_theme_color_override()API [3]. - *NEVER use `expand_margin_
to increase clickable area** — It only expands the VISUAL bounds. Usecontent_margin_*` on the StyleBox or adjust the Control's size to ensure input works [5]. - NEVER define StyleBoxes as local variables inside `_draw()` — They will be garbage collected before the RenderingServer can finish drawing them [7]. Store at class level.
- NEVER duplicate scenes/themes just to change one color — Use
theme_type_variationto create lightweight derived styles (e.g. "DangerButton") within the same Theme [8]. - NEVER skip `corner_radius_all` shortcut — It's a useful shorthand for uniform rounding in
StyleBoxFlat.
---
1. Project Settings → GUI → Theme 2. Create new Theme resource 3. Assign to root Control node 4. All children inherit theme
StyleBox Pattern
# Create StyleBoxFlat for buttons
var style := StyleBoxFlat.new()
style.bg_color = Color.DARK_BLUE
style.corner_radius_top_left = 5
style.corner_radius_top_right = 5
style.corner_radius_bottom_left = 5
style.corner_radius_bottom_right = 5
# Apply to button
$Button.add_theme_stylebox_override("normal", style)Font Loading
# Load custom font
var font := load("res://fonts/my_font.ttf")
$Label.add_theme_font_override("font", font)
$Label.add_theme_font_size_override("font_size", 24)Expert Theming Patterns
1. Shared-Color-Palette (The Static Pattern)
Maintain a single source of truth for UI colors accessible to both the Theme Editor and GDScript.
- Theme Setup: In your
.themefile, create a custom type calledPaletteand addColoritems (e.g.,primary,danger,accent). - Static Access: Use a
SharedPaletteclass withstatic func get_primary() -> Colorthat pulls fromThemeDB.get_project_theme(). This ensures UI scripts and the visual theme never drift.
2. Theme-Type-Variations
Avoid duplicating button scenes or styleboxes for variants like "Danger" or "Ghost" styles.
- Implementation: In the Theme Editor, create a new Type Variation. Set its Base Type to
Button. - Inheritance: The variation inherits all properties from the base type. You only override what's different (e.g., set
font_colorto red forDangerButton). - Usage: Assign via code
node.theme_type_variation = &"DangerButton"or via the Inspector dropdown.
3. Runtime-Theme-Swapping (Accessibility)
Efficiently switch the visual style of the entire game for Light, Dark, or High-Contrast modes.
- Cascading Updates: Assign a new
Themeresource to the root Control node. Godot propagates this to every descendant. - Accessibility: Use
NOTIFICATION_THEME_CHANGEDto update elements that don't support automatic theming (like custom_draw()logic or RichText effects). - High-Contrast: Ensure High-Contrast themes use pure black/white and thicker focus outlines for low-vision accessibility.
4. Themed-Asset-Loading (Seasonal Variants)
Godot Themes support more than just colors and fonts—they can store textures.
- Setup: Define UI icons as Icon items within separate Theme resources (e.g.,
halloween.theme,christmas.theme). - Swapping: Swapping the root theme resource instantly cascades the new icon textures across all buttons and panels without manual logic.
5. UI-Focus-Manager (Dynamic Controller Icons)
Standard focus styles are static. For professional UX, swap controller icons based on the connected device.
- Detection: Use
Input.get_joy_name(device)to identify the controller (e.g., "PS4 Controller", "Xbox One Controller"). - Implementation:
func _on_joy_connection_changed(device: int, connected: bool):
if connected:
var joy_name = Input.get_joy_name(device).to_lower()
if "xbox" in joy_name:
_set_prompt_icons("res://ui/icons/xbox/")
elif "playstation" in joy_name or "ps" in joy_name:
_set_prompt_icons("res://ui/icons/ps/")- Interpolation: When a node gains focus, use a
Tweento move a dedicated "Highlight Panel" to the node'sget_global_rect().
6. Asset-Dependency-Audit (Draw-Call Reduction)
Ensuring UI textures are optimized for rendering performance.
- Atlas Packing: Use
AtlasTextureto crop small UI elements from a singular large sheet. This reduces VRAM state changes and minimizes draw calls [14]. - Compression Policy:
- 2D/Pixel Art: Use Lossless compression to avoid blurry artifacts [15].
- UI Backgrounds: Use Lossy or Basis Universal for large illustrations to save disk space without decreasing VRAM usage [15].
- Audit: Use
ResourceLoader.get_dependencies(scene_path)to ensure no uncompressed raw assets (e.g..png) are leaking into the final export [19].
Reference
Related
- Master Skill: godot-master
# crisp_ui_scaler.gd
# Resolution-independent UI scaling via content_scale_factor [18]
extends Node
func _ready() -> void:
get_tree().root.size_changed.connect(_update_ui_scale)
func _update_ui_scale() -> void:
var window_size := get_tree().root.size
# Baseline is 1080p.
# Scaling the factor instead of node.scale keeps fonts and styleboxes
# crisp and pixel-perfect at any resolution.
var factor: float = window_size.y / 1080.0
get_tree().root.content_scale_factor = factor
# custom_chart_drawing.gd
# Reading theme properties for custom _draw() calls [14]
extends Control
func _draw() -> void:
# Respect the active Theme even in custom drawing logic
var accent := get_theme_color("accent_color", "CustomChart")
var ui_font := get_theme_font("font", "Label")
var ui_size := get_theme_font_size("font_size", "Label")
var style := get_theme_stylebox("panel", "PanelContainer")
# Draw background using the theme's panel style
draw_style_box(style, Rect2(Vector2.ZERO, size))
# Draw custom data visualization using theme colors
draw_circle(size / 2.0, 20.0, accent)
draw_string(ui_font, Vector2(10, size.y - 10), "Themed Label", HORIZONTAL_ALIGNMENT_LEFT, -1, ui_size)
# danger_button_assignment.gd
# Using Theme Variations to create specialized styles without custom scenes [12]
extends Button
func _ready() -> void:
# Assigning a StringName tells the node to look for this variation
# in the active Theme. If found, it uses those overrides; otherwise,
# it falls back to the base "Button" style.
theme_type_variation = &"DangerButton"
# dynamic_stylebox_color.gd
# Safely overriding StyleBoxes at runtime without affecting other nodes [10]
extends Button
func set_runtime_color(new_color: Color) -> void:
# CRITICAL: StyleBoxes are resources and SHARED by default.
# You MUST duplicate() before modifying or you will change the whole theme.
var custom_style := get_theme_stylebox("normal").duplicate() as StyleBoxFlat
if custom_style:
custom_style.bg_color = new_color
# Apply the unique override to this specific instance only
add_theme_stylebox_override("normal", custom_style)
# skills/ui-theming/code/global_theme_manager.gd
extends Node
## UI Theming Expert Pattern
## Implements Global Theme Architecture and Runtime Skin Swapping.
@export var light_theme: Theme
@export var dark_theme: Theme
# 1. Runtime Skin Swapping
func set_theme_mode(is_dark: bool) -> void:
# Professional protocol: Apply theme to the root to cascade to all nodes.
var target_theme = dark_theme if is_dark else light_theme
# Option A: Global Theme (Godot 4 property)
# This affects every UI node in the project instantly.
# ThemeDB.set_project_theme(target_theme) # Generic Godot 4 approach
# Option B: Root Scene Hand-off
get_tree().root.theme = target_theme
print("UI Theme swapped to: ", "Dark" if is_dark else "Light")
# 2. Theme Variation Logic
func apply_button_variant(button: Button, variant_name: String) -> void:
# Professional protocol: Use 'theme_type_variation' to swap styles
# (e.g. PrimaryButton vs DangerButton) without manual hacking.
button.theme_type_variation = variant_name
# 3. StyleBox Nine-Patch Mastery
func create_custom_panel() -> StyleBoxFlat:
# Expert logic: Programmatically define a StyleBox with proper
# anti-aliasing and corner radii for high-end UI.
var sb = StyleBoxFlat.new()
sb.bg_color = Color(0.1, 0.1, 0.1, 1.0)
sb.corner_radius_top_left = 8
sb.corner_radius_top_right = 8
sb.corner_detail = 12
sb.anti_aliasing = true
return sb
## EXPERT NOTE:
## Use 'Theme Type Variations': Create a variation called 'HeaderLabel'
## in your .theme file. Apply it to specific Label nodes to change
## their font size globally without creating separate Label scenes.
## For 'ui-theming', implement 'Color Palettes as Constants':
## Define a 'Colors' static class for shared hex codes to ensure
## code-generated UI matches your .theme files perfectly.
## NEVER use 'Theme Overrides' on individual nodes for global styling;
## use the '.theme' resource. Overrides are for 1-off exceptions
## and make global visual updates impossible.
## Use 'NinePatchRect' or 'StyleBoxTexture' for complex UI borders
## to prevent blurring when boxes are resized.
# memory_safe_custom_drawing.gd
# Preventing garbage collection of StyleBoxes during _draw() [7]
extends Control
# CRITICAL: If you create a StyleBox inside _draw(), it will be
# garbage collected before the RenderingServer can use it.
# ALWAYS cache styleboxes used for draw_style_box at the class level.
var _persistent_style: StyleBoxFlat
func _ready() -> void:
_persistent_style = StyleBoxFlat.new()
_persistent_style.bg_color = Color.MEDIUM_SLATE_BLUE
_persistent_style.corner_radius_all = 8
func _draw() -> void:
draw_style_box(_persistent_style, Rect2(Vector2.ZERO, size))
# procedural_theme_safe.gd
# Ensuring safe theme lookups for procedurally generated UI [13]
extends PanelContainer
func _notification(what: int) -> void:
# NOTIFICATION_THEME_CHANGED is the most reliable hook for
# dynamic theming as it catches tree entry and theme swaps.
if what == NOTIFICATION_THEME_CHANGED:
if not is_node_ready():
await ready
# Safely match a procedural element's color to the theme's core Button text
var fallback_color := get_theme_color("font_color", "Button")
$Label.add_theme_color_override("font_color", fallback_color)
# pulsating_ui_theme.gd
# Animating Theme properties via Tweens (Requires duplication) [10]
extends PanelContainer
var _tween_style: StyleBoxFlat
func trigger_pulsate() -> void:
# Duplicate stylebox to ensure only THIS button pulsates
_tween_style = get_theme_stylebox("panel").duplicate() as StyleBoxFlat
add_theme_stylebox_override("panel", _tween_style)
var tween = create_tween().set_loops()
# Target the resource property directly
tween.tween_property(_tween_style, "bg_color", Color.RED, 0.4)
tween.tween_property(_tween_style, "bg_color", Color.BLACK, 0.4)
# rtl_theme_mirroring.gd
# Handling Right-to-Left (RTL) layout mirroring via Themes [19]
extends MarginContainer
func _notification(what: int) -> void:
if what == NOTIFICATION_THEME_CHANGED or what == NOTIFICATION_TRANSLATION_CHANGED:
# Detect if the current locale (Arabic, Hebrew) requires RTL
if is_layout_rtl():
# Apply mirrored stylebox/font overrides
var rtl_style := get_theme_stylebox("panel_rtl", "CustomHUD")
add_theme_stylebox_override("panel", rtl_style)
else:
remove_theme_stylebox_override("panel")
# theme_isolation.gd
# Forcing a node to ignore parent themes and use the Project default [15]
extends Control
func _ready() -> void:
# If a parent customizes the theme, but this HUD needs absolute consistency:
var baseline_theme := ThemeDB.get_project_theme()
# Explicitly setting the theme resource halts the upward tree search.
# This ensures the HUD pulls only from the Project Settings theme.
self.theme = baseline_theme
# theme_swapper.gd
# Dynamic theme switching (Dark/Light mode) with cascading propagation
extends Node
@export var light_theme: Theme
@export var dark_theme: Theme
func set_dark_mode(is_dark: bool) -> void:
# Find the root control (usually your main scene root)
# Applying a theme at the root level updates all children automatically [11].
var root_control := get_tree().root.get_child(0) as Control
if root_control:
root_control.theme = dark_theme if is_dark else light_theme
# skills/ui-theming/scripts/ui_scale_manager.gd
extends Node
## UI Scale & Theme Manager Expert Pattern
## Global management of UI scaling and theme swapping.
class_name UIScaleManager
signal scale_changed(new_scale: float)
signal theme_changed(new_theme_resource: Theme)
@export var base_resolution := Vector2i(1920, 1080)
@export var min_scale := 0.5
@export var max_scale := 2.0
var _current_scale := 1.0
func _ready() -> void:
get_tree().root.size_changed.connect(_update_scale)
_update_scale()
func set_theme(theme_path: String) -> void:
var new_theme = load(theme_path) as Theme
if new_theme:
get_tree().root.theme = new_theme
theme_changed.emit(new_theme)
else:
push_error("Failed to load theme: %s" % theme_path)
func _update_scale() -> void:
var window = get_window()
var current_res = window.size
# Calculate scale based on width ratio (or height, depending on preference)
var scale_factor = float(current_res.x) / float(base_resolution.x)
scale_factor = clampf(scale_factor, min_scale, max_scale)
if not is_equal_approx(scale_factor, _current_scale):
_current_scale = scale_factor
_apply_scale(scale_factor)
scale_changed.emit(scale_factor)
func _apply_scale(scale_factor: float) -> void:
# Method 1: Content Scale Factor (Godot 4 native)
get_window().content_scale_factor = scale_factor
# Method 2: Manual Control scaling (if not using Stretch Mode: Canvas Items)
# This usually iterates over root UI nodes if you need manual control
# var root_control = get_tree().current_scene.get_node_or_null("UI")
# if root_control:
# root_control.scale = Vector2.ONE * scale_factor
## EXPERT USAGE:
## Autoload this script as 'UIManager'.
## UIManager.set_theme("res://themes/dark_mode.tres")
## Connect to scale_changed for custom widget adjustments.
Related skills
Lark Openapi ExplorerInstantly explore, test, and generate calls against the full Lark (Feishu) OpenAPI surface without leaving their agent workflow.493k
Lark EventConsume real-time events from Lark/Feishu as structured NDJSON streams inside AI agent workflows.387k16kLark Openapi ExplorerWhen an existing Lark/Feishu skill or CLI command cannot fulfill a specific requirement and they need to discover and invoke the exact native OpenAPI endpoint.386k16k
Just ScrapeQuickly search, crawl, extract structured JSON, or monitor web pages without writing custom scraping code.245k41Lark AppsQuery the current visibility and permission scope of a Lark (Feishu) app without writing HTTP client code.235k16k
Design An InterfaceGenerate multiple radically different interface or API designs in parallel before committing to one.188k198kHow it compares
Use godot-ui-theming for Theme-resource-based UI skinning; use godot-theme-easter in the same repo for seasonal StyleBox juice effects.
FAQ
How many GDScript scripts does godot-ui-theming include?
godot-ui-theming bundles 12 GDScript reference scripts including global_theme_manager.gd, theme_swapper.gd, ui_scale_manager.gd, crisp_ui_scaler.gd, and rtl_theme_mirroring.gd for Godot 4.x Theme resource workflows.
What theming mistakes does godot-ui-theming warn against?
godot-ui-theming lists 11 NEVER rules, including creating StyleBox per node in _ready(), skipping theme inheritance, hardcoding colors, using add_theme_override for global styles, and defining StyleBoxes inside _draw() or _process() loops.