component-architecture

Resources

scripts/ validate-components.sh references/ component-patterns.md

Component Architecture

This skill guides you through designing and implementing UI components using GoodVibes precision and analysis tools. Use this workflow when building React, Vue, or Svelte components with proper composition, state management, and performance optimization.

When to Use This Skill

Load this skill when:

Building new UI components or component libraries
Refactoring component hierarchies or composition patterns
Optimizing component render performance
Organizing component file structures
Implementing design systems or atomic design patterns
Migrating between component frameworks
Reviewing component architecture for maintainability

Trigger phrases: "build component", "create UI", "component structure", "render optimization", "state lifting", "component composition".

Core Workflow

Phase 1: Discovery

Before building components, understand existing patterns in the codebase.

Step 1.1: Map Component Structure

Use discover to find all component files and understand the organization pattern.

discover: queries: - id: react_components type: glob patterns: ["/*.tsx", "/.jsx"] - id: vue_components type: glob patterns: ["**/.vue"] - id: svelte_components type: glob patterns: ["**/*.svelte"] verbosity: files_only

What this reveals:

Framework in use (React, Vue, Svelte, or mixed)
Component file organization (feature-based, atomic, flat)
Naming conventions (PascalCase, kebab-case)
File colocation patterns (components with tests, styles)

Step 1.2: Analyze Component Patterns

Use discover to find composition patterns, state management, and styling approaches.

discover: queries: - id: composition_patterns type: grep pattern: "(children|render|slot|as\s*=)" glob: "/*.{tsx,jsx,vue,svelte}" - id: state_management type: grep pattern: "(useState|useReducer|reactive|writable|createSignal)" glob: "/.{ts,tsx,js,jsx,vue,svelte}" - id: styling_approach type: grep pattern: "(className|styled|css|tw`|@apply)" glob: "**/.{tsx,jsx,vue,svelte}" - id: performance_hooks type: grep pattern: "(useMemo|useCallback|memo|computed|\$:)" glob: "**/*.{ts,tsx,js,jsx,vue,svelte}" verbosity: files_only

What this reveals:

Composition strategy (children props, render props, slots)
State management patterns (hooks, stores, signals)
Styling solution (CSS modules, Tailwind, styled-components)
Performance optimization techniques in use

Step 1.3: Extract Component Symbols

Use precision_read with symbol extraction to understand component exports.

precision_read: files: - path: "src/components/Button/index.tsx" # Example component extract: symbols symbol_filter: ["function", "class", "interface", "type"] verbosity: standard

What this reveals:

Component export patterns (named vs default)
Props interface definitions
Helper functions and hooks
Type definitions and generics

Step 1.4: Read Representative Components

Read 2-3 well-structured components to understand implementation patterns.

precision_read: files: - path: "src/components/Button/Button.tsx" extract: content - path: "src/components/Form/Form.tsx" extract: content output: max_per_item: 100 verbosity: standard

Phase 2: Decision Making

Step 2.1: Choose Component Organization Pattern

Consult references/component-patterns.md for the organization decision tree.

Common patterns:

Atomic Design - atoms, molecules, organisms, templates, pages
Feature-based - group by feature/domain
Flat - all components in single directory
Hybrid - shared components + feature components

Decision factors:

Team size (larger teams -> more structure)
Application complexity (complex -> feature-based)
Design system presence (yes -> atomic design)
Component reusability (high -> shared/ui directory)

Step 2.2: Choose Composition Pattern

See references/component-patterns.md for detailed comparison.

Pattern selection guide:

Pattern Use When Framework Support

Children props Simple wrapper components React, Vue (slots), Svelte

Render props Dynamic rendering logic React (legacy)

Compound components Related components share state React, Vue, Svelte

Higher-Order Components Cross-cutting concerns React (legacy)

Hooks/Composables Logic reuse React, Vue 3, Svelte

Slots Template-based composition Vue, Svelte

Modern recommendation:

React: Hooks + children props (avoid HOCs/render props)
Vue: Composition API + slots
Svelte: Actions + slots

Step 2.3: Choose State Management Strategy

Component-level state:

Use local state for UI-only concerns (modals, forms, toggles)
Lift state only when siblings need to share
Derive state instead of duplicating

Application-level state:

React: Context + useReducer, Zustand, Jotai
Vue: Pinia (Vue 3), Vuex (Vue 2)
Svelte: Stores, Context API

See references/component-patterns.md for state management decision tree.

Phase 3: Implementation

Step 3.1: Define Component Interface

Start with TypeScript interfaces for props.

React Example:

import { ReactNode } from 'react';

interface ButtonProps { /** Button content / children: ReactNode; /* Visual style variant / variant?: 'primary' | 'secondary' | 'ghost' | 'danger'; /* Size preset / size?: 'sm' | 'md' | 'lg'; /* Loading state / isLoading?: boolean; /* Disabled state / disabled?: boolean; /* Click handler / onClick?: () => void; /* Additional CSS classes */ className?: string; }

Best practices:

Document all props with JSDoc comments
Use discriminated unions for variant props
Make optional props explicit with ?
Provide sensible defaults
Avoid any types

Vue 3 Example:

import { defineComponent, PropType } from 'vue';

export default defineComponent({ props: { variant: { type: String as PropType<'primary' | 'secondary' | 'ghost' | 'danger'>, default: 'primary', }, size: { type: String as PropType<'sm' | 'md' | 'lg'>, default: 'md', }, isLoading: { type: Boolean, default: false, }, disabled: { type: Boolean, default: false, }, }, });

Svelte Example:

// Button.svelte (Svelte 5 - using $props rune) <script lang="ts"> let { variant = 'primary', size = 'md', isLoading = false, disabled = false }: { variant?: 'primary' | 'secondary' | 'ghost' | 'danger'; size?: 'sm' | 'md' | 'lg'; isLoading?: boolean; disabled?: boolean; } = $props(); </script>

Step 3.2: Implement Component Logic

Follow framework-specific patterns for component implementation.

React with Composition:

import { forwardRef } from 'react'; import { cn } from '@/lib/utils'; import { Spinner } from './Spinner';

const buttonVariants = { variant: { primary: 'bg-blue-600 hover:bg-blue-700 text-white', secondary: 'bg-gray-200 hover:bg-gray-300 text-gray-900', ghost: 'hover:bg-gray-100 text-gray-700', danger: 'bg-red-600 hover:bg-red-700 text-white', }, size: { sm: 'px-3 py-1.5 text-sm', md: 'px-4 py-2 text-base', lg: 'px-6 py-3 text-lg', }, };

export const Button = forwardRef<HTMLButtonElement, ButtonProps>( ( { children, variant = 'primary', size = 'md', isLoading = false, disabled = false, className, ...props }, ref ) => { return ( <button ref={ref} className={cn( 'inline-flex items-center justify-center rounded-md font-medium', 'transition-colors focus-visible:outline-none focus-visible:ring-2', 'disabled:pointer-events-none disabled:opacity-50', buttonVariants.variant[variant], buttonVariants.size[size], className )} disabled={disabled || isLoading} aria-busy={isLoading} {...props} > {isLoading ? ( <> <Spinner className="mr-2 h-4 w-4" aria-hidden /> <span>Loading...</span> </> ) : ( children )} </button> ); } );

Button.displayName = 'Button';

Key patterns:

Use forwardRef to expose DOM ref
Spread ...props for flexibility
Compose classNames with utility function
Handle loading/disabled states
Add ARIA attributes for accessibility

Step 3.3: Organize Component Files

Create component directory with proper file structure.

Standard structure:

components/ Button/ Button.tsx # Component implementation Button.test.tsx # Unit tests Button.stories.tsx # Storybook stories (if using) index.tsx # Barrel export types.ts # Type definitions (if complex)

Implementation with precision tools:

precision_write: files: - path: "src/components/Button/Button.tsx" content: | import { forwardRef } from 'react'; // ... [full implementation] - path: "src/components/Button/index.tsx" content: | export { Button } from './Button'; export type { ButtonProps } from './Button'; - path: "src/components/Button/Button.test.tsx" content: | import { render, screen } from '@testing-library/react'; import { Button } from './Button'; // ... [test cases] verbosity: count_only

Phase 4: State Management

Step 4.1: Identify State Scope

Local state (component-only):

Form inputs
Modal open/closed
Dropdown expanded/collapsed
Loading states

Lifted state (parent manages):

Form validation across fields
Multi-step wizard state
Accordion with single-open behavior

Global state (app-level):

User authentication
Theme preferences
Shopping cart
Notifications

Step 4.2: Implement State Patterns

React - Local State:

import { useState } from 'react';

interface SearchResult { id: string; title: string; description: string; }

function SearchInput() { const [query, setQuery] = useState(''); const [results, setResults] = useState<SearchResult[]>([]);

const handleSearch = async () => { const data = await fetch(/api/search?q=${encodeURIComponent(query)}); setResults(await data.json()); };

return ( <> <input value={query} onChange={(e) => setQuery(e.target.value)} /> <button onClick={handleSearch}>Search</button> </> ); }

React - Lifted State:

function SearchPage() { const [query, setQuery] = useState(''); const [results, setResults] = useState<SearchResult[]>([]);

return ( <> <SearchInput query={query} onQueryChange={setQuery} /> <SearchResults results={results} /> </> ); }

React - Derived State:

interface Item { id: string; category: string; name: string; }

interface FilteredListProps { items: Item[]; filter: string; }

function FilteredList({ items, filter }: FilteredListProps) { // Don't store filtered items in state - derive them const filteredItems = items.filter(item => item.category === filter);

return <ul>{filteredItems.map(item => <li key={item.id}>{item.name}</li>)}</ul>; }

Step 4.3: Avoid Prop Drilling

Use Context for deeply nested props:

import { createContext, useContext } from 'react';

const ThemeContext = createContext({ theme: 'light', toggleTheme: () => {} });

interface ThemeProviderProps { children: ReactNode; }

export function ThemeProvider({ children }: ThemeProviderProps) { const [theme, setTheme] = useState('light'); const toggleTheme = () => setTheme(t => t === 'light' ? 'dark' : 'light');

return ( <ThemeContext.Provider value={{ theme, toggleTheme }}> {children} </ThemeContext.Provider> ); }

export const useTheme = () => useContext(ThemeContext);

Phase 5: Performance Optimization

Step 5.1: Identify Render Issues

Use analysis tools to detect performance problems.

mcp__plugin_goodvibes_frontend-engine__trace_component_state: component_file: "src/components/Dashboard.tsx" target_component: "Dashboard"

mcp__plugin_goodvibes_frontend-engine__analyze_render_triggers: component_file: "src/components/ExpensiveList.tsx"

What these reveal:

Components re-rendering unnecessarily
State updates triggering cascade renders
Props changing on every parent render

Step 5.2: Apply Memoization

Memoize expensive calculations:

import { useMemo } from 'react';

interface DataItem { id: string; [key: string]: unknown; }

interface DataTableProps { data: DataItem[]; filters: Record<string, any>; }

function DataTable({ data, filters }: DataTableProps) { const filteredData = useMemo(() => { return data.filter(item => matchesFilters(item, filters)); }, [data, filters]);

return <table>{/* render filteredData */}</table>; }

Memoize callback functions:

import { useCallback } from 'react';

function Parent() { const [count, setCount] = useState(0);

// Prevent Child re-render when count changes const handleClick = useCallback(() => { onClick(); }, []);

return <Child onClick={handleClick} />; }

Memoize components:

import { memo } from 'react';

interface ExpensiveChildProps { data: DataItem[]; }

const ExpensiveChild = memo(function ExpensiveChild({ data }: ExpensiveChildProps) { // Only re-renders if data changes return <div>{/* complex rendering */}</div>; });

Step 5.3: Implement Virtualization

For large lists, use virtualization libraries.

import { useVirtualizer } from '@tanstack/react-virtual';

interface VirtualListProps<T = unknown> { items: T[]; }

function VirtualList({ items }: VirtualListProps) { const parentRef = useRef(null);

const virtualizer = useVirtualizer({ count: items.length, getScrollElement: () => parentRef.current, estimateSize: () => 50, });

// Note: Inline styles acceptable here for virtualization positioning return ( <div ref={parentRef} style={{ height: '400px', overflow: 'auto' }}> <div style={{ height: ${virtualizer.getTotalSize()}px }}> {virtualizer.getVirtualItems().map(virtualRow => ( <div key={virtualRow.index} style={{ position: 'absolute', top: 0, left: 0, transform: translateY(${virtualRow.start}px), }} > {items[virtualRow.index].name} </div> ))} </div> </div> ); }

Step 5.4: Lazy Load Components

React lazy loading:

import { lazy, Suspense } from 'react';

const HeavyComponent = lazy(() => import('./HeavyComponent'));

function App() { return ( <Suspense fallback={<div>Loading...</div>}> <HeavyComponent /> </Suspense> ); }

Phase 6: Accessibility

Step 6.1: Semantic HTML

Use proper HTML elements instead of divs.

// Bad <div onClick={handleClick}>Click me</div>

// Good <button onClick={handleClick}>Click me</button>

Step 6.2: ARIA Attributes

Add ARIA labels for screen readers.

interface DialogProps { isOpen: boolean; onClose: () => void; children: ReactNode; }

function Dialog({ isOpen, onClose, children }: DialogProps) { return ( <div role="dialog" aria-modal="true" aria-labelledby="dialog-title" aria-describedby="dialog-description" > <h2 id="dialog-title">Dialog Title</h2> <div id="dialog-description">{children}</div> <button onClick={onClose} aria-label="Close dialog"> X </button> </div> ); }

Step 6.3: Keyboard Navigation

Ensure all interactive elements are keyboard-accessible.

function Dropdown() { const [isOpen, setIsOpen] = useState(false);

const handleKeyDown = (e: React.KeyboardEvent<HTMLButtonElement>) => { if (e.key === 'Escape') setIsOpen(false); if (e.key === 'Enter' || e.key === ' ') setIsOpen(!isOpen); };

return ( <div> <button onClick={() => setIsOpen(!isOpen)} onKeyDown={handleKeyDown} aria-expanded={isOpen} aria-haspopup="true" > Menu </button> {isOpen && <div role="menu">{/* menu items */}</div>} </div> ); }

Step 6.4: Validate Accessibility

Use frontend analysis tools to check accessibility.

mcp__plugin_goodvibes_frontend-engine__get_accessibility_tree: component_file: "src/components/Dialog.tsx"

Phase 7: Validation

Step 7.1: Type Check

Verify TypeScript compilation.

precision_exec: commands: - cmd: "npm run typecheck" expect: exit_code: 0 verbosity: minimal

Step 7.2: Run Component Validation Script

Use the validation script to ensure quality.

bash plugins/goodvibes/skills/outcome/component-architecture/scripts/validate-components.sh .

See scripts/validate-components.sh for the complete validation suite.

Step 7.3: Visual Regression Testing

If using Storybook or similar, run visual tests.

precision_exec: commands: - cmd: "npm run test:visual" expect: exit_code: 0 verbosity: minimal

Common Anti-Patterns

DON'T:

Store derived state (calculate from existing state)
Mutate props or state directly
Use index as key for dynamic lists
Create new objects/functions in render
Skip prop validation or TypeScript types
Use any types for component props
Mix presentation and business logic
Ignore accessibility (ARIA, keyboard nav)
Over-optimize (premature memoization)

DO:

Derive state from props when possible
Treat props and state as immutable
Use stable, unique keys for list items
Define functions outside render or use useCallback
Define strict prop types with TypeScript
Separate container (logic) from presentational components
Add ARIA attributes for custom components
Measure before optimizing (React DevTools Profiler)

Quick Reference

Discovery Phase:

discover: { queries: [components, patterns, state, styling], verbosity: files_only } precision_read: { files: [example components], extract: symbols }

Implementation Phase:

precision_write: { files: [Component.tsx, index.tsx, types.ts], verbosity: count_only }

Performance Analysis:

trace_component_state: { component_file: "src/...", target_component: "Name" } analyze_render_triggers: { component_file: "src/..." }

Accessibility Check:

get_accessibility_tree: { component_file: "src/..." }

Validation Phase:

precision_exec: { commands: [{ cmd: "npm run typecheck" }] }

Post-Implementation:

bash scripts/validate-components.sh .

For detailed patterns, framework comparisons, and decision trees, see references/component-patterns.md .

Related Skills

Consider using these complementary GoodVibes skills:

styling-system - Design system tokens, theme architecture, and CSS-in-JS patterns
state-management - Global state patterns, store architecture, and data flow
testing-strategy - Component testing, visual regression, and accessibility testing
performance-audit - Bundle analysis, render profiling, and optimization strategies
accessibility-audit - WCAG compliance, screen reader testing, and ARIA patterns

component-architecture

Safety Notice

Copy this and send it to your AI assistant to learn

Source Transparency

Related Skills

error-recovery

task-orchestration

project-onboarding