---
description: Core front-end development philosophy and principles
alwaysApply: true
---

# Master Front-End Development Philosophy

## Core Mission

Build the best front-end code ever made by combining modern frameworks, utility-first CSS, systematic design thinking, and flawless execution.

## Philosophical Pillars

### 1. Mobile-First, Everywhere-Perfect
- Every component works flawlessly on mobile, tablet, and desktop
- Mobile is the foundation, not an afterthought
- Touch targets, viewport management, and safe areas are first-class citizens

### 2. Consistency is Sacred
- Mobile and desktop versions show **identical content and functionality** unless explicitly designed otherwise
- Design tokens ensure visual consistency across all breakpoints
- User experience never diverges accidentally between screen sizes

**Verification Before Shipping:**
- ✅ Same navigation items on mobile and desktop
- ✅ Same content sections visible
- ✅ Same buttons and CTAs available
- ✅ Only layout and presentation differ

### 3. Theme-First Architecture
- Applications are built with theming as a core architectural decision from day one
- Themes are CSS-based with reactive state management
- Dark mode and light mode are equals, not primary/secondary

**CRITICAL THEME RULE**: Header, sidebar, and main background must use the same fill color.

### 4. Utility-First, Component-Second
- Tailwind CSS utilities in templates for maximum flexibility
- Component classes only for truly reusable patterns
- Extract components when you repeat, not before

### 5. Performance as a Feature
- **Bundle Size**: < 200KB gzipped
- **LCP**: < 2.5s
- **FID**: < 100ms
- CSS transforms for GPU acceleration
- Lazy loading and code splitting by default

### 6. Design System as Foundation
- Typography scale, spacing scale, and color palettes defined upfront
- **4px base grid system** for mathematical harmony
- Consistent component patterns documented

### 7. Accessibility is Non-Negotiable
- **WCAG AA compliance minimum**
- Keyboard navigation works everywhere
- Screen reader friendly
- **4.5:1 contrast ratio** for normal text
- **44x44px minimum touch targets**

### 8. Real Users, Real Devices
- Test on actual phones and tablets
- Consider network conditions (3G, 4G, WiFi)
- Handle offline states gracefully
- Progressive enhancement over graceful degradation

## Success Metrics

### Code Quality
- ✅ Can a new developer understand the codebase in under 1 hour?
- ✅ Does the app work perfectly on a 5-year-old phone?
- ✅ Is mobile/desktop consistency maintained automatically?

### User Experience
- ✅ Does it feel native on every device?
- ✅ Does the interface respond instantly to user input?
- ✅ Load in under 2s on desktop, under 5s on mobile 3G

## Anti-Patterns to Avoid

### ❌ Desktop-First Thinking
Never build desktop first and "make it responsive later"

### ❌ Inconsistent Experiences
Mobile users should never get a degraded experience

### ❌ Hardcoded Values
Use design tokens, variables, and systematic scales

### ❌ Ignoring Performance
Every kilobyte matters, every millisecond counts

### ❌ Accessibility as Afterthought
Build accessible from day one, not as a retrofit

### ❌ Skipping Documentation
Code without documentation is technical debt

## The Ultimate Goal

**When someone uses your application:**
- "This feels incredibly polished"
- "Everything just works"
- "This looks beautiful on my device"

**When a developer reads your code:**
- "This is so well organized"
- "I understand exactly what's happening"
- "Adding features will be straightforward"