frontend-design

# Frontend Design (UI/UX for Developers) Practical UI/UX guidance with strict best-practice enforcement for responsive, accessible interfaces. ## When to Use Me Use me when: - Building user interfaces (web, mobile, desktop) - Designing forms, dashboards, landing pages - Implementing responsive layouts - Adding animations or micro-interactions - Reviewing UI for accessibility issues - Creating component states (loading, error, empty) - Setting up design systems Do not use me for: - Backend architecture - Database design - API development - Business logic implementation --- ## Non-Negotiable Enforcement Rules For restyling/design tasks, these rules are mandatory: 1. **Mobile-first is required**: build 375px base first, then enhance with breakpoints. 2. **All domain checks must pass**: mobile, typography, hierarchy, states, forms, interaction, animation, accessibility. 3. **Final deep scan is required**: run domain-by-domain validation and patch gaps before final output. 4. **No partial completion**: if a domain fails, iterate until all critical checks pass. --- ## Workflow (Best-Practice Enforcement) 1. **Analyze requirements** - Identify product type and constraints from `references/product-recommendations.csv` - Determine primary user action and success metric 2. **Apply mobile-first (VERPLICHT)** - Start with mobile base (375px), no desktop-first classes - Enforce touch targets >= 44x44 and >= 8px spacing - Place primary actions in thumb-friendly zones 3. **Apply typography system** - Max 2 fonts - Consistent type scale and heading/body contrast - Body text min 16px, readable line height 4. **Apply visual hierarchy** - Prioritize with size -> color -> weight -> position - Keep clear scanning order (headline, key value, CTA, details) 5. **Enhance for larger screens** - Add `sm:`, `md:`, `lg:`, `xl:` progressively - Validate on 375, 768, 1024, and 1440 widths 6. **Implement component and form states** - Component states: default, hover, focus, active, disabled, loading, error, success - Form UX: visible labels, field-level errors, correct input types, submit feedback 7. **Review interaction patterns** - Apply Fitts's Law (target size/proximity) - Apply Hick's Law (limit choices) - Add explicit feedback timing for user actions 8. **Apply motion safely** - Use short, purposeful motion - Animate transform/opacity only - Respect reduced-motion preferences 9. **Check accessibility (WCAG 2.1 AA)** - Contrast >= 4.5:1 for normal text - Visible focus states and keyboard reachability - ARIA labels where needed - No color-only meaning 10. **Run deep scan and iterate** - Run the domain checklist below - Fix all failed items - Re-scan until zero critical failures --- ## Domain Gate Checklist (Must Pass) | Domain | Mandatory Checks | Reference | | -------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------- | | Mobile UX | 375px base first, touch >= 44x44, spacing >= 8px, thumb-friendly actions, no desktop-first | `references/mobile-ux.md` | | Typography | Max 2 fonts, min 16px body text, readable line-height, stable type scale | `references/typography.md` | | Visual Hierarchy | Size/color/weight/position priorities are clear | `references/visual-hierarchy.md` | | Component States | default/hover/focus/active/disabled/loading/error/success all covered | `references/component-states.md` | | Forms UX | Visible labels, input types, validation timing, field-level errors, submit feedback | `references/forms-ux.md` | | Interaction Patterns | Fitts + Hick + error prevention + timed feedback | `references/interaction-patterns.md` | | Animation | <= 300ms UI motion, transform/opacity only, reduced-motion support | `references/animation.md` | | Accessibility | WCAG contrast, focus visibility, ARIA naming, keyboard flow, no color-only signals | `references/contrast-accessibility.md` | | UX Guidelines | Resolve any high-severity conflicts before final output | `references/ux-guidelines.csv` | | Product Fit | Style direction aligns with product type and context | `references/product-recommendations.csv` | If any row fails, do not finalize. Fix and re-run the checklist. --- ## Quick Reference ### Component States Checklist Every interactive component needs: | State | Visual | Code Example | | ------------ | --------------------- | ---------------------------------- | | **Default** | Normal appearance | `class="btn"` | | **Hover** | Subtle feedback | `hover:bg-gray-100` | | **Focus** | Visible ring (a11y) | `focus:ring-2 focus:ring-blue-500` | | **Active** | Pressed feedback | `active:scale-95` | | **Disabled** | Reduced opacity | `opacity-50 cursor-not-allowed` | | **Loading** | Spinner + disabled | `disabled spinner` | | **Error** | Red border + message | `border-red-500 text-red-600` | | **Success** | Positive confirmation | `text-green-700 border-green-300` | ### Touch Targets - **Minimum size**: 44x44px - **Minimum gap**: 8px between targets - **Code**: `min-h-[44px] min-w-[44px]` ### Typography Quick Rules | Element | Size | Weight | Line Height | | ------- | ------- | -------- | ----------- | | H1 | 32-48px | Bold | 1.2-1.3 | | H2 | 24-32px | Semibold | 1.3-1.4 | | Body | 16px | Regular | 1.5-1.6 | | Small | 12-14px | Regular | 1.4-1.5 | | Minimum | 12px | - | - | - **Max fonts**: 2 families - **Line length**: 65-75ch desktop, 30-40ch mobile ### Color Accessibility - **Normal text**: 4.5:1 contrast ratio minimum - **Large text**: 3:1 contrast ratio minimum - **Never rely on color alone** - add icons or text ### Mobile-First Checklist Bij elke styling taak: | Check | Voorbeeld | | -------------------------- | --------------------------- | | ✅ Base = mobile (375px) | `flex flex-col gap-4 p-4` | | ✅ Enhance met breakpoints | `md:flex-row md:gap-8` | | ✅ Touch targets ≥ 44px | `min-h-[44px] min-w-[44px]` | | ✅ Primary actions bottom | Fixed bottom nav | | ❌ No desktop-first | Niet `lg:` als basis | ### Motion Checklist - UI motion meestal <= 300ms - Alleen `transform` en `opacity` animeren - `prefers-reduced-motion` respecteren - Geen decoratieve oneindige animaties --- ### Mobile-First Regel (Altijd Toepassen) ``` ❌ FOUT: Desktop first, dan "fixen" voor mobile class="flex-row gap-8 p-8 md:flex-col md:gap-4 md:p-4" ✅ GOED: Mobile base, enhance voor desktop class="flex flex-col gap-4 p-4 md:flex-row md:gap-8 md:p-8" ``` **Tailwind volgorde**: base styles (mobile) → `sm:` (640px) → `md:` (768px) → `lg:` (1024px) → `xl:` (1280px) --- ## Key Principles ### 1. Mobile-First (VERPLICHT) **Bij ELKE styling of restyling taak: begin met mobile (375px), enhance voor grotere schermen.** Dit is niet optioneel - mobile-first zorgt voor: - Betere performance (minder CSS op mobile) - Betere UX (meest beperkte scherm eerst) - Eenvoudigere code (additive, niet subtractive) ```html <!-- ❌ FOUT: Desktop first --> <div class="flex-row gap-8 p-8 md:flex-col md:gap-4 md:p-4"></div> <!-- ✅ GOED: Mobile first --> <div class="flex flex-col gap-4 p-4 md:flex-row md:gap-8 md:p-8"></div> ``` **Zie**: `references/mobile-ux.md` voor complete mobile patterns. ### 2. Typography Before Decoration Text clarity comes before ornamental style: - Body text stays readable on mobile (>= 16px) - Heading scale is consistent - No more than 2 font families - Paragraph width remains scannable ### 3. Visual Hierarchy Guide user attention through: - **Size**: Larger = more important - **Color**: Darker/vibrant = more attention - **Weight**: Bolder = stands out - **Position**: Top/center = noticed first ### 4. Feedback Every action needs response: - **Immediate**: Button press, hover state - **Progress**: Loading spinners, skeletons - **Completion**: Success toasts, checkmarks - **Failure**: Error messages with recovery ### 5. Accessibility (WCAG 2.1) Non-negotiable requirements: - All images have `alt` text - All inputs have labels - All interactive elements have focus states - Color contrast meets 4.5:1 minimum - Never convey info by color alone - Respect reduced-motion settings --- ## Common Patterns ### Form UX ``` ✓ Label above input ✓ Error below input ✓ Inline validation on blur ✓ Show/hide password toggle ✓ Appropriate input types (email, tel, number) ✓ Required field indicators ✓ Submit feedback (loading + success/error) ``` ### Loading States ``` ✓ Skeleton screens for content ✓ Spinners for actions ✓ Progress bars for multi-step ✓ Disable buttons during submission ✓ Reduced-motion fallback ``` ### Empty States ``` ✓ Clear message explaining why empty ✓ Actionable CTA to fix it ✓ Helpful tips or suggestions ✓ Maintain brand personality ✓ Focusable CTA for keyboard users ``` ### Error Handling ``` ✓ Clear message what went wrong ✓ Actionable solution ✓ Preserve user input ✓ Don't blame the user ✓ Announce critical errors (`role="alert"`) ``` --- ## Anti-Patterns to Avoid | Don't | Do Instead | | ------------------------ | ----------------------------- | | Remove focus outlines | Add custom focus styles | | Use placeholder as label | Always show visible label | | Auto-play video/audio | Click-to-play only | | Infinite animations | Animate on interaction | | Generic "Error occurred" | Specific error with solution | | Disable zoom | Never disable user zoom | | Fixed 100vh on mobile | Use `min-h-dvh` | | More than 2 fonts | Keep typography system simple | | Animate width/height | Animate transform/opacity | --- ## Design Workflow Example: Card Component Restyling Een praktisch voorbeeld van hoe je een component restyled met mobile-first aanpak. ### Scenario **Opdracht**: Restyle een simpele ProductCard naar een moderne DashboardCard **Before (Desktop-first, verouderd)**: ```html <div class="w-80 h-48 p-6 border rounded shadow-lg flex-row gap-4"> <img class="w-32 h-32 object-cover" src="product.jpg" /> <div class="flex-1"> <h3 class="text-xl font-bold mb-2">Product Naam</h3> <p class="text-gray-600 mb-4">Omschrijving...</p> <button class="bg-blue-500 text-white px-4 py-2 rounded">Bekijk</button> </div> </div> ``` **Problemen**: - ❌ Desktop-first (w-80, flex-row als basis) - ❌ Geen responsive breakpoints - ❌ Touch target te klein (py-2 < 44px) - ❌ Geen states (hover, focus, loading) - ❌ Geen accessibility (geen alt, geen focus ring) --- ### Stap 1: Mobile Base (375px) Start met de kleinste schermgrootte. Verticale layout, full-width, voldoende touch targets. ```html <!-- Mobile base - altijd eerst! --> <article class="p-4 border rounded-lg"> <img class="w-full h-40 object-cover rounded" src="product.jpg" alt="Product afbeelding" />