@codihaus/claude-skills 1.6.6 → 1.6.7

package/skills/dev-coding-frontend/references/fundamentals.md

@@ -1,577 +0,0 @@
-# Frontend Fundamentals
-
-The principles and patterns that create excellent user experiences.
-
-## Core Mindset
-
-**"I am the communicator with humans. I must be clear, responsive, and consistent."**
-
-The frontend is the interface between humans and the system. It:
-- Communicates what's happening
-- Responds instantly (or appears to)
-- Behaves consistently
-- Works for everyone
-
----
-
-## The Principles
-
-Principles are the fundamental laws. Patterns are solutions derived from them.
-
-### 1. Always Communicate
-
-**Law**: The user should NEVER wonder what's happening.
-
-**Why**: Uncertainty creates anxiety. Users abandon apps that feel "broken" or "stuck."
-
-**Patterns derived**:
-
-| Pattern | What it Communicates |
-|---------|---------------------|
-| Loading State | "I'm working on it" |
-| Error State | "Something went wrong, here's what" |
-| Empty State | "Nothing here yet, here's why" |
-| Success Feedback | "Done! Here's the result" |
-| Progress Indicator | "X% complete" |
-| Skeleton UI | "Content is coming, here's the shape" |
-
-**Recognition signals**:
-- Blank screen while loading
-- Click button, nothing visible happens
-- Error occurs, user sees nothing
-- Form submits, no confirmation
-- List might be empty, just shows nothing
-
-**State matrix for EVERY data-fetching component**:
-```
-STATE        WHAT USER SEES
-─────────────────────────────────────
-idle         Initial state, maybe CTA
-loading      Spinner, skeleton, or shimmer
-success      The actual content
-empty        Helpful message + action
-error        What went wrong + retry option
-```
-
-**Structure example**:
-```vue
-<!-- BAD: No communication -->
-<template>
-  <div v-for="item in items">{{ item.name }}</div>
-</template>
-
-<!-- GOOD: Always communicating -->
-<template>
-  <!-- Loading: Show skeleton -->
-  <div v-if="pending">
-    <Skeleton v-for="i in 3" :key="i" />
-  </div>
-
-  <!-- Error: Explain and offer action -->
-  <div v-else-if="error">
-    <ErrorMessage :error="error" />
-    <Button @click="refresh">Try Again</Button>
-  </div>
-
-  <!-- Empty: Guide the user -->
-  <div v-else-if="items.length === 0">
-    <EmptyState
-      title="No items yet"
-      description="Create your first item to get started"
-      action="Create Item"
-      @action="openCreateModal"
-    />
-  </div>
-
-  <!-- Success: Show content -->
-  <div v-else>
-    <Item v-for="item in items" :key="item.id" :item="item" />
-  </div>
-</template>
-```
-
----
-
-### 2. Feel Instant
-
-**Law**: Perception matters more than reality. Make it FEEL fast.
-
-**Why**: Users perceive 100ms as instant. After 1s they notice delay. After 3s they leave.
-
-**Patterns derived**:
-
-| Pattern | How it Feels Faster |
-|---------|---------------------|
-| Optimistic UI | Show result before server confirms |
-| Skeleton Loading | Show shape, brain fills in details |
-| Lazy Loading | Load what's visible first |
-| Prefetching | Load before user needs it |
-| Debouncing | Don't overwork on rapid input |
-| Code Splitting | Smaller initial bundle |
-| Instant Navigation | Client-side routing |
-
-**Recognition signals**:
-- User clicks, waits, then sees change
-- Full page reload on navigation
-- Large bundle size, slow initial load
-- Images load all at once, page jumps
-- Search triggers on every keystroke
-
-**Optimistic UI example**:
-```javascript
-// BAD: Wait for server
-async function toggleLike(post) {
-  const result = await api.likePost(post.id)  // User waits 500ms
-  post.liked = result.liked
-  post.likeCount = result.likeCount
-}
-
-// GOOD: Optimistic update
-async function toggleLike(post) {
-  // Immediately update UI (feels instant)
-  const previousState = { liked: post.liked, count: post.likeCount }
-  post.liked = !post.liked
-  post.likeCount += post.liked ? 1 : -1
-
-  try {
-    await api.likePost(post.id)
-  } catch (error) {
-    // Rollback if server fails
-    post.liked = previousState.liked
-    post.likeCount = previousState.count
-    toast.error('Could not update like')
-  }
-}
-```
-
-**Loading priority**:
-```
-1. Critical content (above fold)     → Load immediately
-2. Interactive elements              → Load immediately
-3. Below-fold content                → Lazy load on scroll
-4. Images                            → Lazy load + placeholder
-5. Analytics, tracking               → Load after page ready
-6. Non-essential features            → Load on interaction
-```
-
----
-
-### 3. Stay Consistent
-
-**Law**: Same action should always produce same result. Match existing patterns.
-
-**Why**: Consistency builds trust. Inconsistency confuses and frustrates.
-
-**Patterns derived**:
-
-| Pattern | What it Standardizes |
-|---------|---------------------|
-| Design System | Visual appearance |
-| Component Library | UI behavior |
-| Naming Conventions | Code readability |
-| Layout Templates | Page structure |
-| Form Patterns | Input behavior |
-| Navigation Patterns | Movement through app |
-
-**Recognition signals**:
-- Buttons look different on different pages
-- Same action has different animations
-- Forms behave differently
-- Different naming styles in codebase
-- New code doesn't match existing patterns
-
-**Consistency checklist**:
-```
-Before writing new code, check existing codebase for:
-
-NAMING:
-□ How are components named? (PascalCase, kebab-case?)
-□ How are files named? (index.vue, ComponentName.vue?)
-□ How are props named? (isOpen, open, opened?)
-□ How are events named? (onClose, handleClose, close?)
-□ How are functions named? (getData, fetchData, loadData?)
-
-STRUCTURE:
-□ Where do components live? (components/, shared/?)
-□ How is state managed? (Pinia, composables, local?)
-□ How are forms handled? (controlled, libraries?)
-□ How is API data fetched? (useFetch, custom hooks?)
-
-STYLE:
-□ What CSS approach? (Tailwind, modules, styled?)
-□ What design tokens exist? (colors, spacing, shadows?)
-□ How are responsive breakpoints handled?
-
-BEHAVIOR:
-□ How do modals open/close?
-□ How is form validation shown?
-□ How are notifications displayed?
-□ How do lists handle empty/loading states?
-```
-
-**Match existing pattern example**:
-```javascript
-// EXISTING CODE uses this pattern:
-const { data: users, pending, error } = await useFetch('/api/users')
-
-// NEW CODE should match:
-// GOOD - matches existing
-const { data: products, pending, error } = await useFetch('/api/products')
-
-// BAD - different pattern
-const products = ref([])
-const loading = ref(true)
-onMounted(async () => {
-  loading.value = true
-  products.value = await fetch('/api/products').then(r => r.json())
-  loading.value = false
-})
-```
-
----
-
-### 4. Work for Everyone
-
-**Law**: The interface must work for all users, not just ideal conditions.
-
-**Why**: Users have disabilities, slow connections, old devices, different languages.
-
-**Patterns derived**:
-
-| Pattern | Who it Helps |
-|---------|-------------|
-| Semantic HTML | Screen readers, SEO |
-| Keyboard Navigation | Motor disabilities, power users |
-| Color Contrast | Visual impairments |
-| Responsive Design | Mobile users |
-| Offline Support | Poor connections |
-| Error Recovery | All users |
-| Internationalization | Non-English speakers |
-
-**Recognition signals**:
-- Can't use with keyboard only
-- No alt text on images
-- Low color contrast
-- Breaks on mobile
-- Crashes on slow connection
-- No error recovery
-
-**Accessibility minimum**:
-```html
-<!-- Semantic HTML first -->
-<nav> not <div class="nav">
-<button> not <div onclick>
-<main> not <div class="main">
-<h1>, <h2>, <h3> in order
-
-<!-- Images -->
-<img src="..." alt="Description of what image shows" />
-<img src="decorative.png" alt="" />  <!-- Empty alt for decorative -->
-
-<!-- Interactive elements -->
-<button aria-label="Close dialog">×</button>
-<input aria-describedby="help-text" />
-<div id="help-text">Password must be 8+ characters</div>
-
-<!-- Focus management -->
-<!-- When modal opens: focus first element -->
-<!-- When modal closes: focus trigger element -->
-
-<!-- Keyboard -->
-<!-- All interactive elements reachable via Tab -->
-<!-- Enter/Space activates buttons -->
-<!-- Escape closes modals/dropdowns -->
-```
-
-**Responsive approach**:
-```
-MOBILE FIRST:
-1. Design for smallest screen first
-2. Add complexity for larger screens
-3. Test at: 320px, 768px, 1024px, 1440px
-
-CSS ORDER:
-.component {
-  /* Mobile styles (default) */
-  padding: 1rem;
-}
-
-@media (min-width: 768px) {
-  /* Tablet and up */
-  padding: 2rem;
-}
-
-@media (min-width: 1024px) {
-  /* Desktop and up */
-  padding: 3rem;
-}
-```
-
----
-
-### 5. Single Source of Truth
-
-**Law**: Each piece of state should live in ONE place.
-
-**Why**: Duplicate state gets out of sync. Bugs appear. Debugging is nightmare.
-
-**Patterns derived**:
-
-| Pattern | What it Centralizes |
-|---------|---------------------|
-| State Management (Pinia) | Global app state |
-| Composables | Shared logic |
-| Controlled Components | Form input values |
-| URL as State | Navigation/filter state |
-| Props Down, Events Up | Component communication |
-
-**Recognition signals**:
-- Same data stored in multiple places
-- Prop drilling through many levels
-- Components directly modifying parent state
-- State out of sync after actions
-- "Why isn't this updating?"
-
-**State location guide**:
-```
-WHO NEEDS THIS STATE?
-│
-├─ Just this component → Local state (ref/reactive)
-│
-├─ Parent and children → Props down, events up
-│
-├─ Siblings → Lift state to common parent, or use composable
-│
-├─ Many unrelated components → Global store (Pinia)
-│
-└─ Should survive refresh → URL params or localStorage
-```
-
-**Example**:
-```javascript
-// BAD: Duplicate state
-// In Parent:
-const selectedUser = ref(null)
-
-// In Child (duplicating):
-const selectedUser = ref(null)  // Out of sync risk!
-
-// GOOD: Single source
-// In Parent:
-const selectedUser = ref(null)
-
-// In Child (receiving):
-const props = defineProps(['selectedUser'])
-const emit = defineEmits(['update:selectedUser'])
-
-// Or use store for global state:
-// store/user.js
-export const useUserStore = defineStore('user', () => {
-  const selectedUser = ref(null)
-  const selectUser = (user) => selectedUser.value = user
-  return { selectedUser, selectUser }
-})
-
-// Any component:
-const userStore = useUserStore()
-userStore.selectUser(user)
-```
-
----
-
-### 6. Minimize Complexity
-
-**Law**: Simple is better than clever. Obvious is better than magical.
-
-**Why**: Others (and future you) must understand and modify this code.
-
-**Patterns derived**:
-
-| Pattern | How it Simplifies |
-|---------|-------------------|
-| Small Components | Each does one thing |
-| Composition | Combine simple pieces |
-| Explicit Props | Clear interface |
-| Flat State | Avoid deep nesting |
-| Co-location | Related code together |
-
-**Recognition signals**:
-- Component file > 300 lines
-- Props > 10 items
-- Deeply nested state (a.b.c.d.e)
-- "Magic" that's hard to trace
-- Heavy abstraction for simple tasks
-
-**Component size guide**:
-```
-IDEAL COMPONENT:
-- One clear responsibility
-- < 200 lines (template + script)
-- < 10 props
-- Can describe in one sentence
-
-TOO BIG IF:
-- Multiple responsibilities
-- Lots of conditional rendering
-- Can't understand in 30 seconds
-- Needs comments to explain
-
-SPLIT INTO:
-- Container (data/logic) + Presenter (UI)
-- Multiple smaller components
-- Composable for shared logic
-```
-
-**Composition over complexity**:
-```vue
-<!-- BAD: One complex component -->
-<template>
-  <div>
-    <div v-if="mode === 'edit'">
-      <!-- 100 lines of edit form -->
-    </div>
-    <div v-else-if="mode === 'view'">
-      <!-- 100 lines of view display -->
-    </div>
-    <div v-else-if="mode === 'loading'">
-      <!-- 50 lines of skeleton -->
-    </div>
-  </div>
-</template>
-
-<!-- GOOD: Composed simple components -->
-<template>
-  <ProductSkeleton v-if="pending" />
-  <ProductEditForm v-else-if="mode === 'edit'" :product="data" @save="save" />
-  <ProductView v-else :product="data" @edit="startEdit" />
-</template>
-```
-
----
-
-## Pattern Decision Matrix
-
-Quick reference for choosing patterns:
-
-| Situation | Apply These Patterns |
-|-----------|---------------------|
-| Data from API | Loading + Error + Empty states |
-| User action → Server | Optimistic UI or Loading feedback |
-| Form with many fields | Form library + Validation schema |
-| Large list (100+ items) | Virtualization |
-| Heavy component rarely used | Lazy loading |
-| Multiple components need same data | State management (Pinia) |
-| Complex UI with many states | State machine |
-| Need to match existing code | Study patterns first, match exactly |
-| Reusable UI element | Extract to component |
-| Reusable logic | Extract to composable |
-
----
-
-## Component Structure
-
-Standard component organization:
-
-```vue
-<script setup lang="ts">
-// 1. Imports
-import { ref, computed, watch } from 'vue'
-import { useUserStore } from '@/stores/user'
-import ChildComponent from './ChildComponent.vue'
-
-// 2. Props & Emits
-const props = defineProps<{
-  title: string
-  items: Item[]
-}>()
-
-const emit = defineEmits<{
-  select: [item: Item]
-  close: []
-}>()
-
-// 3. Composables & Stores
-const userStore = useUserStore()
-const { data, pending, error } = await useFetch('/api/data')
-
-// 4. Local State
-const isOpen = ref(false)
-const searchQuery = ref('')
-
-// 5. Computed
-const filteredItems = computed(() =>
-  props.items.filter(item =>
-    item.name.includes(searchQuery.value)
-  )
-)
-
-// 6. Methods
-function handleSelect(item: Item) {
-  emit('select', item)
-}
-
-// 7. Lifecycle & Watchers
-watch(searchQuery, (newValue) => {
-  // React to changes
-})
-</script>
-
-<template>
-  <!-- Single root with clear structure -->
-</template>
-
-<style scoped>
-/* Component-specific styles */
-</style>
-```
-
----
-
-## UI States Template
-
-Every data component should handle:
-
-```vue
-<script setup>
-const { data, pending, error, refresh } = await useFetch('/api/resource')
-</script>
-
-<template>
-  <div class="resource-container">
-    <!-- Loading -->
-    <ResourceSkeleton v-if="pending" />
-
-    <!-- Error -->
-    <ErrorState
-      v-else-if="error"
-      :message="error.message"
-      @retry="refresh"
-    />
-
-    <!-- Empty -->
-    <EmptyState
-      v-else-if="!data || data.length === 0"
-      title="No resources found"
-      description="Create your first resource to get started"
-    >
-      <Button @click="openCreate">Create Resource</Button>
-    </EmptyState>
-
-    <!-- Success -->
-    <ResourceList v-else :items="data" />
-  </div>
-</template>
-```
-
----
-
-## Checklist Before Implementation
-
-- [ ] Which principle applies to this feature?
-- [ ] Does this match existing code patterns?
-- [ ] What are all the UI states? (loading, error, empty, success)
-- [ ] How can this feel instant?
-- [ ] Can it be used with keyboard only?
-- [ ] Does it work on mobile?
-- [ ] Where should state live?
-- [ ] Is this component doing too much?