hip-0504

HIP-504: Unified Cross-Platform Design System. Status Draft. Hanzo's own standard — read this before implementing against it.

HIP-0504: Unified Cross-Platform Design System

Abstract

This proposal defines the canonical design-system architecture for every Hanzo, Lux, and Zoo surface — web, native (React Native / Expo), and desktop (Tauri). It establishes one substrate (@hanzo/gui), one component library (@hanzo/ui), and brands as values (@luxfi/ui, @zooai/ui) rather than forks. A component is defined once, themed many times, and rendered everywhere. The standard is binding: per-brand component forks and brand-scoped substrates are non-conformant.

Specification

Two orthogonal axes

Design-system concerns separate along two independent axes. Brand is one axis; it is not the substrate axis.

Substrate (mechanism — how to render on web/native/desktop): tokens, themes, the compiler, accessible primitives. Brand- and app-agnostic.
Components (composition — the parts): the design language, composed from substrate primitives. The single public surface apps import.
Brand (values): theme tokens (color, type, radius, motion) plus a small set of brand-specific compositions. Brands re-implement nothing.

| | Substrate | Components | |---|---|---| | Generic | @hanzo/gui | @hanzo/ui | | Domain (web3) | @hanzo/gui-web3 | @hanzo/ui-web3 | | Brand (lux/zoo) | — (forbidden) | @luxfi/ui, @zooai/ui |

Normative rules

MUST — one definition. Every component is defined exactly once (in @hanzo/ui / @hanzo/ui-web3). No duplicate component implementation may exist elsewhere in the dependency tree.
MUST — substrate splits by domain, never by brand. Cross-platform capability lives in @hanzo/gui (generic) or a domain module such as @hanzo/gui-web3 (wallet-connect, chain selector, address/amount inputs, native QR/camera, hardware-wallet bridge). A brand-scoped substrate package (e.g. @luxfi/gui) is non-conformant — domain primitives are brand-agnostic and shared by Lux and Zoo alike.
MUST — brand is a value, not a place. @luxfi/ui / @zooai/ui are theme tokens plus brand-only compositions over @hanzo/ui. A new brand is a token set, not a component fork. Adding @parsdao/ui means writing a theme.
MUST — one import per app. An app depends only on its brand ui (@hanzo/ui for Hanzo). Importing @hanzo/gui directly from an app is non-conformant; the substrate is internal.
MUST — stable public API. Re-basing @hanzo/ui onto @hanzo/gui preserves its import surface; consuming apps upgrade without source changes.
MUST — visual-regression gate. Each migration phase is gated by a Playwright visual-regression suite: rendered output MUST match the pre-migration baseline within tolerance before the phase merges. Decomplecting the implementation MUST NOT change the user-visible pixels.

Dependency spine

@hanzo/gui ──┬── @hanzo/gui-web3        substrate: generic + crypto domain (shared)
             ▼
@hanzo/ui ───┴── @hanzo/ui-web3         components composed from the substrate
             ▼
@luxfi/ui  = @hanzo/ui(+web3) + lux theme + lux-only compositions
@zooai/ui  = @hanzo/ui(+web3) + zoo theme + zoo-only compositions
             ▼
Lux apps → @luxfi/ui   Zoo apps → @zooai/ui   Hanzo apps → @hanzo/ui   (one import each)

Migration phases

Each phase builds green and passes the visual-regression gate before the next begins. No big-bang.

Phase 0 — Foundation. @hanzo/ui takes a dependency on @hanzo/gui and re-bases its components as substrate compositions, keeping the public API identical. Standalone primitives are deleted.
Phase 1 — Brands. @luxfi/ui and @zooai/ui become token/theme overlays on the new @hanzo/ui; brand-unique widgets re-expressed as substrate compositions.
Phase 2 — Adopt. Sites and apps move to the unified brand ui and inherit web / native / desktop.

Conformance

A package or app is conformant iff: it imports exactly one ui package (its brand's); it defines no component that already exists upstream; it contributes no brand-scoped substrate; and (for migration PRs) it passes the visual-regression gate. The @hanzo/gui developer reference is the gui-docs Architecture page; this HIP is the binding form.

Security Considerations

The web3 substrate (@hanzo/gui-web3) is the single place key-handling primitives (wallet connect, hardware-wallet bridge, address entry) live, so security review and supply-chain scrutiny concentrate on one audited module rather than N brand forks. Brand packages, holding only tokens and compositions, carry no key-handling surface.