ui-ux-master 1.2.1 → 1.5.0

package/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: ui-ux-master
 description: "Use when an agent must design, audit, improve, prototype, specify, or hand off any UI/UX work end-to-end. Provides one-stop UX strategy, research, IA, flows, wireframes, visual design, design systems, accessibility, usability testing, conversion, and engineering handoff workflows."
-version: 1.2.1
+version: 1.5.0
 author: Rupak Biswas
 license: MIT
 platforms: [linux, macos, windows]
@@ -23,32 +23,38 @@ The job is not only to make screens look good. The job is to solve the user's go
 
 This skill is opt-in. In Codex, Claude, Windsurf, Antigravity, Gemini, Cursor, and other agents, activate it only when the user includes `/ui-ux-master` in the prompt or invokes the installed native slash command. If the user does not mention `/ui-ux-master`, do not apply this skill automatically.
 
-When activated, the user can write naturally, for example: `/ui-ux-master audit this checkout flow` or `/ui-ux-master design a premium SaaS landing page`. Treat the rest of the prompt as the task and follow this SKILL.md plus the referenced files.
-
-## AI Discovery and MCP
-
-This package exposes the workflow through human-readable instructions and machine-readable discovery assets:
-
-- `llms.txt` gives AI agents a short map of the package.
-- `ai-discovery/ui-ux-master.manifest.json` describes activation, entrypoints, tools, resources, prompts, and supported agents.
-- `system-prompts/` contains full, compact, and MCP-focused system prompt add-ons.
-- `bin/ui-ux-master-mcp.mjs` runs a local read-only MCP server that exposes UI/UX Master tools, resources, and prompts.
-
+When activated, the user can write naturally, for example: `/ui-ux-master audit this checkout flow` or `/ui-ux-master design a premium SaaS landing page`. Treat the rest of the prompt as the task and follow this SKILL.md plus the referenced files.
+
+## AI Discovery and MCP
+
+This package exposes the workflow through human-readable instructions and machine-readable discovery assets:
+
+- `llms.txt` gives AI agents a short map of the package.
+- `ai-discovery/ui-ux-master.manifest.json` describes activation, entrypoints, tools, resources, prompts, and supported agents.
+- `system-prompts/` contains full, compact, and MCP-focused system prompt add-ons.
+- `bin/ui-ux-master-mcp.mjs` runs a local read-only MCP server that exposes UI/UX Master tools, resources, and prompts.
+
 Use MCP and system prompt add-ons only as discovery/activation layers. The workflow remains opt-in and should still require `/ui-ux-master` unless the user explicitly asks to use UI/UX Master.
 
 ## Core Operating Rule
 
 Do not jump directly to visuals. Work in this order unless the user explicitly asks for a narrow task:
 
-1. Check for existing UI/UX memory and branding first: `.ui-ux-memory.md`, design tokens, CSS variables, theme files, existing components, fonts, color scheme, and representative screens.
-2. If memory exists, follow it as the design baseline. If no memory exists, create one for the application using `templates/ui-ux-memory.md` after inspecting existing branding or asking minimum high-value questions for a fresh project.
-3. Understand the product, users, goal, platform, constraints, evidence available, research confidence, and success metric.
-4. Define the UX model: audience, jobs-to-be-done, journeys, service touchpoints, information architecture, flows, states, and content.
-5. Select an appropriate top-brand design method when frontend polish is requested: Product Cinema, Utility Command Center, Editorial Brand World, Enterprise Trust Hub, Card-Based Discovery, Conversion Simplicity, Ecosystem Bundling, Premium Restraint, Playful Familiarity, or Technical Authority.
-6. Design the interface by extending the existing memory/brand baseline unless the user explicitly asks for a redesign or specific visual modification.
-7. Validate: consistency with memory, research evidence, heuristics, WCAG, platform conventions, usability risks, i18n, ethics/privacy, edge cases, technical feasibility, metrics, and brand-fit.
-8. Update the application UI/UX memory with durable design decisions before handoff.
-9. Hand off: exact specs, tokens, component behavior, copy, states, QA checklist, implementation notes.
+1. **Discovery first.** Load `references/design-discovery-protocol.md`. For any new design task, run the 6-question discovery form before producing any visual output. Lock down: surface, audience, tone, brand context, fidelity, and constraints.
+2. **Brand extraction or visual direction.** If the user provides brand assets (URL, screenshot, hex codes), run the 5-step brand extraction protocol from `references/design-discovery-protocol.md` and write a brand-spec summary. If there is no brand, load `references/visual-directions.md`, present the 5 directions, and bind the selected direction's token block as the baseline. Never invent or guess brand colors from a company name alone.
+3. **Check project memory.** Look for `.ui-ux-memory.md` at the project root. If it exists, read all 9 sections (schema defined in `references/design-system-schema.md`) before designing. If it does not exist, create it using the schema after discovery completes.
+4. Understand the product, users, goal, platform, constraints, evidence available, research confidence, and success metric.
+5. Define the UX model: audience, jobs-to-be-done, journeys, service touchpoints, information architecture, flows, states, and content.
+6. **Industry reasoning.** Load `references/industry-reasoning-rules.md`. Match the user's product to an industry category and output the full Design System Block (pattern + style + colors + typography + effects + anti-patterns) in one step before designing.
+6a. Select an appropriate top-brand design method when frontend polish is requested. Load the corresponding brand-method skill file from references/: `references/brand-method-product-cinema.md`, `references/brand-method-utility-command-center.md`, `references/brand-method-editorial-brand-world.md`, `references/brand-method-enterprise-trust-hub.md`, `references/brand-method-card-based-discovery.md`, `references/brand-method-conversion-simplicity.md`, `references/brand-method-ecosystem-bundling.md`, `references/brand-method-premium-restraint.md`, `references/brand-method-playful-familiarity.md`, or `references/brand-method-technical-authority.md`.
+6b. Apply color psychology: load `references/color-psychology-branding.md`, identify the industry and sentiment, prescribe a complete palette with contrast ratios and rationale before any visual design begins. Use `references/color-scale-system.md` to generate full 11-step (50–950) OKLch color scales for the brand primary, neutral, and all semantic colors.
+6c. Select a UI style from `references/ui-styles-catalog.md`. Apply the style's token overrides on top of the visual direction baseline.
+7. **Junior designer warm-up.** For high-fidelity requests, show a wireframe sketch (grey blocks, real layout) first. Confirm direction before applying brand and polish. Skip if the user explicitly requests final output or provides a detailed reference.
+8. Design the interface by extending the established brand/direction baseline. Apply only tokens from the schema — no ad-hoc magic values. Apply stack-specific rules from `references/tech-stack-guidelines.md` for the user's chosen framework. For landing pages and marketing pages, follow the appropriate conversion pattern from `references/landing-page-patterns.md`. For dashboards, use the chart type guide in that same file.
+9. **Quality gates before any emit.** Load `references/output-quality-gates.md`. Run the 5-dimensional self-critique (philosophy/hierarchy/execution/specificity/restraint), pass all P0 hard gates, and clear the anti-slop blacklist. Fix and rescore until all dimensions ≥ 3. Do not emit output until all gates pass.
+10. Validate: consistency with memory, research evidence, heuristics, WCAG, platform conventions, usability risks, i18n, ethics/privacy, edge cases, technical feasibility, metrics, and brand-fit.
+11. Update `.ui-ux-memory.md` with any new durable design decisions before handoff.
+12. Hand off: exact specs, tokens, component behavior, copy, states, QA checklist, implementation notes.
 
 ## When to Use
 
@@ -456,36 +462,52 @@ Must include:
 
 ### Top-Brand Frontend Method
 
-When the user asks for a frontend that looks polished, premium, world-class, or similar to top brands, use `references/top-100-brand-website-analysis.md` before designing.
+When the user asks for a frontend that looks polished, premium, world-class, or similar to top brands, use `references/top-100-brand-website-analysis.md` before designing. Then load the dedicated skill file for the selected method.
 
 Process:
 
 1. Identify the product category and user task.
-2. Pick one primary method and one or two supporting methods:
-   - Product Cinema for premium product reveals.
-   - Utility Command Center for task-heavy ecommerce, booking, logistics, dashboards.
-   - Editorial Brand World for fashion, sports, beverage, entertainment, luxury campaigns.
-   - Enterprise Trust Hub for B2B, finance, healthcare, infrastructure, industrial.
-   - Card-Based Discovery for marketplaces, media, travel, catalogs, content libraries.
-   - Conversion Simplicity for signup, trial, app download, subscription, fintech flows.
-   - Ecosystem Bundling for multi-product suites.
-   - Premium Restraint for luxury, high-end finance, premium services.
-   - Playful Familiarity for food, toys, family, consumer brands.
-   - Technical Authority for AI, developer tools, semiconductors, infrastructure.
-3. Translate the selected methods into original tokens, layout rules, components, states, and copy.
-4. Never copy a brand exactly unless the user owns that brand. Avoid logos, proprietary images, exact trademark color combinations, and pixel-for-pixel layouts.
-5. Preserve accessibility and usability even when using cinematic, luxury, or experimental layouts.
+2. Pick one primary method and one or two supporting methods. Load the corresponding brand-method skill file for full layout, color, typography, spacing, motion, accessibility, and component specs:
+   - **Product Cinema** → `references/brand-method-product-cinema.md` — premium products, hardware, automotive, luxury.
+   - **Utility Command Center** → `references/brand-method-utility-command-center.md` — ecommerce, logistics, booking, dashboards.
+   - **Editorial Brand World** → `references/brand-method-editorial-brand-world.md` — fashion, sports, beverage, entertainment.
+   - **Enterprise Trust Hub** → `references/brand-method-enterprise-trust-hub.md` — B2B SaaS, finance, healthcare, industrial.
+   - **Card-Based Discovery** → `references/brand-method-card-based-discovery.md` — marketplaces, media, travel, catalogs.
+   - **Conversion Simplicity** → `references/brand-method-conversion-simplicity.md` — signup, trial, subscription, fintech flows.
+   - **Ecosystem Bundling** → `references/brand-method-ecosystem-bundling.md` — multi-product suites, plan comparison.
+   - **Premium Restraint** → `references/brand-method-premium-restraint.md` — ultra-luxury, high-end finance, premium services.
+   - **Playful Familiarity** → `references/brand-method-playful-familiarity.md` — food, toys, family, consumer brands.
+   - **Technical Authority** → `references/brand-method-technical-authority.md` — AI, developer tools, semiconductors, infra.
+3. Apply color psychology: load `references/color-psychology-branding.md` to validate and prescribe the palette for the business type and emotional goal. Output the full palette before any visual design.
+4. Translate the selected methods into original tokens, layout rules, components, states, and copy.
+5. Never copy a brand exactly unless the user owns that brand. Avoid logos, proprietary images, exact trademark color combinations, and pixel-for-pixel layouts.
+6. Preserve accessibility and usability even when using cinematic, luxury, or experimental layouts.
 
 Deliverable additions:
 
+- Brand method selected (with rationale).
+- Color psychology palette (business type, emotional goal, full hex palette, contrast ratios).
 - Brand-inspiration blend.
-- Selected method rationale.
 - Layout archetype.
 - Token direction.
 - Component behavior.
 - Accessibility safeguards.
 - Anti-copy/IP safety note.
 
+### Color Psychology and Branding
+
+When a user describes a product, business type, UI feel, or audience, load `references/color-psychology-branding.md` before prescribing any colors.
+
+Process:
+
+1. Identify: business category, emotional goal (trust/energy/calm/luxury/health/play/authority/innovation), positioning (mass/premium/luxury).
+2. Look up the industry prescription and sentiment mapping in the reference file.
+3. Output the complete palette: primary, secondary, accent/CTA, background, surface, text primary, text secondary, border, semantic success/warning/error/info, and dark mode variant if needed.
+4. State the psychological rationale for each choice.
+5. Warn of anti-patterns for this category.
+6. Verify all text-on-background combinations against WCAG 2.2 AA (4.5:1 body, 3:1 large text/UI).
+7. Include this palette in the `.ui-ux-memory.md` and all handoff specs.
+
 ### Frontend Implementation UX
 
 When implementing UI, first load and follow `references/ui-ux-frontend-implementation-rules.md`. Treat it as the non-negotiable frontend implementation checklist.
@@ -704,7 +726,27 @@ Use the supporting files in this skill folder when useful:
 - `references/ui-ux-frontend-implementation-rules.md` — mandatory frontend implementation rules so agents do not miss stack inspection, states, accessibility, responsiveness, tokens, QA, or handoff.
 - `references/wcag-aa-quick-reference.md` — practical WCAG 2.2 AA reference for agents.
 - `references/design-system-playbook.md` — how to create or extend a design system.
+- `references/ui-styles-catalog.md` — 20+ named UI styles (Glassmorphism, Liquid Glass, Data Brutalism, Aurora Borealis, AI-Native UI, Spatial UI, Cyberpunk, Claymorphism, Bento Grid, Soft UI Evolution, and more) with token overrides, required effects, forbidden patterns, and a style selection decision tree.
+- `references/color-scale-system.md` — 11-step (50–950) OKLch architectural color scales for all brand hue families and semantic states. Semantic role-to-step mapping and dark mode overrides. Full px+rem typography scale.
+- `references/industry-reasoning-rules.md` — one-step reasoning engine: input a product description, output a complete Design System Block (pattern, style, colors, typography, effects, anti-patterns, pre-delivery checklist) for 15+ industry categories.
+- `references/tech-stack-guidelines.md` — stack-specific component patterns, rules, and common AI mistakes for 16 frameworks: React, Next.js, Vue, Nuxt, Angular, Svelte, Astro, Remix, SolidJS, React Native, Flutter, SwiftUI, shadcn/ui, Jetpack Compose, Laravel, HTML+Tailwind.
+- `references/landing-page-patterns.md` — 12 named conversion patterns (Hero-Centric, Problem-Solution, Product Demo First, Comparison, etc.) with section-by-section structure. Plus 25-type chart selection guide with dashboard layout rules and data visualization anti-patterns.
+- `references/design-discovery-protocol.md` — 6-question discovery form, brand extraction 5-step protocol, junior designer warm-up, and discovery checklist. Load at the start of every new design task.
+- `references/output-quality-gates.md` — 5-dimensional self-critique (philosophy/hierarchy/execution/specificity/restraint), P0/P1/P2 hard gates, anti-AI-slop blacklist, and honest placeholder protocol. Run before every design emit.
+- `references/visual-directions.md` — 5 fully-specified OKLch token directions (Neutral Modern, Dark Technical, Warm Editorial, Bold Energetic, Calm Trust) for projects with no brand. Each direction includes complete CSS token block ready to bind.
+- `references/design-system-schema.md` — portable 9-section design system schema (color, typography, spacing, layout, components, motion, voice, brand, anti-patterns). Use as the template for all `.ui-ux-memory.md` files.
 - `references/top-100-brand-website-analysis.md` — top global brand website patterns and reusable frontend methods.
+- `references/brand-method-product-cinema.md` — full layout, color, typography, spacing, motion, accessibility, and component spec for the Product Cinema design method.
+- `references/brand-method-utility-command-center.md` — full spec for the Utility Command Center design method.
+- `references/brand-method-editorial-brand-world.md` — full spec for the Editorial Brand World design method.
+- `references/brand-method-enterprise-trust-hub.md` — full spec for the Enterprise Trust Hub design method.
+- `references/brand-method-card-based-discovery.md` — full spec for the Card-Based Discovery design method.
+- `references/brand-method-conversion-simplicity.md` — full spec for the Conversion Simplicity design method.
+- `references/brand-method-ecosystem-bundling.md` — full spec for the Ecosystem Bundling design method.
+- `references/brand-method-premium-restraint.md` — full spec for the Premium Restraint design method.
+- `references/brand-method-playful-familiarity.md` — full spec for the Playful Familiarity design method.
+- `references/brand-method-technical-authority.md` — full spec for the Technical Authority design method.
+- `references/color-psychology-branding.md` — color psychology, industry palette prescriptions, sentiment-to-palette mapping, contrast verification, and dark mode adaptation rules.
 - `references/ux-research-methods.md` — research planning, method selection, evidence confidence, and ethical research rules.
 - `references/usability-heuristics.md` — heuristic review, cognitive rules, and severity scoring.
 - `references/platform-guidelines.md` — web, iOS, Android/Material, Windows, desktop, kiosk, email, TV, and cross-platform rules.
@@ -716,16 +758,16 @@ Use the supporting files in this skill folder when useful:
 - `references/accessibility-advanced-patterns.md` — complex widget accessibility and screen-reader test matrix.
 - `references/ui-ux-curriculum-and-standards.md` — basic-to-advanced UI/UX curriculum and standards map.
 - `references/competitive-landscape.md` — competitor gaps and strategy for staying ahead.
-- `docs/slash-command-compatibility.md` — cross-agent `/ui-ux-master` trigger compatibility.
-- `docs/mcp-server.md` — MCP tools, resources, prompts, client configs, and smoke testing.
-- `llms.txt` — AI-readable package map for discovery by agents and indexing tools.
-- `ai-discovery/ui-ux-master.manifest.json` — machine-readable manifest for activation, entrypoints, MCP, and capabilities.
-- `system-prompts/ui-ux-master-system-add-on.md` — full system prompt add-on.
-- `system-prompts/ui-ux-master-compact.md` — compact system prompt add-on.
-- `system-prompts/ui-ux-master-mcp-add-on.md` — MCP-focused system prompt add-on.
-- `agent-templates/` — Claude, Codex, Windsurf, Antigravity, Gemini, Cursor, and universal installer templates.
-- `bin/ui-ux-master.mjs` — npm CLI installer.
-- `bin/ui-ux-master-mcp.mjs` — local read-only MCP server.
+- `docs/slash-command-compatibility.md` — cross-agent `/ui-ux-master` trigger compatibility.
+- `docs/mcp-server.md` — MCP tools, resources, prompts, client configs, and smoke testing.
+- `llms.txt` — AI-readable package map for discovery by agents and indexing tools.
+- `ai-discovery/ui-ux-master.manifest.json` — machine-readable manifest for activation, entrypoints, MCP, and capabilities.
+- `system-prompts/ui-ux-master-system-add-on.md` — full system prompt add-on.
+- `system-prompts/ui-ux-master-compact.md` — compact system prompt add-on.
+- `system-prompts/ui-ux-master-mcp-add-on.md` — MCP-focused system prompt add-on.
+- `agent-templates/` — Claude, Codex, Windsurf, Antigravity, Gemini, Cursor, and universal installer templates.
+- `bin/ui-ux-master.mjs` — npm CLI installer.
+- `bin/ui-ux-master-mcp.mjs` — local read-only MCP server.
 - `templates/ui-ux-brief.md` — intake and requirements template.
 - `templates/ui-ux-memory.md` — project UI/UX memory file template to copy into an application root as `.ui-ux-memory.md`.
 - `templates/ui-ux-audit-report.md` — audit output template.

package/docs/package-publishing.md

@@ -21,9 +21,9 @@ The GitHub "No packages published" message does not mean the npmjs package is br
 
 ## GitHub Packages Setup
 
-Do not add a root `.npmrc` that changes the default registry, because that can accidentally route normal installs away from npmjs.
+The root `.npmrc` intentionally configures only the `@seance1723` scope. It does not change the default registry, so normal `npm install ui-ux-master` and `npm publish` for the unscoped npmjs package still use npmjs.
 
-Use this scoped configuration only when publishing or installing the GitHub Packages mirror:
+Scoped GitHub Packages configuration:
 
 ```ini
 @seance1723:registry=https://npm.pkg.github.com
@@ -36,13 +36,15 @@ Local install from GitHub Packages:
 npm install @seance1723/ui-ux-master --registry=https://npm.pkg.github.com
 ```
 
+Many GitHub Packages installs require authentication. Use a token with `read:packages` for installs and `write:packages` for publishing.
+
 ## Secrets
 
 Add these repository secrets:
 
 - `NPM_TOKEN` - npm automation token with publish access to `ui-ux-master`.
 
-GitHub Packages publishing uses the built-in `GITHUB_TOKEN` in Actions.
+GitHub Packages publishing uses the built-in `GITHUB_TOKEN` in Actions. The workflow temporarily changes the package name to `@seance1723/ui-ux-master` only for that publish job, then publishes to `https://npm.pkg.github.com/`. Do not permanently rename the root package unless you intentionally want to migrate away from the public unscoped npmjs package.
 
 ## Release Strategy
 

package/index.cjs

@@ -4,8 +4,10 @@ const path = require('node:path');
 
 const packageRoot = __dirname;
 
+const _pkg = require('./package.json');
+
 const name = 'ui-ux-master';
-const version = '1.2.1';
+const version = _pkg.version;
 const trigger = '/ui-ux-master';
 
 const bins = Object.freeze({

package/index.d.ts

@@ -1,5 +1,5 @@
 export declare const name = "ui-ux-master";
-export declare const version = "1.2.1";
+export declare const version: string;
 export declare const trigger = "/ui-ux-master";
 
 export declare const bins: Readonly<{

package/index.mjs

@@ -1,10 +1,13 @@
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
 
 const packageRoot = path.dirname(fileURLToPath(import.meta.url));
+const _require = createRequire(import.meta.url);
+const _pkg = _require('./package.json');
 
 export const name = 'ui-ux-master';
-export const version = '1.2.1';
+export const version = _pkg.version;
 export const trigger = '/ui-ux-master';
 
 export const bins = Object.freeze({

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "ui-ux-master",
-  "version": "1.2.1",
+  "version": "1.5.0",
   "description": "Opt-in UI/UX master skill, CLI, and MCP server for AI coding agents, with accessibility, design-system, UX research, and frontend handoff workflows.",
   "type": "module",
-  "packageManager": "npm@11.14.0",
+  "packageManager": "npm@10.9.2",
   "main": "./index.cjs",
   "module": "./index.mjs",
   "types": "./index.d.ts",
@@ -47,12 +47,13 @@
   "scripts": {
     "validate": "python scripts/validate_skill.py --release",
     "validate:release": "python scripts/validate_skill.py --release",
+    "build": "npm run check:syntax",
     "check:syntax": "node --check index.mjs && node --check index.cjs && node --check bin/ui-ux-master.mjs && node --check bin/ui-ux-master-mcp.mjs",
     "doctor": "node bin/ui-ux-master.mjs doctor --dry-run",
     "test": "npm run test:smoke",
     "test:smoke": "npm run check:syntax && npm run doctor",
     "test:node": "node --test tests/*.test.mjs",
-    "ci": "npm run validate && npm run test:smoke && npm run test:node",
+    "ci": "npm run validate && npm run build && npm run test:smoke && npm run test:node",
     "release:check": "npm run ci && npm run pack:dry-run",
     "pack:dry-run": "npm pack --dry-run",
     "prepack": "npm run validate && npm test",

package/references/brand-method-card-based-discovery.md

@@ -0,0 +1,285 @@
+# Brand Method: Card-Based Discovery
+
+Use this skill when building for marketplaces, media platforms, travel aggregators, content libraries, product catalogs, rental platforms, or any context where the user browses, saves, and discovers from a large collection.
+
+Reference brands: Airbnb, YouTube, Spotify, Netflix, Disney+, LEGO, Nintendo, Booking.com listings, Etsy, Pinterest.
+
+---
+
+## When to Apply This Method
+
+Apply Card-Based Discovery when:
+- The product is a catalog, marketplace, or content library.
+- Users browse, save, filter, and compare rather than searching for one specific item.
+- The value proposition is breadth: "there's always something for you."
+- Discovery and serendipity are core to the experience.
+
+Do not apply when:
+- Users arrive with a specific known item in mind (use Utility Command Center).
+- The brand has a single product hero (use Product Cinema).
+- The primary goal is subscription sign-up (use Conversion Simplicity).
+
+---
+
+## Layout Structure
+
+### Hero / Entry Point
+- Not a full-screen hero — the card grid IS the value proposition.
+- Compact hero: search bar, category tabs, or personalized greeting with immediate content below.
+- Alternative: carousel or featured editorial band (1-3 items), then immediate card grid.
+- Call to action: "Browse [Category]" or personalized "Continue Watching / Listening / Exploring."
+
+### Card Grid
+- Primary layout pattern.
+- Grid: responsive, 2-6 columns depending on card type and screen.
+- Card rows: grouped by category, mood, recommendation engine, or curator picks.
+- Section headings above each row with optional "See all →" link.
+- Horizontal scroll rows for mobile (swipe gesture expected).
+
+### Filter and Sort Controls
+- Persistent or collapsible filter panel.
+- Filter types: category, price/rating range, location, date, availability, mood/genre.
+- Active filter chips shown above results — easy to clear individually or all.
+- Sort: relevance, price, rating, newest, most popular.
+
+### Card Types
+Define at least one primary card type per context:
+- **Content card**: thumbnail (16:9 or 1:1), title, creator/source, metadata (duration, views, rating).
+- **Product card**: image, name, price, rating, badge (deal, new, bestseller).
+- **Place/listing card**: image (4:3), name, location, rating, price/night, favorite icon.
+- **Media card**: album art, title, artist/show, play button.
+
+### Detail Page
+- Hero: large image or media player.
+- Primary action: "Play", "Book", "Add to Cart", "Save."
+- Metadata: ratings, description, related tags.
+- Recommendation section: "More like this", "Because you watched/liked."
+- Reviews (if applicable): summary + individual reviews.
+
+---
+
+## Color Scheme
+
+### Palette by Sub-category
+
+**Travel Marketplace (Airbnb)**
+- Background: `#FFFFFF`
+- Primary: `#FF385C` (coral/brand)
+- Surface: `#F7F7F7`
+- Text: `#222222`
+- Secondary text: `#717171`
+- Border: `#DDDDDD`
+- Map accent: brand coral
+- Favorite icon: `#FF385C`
+
+**Streaming / Media (Netflix, Spotify)**
+- Background: `#141414` (Netflix) or `#121212` (Spotify)
+- Surface: `#1E1E1E` or `#282828`
+- Primary text: `#FFFFFF`
+- Secondary text: `#B3B3B3`
+- Accent: `#E50914` (Netflix red) or `#1DB954` (Spotify green)
+- Progress bar: accent color on dark track
+
+**Family / Toys (LEGO, Disney, Nintendo)**
+- Background: `#FFFFFF`
+- Primary: Brand color (LEGO yellow `#FFD700` / red, Nintendo red `#E4000F`)
+- Surface: `#F8F8F8`
+- Text: `#1A1A1A`
+- Secondary text: `#666666`
+- Card border: `#EEEEEE`
+- Accent / CTA: brand primary
+
+**General Marketplace (Etsy)**
+- Background: `#FFFFFF`
+- Primary: `#F1641E` (Etsy orange)
+- Surface: `#F4F4F4`
+- Text: `#222222`
+
+### Rules
+- Dark surfaces: Spotify and Netflix — vivid accent pops against dark. Use sparingly.
+- Light surfaces: marketplaces, travel — clean white lets imagery drive color.
+- Card backgrounds must be neutral — let card content (images) provide color energy.
+- Favorites / save icon: always high-contrast so users can find it.
+
+---
+
+## Typography
+
+### Scale
+| Role | Size | Weight | Notes |
+|---|---|---|---|
+| Section heading | 18-24px | 600-700 | |
+| Card title | 14-16px | 500-600 | 1-2 line clamp |
+| Card metadata | 12-14px | 400 | Duration, views, rating |
+| Price | 14-16px | 600 | Tabular numerals |
+| Badge | 10-12px | 600-700 | All-caps, high contrast on brand color |
+| Filter label | 13-14px | 500 | |
+| CTA | 14-16px | 600 | |
+| Hero headline (if any) | 28-40px | 700 | |
+
+### Font Pairings
+| Context | Font |
+|---|---|
+| Travel / marketplace | Cereal (Airbnb), Circular, or Inter |
+| Streaming dark | Netflix Sans, or Inter/Roboto |
+| Music | Circular, Montserrat, or Nunito |
+| Family/toys | Nunito, Poppins, or Fredoka One |
+
+### Rules
+- Card titles must be readable at small sizes — minimum 14px.
+- Use `line-clamp` to keep card grids uniform — never let one card blow the layout.
+- Price: bold, tabular numerals, never ambiguous position on card.
+
+---
+
+## Spacing System
+
+| Token | Value | Use |
+|---|---|---|
+| `--space-xs` | 4px | Icon nudges, badge padding |
+| `--space-sm` | 8px | Card inner gaps |
+| `--space-md` | 12-16px | Card padding |
+| `--space-lg` | 20-24px | Grid gutters |
+| `--space-xl` | 32-40px | Section separation (heading to grid) |
+| `--space-2xl` | 48-64px | Between major content sections |
+
+- Grid gutter: 16-24px between cards. Smaller for media, larger for travel listings.
+- Section separation: 32-48px between category rows.
+- Cards must have consistent height within a row (use fixed aspect ratio on images).
+
+---
+
+## Motion and Interaction
+
+### Card Interactions
+- Hover: subtle shadow lift `box-shadow: 0 4px 16px rgba(0,0,0,0.15)`, image zoom `scale(1.03)` transition 200ms.
+- Favorite/save button: heart icon fill animation on click (scale 1.2 → 1.0, 150ms).
+- Play button overlay: appears on card hover with opacity transition.
+- Carousel/row scroll: smooth scroll with momentum. Show scroll indicator or arrows at edges.
+
+### Loading
+- Always use skeleton screens for card grids — never blank areas.
+- Skeleton: match exact card dimensions. Animate shimmer gradient left to right.
+- Infinite scroll: load next batch 200px before viewport bottom. Show spinner at bottom.
+
+### Transitions
+- Page navigation: instant load with skeleton → content fade-in. No full-page loading spinners.
+- Filter apply: instant result update with skeleton transition, never full page reload.
+- Media player appear: slide-up from bottom (mobile) or smooth expand (desktop).
+
+---
+
+## Responsive Behavior
+
+| Breakpoint | Key changes |
+|---|---|
+| Mobile 375px | Single column (1-2 cards wide). Horizontal scroll rows. Filter: bottom sheet. Search: full width. |
+| Tablet 768px | 2-3 column grid. Horizontal scroll or pagination. Collapsible filter sidebar. |
+| Desktop 1024px | 3-5 column grid. Persistent or toggle filter panel. |
+| Wide 1440px+ | 4-6 columns for media/product cards. Max-width content container. |
+
+- Mobile: horizontal scroll card rows (Netflix-style) are expected and usable.
+- Mobile: filter is a full-screen bottom sheet with apply/clear buttons.
+- Mobile: card images must be large enough to see detail (min 140px width).
+
+---
+
+## Accessibility Requirements
+
+- Card: each card is a single interactive unit. Use `<article>` or `<li>`. Primary action (title link) is the main focus target.
+- Favorite button: `aria-label="Save [Item Name]"` or `aria-pressed="true/false"`.
+- Play button: `aria-label="Play [Title]"`.
+- Rating stars: `aria-label="4.2 out of 5 stars"`.
+- Carousel/row: `role="region"` with `aria-label="[Category Name]"`. Left/right scroll buttons keyboard accessible.
+- Infinite scroll: announce new results with `aria-live="polite"` — "12 more results loaded."
+- Filter: `<fieldset>` + `<legend>` per group. Active filters: each chip has a remove button with `aria-label="Remove [filter name] filter"`.
+- Image thumbnails: `alt` describes the content (movie title, product name, property name).
+- Dark streaming UI: ensure text-on-image thumbnails meet contrast. Provide text overlays only with scrim.
+- Touch targets: card images, titles, and favorite buttons all ≥ 44×44px on mobile.
+
+---
+
+## UX Principles for This Method
+
+1. **Discovery over search.** Browsing should feel rewarding — "I didn't know I wanted that."
+2. **Cards are atoms.** Every card must be independently scannable: image, title, key metadata in one glance.
+3. **Personalization is the feature.** Surface what the user is likely to want next — recommendation rows are high-value real estate.
+4. **Save and resume.** Favorites, watch later, saved searches — users leave and return. Meet them where they left off.
+5. **Never lose the user in the grid.** Section headings, pagination, and "see all" links provide orientation.
+6. **Fast first render.** Skeletons, lazy images, and fast first card row matter — the grid must feel instant.
+
+---
+
+## Component Specs
+
+### Standard Card
+```
+Width: flexible (grid cell) — typically 200-320px
+Image: aspect-ratio 16:9 (video/media), 1:1 (music/product), 4:3 (travel/place)
+Image object-fit: cover
+Title: 14-16px, font-weight 500-600, 2-line clamp
+Metadata row: 12-13px, text-secondary
+Price (if applicable): 14-16px, bold
+Favorite button: absolute top-right, 36×36px, heart icon, background: white circle with shadow
+Border-radius: 8-12px (travel/marketplace) | 4px (media) | 0 (ultra editorial)
+Shadow: default none, hover: 0 4px 16px rgba(0,0,0,0.1)
+```
+
+### Category Section Row
+```
+Heading: 18-22px, font-weight 600, margin-bottom 12px
+"See all" link: right-aligned, 14px, brand color
+Horizontal scroll: overflow-x: scroll, scroll-snap-type: x mandatory
+Scroll snapping: scroll-snap-align: start per card
+Scrollbar: hidden (visually), accessible via keyboard
+```
+
+### Filter Bottom Sheet (Mobile)
+```
+Position: fixed bottom 0, full width
+Height: auto, max-height 85vh, overflow-y: scroll
+Background: white
+Border-radius: 16px 16px 0 0
+Handle bar: 4px × 32px, centered top, gray
+Animation: slide up 250ms ease
+Footer: "Apply Filters" (primary) + "Clear All" (ghost), sticky
+```
+
+### Skeleton Card
+```
+Background: var(--surface)
+Image area: same aspect ratio as real card, background: linear-gradient shimmer
+Title lines: 2 lines, height 14px, border-radius 4px, same shimmer
+Animation: @keyframes shimmer, background-position shift 1.5s linear infinite
+```
+
+---
+
+## Anti-Patterns to Avoid
+
+- Do not show more than 6 items per horizontal scroll row before a "See all" link.
+- Do not hide card metadata (price, rating, duration) until hover — mobile users cannot hover.
+- Do not use infinite scroll without an easy way to get back to a specific position.
+- Do not auto-play media in card hover on mobile.
+- Do not use pagination alone without telling users how many total results exist.
+- Do not load the full product catalog without filtering options.
+- Do not use pop-up interstitials over the card grid.
+- Do not make the save/favorite button so small it's untappable on mobile.
+
+---
+
+## QA Checklist
+
+- [ ] Card grid renders correctly at 375px, 768px, 1024px, 1440px.
+- [ ] Skeleton cards shown while data loads.
+- [ ] Infinite scroll loads next batch before hitting bottom.
+- [ ] Filter updates results without full page reload.
+- [ ] Active filter chips visible above results with individual remove buttons.
+- [ ] Favorite button has `aria-label` with item name.
+- [ ] Rating stars have accessible text alternative.
+- [ ] Horizontal scroll rows keyboard navigable (arrow keys or tab).
+- [ ] `aria-live` announces new results loaded.
+- [ ] Mobile filter bottom sheet accessible and closeable via swipe or close button.
+- [ ] All card images have meaningful `alt` text.
+- [ ] Dark streaming UI: text-on-image contrast passes 4.5:1.
+- [ ] No media autoplays on mobile.