Frontend Framework Advisor

Purpose & When-To-Use

Trigger conditions:

• Designing component architecture for new frontend/mobile project
• Choosing between React, Vue, or mobile platforms (iOS/Android/React Native)
• Refactoring component hierarchy or state management approach
• Optimizing rendering performance or bundle size
• Planning cross-platform mobile strategy (native vs React Native)
• Implementing accessibility features (WCAG compliance)
• Migrating from one framework/platform to another
• Establishing testing strategy for frontend components

Not for:

• Backend API design (use api-design-validator)
• Infrastructure deployment (use cloud-native-deployment-orchestrator)
• CSS framework selection or styling implementation
• Low-level browser compatibility issues
• Native platform-specific APIs beyond component architecture

Pre-Checks

Time normalization:

• Compute NOW_ET using NIST/time.gov semantics (America/New_York, ISO-8601): 2025-10-25T21:30:36-04:00
• Use NOW_ET for all citation access dates

Input validation:

• platform must be exactly one of: react, vue, ios, android, react-native
• project_type must be one of: new, refactor, migration
• tier must be: T1 or T2
• state_complexity if provided must be: simple, moderate, complex
• performance_requirements if provided must be: standard, high-performance, low-bandwidth
• accessibility_level if provided must be: basic, WCAG-AA, WCAG-AAA

Source freshness:

• React Documentation (accessed 2025-10-25T21:30:36-04:00): https://react.dev/learn
• Vue.js 3 Guide (accessed 2025-10-25T21:30:36-04:00): https://vuejs.org/guide/introduction.html
• Apple Developer Swift Documentation (accessed 2025-10-25T21:30:36-04:00): https://developer.apple.com/documentation/swift
• Android Kotlin Development (accessed 2025-10-25T21:30:36-04:00): https://developer.android.com/kotlin/first
• React Native Documentation (accessed 2025-10-25T21:30:36-04:00): https://reactnative.dev/docs/getting-started
• Apple Human Interface Guidelines (accessed 2025-10-25T21:30:36-04:00): https://developer.apple.com/design/human-interface-guidelines

Procedure

T1: Quick Guidance (≤2k tokens)

Fast path for 80% of component architecture decisions:

1. Platform-specific starter recommendation:

   • React: Functional components + hooks, avoid class components
   • Vue: Composition API (Vue 3) over Options API for new projects
   • iOS: SwiftUI for iOS 15+ projects, UIKit for legacy support
   • Android: Jetpack Compose for new projects, XML layouts for legacy
   • React Native: Functional components + hooks, platform-specific files (.ios.tsx, .android.tsx)

2. State management quick decision:

   • Simple (forms, UI toggles): Local state (useState/ref)
   • Moderate (app-wide theme, auth): Context API (React), Provide/Inject (Vue), @StateObject/@EnvironmentObject (SwiftUI), ViewModel (Android)
   • Complex (global cache, real-time sync): Redux Toolkit (React), Pinia (Vue), Combine (iOS), Flow/LiveData (Android)

3. Component hierarchy pattern:

   • Follow container/presentational pattern
   • Keep components small (≤200 lines)
   • One component per file
   • Props flow down, events flow up
   • Avoid prop drilling beyond 2-3 levels

4. Performance quick wins:

   • React: React.memo for expensive components, useMemo/useCallback for heavy computations
   • Vue: v-once for static content, computed properties for derived state
   • iOS: LazyVStack/LazyHStack for lists, @ViewBuilder for composition
   • Android: LazyColumn/LazyRow, remember for expensive operations
   • React Native: FlatList over ScrollView, memo for list items

5. Output T1 recommendation:

   • Architecture pattern (component hierarchy sketch)
   • State management choice with rationale
   • Top 3 performance optimizations
   • Testing approach (reference testing-strategy-composer)

T2: Detailed Architecture (≤6k tokens)

Extended guidance for complex component architectures:

1. Comprehensive architecture design:

   • File structure convention:

     • React/Vue: /components, /hooks or /composables, /store, /utils, /types
     • iOS: Group by feature, Models/Views/ViewModels separation
     • Android: MVVM or MVI pattern, package by feature
     • React Native: /src/components, /src/screens, /src/navigation, /src/services

   • Component categorization:

     • Layout components (navigation, grids, containers)
     • UI primitives (buttons, inputs, cards)
     • Feature components (user profile, checkout flow)
     • HOCs/Renderless components (logic encapsulation)

2. State management deep dive:

   • React advanced patterns:

     • Redux Toolkit with RTK Query for API state
     • Zustand for lightweight global state
     • Jotai/Recoil for atomic state management
     • Context + useReducer for feature-scoped state

   • Vue advanced patterns:

     • Pinia stores with composition API
     • VueUse composables for reusable logic
     • Provide/Inject for dependency injection
     • ref/reactive pattern selection guide

   • iOS state management:

     • @State for view-local state
     • @StateObject for owned observable objects
     • @ObservedObject for passed observable objects
     • @EnvironmentObject for app-wide state
     • Combine publishers for async state

   • Android state management:

     • ViewModel with StateFlow/LiveData
     • Repository pattern for data layer
     • Hilt for dependency injection
     • Room for local persistence

   • React Native considerations:

     • Same as React + AsyncStorage for persistence
     • Realm for complex offline-first apps
     • Redux Persist for state hydration

3. Performance optimization strategies:

   • React:

     • Code splitting with React.lazy() and Suspense
     • Virtual lists for long data (react-window, react-virtualized)
     • Optimize re-renders with React DevTools Profiler
     • Bundle analysis with webpack-bundle-analyzer

   • Vue:

     • Async components with defineAsyncComponent
     • Virtual scrolling with vue-virtual-scroller
     • Lazy hydration for SSR
     • Vite bundle analysis

   • iOS:

     • Image optimization (SF Symbols, Asset Catalogs)
     • Background task optimization
     • Instruments profiling (Time Profiler, Allocations)
     • SwiftUI lazy loading modifiers

   • Android:

     • R8 code shrinking and obfuscation
     • Image optimization (WebP, vector drawables)
     • Baseline profiles for app startup
     • Compose recomposition optimization

   • React Native:

     • Hermes JavaScript engine
     • Native module optimization
     • Image caching (react-native-fast-image)
     • FlatList optimization (getItemLayout, keyExtractor)

4. Accessibility implementation:

   • WCAG-AA compliance:

     • Semantic HTML/native components (React/Vue)
     • ARIA labels and roles where needed
     • Keyboard navigation support
     • Color contrast ratios ≥4.5:1 for text
     • Focus management

   • Platform-specific:

     • React: react-aria library for accessible components
     • Vue: vue-announcer for screen reader announcements
     • iOS: VoiceOver support with .accessibilityLabel()
     • Android: TalkBack support with contentDescription
     • React Native: accessibilityLabel, accessibilityRole

5. Testing integration (leverage testing-strategy-composer):

   • Unit tests:

     • React: Jest + React Testing Library
     • Vue: Vitest + Vue Test Utils
     • iOS: XCTest for ViewModels and business logic
     • Android: JUnit + MockK for ViewModels
     • React Native: Jest + React Native Testing Library

   • Component/Integration tests:

     • React/Vue: Component tests with user interaction simulation
     • iOS: XCTest with XCUITest for SwiftUI previews
     • Android: Espresso for UI tests
     • React Native: Detox for e2e mobile tests

   • Visual regression:

     • Storybook + Chromatic (React/Vue/React Native)
     • Snapshot tests (all platforms)

6. Output T2 detailed plan:

   • Complete file structure with naming conventions
   • State management architecture diagram
   • Performance optimization checklist (prioritized)
   • Accessibility implementation guide
   • Testing strategy with tool recommendations
   • Migration path (if project_type=migration)
   • Code scaffolding templates (reference resources/)

Decision Rules

Framework/platform selection guidance:

• Choose React if: large ecosystem, flexible architecture, strong typing (TypeScript), hiring availability priority
• Choose Vue if: gentler learning curve, integrated tooling (Vite), single-file components preferred
• Choose iOS native if: iOS-only app, need platform-specific APIs, best performance required
• Choose Android native if: Android-only app, need platform-specific APIs, Material Design 3 alignment
• Choose React Native if: code sharing across iOS/Android >70%, JavaScript team, faster iteration priority

State management escalation:

• Start with local state; escalate to context/global only when prop drilling exceeds 3 levels
• Prefer built-in solutions (Context API, Composition API) before external libraries
• Only introduce Redux/Pinia when state logic becomes complex (>5 interconnected actions)

Performance optimization priorities:

1. Measure first (profiling tools) before optimizing
2. Optimize critical render path (initial load <3s)
3. Lazy load routes/screens
4. Optimize images and assets
5. Reduce bundle size (code splitting, tree shaking)

Abort conditions:

• If platform not in supported list → reject request
• If migration involves unsupported source/target → request clarification
• If state complexity undefined and project is large → request user input
• If accessibility requirements exceed platform capabilities → flag limitation

Output Contract

Schema:

{
  "architecture_plan": {
    "file_structure": ["string", "array of directory/file paths"],
    "component_hierarchy": "string (ASCII diagram or description)",
    "pattern": "string (container/presentational, MVVM, etc.)"
  },
  "state_management_recommendation": {
    "approach": "string (e.g., 'Redux Toolkit', 'Pinia', 'SwiftUI @StateObject')",
    "rationale": "string (why this choice)",
    "libraries": ["string", "array of package names"],
    "setup_steps": ["string", "array of implementation steps"]
  },
  "performance_patterns": [
    {
      "pattern": "string (e.g., 'React.memo', 'LazyVStack')",
      "use_case": "string",
      "code_example_ref": "string (path to resources/)"
    }
  ],
  "platform_scaffolding": "string (starter code or template reference)",
  "testing_integration": {
    "unit_testing_tools": ["string"],
    "component_testing_tools": ["string"],
    "e2e_testing_tools": ["string"],
    "coverage_target": "number (percentage)"
  },
  "accessibility_checklist": ["string", "array of WCAG requirements"],
  "migration_notes": "string (if project_type=migration, else null)"
}

Required fields: architecture_plan, state_management_recommendation, performance_patterns, testing_integration

Optional fields: accessibility_checklist (if accessibility_level provided), migration_notes (if project_type=migration)

Examples

Example: React component architecture for moderate state complexity

Input:

{
  "platform": "react",
  "project_type": "new",
  "tier": "T1",
  "state_complexity": "moderate",
  "performance_requirements": "standard"
}

Output:

{
  "architecture_plan": {
    "pattern": "container/presentational",
    "component_hierarchy": "App > Layout > [Header, Main(Router), Footer]"
  },
  "state_management_recommendation": {
    "approach": "Context API + useReducer",
    "rationale": "Moderate complexity fits Context; avoid Redux overhead"
  },
  "performance_patterns": [
    {"pattern": "React.memo", "use_case": "expensive list items"},
    {"pattern": "Code splitting", "use_case": "route-based chunks"}
  ]
}

Quality Gates

Token budgets:

• T1 ≤ 2k tokens: Platform detection, state decision, 3-5 quick wins
• T2 ≤ 6k tokens: Full architecture, performance deep dive, accessibility guide, 4-6 authoritative sources
• T3 not implemented: This skill operates at T1/T2 only; complex multi-framework migrations requiring deep research should use architecture-decision-framework

Safety:

• No framework-specific exploits or anti-patterns
• Recommend only stable, well-maintained libraries
• Flag deprecated patterns (e.g., React class components, Vue Options API for new projects)
• Accessibility: ensure compliance with WCAG guidelines

Auditability:

• All platform-specific recommendations cite official documentation (React.dev, Vue.js, Apple, Android, React Native docs)
• Performance claims reference framework-specific profiling tools
• State management recommendations backed by framework maintainer guidance

Determinism:

• Same input → same architectural recommendation
• Version-aware (React 18+, Vue 3+, iOS 15+, Android API 31+)
• Stable library recommendations (prefer framework built-ins over third-party when equivalent)

Resources

Official documentation:

• React: https://react.dev/learn, https://react.dev/reference/react
• Vue: https://vuejs.org/guide/, https://vuejs.org/api/
• iOS: https://developer.apple.com/documentation/swiftui, https://developer.apple.com/documentation/uikit
• Android: https://developer.android.com/jetpack/compose, https://developer.android.com/kotlin
• React Native: https://reactnative.dev/docs/components-and-apis

State management:

• Redux Toolkit: https://redux-toolkit.js.org/
• Pinia: https://pinia.vuejs.org/
• Zustand: https://github.com/pmndrs/zustand
• VueUse: https://vueuse.org/

Performance:

• React DevTools Profiler: https://react.dev/learn/react-developer-tools
• Vue DevTools: https://devtools.vuejs.org/
• Xcode Instruments: https://developer.apple.com/xcode/features/
• Android Profiler: https://developer.android.com/studio/profile

Testing:

• React Testing Library: https://testing-library.com/react
• Vue Test Utils: https://test-utils.vuejs.org/
• Detox (React Native): https://wix.github.io/Detox/

Accessibility:

• React ARIA: https://react-spectrum.adobe.com/react-aria/
• WCAG 2.2: https://www.w3.org/WAI/WCAG22/quickref/
• iOS Accessibility: https://developer.apple.com/accessibility/
• Android Accessibility: https://developer.android.com/guide/topics/ui/accessibility

Templates: See resources/component-templates/ for platform-specific scaffolding

Source: williamzujkowski/cognitive-toolworks — distributed by TomeVault.