From a0cea8081b762e1b0a3a0e20ba358bea969f0a09 Mon Sep 17 00:00:00 2001
From: Michael Freno <michaelt.freno@gmail.com>
Date: Mon, 13 Oct 2025 09:44:33 -0400
Subject: [PATCH] layering

---
 FlexLove.lua                                  |  92 ++++----
 examples/AutoScalingWithExplicitSize.lua      |   2 +-
 examples/EventSystemDemo.lua                  |  16 +-
 examples/OnClickAnimations.lua                |   6 +-
 examples/SimpleGrid.lua                       |  30 +--
 examples/TextAutoScaling.lua                  |   2 +-
 examples/TextSizePresets.lua                  |   2 +-
 examples/ThemeLayeringDemo.lua                | 196 ++++++++++++++++++
 examples/ThemeSystemDemo.lua                  |  34 +--
 examples/ZIndexDemo.lua                       |  26 +--
 .../01_absolute_positioning_basic_tests.lua   |   2 +-
 .../13_relative_positioning_tests.lua         |  28 +--
 12 files changed, 313 insertions(+), 123 deletions(-)
 create mode 100644 examples/ThemeLayeringDemo.lua

diff --git a/FlexLove.lua b/FlexLove.lua
index 1a13f84..dd9c50e 100644
--- a/FlexLove.lua
+++ b/FlexLove.lua
@@ -1082,7 +1082,7 @@ end
 ---@field border Border -- Border configuration for the element
 ---@field opacity number
 ---@field borderColor Color -- Color of the border
----@field background Color -- Background color of the element
+---@field backgroundColor Color -- Background color of the element
 ---@field prevGameSize {width:number, height:number} -- Previous game size for resize calculations
 ---@field text string? -- Text content to display in the element
 ---@field textColor Color -- Color of the text content
@@ -1135,7 +1135,7 @@ Element.__index = Element
 ---@field border Border? -- Border configuration for the element
 ---@field borderColor Color? -- Color of the border (default: black)
 ---@field opacity number?
----@field background Color? -- Background color (default: transparent)
+---@field backgroundColor Color? -- Background color (default: transparent)
 ---@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})
@@ -1214,7 +1214,7 @@ function Element.new(props)
       left = false,
     }
   self.borderColor = props.borderColor or Color.new(0, 0, 0, 1)
-  self.background = props.background or Color.new(0, 0, 0, 0)
+  self.backgroundColor = props.backgroundColor or Color.new(0, 0, 0, 0)
   self.opacity = props.opacity or 1
 
   self.text = props.text
@@ -2152,16 +2152,29 @@ end
 --- Draw element and its children
 function Element:draw()
   -- Handle opacity during animation
-  local drawBackground = self.background
+  local drawBackgroundColor = self.backgroundColor
   if self.animation then
     local anim = self.animation:interpolate()
     if anim.opacity then
-      drawBackground = Color.new(self.background.r, self.background.g, self.background.b, anim.opacity)
+      drawBackgroundColor = Color.new(self.backgroundColor.r, self.backgroundColor.g, self.backgroundColor.b, anim.opacity)
     end
   end
 
-  -- Check if element has a theme component
-  local hasTheme = false
+  -- LAYER 1: Draw backgroundColor first (behind everything)
+  -- Apply opacity to all drawing operations
+  -- (x, y) represents border box, so draw background from (x, y)
+  local backgroundWithOpacity =
+    Color.new(drawBackgroundColor.r, drawBackgroundColor.g, drawBackgroundColor.b, drawBackgroundColor.a * self.opacity)
+  love.graphics.setColor(backgroundWithOpacity:toRGBA())
+  love.graphics.rectangle(
+    "fill",
+    self.x,
+    self.y,
+    self.width + self.padding.left + self.padding.right,
+    self.height + self.padding.top + self.padding.bottom
+  )
+
+  -- LAYER 2: Draw theme on top of backgroundColor (if theme exists)
   if self.themeComponent then
     -- Get the theme to use
     local themeToUse = nil
@@ -2204,7 +2217,6 @@ function Element:draw()
             self.height + self.padding.top + self.padding.bottom,
             self.opacity
           )
-          hasTheme = true
         else
           print("[FlexLove] No atlas for component: " .. self.themeComponent)
         end
@@ -2216,49 +2228,31 @@ function Element:draw()
     end
   end
 
-  -- Draw background if no theme is used
-  if not hasTheme then
-    -- Apply opacity to all drawing operations
-    -- (x, y) represents border box, so draw background from (x, y)
-    local backgroundWithOpacity =
-      Color.new(drawBackground.r, drawBackground.g, drawBackground.b, drawBackground.a * self.opacity)
-    love.graphics.setColor(backgroundWithOpacity:toRGBA())
-    love.graphics.rectangle(
-      "fill",
+  -- LAYER 3: Draw borders on top of theme (always render if specified)
+  local borderColorWithOpacity =
+    Color.new(self.borderColor.r, self.borderColor.g, self.borderColor.b, self.borderColor.a * self.opacity)
+  love.graphics.setColor(borderColorWithOpacity:toRGBA())
+  if self.border.top then
+    love.graphics.line(self.x, self.y, self.x + self.width + self.padding.left + self.padding.right, self.y)
+  end
+  if self.border.bottom then
+    love.graphics.line(
       self.x,
-      self.y,
-      self.width + self.padding.left + self.padding.right,
-      self.height + self.padding.top + self.padding.bottom
+      self.y + self.height + self.padding.top + self.padding.bottom,
+      self.x + self.width + self.padding.left + self.padding.right,
+      self.y + self.height + self.padding.top + self.padding.bottom
     )
   end
-
-  -- Draw borders based on border property (skip if using theme)
-  if not hasTheme then
-    local borderColorWithOpacity =
-      Color.new(self.borderColor.r, self.borderColor.g, self.borderColor.b, self.borderColor.a * self.opacity)
-    love.graphics.setColor(borderColorWithOpacity:toRGBA())
-    if self.border.top then
-      love.graphics.line(self.x, self.y, self.x + self.width + self.padding.left + self.padding.right, self.y)
-    end
-    if self.border.bottom then
-      love.graphics.line(
-        self.x,
-        self.y + self.height + self.padding.top + self.padding.bottom,
-        self.x + self.width + self.padding.left + self.padding.right,
-        self.y + self.height + self.padding.top + self.padding.bottom
-      )
-    end
-    if self.border.left then
-      love.graphics.line(self.x, self.y, self.x, self.y + self.height + self.padding.top + self.padding.bottom)
-    end
-    if self.border.right then
-      love.graphics.line(
-        self.x + self.width + self.padding.left + self.padding.right,
-        self.y,
-        self.x + self.width + self.padding.left + self.padding.right,
-        self.y + self.height + self.padding.top + self.padding.bottom
-      )
-    end
+  if self.border.left then
+    love.graphics.line(self.x, self.y, self.x, self.y + self.height + self.padding.top + self.padding.bottom)
+  end
+  if self.border.right then
+    love.graphics.line(
+      self.x + self.width + self.padding.left + self.padding.right,
+      self.y,
+      self.x + self.width + self.padding.left + self.padding.right,
+      self.y + self.height + self.padding.top + self.padding.bottom
+    )
   end
 
   -- Draw element text if present
@@ -2356,7 +2350,7 @@ function Element:update(dt)
       self.opacity = anim.opacity or self.opacity
       -- Update background color with interpolated opacity
       if anim.opacity then
-        self.background.a = anim.opacity
+        self.backgroundColor.a = anim.opacity
       end
     end
   end
diff --git a/examples/AutoScalingWithExplicitSize.lua b/examples/AutoScalingWithExplicitSize.lua
index a341072..0872230 100644
--- a/examples/AutoScalingWithExplicitSize.lua
+++ b/examples/AutoScalingWithExplicitSize.lua
@@ -70,7 +70,7 @@ local pauseMenu = Gui.new({
   flexDirection = "vertical",
   justifyContent = "center",
   alignItems = "center",
-  background = Color.new(0.1, 0.1, 0.1, 0.9),
+  backgroundColor = Color.new(0.1, 0.1, 0.1, 0.9),
 })
 
 local title = Gui.new({
diff --git a/examples/EventSystemDemo.lua b/examples/EventSystemDemo.lua
index 82d6bf0..f934143 100644
--- a/examples/EventSystemDemo.lua
+++ b/examples/EventSystemDemo.lua
@@ -19,7 +19,7 @@ function EventSystemDemo.init()
     y = 50,
     width = 700,
     height = 500,
-    background = Color.new(0.15, 0.15, 0.2, 0.95),
+    backgroundColor = Color.new(0.15, 0.15, 0.2, 0.95),
     border = { top = true, bottom = true, left = true, right = true },
     borderColor = Color.new(0.8, 0.8, 0.8, 1),
     positioning = "flex",
@@ -36,7 +36,7 @@ function EventSystemDemo.init()
     textSize = 18,
     textAlign = "center",
     textColor = Color.new(1, 1, 1, 1),
-    background = Color.new(0.2, 0.2, 0.3, 1),
+    backgroundColor = Color.new(0.2, 0.2, 0.3, 1),
   })
 
   -- Button container
@@ -46,7 +46,7 @@ function EventSystemDemo.init()
     positioning = "flex",
     flexDirection = "horizontal",
     gap = 15,
-    background = Color.new(0.1, 0.1, 0.15, 0.5),
+    backgroundColor = Color.new(0.1, 0.1, 0.15, 0.5),
     padding = { top = 15, right = 15, bottom = 15, left = 15 },
   })
 
@@ -67,7 +67,7 @@ function EventSystemDemo.init()
     text = "Left Click Me",
     textAlign = "center",
     textColor = Color.new(1, 1, 1, 1),
-    background = Color.new(0.2, 0.6, 0.9, 0.8),
+    backgroundColor = Color.new(0.2, 0.6, 0.9, 0.8),
     border = { top = true, bottom = true, left = true, right = true },
     borderColor = Color.new(0.4, 0.8, 1, 1),
     callback = function(element, event)
@@ -85,7 +85,7 @@ function EventSystemDemo.init()
     text = "Right Click Me",
     textAlign = "center",
     textColor = Color.new(1, 1, 1, 1),
-    background = Color.new(0.9, 0.4, 0.4, 0.8),
+    backgroundColor = Color.new(0.9, 0.4, 0.4, 0.8),
     border = { top = true, bottom = true, left = true, right = true },
     borderColor = Color.new(1, 0.6, 0.6, 1),
     callback = function(element, event)
@@ -105,7 +105,7 @@ function EventSystemDemo.init()
     text = "Try Shift/Ctrl",
     textAlign = "center",
     textColor = Color.new(1, 1, 1, 1),
-    background = Color.new(0.6, 0.9, 0.4, 0.8),
+    backgroundColor = Color.new(0.6, 0.9, 0.4, 0.8),
     border = { top = true, bottom = true, left = true, right = true },
     borderColor = Color.new(0.8, 1, 0.6, 1),
     callback = function(element, event)
@@ -133,7 +133,7 @@ function EventSystemDemo.init()
     text = "All Events",
     textAlign = "center",
     textColor = Color.new(1, 1, 1, 1),
-    background = Color.new(0.9, 0.7, 0.3, 0.8),
+    backgroundColor = Color.new(0.9, 0.7, 0.3, 0.8),
     border = { top = true, bottom = true, left = true, right = true },
     borderColor = Color.new(1, 0.9, 0.5, 1),
     callback = function(element, event)
@@ -151,7 +151,7 @@ function EventSystemDemo.init()
     textSize = 14,
     textAlign = "start",
     textColor = Color.new(0.9, 0.9, 1, 1),
-    background = Color.new(0.05, 0.05, 0.1, 1),
+    backgroundColor = Color.new(0.05, 0.05, 0.1, 1),
     border = { top = true, bottom = true, left = true, right = true },
     borderColor = Color.new(0.3, 0.3, 0.4, 1),
     padding = { top = 10, right = 10, bottom = 10, left = 10 },
diff --git a/examples/OnClickAnimations.lua b/examples/OnClickAnimations.lua
index e9e6a4c..f0ae5b0 100644
--- a/examples/OnClickAnimations.lua
+++ b/examples/OnClickAnimations.lua
@@ -20,7 +20,7 @@ function OnClickAnimDemo.init()
     z = 10,
     w = 300,
     h = 200,
-    background = Color.new(0.1, 0.1, 0.3, 0.8),
+    backgroundColor = Color.new(0.1, 0.1, 0.3, 0.8),
     border = { top = true, bottom = true, left = true, right = true },
     borderColor = Color.new(0.7, 0.7, 0.7, 1),
   })
@@ -33,7 +33,7 @@ function OnClickAnimDemo.init()
     w = 100,
     h = 40,
     text = "Fade",
-    background = Color.new(0.2, 0.9, 0.6, 0.8),
+    backgroundColor = Color.new(0.2, 0.9, 0.6, 0.8),
     textColor = Color.new(1, 1, 1),
     borderColor = Color.new(0.4, 1, 0.8, 1),
     callback = function()
@@ -51,7 +51,7 @@ function OnClickAnimDemo.init()
     w = 100,
     h = 40,
     text = "Scale",
-    background = Color.new(0.9, 0.6, 0.2, 0.8),
+    backgroundColor = Color.new(0.9, 0.6, 0.2, 0.8),
     textColor = Color.new(1, 1, 1),
     borderColor = Color.new(1, 0.8, 0.4, 1),
     callback = function()
diff --git a/examples/SimpleGrid.lua b/examples/SimpleGrid.lua
index aa8740b..74ff22a 100644
--- a/examples/SimpleGrid.lua
+++ b/examples/SimpleGrid.lua
@@ -24,7 +24,7 @@ local grid1 = Gui.new({
   gridColumns = 3,
   columnGap = 10,
   rowGap = 10,
-  background = Color.new(0.9, 0.9, 0.9, 1),
+  backgroundColor = Color.new(0.9, 0.9, 0.9, 1),
   padding = { horizontal = 20, vertical = 20 },
 })
 
@@ -32,7 +32,7 @@ local grid1 = Gui.new({
 for i = 1, 6 do
   Gui.new({
     parent = grid1,
-    background = Color.new(0.2, 0.5, 0.8, 1),
+    backgroundColor = Color.new(0.2, 0.5, 0.8, 1),
     text = "Item " .. i,
     textColor = Color.new(1, 1, 1, 1),
     textAlign = enums.TextAlign.CENTER,
@@ -58,14 +58,14 @@ local grid2 = Gui.new({
   gridColumns = 4,
   columnGap = 5,
   rowGap = 5,
-  background = Color.new(0.9, 0.9, 0.9, 1),
+  backgroundColor = Color.new(0.9, 0.9, 0.9, 1),
   padding = { horizontal = 10, vertical = 10 },
 })
 
 for i = 1, 16 do
   Gui.new({
     parent = grid2,
-    background = Color.new(0.3, 0.6, 0.3, 1),
+    backgroundColor = Color.new(0.3, 0.6, 0.3, 1),
     text = tostring(i),
     textColor = Color.new(1, 1, 1, 1),
     textAlign = enums.TextAlign.CENTER,
@@ -90,7 +90,7 @@ local grid3 = Gui.new({
   gridColumns = 5,
   columnGap = 10,
   rowGap = 0,
-  background = Color.new(0.9, 0.9, 0.9, 1),
+  backgroundColor = Color.new(0.9, 0.9, 0.9, 1),
   padding = { horizontal = 10, vertical = 10 },
 })
 
@@ -98,7 +98,7 @@ local labels = { "Home", "Products", "About", "Contact", "Login" }
 for i = 1, 5 do
   Gui.new({
     parent = grid3,
-    background = Color.new(0.3, 0.3, 0.8, 1),
+    backgroundColor = Color.new(0.3, 0.3, 0.8, 1),
     text = labels[i],
     textColor = Color.new(1, 1, 1, 1),
     textAlign = enums.TextAlign.CENTER,
@@ -122,14 +122,14 @@ local grid4 = Gui.new({
   gridColumns = 1,
   columnGap = 0,
   rowGap = 10,
-  background = Color.new(0.9, 0.9, 0.9, 1),
+  backgroundColor = Color.new(0.9, 0.9, 0.9, 1),
   padding = { horizontal = 10, vertical = 10 },
 })
 
 for i = 1, 5 do
   Gui.new({
     parent = grid4,
-    background = Color.new(0.5, 0.3, 0.7, 1),
+    backgroundColor = Color.new(0.5, 0.3, 0.7, 1),
     text = "Option " .. i,
     textColor = Color.new(1, 1, 1, 1),
     textAlign = enums.TextAlign.CENTER,
@@ -153,14 +153,14 @@ local outerGrid = Gui.new({
   gridColumns = 2,
   columnGap = 10,
   rowGap = 10,
-  background = Color.new(0.85, 0.85, 0.85, 1),
+  backgroundColor = Color.new(0.85, 0.85, 0.85, 1),
   padding = { horizontal = 10, vertical = 10 },
 })
 
 -- Top-left: Simple item
 Gui.new({
   parent = outerGrid,
-  background = Color.new(0.5, 0.3, 0.7, 1),
+  backgroundColor = Color.new(0.5, 0.3, 0.7, 1),
   text = "Single Item",
   textColor = Color.new(1, 1, 1, 1),
   textAlign = enums.TextAlign.CENTER,
@@ -174,14 +174,14 @@ local nestedGrid1 = Gui.new({
   gridColumns = 2,
   columnGap = 5,
   rowGap = 5,
-  background = Color.new(0.7, 0.7, 0.7, 1),
+  backgroundColor = Color.new(0.7, 0.7, 0.7, 1),
   padding = { horizontal = 5, vertical = 5 },
 })
 
 for i = 1, 4 do
   Gui.new({
     parent = nestedGrid1,
-    background = Color.new(0.3, 0.6, 0.9, 1),
+    backgroundColor = Color.new(0.3, 0.6, 0.9, 1),
     text = "A" .. i,
     textColor = Color.new(1, 1, 1, 1),
     textAlign = enums.TextAlign.CENTER,
@@ -196,14 +196,14 @@ local nestedGrid2 = Gui.new({
   gridColumns = 3,
   columnGap = 5,
   rowGap = 5,
-  background = Color.new(0.7, 0.7, 0.7, 1),
+  backgroundColor = Color.new(0.7, 0.7, 0.7, 1),
   padding = { horizontal = 5, vertical = 5 },
 })
 
 for i = 1, 3 do
   Gui.new({
     parent = nestedGrid2,
-    background = Color.new(0.9, 0.6, 0.3, 1),
+    backgroundColor = Color.new(0.9, 0.6, 0.3, 1),
     text = "B" .. i,
     textColor = Color.new(1, 1, 1, 1),
     textAlign = enums.TextAlign.CENTER,
@@ -213,7 +213,7 @@ end
 -- Bottom-right: Another simple item
 Gui.new({
   parent = outerGrid,
-  background = Color.new(0.3, 0.7, 0.5, 1),
+  backgroundColor = Color.new(0.3, 0.7, 0.5, 1),
   text = "Another Item",
   textColor = Color.new(1, 1, 1, 1),
   textAlign = enums.TextAlign.CENTER,
diff --git a/examples/TextAutoScaling.lua b/examples/TextAutoScaling.lua
index 345379b..453e069 100644
--- a/examples/TextAutoScaling.lua
+++ b/examples/TextAutoScaling.lua
@@ -95,7 +95,7 @@ local box = Gui.new({
   text = "Responsive Box",
   textSize = "10ew",
   textAlign = "center",
-  background = Color.new(0.2, 0.2, 0.2),
+  backgroundColor = Color.new(0.2, 0.2, 0.2),
   textColor = Color.new(1, 1, 1),
 })
 print("   Initial (width=200): textSize = " .. box.textSize .. "px")
diff --git a/examples/TextSizePresets.lua b/examples/TextSizePresets.lua
index 01f3fea..67f4736 100644
--- a/examples/TextSizePresets.lua
+++ b/examples/TextSizePresets.lua
@@ -73,7 +73,7 @@ local container = Gui.new({
   flexDirection = "vertical",
   gap = 10,
   padding = { horizontal = 20, vertical = 20 },
-  background = Color.new(0.1, 0.1, 0.1),
+  backgroundColor = Color.new(0.1, 0.1, 0.1),
 })
 
 local title = Gui.new({
diff --git a/examples/ThemeLayeringDemo.lua b/examples/ThemeLayeringDemo.lua
new file mode 100644
index 0000000..0e0ac78
--- /dev/null
+++ b/examples/ThemeLayeringDemo.lua
@@ -0,0 +1,196 @@
+-- Demo showing the new layering system:
+-- backgroundColor -> theme -> borders -> text
+
+local FlexLove = require("FlexLove")
+local Gui = FlexLove.GUI
+local Theme = FlexLove.Theme
+local Color = FlexLove.Color
+
+function love.load()
+  -- Initialize FlexLove with the space theme
+  Gui.init({
+    baseScale = { width = 1920, height = 1080 },
+    theme = "space"
+  })
+  
+  -- Create main container
+  local container = Gui.new({
+    x = 50,
+    y = 50,
+    width = 700,
+    height = 500,
+    backgroundColor = Color.new(0.1, 0.1, 0.15, 1),
+    border = { top = true, bottom = true, left = true, right = true },
+    borderColor = Color.new(0.5, 0.5, 0.6, 1),
+    positioning = "flex",
+    flexDirection = "vertical",
+    gap = 20,
+    padding = { top = 20, right = 20, bottom = 20, left = 20 },
+  })
+  
+  -- Title
+  Gui.new({
+    parent = container,
+    height = 40,
+    text = "Theme Layering Demo",
+    textSize = 24,
+    textAlign = "center",
+    textColor = Color.new(1, 1, 1, 1),
+    backgroundColor = Color.new(0.2, 0.2, 0.3, 1),
+  })
+  
+  -- Description
+  Gui.new({
+    parent = container,
+    height = 60,
+    text = "Layering order: backgroundColor -> theme -> borders -> text\nAll layers are always rendered when specified",
+    textSize = 14,
+    textAlign = "center",
+    textColor = Color.new(0.8, 0.9, 1, 1),
+    backgroundColor = Color.new(0.15, 0.15, 0.2, 0.8),
+    padding = { top = 10, right = 10, bottom = 10, left = 10 },
+  })
+  
+  -- Example 1: Theme with backgroundColor
+  local example1 = Gui.new({
+    parent = container,
+    height = 100,
+    positioning = "flex",
+    flexDirection = "vertical",
+    gap = 10,
+    backgroundColor = Color.new(0.12, 0.12, 0.17, 1),
+    padding = { top = 10, right = 10, bottom = 10, left = 10 },
+  })
+  
+  Gui.new({
+    parent = example1,
+    height = 20,
+    text = "Example 1: Theme with backgroundColor (red tint behind)",
+    textSize = 14,
+    textColor = Color.new(0.8, 0.9, 1, 1),
+    backgroundColor = Color.new(0, 0, 0, 0),
+  })
+  
+  Gui.new({
+    parent = example1,
+    width = 200,
+    height = 50,
+    text = "Themed Button",
+    textAlign = "center",
+    textColor = Color.new(1, 1, 1, 1),
+    backgroundColor = Color.new(0.8, 0.2, 0.2, 0.5), -- Red tint behind theme
+    themeComponent = "button",
+    callback = function(element, event)
+      if event.type == "click" then
+        print("Button with backgroundColor clicked!")
+      end
+    end
+  })
+  
+  -- Example 2: Theme with borders
+  local example2 = Gui.new({
+    parent = container,
+    height = 100,
+    positioning = "flex",
+    flexDirection = "vertical",
+    gap = 10,
+    backgroundColor = Color.new(0.12, 0.12, 0.17, 1),
+    padding = { top = 10, right = 10, bottom = 10, left = 10 },
+  })
+  
+  Gui.new({
+    parent = example2,
+    height = 20,
+    text = "Example 2: Theme with borders (yellow borders on top)",
+    textSize = 14,
+    textColor = Color.new(0.8, 0.9, 1, 1),
+    backgroundColor = Color.new(0, 0, 0, 0),
+  })
+  
+  Gui.new({
+    parent = example2,
+    width = 200,
+    height = 50,
+    text = "Bordered Button",
+    textAlign = "center",
+    textColor = Color.new(1, 1, 1, 1),
+    backgroundColor = Color.new(0.2, 0.2, 0.3, 0.5),
+    border = { top = true, bottom = true, left = true, right = true },
+    borderColor = Color.new(1, 1, 0, 1), -- Yellow border on top of theme
+    themeComponent = "button",
+    callback = function(element, event)
+      if event.type == "click" then
+        print("Button with borders clicked!")
+      end
+    end
+  })
+  
+  -- Example 3: Theme with both backgroundColor and borders
+  local example3 = Gui.new({
+    parent = container,
+    height = 120,
+    positioning = "flex",
+    flexDirection = "vertical",
+    gap = 10,
+    backgroundColor = Color.new(0.12, 0.12, 0.17, 1),
+    padding = { top = 10, right = 10, bottom = 10, left = 10 },
+  })
+  
+  Gui.new({
+    parent = example3,
+    height = 20,
+    text = "Example 3: Theme with backgroundColor AND borders",
+    textSize = 14,
+    textColor = Color.new(0.8, 0.9, 1, 1),
+    backgroundColor = Color.new(0, 0, 0, 0),
+  })
+  
+  Gui.new({
+    parent = example3,
+    width = 250,
+    height = 60,
+    text = "Full Layering",
+    textAlign = "center",
+    textColor = Color.new(1, 1, 1, 1),
+    backgroundColor = Color.new(0.2, 0.6, 0.8, 0.3), -- Blue tint behind
+    border = { top = true, bottom = true, left = true, right = true },
+    borderColor = Color.new(0, 1, 0, 1), -- Green border on top
+    themeComponent = "button",
+    callback = function(element, event)
+      if event.type == "click" then
+        print("Full layering button clicked!")
+      end
+    end
+  })
+  
+  -- Example 4: Panel with backgroundColor
+  Gui.new({
+    x = 800,
+    y = 50,
+    width = 300,
+    height = 200,
+    backgroundColor = Color.new(0.3, 0.1, 0.3, 0.5), -- Purple tint
+    border = { top = true, bottom = true, left = true, right = true },
+    borderColor = Color.new(1, 0.5, 0, 1), -- Orange border
+    themeComponent = "panel",
+    padding = { top = 20, right = 20, bottom = 20, left = 20 }
+  })
+end
+
+function love.update(dt)
+  Gui.update(dt)
+end
+
+function love.draw()
+  love.graphics.clear(0.05, 0.05, 0.1, 1)
+  Gui.draw()
+  
+  -- Draw instructions
+  love.graphics.setColor(1, 1, 1, 1)
+  love.graphics.print("Theme Layering System", 10, 10)
+  love.graphics.print("Hover over buttons to see state changes", 10, 30)
+end
+
+function love.resize(w, h)
+  Gui.resize()
+end
diff --git a/examples/ThemeSystemDemo.lua b/examples/ThemeSystemDemo.lua
index ed4fbe8..19ef47c 100644
--- a/examples/ThemeSystemDemo.lua
+++ b/examples/ThemeSystemDemo.lua
@@ -30,7 +30,7 @@ function ThemeDemo.init()
     y = 50,
     width = 700,
     height = 550,
-    background = Color.new(0.15, 0.15, 0.2, 0.95),
+    backgroundColor = Color.new(0.15, 0.15, 0.2, 0.95),
     border = { top = true, bottom = true, left = true, right = true },
     borderColor = Color.new(0.8, 0.8, 0.8, 1),
     positioning = "flex",
@@ -47,7 +47,7 @@ function ThemeDemo.init()
     textSize = 20,
     textAlign = "center",
     textColor = Color.new(1, 1, 1, 1),
-    background = Color.new(0.2, 0.2, 0.3, 1),
+    backgroundColor = Color.new(0.2, 0.2, 0.3, 1),
   })
 
   -- Status message
@@ -59,7 +59,7 @@ function ThemeDemo.init()
     textSize = 14,
     textAlign = "center",
     textColor = themeLoaded and Color.new(0.3, 0.9, 0.3, 1) or Color.new(0.9, 0.7, 0.3, 1),
-    background = Color.new(0.1, 0.1, 0.15, 0.8),
+    backgroundColor = Color.new(0.1, 0.1, 0.15, 0.8),
     padding = { top = 10, right = 10, bottom = 10, left = 10 },
   })
 
@@ -70,7 +70,7 @@ function ThemeDemo.init()
     positioning = "flex",
     flexDirection = "vertical",
     gap = 15,
-    background = Color.new(0.1, 0.1, 0.15, 0.5),
+    backgroundColor = Color.new(0.1, 0.1, 0.15, 0.5),
     padding = { top = 15, right = 15, bottom = 15, left = 15 },
   })
 
@@ -81,7 +81,7 @@ function ThemeDemo.init()
     positioning = "flex",
     flexDirection = "vertical",
     gap = 10,
-    background = Color.new(0.12, 0.12, 0.17, 1),
+    backgroundColor = Color.new(0.12, 0.12, 0.17, 1),
     padding = { top = 10, right = 10, bottom = 10, left = 10 },
   })
 
@@ -91,7 +91,7 @@ function ThemeDemo.init()
     text = "Example 1: Basic Themed Button",
     textSize = 14,
     textColor = Color.new(0.8, 0.9, 1, 1),
-    background = Color.new(0, 0, 0, 0),
+    backgroundColor = Color.new(0, 0, 0, 0),
   })
 
   -- This button would use theme if loaded
@@ -102,7 +102,7 @@ function ThemeDemo.init()
     text = "Themed Button",
     textAlign = "center",
     textColor = Color.new(1, 1, 1, 1),
-    background = Color.new(0.2, 0.6, 0.9, 0.8),
+    backgroundColor = Color.new(0.2, 0.6, 0.9, 0.8),
     -- theme = "button", -- Uncomment when theme atlas exists
     callback = function(element, event)
       if event.type == "click" then
@@ -118,7 +118,7 @@ function ThemeDemo.init()
     positioning = "flex",
     flexDirection = "vertical",
     gap = 10,
-    background = Color.new(0.12, 0.12, 0.17, 1),
+    backgroundColor = Color.new(0.12, 0.12, 0.17, 1),
     padding = { top = 10, right = 10, bottom = 10, left = 10 },
   })
 
@@ -128,7 +128,7 @@ function ThemeDemo.init()
     text = "Example 2: Button with Hover/Pressed States",
     textSize = 14,
     textColor = Color.new(0.8, 0.9, 1, 1),
-    background = Color.new(0, 0, 0, 0),
+    backgroundColor = Color.new(0, 0, 0, 0),
   })
 
   Gui.new({
@@ -137,7 +137,7 @@ function ThemeDemo.init()
     text = "Hover over or click the button to see state changes (when theme is loaded)",
     textSize = 11,
     textColor = Color.new(0.6, 0.7, 0.8, 1),
-    background = Color.new(0, 0, 0, 0),
+    backgroundColor = Color.new(0, 0, 0, 0),
   })
 
   local stateButton = Gui.new({
@@ -147,7 +147,7 @@ function ThemeDemo.init()
     text = "Interactive Button",
     textAlign = "center",
     textColor = Color.new(1, 1, 1, 1),
-    background = Color.new(0.3, 0.7, 0.4, 0.8),
+    backgroundColor = Color.new(0.3, 0.7, 0.4, 0.8),
     -- theme = "button", -- Will automatically handle hover/pressed states
     callback = function(element, event)
       if event.type == "click" then
@@ -163,7 +163,7 @@ function ThemeDemo.init()
     positioning = "flex",
     flexDirection = "vertical",
     gap = 10,
-    background = Color.new(0.12, 0.12, 0.17, 1),
+    backgroundColor = Color.new(0.12, 0.12, 0.17, 1),
     padding = { top = 10, right = 10, bottom = 10, left = 10 },
   })
 
@@ -173,14 +173,14 @@ function ThemeDemo.init()
     text = "Example 3: Themed Panel/Container",
     textSize = 14,
     textColor = Color.new(0.8, 0.9, 1, 1),
-    background = Color.new(0, 0, 0, 0),
+    backgroundColor = Color.new(0, 0, 0, 0),
   })
 
   local themedPanel = Gui.new({
     parent = example3,
     width = 300,
     height = 80,
-    background = Color.new(0.25, 0.25, 0.35, 0.9),
+    backgroundColor = Color.new(0.25, 0.25, 0.35, 0.9),
     -- theme = "panel", -- Would use panel theme component
     padding = { top = 10, right = 10, bottom = 10, left = 10 },
   })
@@ -191,14 +191,14 @@ function ThemeDemo.init()
     textSize = 12,
     textColor = Color.new(0.9, 0.9, 1, 1),
     textAlign = "center",
-    background = Color.new(0, 0, 0, 0),
+    backgroundColor = Color.new(0, 0, 0, 0),
   })
 
   -- Code example section
   local codeSection = Gui.new({
     parent = self.window,
     height = 40,
-    background = Color.new(0.08, 0.08, 0.12, 1),
+    backgroundColor = Color.new(0.08, 0.08, 0.12, 1),
     padding = { top = 10, right = 10, bottom = 10, left = 10 },
   })
 
@@ -207,7 +207,7 @@ function ThemeDemo.init()
     text = 'Usage: element = Gui.new({ theme = "button", ... })',
     textSize = 12,
     textColor = Color.new(0.5, 0.9, 0.5, 1),
-    background = Color.new(0, 0, 0, 0),
+    backgroundColor = Color.new(0, 0, 0, 0),
   })
 
   return self
diff --git a/examples/ZIndexDemo.lua b/examples/ZIndexDemo.lua
index 1d8e874..20aaa33 100644
--- a/examples/ZIndexDemo.lua
+++ b/examples/ZIndexDemo.lua
@@ -20,7 +20,7 @@ local back = Gui.new({
   width = 100,
   height = 100,
   z = 1,
-  background = Color.new(1, 0, 0, 0.8),
+  backgroundColor = Color.new(1, 0, 0, 0.8),
   text = "Z=1 (Back)",
   textColor = Color.new(1, 1, 1),
 })
@@ -32,7 +32,7 @@ local middle = Gui.new({
   width = 100,
   height = 100,
   z = 2,
-  background = Color.new(0, 1, 0, 0.8),
+  backgroundColor = Color.new(0, 1, 0, 0.8),
   text = "Z=2 (Middle)",
   textColor = Color.new(1, 1, 1),
 })
@@ -44,7 +44,7 @@ local front = Gui.new({
   width = 100,
   height = 100,
   z = 3,
-  background = Color.new(0, 0, 1, 0.8),
+  backgroundColor = Color.new(0, 0, 1, 0.8),
   text = "Z=3 (Front)",
   textColor = Color.new(1, 1, 1),
 })
@@ -75,7 +75,7 @@ local parent = Gui.new({
   y = 0,
   width = 300,
   height = 300,
-  background = Color.new(0.1, 0.1, 0.1, 1),
+  backgroundColor = Color.new(0.1, 0.1, 0.1, 1),
 })
 
 -- Create children in random z-order
@@ -87,7 +87,7 @@ local child3 = Gui.new({
   width = 80,
   height = 80,
   z = 3,
-  background = Color.new(0, 0, 1, 0.8),
+  backgroundColor = Color.new(0, 0, 1, 0.8),
   text = "Z=3",
   textColor = Color.new(1, 1, 1),
 })
@@ -100,7 +100,7 @@ local child1 = Gui.new({
   width = 80,
   height = 80,
   z = 1,
-  background = Color.new(1, 0, 0, 0.8),
+  backgroundColor = Color.new(1, 0, 0, 0.8),
   text = "Z=1",
   textColor = Color.new(1, 1, 1),
 })
@@ -113,7 +113,7 @@ local child2 = Gui.new({
   width = 80,
   height = 80,
   z = 2,
-  background = Color.new(0, 1, 0, 0.8),
+  backgroundColor = Color.new(0, 1, 0, 0.8),
   text = "Z=2",
   textColor = Color.new(1, 1, 1),
 })
@@ -131,14 +131,14 @@ print("   Z-index can be negative for background elements\n")
 
 Gui.destroy()
 
-local background = Gui.new({
+local backgroundColor = Gui.new({
   id = "background",
   x = 0,
   y = 0,
   width = 200,
   height = 200,
   z = -1,
-  background = Color.new(0.2, 0.2, 0.2, 1),
+  backgroundColor = Color.new(0.2, 0.2, 0.2, 1),
   text = "Background (z=-1)",
   textColor = Color.new(1, 1, 1),
 })
@@ -150,7 +150,7 @@ local normal = Gui.new({
   width = 100,
   height = 100,
   z = 0,
-  background = Color.new(0.5, 0.5, 0.5, 1),
+  backgroundColor = Color.new(0.5, 0.5, 0.5, 1),
   text = "Normal (z=0)",
   textColor = Color.new(1, 1, 1),
 })
@@ -175,7 +175,7 @@ local default1 = Gui.new({
   y = 10,
   width = 50,
   height = 50,
-  background = Color.new(1, 0, 0, 1),
+  backgroundColor = Color.new(1, 0, 0, 1),
 })
 
 local explicit = Gui.new({
@@ -185,7 +185,7 @@ local explicit = Gui.new({
   width = 50,
   height = 50,
   z = 1,
-  background = Color.new(0, 1, 0, 1),
+  backgroundColor = Color.new(0, 1, 0, 1),
 })
 
 local default2 = Gui.new({
@@ -194,7 +194,7 @@ local default2 = Gui.new({
   y = 50,
   width = 50,
   height = 50,
-  background = Color.new(0, 0, 1, 1),
+  backgroundColor = Color.new(0, 0, 1, 1),
 })
 
 print("default1.z =", default1.z, "(default)")
diff --git a/testing/__tests__/01_absolute_positioning_basic_tests.lua b/testing/__tests__/01_absolute_positioning_basic_tests.lua
index 5151c4e..8ae64da 100644
--- a/testing/__tests__/01_absolute_positioning_basic_tests.lua
+++ b/testing/__tests__/01_absolute_positioning_basic_tests.lua
@@ -595,7 +595,7 @@ function TestAbsolutePositioningBasic:testMultiBranchZIndexStacking()
   })
 
   -- Background layer (z=1)
-  local background = Gui.new({
+  local backgroundColor = Gui.new({
     parent = container,
     id = "background",
     x = 100,
diff --git a/testing/__tests__/13_relative_positioning_tests.lua b/testing/__tests__/13_relative_positioning_tests.lua
index 849617c..fa8440f 100644
--- a/testing/__tests__/13_relative_positioning_tests.lua
+++ b/testing/__tests__/13_relative_positioning_tests.lua
@@ -18,7 +18,7 @@ function TestRelativePositioning.testBasicRelativePositioning()
     width = 200,
     height = 150,
     positioning = "relative",
-    background = Color.new(0.2, 0.2, 0.2, 1.0),
+    backgroundColor = Color.new(0.2, 0.2, 0.2, 1.0),
   })
 
   local child = Gui.new({
@@ -28,7 +28,7 @@ function TestRelativePositioning.testBasicRelativePositioning()
     width = 50,
     height = 40,
     positioning = "relative",
-    background = Color.new(0.8, 0.2, 0.2, 1.0),
+    backgroundColor = Color.new(0.8, 0.2, 0.2, 1.0),
   })
 
   -- Child should be positioned relative to parent
@@ -45,7 +45,7 @@ function TestRelativePositioning.testRelativePositioningPercentages()
     width = 200,
     height = 100,
     positioning = "relative",
-    background = Color.new(0.2, 0.2, 0.2, 1.0),
+    backgroundColor = Color.new(0.2, 0.2, 0.2, 1.0),
   })
 
   local child = Gui.new({
@@ -55,7 +55,7 @@ function TestRelativePositioning.testRelativePositioningPercentages()
     width = 30,
     height = 20,
     positioning = "relative",
-    background = Color.new(0.8, 0.2, 0.2, 1.0),
+    backgroundColor = Color.new(0.8, 0.2, 0.2, 1.0),
   })
 
   -- Child should be positioned relative to parent with percentage offsets
@@ -72,7 +72,7 @@ function TestRelativePositioning.testRelativePositioningNoOffset()
     width = 150,
     height = 200,
     positioning = "relative",
-    background = Color.new(0.2, 0.2, 0.2, 1.0),
+    backgroundColor = Color.new(0.2, 0.2, 0.2, 1.0),
   })
 
   local child = Gui.new({
@@ -80,7 +80,7 @@ function TestRelativePositioning.testRelativePositioningNoOffset()
     width = 40,
     height = 30,
     positioning = "relative",
-    background = Color.new(0.2, 0.8, 0.2, 1.0),
+    backgroundColor = Color.new(0.2, 0.8, 0.2, 1.0),
   })
 
   -- Child should be positioned at parent's position with no offset
@@ -97,7 +97,7 @@ function TestRelativePositioning.testMultipleRelativeChildren()
     width = 100,
     height = 100,
     positioning = "relative",
-    background = Color.new(0.2, 0.2, 0.2, 1.0),
+    backgroundColor = Color.new(0.2, 0.2, 0.2, 1.0),
   })
 
   local child1 = Gui.new({
@@ -107,7 +107,7 @@ function TestRelativePositioning.testMultipleRelativeChildren()
     width = 20,
     height = 20,
     positioning = "relative",
-    background = Color.new(0.8, 0.2, 0.2, 1.0),
+    backgroundColor = Color.new(0.8, 0.2, 0.2, 1.0),
   })
 
   local child2 = Gui.new({
@@ -117,7 +117,7 @@ function TestRelativePositioning.testMultipleRelativeChildren()
     width = 25,
     height = 25,
     positioning = "relative",
-    background = Color.new(0.2, 0.8, 0.2, 1.0),
+    backgroundColor = Color.new(0.2, 0.8, 0.2, 1.0),
   })
 
   -- Both children should be positioned relative to parent
@@ -136,7 +136,7 @@ function TestRelativePositioning.testNestedRelativePositioning()
     width = 300,
     height = 250,
     positioning = "relative",
-    background = Color.new(0.1, 0.1, 0.1, 1.0),
+    backgroundColor = Color.new(0.1, 0.1, 0.1, 1.0),
   })
 
   local parent = Gui.new({
@@ -146,7 +146,7 @@ function TestRelativePositioning.testNestedRelativePositioning()
     width = 200,
     height = 150,
     positioning = "relative",
-    background = Color.new(0.3, 0.3, 0.3, 1.0),
+    backgroundColor = Color.new(0.3, 0.3, 0.3, 1.0),
   })
 
   local child = Gui.new({
@@ -156,7 +156,7 @@ function TestRelativePositioning.testNestedRelativePositioning()
     width = 50,
     height = 40,
     positioning = "relative",
-    background = Color.new(0.8, 0.8, 0.8, 1.0),
+    backgroundColor = Color.new(0.8, 0.8, 0.8, 1.0),
   })
 
   -- Each level should be positioned relative to its parent
@@ -175,7 +175,7 @@ function TestRelativePositioning.testMixedPositioning()
     width = 180,
     height = 120,
     positioning = "absolute",
-    background = Color.new(0.2, 0.2, 0.2, 1.0),
+    backgroundColor = Color.new(0.2, 0.2, 0.2, 1.0),
   })
 
   local child = Gui.new({
@@ -185,7 +185,7 @@ function TestRelativePositioning.testMixedPositioning()
     width = 60,
     height = 35,
     positioning = "relative",
-    background = Color.new(0.8, 0.8, 0.2, 1.0),
+    backgroundColor = Color.new(0.8, 0.8, 0.2, 1.0),
   })
 
   -- Relative child should still be positioned relative to absolute parent