| name | godot-ui-system |
| description | Design system and UI construction patterns for Godot 4.x games. Covers global themes, color palettes, shaders, HUD bar composition, tween animations, button styling, and workflows for building new UI screens that stay visually consistent. |
Godot UI Design System
Canonical reference for UI construction in Godot 4.x game projects. Every UI scene should follow this system to maintain visual consistency.
When to Use This Skill
Use this skill when:
- Creating any new UI scene (menus, overlays, popups, HUDs)
- Modifying existing UI elements (buttons, panels, labels)
- Adding new HUD sections to the game bar
- Building shop, upgrade, stats, or settings screens
- Styling tooltips, dialogs, or notifications
- Implementing tween entrance/hover/press animations
- Creating or modifying shaders for UI backgrounds
Do NOT use this skill when:
- Working on non-UI gameplay code (enemies, turrets, bullets)
- Editing TileMap or navigation meshes
- Writing autoload/singleton logic unrelated to display
NEVER Do
- NEVER use inline StyleBox overrides when the global theme already covers the control type. Use
nexus_theme.tres.
- NEVER use bright opaque backgrounds on panels. The system is translucent dark glass.
- NEVER hardcode font references per-label. The project-wide theme sets
LuckiestGuy-Regular.ttf.
- NEVER skip hover/press states on interactive elements. Every button needs all four states.
- NEVER use
Color(1,1,1,1) white for text. Use the palette cool-white Color(0.82, 0.88, 0.96, 1).
Color Palette
All colors derive from this core palette. Use these exact values:
| Token | Value | Usage |
|---|
bg_deep | Color(0.04, 0.06, 0.14, 0.92) | Panel backgrounds, HUD bar |
bg_accent | Color(0.06, 0.1, 0.2, 0.85) | Accent panels, containers |
bg_button | Color(0.05, 0.12, 0.22, 0.85) | Button normal state |
bg_button_hover | Color(0.08, 0.22, 0.4, 0.95) | Button hover state |
bg_button_press | Color(0.03, 0.08, 0.18, 0.95) | Button pressed state |
border_blue | Color(0.12, 0.45, 0.75, 0.6) | Primary accent borders |
border_glow | Color(0.2, 0.6, 1.0, 0.7) | Hover glow borders |
border_gold | Color(1.0, 0.85, 0.3, 0.6) | Focus/gold accent borders |
text_primary | Color(0.82, 0.88, 0.96, 1) | Default label text |
text_gold | Color(1.0, 0.9, 0.35, 1) | Gold/currency text |
text_subtitle | Color(0.55, 0.75, 0.95, 0.8) | Subtitles, secondary info |
text_muted | Color(0.4, 0.55, 0.7, 0.5) | Version labels, footnotes |
health_green | Color(0.26, 0.78, 0.14, 1) | Health bar fill |
shadow_dark | Color(0.0, 0.0, 0.0, 0.5) | Text drop shadows |
GDScript Helper
When setting colors in code, reference the palette:
# Correct — uses palette token
label.add_theme_color_override("font_color", Color(1.0, 0.9, 0.35, 1)) # text_gold
# Wrong — arbitrary color
label.add_theme_color_override("font_color", Color(1, 1, 0, 1)) # too saturated
Theme File
Path: res://Assets/UI/nexus_theme.tres
Scope: Set as project-wide theme in project.godot → [gui] theme/custom
Covered Controls
| Control | States / Properties |
|---|
| Button | normal, hover, pressed, focus, disabled + font colors |
| Panel | Dark translucent with blue top-accent |
| PanelContainer | Rounded accent variant |
| Label | Cool-white text with drop shadow |
| HSlider | Dark track, blue fill |
| Tooltip | Dark panel, blue border, padded |
Extending the Theme
To add a new control type to the theme:
- Edit
Assets/UI/nexus_theme.tres in the Godot editor
- Add sub_resource StyleBoxFlat following the palette
- Register under
[resource] with the control type path
- Prefer extending the
.tres over creating per-scene overrides
Per-Scene Theme Overrides
When a specific screen needs variation (e.g., turret build buttons), create a [sub_resource type="Theme"] inside the .tscn that only overrides the needed states:
[sub_resource type="Theme" id="Theme_turret_btn"]
Button/styles/normal = SubResource("StyleBoxFlat_turret_btn_normal")
Button/styles/hover = SubResource("StyleBoxFlat_turret_btn_hover")
Button/styles/pressed = SubResource("StyleBoxFlat_turret_btn_pressed")
Assign via theme = SubResource("Theme_turret_btn") on the container node.
Background Shader: Hex Grid
Path: res://Assets/Shaders/hex_grid_bg.gdshader
Type: canvas_item overlay shader (outputs alpha-transparent pixels)
Uniforms
| Uniform | Default | Purpose |
|---|
hex_color | blue | Color of hex edge lines |
glow_color | cyan | Cell interior pulse + scan line color |
hex_scale | 18.0 | Grid density (higher = smaller hexes) |
line_width | 0.04 | Hex border thickness |
pulse_speed | 0.6 | Diagonal wave animation speed |
scan_speed | 0.15 | Horizontal scan line speed |
vignette_strength | 0.6 | Edge darkening intensity |
overlay_darken | 0.45 | How much to dim underlying art (0–1) |
Usage Pattern
Layer the shader over background art:
Scene Tree:
├─ ArtBG (TextureRect) ← Your background image, stretch fill
├─ ShaderBG (ColorRect) ← hex_grid_bg.gdshader material
└─ ContentMargin (MarginContainer) ← UI content on top
The shader is transparent where there's no hex geometry, so the art shows through. Adjust overlay_darken to control mood.
Hooks & Workflows
Hook 1: New Menu Screen
When creating a new full-screen menu (settings, credits, etc.):
1. Create scene: Scenes/UIScenes/{ScreenName}.tscn
2. Root node: Control (anchors_preset=15, full rect)
3. Background layers:
a. ArtBG (TextureRect) — optional background art
b. ShaderBG (ColorRect) — hex_grid_bg.gdshader at overlay_darken=0.45
OR
b. ColorRect with bg_deep color if no shader needed
4. ContentMargin (MarginContainer, 60-100px margins)
5. Layout (VBoxContainer) inside margin
6. Assign nexus_theme.tres via theme= on root or inherit from project
7. Add entrance tween animation (see Hook 5)
8. Wire SFX: click_2.mp3 (press), click_1.mp3 (hover)
Hook 2: New HUD Element
When adding a section to the game HUD bar:
1. Open Scenes/MainScenes/GameScene.tscn
2. Add node inside InfoBox/H (HBoxContainer)
3. For icons: TextureRect, 32-60px, size_flags_vertical=4
4. For labels: Label with theme font, size 28-36
5. For buttons: Button (NOT TextureButton), apply turret_btn theme
6. For reactive data: create script in Scenes/MainScenes/Labels/
- Watch Kore.store key via Kore.store.watch()
- Update text in callback
7. Gold text uses text_gold color, other text uses text_primary
Hook 3: New Popup/Overlay
When creating a modal overlay (item drop, shop, upgrade):
1. Root: Control (full rect, anchors_preset=15)
2. Dimmer: ColorRect color=Color(0.0, 0.0, 0.02, 0.6)
3. Panel: PanelContainer (centered, custom_minimum_size)
- Will auto-style via nexus_theme.tres PanelContainer style
4. Content inside VBoxContainer with 16-24px separation
5. Title: Label, font_size=36, text_gold color
6. Body: Labels at font_size=24, text_primary color
7. Buttons: HBoxContainer at bottom, 16px separation
8. Entrance: scale from 0.8→1.0, fade alpha 0→1, 0.25s, TRANS_BACK
9. Exit: fade out 0.15s, then queue_free()
Hook 4: Button Styling
When adding any clickable button:
Decision tree:
├─ Is it in a menu? → Use nexus_theme.tres Button styles (automatic)
├─ Is it in the HUD build bar? → Use Theme_turret_btn sub_resource
├─ Is it a small icon toggle? → Use TextureButton (pause, mute, FF)
└─ Is it a large action button? → Use Button + theme + font override
All Button nodes must have:
- custom_minimum_size (at least width 100, height 48)
- theme_override_fonts/font = LuckiestGuy-Regular.ttf
- theme_override_font_sizes/font_size = 28-38
For icon-inside-button:
- Add TextureRect child, anchors centered, 24-32px
- Button text = "" (empty), use icon only
- Or combine: icon left + text via HBoxContainer child
Hook 5: Tween Entrance Animations
Standard entrance pattern used across all menus:
## Standard entrance animation — copy this pattern for any new screen
func _play_entrance_animation() -> void:
# Title: slide down + fade in
title.modulate.a = 0.0
title.position.y -= 40.0
var tw := create_tween().set_ease(Tween.EASE_OUT).set_trans(Tween.TRANS_BACK)
tw.tween_property(title, "modulate:a", 1.0, 0.6)
tw.parallel().tween_property(title, "position:y", title.position.y + 40.0, 0.6)
# Buttons: stagger slide from left
var buttons := button_container.get_children()
for i: int in buttons.size():
var btn: Control = buttons[i]
btn.modulate.a = 0.0
btn.position.x -= 60.0
var btw := create_tween().set_ease(Tween.EASE_OUT).set_trans(Tween.TRANS_CUBIC)
btw.tween_property(btn, "modulate:a", 1.0, 0.4).set_delay(0.3 + 0.12 * i)
btw.parallel().tween_property(btn, "position:x", btn.position.x + 60.0, 0.5).set_delay(0.3 + 0.12 * i)
Hook 6: Button Hover/Press Feedback
Standard interaction feedback — apply to every button container:
## Wire these to every button in a container
func _setup_button_signals() -> void:
for btn: Button in container.get_children():
btn.mouse_entered.connect(_on_hover.bind(btn))
btn.mouse_exited.connect(_on_unhover.bind(btn))
btn.pressed.connect(_on_pressed.bind(btn))
func _on_hover(btn: Button) -> void:
sfx_hover.play()
var tw := create_tween().set_ease(Tween.EASE_OUT).set_trans(Tween.TRANS_ELASTIC)
tw.tween_property(btn, "scale", Vector2(1.05, 1.05), 0.25)
func _on_unhover(btn: Button) -> void:
var tw := create_tween().set_ease(Tween.EASE_OUT).set_trans(Tween.TRANS_CUBIC)
tw.tween_property(btn, "scale", Vector2.ONE, 0.2)
func _on_pressed(btn: Button) -> void:
sfx_click.play()
var tw := create_tween().set_ease(Tween.EASE_OUT).set_trans(Tween.TRANS_BACK)
tw.tween_property(btn, "scale", Vector2(0.92, 0.92), 0.08)
tw.tween_property(btn, "scale", Vector2.ONE, 0.15)
Hook 7: Reactive Label (Kore.store binding)
Pattern for labels that auto-update from game state:
extends Label
func _ready() -> void:
var kore := get_node_or_null("/root/Kore")
if kore:
Kore.store.watch(&"your_key", _on_value_changed)
_refresh()
func _on_value_changed(_val: Variant) -> void:
_refresh()
func _refresh() -> void:
text = str(GameData.YourField) + " suffix"
File Map
| File | Purpose |
|---|
Assets/UI/nexus_theme.tres | Global theme resource (project-wide) |
Assets/Shaders/hex_grid_bg.gdshader | Animated hex overlay shader |
Assets/Fonts/LuckiestGuy-Regular.ttf | Primary font |
Assets/Fonts/Kenney Future Narrow.ttf | Secondary font (small labels) |
Assets/Sounds/SFX/click_1.mp3 | Hover SFX |
Assets/Sounds/SFX/click_2.mp3 | Click/press SFX |
Scenes/UIScenes/MainMenu.tscn | Reference implementation (menu) |
Scenes/UIScenes/MainMenu.gd | Reference implementation (animations) |
Scenes/MainScenes/GameScene.tscn | Reference implementation (HUD bar) |
Quick Reference
| Category | Prefer | Avoid |
|---|
| Panel BG | nexus_theme.tres Panel style | Bright/opaque StyleBoxFlat |
| Button | Button + theme | TextureButton for text buttons |
| Font | Project-wide LuckiestGuy-Regular | Per-node font loading |
| Text color | Palette tokens above | Pure white, saturated yellow |
| Corners | 6-8px radius | Sharp corners or >15px |
| Borders | 1-3px, blue palette | Thick white/gray borders |
| Shadows | 2-6px, dark/transparent | Large or colorful shadows |
| Transparency | 0.85-0.95 alpha on panels | Fully opaque panels |
| Animation | Tween, 0.15-0.6s, EASE_OUT | No animation or >1s duration |
| SFX | click_1.mp3 hover, click_2.mp3 press | Silent interactions |
| Screen BG | Art + hex shader overlay | Flat solid color |
