@kensaurus/skills 0.0.0-stage → 2.1.0

package/skills/design-email/SKILL.md

@@ -0,0 +1,370 @@
+---
+name: design-email
+description: >
+  Design and build transactional and marketing email templates. Use when
+  "build an email template", "welcome email", "password reset email", "React
+  Email", "MJML", "dark mode email", or "email copy review". Spam/SPF →
+  enhance-email-deliverability.
+license: MIT
+---
+
+# design-email — Email Templates That Actually Get Read
+
+**Degree of freedom: MIXED.** Copy and layout judgment `[HIGH freedom]`;
+stack detect, markup, send, and preview `[LOW freedom — run exactly]`.
+
+**Email is the one channel users check before they check your app.** A
+well-crafted transactional email — clear, warm, fast-loading, and readable on
+any device — builds trust. A corporate, jargon-heavy, broken email erodes it.
+This skill handles design and copy. Inbox placement / SPF DKIM DMARC is `enhance-email-deliverability`.
+
+## How to reason
+
+1. **Detect** — React Email vs MJML vs none
+2. **Audit** — copy voice, subject, one action; client-safe layout
+3. **Write** — specific subject, human "you", plain-text twin
+4. **Preview** — 375px + dark mode; hand DNS off
+
+## Worked example
+
+> **Detect:** `@react-email/components` already in `package.json`; `emails/` has a receipt only.
+> **Audit:** password-reset subject is "Account notification"; two CTAs; no preview text.
+> **Write:** subject "Reset your App password"; one "Reset my password" button; expiry in the first sentence.
+> **Preview:** `npx email dev` at 375px; tap target ≥44px; DNS/spam → `enhance-email-deliverability`.
+
+## Self-critique before reporting
+
+- **One action** — exactly one primary CTA; subject is specific and honest
+- **Client-safe** — 600px single column, inline styles, alt text, dark fallback
+- **Human copy** — "you"/"we"; no jargon or ALL-CAPS subject
+- **Right owner** — SPF / DKIM / DMARC / bounces / List-Unsubscribe → `enhance-email-deliverability`
+
+---
+
+## Phase 0: Detect the stack  [LOW freedom — run exactly]
+
+```
+package.json        → @react-email/*, mjml, nodemailer, @sendgrid/mail,
+                      resend, @aws-sdk/client-ses, postmark
+emails/             → existing React Email templates
+src/emails/         → email template directory
+.env.*              → RESEND_API_KEY, SENDGRID_API_KEY, etc. (reference by name only)
+```
+
+| Detected framework | Approach |
+|--------------------|----------|
+| React Email (`@react-email/components`) | JSX components, preview server, multi-client export |
+| MJML | XML-like syntax, battle-tested cross-client output |
+| None | Implement React Email (current best practice) |
+
+---
+
+## Phase 1: Audit existing templates  [HIGH freedom]
+
+If templates already exist, walk through each one and check:
+
+**Copy quality**:
+- Does it sound like a person sent it, or a system?
+- Is the subject line specific? ("Your order is on its way" not "Order notification")
+- Is the first sentence the most important one (preview text matters)?
+- Does it tell the reader exactly what to do and what happens next?
+- Is it free of business jargon, technical terms, and passive voice?
+
+**Design**:
+- Single-column layout? (Most reliable across clients)
+- Max-width 600px? (Standard email width)
+- All styles inline? (Gmail strips `<style>` tags)
+- Images have `alt` text? (Many clients block images by default)
+- Dark mode support? (`@media (prefers-color-scheme: dark)` + inline fallbacks)
+- Mobile: tap targets ≥ 44px, font size ≥ 14px
+
+**Sender identity (template-side):**
+- "From" address uses the app domain, not a personal Gmail?
+- SPF / DKIM / DMARC / bounces → `enhance-email-deliverability`
+
+---
+
+## Phase 2: Research best practices  [HIGH freedom]
+
+```json
+firecrawl:firecrawl_search
+{
+  "query": "transactional email design best practices [current year] React Email",
+  "limit": 3,
+  "sources": [{ "type": "web" }]
+}
+```
+
+Fetch React Email docs if using it:
+```json
+context7:resolve-library-id
+{
+  "libraryName": "react-email"
+}
+```
+
+---
+
+## Phase 3: Copy principles  [HIGH freedom]
+
+Apply these to every email before looking at design:
+
+| Principle | How |
+|-----------|-----|
+| Lead with the most important thing | First line = the key action or news. Not "Hi, we wanted to let you know that…" |
+| Subject line = specific, honest | "Your password reset link" not "Important account information" |
+| One email, one action | Every email should have exactly one thing it wants the reader to do |
+| Write to a person, not an account | "You" not "the user". "We" not "the system". |
+| Tell them what happens next | "Click the button below to confirm. The link expires in 24 hours." |
+| No jargon | "Your account" not "your profile entity". "Sign in" not "authenticate". |
+| Active voice | "We've sent you a link" not "A link has been sent to you" |
+| Short paragraphs | 1–2 sentences max. White space is your friend in email. |
+| Plain text fallback | Every HTML email should have a plain text version |
+
+### Common email types — copy templates
+
+**Welcome email:**
+```
+Subject: Welcome to [App Name], [First Name] 👋
+Preview: Here's how to get started in 2 minutes.
+
+Hi [First Name],
+
+You're in. [App Name] helps you [core value in 1 sentence].
+
+Here's the first thing to do: [single CTA — most valuable first action].
+
+[Primary Button: Get started]
+
+If you have any questions, just reply to this email.
+
+— [Name], [App Name]
+```
+
+**Password reset:**
+```
+Subject: Reset your [App Name] password
+Preview: Your link expires in 1 hour.
+
+Hi [First Name],
+
+Someone requested a password reset for your [App Name] account.
+If that was you, click the button below. If not, you can ignore this email.
+
+[Primary Button: Reset my password]
+
+This link expires in 1 hour. After that, you'll need to request a new one.
+```
+
+**Billing confirmation:**
+```
+Subject: Your payment of [amount] was successful
+Preview: Next billing date: [date].
+
+Hi [First Name],
+
+Your payment of [amount] for [Plan Name] went through.
+
+Amount: [amount]
+Date: [date]
+Next billing date: [date]
+
+[Button: View your invoice]
+
+Questions about your bill? Reply here and we'll sort it out.
+```
+
+---
+
+## Phase 4: Build the template (React Email)  [LOW freedom — run exactly]
+
+Install if not present:
+```bash
+npm install react-email @react-email/components
+```
+
+Base template structure (illustrative — swap the indigo button and off-white ground for the brand):
+```tsx
+// emails/welcome.tsx
+import {
+  Body, Button, Container, Head, Heading, Hr, Html,
+  Link, Preview, Section, Text, Img,
+} from '@react-email/components';
+
+interface WelcomeEmailProps {
+  firstName: string;
+  ctaUrl: string;
+}
+
+export function WelcomeEmail({ firstName, ctaUrl }: WelcomeEmailProps) {
+  return (
+    <Html lang="en">
+      <Head />
+      <Preview>Welcome to AppName — here's how to get started.</Preview>
+      <Body style={body}>
+        <Container style={container}>
+          <Img src="https://yourdomain.com/logo.png" width="48" height="48" alt="AppName" />
+          <Heading style={h1}>Welcome, {firstName}</Heading>
+          <Text style={text}>
+            You're in. AppName helps you [core value in one sentence].
+          </Text>
+          <Text style={text}>
+            Here's the first thing to do:
+          </Text>
+          <Section style={btnContainer}>
+            <Button style={button} href={ctaUrl}>
+              Get started
+            </Button>
+          </Section>
+          <Text style={text}>
+            If you have any questions, just reply to this email.
+          </Text>
+          <Hr style={hr} />
+          <Text style={footer}>
+            AppName · 123 Street · City · {' '}
+            <Link href="{{{UNSUBSCRIBE_URL}}}">Unsubscribe</Link>
+          </Text>
+        </Container>
+      </Body>
+    </Html>
+  );
+}
+
+const body = { backgroundColor: '#f6f9fc', fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif' };
+const container = { backgroundColor: '#ffffff', margin: '40px auto', padding: '40px', maxWidth: '600px', borderRadius: '8px' };
+const h1 = { fontSize: '24px', fontWeight: '700', color: '#1a1a1a', marginBottom: '16px' };
+const text = { fontSize: '16px', lineHeight: '1.6', color: '#444', marginBottom: '16px' };
+const btnContainer = { textAlign: 'center' as const, marginBottom: '24px' };
+const button = { backgroundColor: '#6366f1', borderRadius: '6px', color: '#fff', fontSize: '16px', fontWeight: '600', padding: '12px 28px', textDecoration: 'none', display: 'inline-block' };
+const hr = { borderColor: '#e5e7eb', marginTop: '32px', marginBottom: '32px' };
+const footer = { fontSize: '12px', color: '#9ca3af', textAlign: 'center' as const };
+```
+
+### Dark mode support
+
+```tsx
+// In <Head>:
+<style>{`
+  @media (prefers-color-scheme: dark) {
+    .email-body { background-color: #1a1a1a !important; }
+    .email-container { background-color: #2d2d2d !important; }
+    .email-text { color: #e5e7eb !important; }
+    .email-heading { color: #f9fafb !important; }
+  }
+`}</style>
+// Add className to Body, Container, Text, Heading components to match
+```
+
+---
+
+## Phase 5: Send via provider  [LOW freedom — run exactly]
+
+### Resend (recommended for new projects)
+
+```typescript
+import { Resend } from 'resend';
+import { WelcomeEmail } from '../emails/welcome';
+import { render } from '@react-email/render';
+
+const resend = new Resend(process.env.RESEND_API_KEY);
+
+await resend.emails.send({
+  from: 'AppName <hello@yourdomain.com>',
+  to: user.email,
+  subject: `Welcome to AppName, ${user.firstName}`,
+  react: <WelcomeEmail firstName={user.firstName} ctaUrl={ctaUrl} />,
+});
+```
+
+### Add a Supabase Edge Function trigger (if using Supabase)
+
+```typescript
+// supabase/functions/send-welcome-email/index.ts
+import { serve } from 'https://deno.land/std/http/server.ts';
+import { Resend } from 'npm:resend';
+
+serve(async (req) => {
+  const { record } = await req.json(); // from a database webhook
+  const resend = new Resend(Deno.env.get('RESEND_API_KEY'));
+  await resend.emails.send({
+    from: 'AppName <hello@yourdomain.com>',
+    to: record.email,
+    subject: `Welcome to AppName!`,
+    html: '...', // rendered HTML
+  });
+  return new Response('OK');
+});
+```
+
+Deploy:
+```bash
+supabase functions deploy send-welcome-email --no-verify-jwt
+```
+
+---
+
+## Phase 6: Content flags that hurt placement  [LOW freedom — do not skip]
+
+DNS auth, bounces, and List-Unsubscribe headers are `enhance-email-deliverability`.
+This phase only owns copy/markup that templates can fix:
+
+- [ ] From address uses your domain (not `noreply@gmail.com`)
+- [ ] Reply-To set if replies should go somewhere useful
+- [ ] No ALL-CAPS words in subject line
+- [ ] No spam trigger words: "FREE", "URGENT", "ACT NOW", "GUARANTEED"
+- [ ] Plain text version matches the HTML version
+- [ ] Hand remaining inbox-placement work to `enhance-email-deliverability`
+
+---
+
+## Phase 7: Preview and test  [LOW freedom — run exactly]
+
+Start the React Email preview server:
+```bash
+npx email dev --dir emails --port 3001
+```
+
+Then check with Playwright:
+```bash
+PW="npx --yes @playwright/cli@latest"
+$PW -s=email-preview open --headed http://localhost:3001
+$PW -s=email-preview snapshot                                  # verify each template renders
+$PW -s=email-preview resize 375 812                            # mobile — font size, tap targets
+$PW -s=email-preview screenshot --filename ".playwright-mcp/email-mobile.png"
+```
+
+For cross-client testing, use Litmus or Email on Acid. Key clients to test:
+- Gmail (web + Android + iOS)
+- Apple Mail (macOS + iOS)
+- Outlook (Windows — most restrictive CSS support)
+- Samsung Mail
+
+---
+
+## Email templates checklist
+
+```
+Design:
+- [ ] Max-width 600px
+- [ ] Single column
+- [ ] All styles inline (no <style> blocks except dark mode)
+- [ ] Images have alt text
+- [ ] Buttons ≥ 44px tall, large enough to tap
+- [ ] Font size ≥ 14px on body text
+- [ ] Dark mode tested
+
+Copy:
+- [ ] Subject line is specific and honest
+- [ ] Preview text set and meaningful
+- [ ] First sentence is the most important thing
+- [ ] Exactly one primary action
+- [ ] Copy sounds like a person wrote it
+- [ ] No jargon or passive voice
+- [ ] Plain text version exists
+
+Deliverability (handoff — do not own here):
+- [ ] From address on app domain
+- [ ] Plain-text alternative present
+- [ ] SPF / DKIM / DMARC / bounces / unsubscribe headers → `enhance-email-deliverability`
+```
+

package/skills/design-frontend/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: design-frontend
+description: >
+  Create a new production-grade UI from scratch, not a polish pass. Use when
+  "build this UI", "design this page", or "new dashboard layout". Polish →
+  enhance-web-ui. Landing → enhance-web-landing. Redesign →
+  enhance-web-redesign.
+license: MIT
+---
+
+# Frontend Design Skill
+
+**Degree of freedom: MIXED.** Visual composition `[HIGH freedom]`; design-system
+discovery `[LOW freedom — run exactly]`.
+
+> Discover design systems, respect existing patterns, create beautiful interfaces.
+
+## How to reason
+
+1. **Discover** — tokens, `components/ui`, forbidden patterns
+2. **Reuse** — extend existing components; do not fork a second Button
+3. **Compose** — new surface on those tokens
+4. **Check** — type mins, 44px targets, reduced-motion, none of the named defaults in the Anti-Generic list
+
+## Worked example
+
+> **Discover:** `components/ui/button.tsx` + `globals.css` tokens; `text-xs` min; `rounded-sm`.
+> **Reuse:** settings rows use existing `Button` / `Input`; no new primitive.
+> **Compose:** new `/settings` page — token spacing, `text-sm` body, 44px save.
+> **Check:** Anti-Generic list clear (no Inter, purple-on-white, or pill buttons); `prefers-reduced-motion` on any spinner.
+
+## Self-critique before reporting
+
+- **Discovery stated** — token file, radius, and forbidden list were spoken before JSX
+- **Reuse first** — no duplicate primitive next to `components/ui`
+- **Mins held** — readable type ≥ `text-xs`; tap targets ≥44px
+- **Right owner** — polish existing → `enhance-web-ui`; landing → `enhance-web-landing`; redesign existing → `enhance-web-redesign`
+
+---
+
+## Phase 1: Design System Discovery  [LOW freedom — run exactly]
+
+**Before writing ANY frontend code:**
+
+### 1.1 Find Design System Files
+```
+Glob: **/*design-system*.{md,ts,css}
+Glob: **/tokens*.{ts,json}
+Glob: **/components/ui/**
+Glob: **/_*README*
+```
+
+### 1.2 Extract & Document Tokens
+| Category | Find | Examples |
+|----------|------|----------|
+| Typography | Sizes, weights | `text-xs`, `font-medium` |
+| Spacing | Padding, gaps | `p-4`, `gap-2` |
+| Colors | Palette, semantic | `bg-emerald-50` |
+| Borders | Radius, styles | `rounded-sm` |
+| Animations | Durations | `duration-200` |
+
+### 1.3 Find Forbidden Patterns
+```bash
+grep -r "NEVER\|FORBIDDEN\|❌" docs/ README*
+```
+
+### 1.4 Verification Statement (REQUIRED)
+```
+"Design System Discovery:
+├─ Found: [design system path]
+├─ Typography min: [e.g., text-xs]
+├─ Radius standard: [e.g., rounded-sm]
+├─ Forbidden: [list patterns]
+└─ Reusing: [existing components]"
+```
+
+---
+
+## Phase 2: Implementation Standards  [HIGH freedom]
+
+### Typography Minimums
+| Context | Minimum | Usage |
+|---------|---------|-------|
+| Body | `text-sm` (14px) | Primary content |
+| Captions | `text-xs` (12px) | Labels, hints |
+| Compact | `text-[10px]` | Dense dashboards only |
+
+**Never use** `text-[8px]` or `text-[9px]` for readable content.
+
+### Accessibility Requirements
+| Check | Requirement |
+|-------|-------------|
+| Touch targets | ≥44×44px |
+| Contrast | 4.5:1 text, 3:1 UI |
+| Keyboard | `tabIndex`, focus styles |
+| Motion | `prefers-reduced-motion` |
+
+### Quick Reference
+```
+Typography: text-xs=12px, text-sm=14px, text-base=16px
+Spacing: 1=4px, 2=8px, 3=12px, 4=16px, 6=24px, 8=32px
+```
+
+---
+
+## Phase 3: Quality Checklist  [LOW freedom — do not skip]
+
+```
+[ ] Uses design system tokens (no hardcoded values)
+[ ] Extends existing components (no duplicates)
+[ ] Typography ≥ text-xs for readable content
+[ ] Touch targets ≥ 44px
+[ ] Focus states visible
+[ ] prefers-reduced-motion respected
+```
+
+### Common Fixes
+| Issue | Fix |
+|-------|-----|
+| Tiny text | `text-[9px]` → `text-xs` |
+| Bold weights | `font-bold` → `font-medium` |
+| Large radius | `rounded-lg` → `rounded-sm` |
+| Spin animation | `animate-spin` → `animate-pulse` |
+
+---
+
+## Anti-Generic Checklist
+
+Undirected drafts land on the same few defaults; the check is concrete only when they are named:
+- [ ] Inter / Roboto / Arial as the display or body face
+- [ ] Purple (violet/indigo) gradient on white
+- [ ] Cream / off-white page background
+- [ ] Italic accent words inside headlines
+- [ ] "01 / 02 / 03" numbered section labels
+- [ ] Monospace eyebrow labels on a non-code product
+- [ ] Pill-shaped (fully rounded) buttons as the house button
+- [ ] Three equal cards in a row as the default section layout
+
+Extend this list with whatever the first draft used instead.
+
+---
+
+> **Remember:** The codebase's design system is the source of truth. Search before creating. Reuse before reinventing.