Design System

Reference design guidance for GO(A)HT apps with strong architectural opinions.

GO(A)HT has strong architectural opinions about how UI should be built. It does not require one brand palette, one sports-inspired mood board, or one BagTrax-specific visual language.

The design system guidance is reference guidance, not a mandatory aesthetic.

What Is Opinionated

The stack is opinionated about structure:

  • pages and fragments are server-rendered
  • HTML fragments are the primary UI API
  • Tailwind is the default utility layer
  • Alpine is the exception layer for local state
  • component choices should support progressive enhancement and stable swaps

Those are architectural opinions. They tell you how UI is delivered and maintained.

What Is Not Prescribed

The stack does not require:

  • dark mode by default
  • a sports UI
  • orange accents
  • glassmorphism
  • DaisyUI as your only component vocabulary

You can build a quiet productivity app, an editorial site, an internal admin tool, or a realtime scoreboard with the same GO(A)HT architecture.

Design Tokens As Reference

Design tokens are useful because they make server-rendered pages and fragments consistent. They are not useful because they force every app into one visual identity.

Good token categories:

  • color roles such as background, foreground, accent, border, success, danger
  • typography roles such as display, body, label, code
  • spacing and radius scales
  • motion durations and easing

Example:

:root {
  --color-bg: oklch(98% 0.01 95);
  --color-surface: oklch(100% 0 0);
  --color-fg: oklch(20% 0.02 250);
  --color-accent: oklch(62% 0.18 220);
  --color-border: oklch(88% 0.01 250);

  --font-display: "Satoshi", sans-serif;
  --font-body: "Satoshi", sans-serif;
  --font-code: "JetBrains Mono", monospace;

  --radius-sm: 0.375rem;
  --radius-md: 0.75rem;
  --duration-fast: 120ms;
  --duration-base: 200ms;
}

Those tokens describe a system, not a brand direction.

Fragments Need Stable Styling Contracts

Because GO(A)HT apps swap HTML fragments frequently, styling should be resilient to partial refreshes.

Prefer:

  • reusable utility compositions
  • small component classes for repeated fragments
  • data or semantic attributes that survive re-rendering

Avoid:

  • DOM structures that only work if a client framework owns the whole page
  • styling that depends on fragile parent-child position
  • visual logic hidden in JavaScript state when the server owns the markup

If a fragment can be rendered on first load and refreshed later without changing its styling contract, the design system is doing its job.

Accessibility And Interaction States

A GO(A)HT design system should define states that work whether the user arrives through a full page load, an HTMX swap, or a boosted navigation event.

Document patterns for:

  • focus visibility
  • disabled controls
  • loading states
  • validation feedback
  • empty states
  • success and error banners

These matter more than any one palette.

Component Guidance

Use component guidance as reusable patterns, not mandatory skins.

For example:

  • buttons should have clear primary, secondary, and destructive roles
  • cards or panels should define padding, border, and heading treatment
  • tables and list rows should specify hover, density, and selection behavior
  • badges should communicate status clearly without depending only on color

The implementation can be utilities, component classes, or a light internal library. The important part is that fragments and pages share the same rules.

Motion Guidance

Keep motion intentional and small:

  • use short transitions for hover, focus, and state change
  • use entrance motion sparingly for newly swapped content
  • respect prefers-reduced-motion

GO(A)HT does not need SPA-style animation choreography. Most motion should support clarity, not spectacle.

DaisyUI, Tailwind, And Variants

Tailwind is the default styling tool in the docs. DaisyUI can be useful, but it is optional. If you use it, treat its component classes as a starting point and adapt them to your product rather than assuming the defaults are the GO(A)HT brand.

A Practical Standard

When evaluating a design system for a GO(A)HT app, ask:

  1. does it support server-rendered pages and HTML fragments cleanly?
  2. are selectors and component boundaries stable under HTMX swaps?
  3. does it define reusable roles and states instead of one-off styling?
  4. does it leave room for product-specific visual direction?

If the answer is yes, it fits the stack whether it looks like BagTrax or not.

Gotchas

  • Do not confuse architectural consistency with visual sameness.
  • Do not document one app’s brand tokens as if they were required for every app on the stack.
  • Fragment-friendly components matter more than decorative flourish.
  • If a design rule only works for one product aesthetic, document it as an example, not as the framework default.