August Design System

A comprehensive React Native design system following Apple Human Interface Guidelines. Build beautiful, accessible, and consistent UIs for iOS, Android, and Web.

Features

• Apple HIG Compliant - Follows iOS design patterns and accessibility guidelines
• Cross-Platform - Works on iOS, Android, and Web (React Native Web)
• Fully Typed - Complete TypeScript support with comprehensive types
• Themeable - Light/dark mode support with customizable design tokens
• Accessible - Built-in accessibility hooks (reduced motion, screen reader, dynamic type)
• 30+ Components - Foundation primitives, core UI, and chat SDK components
• Rich Design Tokens - Colors, typography, spacing, shadows, radius, animations

Installation

npm install august-design-system
# or
yarn add august-design-system

Peer Dependencies

Ensure you have the peer dependencies installed:

npm install react react-native

For web support:

npm install react-native-web

Additional Dependencies

The design system uses these packages for enhanced functionality:

• react-native-gesture-handler - Touch interactions
• react-native-reanimated - Animations
• react-native-safe-area-context - Safe area handling
• react-native-svg - SVG rendering
• react-native-vector-icons - Icon support

Quick Start

Wrap your app with the ThemeProvider:

import { ThemeProvider, Button } from 'august-design-system';

function App() {
  return (
    <ThemeProvider>
      <Button title="Get Started" onPress={() => console.log('Pressed!')} />
    </ThemeProvider>
  );
}

Documentation

View the full documentation and interactive examples:

Storybook Documentation

Components

Foundation Primitives

Component	Description
Box	Flexible layout primitive with theme-aware styling
Pressable	Enhanced touchable with haptic feedback and press states
Icon	Platform-native icon component
Button	Interactive button with multiple variants (filled, tinted, gray, outlined, ghost)
Spinner	Loading indicator with customizable size
Divider	Visual separator component
Toast	Notification component with ToastProvider
SearchBar	iOS-style search input
EmptyState	Placeholder content for empty views

Core UI Components

Component	Description
Switch	iOS-style toggle switch
Badge	Generic badge (count, dot, label variants)
Progress	Linear and circular progress indicators
Alert	Inline notification/banner component
Card	Content grouping container
Header	Navigation bar (iOS navigation bar style)
Modal	Centered modal dialog
Sheet	Bottom sheet modal surface
ListItem	Configurable list row (iOS table view cell style)
TabBar	Bottom tab bar navigation
ActionMenu	Contextual action menu (iOS context menu style)
MessageReactions	Emoji reactions for messages

Chat SDK Components

Component	Description
Avatar	User avatar with initials fallback and group support
StatusBadge	Online/offline presence indicator
UnreadBadge	Unread message count badge
TypingIndicator	Animated typing indicator
MessageBubble	Chat message bubble for text, images, and files
InputBar	Message input with attachments and error states
ConversationListItem	Chat list item with badges and status

Hooks

Hook	Description
useTheme	Access theme context (colors, toggleColorMode, isDark)
useThemedStyles	Create theme-aware stylesheets
useBreakpoint	Current responsive breakpoint
useResponsiveValue	Responsive values based on screen size
useDeviceType	Detect device type (phone, tablet, desktop)
useReducedMotion	Respect reduced motion preferences
useAccessibleAnimation	Animations respecting accessibility settings
useScreenReader	Detect screen reader status
useDynamicType	Support iOS dynamic type scaling
useHighContrast	Detect high contrast mode

Usage Examples

Button Variants

import { Button } from 'august-design-system';

// Filled button (default)
<Button title="Primary" variant="filled" colorScheme="primary" />

// Outlined button
<Button title="Cancel" variant="outlined" colorScheme="neutral" />

// Destructive button
<Button title="Delete" variant="filled" colorScheme="destructive" />

// Loading state
<Button title="Save" loading loadingText="Saving..." />

Core UI Components

import {
  Card,
  Badge,
  Switch,
  Alert,
  ListItem,
  Header,
  SearchBar,
  Progress,
} from 'august-design-system';

// Card with content
<Card title="Settings" subtitle="Manage your preferences">
  <ListItem title="Notifications" accessory={<Switch value={true} />} />
  <ListItem title="Dark Mode" accessory={<Switch value={false} />} />
</Card>

// Badges
<Badge variant="count" count={5} />
<Badge variant="dot" colorScheme="success" />
<Badge variant="label" label="New" />

// Alert
<Alert
  type="info"
  title="Update Available"
  message="A new version is ready to install"
  onDismiss={() => {}}
/>

// Header
<Header
  title="Messages"
  leftAction={{ icon: 'arrow-back', onPress: goBack }}
  rightAction={{ icon: 'settings', onPress: openSettings }}
/>

// SearchBar
<SearchBar
  placeholder="Search conversations..."
  value={query}
  onChangeText={setQuery}
/>

// Progress
<Progress value={0.75} variant="linear" />
<Progress value={0.5} variant="circular" />

Chat Components

import {
  Avatar,
  MessageBubble,
  InputBar,
  ConversationListItem,
  TypingIndicator,
} from 'august-design-system';

// Avatar with status
<Avatar name="John Doe" size="lg" status="online" />

// Group avatar
<Avatar
  group={[
    { name: 'Alice' },
    { name: 'Bob' },
    { name: 'Charlie' },
  ]}
  size="md"
/>

// Message bubble
<MessageBubble
  direction="outgoing"
  text="Hello! How are you?"
  timestamp={new Date()}
  status="read"
/>

// Typing indicator
<TypingIndicator users={['Alice', 'Bob']} />

// Conversation list item
<ConversationListItem
  id="conv-1"
  title="John Doe"
  subtitle="Hey, how are you?"
  timestamp={new Date()}
  unreadCount={3}
  avatarName="John Doe"
  presenceStatus="online"
  onPress={() => openChat('conv-1')}
/>

Theming

import { ThemeProvider, useTheme, createTheme } from 'august-design-system';

// Use the theme hook
function MyComponent() {
  const { theme, isDark, toggleColorMode } = useTheme();

  return (
    <View style={{ backgroundColor: theme.colors.background.primary }}>
      <Text style={{ color: theme.colors.label.primary }}>
        Hello World
      </Text>
    </View>
  );
}

// Custom theme
const customTheme = createTheme({
  colors: {
    interactive: {
      tint: '#FF6B6B',
    },
  },
});

<ThemeProvider theme={customTheme}>
  <App />
</ThemeProvider>

Design Tokens

Access design tokens directly:

import { spacing, typography, radius, lightColors } from 'august-design-system/tokens';

const styles = StyleSheet.create({
  container: {
    padding: spacing.lg,      // 16pt
    borderRadius: radius.md,  // 12pt
  },
  text: {
    ...typography.body,
    color: lightColors.label.primary,
  },
});

useThemedStyles Hook

Create theme-aware stylesheets:

import { useThemedStyles } from 'august-design-system';

function MyComponent() {
  const styles = useThemedStyles((theme) => ({
    container: {
      backgroundColor: theme.colors.background.primary,
      padding: theme.spacing.lg,
    },
    title: {
      ...theme.typography.headline,
      color: theme.colors.label.primary,
    },
  }));

  return (
    <View style={styles.container}>
      <Text style={styles.title}>Themed Content</Text>
    </View>
  );
}

Accessibility Hooks

import {
  useReducedMotion,
  useAccessibleAnimation,
  useDynamicType,
} from 'august-design-system';

function AnimatedComponent() {
  const prefersReducedMotion = useReducedMotion();
  const animConfig = useAccessibleAnimation({
    duration: 300,
    useNativeDriver: true,
  });

  // Animation respects user's motion preferences
}

function ScaledText() {
  const { fontScale } = useDynamicType();

  // Text scales with iOS dynamic type settings
}

Imports

All exports are available from the main entry point:

import {
  // Components
  Button,
  Card,
  Modal,
  Avatar,

  // Theme
  ThemeProvider,
  useTheme,
  createTheme,

  // Tokens
  spacing,
  typography,
  radius,
  lightColors,

  // Hooks
  useThemedStyles,
  useReducedMotion,
} from 'august-design-system';

Subpath Imports (bundlers with ESM support)

For bundlers that fully support package exports (Webpack, Vite):

import { Button, Card } from 'august-design-system/components';
import { ThemeProvider } from 'august-design-system/theme';
import { spacing } from 'august-design-system/tokens';
import { useThemedStyles } from 'august-design-system/hooks';

Note: Metro bundler (React Native) has experimental support for package exports. If subpath imports don't work, use the main entry point instead.

API Reference

ThemeProvider Props

Prop	Type	Default	Description
theme	ThemeConfig	defaultTheme	Custom theme configuration
colorMode	'light' | 'dark' | 'system'	'system'	Color mode preference
children	ReactNode	-	Child components

Button Props

Prop	Type	Default	Description
title	string	-	Button label text
variant	'filled' | 'tinted' | 'gray' | 'outlined' | 'ghost'	'filled'	Visual style
size	'sm' | 'md' | 'lg'	'md'	Button size
colorScheme	'primary' | 'destructive' | 'success' | 'neutral'	'primary'	Color scheme
disabled	boolean	false	Disable button
loading	boolean	false	Show loading indicator
fullWidth	boolean	false	Take full width
onPress	() => void	-	Press handler

Development

Prerequisites

• Node.js >= 20
• React Native development environment set up

Running Locally

# Install dependencies
npm install

# Run Storybook (interactive component playground)
npm run storybook

# Run on iOS
npm run ios

# Run on Android
npm run android

# Run on Web
npm run web

# Build the library
npm run build

# Run type checking
npm run typecheck

# Run tests
npm test

Building Storybook

npm run build-storybook

Contributing

Contributions are welcome! Please read our contributing guidelines before submitting a pull request.

License

MIT License - see LICENSE for details.

---

Built with love for the React Native community.