Instruction file imported from persist-os/plansandschemes (.cursor/rules/mobile_friendliness_patterns.mdc). Copyright stays with the author.

🚨 THE THREE NON-NEGOTIABLES (ZERO TOLERANCE) (Added 2025-01-25)

1. 📱 MOBILE RESPONSIVENESS (MANDATORY)

2. 🌓 LIGHT MODE + DARK MODE (MANDATORY)

3. 🧩 MODULARITY + EXISTING COMPONENTS (MANDATORY)

→reference|pattern:PT:41|file:patterns.mdc|component_first_development:true

📱 RESPONSIVE BREAKPOINT SYSTEM

●breakpoints|frame:Ω:CONSTRUCTION|system:tailwind

Standard Breakpoints (Tailwind)

Breakpoint Usage Pattern

●pattern|id:mobile_first|frame:Ω:CONSTRUCTION|method:mobile_then_desktop

/* Mobile-first: Write mobile styles first */
.class-name {
  /* Mobile styles (default) */
  width: 100%;
  padding: 1rem;
}

/* Desktop override: Use md: for desktop */
.md\:class-name {
  /* Desktop styles (override) */
  width: 50%;
  padding: 2rem;
}

→critical|always:write_mobile_first|then:override_with_md

🎨 Z-INDEX HIERARCHY SYSTEM (MANDATORY)

Z-Index Layers (Highest to Lowest)

Z-Index Usage Rules

Verification Commands

👆 TOUCH TARGET STANDARDS (MANDATORY)

●touch_targets|frame:Ω:CONSTRUCTION|mandatory:true|standards:apple_hig_material_design

Minimum Touch Target Size

Touch Target Implementation

●pattern|touch_target_implementation|frame:Ω:CONSTRUCTION

// ✅ CORRECT: Minimum 44px touch target
<button className="min-h-[44px] min-w-[44px] px-4 py-2">
  Tap Me
</button>

// ❌ WRONG: Too small (< 44px)
<button className="h-8 w-8">
  <Icon />
</button>

Touch Target Checklist

📐 MOBILE NAVIGATION PATTERNS

●patterns|mobile_navigation|frame:Ω:CONSTRUCTION|count:3

Pattern 1: Hamburger Menu (Mobile)

Pattern 2: Back Button Coordination

Pattern 3: Command Palette Mobile

🎨 TYPOGRAPHY & READABILITY

●typography|frame:Ω:CONSTRUCTION|mobile:standards

Mobile Typography Standards

Responsive Typography Pattern

●pattern|responsive_typography|frame:Ω:CONSTRUCTION

// ✅ CORRECT: Mobile-first typography
<p className="text-base md:text-lg">
  Readable text
</p>

// ❌ WRONG: Too small on mobile
<p className="text-sm">
  Hard to read
</p>

♿ ACCESSIBILITY REQUIREMENTS (MANDATORY)

●accessibility|frame:Ω:CONSTRUCTION|mandatory:true|standard:wcag_aa

WCAG AA Compliance (Minimum)

●wcag_aa|requirements:5 →color_contrast:4_5_1_normal_text|3_1_large_text →touch_targets:44px_x_44px_minimum →focus_indicators:visible_rings_2px_minimum →keyboard_navigation:all_interactive_keyboard_accessible →screen_readers:aria_labels_semantic_html_landmarks

ARIA Label Pattern

●pattern|aria_label|frame:Ω:CONSTRUCTION

// ✅ CORRECT: Descriptive ARIA label
<button
  aria-label="Open navigation menu"
  onClick={handleToggle}
>
  <MenuIcon />
</button>

// ❌ WRONG: Missing ARIA label
<button onClick={handleToggle}>
  <MenuIcon />
</button>

Focus State Pattern

●pattern|focus_state|frame:Ω:CONSTRUCTION

// ✅ CORRECT: Visible focus ring
<button className="focus:outline-none focus:ring-2 focus:ring-primary focus:ring-offset-2">
  Click me
</button>

// ❌ WRONG: No focus indicator
<button className="outline-none">
  Click me
</button>

Keyboard Navigation Pattern

●pattern|keyboard_navigation|frame:Ω:CONSTRUCTION

// ✅ CORRECT: Keyboard event handlers
<button
  onClick={handleClick}
  onKeyDown={(e) => {
    if (e.key === 'Enter' || e.key === ' ') {
      handleClick()
    }
  }}
>
  Click me
</button>

Colorblind Accessibility Pattern

●pattern|colorblind_accessibility|frame:Ω:CONSTRUCTION

// ✅ CORRECT: Icon + text, not color alone
<button className="flex items-center gap-2">
  <ErrorIcon className="w-5 h-5 text-destructive" />
  <span>Error occurred</span>
</button>

// ❌ WRONG: Color alone
<button className="text-red-500">
  Error occurred
</button>

📱 DEVICE-SPECIFIC CONSIDERATIONS

●devices|frame:Ω:CONSTRUCTION|count:4

Mobile Phones (320px - 767px)

●device|mobile_phones|range:320px_767px →portrait:primary_orientation|optimize:vertical_scrolling →landscape:secondary_orientation|ensure:horizontal_fit →touch:large_targets_swipe_gestures|where:appropriate →performance:optimize_images_lazy_load_content

Tablets (768px - 1023px)

●device|tablets|range:768px_1023px →portrait:similar_to_mobile|more:space →landscape:hybrid_mobile_desktop →touch:targets_still_important|not:just_mouse →layout:more_columns_still_touch_friendly

Small Laptops (1024px - 1279px)

●device|small_laptops|range:1024px_1279px →hybrid:touch_and_mouse_input →layout:desktop_like|ensure:touch_targets_adequate →performance:full_desktop_features_available

Desktop (1280px+)

🚀 PERFORMANCE OPTIMIZATIONS

●performance|frame:Ω:CONSTRUCTION|mobile:standards

Mobile Performance Standards

●performance_standards|count:5 →lighthouse_mobile_score:90_plus|categories:performance_accessibility_best_practices_seo →first_contentful_paint:lt_1_8s →time_to_interactive:lt_3_8s →total_blocking_time:lt_200ms →cumulative_layout_shift:lt_0_1

Image Optimization Pattern

●pattern|image_optimization|frame:Ω:CONSTRUCTION

// ✅ CORRECT: Responsive images with lazy loading
<Image
  src="/image.jpg"
  width={800}
  height={600}
  alt="Description"
  loading="lazy"
  sizes="(max-width: 768px) 100vw, 50vw"
/>

// ❌ WRONG: Unoptimized images
<img src="/large-image.jpg" alt="Description" />

Font Loading Pattern

●pattern|font_loading|frame:Ω:CONSTRUCTION

/* ✅ CORRECT: Font display swap */
@font-face {
  font-family: 'CustomFont';
  src: url('font.woff2') format('woff2');
  font-display: swap; /* Prevents invisible text */
}

🔍 SEO REQUIREMENTS

●seo|frame:Ω:CONSTRUCTION|mobile:standards

Mobile SEO Standards

●seo_standards|count:5 →viewport_meta_tag:width_device_width_initial_scale_1 →theme_color:meta_tag_with_color →mobile_friendly:google_test_passes →semantic_html:proper_heading_hierarchy_landmarks →no_duplicate_content:mobile_desktop_share_html_responsive_not_separate

Semantic HTML Pattern

●pattern|semantic_html|frame:Ω:CONSTRUCTION

// ✅ CORRECT: Semantic HTML structure
<nav aria-label="Main navigation">
  <ul>
    <li><a href="/">Home</a></li>
    <li><a href="/about">About</a></li>
  </ul>
</nav>

// ❌ WRONG: Non-semantic structure
<div>
  <div onClick={handleClick}>Home</div>
  <div onClick={handleClick}>About</div>
</div>

🧪 TESTING CHECKLIST

●testing|frame:Ω:SURGERY|types:4

Device Testing

●device_testing|items:4 →mobile_phone:320px_767px|portrait_and_landscape →tablet:768px_1023px|portrait_and_landscape →small_laptop:1024px_1279px →desktop:gte_1280px|verify:unchanged

Accessibility Testing

●accessibility_testing|items:5 →screen_reader:voiceover_nvda_jaws →keyboard_navigation:tab_enter_escape_arrow_keys →color_contrast_checker:wcag_aa →touch_target_size_checker:44px_minimum →focus_indicator:visibility

Performance Testing

●performance_testing|items:5 →lighthouse_mobile_score:90_plus →page_load_time:lt_3s_on_3g →first_contentful_paint:lt_1_8s →image_optimization:webp_lazy_loading →font_loading:font_display_swap

Browser Testing

●browser_testing|items:4 →safari_ios:latest →chrome_android:latest →firefox_mobile:latest →edge_mobile:latest

📚 LEARNINGS FROM IMPLEMENTATION (2025-01-25)

●learnings|frame:Ω:GARDENING|date:2025-01-25|count:5

Z-Index Hierarchy Conflicts

●learning|z_index_conflicts|date:2025-01-25 →issue:navigation_elements_covered_by_content →solution:established_z_index_hierarchy|z_100_nav_z_80_modals →pattern:always_use_established_values|never:arbitrary_numbers

Mobile Navigation Positioning

Mobile Sidebar Width

●learning|mobile_sidebar_width|date:2025-01-25 →issue:full_width_sidebar_256px_too_wide →solution:compact_dropdown_menu_192px|with:spring_animation →pattern:use_compact_dropdowns_on_mobile|not:full_width_sidebars

NotesTree Mobile View

Touch Target Sizes

●learning|touch_target_sizes|date:2025-01-25 →issue:some_buttons_too_small_lt_44px →solution:minimum_min_h_44px_min_w_44px|for:all_interactive_elements →pattern:always_ensure_44px_minimum|on:mobile

🚨 WALL OF SHAME (Mobile Failures)

✅ VERIFICATION PROTOCOL

●verification|frame:Ω:SURGERY|phases:4

Pre-Implementation Checks

Post-Implementation Checks

Accessibility Checks

●accessibility_checks|items:5 →screen_reader:tested|tools:voiceover_nvda →keyboard_navigation:tested|keys:tab_enter_escape →color_contrast:verified|standard:wcag_aa →focus_indicators:visible →touch_targets:44px_minimum

Performance Checks

●performance_checks|items:4 →lighthouse_mobile_score:90_plus →page_load_time:lt_3s →images:optimized|formats:webp_lazy_loading →fonts:optimized|display:swap

📖 PATTERN REFERENCE

●pattern_reference|frame:Ω:CONSTRUCTION|count:6

Pattern 1: Mobile Navigation Dropdown

●pattern_ref|id:PT:MOBILE_NAV_DROPDOWN|file:global-nav.tsx →pattern:compact_dropdown_menu|width:w_48_192px|animation:spring →z_index:z_90_below_hamburger_button →position:fixed_top_16_left_4

Pattern 2: Responsive Back Button

●pattern_ref|id:PT:RESPONSIVE_BACK_BUTTON|file:omnipresent-back-button.tsx →pattern:mobile_left_16|desktop_left_20 →z_index:z_100_same_as_hamburger_menu

Pattern 3: Mobile Command Palette

●pattern_ref|id:PT:MOBILE_COMMAND_PALETTE|file:dashboard-nav.tsx →pattern:full_width_on_mobile_w_95vw|centered_on_desktop →z_index:z_80_below_navigation

Pattern 4: Single Responsive Component

●pattern_ref|id:PT:SINGLE_RESPONSIVE_COMPONENT|file:NotesTree.tsx →pattern:desktop_view_on_all_devices|responsive_css_only →avoid:separate_mobile_components

Pattern 5: Compact Mobile Switcher (Overlap Prevention)

Pattern 6: Tab Visibility Guarantee Pattern

// ✅ CORRECT: Explicit visibility guarantees
<div className="flex flex-shrink-0 z-10">
  {/* Tabs must always be visible, never conditionally hidden */}
  <Tabs>
    <TabsList>
      <TabsTrigger value="notepad">Notepad</TabsTrigger>
      <TabsTrigger value="artifacts">Artifacts</TabsTrigger>
      <TabsTrigger value="widgets">Widgets</TabsTrigger>
    </TabsList>
  </Tabs>
</div>

END OF PATTERNS

About