@stephen-lord/docs 1.0.0

package/dist/agent-skills/glm-skills/frontend-design/SKILL.md

@@ -0,0 +1,981 @@
+---
+name: frontend-design
+description: Transform UI style requirements into production-ready frontend code with systematic design tokens, accessibility compliance, and creative execution. Use when building websites, web applications, React/Vue components, dashboards, landing pages, or any web UI requiring both design consistency and aesthetic quality.
+version: 2.0.0
+license: MIT
+---
+
+# Frontend Design Skill — Systematic & Creative Web Development
+
+**Skill Location**: `{project_path}/skills/frontend-design/`
+
+This skill transforms vague UI style requirements into executable, production-grade frontend code through a systematic design token approach while maintaining creative excellence. It ensures visual consistency, accessibility compliance, and maintainability across all deliverables.
+
+---
+
+## When to Use This Skill (Trigger Patterns)
+
+**MUST apply this skill when:**
+
+- User requests any website, web application, or web component development
+- User mentions design styles: "modern", "premium", "minimalist", "dark mode", "SaaS-style"
+- Building dashboards, landing pages, admin panels, or any web UI
+- User asks to "make it look better" or "improve the design"
+- Creating component libraries or design systems
+- User specifies frameworks: React, Vue, Svelte, Next.js, Nuxt, etc.
+- Converting designs/mockups to code
+- User mentions: Tailwind CSS, shadcn/ui, Material-UI, Chakra UI, etc.
+
+**Trigger phrases:**
+- "build a website/app/component"
+- "create a dashboard/landing page"
+- "design a UI for..."
+- "make it modern/clean/premium"
+- "style this with..."
+- "convert this design to code"
+
+**DO NOT use for:**
+- Backend API development
+- Pure logic/algorithm implementation
+- Non-visual code tasks
+
+---
+
+## Skill Architecture
+
+This skill provides:
+
+1. **SKILL.md** (this file): Core methodology and guidelines
+2. **examples/css/**: Production-ready CSS examples
+   - `tokens.css` - Design token system
+   - `components.css` - Reusable component styles
+   - `utilities.css` - Utility classes
+3. **examples/typescript/**: TypeScript implementation examples
+   - `design-tokens.ts` - Type-safe token definitions
+   - `theme-provider.tsx` - Theme management
+   - `sample-components.tsx` - Component examples
+4. **templates/**: Quick-start templates
+   - `tailwind-config.js` - Tailwind configuration
+   - `globals.css` - Global styles template
+
+---
+
+## Core Principles (Non-Negotiable)
+
+### 1. **Dual-Mode Thinking: System + Creativity**
+
+**Systematic Foundation:**
+- Design tokens first, UI components second
+- No arbitrary hardcoded values (colors, spacing, shadows, radius)
+- Consistent scales for typography, spacing, radius, elevation
+- Complete state coverage (default/hover/active/focus/disabled + loading/empty/error)
+- Accessibility as a constraint, not an afterthought
+
+**Creative Execution:**
+- AVOID generic "AI slop" aesthetics (Inter/Roboto fonts, purple gradients, cookie-cutter layouts)
+- Choose BOLD aesthetic direction: brutalist, retro-futuristic, luxury, playful, editorial, etc.
+- Make unexpected choices in typography, color, layout, and motion
+- Each design should feel unique and intentionally crafted for its context
+
+### 2. **Tokens-First Methodology**
+
+```
+Design Tokens → Component Styles → Page Layouts → Interactive States
+```
+
+**Never skip token definition.** All visual properties must derive from the token system.
+
+### 3. **Tech Stack Flexibility**
+
+**Default stack (if unspecified):**
+- Framework: React + TypeScript
+- Styling: Tailwind CSS
+- Components: shadcn/ui
+- Theme: CSS custom properties (light/dark modes)
+
+**Supported alternatives:**
+- Frameworks: Vue, Svelte, Angular, vanilla HTML/CSS
+- Styling: CSS Modules, SCSS, Styled Components, Emotion
+- Libraries: MUI, Ant Design, Chakra UI, Headless UI
+
+### 4. **Tailwind CSS Best Practices**
+
+**⚠️ CRITICAL: Never use Tailwind via CDN**
+
+**MUST use build-time integration:**
+```bash
+npm install -D tailwindcss postcss autoprefixer
+npx tailwindcss init -p
+```
+
+**Why build-time is mandatory:**
+- ✅ Enables tree-shaking (2-15KB vs 400KB+ bundle)
+- ✅ Full design token customization
+- ✅ IDE autocomplete and type safety
+- ✅ Integrates with bundlers (Vite, webpack, Next.js)
+
+**CDN only acceptable for:**
+- Quick prototypes/demos
+- Internal testing
+
+---
+
+## Implementation Workflow
+
+### Phase 1: Design Analysis & Token Definition
+
+**Step 1: Understand Context**
+```
+- Purpose: What problem does this solve? Who uses it?
+- Aesthetic Direction: Choose ONE bold direction
+- Technical Constraints: Framework, performance, accessibility needs
+- Differentiation: What makes this memorable?
+```
+
+**Step 2: Generate Design Tokens**
+
+Create comprehensive token system (see `examples/css/tokens.css` and `examples/typescript/design-tokens.ts`):
+
+1. **Semantic Color Slots** (light + dark modes):
+   ```
+   --background, --surface, --surface-subtle
+   --text, --text-secondary, --text-muted
+   --border, --border-subtle
+   --primary, --primary-hover, --primary-active, --primary-foreground
+   --secondary, --secondary-hover, --secondary-foreground
+   --accent, --success, --warning, --danger
+   ```
+
+2. **Typography Scale**:
+   ```
+   Display: 3.5rem/4rem (56px/64px), weight 700-800
+   H1: 2.5rem/3rem (40px/48px), weight 700
+   H2: 2rem/2.5rem (32px/40px), weight 600
+   H3: 1.5rem/2rem (24px/32px), weight 600
+   Body: 1rem/1.5rem (16px/24px), weight 400
+   Small: 0.875rem/1.25rem (14px/20px), weight 400
+   Caption: 0.75rem/1rem (12px/16px), weight 400
+   ```
+
+3. **Spacing Scale** (8px system):
+   ```
+   0.5 → 4px, 1 → 8px, 2 → 16px, 3 → 24px, 4 → 32px
+   5 → 40px, 6 → 48px, 8 → 64px, 12 → 96px, 16 → 128px
+   ```
+
+4. **Radius Scale**:
+   ```
+   xs: 2px (badges, tags)
+   sm: 4px (buttons, inputs)
+   md: 6px (cards, modals)
+   lg: 8px (large cards, panels)
+   xl: 12px (hero sections)
+   2xl: 16px (special elements)
+   full: 9999px (pills, avatars)
+   ```
+
+5. **Shadow Scale**:
+   ```
+   sm: Subtle lift (buttons, inputs)
+   md: Card elevation
+   lg: Modals, dropdowns
+   xl: Large modals, drawers
+   ```
+
+6. **Motion Tokens**:
+   ```
+   Duration: 150ms (micro), 220ms (default), 300ms (complex)
+   Easing: ease-out (enter), ease-in (exit), ease-in-out (transition)
+   ```
+
+### Phase 2: Component Development
+
+**Step 3: Build Reusable Components**
+
+Follow this structure (see `examples/typescript/sample-components.tsx`):
+
+```typescript
+interface ComponentProps {
+  variant?: 'primary' | 'secondary' | 'outline' | 'ghost';
+  size?: 'sm' | 'md' | 'lg';
+  state?: 'default' | 'hover' | 'active' | 'disabled' | 'loading';
+}
+```
+
+**Required component states:**
+- Default, Hover, Active, Focus, Disabled
+- Loading (skeleton/spinner)
+- Empty state (clear messaging)
+- Error state (recovery instructions)
+
+**Required component features:**
+- Accessible (ARIA labels, keyboard navigation)
+- Responsive (mobile-first)
+- Theme-aware (light/dark mode)
+- Token-based styling (no hardcoded values)
+
+### Phase 3: Page Assembly
+
+**Step 4: Compose Pages from Components**
+
+```
+- Use established tokens and components only
+- Mobile-first responsive design
+- Loading states for async content
+- Empty states with clear CTAs
+- Error states with recovery options
+```
+
+### Phase 4: Quality Assurance
+
+**Step 5: Self-Review Checklist**
+
+- [ ] All colors from semantic tokens (no random hex/rgb)
+- [ ] All spacing from spacing scale
+- [ ] All radius from radius scale
+- [ ] Shadows justified by hierarchy
+- [ ] Clear type hierarchy with comfortable line-height (1.5+)
+- [ ] All interactive states implemented and tested
+- [ ] Accessibility: WCAG AA contrast, keyboard navigation, ARIA, focus indicators
+- [ ] Responsive: works on mobile (375px), tablet (768px), desktop (1024px+)
+- [ ] Loading/empty/error states included
+- [ ] Code is maintainable: DRY, clear naming, documented
+
+---
+
+## Design Direction Templates
+
+### 1. Minimal Premium SaaS (Most Universal)
+
+```
+Visual Style: Minimal Premium SaaS
+- Generous whitespace (1.5-2x standard padding)
+- Near-white background with subtle surface contrast
+- Light borders (1px, low-opacity)
+- Very subtle elevation (avoid heavy shadows)
+- Unified control height: 44-48px
+- Medium-large radius: 6-8px
+- Gentle hover states (background shift only)
+- Clear but not harsh focus rings
+- Low-contrast dividers
+- Priority: Readability and consistency
+```
+
+**Best for:** Enterprise apps, B2B SaaS, productivity tools
+
+### 2. Bold Editorial
+
+```
+Visual Style: Bold Editorial
+- Strong typographic hierarchy (large display fonts)
+- High contrast (black/white or dark/light extremes)
+- Generous use of negative space
+- Asymmetric layouts with intentional imbalance
+- Grid-breaking elements
+- Minimal color palette (1-2 accent colors max)
+- Sharp, geometric shapes
+- Dramatic scale differences
+- Priority: Visual impact and memorability
+```
+
+**Best for:** Marketing sites, portfolios, content-heavy sites
+
+### 3. Soft & Organic
+
+```
+Visual Style: Soft & Organic
+- Rounded corners everywhere (12-24px radius)
+- Soft shadows and subtle gradients
+- Pastel or muted color palette
+- Gentle animations (ease-in-out, 300-400ms)
+- Curved elements and flowing layouts
+- Generous padding (1.5-2x standard)
+- Soft, blurred backgrounds
+- Priority: Approachability and comfort
+```
+
+**Best for:** Consumer apps, wellness, lifestyle brands
+
+### 4. Dark Neon (Restrained)
+
+```
+Visual Style: Dark Neon
+- Dark background (#0a0a0a to #1a1a1a, NOT pure black)
+- High contrast text (#ffffff or #fafafa)
+- Accent colors ONLY for CTAs and key states
+- Subtle glow on hover (box-shadow with accent color)
+- Minimal borders (use subtle outlines)
+- Optional: Subtle noise texture
+- Restrained use of neon (less is more)
+- Priority: Focus and sophisticated edge
+```
+
+**Best for:** Developer tools, gaming, tech products
+
+### 5. Playful & Colorful
+
+```
+Visual Style: Playful & Colorful
+- Vibrant color palette (3-5 colors)
+- Rounded corners (8-16px)
+- Micro-animations on hover/interaction
+- Generous padding and breathing room
+- Friendly, geometric illustrations
+- Smooth transitions (200-250ms)
+- High energy but balanced
+- Priority: Delight and engagement
+```
+
+**Best for:** Consumer apps, children's products, creative tools
+
+---
+
+## Standard Prompting Workflow
+
+### Master Prompt Template
+
+```
+You are a Design Systems Engineer + Senior Frontend UI Developer with expertise in creative design execution.
+
+[TECH STACK]
+- Framework: {{FRAMEWORK = React + TypeScript}}
+- Styling: {{STYLING = Tailwind CSS}}
+- Components: {{UI_LIB = shadcn/ui}}
+- Theme: CSS variables (light/dark modes)
+
+[DESIGN SYSTEM RULES - MANDATORY]
+1. Layout: 8px spacing system; mobile-first responsive
+2. Typography: Clear hierarchy (Display/H1/H2/H3/Body/Small/Caption); line-height 1.5+
+3. Colors: Semantic tokens ONLY (no hardcoded values)
+4. Shape: Tiered radius system; tap targets ≥ 44px
+5. Elevation: Minimal shadows; borders for hierarchy
+6. Motion: Subtle transitions (150-220ms); restrained animations
+7. Accessibility: WCAG AA; keyboard navigation; ARIA; focus indicators
+
+[AESTHETIC DIRECTION]
+Style: {{STYLE = Minimal Premium SaaS}}
+Key Differentiator: {{UNIQUE_FEATURE}}
+Target Audience: {{AUDIENCE}}
+
+[INTERACTION STATES - REQUIRED]
+✓ Default, Hover, Active, Focus, Disabled
+✓ Loading (skeleton), Empty (with messaging), Error (with recovery)
+
+[OUTPUT REQUIREMENTS]
+1. Design Tokens (CSS variables + TypeScript types)
+2. Component implementations (copy-paste ready)
+3. Page layouts with all states
+4. NO hardcoded values; reference tokens only
+5. Minimal but clear code comments
+```
+
+### Token Generation Prompt
+
+```
+Generate a complete Design Token system including:
+
+1. Semantic color slots (CSS custom properties):
+   - Light mode + Dark mode variants
+   - Background, surface, text, border, primary, secondary, accent, semantic colors
+   - Interactive states for each (hover, active)
+
+2. Typography scale:
+   - Display, H1-H6, Body, Small, Caption, Monospace
+   - Include: font-size, line-height, font-weight, letter-spacing
+
+3. Spacing scale (8px base):
+   - 0.5, 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24 (in rem)
+
+4. Radius scale:
+   - xs (2px), sm (4px), md (6px), lg (8px), xl (12px), 2xl (16px), full
+
+5. Shadow scale:
+   - sm, md, lg, xl (with color and blur values)
+   - Usage guidelines for each tier
+
+6. Motion tokens:
+   - Duration: fast (150ms), base (220ms), slow (300ms)
+   - Easing: ease-out, ease-in, ease-in-out
+
+7. Component density:
+   - Button heights: sm (36px), md (44px), lg (48px)
+   - Input heights: sm (36px), md (40px)
+   - Padding scales
+
+Output format:
+- CSS custom properties (globals.css)
+- Tailwind config integration
+- TypeScript type definitions
+- Usage examples for each token category
+
+DO NOT write component code yet.
+```
+
+### Component Implementation Prompt
+
+```
+Using the established Design Tokens, implement: <{{COMPONENT_NAME}} />
+
+Requirements:
+- Props: variant, size, state, className (for composition)
+- States: default, hover, focus, active, disabled, loading, error
+- Accessibility: keyboard navigation, ARIA labels, focus management
+- Responsive: mobile-first, touch-friendly (44px+ tap targets)
+- Styling: Use tokens ONLY (no hardcoded values)
+- TypeScript: Full type safety with exported interfaces
+
+Include:
+1. Component implementation
+2. Usage examples (3-5 variants)
+3. Loading state example
+4. Error state example
+5. Accessibility notes
+
+Output: Production-ready, copy-paste code with JSDoc comments.
+```
+
+### Page Development Prompt
+
+```
+Build page: {{PAGE_NAME}}
+
+Using:
+- Established Design Tokens
+- Implemented Components
+- {{STYLE}} aesthetic direction
+
+Requirements:
+- Responsive layout (mobile/tablet/desktop)
+- All interaction states (hover/focus/active/disabled)
+- Loading skeleton for async content
+- Empty state with clear CTA
+- Error state with recovery options
+- Accessible (keyboard nav, ARIA, WCAG AA)
+- No hardcoded styles (components + utility classes only)
+
+Include:
+1. Page component with mock data
+2. Loading state variant
+3. Empty state variant
+4. Error state variant
+5. Responsive behavior notes
+
+Output: Complete, runnable page component.
+```
+
+### Review & Optimization Prompt
+
+```
+You are a Frontend Code Reviewer specializing in design systems and accessibility.
+
+Review the implementation and check:
+
+1. Token Compliance:
+   - Any hardcoded colors, sizes, shadows, radius?
+   - All values from established scales?
+
+2. Typography:
+   - Clear hierarchy?
+   - Comfortable line-height (1.5+)?
+   - Appropriate font sizes for each level?
+
+3. Spacing & Layout:
+   - Consistent use of spacing scale?
+   - Adequate whitespace?
+   - No awkward gaps or cramped sections?
+
+4. Interactive States:
+   - Hover/focus/active clearly distinct?
+   - Disabled state obviously different?
+   - Loading/empty/error states implemented?
+
+5. Accessibility:
+   - WCAG AA contrast met?
+   - Keyboard reachable?
+   - ARIA labels complete?
+   - Focus indicators visible?
+   - Semantic HTML?
+
+6. Responsive Design:
+   - Mobile layout functional (375px)?
+   - Tablet optimized (768px)?
+   - Desktop enhanced (1024px+)?
+   - Touch targets ≥ 44px?
+
+7. Maintainability:
+   - DRY principles followed?
+   - Clear component boundaries?
+   - Consistent naming?
+   - Adequate comments?
+
+8. Creative Execution:
+   - Matches intended aesthetic?
+   - Avoids generic patterns?
+   - Unique and memorable?
+
+Output:
+- Findings (sorted by severity: Critical, High, Medium, Low)
+- Specific fixes (code patches)
+- Improvement suggestions
+```
+
+---
+
+## Common Pitfalls & Solutions
+
+### ❌ Problem: Vague aesthetic descriptions
+### ✅ Solution: Force actionable specifications
+
+```
+DON'T: "Make it modern and clean"
+DO: 
+- Whitespace: 1.5x standard padding (24px instead of 16px)
+- Typography: Display 56px, H1 40px, Body 16px, line-height 1.6
+- Colors: Neutral gray scale (50-900) + single accent color
+- Shadows: Maximum 2 shadow tokens (card + modal only)
+- Radius: Consistent 6px (buttons/inputs) and 8px (cards)
+- Borders: 1px with --border-subtle (#e5e7eb in light mode)
+- Transitions: 150ms ease-out only
+```
+
+### ❌ Problem: Each component invents its own styles
+### ✅ Solution: Enforce token-only rule
+
+```
+RULE: Every visual property must map to a token.
+
+Violations:
+- ❌ bg-gray-100 (hardcoded Tailwind color)
+- ❌ p-[17px] (arbitrary padding not in scale)
+- ❌ rounded-[5px] (radius not in scale)
+- ❌ shadow-[0_2px_8px_rgba(0,0,0,0.1)] (arbitrary shadow)
+
+Correct:
+- ✅ bg-surface (semantic token)
+- ✅ p-4 (maps to spacing scale: 16px)
+- ✅ rounded-md (maps to radius scale: 6px)
+- ✅ shadow-sm (maps to shadow token)
+```
+
+### ❌ Problem: Missing interactive states
+### ✅ Solution: State coverage checklist
+
+```
+For EVERY interactive element, implement:
+
+Visual States:
+- [ ] Default (base appearance)
+- [ ] Hover (background shift, shadow, scale)
+- [ ] Active (pressed state, slightly darker)
+- [ ] Focus (visible ring, keyboard accessible)
+- [ ] Disabled (reduced opacity, cursor not-allowed)
+
+Data States:
+- [ ] Loading (skeleton or spinner with same dimensions)
+- [ ] Empty (clear message + CTA)
+- [ ] Error (error message + retry option)
+
+Test each state in isolation and in combination.
+```
+
+### ❌ Problem: Generic AI aesthetics
+### ✅ Solution: Force creative differentiation
+
+```
+BANNED PATTERNS (overused in AI-generated UIs):
+- ❌ Inter/Roboto/System fonts as primary choice
+- ❌ Purple gradients on white backgrounds
+- ❌ Card-grid-card-grid layouts only
+- ❌ Generic blue (#3b82f6) as primary
+- ❌ Default Tailwind color palette with no customization
+
+REQUIRED CREATIVE CHOICES:
+- ✅ Select distinctive fonts (Google Fonts, Adobe Fonts, custom)
+- ✅ Build custom color palette (not Tailwind defaults)
+- ✅ Design unique layouts (asymmetry, overlap, grid-breaking)
+- ✅ Add personality: illustrations, icons, textures, patterns
+- ✅ Create signature elements (unique buttons, cards, headers)
+
+Ask yourself: "Would someone recognize this as uniquely designed for this purpose?"
+```
+
+### ❌ Problem: Accessibility as afterthought
+### ✅ Solution: Accessibility as constraint
+
+```
+Build accessibility IN, not ON:
+
+Color Contrast:
+- Run contrast checker on all text/background pairs
+- Minimum WCAG AA: 4.5:1 (normal text), 3:1 (large text)
+- Use tools: WebAIM Contrast Checker, Chrome DevTools
+
+Keyboard Navigation:
+- Tab order follows visual flow
+- All interactive elements keyboard reachable
+- Focus indicator always visible (outline or ring)
+- Escape closes modals/dropdowns
+
+ARIA & Semantics:
+- Use semantic HTML first (<button>, <nav>, <main>)
+- Add ARIA only when semantic HTML insufficient
+- aria-label for icon-only buttons
+- aria-describedby for form errors
+- aria-expanded for disclosure widgets
+
+Test with:
+- Keyboard only (no mouse)
+- Screen reader (NVDA, JAWS, VoiceOver)
+- Reduced motion preference (prefers-reduced-motion)
+```
+
+---
+
+## Quick Start: Complete Example
+
+```
+You are a Design Systems Engineer + Senior Frontend UI Developer.
+
+[STACK]
+React + TypeScript + Tailwind CSS + shadcn/ui
+
+[TASK]
+Build a Team Dashboard for a project management app.
+
+[AESTHETIC]
+Style: Minimal Premium SaaS
+Unique Element: Subtle animated background gradient
+Audience: Product managers and software teams
+
+[REQUIREMENTS]
+1. Components needed:
+   - Header with search and user menu
+   - Team members grid (name, role, avatar, status)
+   - Invite modal (name, email, role selector)
+   - Empty state (no team members yet)
+   - Loading skeleton
+
+2. Features:
+   - Search/filter team members
+   - Click to view member details
+   - Invite button opens modal
+   - Sort by name/role/status
+
+3. States:
+   - Loading (skeleton grid)
+   - Empty (with invite CTA)
+   - Populated (member cards)
+   - Error (failed to load)
+
+[OUTPUT]
+1. Design Tokens (globals.css + tailwind.config.ts)
+2. Component implementations:
+   - TeamMemberCard
+   - InviteModal
+   - SearchBar
+   - UserMenu
+3. TeamDashboard page component
+4. All states (loading/empty/error)
+5. Full TypeScript types
+6. Accessibility notes
+
+Rules:
+- Mobile-first responsive
+- No hardcoded values (use tokens)
+- WCAG AA compliance
+- Include hover/focus/active states
+- Add subtle micro-interactions
+```
+
+---
+
+## Examples & Templates
+
+This skill includes production-ready examples in `examples/`:
+
+### CSS Examples (`examples/css/`)
+
+**`tokens.css`** — Complete design token system
+- Semantic color tokens (light + dark modes)
+- Typography scale with fluid sizing
+- Spacing, radius, shadow, motion scales
+- CSS custom properties ready to use
+
+**`components.css`** — Component style library
+- Buttons (variants, sizes, states)
+- Inputs, textareas, selects
+- Cards, modals, tooltips
+- Navigation, headers, footers
+- Loading skeletons
+- All with state variants (hover/focus/active/disabled)
+
+**`utilities.css`** — Utility class library
+- Layout utilities (flex, grid, container)
+- Spacing utilities (margin, padding)
+- Typography utilities (sizes, weights, line-heights)
+- State utilities (hover, focus, group variants)
+
+### TypeScript Examples (`examples/typescript/`)
+
+**`design-tokens.ts`** — Type-safe token definitions
+- Token interfaces and types
+- Design system configuration
+- Theme type definitions
+- Token validators
+
+**`theme-provider.tsx`** — Theme management system
+- Theme context provider
+- Dark mode toggle
+- System preference detection
+- Theme persistence (localStorage)
+
+**`sample-components.tsx`** — Production component examples
+- Button component (all variants)
+- Input component (with validation)
+- Card component (with loading states)
+- Modal component (with focus management)
+- All with full TypeScript types and accessibility
+
+### Templates (`templates/`)
+
+**`tailwind-config.js`** — Optimized Tailwind configuration
+- Custom color palette
+- Typography plugin setup
+- Spacing and sizing scales
+- Plugin configurations
+
+**`globals.css`** — Global styles template
+- CSS reset/normalize
+- Token definitions
+- Base element styles
+- Utility classes
+
+---
+
+## Output Quality Standards
+
+Every deliverable must meet:
+
+### Code Quality
+- ✅ Production-ready (copy-paste deployable)
+- ✅ TypeScript with full type safety
+- ✅ ESLint/Prettier compliant
+- ✅ No hardcoded magic numbers
+- ✅ DRY (Don't Repeat Yourself)
+- ✅ Clear, descriptive naming
+- ✅ JSDoc comments for complex logic
+
+### Design Quality
+- ✅ Unique, memorable aesthetic
+- ✅ Consistent token usage
+- ✅ Cohesive visual language
+- ✅ Thoughtful micro-interactions
+- ✅ Polished details (shadows, transitions, spacing)
+
+### Accessibility Quality
+- ✅ WCAG AA minimum (AAA preferred)
+- ✅ Keyboard navigable
+- ✅ Screen reader friendly
+- ✅ Focus management
+- ✅ Semantic HTML
+- ✅ ARIA when necessary
+
+### Performance Quality
+- ✅ Optimized bundle size (tree-shaking)
+- ✅ Lazy loading for heavy components
+- ✅ CSS-only animations when possible
+- ✅ Minimal re-renders (React memo/useMemo)
+- ✅ Responsive images (srcset, sizes)
+
+---
+
+## Verification Checklist
+
+Before delivering code, verify:
+
+**Tokens & System:**
+- [ ] All colors from semantic tokens (no hex/rgb hardcoded)
+- [ ] All spacing from spacing scale (8px system)
+- [ ] All radius from radius scale (xs/sm/md/lg/xl/2xl/full)
+- [ ] Shadows minimal and justified
+- [ ] Typography hierarchy clear (Display/H1/H2/H3/Body/Small/Caption)
+- [ ] Line-height comfortable (1.5+ for body text)
+
+**States & Interactions:**
+- [ ] Default state implemented
+- [ ] Hover state (visual feedback)
+- [ ] Active state (pressed appearance)
+- [ ] Focus state (keyboard ring visible)
+- [ ] Disabled state (reduced opacity, no pointer)
+- [ ] Loading state (skeleton or spinner)
+- [ ] Empty state (clear message + CTA)
+- [ ] Error state (message + recovery)
+
+**Accessibility:**
+- [ ] WCAG AA contrast (4.5:1 text, 3:1 large text)
+- [ ] Keyboard navigation complete
+- [ ] Focus indicators always visible
+- [ ] Semantic HTML used
+- [ ] ARIA labels where needed
+- [ ] Form labels associated
+- [ ] Alt text on images
+
+**Responsive Design:**
+- [ ] Mobile layout (375px+) functional
+- [ ] Tablet layout (768px+) optimized
+- [ ] Desktop layout (1024px+) enhanced
+- [ ] Touch targets ≥ 44px
+- [ ] Text readable on all sizes
+- [ ] No horizontal scroll
+
+**Creative Execution:**
+- [ ] Unique aesthetic (not generic)
+- [ ] Matches stated design direction
+- [ ] Memorable visual element
+- [ ] Cohesive design language
+- [ ] Polished details
+
+**Code Quality:**
+- [ ] TypeScript types complete
+- [ ] No linter errors
+- [ ] DRY principles followed
+- [ ] Clear component boundaries
+- [ ] Consistent naming conventions
+- [ ] Adequate comments
+- [ ] Production-ready (can deploy as-is)
+
+---
+
+## Advanced Techniques
+
+### 1. Fluid Typography
+
+```css
+/* Responsive type scale using clamp() */
+:root {
+  --font-size-sm: clamp(0.875rem, 0.8rem + 0.2vw, 1rem);
+  --font-size-base: clamp(1rem, 0.9rem + 0.3vw, 1.125rem);
+  --font-size-lg: clamp(1.125rem, 1rem + 0.4vw, 1.25rem);
+  --font-size-xl: clamp(1.25rem, 1.1rem + 0.5vw, 1.5rem);
+  --font-size-2xl: clamp(1.5rem, 1.3rem + 0.7vw, 2rem);
+  --font-size-3xl: clamp(1.875rem, 1.5rem + 1vw, 2.5rem);
+  --font-size-4xl: clamp(2.25rem, 1.8rem + 1.5vw, 3.5rem);
+}
+```
+
+### 2. Advanced Color Systems
+
+```css
+/* Color with opacity variants using oklch */
+:root {
+  --primary-base: oklch(60% 0.15 250);
+  --primary-subtle: oklch(95% 0.02 250);
+  --primary-muted: oklch(85% 0.05 250);
+  --primary-emphasis: oklch(50% 0.18 250);
+  --primary-foreground: oklch(98% 0.01 250);
+}
+
+/* Dark mode: adjust lightness only */
+[data-theme="dark"] {
+  --primary-base: oklch(70% 0.15 250);
+  --primary-subtle: oklch(20% 0.02 250);
+  --primary-muted: oklch(30% 0.05 250);
+  --primary-emphasis: oklch(80% 0.18 250);
+  --primary-foreground: oklch(10% 0.01 250);
+}
+```
+
+### 3. Skeleton Loading Patterns
+
+```tsx
+// Animated skeleton with shimmer effect
+const Skeleton = ({ className }: { className?: string }) => (
+  <div
+    className={cn(
+      "animate-pulse rounded-md bg-surface-subtle",
+      "relative overflow-hidden",
+      "before:absolute before:inset-0",
+      "before:-translate-x-full before:animate-shimmer",
+      "before:bg-gradient-to-r before:from-transparent before:via-white/10 before:to-transparent",
+      className
+    )}
+  />
+);
+
+// Usage in components
+<Card>
+  <Skeleton className="h-4 w-3/4 mb-2" />
+  <Skeleton className="h-4 w-1/2 mb-4" />
+  <Skeleton className="h-32 w-full" />
+</Card>
+```
+
+### 4. Advanced Motion
+
+```css
+/* Page transitions */
+@keyframes fade-in {
+  from {
+    opacity: 0;
+    transform: translateY(8px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+/* Staggered animations */
+.stagger-item {
+  animation: fade-in 0.3s ease-out backwards;
+}
+.stagger-item:nth-child(1) { animation-delay: 0ms; }
+.stagger-item:nth-child(2) { animation-delay: 50ms; }
+.stagger-item:nth-child(3) { animation-delay: 100ms; }
+.stagger-item:nth-child(4) { animation-delay: 150ms; }
+
+/* Respect reduced motion */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+---
+
+## Tips for Excellence
+
+1. **Always start with tokens** — Never skip to components
+2. **Think mobile-first** — Design for 375px, enhance upward
+3. **Validate states early** — Test each interactive state in isolation
+4. **Be bold with aesthetics** — Avoid generic patterns
+5. **Accessibility is non-negotiable** — Build it in from the start
+6. **Use real content** — Test with actual text, images, data
+7. **Review your own work** — Self-audit before delivering
+8. **Document decisions** — Explain complex styling choices
+9. **Keep it maintainable** — Future developers will thank you
+10. **Ship production-ready code** — No "TODO" or "FIXME" in deliverables
+
+---
+
+## References & Resources
+
+- **Tailwind CSS**: https://tailwindcss.com/docs
+- **shadcn/ui**: https://ui.shadcn.com
+- **WCAG Guidelines**: https://www.w3.org/WAI/WCAG21/quickref/
+- **Color Contrast Checker**: https://webaim.org/resources/contrastchecker/
+- **Type Scale**: https://typescale.com
+- **Modular Scale**: https://www.modularscale.com
+- **CSS Custom Properties**: https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties
+
+---
+
+**Version**: 2.0.0  
+**Last Updated**: December 2024  
+**License**: MIT  
+**Maintained by**: z-ai platform team