godot-ui-system

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:

1. Edit Assets/UI/nexus_theme.tres in the Godot editor
2. Add sub_resource StyleBoxFlat following the palette
3. Register under [resource] with the control type path
4. 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