ui-ux-master 1.2.1 → 1.5.0

package/references/brand-method-playful-familiarity.md

@@ -0,0 +1,284 @@
+# Brand Method: Playful Familiarity
+
+Use this skill when building for food and beverage retail, family brands, toys, children's platforms, casual consumer apps, or any context where the primary emotion is delight, comfort, and ease.
+
+Reference brands: McDonald's, KFC, Burger King, Domino's, Starbucks, LEGO, Nintendo, Coca-Cola, Nestlé, Colgate, Costco.
+
+---
+
+## When to Apply This Method
+
+Apply Playful Familiarity when:
+- The brand uses friendly, familiar, or joyful tone as a key differentiator.
+- The audience is broad: families, children, casual users, all age groups.
+- The primary task is order, find, or buy — but the experience should feel fun, not cold.
+- Brand characters, mascots, or iconic imagery are key recognition assets.
+
+Do not apply when:
+- The brand is luxury or premium (use Premium Restraint).
+- The product is enterprise software or professional tools (use Enterprise Trust Hub or Technical Authority).
+- The primary goal is brand storytelling without task completion (use Editorial Brand World).
+
+---
+
+## Layout Structure
+
+### Hero
+- Brand imagery dominant: food photography, character/mascot, product in context.
+- Warm, bright, inviting — the hero should make the user feel good immediately.
+- Headline: short, friendly, direct. "Order Now." "What are you craving?" "Start Building."
+- CTA: bold, large, visible — "Order Now", "Find a Store", "Shop Now."
+- Promotional strip: thin banner above or below hero with current offer.
+
+### Navigation
+- Clear, simple, icons + labels.
+- Categories visible in nav or below hero (not hidden in hamburger on desktop).
+- Key CTAs in nav: "Order Now", "Delivery", "Store Finder."
+- Mobile: bottom navigation bar (food ordering / consumer apps) OR clear hamburger.
+
+### Homepage Sections (in order)
+1. **Hero** — brand world, CTA, current promotion.
+2. **Featured offers / menu highlights** — 3-4 featured items with prices, large photos.
+3. **Order method selection** — Delivery / Takeaway / Dine-in (food brands).
+4. **Brand story snippet** — 1-2 paragraphs or a visual story block, friendly tone.
+5. **Loyalty / rewards** — app or rewards program teaser.
+6. **Location finder** — map or zip code input.
+
+### Menu / Product Page
+- Large food photography or product imagery.
+- Clear product name, price, description (friendly tone).
+- Customization options (size, extras, add-ons): large touch targets, visible choices.
+- "Add to Order" / "Add to Cart": prominent, colored, full-width on mobile.
+- Allergen info: accessible, visible, not buried.
+
+---
+
+## Color Scheme
+
+### Palette Archetypes
+
+**Fast Food (McDonald's, KFC, Burger King)**
+- McDonald's: `#FFC72C` (yellow) + `#DA291C` (red) on white
+- KFC: `#E4002B` (red) + `#000000` on white
+- Burger King: `#E8611A` (orange/red) + `#502314` (brown) + cream `#F5F0E5`
+- Rule: high-energy primaries, white background, CTA uses the brightest brand color.
+
+**Coffee / Comfort (Starbucks)**
+- Primary: `#00704A` (green)
+- Background: `#FFFFFF` or `#F9F4EE` (warm cream)
+- Accent: `#CBA258` (gold, reward tier)
+- Text: `#1E3932` (deep green)
+
+**Family Toys (LEGO)**
+- Primary: `#F5CC0A` (LEGO yellow) + `#D91F26` (red) + `#006CB7` (blue)
+- Background: `#FFFFFF`
+- Text: `#1A1A1A`
+- Use multiple brand colors in theme/product routing — each theme has its own color.
+
+**Family Food Brands (Nestlé, Colgate)**
+- Background: `#FFFFFF`
+- Primary: brand blue or red
+- Surface: light pastel of primary color at 10-20% opacity
+- Text: `#1A1A1A`
+- Warm accent: yellow or green for health cues
+
+**Gaming / Family Entertainment (Nintendo)**
+- Primary: `#E4000F` (red)
+- Background: `#FFFFFF`
+- Game character/art provides additional color
+- Text: `#1A1A1A`
+
+### Rules
+- Colors must be high-energy and identifiable — the brand color is the experience.
+- CTA must use the brand's most energetic color.
+- White backgrounds prevent color fatigue when using multiple brand colors.
+- Never use muted, desaturated tones for primary elements — that signals premium, not playful.
+
+---
+
+## Typography
+
+### Scale
+| Role | Size | Weight | Notes |
+|---|---|---|---|
+| Hero headline | 32-56px | 700-900 | Friendly bold, may be condensed |
+| Section headline | 22-32px | 700 | |
+| Product name | 16-20px | 600-700 | |
+| Product description | 14-16px | 400 | Friendly tone, short |
+| Price | 18-24px | 700 | Tabular numerals, brand accent |
+| CTA | 15-18px | 700 | |
+| Navigation label | 13-14px | 500-600 | |
+| Promo badge | 11-13px | 700-800 | All-caps or bold |
+
+### Font Pairings
+| Brand type | Font |
+|---|---|
+| Fast food | Nunito Black / ExtraBold, Fredoka One, or brand custom |
+| Coffee / lifestyle | Lato Bold, Raleway, or circular |
+| Family toys | Nunito, Poppins, or Fredoka One |
+| Family food/health | Rounded Sans: Nunito, Quicksand, or Poppins |
+| Gaming consumer | Custom or Barlow, Exo 2, or Noto Sans Bold |
+
+### Rules
+- Use rounded fonts — sharp serifs and thin weights feel cold for playful brands.
+- Headlines must command attention immediately — heavy weight, high contrast.
+- Never use decorative fonts that sacrifice legibility.
+
+---
+
+## Spacing System
+
+| Token | Value | Use |
+|---|---|---|
+| `--space-xs` | 4px | Icon nudges |
+| `--space-sm` | 8px | Label margins |
+| `--space-md` | 16px | Card padding, button padding |
+| `--space-lg` | 24px | Between product cards |
+| `--space-xl` | 40-48px | Section separation |
+| `--space-2xl` | 64-80px | Hero padding |
+
+- Product grids: 16-20px gutters.
+- CTA buttons: generous padding (16px × 32px minimum) — must feel easy to tap.
+- Cards: 16px padding, 8-12px border-radius.
+
+---
+
+## Motion and Interaction
+
+### Principles
+- Microinteractions should delight — bouncy, friendly, never cold or mechanical.
+- Add-to-cart / Order: satisfying animation (checkmark pop, cart count bounce).
+- Promo banner: gentle left-right auto-scroll with pause on hover.
+- Product card: hop/lift on hover, 150ms.
+
+### Mascot / Character Animation
+- Character appears on key moments: empty cart ("Add your first item!"), order success, loyalty milestone.
+- Keep to a few frames — simple, not complex.
+- `prefers-reduced-motion`: replace all bounce/spring animations with instant transitions.
+
+### Loading
+- Skeleton: match card dimensions, shimmer animation.
+- Order confirmation: celebratory micro-animation (checkmark or confetti), then settled state.
+
+### Transitions
+- Button tap: scale `0.95` on press, bounce back, 150ms spring.
+- Card hover: `translateY(-4px)`, `box-shadow` lift, 150ms ease.
+
+---
+
+## Responsive Behavior
+
+| Breakpoint | Key changes |
+|---|---|
+| Mobile 375px | Hero: full-width, stacked CTA. Menu: single-column. Bottom nav bar. Large tap targets. Price prominent on card. |
+| Tablet 768px | 2-column menu grid. Nav visible. |
+| Desktop 1024px | 3-4 column product grid. Full nav visible. |
+| Wide 1440px+ | Max-width 1280px. Product grid up to 5 columns. |
+
+- Mobile is the primary experience for food ordering — optimize for thumb reach.
+- Bottom nav bar on mobile: 5 items max, icons + labels.
+- "Add to Order" button: sticky at bottom of product detail on mobile.
+
+---
+
+## Accessibility Requirements
+
+- Food photography alt text: describe the food item, not "image of food" — e.g., `alt="Big Mac burger with sesame bun, lettuce, cheese, and special sauce"`.
+- Menu customization: radio buttons or checkboxes with visible labels. `<fieldset>` + `<legend>` per option group.
+- Allergen info: must be a text element, visible by default, not only revealed on hover.
+- Bottom navigation: `role="navigation"`, `aria-label="Main navigation"`. Active item: `aria-current="page"`.
+- Promotions and badges: always include text content, not just color/icon.
+- Character/mascot images: `alt` describes the character's action, not just "mascot."
+- Order confirmation: `aria-live="polite"` for success message.
+- Touch targets: all buttons and links minimum 44×44px — critical for food ordering on mobile.
+- Promo banner: auto-scrolling must pause on focus and on `prefers-reduced-motion`.
+
+---
+
+## UX Principles for This Method
+
+1. **Make the primary task impossible to miss.** Ordering or finding a location is the job — never bury it.
+2. **Delight is earned through speed, not decoration.** A fast, frictionless order is more delightful than a bouncy animation on a slow page.
+3. **Familiarity is a feature.** Use recognizable patterns (bottom nav, large cards, price prominent) — users already know this language.
+4. **Food photography sells.** Invest in imagery. A great photo of food is worth 1000 feature descriptions.
+5. **Broad audience.** Someone's grandmother should be able to order without frustration. Do not assume tech literacy.
+6. **Loyalty creates habit.** Rewards and loyalty flows are high-value — design them to be simple and visible.
+
+---
+
+## Component Specs
+
+### Menu Product Card
+```
+Width: flexible
+Border-radius: 12px
+Background: white
+Border: 1px solid var(--border)
+Image: 16:9 or square, object-fit: cover, border-radius top
+Product name: 16-18px, weight 700, margin-top 12px
+Description: 13-14px, text-secondary, 2-line clamp
+Price: 16-20px, weight 700, brand accent color
+CTA: "Add" button, right-aligned or full-width, brand primary
+```
+
+### CTA Button (Playful)
+```
+Background: brand primary
+Text: white, 15-18px, weight 700
+Padding: 14-16px 28-36px
+Border-radius: 8-12px
+Hover: darken 8%, scale 1.02
+Active: scale 0.97, darken 12%
+Focus: 3px solid brand-darker, offset 2px
+Bounce animation on add-to-cart: scale 1.1 → 1.0, 200ms spring
+```
+
+### Loyalty Badge / Reward
+```
+Background: brand accent (gold or contrasting)
+Text: 12-13px, bold, white or dark
+Border-radius: 6-8px (pill: 20px)
+Icon: star or flame, 14px, inline
+Padding: 4px 10px
+Positioned: bottom-left of product card image (absolute)
+```
+
+### Promo Banner
+```
+Background: brand accent
+Text: 13-14px, bold, white or dark
+Height: 40-44px
+Auto-scroll interval: 4-5s
+Pause on hover + focus
+Indicator dots: below banner, small (6px), brand light color
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+- Do not hide the menu behind 3 clicks.
+- Do not use small, light, or thin typography — broad audiences include elderly users.
+- Do not use low-contrast food badges or promo text on colorful backgrounds.
+- Do not autoplay promotional audio.
+- Do not require account creation before viewing the menu.
+- Do not use dark patterns for upsells — every "add extra" must be a clear opt-in, not pre-checked.
+- Do not use countdown timers for items that are not actually time-limited.
+- Do not rely solely on color to convey allergen information.
+
+---
+
+## QA Checklist
+
+- [ ] Primary CTA ("Order Now", "Add to Cart") visible above fold on mobile.
+- [ ] Bottom nav (if used): all items labeled, accessible, active state clear.
+- [ ] Food photography loads with skeleton placeholder.
+- [ ] Menu customization uses `<fieldset>` + `<legend>` with keyboard-navigable options.
+- [ ] Allergen info visible as text, not hover-only.
+- [ ] All interactive elements ≥ 44×44px touch target.
+- [ ] "Add to Order" sticky button on mobile product detail.
+- [ ] Loyalty / rewards section reachable within 2 taps.
+- [ ] Order confirmation announces success to screen reader (`aria-live`).
+- [ ] `prefers-reduced-motion`: all bounce/spring animations replaced with instant transitions.
+- [ ] No pre-checked upsell options (dark pattern check).
+- [ ] Page loads in under 3s on 4G (food ordering is mobile-first, often on poor connections).

package/references/brand-method-premium-restraint.md

@@ -0,0 +1,270 @@
+# Brand Method: Premium Restraint
+
+Use this skill when building for ultra-luxury brands, high-end finance, premium professional services, or any context where the absence of clutter, the quality of typography, and the control of the visual field are the primary brand signal.
+
+Reference brands: Chanel, Hermès, Rolex, Cartier, Dior, Bottega Veneta, Goldman Sachs, Audi (editorial mode), Porsche (brand site), Nespresso.
+
+---
+
+## When to Apply This Method
+
+Apply Premium Restraint when:
+- The product commands a significant price premium based on heritage, craft, or exclusivity.
+- The brand identity is built on what is NOT shown, not what IS shown.
+- The primary emotional outcome is aspiration, desire, and trust in quality.
+- Excess, busyness, and bargain signals actively harm the brand.
+
+Do not apply when:
+- The product is mass-market or price-competitive.
+- The user needs to complete a task quickly (use Utility Command Center).
+- The brand uses energy, color, or playfulness as a differentiator.
+
+---
+
+## Layout Structure
+
+### Core Principle: Reduction
+- Every element on the page must pass the question: "Does this need to be here?"
+- Default answer is no. Add only when the answer is yes.
+
+### Hero
+- Full-viewport or near-full-viewport image or video.
+- Product or brand world imagery — no UI chrome, no overlays, no text unless absolutely necessary.
+- If text: one word or one short phrase, white or black, perfectly typeset, positioned with asymmetrical precision.
+- No CTA in the hero, or one ultra-minimal text link ("Discover →").
+
+### Navigation
+- Ultra-thin, horizontal: logo centered OR left. Navigation links right (max 4).
+- Text-only links, 11-13px, letter-spaced, no underlines.
+- No mega-nav. No dropdowns on the homepage hero.
+- Disappears on downward scroll, reappears on upward.
+
+### Content Sections
+- Each section occupies the full viewport width; most content is centered with massive side margins (24-30% each side on desktop).
+- Text-to-content ratio: more whitespace than content by area.
+- One idea per section — never combine two things in one section.
+- Images: full-bleed alternating left/right OR centered portrait. Never a grid of small images.
+- Captions: if used, ultra-small (10-11px), muted, right-aligned or centered.
+
+### Commerce / Product Pages
+- Product image: extremely large, centered, no background.
+- Price: small, not prominent — the brand is above price anxiety.
+- Add to bag: minimal text link or outlined button. Never a filled bright button.
+- Product description: sparse, poetic, not a spec sheet.
+- Material / craftsmanship section: single long-form paragraph or a few precise sentences.
+
+---
+
+## Color Scheme
+
+### Core Rule: Near-Monochrome
+
+**Luxury Fashion (Chanel, Bottega Veneta)**
+- Background: `#FFFFFF` or `#FAF8F5` (warm white)
+- Primary text: `#111111` or `#1A1A1A`
+- Secondary text: `#888888` (light gray — used with caution, must pass 4.5:1)
+- Divider / border: `#E5E5E5`
+- Accent: none, or a single heritage color (used once per page maximum)
+
+**Luxury Jewelry / Watches (Rolex, Cartier)**
+- Background: `#FAFAF8` (cream-white) or `#0A0A0A` (dark section)
+- Primary: cream `#F5F0E8` on dark, near-black `#1C1C1C` on light
+- Gold accent: `#C8A96E` or `#D4A017` (used only for jewelry imagery, dividers, or single accent element)
+- Deep red: `#8B0000` (Cartier) — for section backgrounds, used maximally once per page
+
+**Premium Beverage / Lifestyle (Nespresso, Moët)**
+- Background: `#1C1C1C` or `#FAF5EF`
+- Gold: `#C6A55C`
+- Cream: `#F5ECD7`
+- Text: inverse of background
+
+**Finance / Professional Services (Goldman Sachs)**
+- Background: `#FFFFFF`
+- Primary: Navy `#001533` or `#002547`
+- Text: `#1A1A1A`
+- Accent: gold `#C8A96E` only as a single decorative line or icon, never as CTA color
+
+### Color Rules
+- Maximum 2 hues active on a single page. Neutrals (black, white, gray, cream) do not count toward this limit.
+- Never use: bright primary colors (red/blue/green/yellow) as dominant colors.
+- Never use: gradients as backgrounds.
+- A single heritage accent color used once — a rule, not a palette.
+- Gold: decorative/divider use only, not CTA backgrounds.
+
+---
+
+## Typography
+
+### Core Rule: Typography IS the design.
+
+### Scale
+| Role | Size | Weight | Notes |
+|---|---|---|---|
+| Brand/house name | 11-13px | 400-500 | All-caps, tracked +0.15em, nav only |
+| Hero text | 20-48px | 300-400 | Light weight, generous tracking |
+| Section headline | 18-32px | 300-400 | |
+| Body / story copy | 16-18px | 300-400 | Line-height 1.8-2.0, generous |
+| Product name | 18-24px | 400-500 | |
+| Product description | 14-16px | 300 | Wide line-height |
+| Price | 14-16px | 400 | Small, not prominent |
+| Caption / credit | 10-11px | 300-400 | Tracked, muted |
+| CTA / text link | 11-13px | 400-500 | All-caps, tracked +0.12em |
+
+### Font Pairings
+| Brand type | Heading | Body |
+|---|---|---|
+| Classic French luxury | Didot, Bodoni, or custom | Garamond, Cormorant |
+| Contemporary luxury | Helvetica Neue Light, Futura Light | Helvetica Neue, Futura |
+| Heritage jewelry/watches | Optima, Trajan Pro | Palatino, Garamond |
+| Premium beverage/lifestyle | Libre Baskerville Light | Raleway, Lato Light |
+| High-end finance | Mercury Display (editorial) | Mercury Text, or Helvetica Neue |
+
+### Rules
+- Never use more than 2 typefaces.
+- Default to light weights (300-400) — luxury is effortless.
+- Letter-spacing on all-caps labels: `letter-spacing: 0.12em` minimum.
+- Line-height on body text: 1.8-2.0 — luxury copy breathes.
+- Never use system emoji or icon fonts — only SVG icons, and sparingly.
+
+---
+
+## Spacing System
+
+### Core Rule: Maximum whitespace.
+
+| Token | Value | Use |
+|---|---|---|
+| `--space-xs` | 6px | Text list gaps |
+| `--space-sm` | 16px | Caption to image |
+| `--space-md` | 32px | Text block padding |
+| `--space-lg` | 64px | Between text elements in a section |
+| `--space-xl` | 96-128px | Between sections |
+| `--space-2xl` | 160-200px | Hero breathing room, full-viewport spacing |
+| `--space-3xl` | 240-300px | Full-page section padding (luxury pages are not short) |
+
+- Page max content width: 800-1000px for text sections. Images: full-bleed or inset 10-15% each side.
+- Mobile: scale down 50%, but never sacrifice the sense of emptiness.
+
+---
+
+## Motion and Interaction
+
+### Principles
+- No motion unless it is slower and more intentional than you think is necessary.
+- Scroll transitions: long, slow fades. Duration 800-1200ms. Ease-in-out.
+- No pop, bounce, or scale animations.
+- Image load: fade in from white, 600ms.
+
+### Navigation hover
+- Underline slides in from left, 200ms. No background fill.
+
+### CTA
+- Hover: letter-spacing expands slightly (+0.02em), 200ms. No fill, no scale.
+
+### Product image
+- Hover (desktop): subtle secondary image crossfade, 400ms.
+- No parallax on text — only on background imagery, subtle (0.05-0.1× difference).
+
+### `prefers-reduced-motion`
+- Remove all fade-ins, parallax, and crossfades. All content appears immediately.
+
+---
+
+## Responsive Behavior
+
+| Breakpoint | Key changes |
+|---|---|
+| Mobile 375px | Full-bleed images. Side margins 16-24px (not the desktop 24-30%). Hero text: 18-28px. Single-column all. Nav: hamburger with full-screen overlay (imagery background). |
+| Tablet 768px | Side margins 8-12%. Side-by-side sections optional. |
+| Desktop 1024px | Side margins 16-24%. Full typographic luxury. |
+| Wide 1440px+ | Side margins 24-30%. Text column max 800px. Never let content stretch to edges. |
+
+- Never fill the screen edge-to-edge with text — the margins carry the luxury signal.
+
+---
+
+## Accessibility Requirements
+
+- Luxury gray text (`#888888` on `#FFFFFF`) = 3.5:1 — **fails WCAG AA** for body text. Use `#767676` minimum for secondary text (passes at 4.6:1), or use `#555555` for safety.
+- Image-only navigation: never acceptable. Every nav link must have text (even if visually hidden with `sr-only`).
+- Hero with text: text-to-background contrast must be checked including any scrim or overlay.
+- Hover-only product information: all info visible on hover must also be reachable via keyboard focus.
+- Slow animations: ensure they don't delay time-sensitive content. Content must be accessible before animation completes.
+- Custom cursor: if used, must not be the only hover indicator. Standard interactive affordances required.
+- SVG icons: `aria-hidden="true"` if decorative; `title` and `aria-labelledby` if informational.
+- Product page: price must be a text element, not an image.
+
+---
+
+## UX Principles for This Method
+
+1. **Absence is the message.** Luxury is what you don't include.
+2. **Trust through restraint.** The brand does not need to prove itself with noise.
+3. **Typography is the logo.** In the absence of color and decoration, letterforms carry the entire brand.
+4. **Speed is luxury too.** A slow page is a dissonant luxury experience. Optimize aggressively.
+5. **Commerce is not the point.** The user must desire before they buy. Commerce is the final, quiet step.
+6. **Consistency of quiet.** No element breaks the established calm — not a social share button, not a chat widget, not a newsletter popup.
+
+---
+
+## Component Specs
+
+### Navigation (Luxury)
+```
+Height: 40-48px (minimal)
+Logo: centered or left, 80-120px wide
+Links: 11-13px, all-caps, letter-spacing 0.12em, font-weight 400
+No underline default. Hover: thin underline, transition 200ms
+Background: transparent over hero, white/cream on scroll
+Transition: background 250ms ease
+```
+
+### Text-Link CTA (Not a button)
+```
+Display: inline
+Font: 11-13px, all-caps, letter-spacing 0.12em
+Text: "Discover" or "Explore [Collection]" or "Add to bag"
+Hover: letter-spacing +0.02em, 200ms
+No background, no border (minimal mode)
+Or: outlined button with 1px border, no fill, hover: fill with text color, invert text
+```
+
+### Image Section
+```
+Full-bleed: width 100vw, height auto or 80vh
+Inset: margin 0 auto, max-width 75-85vw
+Object-fit: cover
+No rounded corners (luxury is sharp or geometric)
+Caption: 10-11px, tracked, right or center aligned, margin-top 12px, color text-muted
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+- Do not use promotional badges, price slashes, or urgency labels.
+- Do not use rounded pill buttons — luxury uses sharp rectangles or text links.
+- Do not use drop shadows on UI elements — they imply web 2.0, not luxury.
+- Do not use emojis or informal copy.
+- Do not use chatbots with intrusive pop-ups — if chat is needed, make it quiet and opt-in.
+- Do not use stock photography — only art-directed or product photography.
+- Do not clutter the footer with social media icons, newsletter sign-up, and multiple widget links.
+- Do not use system fonts — typography is the primary brand expression tool.
+- Do not use gray text that fails WCAG contrast — luxury does not exempt brands from accessibility.
+
+---
+
+## QA Checklist
+
+- [ ] Secondary text color passes 4.5:1 contrast (check `#888888` — likely fails, use `#767676` min).
+- [ ] No element in the hero competes visually with the product/brand image.
+- [ ] Every navigation link has accessible text (not icon-only).
+- [ ] Hover-reveal product info also visible on keyboard focus.
+- [ ] Custom cursor (if used) does not break standard interactive affordances.
+- [ ] `prefers-reduced-motion`: all animations removed, content immediately visible.
+- [ ] No promotional, urgency, or discount UI patterns.
+- [ ] No popups, chat widgets, or newsletter banners interrupt the experience.
+- [ ] Mobile: nav accessible and functional without degrading luxury feel.
+- [ ] Page LCP ≤ 2.5s — luxury pages often have large images. Optimize all images.
+- [ ] Price is a text element, not an image.
+- [ ] Typography is consistent — no accidental system font fallback visible.