Design conventions

Design conventions

The visual design follows conventions shared across widely used open-source design systems as of late 2026, checked against their source code and documentation: shadcn/ui, Radix Themes, HeroUI v3, Primer, Material 3 Expressive, and Apple’s current platform design language.

Convention	In this template
Cards separated by a subtle ring and soft shadow rather than a heavy border	border.default plus shadow.subtle on an off-white page background
A single base radius scaled across component sizes	sm 6, md 10, lg 16, xl 24
Control heights of 32 to 36px with 14px labels for pointer devices, 44px and up for touch	36 and 48 at the default size
Outlined secondary buttons paired with filled primary buttons	button.secondary.border
Pill-shaped badges	Badge
Slight scale-down animation on button press (HeroUI uses 0.97)	motion.press-scale
Capsule buttons and floating navigation bars on touch platforms	size.button-radius, TabBar, BottomSheet

Two intentional departures from those systems:

• Text field borders maintain a 3:1 contrast ratio against their background. Several of the systems above use lower-contrast borders, whereas here every input field must be identifiable by its outline alone.
• Hover and pressed states are defined as explicit solid colors rather than opacity overlays. Neither GPUI nor React Native supports runtime color blending, and explicit values allow the build script to verify contrast ratios statically.

Keeping platforms consistent

Area	Mechanism	Status
Token values	Generated files are committed, and CI regenerates and diffs them	Automated
Contrast	The token build verifies every foreground/background pairing in both modes	Automated
Component APIs	Component props and types on each platform are kept in sync manually rather than generated from a shared schema	Manual
Visual appearance	Compare the design preview screens visually across platforms; there is no automated screenshot diffing	Manual