Skip to main content

​
Design Principles for Base MiniApps

These principles guide the creation of high-quality, user-friendly MiniApps that feel native within the Base App ecosystem. Inspired by Apple’s Human Interface Guidelines, they’re adapted for the unique constraints and opportunities of webview-based mini applications.

​
Core Principles

​
Clarity

Make purpose and functionality immediately clear through design and content.
  • Immediate Value: Users should understand your app’s purpose within 5 seconds - Visual Hierarchy: Use size, color, and spacing to guide attention - Plain Language: Avoid crypto jargon and technical terms in primary UI - Clear Actions: Button text describes outcomes, not mechanisms
Example Copy Transformation: 
- "Connect your wallet to authenticate and view your NFT portfolio"
+ "View your collectibles and track their value"

​
Deference

Respect the Base App environment and don’t obstruct the native experience.
  • Safe Areas: Respect iOS/Android safe areas and Base App chrome - Native Feel: Follow platform conventions for navigation and interaction
  • Seamless Integration: Feel like part of Base App, not a separate website - Performance: Load quickly without blocking the main app
CSS Safe Area Implementation: 
:root {
  --inset-top: env(safe-area-inset-top);
  --inset-bottom: env(safe-area-inset-bottom);
  --inset-left: env(safe-area-inset-left);
  --inset-right: env(safe-area-inset-right);
}

.app-container {
  padding-top: var(--inset-top);
  padding-bottom: var(--inset-bottom);
  padding-left: var(--inset-left);
  padding-right: var(--inset-right);
}

​
Depth

Use motion and layering thoughtfully to create intuitive user experiences.
  • Purposeful Motion: Animations should guide attention and provide feedback - Subtle Transitions: Prefer slide-ins over full-screen spinners - Visual Feedback: Confirm actions with appropriate micro-interactions - Accessibility: Honor prefers-reduced-motion user settings
Motion Implementation: 
/* Respect user preferences */
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
  }
}

/* Standard transitions */
.button {
  transition: all 0.2s ease-out;
}

.slide-in {
  animation: slideIn 0.3s ease-out;
}

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

​
Design Tokens

​
Typography Scale

Use Base App’s typography tokens for consistency: 
:root {
  /* Heading Sizes */
  --text-xl: 1.25rem; /* 20px - Page titles */
  --text-lg: 1.125rem; /* 18px - Section headers */
  --text-base: 1rem; /* 16px - Body text */
  --text-sm: 0.875rem; /* 14px - Captions */
  --text-xs: 0.75rem; /* 12px - Labels */

  /* Line Heights */
  --leading-tight: 1.25;
  --leading-normal: 1.5;
  --leading-relaxed: 1.625;
}

​
Color System

Support both light and dark themes: 
:root {
  /* Light Theme */
  --primary: #0052ff;
  --primary-hover: #0040cc;
  --background: #ffffff;
  --surface: #f8f9fa;
  --text-primary: #111111;
  --text-secondary: #6b7280;
  --border: #e5e7eb;
}

@media (prefers-color-scheme: dark) {
  :root {
    /* Dark Theme */
    --primary: #4285ff;
    --primary-hover: #5a95ff;
    --background: #0b0b0c;
    --surface: #1a1a1b;
    --text-primary: #ffffff;
    --text-secondary: #9ca3af;
    --border: #374151;
  }
}

​
Spacing Scale

Consistent spacing using 4px base unit: 
:root {
  --space-1: 0.25rem; /* 4px */
  --space-2: 0.5rem; /* 8px */
  --space-3: 0.75rem; /* 12px */
  --space-4: 1rem; /* 16px */
  --space-6: 1.5rem; /* 24px */
  --space-8: 2rem; /* 32px */
  --space-12: 3rem; /* 48px */
  --space-16: 4rem; /* 64px */
}

​
Touch Targets

Ensure accessibility with proper touch target sizes: 
/* Minimum touch target size */
.interactive {
  min-height: 44px;
  min-width: 44px;

  /* For smaller visual elements, add padding */
  padding: var(--space-3);
}

/* Button sizing */
.button-sm {
  height: 36px;
  padding: 0 var(--space-3);
}
.button-md {
  height: 44px;
  padding: 0 var(--space-4);
}
.button-lg {
  height: 52px;
  padding: 0 var(--space-6);
}

​
Layout Patterns

​
Grid System

Use CSS Grid for responsive layouts: 
.grid {
  display: grid;
  gap: var(--space-4);
  padding: var(--space-4);
}

/* Common layouts */
.grid-2 {
  grid-template-columns: repeat(2, 1fr);
}
.grid-3 {
  grid-template-columns: repeat(3, 1fr);
}

/* Responsive grid */
.grid-auto {
  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
}

​
Card Components

Standard card styling: 
.card {
  background: var(--surface);
  border: 1px solid var(--border);
  border-radius: 12px;
  padding: var(--space-4);
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
}

.card-interactive {
  transition: all 0.2s ease-out;
  cursor: pointer;
}

.card-interactive:hover {
  box-shadow: 0 4px 12px rgba(0, 0, 0, 0.15);
  transform: translateY(-1px);
}

​
Common Mistakes to Avoid

​
❌ Layout Issues

  • Ignoring safe areas: Content gets cut off by device notches or home indicators
  • Fixed positioning: Overlapping Base App navigation elements
  • Inconsistent spacing: Using arbitrary pixel values instead of design tokens

​
❌ Typography Problems

  • Poor contrast: Text that’s hard to read in light or dark mode
  • Inconsistent sizing: Not using the typography scale
  • Too small text: Body text smaller than 16px on mobile

​
❌ Interaction Issues

  • Tiny touch targets: Interactive elements smaller than 44px
  • Missing feedback: No visual response to user actions
  • Broken animations: Not respecting prefers-reduced-motion

​
❌ Copy and Content

  • Crypto jargon: Using “connect wallet” instead of “continue”
  • Unclear value: Not explaining what the app does upfront
  • Technical language: Using protocol terms in user-facing text

​
Design Review Checklist

Before submitting your MiniApp:
  • Typography: Uses Base App typography tokens
  • Colors: Supports both light and dark themes
  • Spacing: Consistent spacing using design tokens
  • Touch Targets: All interactive elements ≥ 44px
  • Safe Areas: Properly implemented using CSS environment variables
  • Motion: Respects user motion preferences
  • Copy: Clear, jargon-free language focused on user benefits
  • Visual Hierarchy: Clear information hierarchy guides user attention

​
Resources

These principles are enforced through the Quality Bar checklist. Apps that don’t follow these guidelines will not be eligible for featuring in Base App.