Skip to content

Design System

Awake Graphical User Interface (GUI)

Status: refactor in progress — see docs/audits/2026-08-17-ui-refactor-vs-recreate-audit.md.

Awake UI is a lightweight declarative UI framework designed for game HUDs, overlays, and developer tooling within the Awake engine. Placement rules for these modules live in docs/reference/ui-ownership.md; the same optional-content-vs-capability principle the render backends follow is documented at docs/reference/render-extensibility.md.

Module Architecture

The UI system is decomposed into focused, single-responsibility modules:

include(":awake:ui:graphics")
include(":awake:core:text")
include(":awake:ui:animation")
include(":awake:ui:ui-core")
include(":awake:ui:headless")
include(":awake:tailwind")
include(":awake:ui:material3")
include(":awake:ui:shadcn")
include(":awake:heroicons")
include(":awake:ui:testing")
include(":awake:ui:font-atlas-generator")
include(":awake:tailwind-generator")

Module Descriptions

One line each — the public API and its class names are KDoc'd in the source itself (generated via Dokka), not duplicated here.

  • awake:ui:graphics — drawing primitives, shape painters, vector paths, gradients, bounds, density, icons.
  • awake:ui:text — SDF/MSDF font rendering, font atlas integration, typography styles.
  • awake:ui:animation — frame-clock driven animation, layout transitions, popup positioning, shimmer sweep primitives.
  • awake:ui:ui-core — frame loop, runtime state, layout engine, modifiers, state hooks, neutral theme mechanics. No ambient per-component style defaults; recipes pass explicit Style. (Named ui-core to disambiguate from engine root :awake:core.)
  • awake:ui:headless — unstyled, accessible leaf widgets for building custom design systems. Public APIs receive generic Style; no branded or theme-provider vocabulary.
  • awake:ui:tailwind — standalone Tailwind CSS design tokens.
  • awake:ui:material3 — Material 3 color schemes and components, including Scaffold.
  • awake:ui:shadcn — shadcn/ui-styled component library built on Compose Foundation + Tailwind. Owns named themes and branded recipes.
  • awake:ui:heroicons — Heroicons icon set integration.
  • awake:ui:testing — snapshot test runners and interaction-test harnesses for UI components.
  • awake:ui:font-atlas-generator — SDF/MSDF font atlas generation tooling.
  • awake:ui:tailwind-generator — Tailwind-pattern style/theme generation tooling.

Dependency Flow

graph TD
    GRAPHICS[":awake:ui:graphics<br/>(Drawing, Gradients, Shapes, Paths, Dp, Bounds)"]
    TEXT[":awake:core:text<br/>(MSDF Font, Bitmap Font, TextStyle, FontWeight)"]
    CORE[":awake:ui:ui-core<br/>(UiContext, Layout Engine, Alignment, Insets, Modifiers)"]
    ANIMATION[":awake:ui:animation<br/>(animateFloat, AnimatedVisibility, Transitions, Popups)"]
    HEADLESS[":awake:ui:headless<br/>(Unstyled Primitives & Tab Contracts)"]
    MATERIAL3[":awake:ui:material3<br/>(Material 3 Components)"]
    DS[":awake:ui:shadcn<br/>(Shadcn Recipes)"]

    GRAPHICS --> TEXT
    GRAPHICS --> CORE
    TEXT --> CORE
    CORE --> ANIMATION
    CORE --> HEADLESS
    GRAPHICS --> HEADLESS
    ANIMATION --> HEADLESS
    TEXT --> HEADLESS

    HEADLESS --> MATERIAL3
    HEADLESS --> DS
    CORE -. "internal infrastructure" .-> DS

Known gaps

Tracked in docs/reference/ui-validation.md's component coverage matrix and docs/reference/ui-status.md, not duplicated here.