diff --git a/modules/utils.lua b/modules/utils.lua
index c47b124..1e97751 100644
--- a/modules/utils.lua
+++ b/modules/utils.lua
@@ -1,5 +1,5 @@
 ---@class ElementProps
----@field id string?
+---@field id string? -- Unique identifier for the element (auto-generated in immediate mode if not provided)
 ---@field parent Element? -- Parent element for hierarchical structure
 ---@field x number|string? -- X coordinate of the element (default: 0)
 ---@field y number|string? -- Y coordinate of the element (default: 0)
@@ -12,27 +12,26 @@
 ---@field left number|string? -- Offset from left edge (CSS-style positioning)
 ---@field border Border? -- Border configuration for the element
 ---@field borderColor Color? -- Color of the border (default: black)
----@field opacity number?
+---@field opacity number? -- Element opacity 0-1 (default: 1)
 ---@field backgroundColor Color? -- Background color (default: transparent)
 ---@field cornerRadius number|{topLeft:number?, topRight:number?, bottomLeft:number?, bottomRight:number?}? -- Corner radius: number (all corners) or table for individual corners (default: 0)
----@field gap number|string? -- Space between children elements (default: 10)
----@field padding {top:number|string?, right:number|string?, bottom:number|string?, left:number|string?, horizontal: number|string?, vertical:number|string?}? -- Padding around children (default: {top=0, right=0, bottom=0, left=0})
----@field margin {top:number|string?, right:number|string?, bottom:number|string?, left:number|string?, horizontal: number|string?, vertical:number|string?}? -- Margin around children (default: {top=0, right=0, bottom=0, left=0})
+---@field gap number|string? -- Space between children elements (default: 0)
+---@field padding {top:number|string?, right:number|string?, bottom:number|string?, left:number|string?, horizontal:number|string?, vertical:number|string?}? -- Padding around children (default: {top=0, right=0, bottom=0, left=0})
+---@field margin {top:number|string?, right:number|string?, bottom:number|string?, left:number|string?, horizontal:number|string?, vertical:number|string?}? -- Margin around element (default: {top=0, right=0, bottom=0, left=0})
 ---@field text string? -- Text content to display (default: nil)
----@field titleColor Color? -- Color of the text content (default: black)
 ---@field textAlign TextAlign? -- Alignment of the text content (default: START)
----@field textColor Color? -- Color of the text content (default: black)
----@field textSize number|string? -- Font size: number (px), string with units ("2vh", "10%"), or preset ("xxs"|"xs"|"sm"|"md"|"lg"|"xl"|"xxl"|"3xl"|"4xl") (default: "md")
----@field minTextSize number?
----@field maxTextSize number?
----@field fontFamily string? -- Font family name from theme or path to font file (default: theme default or system default)
+---@field textColor Color? -- Color of the text content (default: black or theme text color)
+---@field textSize number|string? -- Font size: number (px), string with units ("2vh", "10%"), or preset ("xxs"|"xs"|"sm"|"md"|"lg"|"xl"|"xxl"|"3xl"|"4xl") (default: "md" or 12px)
+---@field minTextSize number? -- Minimum text size in pixels for auto-scaling
+---@field maxTextSize number? -- Maximum text size in pixels for auto-scaling
+---@field fontFamily string? -- Font family name from theme or path to font file (default: theme default or system default, inherits from parent)
 ---@field autoScaleText boolean? -- Whether text should auto-scale with window size (default: true)
----@field positioning Positioning? -- Layout positioning mode (default: RELATIVE)
----@field flexDirection FlexDirection? -- Direction of flex layout (default: HORIZONTAL)
+---@field positioning Positioning? -- Layout positioning mode: "absolute"|"relative"|"flex"|"grid" (default: RELATIVE)
+---@field flexDirection FlexDirection? -- Direction of flex layout: "horizontal"|"vertical" (default: HORIZONTAL)
 ---@field justifyContent JustifyContent? -- Alignment of items along main axis (default: FLEX_START)
 ---@field alignItems AlignItems? -- Alignment of items along cross axis (default: STRETCH)
 ---@field alignContent AlignContent? -- Alignment of lines in multi-line flex containers (default: STRETCH)
----@field flexWrap FlexWrap? -- Whether children wrap to multiple lines (default: NOWRAP)
+---@field flexWrap FlexWrap? -- Whether children wrap to multiple lines: "nowrap"|"wrap"|"wrap-reverse" (default: NOWRAP)
 ---@field justifySelf JustifySelf? -- Alignment of the item itself along main axis (default: AUTO)
 ---@field alignSelf AlignSelf? -- Alignment of the item itself along cross axis (default: AUTO)
 ---@field callback fun(element:Element, event:InputEvent)? -- Callback function for interaction events
@@ -41,18 +40,18 @@
 ---@field onTextInput fun(element:Element, text:string)? -- Callback when text is input
 ---@field onTextChange fun(element:Element, text:string)? -- Callback when text content changes
 ---@field onEnter fun(element:Element)? -- Callback when Enter key is pressed
----@field transform table? -- Transform properties for animations and styling
----@field transition table? -- Transition settings for animations
+---@field transform TransformProps? -- Transform properties for animations and styling
+---@field transition TransitionProps? -- Transition settings for animations
 ---@field gridRows number? -- Number of rows in the grid (default: 1)
 ---@field gridColumns number? -- Number of columns in the grid (default: 1)
----@field columnGap number|string? -- Gap between grid columns
----@field rowGap number|string? -- Gap between grid rows
----@field theme string? -- Theme name to use (e.g., "space", "dark"). Defaults to theme from Gui.init()
+---@field columnGap number|string? -- Gap between grid columns (default: 0)
+---@field rowGap number|string? -- Gap between grid rows (default: 0)
+---@field theme string? -- Theme name to use (e.g., "space", "metal"). Defaults to theme from Gui.init()
 ---@field themeComponent string? -- Theme component to use (e.g., "panel", "button", "input"). If nil, no theme is applied
 ---@field disabled boolean? -- Whether the element is disabled (default: false)
 ---@field active boolean? -- Whether the element is active/focused (for inputs, default: false)
----@field disableHighlight boolean? -- Whether to disable the pressed state highlight overlay (default: false)
----@field contentAutoSizingMultiplier {width:number?, height:number?}? -- Multiplier for auto-sized content dimensions (default: sourced from theme)
+---@field disableHighlight boolean? -- Whether to disable the pressed state highlight overlay (default: false, or true when using themeComponent)
+---@field contentAutoSizingMultiplier {width:number?, height:number?}? -- Multiplier for auto-sized content dimensions (default: sourced from theme or {1, 1})
 ---@field scaleCorners number? -- Scale multiplier for 9-patch corners/edges. E.g., 2 = 2x size (overrides theme setting)
 ---@field scalingAlgorithm "nearest"|"bilinear"? -- Scaling algorithm for 9-patch corners: "nearest" (sharp/pixelated) or "bilinear" (smooth) (overrides theme setting)
 ---@field contentBlur {intensity:number, quality:number}? -- Blur the element's content including children (intensity: 0-100, quality: 1-10, default: nil)
@@ -63,11 +62,11 @@
 ---@field maxLines number? -- Maximum number of lines (default: nil)
 ---@field maxLength number? -- Maximum text length in characters (default: nil)
 ---@field placeholder string? -- Placeholder text when empty (default: nil)
----@field passwordMode boolean? -- Whether to display text as password (default: false)
+---@field passwordMode boolean? -- Whether to display text as password (default: false, disables multiline)
 ---@field inputType "text"|"number"|"email"|"url"? -- Input type for validation (default: "text")
 ---@field textOverflow "clip"|"ellipsis"|"scroll"? -- Text overflow behavior (default: "clip")
 ---@field scrollable boolean? -- Whether text is scrollable (default: false for single-line, true for multi-line)
----@field autoGrow boolean? -- Whether element auto-grows with text (default: false)
+---@field autoGrow boolean? -- Whether element auto-grows with text (default: false for single-line, true for multi-line)
 ---@field selectOnFocus boolean? -- Whether to select all text on focus (default: false)
 ---@field cursorColor Color? -- Cursor color (default: nil, uses textColor)
 ---@field selectionColor Color? -- Selection background color (default: nil, uses theme or default)
@@ -76,18 +75,20 @@
 ---@field overflowX "visible"|"hidden"|"scroll"|"auto"? -- X-axis overflow (overrides overflow)
 ---@field overflowY "visible"|"hidden"|"scroll"|"auto"? -- Y-axis overflow (overrides overflow)
 ---@field scrollbarWidth number? -- Width of scrollbar track in pixels (default: 12)
----@field scrollbarColor Color? -- Scrollbar thumb color
----@field scrollbarTrackColor Color? -- Scrollbar track color
+---@field scrollbarColor Color? -- Scrollbar thumb color (default: Color.new(0.5, 0.5, 0.5, 0.8))
+---@field scrollbarTrackColor Color? -- Scrollbar track color (default: Color.new(0.2, 0.2, 0.2, 0.5))
 ---@field scrollbarRadius number? -- Corner radius for scrollbar (default: 6)
 ---@field scrollbarPadding number? -- Padding between scrollbar and edge (default: 2)
 ---@field scrollSpeed number? -- Pixels per wheel notch (default: 20)
----@field hideScrollbars boolean|{vertical:boolean, horizontal:boolean}? -- Hide scrollbars (boolean for both, or table for individual control)
+---@field hideScrollbars boolean|{vertical:boolean, horizontal:boolean}? -- Hide scrollbars (boolean for both, or table for individual control, default: false)
 ---@field imagePath string? -- Path to image file (auto-loads via ImageCache)
 ---@field image love.Image? -- Image object to display
 ---@field objectFit "fill"|"contain"|"cover"|"scale-down"|"none"? -- Image fit mode (default: "fill")
 ---@field objectPosition string? -- Image position like "center center", "top left", "50% 50%" (default: "center center")
 ---@field imageOpacity number? -- Image opacity 0-1 (default: 1, combines with element opacity)
----@field userdata table? -- put whatever here
+---@field _scrollX number? -- Internal: scroll X position (restored in immediate mode)
+---@field _scrollY number? -- Internal: scroll Y position (restored in immediate mode)
+---@field userdata table? -- User-defined data storage for custom properties
 local ElementProps = {}
 
 ---@class Border