@ivannxbt/ai-config 0.1.0

package/.agents/skills/design-md/examples/DESIGN.md

@@ -0,0 +1,154 @@
+# Design System: Furniture Collections List
+**Project ID:** 13534454087919359824
+
+## 1. Visual Theme & Atmosphere
+
+The Furniture Collections List embodies a **sophisticated, minimalist sanctuary** that marries the pristine simplicity of Scandinavian design with the refined visual language of luxury editorial presentation. The interface feels **spacious and tranquil**, prioritizing breathing room and visual clarity above all else. The design philosophy is gallery-like and photography-first, allowing each furniture piece to command attention as an individual art object.
+
+The overall mood is **airy yet grounded**, creating an aspirational aesthetic that remains approachable and welcoming. The interface feels **utilitarian in its restraint** but elegant in its execution, with every element serving a clear purpose while maintaining visual sophistication. The atmosphere evokes the serene ambiance of a high-end furniture showroom where customers can browse thoughtfully without visual overwhelm.
+
+**Key Characteristics:**
+- Expansive whitespace creating generous breathing room between elements
+- Clean, architectural grid system with structured content blocks
+- Photography-first presentation with minimal UI interference
+- Whisper-soft visual hierarchy that guides without shouting
+- Refined, understated interactive elements
+- Professional yet inviting editorial tone
+
+## 2. Color Palette & Roles
+
+### Primary Foundation
+- **Warm Barely-There Cream** (#FCFAFA) – Primary background color. Creates an almost imperceptible warmth that feels more inviting than pure white, serving as the serene canvas for the entire experience.
+- **Crisp Very Light Gray** (#F5F5F5) – Secondary surface color used for card backgrounds and content areas. Provides subtle visual separation while maintaining the airy, ethereal quality.
+
+### Accent & Interactive
+- **Deep Muted Teal-Navy** (#294056) – The sole vibrant accent in the palette. Used exclusively for primary call-to-action buttons (e.g., "Shop Now", "View all products"), active navigation links, selected filter states, and subtle interaction highlights. This sophisticated anchor color creates visual focus points without disrupting the serene neutral foundation.
+
+### Typography & Text Hierarchy
+- **Charcoal Near-Black** (#2C2C2C) – Primary text color for headlines and product names. Provides strong readable contrast while being softer and more refined than pure black.
+- **Soft Warm Gray** (#6B6B6B) – Secondary text used for body copy, product descriptions, and supporting metadata. Creates clear typographic hierarchy without harsh contrast.
+- **Ultra-Soft Silver Gray** (#E0E0E0) – Tertiary color for borders, dividers, and subtle structural elements. Creates separation so gentle it's almost imperceptible.
+
+### Functional States (Reserved for system feedback)
+- **Success Moss** (#10B981) – Stock availability, confirmation states, positive indicators
+- **Alert Terracotta** (#EF4444) – Low stock warnings, error states, critical alerts
+- **Informational Slate** (#64748B) – Neutral system messages, informational callouts
+
+## 3. Typography Rules
+
+**Primary Font Family:** Manrope  
+**Character:** Modern, geometric sans-serif with gentle humanist warmth. Slightly rounded letterforms that feel contemporary yet approachable.
+
+### Hierarchy & Weights
+- **Display Headlines (H1):** Semi-bold weight (600), generous letter-spacing (0.02em for elegance), 2.75-3.5rem size. Used sparingly for hero sections and major page titles.
+- **Section Headers (H2):** Semi-bold weight (600), subtle letter-spacing (0.01em), 2-2.5rem size. Establishes clear content zones and featured collections.
+- **Subsection Headers (H3):** Medium weight (500), normal letter-spacing, 1.5-1.75rem size. Product names and category labels.
+- **Body Text:** Regular weight (400), relaxed line-height (1.7), 1rem size. Descriptions and supporting content prioritize comfortable readability.
+- **Small Text/Meta:** Regular weight (400), slightly tighter line-height (1.5), 0.875rem size. Prices, availability, and metadata remain legible but visually recessive.
+- **CTA Buttons:** Medium weight (500), subtle letter-spacing (0.01em), 1rem size. Balanced presence without visual aggression.
+
+### Spacing Principles
+- Headers use slightly expanded letter-spacing for refined elegance
+- Body text maintains generous line-height (1.7) for effortless reading
+- Consistent vertical rhythm with 2-3rem between related text blocks
+- Large margins (4-6rem) between major sections to reinforce spaciousness
+
+## 4. Component Stylings
+
+### Buttons
+- **Shape:** Subtly rounded corners (8px/0.5rem radius) – approachable and modern without appearing playful or childish
+- **Primary CTA:** Deep Muted Teal-Navy (#294056) background with pure white text, comfortable padding (0.875rem vertical, 2rem horizontal)
+- **Hover State:** Subtle darkening to deeper navy, smooth 250ms ease-in-out transition
+- **Focus State:** Soft outer glow in the primary color for keyboard navigation accessibility
+- **Secondary CTA (if needed):** Outlined style with Deep Muted Teal-Navy border, transparent background, hover fills with whisper-soft teal tint
+
+### Cards & Product Containers
+- **Corner Style:** Gently rounded corners (12px/0.75rem radius) creating soft, refined edges
+- **Background:** Alternates between Warm Barely-There Cream and Crisp Very Light Gray based on layering needs
+- **Shadow Strategy:** Flat by default. On hover, whisper-soft diffused shadow appears (`0 2px 8px rgba(0,0,0,0.06)`) creating subtle depth
+- **Border:** Optional hairline border (1px) in Ultra-Soft Silver Gray for delicate definition when shadows aren't present
+- **Internal Padding:** Generous 2-2.5rem creating comfortable breathing room for content
+- **Image Treatment:** Full-bleed at the top of cards, square or 4:3 ratio, seamless edge-to-edge presentation
+
+### Navigation
+- **Style:** Clean horizontal layout with generous spacing (2-3rem) between menu items
+- **Typography:** Medium weight (500), subtle uppercase, expanded letter-spacing (0.06em) for refined sophistication
+- **Default State:** Charcoal Near-Black text
+- **Active/Hover State:** Smooth 200ms color transition to Deep Muted Teal-Navy
+- **Active Indicator:** Thin underline (2px) in Deep Muted Teal-Navy appearing below current section
+- **Mobile:** Converts to elegant hamburger menu with sliding drawer
+
+### Inputs & Forms
+- **Stroke Style:** Refined 1px border in Soft Warm Gray
+- **Background:** Warm Barely-There Cream with transition to Crisp Very Light Gray on focus
+- **Corner Style:** Matching button roundness (8px/0.5rem) for visual consistency
+- **Focus State:** Border color shifts to Deep Muted Teal-Navy with subtle outer glow
+- **Padding:** Comfortable 0.875rem vertical, 1.25rem horizontal for touch-friendly targets
+- **Placeholder Text:** Ultra-Soft Silver Gray, elegant and unobtrusive
+
+### Product Cards (Specific Pattern)
+- **Image Area:** Square (1:1) or landscape (4:3) ratio filling card width completely
+- **Content Stack:** Product name (H3), brief descriptor, material/finish, price
+- **Price Display:** Emphasized with semi-bold weight (600) in Charcoal Near-Black
+- **Hover Behavior:** Gentle lift effect (translateY -4px) combined with enhanced shadow
+- **Spacing:** Consistent 1.5rem internal padding below image
+
+## 5. Layout Principles
+
+### Grid & Structure
+- **Max Content Width:** 1440px for optimal readability and visual balance on large displays
+- **Grid System:** Responsive 12-column grid with fluid gutters (24px mobile, 32px desktop)
+- **Product Grid:** 4 columns on large desktop, 3 on desktop, 2 on tablet, 1 on mobile
+- **Breakpoints:** 
+  - Mobile: <768px
+  - Tablet: 768-1024px  
+  - Desktop: 1024-1440px
+  - Large Desktop: >1440px
+
+### Whitespace Strategy (Critical to the Design)
+- **Base Unit:** 8px for micro-spacing, 16px for component spacing
+- **Vertical Rhythm:** Consistent 2rem (32px) base unit between related elements
+- **Section Margins:** Generous 5-8rem (80-128px) between major sections creating dramatic breathing room
+- **Edge Padding:** 1.5rem (24px) mobile, 3rem (48px) tablet/desktop for comfortable framing
+- **Hero Sections:** Extra-generous top/bottom padding (8-12rem) for impactful presentation
+
+### Alignment & Visual Balance
+- **Text Alignment:** Left-aligned for body and navigation (optimal readability), centered for hero headlines and featured content
+- **Image to Text Ratio:** Heavily weighted toward imagery (70-30 split) reinforcing photography-first philosophy
+- **Asymmetric Balance:** Large hero images offset by compact, refined text blocks
+- **Visual Weight Distribution:** Strategic use of whitespace to draw eyes to hero products and primary CTAs
+- **Reading Flow:** Clear top-to-bottom, left-to-right pattern with intentional focal points
+
+### Responsive Behavior & Touch
+- **Mobile-First Foundation:** Core experience designed and perfected for smallest screens first
+- **Progressive Enhancement:** Additional columns, imagery, and details added gracefully at larger breakpoints
+- **Touch Targets:** Minimum 44x44px for all interactive elements (WCAG AAA compliant)
+- **Image Optimization:** Responsive images with appropriate resolutions for each breakpoint, lazy-loading for performance
+- **Collapsing Strategy:** Navigation collapses to hamburger, grid reduces columns, padding scales proportionally
+
+## 6. Design System Notes for Stitch Generation
+
+When creating new screens for this project using Stitch, reference these specific instructions:
+
+### Language to Use
+- **Atmosphere:** "Sophisticated minimalist sanctuary with gallery-like spaciousness"
+- **Button Shapes:** "Subtly rounded corners" (not "rounded-md" or "8px")
+- **Shadows:** "Whisper-soft diffused shadows on hover" (not "shadow-sm")
+- **Spacing:** "Generous breathing room" and "expansive whitespace"
+
+### Color References
+Always use the descriptive names with hex codes:
+- Primary CTA: "Deep Muted Teal-Navy (#294056)"
+- Backgrounds: "Warm Barely-There Cream (#FCFAFA)" or "Crisp Very Light Gray (#F5F5F5)"
+- Text: "Charcoal Near-Black (#2C2C2C)" or "Soft Warm Gray (#6B6B6B)"
+
+### Component Prompts
+- "Create a product card with gently rounded corners, full-bleed square product image, and whisper-soft shadow on hover"
+- "Design a primary call-to-action button in Deep Muted Teal-Navy (#294056) with subtle rounded corners and comfortable padding"
+- "Add a navigation bar with generous spacing between items, using medium-weight Manrope with subtle uppercase and expanded letter-spacing"
+
+### Incremental Iteration
+When refining existing screens:
+1. Focus on ONE component at a time (e.g., "Update the product grid cards")
+2. Be specific about what to change (e.g., "Increase the internal padding of product cards from 1.5rem to 2rem")
+3. Reference this design system language consistently

package/.agents/skills/email-best-practices/README.md

@@ -0,0 +1,63 @@
+```
+  ╔══════════════════════════════════════╗
+  ║   _____ __  __    _    ___ _         ║
+  ║  | ____|  \/  |  / \  |_ _| |        ║
+  ║  |  _| | |\/| | / _ \  | || |        ║
+  ║  | |___| |  | |/ ___ \ | || |___     ║
+  ║  |_____|_|  |_/_/   \_\___|_____|    ║
+  ║                                      ║
+  ║           Best Practices             ║
+  ╚══════════════════════════════════════╝
+```
+
+# Email Best Practices Skill
+
+A comprehensive agent skill for building production-ready email systems. Covers everything from DNS authentication to webhook processing, with a focus on deliverability, compliance, and reliability.
+
+## Installation
+
+```bash
+npx skills add resend/email-best-practices
+```
+
+## What This Skill Covers
+
+**Getting Started**
+- Planning which emails your app needs (password reset, verification, order confirmations)
+- Setting up email authentication (SPF, DKIM, DMARC) so emails reach inboxes
+
+**Sending Emails**
+- Transactional email design (subject lines, content structure, mobile-first)
+- Marketing email best practices (consent, segmentation, unsubscribe)
+- Compliance requirements by region (CAN-SPAM, GDPR, CASL)
+
+**Production Infrastructure**
+- Idempotency and retry logic to prevent duplicates
+- Webhook processing for delivery events
+- Suppression lists and list hygiene automation
+
+## Structure
+
+```
+email-best-practices/
+├── SKILL.md                             # Start here - routes to the right resource
+└── resources/
+    ├── deliverability.md                # SPF/DKIM/DMARC, sender reputation
+    ├── transactional-emails.md          # Password resets, OTPs, confirmations
+    ├── transactional-email-catalog.md   # Email combinations by app type
+    ├── marketing-emails.md              # Newsletters, campaigns, consent
+    ├── email-capture.md                 # Validation, verification, opt-in
+    ├── compliance.md                    # CAN-SPAM, GDPR, CASL
+    ├── email-types.md                   # Transactional vs marketing
+    ├── sending-reliability.md           # Idempotency, retry logic, errors
+    ├── webhooks-events.md               # Delivery events, webhook setup
+    └── list-management.md               # Suppression lists, hygiene
+```
+
+## Quick Start
+
+Open `SKILL.md` - it has a routing table that directs you to the right resource based on what you need to do.
+
+## License
+
+MIT

package/.agents/skills/email-best-practices/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: email-best-practices
+description: Use when building email features, emails going to spam, high bounce rates, setting up SPF/DKIM/DMARC authentication, implementing email capture, ensuring compliance (CAN-SPAM, GDPR, CASL), handling webhooks, retry logic, or deciding transactional vs marketing.
+---
+
+# Email Best Practices
+
+Guidance for building deliverable, compliant, user-friendly emails.
+
+## Architecture Overview
+
+```
+[User] → [Email Form] → [Validation] → [Double Opt-In]
+                                              ↓
+                                    [Consent Recorded]
+                                              ↓
+[Suppression Check] ←──────────────[Ready to Send]
+        ↓
+[Idempotent Send + Retry] ──────→ [Email API]
+                                       ↓
+                              [Webhook Events]
+                                       ↓
+              ┌────────┬────────┬─────────────┐
+              ↓        ↓        ↓             ↓
+         Delivered  Bounced  Complained  Opened/Clicked
+                       ↓        ↓
+              [Suppression List Updated]
+                       ↓
+              [List Hygiene Jobs]
+```
+
+## Quick Reference
+
+| Need to... | See |
+|------------|-----|
+| Set up SPF/DKIM/DMARC, fix spam issues | [Deliverability](./resources/deliverability.md) |
+| Build password reset, OTP, confirmations | [Transactional Emails](./resources/transactional-emails.md) |
+| Plan which emails your app needs | [Transactional Email Catalog](./resources/transactional-email-catalog.md) |
+| Build newsletter signup, validate emails | [Email Capture](./resources/email-capture.md) |
+| Send newsletters, promotions | [Marketing Emails](./resources/marketing-emails.md) |
+| Ensure CAN-SPAM/GDPR/CASL compliance | [Compliance](./resources/compliance.md) |
+| Decide transactional vs marketing | [Email Types](./resources/email-types.md) |
+| Handle retries, idempotency, errors | [Sending Reliability](./resources/sending-reliability.md) |
+| Process delivery events, set up webhooks | [Webhooks & Events](./resources/webhooks-events.md) |
+| Manage bounces, complaints, suppression | [List Management](./resources/list-management.md) |
+
+## Start Here
+
+**New app?**
+Start with the [Catalog](./resources/transactional-email-catalog.md) to plan which emails your app needs (password reset, verification, etc.), then set up [Deliverability](./resources/deliverability.md) (DNS authentication) before sending your first email.
+
+**Spam issues?**
+Check [Deliverability](./resources/deliverability.md) first—authentication problems are the most common cause. Gmail/Yahoo reject unauthenticated emails.
+
+**Marketing emails?**
+Follow this path: [Email Capture](./resources/email-capture.md) (collect consent) → [Compliance](./resources/compliance.md) (legal requirements) → [Marketing Emails](./resources/marketing-emails.md) (best practices).
+
+**Production-ready sending?**
+Add reliability: [Sending Reliability](./resources/sending-reliability.md) (retry + idempotency) → [Webhooks & Events](./resources/webhooks-events.md) (track delivery) → [List Management](./resources/list-management.md) (handle bounces).

package/.agents/skills/email-best-practices/resources/compliance.md

@@ -0,0 +1,125 @@
+# Email Compliance
+
+Legal requirements for email by jurisdiction. **Not legal advice—consult an attorney for your specific situation.**
+
+## Quick Reference
+
+| Law | Region | Key Requirement | Penalty |
+|-----|--------|-----------------|---------|
+| CAN-SPAM | US | Opt-out mechanism, physical address | $53k/email |
+| GDPR | EU | Explicit opt-in consent | €20M or 4% revenue |
+| CASL | Canada | Express consent, opt-out mechanism | $1M (individual) to $10M (organization) CAD |
+
+## CAN-SPAM (United States)
+
+**Requirements:**
+- Accurate header info (From, To, Reply-To)
+- Non-deceptive subject lines
+- Physical mailing address in every email
+- Clear opt-out mechanism
+- Honor opt-out within 10 business days
+
+**Transactional emails:** Can send without opt-in if related to a transaction and not promotional.
+
+## GDPR (European Union)
+
+**Requirements:**
+- Explicit opt-in consent (not pre-checked boxes)
+- Consent must be freely given, specific, informed
+- Easy to withdraw consent (as easy as giving it)
+- Right to access data and deletion ("right to be forgotten")
+- Process unsubscribe immediately
+
+**Consent records:** Document who, when, how, and what they consented to.
+
+**Transactional emails:** Can send based on contract fulfillment or legitimate interest.
+
+## CASL (Canada)
+
+**Consent types:**
+- **Express consent:** Explicit opt-in (ideal)
+- **Implied consent:** Existing business relationship (2 years) or inquiry (6 months)
+
+**Requirements:**
+- Clear sender identification that will be valid for 60 days after send
+- Unsubscribe functional for 60 days after send
+- Process unsubscribe no later than 10 business days
+- Keep consent records 3 years after expiration
+
+## Other Regions
+
+| Region | Law | Key Points |
+|--------|-----|------------|
+| Australia | Spam Act 2003 | Consent required, honor unsubscribe within 5 days |
+| UK | PECR + GDPR | Same as GDPR |
+| Brazil | LGPD | Similar to GDPR, explicit consent for marketing |
+
+## Unsubscribe Requirements Summary
+
+| Law | Timing | Notes |
+|-----|--------|-------|
+| CAN-SPAM | 10 business days | Must work 30 days after send |
+| GDPR | Immediately | Must be as easy as opting in |
+| CASL | 10 business days | Must work 60 days after send |
+
+**Universal best practices:** Prominent link, one-click when possible, no login required, free, confirm action.
+
+### List-Unsubscribe Header (Required for Bulk Senders)
+
+Gmail, Yahoo, and Microsoft require `List-Unsubscribe` headers. Without them, bulk emails may be rejected or spam-filtered.
+
+**Required headers:**
+
+```typescript
+headers: {
+  'List-Unsubscribe': '<https://example.com/unsubscribe>',
+  'List-Unsubscribe-Post': 'List-Unsubscribe=One-Click',
+}
+```
+
+**Your unsubscribe endpoint must:**
+- Accept POST requests — return `200` or `202` with a blank page
+- Display standard unsubscribe page for GET requests
+- Stop sending within 48 hours of the request
+
+## Managing preferences vs Unsubscribe from all
+
+Most legistlations require a one-click unsubscribe. `Managing preferences` is a nice-to-have and can lead to lower unsubscribe rate but doesn't replace `Unsubscribe`. If possible, offer both.
+
+## Consent Management
+
+**Record:**
+- Email address
+- Date/time of consent
+- Method (form, checkbox)
+- What they consented to
+- Source (which page/form)
+
+**Storage:** Database with timestamps, audit trail of changes, link to user account.
+
+## Data Retention
+
+| Law | Requirement |
+|-----|-------------|
+| GDPR | Keep only as long as necessary, delete when no longer needed |
+| CASL | Keep consent records 3 years after expiration |
+
+**Best practice:** Have clear retention policy, honor deletion requests promptly, review and clean regularly.
+
+## Privacy Policy Must Include
+
+- What data you collect
+- How you use data
+- Who you share data with
+- User rights (access, deletion)
+- How to contact about privacy
+
+## International Sending
+
+**Best practice:** Follow the most restrictive requirements (usually GDPR) to ensure compliance across all regions.
+
+## Related
+
+- [Email Capture](./email-capture.md) - Implement consent forms and double opt-in
+- [Marketing Emails](./marketing-emails.md) - Consent and unsubscribe requirements
+- [List Management](./list-management.md) - Handle unsubscribes and deletion requests

package/.agents/skills/email-best-practices/resources/deliverability.md

@@ -0,0 +1,121 @@
+# Email Deliverability
+
+Maximizing the chances that your emails are delivered successfully to the recipients.
+
+## Email Authentication
+
+**Required by Gmail/Yahoo/Microsoft** - unauthenticated emails will be rejected or spam-filtered.
+
+### SPF (Sender Policy Framework)
+
+Specifies which servers can send email for your domain.
+
+```
+v=spf1 include:amazonses.com ~all
+```
+
+- Add TXT record to DNS
+- Use `~all` (soft fail)
+
+### DKIM (DomainKeys Identified Mail)
+
+Cryptographic signature proving email authenticity.
+
+- Your email service will provide you with a TXT record
+
+### DMARC
+
+Policy for handling SPF/DKIM failures + reporting.
+
+```
+v=DMARC1; p=none; rua=mailto:dmarc@yourdomain.com
+```
+
+**Rollout:** `p=none` (monitor) → `p=quarantine; pct=25` → `p=reject`
+
+Learn more: https://resend.com/blog/dmarc-policy-modes 
+
+### Verify Your Setup
+
+Check DNS records directly:
+
+```bash
+# SPF record
+dig TXT yourdomain.com +short
+
+# DKIM record (replace 'resend' with your selector)
+dig TXT resend._domainkey.yourdomain.com +short
+
+# DMARC record
+dig TXT _dmarc.yourdomain.com +short
+```
+
+**Expected output:** Each command should return your configured record. No output = record missing.
+
+## Sender Reputation
+
+### IP Warming
+
+New IP/domain? Gradually increase volume:
+
+| Week | Daily Volume |
+|------|-------------|
+| 1 | 50-100 |
+| 2 | 200-500 |
+| 3 | 1,000-2,000 |
+| 4 | 5,000-10,000 |
+
+Start with engaged users. Send consistently. Don't rush.
+
+Learn more: https://resend.com/docs/knowledge-base/warming-up
+
+### Maintaining Reputation
+
+**Do:** Send to engaged users, keep bounce <4%, complaints <0.1%, remove inactive subscribers.
+
+**Don't:** Send to purchased lists, ignore bounces/complaints, send inconsistent volumes
+
+## Bounce Handling
+
+| Type | Cause | Action |
+|------|-------|--------|
+| Hard bounce | Permanent failure to deliver | Remove immediately |
+| Soft bounce | Transient failure to deliver | Retry: 1h → 4h → 24h, remove after 3-5 failures |
+
+**Targets:** <1% good, 1-3% acceptable, 3-4% concerning, >4% critical
+
+## Complaint Handling
+
+**Targets:** <0.01% excellent, 0.01-0.05% good, >0.05% critical
+
+**Reduce complaints:**
+- Only send to opted-in users
+- Make unsubscribe easy and immediate
+- Use clear sender names and "From" addresses
+
+**Feedback loops:** Set up with Gmail (Postmaster Tools), Yahoo, Microsoft SNDS. Remove complainers immediately.
+
+## Infrastructure
+
+**Dedicated sending domain:** Use different subdomains for different sending purposes (e.g., `t.yourdomain.com` for transactional emails and `m.yourdomain.com` for marketing emails). 
+
+**DNS TTL:** Low (300s) during setup, high (3600s+) after stable.
+
+## Troubleshooting
+
+**Emails going to spam?** Check in order:
+1. Authentication (SPF, DKIM, DMARC)
+2. List-Unsubscribe header — required by Gmail/Yahoo since Feb 2024 (see [Compliance](./compliance.md))
+3. Sender reputation (blacklists, complaint rates)
+4. Content
+5. Sending patterns (sudden volume spikes)
+
+**Diagnostic tools:**
+- [Google Postmaster Tools](https://postmaster.google.com) - Domain reputation and spam rates
+- [mail-tester.com](https://www.mail-tester.com) - Send a test email, get deliverability score
+- [MXToolbox](https://mxtoolbox.com/blacklists.aspx) - Check blacklist status
+
+## Related
+
+- [List Management](./list-management.md) - Handle bounces and complaints to protect reputation
+- [Sending Reliability](./sending-reliability.md) - Retry logic and error handling

package/.agents/skills/email-best-practices/resources/email-capture.md

@@ -0,0 +1,129 @@
+# Email Capture Best Practices
+
+Collecting email addresses responsibly with validation, verification, and proper consent.
+
+## Email Validation
+
+### Client-Side
+
+**HTML5:**
+```html
+<input type="email" required>
+```
+
+**Best practices:**
+- Validate on blur or with short debounce
+- Show clear error messages
+- Don't be too strict (allow unusual but valid formats)
+- Client-side validation ≠ deliverability
+
+### Server-Side (Recommended)
+
+Always validate server-side—client-side can be bypassed.
+
+**Check:**
+- Email format (RFC 5322)
+- Domain exists (DNS lookup)
+- Domain has MX records
+- Optionally: disposable email detection
+
+Recommended tools: https://resend.com/blog/best-email-verification-apis
+
+## Double opt-in
+
+Confirms address belongs to user and is deliverable.
+
+### Process
+
+1. User submits email
+2. Send verification email with unique link/token
+3. User clicks link
+4. Mark as verified
+5. Allow access/add to list
+
+**Timing:** Send immediately, include expiration (24-48 hours), allow resend after 60 seconds, limit resend attempts (3/hour).
+
+### Single vs Double Opt-In
+
+| | Single Opt-In | Double Opt-In |
+|--|---------------|---------------|
+| **Process** | Add to list immediately | Require email confirmation first |
+| **Pros** | Lower friction, faster growth | Verified addresses, better engagement, meets GDPR/CASL |
+| **Cons** | Higher invalid rate, lower engagement | Some users don't confirm |
+| **Use for** | Account creation, transactional | Marketing lists, newsletters |
+
+**Recommendation:** Double opt-in for all marketing emails.
+
+## Form Design
+
+### Email Input
+
+- Use `type="email"` for mobile keyboard
+- Include placeholder ("you@example.com")
+- Clear error messages ("Please enter a valid email address" not "Invalid")
+
+### Consent Checkboxes (Marketing)
+
+- **Unchecked by default** (required)
+- Specific language about what they're signing up for
+- Separate checkboxes for different email types
+- Link to privacy policy
+
+```
+☐ Subscribe to our weekly newsletter with product updates
+☐ Send me promotional offers and deals
+```
+
+**Don't:** Pre-check boxes, use vague language, hide in terms.
+
+### Form Layout
+
+- Keep simple and focused
+- One primary action
+- Clear value proposition
+- Mobile-friendly
+- Accessible (labels, ARIA)
+
+## Error Handling
+
+### Invalid Email
+
+- Show clear error message
+- Suggest corrections for common typos (@gmial.com → @gmail.com)
+- Allow user to fix and resubmit
+
+### Already Registered
+
+- Accounts: "This email is already registered. [Sign in]"
+- Marketing: "You're already subscribed! [Manage preferences]"
+- Don't reveal if account exists (security)
+
+### Rate Limiting
+
+- Limit verification emails (3/hour per email)
+- Rate limit form submissions
+- Use CAPTCHA sparingly if needed
+- Monitor for abuse patterns
+
+## Verification Emails
+
+**Content:**
+- Clear purpose ("Verify your email address")
+- Prominent verification button
+- Expiration time
+- Resend option
+- "I didn't request this" notice
+- Don't include OTP/2FA codes in subject line or preview text as it discourages opens
+
+**Design:**
+- Mobile-friendly
+- Large, tappable button
+- Clear call-to-action
+
+See [Transactional Emails](./transactional-emails.md) for detailed email design guidance.
+
+## Related
+
+- [Compliance](./compliance.md) - Legal requirements for consent (GDPR, CASL)
+- [Marketing Emails](./marketing-emails.md) - What happens after capture
+- [Deliverability](./deliverability.md) - How validation improves sender reputation