Quartz 4

ui-library-choice

4 min read

UI Library Choice: Tailwind + shadcn/ui

Architecture decision record for the Guild frontend component library.

Decision

Tailwind CSS v4 + shadcn/ui with a custom theme for the cassette futurism / sword & sorcery aesthetic. See guild-visual-direction for the visual identity.

Context

Guild needs a UI library for three upcoming surfaces:

  1. Signup page — tier selection + Stripe Checkout (mobile-first, used in-store)
  2. Kiosk app — Raspberry Pi + touchscreen + NFC (single-purpose, needs to be bulletproof)
  3. Member portal — points balance, tier info, benefits (light reads, mobile)

None of these are complex UIs. Cards, buttons, short forms, confirmation screens.

Options Evaluated

Mantine 7

  • 100+ components, 50+ hooks, built-in forms/dates/notifications
  • PostCSS modules — zero runtime CSS overhead
  • React 19 compatible, Next.js App Router supported
  • Best batteries-included DX — Reddit consensus for fastest dev velocity
  • Known minor issue: Next.js 16 Link component needs 'use client' workaround
  • Why not chosen: Different styling system from Medusa storefront (which uses Tailwind). Would mean maintaining two CSS approaches. Also, no pre-built theme captures the cassette futurism aesthetic — we’d be fighting Mantine’s defaults either way.

Chakra UI v3

  • Batteries-included, good style-props DX
  • v3 was a major rewrite — kept Emotion (runtime CSS-in-JS) despite plans to move to Panda CSS
  • Ecosystem still rebuilding after v2 → v3 migration
  • Why not chosen: Runtime CSS-in-JS, ecosystem instability after rewrite, different styling system from storefront.

Park UI (Panda CSS + Ark UI)

  • Chakra ecosystem’s recommended modern path (per Sage’s blog post)
  • Static CSS, headless primitives with pre-built styles
  • Why not chosen: Smaller community, more assembly required, Panda CSS is a third styling system.

DaisyUI

  • Tailwind plugin with semantic classes
  • Easy themes but less control
  • Why not chosen: Too generic, hard to achieve the specific aesthetic we want.

RetroUI / neobrutalism.dev

  • Neobrutalism-themed shadcn components
  • RetroUI installs via shadcn registry, Tailwind-native
  • neobrutalism.dev is abandoned (maintainer quit Jul 2025)
  • Why not chosen as primary: Neobrutalism is adjacent but not the right vibe — it’s rave flyer, not dungeon zine. May cherry-pick individual components if useful.

shadcn/ui (Tailwind + Radix) ← chosen

  • Copy-paste components, you own the code
  • Most popular in Next.js ecosystem (2025-2026)
  • Payload CMS has an official guide and example repo
  • Radix primitives for accessibility
  • Fully customizable — no fighting a pre-built theme
  • Same styling foundation as Medusa storefront (both Tailwind)

Why Tailwind + shadcn

  1. Consistent with the Medusa storefront. Both Solace and Fashion starters use Tailwind. Medusa UI (@medusajs/ui) is Tailwind-based. If the member portal ever lives alongside the shop, it’s the same styling system.

  2. Payload officially supports it. Official guide, example repo, and data-theme dark mode integration documented. If we customize the admin panel later, Tailwind is already there.

  3. The aesthetic demands a custom theme. No pre-built library captures “cassette futurism meets 80s sword & sorcery.” We’d be overriding defaults in any library. shadcn’s copy-paste model means we own the components and can theme them freely without fighting upstream opinions.

  4. The frontend is simple enough. The Reddit critique of shadcn (“slower dev velocity”) applies to complex apps with dozens of components. Guild needs cards, buttons, a form, and confirmation screens. The velocity difference is negligible at this scale.

  5. Solo dev, frontend isn’t the strength — but that’s OK here. Mantine would be faster for a generic-looking app. But we want a specific look (dungeon zine, CRT terminals, cassette tape labels). That requires custom styling work regardless of the library. Better to do that work in the system that’s consistent with everything else.

Trade-offs Accepted

  • Less out-of-the-box than Mantine. Loading states, form validation, etc. require more manual work. Acceptable given the small number of UI surfaces.
  • Tailwind utility classes have a learning curve. But it’s an investment that pays off across both Guild and the storefront.

References

Graph View

Backlinks