legendui-swift: LegendUI: The SwiftUI Kit Where Theme Is the Product

A look at a cross-platform component library that puts semantic colors, layout tokens, and @Observable state at the center of the UI stack.

8 min read • View on GitHub • More from sunghyun-k

A mechanical theme engine feeds several downstream UI parts through levers for color, spacing, and border shape. The scene explains that LegendUI treats theme decisions as upstream infrastructure, not as per-component decoration.
LegendUI’s core idea is simple: change the theme once, and the rest of the system follows.

A description for your component library.

sunghyun-k, Project Creator · README.md - legendui-swift
Key Takeaways

Why LegendUI Feels Like Infrastructure, Not a Widget Pack

LegendUI does not read like a library that started with a button and kept expanding. It reads like a theme system that happened to grow components around it. That is the real distinction: the library’s value is less about individual controls and more about how one theme object can reshape the whole UI language.

That matters because SwiftUI already gives you components. What it does not give you is a strong opinionated layer for propagating brand decisions across screens, states, and platforms. LegendUI tries to be that layer.

The Theme Engine Is the Real Product

LegendUI’s main abstraction is the path from one observable theme object to many downstream component behaviors.

The architecture centers on SharedTheme, which is built as an @Observable object. That choice is the quiet headline. Instead of pushing theme data through ad hoc environment plumbing, the library treats theme state as something the UI can subscribe to directly.

@Observable
final class SharedTheme {
    var value = LegendTheme()
}

struct LegendTheme {
    var colors = LegendColors()
    var layout = LegendLayout()
    var typography = LegendTypography()
}

That structure gives the rest of the library a clean hierarchy. LegendTheme is the container. LegendColors, LegendLayout, and LegendTypography are the token families. Components consume them downstream, which keeps the styling logic centralized instead of scattered across every view.

Theme-first LegendUIComponent-first SwiftUI styling
One observable theme object drives the systemEach component often carries its own styling logic
Semantic tokens encode brand decisionsAppearance is frequently local and ad hoc
Layout, typography, and color move togetherSpacing and color can drift across screens
Buttons and toasts inherit from shared primitivesEvery control can become its own special case
Cross-platform behavior is part of the theme storyPlatform differences are usually handled case by case
The same family of controls appears twice, once with dense solid fills and once with muted soft surfaces. The image explains how LegendUI turns semantic variants into part of the theme vocabulary rather than a one-off visual treatment.
LegendUI’s semantic variants make style a language, not a pile of exceptions.

Semantic Colors Turn Variants Into a Language

The most revealing idea in LegendUI is the way it handles semantic color groups. The library organizes colors around roles like default, foreground, soft, and softForeground. That is not just naming hygiene. It lets the component system speak in terms of intent.

A soft surface is not a decorative flourish. It is a reusable design primitive. Once that concept exists at the theme layer, buttons, chips, and other controls can shift from solid to soft without changing their structure.

Buttons Show the Architecture at Its Best

Buttons are where the library’s philosophy becomes obvious. LegendUI uses a style system that separates behavior from presentation, which keeps the interaction model clean while still allowing variants, sizes, and custom themes to flow in from the outside.

Button("Continue") { }
    .buttonStyle(
        LegendButtonStyle(
            variant: .primary,
            size: .medium
        )
    )

That is the right abstraction for a theme-first kit. The button is not a special snowflake. It is a consumer of shared tokens, with an escape hatch for custom variants when a product needs something unusual.

LegendUI button systemTypical SwiftUI button styling
Primitive behavior is kept separate from renderingBehavior and appearance are often bundled together
Variants come from a shared theme vocabularyVariants are frequently reimplemented per screen
Custom variants can still fit the systemOne-off tweaks can fragment consistency
Hover and platform differences are modeled explicitlyPlatform behavior is often bolted on later

Toasts and Overlays Solve the Ugly Part of SwiftUI

The overlay story is practical, and that is why it matters. Toasts are usually where SwiftUI apps start to show seams. LegendUI pushes that problem into a shared overlay layer so notifications can appear without blocking the rest of the interface.

That makes the library more than a visual kit. It becomes a small interaction infrastructure layer, one that can handle passthrough behavior, global presentation, and the awkward parts of transient UI.

Where LegendUI Fits in the SwiftUI Landscape

LegendUI is not trying to replace SwiftUI. It sits above SwiftUI and changes the way a team thinks about brand consistency. Compared with vanilla styling, it is much more opinionated. Compared with many component kits, it starts with the theme and lets the widgets follow.

LegendUIVanilla SwiftUI
Theme is centralized and observableStyling is often distributed across views
Semantic tokens drive component variantsComponents are styled more locally
Layout is part of the design systemSpacing tends to be defined ad hoc
Global overlays are first-classTransient UI usually needs custom plumbing
Cross-platform behavior is intentionalPlatform-specific polish is often manual

A Small Project With Serious Architectural Discipline

The codebase looks early, but it does not look careless. The package structure is clean, the theme layer is separated from components, and the presence of docs-oriented conventions suggests someone is building for maintainability rather than a quick demo.

That discipline is the real signal. Even before the project has broad adoption, it already behaves like a serious library: modular, opinionated, and organized around a stable abstraction boundary.

A hedcut-style portrait of the LegendUI maintainer, rendered from the verified GitHub avatar. The portrait gives a face to the project’s creator while keeping the emphasis on the library’s architectural ideas.