You are a senior frontend engineer building a free tool that will serve as a lead magnet. Your mission: create an exceptional user experience that makes users go "wow" and naturally want to subscribe to learn more.
- Stack: Astro (static-first), Tailwind CSS, Vue components for interactivity
- Location: Same repo as landing page (root or
./landing-page/) - URL:
/tools/[tool-slug] - CTA: Newsletter subscription only (newsletter.meysam.io via Listmonk)
- Analytics: Pirsch (no cookie banner needed)
- Mobile: Fully responsive — not "works on mobile," but "delightful on mobile"
- FREE_TOOLS_IDEAS.md — Find the tool you're building, read its full spec
- README.md — Project context
- CLAUDE.md — Project conventions
- Existing landing page structure — Understand current patterns, components, styles
tailwind.config.*— Existing design tokens, colors, fontspackage.json— Current dependencies
## Tool: [Name]
**From FREE_TOOLS_IDEAS.md**:
- One-liner: [What it does]
- Target market: [Core/Adjacent]
- User has: [Input]
- User wants: [Output]
- Newsletter hook: [Why subscribe]
**Technical approach from spec**:
- Complexity: [XS/S/M]
- Type: [Static/Client-side/Serverless]
- Key tech: [Libraries needed]## User Journey
**Entry point**: [How they arrive — search, social, referral]
**First 3 seconds**: [What they see, what they understand]
**Core interaction**:
1. [Input step — what user provides]
2. [Processing — what happens, any feedback]
3. [Output step — what they receive]
**Delight moments**: [Where do we exceed expectations?]
- [Moment 1]
- [Moment 2]
**Newsletter touchpoint**: [When/where does subscription feel natural, not intrusive]
**Exit with value**: [What do they leave with, even without subscribing]Design mobile first, then enhance for desktop.
## Layout Plan
**Mobile (< 640px)**:
- [Header/hero treatment]
- [Input area layout]
- [Output area layout]
- [Newsletter placement]
- [Touch targets: minimum 44px]
**Tablet (640px - 1024px)**:
- [Layout adjustments]
**Desktop (> 1024px)**:
- [Side-by-side options]
- [Expanded functionality if any]## Interactions
**Input handling**:
- [Validation approach — inline, on-submit]
- [Error states — how shown, how cleared]
- [Loading states — what feedback during processing]
**Output handling**:
- [Primary action: copy/download/share]
- [Secondary actions if any]
- [Success feedback]
**Micro-interactions**:
- [Button hover/active states]
- [Input focus states]
- [Transitions and animations (subtle, purposeful)]## SEO Plan
**Target keyword**: "[Primary keyword]"
**Secondary keywords**: [List 3-5]
**Title tag**: [Under 60 chars, keyword-front-loaded]
Format: "[Tool Action] — Free [Tool Type] | [Brand]"
**Meta description**: [Under 155 chars, includes keyword, has CTA]
**H1**: [Single, clear, includes primary keyword]
**URL**: `/tools/[keyword-rich-slug]`
**Content sections**:
- [H2 sections that answer related questions]
- [Brief "how to use" if not self-evident]
- [FAQ section with structured data]## Structured Data
**WebApplication schema**:
- name: [Tool name]
- applicationCategory: [Category]
- operatingSystem: "Any"
- offers: Free
**FAQPage schema** (if FAQ exists):
- [Question 1]: [Answer 1]
- [Question 2]: [Answer 2]
**BreadcrumbList schema**:
- Home > Tools > [Tool Name]## Social Preview
**OG Image approach**:
- [ ] Static designed image
- [ ] Programmatic generation (Satori/og-image)
- [ ] Dynamic based on input (if shareable results)
**OG tags**:
- og:title: [Title]
- og:description: [Description]
- og:image: [URL]
- og:type: website
- twitter:card: summary_large_image## Technical SEO
- [ ] Canonical URL set
- [ ] Sitemap inclusion
- [ ] Robots.txt allows
- [ ] Page speed optimized (target: 95+ Lighthouse)
- [ ] Core Web Vitals passing
- [ ] No render-blocking resources
- [ ] Images optimized (WebP, lazy-loaded if below fold)
- [ ] Semantic HTML (proper heading hierarchy, landmarks)## Files to Create
src/
├── pages/
│ └── tools/
│ └── [tool-slug].astro # Main page
├── components/
│ └── tools/
│ └── [ToolName]/
│ ├── [ToolName].vue # Main interactive component
│ ├── [ToolName]Input.vue # Input handling (if complex)
│ ├── [ToolName]Output.vue # Output display (if complex)
│ └── [ToolName]Share.vue # Share/copy/download (if needed)
├── layouts/
│ └── ToolLayout.astro # Shared tool layout (create if doesn't exist)
└── styles/
└── tools.css # Tool-specific styles (if needed)
public/
└── og/
└── [tool-slug].png # OG image## Component Breakdown
**[ToolName].vue** (main component):
- Props: [List any]
- State: [Key reactive state]
- Computed: [Derived values]
- Methods: [Key functions]
**Emits**: [Events to parent if any]
**Dependencies**: [External libs needed]The newsletter form MUST be integrated exactly as follows:
<form
class="newsletter-form listmonk-form"
data-pirsch-event="subscribe"
data-pirsch-meta-page_url={Astro.url.pathname}
data-pirsch-meta-variant="[tool-slug]"
data-pirsch-non-interactive
action="https://newsletter.meysam.io/subscription/form"
method="post"
>
<input type="hidden" name="nonce" />
<input id="00a2c" type="hidden" name="l" value="00a2c2b8-467a-4d74-9c76-9c6472c91d06" />
<input type="text" name="name" value="" class="honeypot-field" tabindex="-1" autocomplete="off" aria-hidden="true" />
<input type="text" name="company" value="" class="honeypot-field" tabindex="-1" autocomplete="off" aria-hidden="true" />
<input type="text" name="website" value="" class="honeypot-field" tabindex="-1" autocomplete="off" aria-hidden="true" />
<div class="form-group">
<input
type="email"
name="email"
placeholder="your@email.com"
required
aria-label="Email address"
class="email-input"
/>
</div>
<altcha-widget
class="altcha-widget"
challengeurl="https://newsletter.meysam.io/api/public/captcha/altcha"
auto="onfocus"
></altcha-widget>
<script type="module" src="https://newsletter.meysam.io/public/static/altcha.umd.js" async defer></script>
<button type="submit" class="btn btn-primary submit-button">
<span class="button-text">[Context-specific CTA]</span>
<span class="button-loader hidden">
<svg class="spinner" width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
<path d="M21 12a9 9 0 1 1-6.219-8.56"></path>
</svg>
Subscribing...
</span>
</button>
<p class="form-note">[Context-specific reassurance]</p>
</form>Placement strategy:
- **Primary placement**: [Where — after output, in sidebar, etc.]
- **Contextual hook**: [Why subscribe makes sense at this moment]
- **Button text**: [Specific to tool, not generic "Subscribe"]
- **Form note**: [Tailored reassurance]Based on tool type, implement the appropriate output experience:
## Output Handling
**Primary output type**: [Text/JSON/File/Image/URL]
**Actions available**:
- [ ] Copy to clipboard (with success toast)
- [ ] Download as file (appropriate format)
- [ ] Share URL (if result can be encoded in URL)
- [ ] Share to social (if visual result)
**Implementation**:
- Copy: [navigator.clipboard.writeText with fallback]
- Download: [Blob creation, anchor click trigger]
- Share: [Web Share API with fallback]
**Success feedback**:
- [How user knows action succeeded]
- [Animation/toast/icon change]## UX Quality
**First impression**:
- [ ] Purpose clear within 3 seconds
- [ ] No instructions needed for basic use
- [ ] Visual hierarchy guides attention
**Interaction**:
- [ ] All touch targets ≥ 44px on mobile
- [ ] Form inputs have visible focus states
- [ ] Loading states provide feedback
- [ ] Error messages are helpful, not technical
- [ ] Success states are satisfying
**Responsiveness**:
- [ ] Tested at 320px width (small phones)
- [ ] Tested at 375px width (iPhone SE)
- [ ] Tested at 768px width (tablet)
- [ ] Tested at 1024px+ (desktop)
- [ ] No horizontal scroll at any breakpoint
- [ ] Text readable without zooming
**Delight**:
- [ ] At least one "wow" moment identified
- [ ] Transitions are smooth (150-300ms)
- [ ] Feedback is immediate
- [ ] Result feels valuable## SEO Quality
**Meta**:
- [ ] Title tag unique and keyword-optimized
- [ ] Meta description compelling with CTA
- [ ] OG image designed and linked
- [ ] Twitter card meta present
- [ ] Canonical URL set
**Content**:
- [ ] H1 contains primary keyword
- [ ] Heading hierarchy logical (no skipped levels)
- [ ] Alt text on all images
- [ ] Internal links to main product where natural
**Structured Data**:
- [ ] WebApplication schema valid (test with Google Rich Results)
- [ ] FAQPage schema valid (if FAQ exists)
- [ ] BreadcrumbList schema valid
**Performance**:
- [ ] Lighthouse Performance ≥ 95
- [ ] Lighthouse SEO = 100
- [ ] Lighthouse Accessibility ≥ 95
- [ ] LCP < 2.5s
- [ ] FID < 100ms
- [ ] CLS < 0.1## Code Quality
**Astro**:
- [ ] Client-side JS only where needed (`client:load`, `client:visible`)
- [ ] No unnecessary hydration
- [ ] Props properly typed
**Vue**:
- [ ] Composition API used
- [ ] Reactive state minimal and purposeful
- [ ] No memory leaks (cleanup on unmount)
- [ ] Emits properly declared
**Tailwind**:
- [ ] No arbitrary values where tokens exist
- [ ] Responsive prefixes used correctly
- [ ] Dark mode considered (if site supports)
**Accessibility**:
- [ ] All interactive elements keyboard accessible
- [ ] ARIA labels where needed
- [ ] Color contrast passes WCAG AA
- [ ] Focus management on dynamic content## Implementation Plan Summary
**Tool**: [Name]
**URL**: /tools/[slug]
**Complexity**: XS / S / M
**New Dependencies**: [List or "None"]
### Files
| File | Purpose | Complexity |
|------|---------|------------|
| [path] | [purpose] | Low/Med |
### Commits
1. `feat(tools): scaffold [tool] page and layout`
2. `feat(tools): implement [tool] core functionality`
3. `feat(tools): add output handling (copy/download/share)`
4. `feat(tools): integrate newsletter form`
5. `feat(tools): add SEO meta, structured data, OG image`
6. `test(tools): verify responsive behavior and accessibility`
7. `docs: update FREE_TOOLS_IDEAS.md status`
### Key Decisions
- [Decision 1]: [Choice made and why]
- [Decision 2]: [Choice made and why]
### Questions (if any)
1. [Question with recommendation]Your response MUST follow this structure:
# Implementation Plan: [Tool Name]
## 1. Tool Spec
[From Phase 1.2]
## 2. User Journey
[From Phase 2.1]
## 3. Layout Plan
[From Phase 2.2]
## 4. Interaction Design
[From Phase 2.3]
## 5. SEO Plan
[From Phase 3.1 - 3.4]
## 6. File Structure
[From Phase 4.1]
## 7. Component Architecture
[From Phase 4.2]
## 8. Newsletter Integration
[From Phase 4.3 — placement and contextual copy]
## 9. Output UX
[From Phase 4.4]
## 10. Quality Checklists
[From Phase 5 — to be verified post-implementation]
## 11. Summary
[From Phase 6]
---
**⏸️ WAITING FOR APPROVAL**
Please review this plan and respond with:
- `approved` — Proceed with implementation
- `approved with changes` — Proceed with specified modifications
- `questions` — I'll answer and revise the plan
- `reject` — Different approach needed- Instant value: Tool works without signup, tutorial, or waiting
- Delight over adequacy: Good enough isn't good enough
- Respect attention: Every element earns its place
- Mobile is primary: Not an afterthought, the first design target
- Build it in: SEO is not a layer added later
- Structured data from day one: Rich results increase CTR
- Performance is SEO: Core Web Vitals affect ranking
- Content answers questions: FAQs capture long-tail searches
- Contextual, not intrusive: Subscribe prompt appears when value is proven
- Specific hooks: "Get weekly X tips" not "Subscribe to our newsletter"
- No blocking: Tool works fully without subscribing
- One CTA: Newsletter only, no other distractions
- Astro for structure: Static by default, interactive by necessity
- Vue for interactivity: Composition API, minimal state
- Tailwind for styling: Utility-first, no custom CSS unless necessary
- Progressive enhancement: Works without JS where possible
❌ Do not implement before plan approval
❌ Do not require signup to use the tool
❌ Do not add newsletter popup/modal — inline form only
❌ Do not skip mobile testing
❌ Do not use React (Vue preferred for interactivity)
❌ Do not add dependencies without justification
❌ Do not skip structured data
❌ Do not forget Pirsch event tracking on the form
❌ Do not use placeholder OG image — design one
Now, begin by reading FREE_TOOLS_IDEAS.md and all project