@thorprovider/create-storefront 0.1.1

package/skills/storefront-best-practices/reference/design.md

@@ -0,0 +1,388 @@
+# Design Guidelines
+
+## Contents
+
+- [Overview](#overview)
+- [Discovering Existing Brand Identity](#discovering-existing-brand-identity)
+- [Critical Consistency Rules](#critical-consistency-rules)
+- [When to Ask User Approval](#when-to-ask-user-approval)
+- [New Project Setup](#new-project-setup)
+- [Decision Tree](#decision-tree)
+- [Common Mistakes](#common-mistakes)
+
+## Overview
+
+**Purpose:** Provide guardrails to maintain brand consistency when building UI components. This prevents agents from accidentally introducing inconsistent colors, fonts, or design patterns.
+
+**Critical principle:** ALWAYS discover and use existing design tokens before creating new components. NEVER introduce new colors or fonts without user approval.
+
+**When to apply:** Before creating any UI component or design-related change.
+
+## Discovering Existing Brand Identity
+
+Before implementing any component, identify existing brand colors, typography, and design patterns. AI agents can do this - focus on WHAT to look for, not detailed HOW.
+
+### What to Look For
+
+**Colors:**
+1. **Tailwind config** (`tailwind.config.ts/js`) - Check `theme.extend.colors` or `theme.colors`
+2. **CSS variables** (globals.css, app.css) - Look for `:root { --color-primary: ... }`
+3. **Existing components** - Scan 2-3 components for color usage patterns
+
+**Typography:**
+1. **Tailwind config** - Check `theme.extend.fontFamily`
+2. **Font imports** - Look in layout files or CSS (Next.js `next/font`, Google Fonts, local fonts)
+3. **CSS variables** - Check for `--font-sans`, `--font-heading`
+4. **Existing components** - Identify font usage patterns
+
+**Other patterns:**
+- Spacing scale (p-4, mb-6, etc.)
+- Border radius (rounded-lg, rounded-xl)
+- Shadows (shadow-md, shadow-lg)
+- Interactive states (hover, focus colors)
+
+### Detecting Tailwind Version (CRITICAL)
+
+**ALWAYS check the Tailwind CSS version before writing utility classes.**
+
+Tailwind v3 and v4 have different syntax, and mixing them causes errors.
+
+**How to detect version:**
+1. **Check `package.json`**: Look for `"tailwindcss": "^3.x.x"` or `"tailwindcss": "^4.x.x"`
+2. **Check config file**:
+   - v3: Uses `tailwind.config.js/ts` with `module.exports` or `export default`
+   - v4: May use CSS-based config with `@import "tailwindcss"`
+3. **Check existing components**: Look at class usage patterns
+
+**Key differences:**
+
+**Tailwind v3:**
+```tsx
+// v3 syntax
+<div className="bg-primary text-white">Content</div>
+```
+
+**Tailwind v4:**
+```tsx
+// v4 may use CSS variables differently
+// Check the project's existing patterns
+<div className="bg-primary text-white">Content</div>
+```
+
+**Common mistake:** Using v3 syntax in v4 projects or vice versa. Always verify the version first.
+
+### Document Discovery
+
+Create mental inventory of:
+- **Primary color(s)** and their usage
+- **Font families** (sans, serif, heading, mono)
+- **Common patterns** (button styles, card designs, spacing)
+- **Semantic names** (primary, secondary, accent vs blue-500, red-600)
+
+## Critical Consistency Rules
+
+### ALWAYS Follow These Rules
+
+✅ **NEVER use emojis in storefront UI** - Always use icons or images instead
+
+```tsx
+// ✅ CORRECT - Using icon component or image
+<button className="flex items-center gap-2">
+  <ShoppingCartIcon className="w-5 h-5" />
+  Add to Cart
+</button>
+
+// ❌ WRONG - Using emoji
+<button>
+  🛒 Add to Cart
+</button>
+```
+
+**Why:** Emojis appear differently across platforms, lack professional appearance, and can cause accessibility issues. Use icon libraries (Heroicons, Lucide, Font Awesome) or SVG images instead.
+
+✅ **USE existing design tokens** (colors, fonts, spacing from theme)
+
+```tsx
+// ✅ CORRECT - Using theme colors
+<button className="bg-primary text-white hover:bg-primary-dark">
+  Click Me
+</button>
+
+// ❌ WRONG - Arbitrary colors when theme exists
+<button className="bg-[#3B82F6] text-white hover:bg-[#2563EB]">
+  Click Me
+</button>
+```
+
+✅ **USE existing font definitions**, not new font families
+
+```tsx
+// ✅ CORRECT - Using theme font
+<h1 className="font-heading text-4xl font-bold">
+  Welcome
+</h1>
+
+// ❌ WRONG - Introducing new font
+<h1 className="font-['Montserrat'] text-4xl font-bold">
+  Welcome
+</h1>
+```
+
+✅ **MATCH patterns from existing components**
+
+```tsx
+// If existing buttons use: bg-primary px-6 py-3 rounded-lg
+// New buttons should use the same pattern
+<button className="bg-primary px-6 py-3 rounded-lg">
+  New Button
+</button>
+```
+
+### NEVER Do These Things
+
+❌ **DON'T introduce new colors without user approval**
+- If you need a color not in the theme, ASK first
+- Don't use arbitrary values like `bg-[#FF6B6B]` when theme has colors
+
+❌ **DON'T add new fonts without user approval**
+- If current design uses Inter, don't add Montserrat without asking
+- Don't use `font-['NewFont']` syntax when theme fonts exist
+
+❌ **DON'T use hard-coded values when theme tokens exist**
+- Use `bg-primary` not `bg-[#3B82F6]`
+- Use `p-6` not `p-[24px]`
+- Use `font-heading` not `font-['Poppins']`
+
+❌ **DON'T create inconsistent patterns**
+- If buttons use `rounded-lg`, all buttons should
+- If cards use `shadow-md`, all cards should
+- If hover effects use `hover:bg-primary-dark`, be consistent
+
+## When to Ask User Approval
+
+**ALWAYS ask before:**
+
+### 1. Adding New Color
+
+```
+"I notice the current palette doesn't include an orange accent color.
+Should I add one, or would you prefer to use the existing accent color?"
+```
+
+**Scenario:** You're building a promotional banner that needs an orange color, but theme only has blue/purple.
+
+### 2. Adding New Font
+
+```
+"The current design uses Inter for all text. Do you want me to add
+a different font for headings, or keep using Inter throughout?"
+```
+
+**Scenario:** Building a hero section and wondering if headings should use a different font.
+
+### 3. Changing Existing Definitions
+
+```
+"Should I update the primary color to #3B82F6, or create a
+new color variant?"
+```
+
+**Scenario:** Current primary is #2563EB but new design mockup shows #3B82F6.
+
+### 4. Creating New Pattern
+
+```
+"The current components don't have a ghost button style (transparent with border).
+Should I create one, or use an existing button variant?"
+```
+
+**Scenario:** Need a subtle button style that doesn't exist yet.
+
+### DON'T Ask About
+
+❌ Standard web dev decisions (responsive breakpoints, hover effects)
+❌ Component structure or layout choices
+❌ Accessibility patterns (AI agents know WCAG)
+❌ Using existing theme colors/fonts in new ways
+
+## New Project Setup
+
+When starting a new project WITHOUT existing theme:
+
+### Ask User These Questions
+
+**1. Brand Colors:**
+```
+"What are your brand colors? Please provide:
+- Primary color (main brand color)
+- Secondary color (optional)
+- Any specific hex codes or color preferences?"
+```
+
+**2. Font Preferences:**
+```
+"Do you have font preferences?
+- Modern and clean (Inter, Poppins)
+- Classic and professional (Merriweather, Lora)
+- Specific fonts?
+- Or should I choose appropriate fonts?"
+```
+
+**3. Design Style:**
+```
+"What design style do you prefer?
+- Minimal (lots of whitespace, clean lines)
+- Bold (vibrant colors, large typography)
+- Professional (conservative, trust-focused)
+- Modern (rounded corners, gradients, shadows)"
+```
+
+**4. Reference Sites (Optional):**
+```
+"Do you have 2-3 example websites you like the look of?
+This helps me understand your aesthetic preferences."
+```
+
+### Setup Theme Configuration
+
+After gathering preferences, configure Tailwind theme:
+
+```typescript
+// tailwind.config.ts
+export default {
+  theme: {
+    extend: {
+      colors: {
+        primary: '#3B82F6',     // User's primary color
+        secondary: '#8B5CF6',    // User's secondary
+        accent: '#F59E0B',       // Accent if needed
+        // Full scales if sophisticated design
+        brand: {
+          50: '#eff6ff',
+          500: '#3b82f6',
+          900: '#1e3a8a',
+        }
+      },
+      fontFamily: {
+        sans: ['Inter', 'system-ui', 'sans-serif'],
+        heading: ['Poppins', 'sans-serif'],
+      },
+    },
+  },
+}
+```
+
+**Use Tailwind CSS for all new projects** - industry standard for ecommerce, highly customizable, excellent DX.
+
+## Decision Tree
+
+**When creating any component:**
+
+```
+1. Does a theme configuration exist?
+   ├─ Yes → Extract colors/fonts from theme
+   │         Use existing tokens for new component
+   └─ No → Ask user for brand preferences
+           Create theme configuration
+
+2. Are there similar existing components?
+   ├─ Yes → Follow their patterns exactly
+   │         (spacing, colors, hover states)
+   └─ No → Check ANY existing components
+           Extract general patterns (spacing scale, hover effects)
+
+3. Do you need a color/font not in theme?
+   ├─ Yes → ASK user for approval before adding
+   │         Explain why you need it
+   └─ No → Proceed with existing tokens
+
+4. Are you unsure about a design pattern?
+   ├─ Yes → Check 2-3 existing components for guidance
+   │         Follow majority pattern
+   └─ No → Implement using theme tokens
+           Maintain consistency with existing components
+```
+
+## Common Mistakes
+
+### ❌ Using Arbitrary Values When Theme Exists
+
+**Problem:** Using `bg-[#3B82F6]` when `bg-primary` exists.
+
+**Why it's wrong:** Bypasses theme, creates inconsistency, harder to maintain.
+
+**Fix:** Always use semantic names from theme.
+
+### ❌ Introducing New Colors Without Permission
+
+**Problem:** Adding `text-orange-500` when theme doesn't have orange.
+
+**Why it's wrong:** User may not want orange in their brand, creates color chaos.
+
+**Fix:** Ask user first: "Should I add an orange color, or use existing accent?"
+
+### ❌ Not Checking Existing Patterns
+
+**Problem:** Creating buttons with `rounded-full` when all other buttons use `rounded-lg`.
+
+**Why it's wrong:** Visual inconsistency confuses users.
+
+**Fix:** Check 2-3 existing buttons, use same rounding.
+
+### ❌ Adding Fonts Without Permission
+
+**Problem:** Using `font-['Montserrat']` when theme uses Inter everywhere.
+
+**Why it's wrong:** Fonts are brand identity - can't arbitrarily change.
+
+**Fix:** Use existing `font-heading` or `font-sans`, or ask to add Montserrat.
+
+### ❌ Using Inline Styles Instead of Theme
+
+**Problem:** `style={{ backgroundColor: '#3B82F6', padding: '24px' }}`
+
+**Why it's wrong:** Bypasses Tailwind theme, not responsive, harder to maintain.
+
+**Fix:** Use Tailwind classes: `bg-primary p-6`
+
+### ❌ Mixing Tailwind v3 and v4 Syntax
+
+**Problem:** Using Tailwind v3 syntax in a v4 project, or vice versa.
+
+**Why it's wrong:** Different versions have different configuration and syntax patterns. Mixing them causes build errors and unexpected styling behavior.
+
+**Fix:** Check `package.json` for Tailwind version first. Look at existing components to understand the syntax patterns used in the project. Match the version-specific patterns consistently.
+
+### ❌ Inconsistent Interactive States
+
+**Problem:** Some buttons use `hover:bg-primary-600`, others use `hover:brightness-110`.
+
+**Why it's wrong:** Inconsistent user experience.
+
+**Fix:** Check existing buttons, use same hover pattern everywhere.
+
+### ❌ Creating Theme Changes Without Approval
+
+**Problem:** Adding new color to `tailwind.config.ts` without asking.
+
+**Why it's wrong:** Theme changes affect entire project, need user agreement.
+
+**Fix:** Ask first, explain rationale, get approval.
+
+## Summary Checklist
+
+**Before creating any component:**
+
+- [ ] **Detected Tailwind CSS version (v3 or v4) from package.json**
+- [ ] Checked for existing theme configuration (Tailwind config or CSS variables)
+- [ ] Extracted existing colors and documented them
+- [ ] Extracted existing fonts and documented them
+- [ ] Reviewed 2-3 existing components for patterns
+- [ ] Identified spacing scale, border radius, shadow patterns
+- [ ] Confirmed I'm using theme tokens, not arbitrary values
+- [ ] Matched hover/focus states from existing components
+- [ ] Verified color contrast meets WCAG 2.1 AA (4.5:1 for text) - Use [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/)
+- [ ] Asked user before adding any new colors or fonts
+- [ ] Maintained visual consistency across all components
+
+**This is about CONSISTENCY, not creating new designs.** Match what exists, ask before changing.

package/skills/storefront-best-practices/reference/features/promotions.md

@@ -0,0 +1,307 @@
+# Promotions Feature
+
+## Contents
+
+- [Overview](#overview)
+- [Promotion Types and When to Use](#promotion-types-and-when-to-use)
+- [Sale Price Display](#sale-price-display)
+- [Promo Code Input](#promo-code-input)
+- [Free Shipping Threshold](#free-shipping-threshold)
+- [Promotional Banners](#promotional-banners)
+- [Countdown Timers](#countdown-timers)
+- [Mobile Considerations](#mobile-considerations)
+- [Checklist](#checklist)
+
+## Overview
+
+Promotions are temporary price reductions, discounts, or special offers designed to drive sales and incentivize purchases. Effective promotion UI clearly communicates value, creates urgency, and makes redemption easy.
+
+**Backend Integration (CRITICAL):**
+
+All promotion logic and data must come from the ecommerce backend. Do this based on backend integrated. Fetch active promotions, discount codes, and price rules from backend API. Never hardcode promotion logic in frontend.
+
+### Key Ecommerce Requirements
+
+- Clear discount communication (strikethrough pricing, percentage off)
+- Promo code input (cart/checkout)
+- Free shipping threshold progress (increase AOV)
+- Countdown timers (create urgency)
+- Automatic discount application
+- Sale badges (product discovery)
+
+### Purpose
+
+**Conversion optimization:**
+- Drive sales and increase conversion rate
+- Increase average order value (free shipping thresholds, tiered discounts)
+- Acquire new customers (first-order discounts)
+- Create urgency (limited-time offers)
+- Clear inventory (seasonal sales)
+- Reward loyalty (VIP codes, member discounts)
+
+## Promotion Types and When to Use
+
+### Sales (Price Reductions)
+
+**What it is**: Select products with reduced prices, automatically applied. No code needed.
+
+**Use when:**
+- Seasonal sales (Black Friday, holiday sales)
+- Clearance or end-of-season inventory
+- Product-specific promotions
+- You want reduced prices visible on product pages (increases click-through)
+
+**Display:**
+- Strikethrough original price (provides context for savings)
+- Sale price bold and prominent (red or brand color)
+- Sale badge on product cards ("Sale", "30% Off")
+
+**Medusa implementation:**
+Use Price Lists with special prices for products. Provides automatic strikethrough pricing in cart and on product pages.
+
+### Discount Codes
+
+**What it is**: Customer enters code to unlock discount (percentage, fixed amount, or free shipping).
+
+**Use when:**
+- Newsletter signups ("Get 10% off with WELCOME10")
+- VIP or loyalty program members (exclusive codes)
+- Targeted marketing campaigns (email, social media)
+- First-time customer incentives
+- Friends and family discounts (limited distribution)
+
+**Display:**
+- Promo code input field in cart/checkout
+- Success message: "Code applied: WELCOME10"
+- Discount shown in order summary with code name
+- Remove option (X icon or "Remove" link)
+
+**Medusa implementation:**
+Discount/promo code system with advanced logic (order-level discounts, usage limits, expiration dates).
+
+### Automatic Discounts
+
+**What it is**: Discount automatically applied when conditions met. No code entry required.
+
+**Use when:**
+- Free shipping thresholds ("Free shipping over $50")
+- Volume discounts ("Spend $100, get $20 off")
+- Buy One Get One (BOGO) offers
+- Encouraging larger cart values (increase AOV)
+
+**Display:**
+- Banner announcing the promotion
+- Progress indicator toward threshold (see Free Shipping Threshold section)
+- "Discount applied" message in cart
+- Automatic addition to order summary
+
+### Buy X, Get Y (BOGO)
+
+**What it is**: Purchase certain products to unlock free/discounted items.
+
+**Use when:**
+- Moving inventory (clear out slow-moving products)
+- Cross-selling related products ("Buy sunscreen, get beach bag 50% off")
+- Increasing units per transaction
+
+**Display:**
+- Clear promotion text on product page ("Buy 2, Get 1 Free")
+- Free/discounted item shown in cart with explanation
+- Discount line in order summary
+
+**Medusa implementation:**
+Buy X Get Y automatic discount. Free/discounted item must be added to cart to activate.
+
+## Sale Price Display
+
+### Strikethrough Pricing Pattern
+
+**Format:**
+```
+$49.99  $34.99
+(Original, strikethrough)  (Sale price, bold)
+```
+
+**Design:**
+- Original price: Strikethrough, muted gray color, smaller
+- Sale price: Bold, larger, red or accent color
+- Clear visual hierarchy (sale price dominates)
+
+**Placement:**
+- Product cards: Below image
+- Product page: Near "Add to Cart" button
+- Cart: Item price column
+
+### Percentage Off Display
+
+Show savings to emphasize value.
+
+**Options:**
+- "Save 30%" badge
+- "30% off" label
+- "$15 off" (absolute savings)
+
+**Placement:**
+- Badge on product image (top-left or top-right corner)
+- Near price (inline or below)
+- In cart summary ("Total savings: $45")
+
+### Sale Badge
+
+Bright badge on product image (red, orange, yellow) in top corner. 48-64px desktop, 40-48px mobile. Text: "Sale", "30% Off", or "Save $15".
+
+## Promo Code Input
+
+### Placement and Design
+
+**Location:**
+Cart page order summary or checkout page. Position in right sidebar (desktop) or below items (mobile).
+
+**Layout:**
+- Label: "Promo code" or "Discount code"
+- Text input (200-280px desktop, full-width mobile)
+- "Apply" button inline or stacked (mobile)
+- Auto-uppercase on submit (codes usually uppercase)
+
+**Expandable pattern (optional):**
+"Have a promo code?" link that expands to show input. Saves vertical space, reduces visual clutter.
+
+### Success and Error States
+
+**Success:**
+- Green checkmark or success message: "Code applied: WELCOME10"
+- Discount shown in order summary with code name: "Discount (WELCOME10) -$10.00"
+- Remove option: X icon or "Remove" link
+- Update cart total immediately
+
+**Error:**
+- Red error message below input: "Invalid code", "Code expired", or "Minimum purchase not met"
+- Input remains visible for retry
+- Don't clear input field (user may have typo)
+
+**Applied code display in order summary:**
+```
+Subtotal              $100.00
+Discount (WELCOME10)  -$10.00
+Shipping              $5.00
+─────────────────────
+Total                 $95.00
+```
+
+## Free Shipping Threshold
+
+**Purpose (CRITICAL)**: Increase average order value by encouraging customers to add more items to reach free shipping.
+
+### Progress Bar Pattern
+
+**Display in cart:**
+- "Add $25 more for FREE SHIPPING"
+- Horizontal progress bar showing proximity to threshold
+- Updates automatically as cart value changes
+- Green when threshold reached
+
+**Example:**
+```
+Add $25.00 more for FREE SHIPPING
+[███████░░░░░░░░] 50%
+```
+
+**When threshold met:**
+- "You've unlocked free shipping!" (success message)
+- Green checkmark or badge
+- Crossed-out shipping charge in order summary
+
+**Why it works:**
+- Visualizes proximity to goal (loss aversion)
+- Increases AOV by 15-30% on average
+- Reduces cart abandonment (free shipping is top reason to complete purchase)
+
+### Free Shipping Banner
+
+Sitewide announcement: "Free shipping on orders over $50". Display in top banner or near cart icon. Visible on all pages for awareness.
+
+## Promotional Banners
+
+### Top Banner
+
+Full-width strip at top of page (48-64px height). Bright color contrasting with navbar. Short message: "Free shipping on orders over $50" or "Sale: Up to 50% off - Shop Now".
+
+**Position:**
+- Above navbar (most common)
+- Below navbar (alternative)
+- Sticky (stays visible on scroll, optional)
+
+**CTA:**
+Link to sale page ("Shop Now", "Learn More") or whole banner clickable.
+
+### Hero Banner
+
+Large hero section on homepage with promotional message. Background image, headline ("Black Friday Sale"), subheading ("Up to 60% off sitewide"), CTA button ("Shop the Sale"), optional countdown timer.
+
+### Inline Banners
+
+Within page content (product pages, cart). Examples: Free shipping reminder on cart page, "Sale ends soon" on product page. Less prominent than hero.
+
+## Countdown Timers
+
+Use for time-sensitive promotions to create urgency and FOMO.
+
+**When to use:**
+- Flash sales (24-hour sales)
+- Limited-time offers
+- Holiday promotions
+- Never for permanent sales (fake urgency harms trust)
+
+**Display format:**
+- "Sale ends in: 2d 14h 32m 15s"
+- Or simpler: "Ends in 2 days"
+- Or: "Hurry! Only 14 hours left"
+
+**Placement:**
+Top banner, product page near price, cart page, or hero section.
+
+**Implementation:**
+Server-side time to prevent client manipulation, auto-hide when expired, update in real-time.
+
+## Mobile Considerations
+
+**Top banner:**
+Shorter text (fewer words), smaller height (40-48px), dismissible (X button).
+
+**Sale badges:**
+Slightly smaller (40-48px), still clearly visible, don't obstruct product image.
+
+**Promo code input:**
+Full-width input and button, stacked layout (input above button), large touch targets (48px height), expandable section to save space.
+
+**Countdown timer:**
+Simplified format ("Ends in 14 hours" vs full d:h:m:s), larger text for readability.
+
+## Checklist
+
+**Essential features:**
+
+- [ ] Strikethrough original price for sales
+- [ ] Sale price bold, prominent, colored
+- [ ] Sale badges on product images (40-64px)
+- [ ] Percentage off displayed ("30% Off")
+- [ ] Promo code input field in cart/checkout
+- [ ] "Apply" button next to promo input
+- [ ] Success message after applying code
+- [ ] Error message for invalid codes
+- [ ] Applied code displayed in order summary with name
+- [ ] Remove code option (X icon or "Remove" link)
+- [ ] Total savings highlighted in cart
+- [ ] Free shipping progress bar (if applicable)
+- [ ] Progress updates as cart value changes
+- [ ] Success message when threshold met
+- [ ] Countdown timer for time-limited offers (server-side)
+- [ ] Promotional banners (top banner, hero)
+- [ ] Backend integration (fetch promotions from API)
+- [ ] Mobile: Full-width promo input, stacked layout
+- [ ] Mobile: Large touch targets (48px)
+- [ ] Expandable promo section (optional, saves space)
+- [ ] ARIA labels on promo input
+- [ ] Screen reader announcements for price changes
+- [ ] Keyboard accessible (Tab, Enter)
+- [ ] High contrast text (4.5:1 minimum)