The Zovia Design System

Two Paradigms, One Philosophy

A mobile-first design system powering all Zovia apps.

  • 43

    Packages

  • 2

    Paradigms

  • 100%

    Phone-Only

Zarden on an iPhone, showing a garden of plants
Zistil Insights screen showing an organization health score, what you own by category and how many items each storage space holds
The Zuzzle hub, showing today's daily puzzle and the Space Age era card, Decimal, Base 10.
Zarden OURS
Zistil OURS
Zuzzle OURS

Philosophy

Invisible Complexity, Visible Simplicity

Technology should disappear. Users shouldn't think about the interface, they should think about their content.

  • Reduction Before Addition

    Remove before you add

  • Motion with Meaning

    Animation explains change

  • Color as Communication

    Color indicates state

  • Touch-First Thinking

    44×44pt minimum targets

  • Depth Through Layers

    Glassmorphism hierarchy

  • Consistency Through Patterns

    Learn once, use everywhere

Our design system draws on two of the most studied design languages in the world: Apple's Human Interface Guidelines and Google's Material. We took the parts that fit a calm, focused product and refined them into our own token-driven system: a single palette, a quiet type scale with no bold weights, consistent motion, and contrast checked everywhere.

Two paradigms

Dual Paradigms

Two visual languages. Same logic. Different expressions.

Spatial UI

Monument Valley-inspired interfaces for games and immersive experiences.

  • Floating orbs & 3D layouts
  • Minimal text, maximum gesture
  • Context-aware animations
  • Zuzzle (number-systems puzzles)

Traditional UI

Familiar patterns for productivity apps and information-dense screens.

  • Lists, tabs, forms
  • Information hierarchy
  • Scannable content
  • Zyve
  • Zistil
  • Zots

CLAUDE.md Rule 9

ZAppScaffold Chrome System

Every screen in every Zovia app uses the same chrome stack. No deviations across existing, new, or future apps.

  • Glass app bar

    Floating glass top island. Set useGlassAppBar: true.

  • Glass bottom nav

    Floating glass bottom nav when present. Set useGlassBottomNav: true.

  • extendBehindGlassAppBar

    Body extends edge-to-edge under chrome so glass blurs items and the top fade dissolves cleanly.

  • Per-app accent gradient

    accentColor drives the atmosphere drawn behind the body. Never replace with a flat background.

  • ZAppScaffold.topInsetFor(context)

    The canonical top spacer (status bar + bar height). Using glassAppBarHeight alone clips items mid-fade.

Rule 9, absolute

If the system doesn't fit a real need, fix ZAppScaffold and roll it out across all apps in the same change. Never one-off it.

The Z Component Library

Named Atoms, Not Raw Material

Every visual unit in a Zovia app is a Z atom. Raw Material widgets break the type ramp, the theme, and the cross-app consistency contract.

  • ZText

    Never use raw Text(). Five styles (header, title, body, caption, micro) tuned to the Zovia type ramp.

  • ZButton

    Never use raw ElevatedButton or TextButton. ZButton handles brand color, contrast, and tier intent automatically.

  • ZIconTextButton

    Replaces ad-hoc icon-plus-label rows. Primary, secondary, ghost variants. The canonical CTA for modals.

  • ZLink

    Replaces tappable Text and TextButton for inline links. Small, medium, large sizes that match caption-scale type.

  • ZCard

    Replaces Container + BoxDecoration. Standard radius, padding, shadow, and theme-aware surface color.

  • ZPanelSheet

    Replaces showDialog and AlertDialog. The only sanctioned modal surface, auto-tracked by ZModalCoordinator.

  • ZSkeleton

    Atoms for loading shimmer (line, circle, block). The escape hatch when a component skeleton doesn't fit.

  • ZSnackbar

    Ambient signal surface. Preferred over permanent chrome for transient feedback. Never stacks, never blocks.

  • ZPill

    Compact status and category tag. Used for tier badges, filter chips, list metadata.

  • ZScrollRow

    Horizontal scroll row with built-in alignment, edge fades, and snap behavior tuned to phone-only layouts.

  • ZModalCoordinator

    Queues auto-firing modals so prompts never stack on top of each other. Required for any sheet not triggered by a direct tap.

Rule 11

Auto-firing modals (post-frame, timers, stream listeners, lifecycle callbacks) MUST wrap their show call with ZModalCoordinator.enqueue. Direct .show() from an auto-trigger stacks on top of any open modal.

Rule 12

Every button, CTA, and tappable text uses a Z component. Never reach for ElevatedButton, TextButton, OutlinedButton, FilledButton, or a tappable raw Text. The Z atoms are pre-tuned to the Zovia type ramp.

CLAUDE.md Rule 8

Skeletons on Every Loading State

Blank screens and bare spinners are forbidden. Every visual component with a data-loaded lifecycle ships a static .skeleton() factory matching its shape.

Mandatory

  • Initial load uses an app composite skeleton, never a CircularProgressIndicator.
  • Text placeholders use ZText.skeleton(style).
  • Pills, buttons, cards all expose .skeleton() factories.
  • ZSkeleton.line / circle / block is the escape hatch for custom shapes.

Enforced

A compliance test fails CI when a Z* widget lands without a .skeleton() factory or a /// @no-skeleton: explanation marker.

packages/z_design/test/skeleton_factory_compliance_test.dart

CLAUDE.md Rule 13

Ten enforceable design principles

Every screen, feature, and interaction clears these ten. When proposing a design, name the two or three you are leaning on. When violating one, say which and why.

  • 1

    Doherty Threshold

    Every action shows a response within roughly 400ms. No "did anything happen?" gaps.

  • 2

    Fitts's Law

    Primary tap targets at least 44pt, placed in the natural thumb zone. Never under glass-bar hit slop.

  • 3

    Forgiveness

    Every destructive action has undo (preferred) or explicit confirmation. No silent permanent destruction.

  • 4

    Recognition Over Recall

    Inputs surface recent and likely options. Empty fields suggest, never blank.

  • 5

    Progressive Disclosure

    Complex screens open with the 80% case visible. Advanced controls live behind "More" or expand.

  • 6

    Hick's Law

    Primary choice surfaces show no more than about 7 options at once. Beyond that, group, filter, or paginate.

  • 7

    Peak-End Rule

    Every flow has an intentional opening moment and a satisfying close. No flow ends by silently dropping back to a list.

  • 8

    Zeigarnik Effect

    Incomplete progress is visible when the user returns. Multi-step state never resets silently.

  • 9

    Goal-Gradient Effect

    Multi-step flows show progress and visibly accelerate cues near completion.

  • 10

    Calm Technology

    Default to ambient signals (badges, color shifts, subtle cards). Reserve push and modal interruption for high-stakes events.

Full canon and rationale live in CLAUDE.md at the repo root.

Themes

Built for Light and Dark

Every component adapts automatically. All apps support both themes out of the box.

The Zupply list on an iPhone: one shared grocery list grouped by category, with Bakery, Beverages, Cleaning Supplies and Dairy, and the household member who added an item named under it., in dark mode
Zupply, dark mode
Zistil Insights screen showing an organization health score, what you own by category and how many items each storage space holds, in light mode
Zistil, light mode

Palette

Colors

Tropical Rainforest Dawn • Coral Reef Depths

Light Mode Palette

Foundation

  • Morning Mist

    #F8F6F2

  • Dew on Leaves

    #E8E3DB

  • Fern Grove

    #7A9179

  • Forest Ink

    #2D3B2A

  • Leaf Text

    #4A5D47

  • Mist Text

    #7A8A77

Semantic Colors

  • Accent

    #D97AA6

  • Success

    #A8D6A8

  • Warning

    #E67E22

  • Error

    #E74C3C

  • Info

    #00A5A8

Dark Mode Palette

Foundation

  • Abyssal

    #0A0F14

  • Deep Current

    #121820

  • Mid Water

    #1A222C

  • Parrotfish

    #00CED1

  • Pearl Glow

    #E6F3FF

  • Foam White

    #B8D4EA

Coral Reefs & Fish

  • Staghorn Coral

    #FF7F7F

  • Table Coral

    #7FFFD4

  • Brain Coral

    #FFB347

  • Sea Fan

    #FF69B4

  • Angelfish

    #FFD700

Type

Typography

Subtle, quiet text hierarchy. Built with SF Pro.

  • Header • 20pt • Light (300)

    The quick brown fox jumps over the lazy dog

  • Title • 17pt • Light (300)

    The quick brown fox jumps over the lazy dog

  • Body • 14pt • Regular (400)

    The quick brown fox jumps over the lazy dog

  • Caption • 12pt • Regular (400)

    The quick brown fox jumps over the lazy dog

  • Micro • 11pt • Regular (400)

    THE QUICK BROWN FOX JUMPS OVER THE LAZY DOG

Design Notes

  • No bold weights - maximum is Medium (500) for buttons only
  • Maximum 20pt for app interfaces - subtlety over drama
  • SF Pro on iOS, Roboto on Android - system fonts for performance
  • Negative letter spacing for headers creates elegant tension

Icon set

Icons

Phosphor Icons. Exclusively.

Why Phosphor Icons

Most apps mix icon sets, Material here, Font Awesome there, custom SVGs everywhere. This creates visual chaos. Users subconsciously notice the inconsistency.

We use Phosphor Icons exclusively across every screen, every app, every interaction in the Zovia ecosystem. No exceptions.

Why Phosphor? Because they understand what we understand: consistency is invisible, but its absence is jarring.

How We Use Them

  • Spatial UI (Games)

    Thin weight for Monument Valley minimalism. Icons become geometry.

  • Traditional UI (Apps)

    Thin weight for clarity and information density. Same default as games for cross-app consistency.

  • Thin Everywhere

    Thin is the Zovia default across all surfaces. Fill is explicitly avoided because it renders as a solid blob on light backgrounds.

Six Weights, Infinite Expression

  • Thin

    Games

  • Light

    Apps

  • Regular

    Default

  • Bold

    Emphasis

  • Fill

    Avoided

  • Duotone

    Depth

Design Notes

  • Thin is the Zovia default across all surfaces. Fill is explicitly avoided because it renders as a solid blob on light backgrounds.
  • Same icon, six personalities, perfect for creating visual hierarchy
  • 1,512 icons across all categories, we've never needed anything else
  • Clean geometric construction matches our glassmorphism aesthetic
  • Users recognize the same icon language across Zots, Zyve, Zuzzle, Zistil

Icons We Use Daily

And hundreds more. Every interaction, every state, every screen.

The ecosystem

In Production

Used across the Zovia ecosystem

  • Zupply

    The grocery list that learns.

    Available Now
  • Zyve

    Family Calendar

    Available Now
  • Zistil

    Inventory Management

    Available Now
  • Zots

    Counter & Schedule Tracker

    Available Now
  • Zuzzle

    Number System Puzzles

    Available Now
  • Zarden

    Plant care that thinks

    Available Now
  • Artist Circle

    Post your work. Get real critique.

    Live on the web
  • 221B

    Detective logic grid mysteries.

    In final testing
  • Zivics

    How well do you know your rights?

    In development

43 shared packages • 100% phone-only • Zero tablet code

Build your own

This design system is yours in Zovia Snapshot

The Z component library ships as real source in Zovia Snapshot, alongside the backend layer and a Claude Code guide, so you can build your own app on the same foundation we use.