ui-ux-master 1.2.0 → 1.5.0

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.

package/references/brand-method-product-cinema.md

@@ -0,0 +1,258 @@
+# Brand Method: Product Cinema
+
+Use this skill when building for premium products, hardware, AI products, automotive, luxury goods, creator tools, or any brand where the product itself is the hero.
+
+Reference brands: Apple, Tesla, Mercedes-Benz, Porsche, Rolex, Audi, Sony PlayStation, Samsung, BMW.
+
+---
+
+## When to Apply This Method
+
+Apply Product Cinema when:
+- The product has strong visual appeal or engineering craft.
+- The brand commands premium pricing and aspiration.
+- The primary goal is desire, trust, and direct purchase or configuration.
+- The user journey is: discover → desire → configure/buy.
+
+Do not apply when:
+- The product is commodity, utility-first, or price-sensitive.
+- The primary task is search, compare, or track.
+- The brand is playful, enterprise-B2B, or social.
+
+---
+
+## Layout Structure
+
+### Hero Section
+- Full-viewport (100vw × 100vh) product image or video.
+- Product centered or offset-right with breathing room.
+- Minimal overlay: one eyebrow label (optional), one H1 (product name or single claim), one 14-18px supporting sentence, 1-2 CTAs.
+- CTA placement: bottom-center or bottom-left, never covering the product.
+- No decorative gradients over the product. Let the product speak.
+
+### Scroll Reveal Sections (in order)
+1. **Product story / film** — motion reveals or cinematic zoom showing key features.
+2. **Key benefit blocks** — 3-4 full-width sections, one benefit each, alternating image/text.
+3. **Specifications** — clean table or card grid, minimal chrome.
+4. **Ecosystem / accessories** — horizontal scroll or grid of related products.
+5. **Social proof** — awards, press quotes, review aggregate. Never more than 3 sources.
+6. **Final CTA** — sticky or section-level, repeated from hero.
+
+### Navigation
+- Minimal sticky nav: logo left, 3-5 links max, one CTA right.
+- On scroll: nav becomes translucent or colored, never opaque-white over hero.
+- Mobile: hamburger with full-screen overlay, not a drawer.
+
+### Footer
+- Minimal. Legal, links, social icons. Never crowded.
+
+---
+
+## Color Scheme
+
+### Primary Palette (choose one direction)
+
+**Light / Clean Premium**
+- Background: `#FFFFFF` or `#F5F5F7`
+- Surface: `#FAFAFA`
+- Primary text: `#1D1D1F`
+- Secondary text: `#6E6E73`
+- CTA: Brand accent (e.g., `#0071E3` for tech, `#BB0000` for automotive)
+- Border/divider: `#D2D2D7`
+
+**Dark / Cinematic**
+- Background: `#000000` or `#0A0A0A`
+- Surface: `#161617`
+- Primary text: `#F5F5F7`
+- Secondary text: `#A1A1A6`
+- CTA: High-contrast accent (`#FFFFFF` text on dark, or vivid color button)
+- Border/divider: `#2C2C2E`
+
+### Accent Colors by Sub-Category
+| Sub-category | Accent examples |
+|---|---|
+| Consumer tech | Blue `#0071E3`, silver `#8E8E93` |
+| Luxury automotive | Red `#CC0000`, gold `#B8860B`, silver |
+| Premium watches / jewelry | Gold `#D4A017`, deep green `#1B4332`, heritage red |
+| Creator tools | Vivid gradient accent on dark surface |
+| Luxury fashion | Cream `#F5F0E8`, gold, black |
+
+### Rules
+- Maximum 3 colors in active use at any time (background, text, accent).
+- Never use more than one accent color per viewport.
+- Gradient: allowed only on the accent CTA button or as a product surface glow, never as a background.
+
+---
+
+## Typography
+
+### Scale
+| Role | Size | Weight | Style |
+|---|---|---|---|
+| Eyebrow | 11-12px | 500-600 | All-caps, tracked +0.08em |
+| H1 / Product name | 48-80px | 600-700 | Tight tracking −0.01em to −0.03em |
+| H2 / Section headline | 28-40px | 600 | Tight |
+| Body / benefit copy | 17-21px | 400 | Normal tracking, 1.6 line-height |
+| Spec label | 11-13px | 500 | All-caps, tracked |
+| Spec value | 14-17px | 400-500 | Tabular numerals |
+| CTA | 14-17px | 500-600 | Normal tracking |
+
+### Font Pairings
+| Brand type | Heading | Body |
+|---|---|---|
+| Consumer tech | SF Pro Display (system), or Inter | SF Pro Text, Inter |
+| Luxury automotive | Gill Sans, Optima, or custom serif | Helvetica Neue, Inter |
+| Luxury watches/jewelry | Didot, Cormorant Garamond | Futura, Montserrat |
+| Premium lifestyle | Playfair Display | Lato, Source Sans |
+
+### Rules
+- Never use more than 2 font families.
+- Headlines must be large enough to command attention before any image does.
+- Avoid system emoji or decorative fonts.
+
+---
+
+## Spacing System
+
+| Token | Value | Use |
+|---|---|---|
+| `--space-xs` | 4px | Icon gaps, inline nudges |
+| `--space-sm` | 8px | Label spacing, tight stacks |
+| `--space-md` | 16px | Component padding |
+| `--space-lg` | 32px | Section inner padding |
+| `--space-xl` | 64px | Between content blocks |
+| `--space-2xl` | 96-128px | Hero breathing room, section separators |
+| `--space-3xl` | 160-200px | Full-screen section padding top/bottom |
+
+- Sections must breathe. Minimum 96px padding between major content blocks on desktop.
+- On mobile: scale down by ~40%, but never below 24px section separation.
+
+---
+
+## Motion and Interaction
+
+### Scroll-Driven Animation
+- Parallax: product image moves at 0.8× scroll speed relative to background.
+- Fade-in on scroll: `opacity 0→1`, `translateY 20px→0`, duration 400-600ms, ease-out.
+- Never animate text before the user has had 300ms to read it.
+
+### CTA States
+| State | Effect |
+|---|---|
+| Default | Brand accent background, white text |
+| Hover | Darken 8-12% or subtle scale `1.02` |
+| Active | Scale `0.98`, darken further |
+| Focus | 2-3px offset focus ring, brand color or `#0071E3` |
+| Loading | Spinner inside button, text hidden or replaced |
+| Disabled | 40% opacity, no pointer events |
+
+### Video / Motion Rules
+- Autoplay: allowed for hero video if: muted, no audio track, `prefers-reduced-motion` respected.
+- Provide poster image fallback.
+- Never autoplay audio.
+- Reduced motion: replace parallax and scroll animation with instant transitions.
+
+---
+
+## Responsive Behavior
+
+| Breakpoint | Key changes |
+|---|---|
+| Mobile 375px | Full-bleed hero image, product fills screen, CTA stacks vertically, type H1 scales to 32-40px |
+| Tablet 768px | Two-column benefit layout, nav collapses to hamburger |
+| Desktop 1024px | Full layout, scroll animations active |
+| Wide 1440px+ | Max content width `1280px` centered, hero fills viewport edge-to-edge |
+
+- On mobile: remove parallax, replace with static scroll.
+- On mobile: sticky CTA bar at bottom for primary action.
+- Images: use `srcset` or responsive image format (WebP/AVIF). Never serve desktop hero at mobile.
+
+---
+
+## Accessibility Requirements
+
+- Color contrast: minimum 4.5:1 for body text, 3:1 for large text/UI components.
+- On dark cinematic surfaces: white text `#F5F5F7` on `#000000` = 21:1 — always passes.
+- On hero image overlays: always add a semi-transparent scrim (`rgba(0,0,0,0.4)` minimum) before placing text.
+- `prefers-reduced-motion`: wrap all scroll animations in `@media (prefers-reduced-motion: no-preference)`.
+- Video: must have `aria-label`, pause control, and `prefers-reduced-motion` stops autoplay.
+- CTA buttons: always have visible text label, never icon-only.
+- Focus indicators: `outline: 2px solid <accent>; outline-offset: 3px` — never `outline: none` without custom focus style.
+- Keyboard: all interactive elements reachable, logical tab order follows visual order.
+- Screen reader: hero heading must be an `<h1>`, not a `<div>`. Product name = page title.
+- Images: `alt` text describes the product and context, not just "product image".
+
+---
+
+## UX Principles for This Method
+
+1. **Confidence over explanation.** Premium brands do not over-explain. One claim. One proof. Move on.
+2. **Product is the hero.** Every layout decision protects the product's visual dominance.
+3. **Reduce friction to desire.** The user should feel the product is within reach before they see a price.
+4. **CTA placement follows desire.** Place CTA after the moment of maximum desire, not immediately at load.
+5. **Consistency of restraint.** Every added element costs attention. Default to removing, not adding.
+6. **Configurator UX.** If the product is configurable: show the default beautifully, let the user modify progressively, never show all options at once.
+
+---
+
+## Component Specs
+
+### Hero CTA Button
+```
+Background: brand accent
+Text: contrasting (white on dark, near-black on light)
+Padding: 14px 28px
+Border-radius: 6-8px (tech) | 0-2px (ultra luxury) | 20px (lifestyle)
+Font: 15-17px, weight 500-600
+Transition: background 180ms ease, transform 120ms ease
+Min-width: 140px
+```
+
+### Spec Table
+```
+Cell padding: 12px 16px
+Border: 1px solid var(--border)
+Header row: background var(--surface), font-weight 600, font-size 11px all-caps
+Value rows: alternating subtle background on hover
+Numbers: tabular-nums
+```
+
+### Sticky Nav
+```
+Position: fixed top 0
+Height: 44-52px
+Backdrop: blur(20px) saturate(180%) with semi-transparent background
+Transition: background 200ms ease on scroll
+Z-index: 1000
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+- Do not clutter the hero with more than 2 CTAs.
+- Do not use stock photography — use real product photography or none.
+- Do not use discount badges, countdown timers, or urgency copy.
+- Do not use carousels in hero — they reduce impact and have poor accessibility.
+- Do not use full-width decorative gradients as backgrounds — they cheapen premium perception.
+- Do not mix dark and light sections without deliberate contrast logic.
+- Do not use multiple accent colors on the same page — pick one.
+- Do not put the specification table above the benefit/story section.
+- Do not use hover-only navigation — touch users cannot hover.
+
+---
+
+## QA Checklist
+
+- [ ] Hero image/video loads with correct poster/fallback.
+- [ ] `prefers-reduced-motion` stops or reduces animation.
+- [ ] All text passes 4.5:1 contrast (use browser accessibility audit).
+- [ ] Sticky nav visible and usable at all scroll positions.
+- [ ] CTA button has visible focus ring.
+- [ ] All images have meaningful `alt` text.
+- [ ] H1 exists and is the product/brand name.
+- [ ] Mobile 375px: hero fills screen, CTA accessible without scroll.
+- [ ] Keyboard: tab through all interactive elements without mouse.
+- [ ] Screen reader: hero heading, CTA label, product description all announced correctly.
+- [ ] No autoplay audio.
+- [ ] Page loads in under 3s on 4G (Core Web Vitals: LCP ≤ 2.5s).