k-fenui

FenUI

FenUI is a progressive-enhancement widget layer over Blizzard's frames and templates, with a design-token theme system. The copy in Mechanic/Libs/FenUI/ is synced from the FenUI source repo (_dev_/Libs/FenUI); fix FenUI in its own repo and re-sync rather than patching the vendored copy. Authoritative docs: Mechanic/Libs/FenUI/README.md and Mechanic/Libs/FenUI/AGENTS.md.

Access and degradation

FenUI is a plain global (FenUI = FenUI or {} in Core/FenUI.lua), not a LibStub library. The library is embedded through Libs\FenUI\FenUI.xml. Always guard when FenUI is optional:

if FenUI and FenUI.CreatePanel then
    frame = FenUI:CreatePanel(parent, config)
else
    frame = CreateFrame("Frame", nil, parent, "BackdropTemplate")  -- fallback
end

Factories

Pattern: FenUI:Create<Widget>(parent, config) returns a Blizzard frame with a mixin applied. A string config is accepted by CreatePanel (title) and CreateButton (text). Builder forms exist for a few: FenUI.Panel(parent):title("..."):build(), FenUI.Flex, FenUI.Stack, FenUI.TabGroup, FenUI.Group.

local panel = FenUI:CreatePanel(UIParent, { title = "My Window", width = 400, height = 300,
    movable = true, resizable = true, closable = true })

local stack = FenUI:CreateStack(panel, { direction = "vertical", gap = "md", align = "stretch", padding = "sm" })
stack:AddChild(topButton)
stack:AddChild(spacer, { grow = 1 })

local tabs = FenUI:CreateTabGroup(panel, {
    tabs = { { key = "main", text = "Main" }, { key = "settings", text = "Settings", badge = "!" } },
    onChange = function(key) end,
})

local grid = FenUI:CreateGrid(panel, { columns = { 24, "1fr", "auto" }, rowHeight = 24,
    onRowClick = function(row, data) end })

local button = FenUI:CreateButton(panel, { text = "Click me", onClick = function() end })

Sizes accept numbers, percentages ("50%"), viewport units and "auto"; minWidth/maxWidth/aspectRatio constrain layouts. Check the factory's config handling in Widgets/<Name>.lua for the exact keys before using one you have not used.

Tokens and themes

• Colors: FenUI:GetColor(token), GetColorRGB, GetColorHex, GetColorTable; spacing FenUI:GetSpacing("spacingPanel"); radius FenUI:GetRadius("radiusControl"). Three tiers: primitive, semantic, component. Use semantic tokens (textDefault, textHeading, surfacePanel), not raw colors.
• Themes: FenUI:GetThemeList(), FenUI:SetGlobalTheme(name), FenUI:GetGlobalTheme(), FenUI:OnThemeChanged(callback). A global theme change re-colors live widgets; a custom widget that resolves token colors once defines RefreshTheme() and calls FenUI:RegisterThemedFrame(widget).
• Blizzard scroll frames can be skinned with FenUI:SkinScrollFrame.

Mechanic conventions

• Use FenUI widgets instead of raw frames where one exists; add new widgets to FenUI itself.
• Type scale and neutral headings follow the Obsidian look (Mechanic/CHANGELOG.md 1.3.7): gold only for the window title, active tab, selection and focus.
• Keep the view layer thin and test at several UI scales.
• Mechanic's Utils.lua falls back gracefully when FenUI helpers are missing.