@poke-flow/zui

A comprehensive UI component library for ZeppOS smart watches, optimized for Amazfit Balance (480x480 resolution).

Features

• 🎨 ZeppOS Design System - Follows official ZeppOS 3.0 design principles
• 📱 Optimized for Circular Displays - Built for Amazfit Balance (480x480)
• 🧩 Component Library - Buttons, Switches, Steppers, Lists, Toasts, and more
• 🎬 Smooth Animations - Built-in easing functions and animation utilities
• 📐 Flexible Layouts - Stack, Container, ScrollView, CircularLayout
• 🎯 TypeScript - Full type safety and IntelliSense support
• ✅ Tested - 180+ unit tests

Installation

npm install @poke-flow/zui
# or
yarn add @poke-flow/zui

Quick Start

import { Button, Switch, Toast } from '@poke-flow/zui';

// Create a primary button
const button = new Button({
  label: 'Click Me',
  variant: 'primary',
  x: 100,
  y: 200,
  onPress: () => console.log('Pressed!'),
});
button.mount();

// Create a toggle switch
const toggle = new Switch({
  value: false,
  onChange: (value) => console.log('Toggled:', value),
});
toggle.mount();

// Show a toast notification
Toast.show({
  message: 'Hello ZUI!',
  duration: 3000,
});

Components

Input Components

| Component | Description | |-----------|-------------| | Button | Interactive button with multiple variants (primary, secondary, destructive, ghost) | | Switch | Toggle switch with iOS-style design | | Stepper | Value stepper with increment/decrement buttons |

Display Components

| Component | Description | |-----------|-------------| | Text | Text display with typography presets and auto-scrolling |

Navigation Components

| Component | Description | |-----------|-------------| | TitleBar | Page title bar with optional back button | | ListItem | Settings/list row with label and accessories | | SectionHeader | Section header for grouping items |

Feedback Components

| Component | Description | |-----------|-------------| | Toast | Lightweight notification | | Loading | Loading indicator |

Layout Components

| Component | Description | |-----------|-------------| | Container | Basic container with padding and background | | Stack | Horizontal/vertical stack layout | | ScrollView | Scrollable content container | | CircularLayout | Layout optimized for circular screens |

Theme System

ZUI includes a comprehensive theme system based on ZeppOS design guidelines:

import { 
  systemColors, 
  textColors, 
  backgroundColors,
  fontSizes,
  spacingScale 
} from '@poke-flow/zui/theme';

// Colors
console.log(systemColors.blue);    // '#0986D4'
console.log(textColors.title);     // '#FFFFFF'
console.log(backgroundColors.primary); // '#000000' (OLED black)

// Typography (480x480)
console.log(fontSizes.body);       // { size: 32, lineHeight: 40 }

// Spacing
console.log(spacingScale.md);      // 16

Animations

Built-in animation utilities with easing functions:

import { animator, easeOut, easeInOut } from '@poke-flow/zui/animations';

// Animate a widget
animator.animate(widget, {
  property: 'x',
  from: 0,
  to: 100,
  duration: 300,
  easing: 'easeOut',
});

Usage in ZeppOS Project

After installing, import components in your ZeppOS pages:

// pages/settings/index.js
import { TitleBar, ListItem, Switch, Stepper } from '@poke-flow/zui';

Page({
  build() {
    // Create title bar
    const titleBar = new TitleBar({
      title: 'Settings',
      y: 50,
      screenWidth: 480,
    });
    titleBar.mount();

    // Create a list item with switch
    const vibrationSwitch = new Switch({ value: true });
    const listItem = new ListItem({
      label: 'Vibration',
      x: 50,
      y: 140,
      width: 380,
      accessory: 'custom',
      customAccessory: vibrationSwitch,
    });
    listItem.mount();
  },

  onDestroy() {
    // Cleanup
    titleBar.destroy();
    listItem.destroy();
  }
});

Design Principles

ZUI follows ZeppOS 3.0 design values:

• Natural - Natural recognition and interaction
• Simple - Simple interface, easy to understand
• Symbiosis - Experience and value symbiosis

Visual Guidelines

• Color System - Derived from nature, warm and diverse
• Typography - Noto Sans font, minimum 24px for readability
• Spacing - 4px grid system
• Touch Targets - Minimum 48x48px for accessibility

API Reference

Full API documentation is available in the docs folder.

Contributing

Contributions are welcome! Please read our contributing guidelines.

License

MIT © PokeFlow