CODITECT Mobile-First Design System

Version: 1.0.0 Date: 2025-10-08 Status: ✅ PRODUCTION READY

---

Philosophy

CODITECT is mobile-first with touch-friendly interactions. Every UI element is designed for fingers, not mouse cursors.

Core Principles

1. Touch Targets: Minimum 44x44px (WCAG AAA standard)
2. Click-to-Open, Click-to-Close: Accordion/card-based navigation
3. One Thing at a Time: Progressive disclosure, minimal cognitive load
4. Responsive: Works perfectly on 320px (iPhone SE) to 4K displays
5. Accessibility: WCAG 2.1 AAA compliance
6. Performance: Fast interactions, no jank

---

Touch Target Guidelines

Minimum Sizes

Element	Minimum Size	Recommended	Notes
Button	44x44px	56x56px	Primary actions use 56px
Input Field	44px height	56px height	Full width on mobile
Switch/Toggle	44x44px	48x48px	Large size variant
Icon Button	44x44px	48x48px	With visual feedback
Card Header	56px height	60px height	Easy to tap
Select Dropdown	44px height	56px height	Native feel

Spacing

Area	Size	Purpose
Touch padding	12-16px	Around tappable elements
Card spacing	16-24px	Between cards
Content padding	16px mobile, 24px desktop	Inside containers
Section spacing	32-48px	Major section separation

---

Component Library

1. TouchFriendlyCard

File: /src/components/touch-friendly-card.tsx

Purpose: Collapsible card with large touch target

Features:

• Click header to expand/collapse
• 60px header (easy tapping)
• Smooth animations
• Icons for visual recognition
• Progressive disclosure

Usage:

<TouchFriendlyCard
  title="Settings"
  icon={FiSettings}
  iconColor="blue.500"
  defaultOpen={false}
>
  {/* Content goes here */}
</TouchFriendlyCard>

Props:

interface TouchFriendlyCardProps {
  title: string                    // Card title
  icon?: IconType                  // Optional icon (react-icons)
  iconColor?: string               // Icon color (Chakra color)
  children: React.ReactNode        // Card content
  isOpen?: boolean                 // Controlled state
  onToggle?: () => void            // Controlled toggle handler
  defaultOpen?: boolean            // Uncontrolled default state
}

Example:

import { TouchFriendlyCard } from '../components/TouchFriendlyCard'
import { FiUser } from 'react-icons/fi'

<TouchFriendlyCard title="Profile" icon={FiUser} iconColor="purple.500" defaultOpen>
  <FormControl>
    <FormLabel>Name</FormLabel>
    <Input size="lg" height="56px" />
  </FormControl>
</TouchFriendlyCard>

---

2. Origami Components (Legacy/Optional)

Files:

• /src/components/origami-card.tsx - Stat cards with 3D effect
• /src/components/origami-accordion.tsx - Accordion container
• /src/components/origami-section.tsx - Accordion section

When to Use:

• Origami: Dashboard stats, metrics, visual flair
• TouchFriendly: Settings, forms, mobile-first interactions

Migration Path: Use TouchFriendlyCard for new components.

---

Design Patterns

Pattern 1: Settings Pages

Anti-pattern ❌:

// DON'T: Tabs are hard to tap on mobile
<Tabs>
  <TabList>
    <Tab>Appearance</Tab>
    <Tab>editor</Tab>
    <Tab>Security</Tab>
  </TabList>
  <TabPanels>...</TabPanels>
</Tabs>

Best practice ✅:

// DO: Accordion cards are touch-friendly
<VStack spacing={6}>
  <TouchFriendlyCard title="Appearance" icon={FiEye} defaultOpen>
    {/* Settings */}
  </TouchFriendlyCard>

  <TouchFriendlyCard title="editor" icon={FiCode}>
    {/* Settings */}
  </TouchFriendlyCard>

  <TouchFriendlyCard title="Security" icon={FiLock}>
    {/* Settings */}
  </TouchFriendlyCard>
</VStack>

---

Pattern 2: Forms

All form inputs must meet touch standards:

// Input fields - 56px height
<Input
  size="lg"
  height="56px"
  placeholder="Enter text..."
/>

// Select dropdowns - 56px height
<Select
  size="lg"
  height="56px"
>
  <option>Option 1</option>
</Select>

// Switches - large size
<Switch size="lg" />

// Buttons - 56px height, full width on mobile
<Button
  size="lg"
  height="56px"
  w={{ base: '100%', md: 'auto' }}
>
  Submit
</Button>

---

Pattern 3: Card-Based Navigation

Anti-pattern ❌:

// DON'T: Small links hard to tap
<VStack>
  <Link fontSize="sm">Settings</Link>
  <Link fontSize="sm">Profile</Link>
  <Link fontSize="sm">Security</Link>
</VStack>

Best practice ✅:

// DO: Large tappable cards
<VStack spacing={4}>
  <TouchFriendlyCard title="Settings" icon={FiSettings}>
    <Text>Manage your preferences</Text>
  </TouchFriendlyCard>

  <TouchFriendlyCard title="Profile" icon={FiUser}>
    <Text>Update your information</Text>
  </TouchFriendlyCard>
</VStack>

---

Responsive Breakpoints

const breakpoints = {
  base: '0px',      // Mobile first (320px+)
  sm: '480px',      // Small mobile landscape
  md: '768px',      // Tablet portrait
  lg: '992px',      // Tablet landscape
  xl: '1280px',     // Desktop
  '2xl': '1536px'   // Large desktop
}

Usage Examples

// Padding: 16px mobile, 24px desktop
<Box px={{ base: 4, md: 6 }}>

// Width: 100% mobile, auto desktop
<Button w={{ base: '100%', md: 'auto' }}>

// Hide on mobile, show on desktop
<Box display={{ base: 'none', md: 'block' }}>

// Stack vertically on mobile, horizontally on desktop
<Stack direction={{ base: 'column', md: 'row' }}>

---

Accessibility

WCAG 2.1 AAA Compliance

✅ Touch Targets: All interactive elements ≥ 44x44px ✅ Color Contrast: 7:1 for AAA (4.5:1 minimum for AA) ✅ Keyboard Navigation: Full keyboard support ✅ Screen Readers: ARIA labels on all interactive elements ✅ Focus Visible: Clear focus indicators ✅ No Color-Only: Icons + text for all actions

Keyboard Shortcuts

Key	Action
Tab	Navigate forward
Shift+Tab	Navigate backward
Enter / Space	Activate button/toggle card
Escape	Close modal/drawer
Arrow Keys	Navigate within lists

---

Component Examples

Example 1: Profile Page (Mobile-First)

import { TouchFriendlyCard } from '../components/TouchFriendlyCard'
import { FiUser, FiMail, FiLock } from 'react-icons/fi'

export const ProfilePage = () => (
  <Container maxW="container.md" py={6} px={4}>
    <VStack spacing={6} align="stretch">
      <Heading size="lg">Your Profile</Heading>

      <TouchFriendlyCard title="Personal Info" icon={FiUser} defaultOpen>
        <FormControl>
          <FormLabel fontSize="md">Full Name</FormLabel>
          <Input size="lg" height="56px" />
        </FormControl>

        <FormControl>
          <FormLabel fontSize="md">Bio</FormLabel>
          <Textarea size="lg" rows={4} />
        </FormControl>

        <Button size="lg" height="56px" w="100%" colorScheme="blue">
          Save Changes
        </Button>
      </TouchFriendlyCard>

      <TouchFriendlyCard title="Email Settings" icon={FiMail}>
        <FormControl>
          <FormLabel fontSize="md">Email Address</FormLabel>
          <Input type="email" size="lg" height="56px" />
        </FormControl>

        <FormControl display="flex" alignItems="center" minH="56px">
          <FormLabel mb={0} flex="1">Email Notifications</FormLabel>
          <Switch size="lg" />
        </FormControl>
      </TouchFriendlyCard>

      <TouchFriendlyCard title="Password" icon={FiLock}>
        <FormControl>
          <FormLabel fontSize="md">Current Password</FormLabel>
          <Input type="password" size="lg" height="56px" />
        </FormControl>

        <FormControl>
          <FormLabel fontSize="md">New Password</FormLabel>
          <Input type="password" size="lg" height="56px" />
        </FormControl>

        <Button size="lg" height="56px" w="100%" colorScheme="red">
          Change Password
        </Button>
      </TouchFriendlyCard>
    </VStack>
  </Container>
)

---

Example 2: Settings Page (Reference Implementation)

See: /src/pages/settings-page.tsx

Features:

• 5 collapsible sections (Appearance, editor, llm, Privacy, Security)
• All inputs 56px height
• Large switches
• Full-width buttons on mobile
• First section open by default
• Touch-optimized spacing

---

Migration Guide

Updating Existing Components

Before (❌ Not Touch-Friendly)

<Tabs>
  <TabList>
    <Tab fontSize="sm">Settings</Tab>
  </TabList>
  <TabPanels>
    <TabPanel>
      <FormControl>
        <FormLabel fontSize="xs">Name</FormLabel>
        <Input size="sm" />
      </FormControl>
      <Button size="sm">Save</Button>
    </TabPanel>
  </TabPanels>
</Tabs>

After (✅ Touch-Friendly)

<VStack spacing={6}>
  <TouchFriendlyCard title="Settings" icon={FiSettings} defaultOpen>
    <FormControl>
      <FormLabel fontSize="md">Name</FormLabel>
      <Input size="lg" height="56px" />
    </FormControl>

    <Button size="lg" height="56px" w="100%">
      Save
    </Button>
  </TouchFriendlyCard>
</VStack>

Checklist

When migrating a component to mobile-first:

• Replace tabs with TouchFriendlyCard accordions
• Update all Input to size="lg" and height="56px"
• Update all Select to size="lg" and height="56px"
• Update all Switch to size="lg"
• Update all Button to size="lg" and height="56px"
• Make buttons full-width on mobile: w={{ base: '100%', md: 'auto' }}
• Add minH="56px" to form rows with switches
• Update FormLabel to fontSize="md" (not "sm" or "xs")
• Add container padding: px={4} mobile, px={6} desktop
• Test on mobile viewport (320px width)

---

Testing

Manual Testing Checklist

Mobile (320px-767px)

• All buttons/inputs easily tappable with thumb
• No horizontal scroll
• Cards stack vertically
• Full-width buttons
• Spacing comfortable (not cramped)
• Text readable without zoom (16px minimum)

Tablet (768px-991px)

• Cards may have 2-column grid if appropriate
• Buttons still large enough
• Sidebars collapsible

Desktop (992px+)

• Buttons can be auto-width
• Multi-column layouts allowed
• Hover states work
• Keyboard navigation smooth

Device Testing

Test on real devices:

• iPhone SE (320px width) - Smallest viewport
• iPhone 14 Pro (390px width)
• iPad Mini (768px width)
• iPad Pro (1024px width)
• Desktop (1280px+ width)

---

Design Tokens

Colors

// Primary actions
colorScheme="blue"   // Save, Submit, Confirm
colorScheme="green"  // Success, Enabled
colorScheme="red"    // Delete, Danger, Password
colorScheme="orange" // Warning
colorScheme="purple" // Profile, User
colorScheme="teal"   // Privacy, Settings

Icon Colors

// Semantic colors for icons
FiUser: "purple.500"
FiSettings: "blue.500"
FiLock: "red.500"
FiShield: "teal.500"
FiCode: "green.500"
FiCpu: "orange.500"
FiEye: "purple.500"

---

Best Practices

DO ✅

1. Use TouchFriendlyCard for all settings/forms
2. Size="lg" and height="56px" for all inputs
3. Full-width buttons on mobile
4. Icons with labels (not icon-only)
5. Progressive disclosure (cards closed by default)
6. Test on 320px viewport
7. Minimum 16px padding on mobile
8. Use VStack with spacing={6} between cards

DON'T ❌

1. Don't use tabs on mobile - Use accordion cards
2. Don't use size="sm" or size="md" - Always "lg" for touch
3. Don't use icon-only buttons - Add text labels
4. Don't use small touch targets (<44px) - Always ≥56px
5. Don't assume mouse hover - Design for touch first
6. Don't use tooltips as primary info - They don't work on touch
7. Don't nest accordions - Keep navigation flat
8. Don't use horizontal scroll - Stack vertically on mobile

---

Performance

Optimization Tips

1. Lazy load accordion content - Use React.lazy() for heavy sections
2. Virtualize long lists - Use react-window for 100+ items
3. Debounce inputs - 300ms delay for search/filter
4. Optimize animations - Use CSS transforms, not top/left
5. Minimize re-renders - Use React.memo() on heavy components

---

Future Enhancements

Planned Features

• Swipe gestures - Swipe to delete, swipe to navigate
• Pull to refresh - Refresh data with pull gesture
• Bottom sheet - Modal alternative for mobile
• Haptic feedback - Vibration on key actions (with permission)
• Dark mode optimization - OLED-friendly pure black option
• Offline mode - Service worker with offline UI

---

Resources

Design References

• Apple Human Interface Guidelines
• Material Design Touch Targets
• WCAG 2.1 AAA Guidelines

Code Examples

• ✅ Settings Page: /src/pages/settings-page.tsx
• ✅ Touch Card: /src/components/touch-friendly-card.tsx
• ⏳ Profile Page: Planned upgrade
• ⏳ Chat Panel: Planned upgrade

---

Summary

CODITECT's mobile-first design ensures:

✅ Every element is touch-friendly (≥56px targets) ✅ Card-based navigation (click to open/close) ✅ Progressive disclosure (one thing at a time) ✅ Responsive (320px to 4K) ✅ Accessible (WCAG 2.1 AAA) ✅ Performant (smooth 60fps animations)

Use TouchFriendlyCard everywhere. Make everything large. Test on mobile first.

---

Document Version: 1.0.0 Last Updated: 2025-10-08 Status: ✅ PRODUCTION STANDARD