williamzujkowski/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)

1. 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)

1. 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

1. 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

1. 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)

1. 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

1. 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)

1. 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

1. 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)

1. 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:

json
{
  "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:

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

Output:

json
{
  "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