Design Guidelines

This page gives you quick, visual rules to meet a high design standard for mini apps. Follow these patterns to create polished, native-feeling experiences within Watchee.

Grid and Spacing

Usage

Use an 8px base unit for all spacing. This creates consistent rhythm and alignment throughout your mini app.

Token	Value	Usage
xs	4px	Tight spacing, icon gaps
sm	8px	Default element gaps
md	16px	Section spacing, card padding
lg	24px	Default page padding
xl	32px	Section separators
2xl	48px	Large section gaps

Paddings

Usage

Padding is set to a default of 24px, providing ample breathing room around elements while maintaining a clean and structured appearance.

/* Default page padding */
.page-content {
  padding: 24px;
}

/* Card padding */
.card {
  padding: 16px;
}

Navigation Bar

Usage

The navigation bar should be 64px in height (plus safe area inset). Keep the right side clear for system controls provided by Watchee. All other content can be customized.

<header className="sticky top-0 z-50 bg-primary/95 backdrop-blur-md border-b pt-safe-top">
  <div className="flex items-center justify-between px-6 h-16">
    {/* Your content here */}
  </div>
</header>

Guidelines:

• Height: 64px content area + safe area inset
• Horizontal padding: 24px
• Background: Use blur effect for depth (backdrop-blur-md)
• Keep right corner clear for Watchee system controls

Main Pages

Content Spacing

Relationship	Spacing
Header to content	16px
Elements within section	16px
Between sections	32px
Search bar to content	24px
Header to sub-headline section	24px
Last item to bottom bar	32px

Best Practices

1. One clear task per page - Focus each screen on a single primary action
2. Keep CTAs visible - Primary buttons should be immediately visible without scrolling
3. Minimize unnecessary scrolling - Prioritize above-the-fold content
4. Prioritize primary actions - Use visual hierarchy to guide users

Secondary Pages

Usage

Secondary pages (detail views, forms, etc.) follow slightly different spacing rules:

Relationship	Spacing
Header to content	24px
Header to secondary title	32px
Secondary title to description	12px

Tab Bar (Android vs iOS)

Usage

Navigation bar is positioned with a 12px space from the iOS & Android bottom system bar, ensuring optimal accessibility and comfortable tap areas.

.tab-bar {
  position: fixed;
  bottom: 0;
  left: 0;
  right: 0;
  padding-bottom: calc(12px + env(safe-area-inset-bottom));
}

Guidelines:

• Tab bar height: 56px (content) + safe area
• Gap above system bar: 12px
• Minimum tap target: 44x44px

Drawers / Sheets

Usage

Bottom sheets and drawers should maintain 12px spacing from the device's bottom bar.

.drawer-content {
  padding-bottom: calc(12px + env(safe-area-inset-bottom));
}

Guidelines:

• Handle/grabber: 4px height, 36px width, centered
• Top padding: 12px above handle
• Corner radius: 16px (top corners only)

Toasts

Usage

Toast messages should be horizontally centered and positioned directly below the header to ensure visibility without disrupting user interaction.

.toast {
  position: fixed;
  top: calc(64px + env(safe-area-inset-top) + 12px);
  left: 50%;
  transform: translateX(-50%);
  max-width: calc(100% - 48px);
}

Guidelines:

• Position: Below header, horizontally centered
• Max width: Screen width - 48px (24px padding each side)
• Auto-dismiss: 3-5 seconds for informational, persistent for errors

Keyboard Handling

Usage

When the keyboard is active, buttons and interactive elements should be positioned 24px above the keyboard to prevent accidental taps.

// React Native / Expo
import { KeyboardAvoidingView, Platform } from 'react-native';

<KeyboardAvoidingView 
  behavior={Platform.OS === 'ios' ? 'padding' : 'height'}
  keyboardVerticalOffset={24}
>
  {/* Your form content */}
</KeyboardAvoidingView>

Web Implementation:

.form-actions {
  position: fixed;
  bottom: 24px;
  /* Use JS to detect keyboard and adjust */
}

Bottom Safe Area

Usage

Buttons and interactive elements at the bottom of the screen should maintain 24px spacing from the safe area, ensuring optimal accessibility.

.bottom-actions {
  position: fixed;
  bottom: 0;
  left: 0;
  right: 0;
  padding: 24px;
  padding-bottom: calc(24px + env(safe-area-inset-bottom));
}

States

Usage

Center-align empty states, loading indicators, and other transient states both horizontally and vertically. This creates visual consistency across various screen sizes.

// Empty State
<div className="flex flex-col items-center justify-center min-h-[50vh] text-center px-6">
  <Icon className="w-16 h-16 text-gray-400 mb-4" />
  <h3 className="text-lg font-semibold mb-2">No Items Yet</h3>
  <p className="text-secondary mb-6">Start by adding your first item</p>
  <Button>Add Item</Button>
</div>

// Loading State
<div className="flex items-center justify-center min-h-[50vh]">
  <Spinner />
</div>

Color & Theming

Light Mode (Default)

:root {
  --bg-primary: #FFFFFF;
  --bg-secondary: #F7F7F7;
  --bg-tertiary: #EFEFEF;
  --text-primary: #222222;
  --text-secondary: #717171;
  --text-tertiary: #B0B0B0;
}

Dark Mode

@media (prefers-color-scheme: dark) {
  :root {
    --bg-primary: #121212;
    --bg-secondary: #1E1E1E;
    --bg-tertiary: #2A2A2A;
    --text-primary: #FFFFFF;
    --text-secondary: #A0A0A0;
    --text-tertiary: #6B6B6B;
  }
}

Typography

Element	Size	Weight	Line Height
Page Title	24px	700	1.2
Section Header	18px	600	1.3
Body	16px	400	1.5
Caption	14px	400	1.4
Small	12px	400	1.4

Touch Targets

Minimum touch target size should be 44x44px to ensure comfortable interaction:

.touchable {
  min-height: 44px;
  min-width: 44px;
  display: flex;
  align-items: center;
  justify-content: center;
}

Animations

Use subtle animations to provide feedback and delight:

/* Standard transition */
.element {
  transition: all 200ms ease;
}

/* Touch feedback */
.touchable:active {
  transform: scale(0.98);
  opacity: 0.9;
}

/* Entrance animations */
@keyframes fadeIn {
  from { opacity: 0; }
  to { opacity: 1; }
}

@keyframes slideUp {
  from { 
    opacity: 0; 
    transform: translateY(20px); 
  }
  to { 
    opacity: 1; 
    transform: translateY(0); 
  }
}

Quick Reference

Element	Value
Default padding	24px
Navigation bar height	64px + safe area
Tab bar height	56px + safe area
Minimum touch target	44x44px
Section spacing	32px
Element spacing	16px
Bottom button spacing	24px from safe area
Toast position	12px below header
Keyboard offset	24px
Border radius (cards)	16px
Border radius (buttons)	12px
Border radius (inputs)	8px

---

These guidelines are inspired by World's Mini App Design Guidelines and adapted for the Watchee ecosystem.