| name | frontend-architecture |
| description | Practical frontend architecture rules for scalable UI, performance, and maintainability. |
| license | See repository LICENSE |
| user-invocable | false |
Frontend Architecture & Performance
Use this skill for UI architecture, component boundaries, state placement, and frontend performance work.
Priorities
- Clear ownership
- Predictable state flow
- Usable performance
- Composition over duplication
- Maintainable delivery
Core Rules
1. Split by responsibility, not by hype
- Components should have clear ownership.
- Keep screen/container concerns separate from presentational concerns when that improves clarity.
- Do not create a new architectural layer unless it reduces real complexity.
2. Keep state as local as possible
- Start with local component state.
- Lift state only when multiple consumers truly need it.
- Global state should be reserved for cross-cutting or shared application concerns, not convenience.
3. Make data flow obvious
- Prefer one clear direction of data flow.
- Keep fetching, normalization, and rendering responsibilities understandable.
- Avoid passing unstable props or context values through large trees without reason.
4. Reuse patterns intentionally
- Reuse component, layout, and styling conventions already present in the repo.
- Prefer composition over giant configurable mega-components.
- Extract shared primitives only after repetition becomes real.
5. Design for loading, error, and empty states
- Every meaningful async screen should define:
- loading state
- error state
- empty state
- success state
- Do not optimize only the happy path.
Performance Rules
6. Optimize the right thing
- Prioritize user-visible slowness: route transitions, large lists, blocking renders, image weight, bundle size, and repeated network work.
- Measure with the platform tools available in the repo before adding memoization or architectural complexity.
7. Keep renders cheap
- Avoid unnecessary derived work in render paths.
- Memoization is a tool, not a default.
- Stabilize props and callbacks only when it measurably helps or prevents correctness issues.
8. Be deliberate about bundles
- Lazy-load heavy routes or features when it helps real startup cost.
- Keep dependency additions conservative.
- Avoid shipping large helpers for tiny benefits.
Styling and Structure Rules
- Respect the repo's styling system.
- Keep layout primitives and page-specific styling separate when possible.
- Avoid one-off CSS or utility explosions that are hard to reason about later.
- Accessibility is architecture too: semantics, focus flow, labels, and contrast should be built in, not patched in at the end.
Review Heuristics
Look for:
- oversized components with mixed responsibilities
- state lifted too high
- duplicated fetching/normalization logic
- missing loading/error/empty states
- performance work added without measurement
- giant shared components that became bottlenecks
- unnecessary global state or context churn
Anti-Patterns
Avoid:
- mega-components that own unrelated concerns
- storing server state and transient UI state in the same generic bucket without boundaries
- premature abstraction of every repeated markup fragment
- memoization everywhere "just in case"
- component APIs with too many mode flags
Quick Checklist
