seo-checklist

What this skill does

# SEO First Principles for PolicyEngine Web Apps

Use this skill when auditing or building web applications that need to be discoverable via search engines. PolicyEngine apps are typically React SPAs deployed to GitHub Pages, often served both standalone and embedded as iframes in policyengine.org research pages.

---

## How Search Engines Work

Google does three things:

1. **Crawl** — Googlebot fetches your URL and downloads the raw HTML response
2. **Index** — It reads that HTML, understands what the page is about, stores it
3. **Rank** — When someone searches, it picks the best matching pages from its index

Your job is to make all three steps easy. If any step fails, your page won't appear in search results.

---

## Principle 1: Google Reads HTML, Not Your Screen

**The most critical issue for React SPAs.** When Googlebot visits a client-side rendered app, it sees:

```html
<div id="root"></div>
```

All content generated by JavaScript may or may not be indexed. Google can execute JS but:
- Pages enter a "render queue" (delays of hours to days)
- JS errors = no content indexed
- Google deprioritizes JS-rendered content vs static HTML

**Test:** Run `curl -s YOUR_URL | grep -c '<h1>'` — if the result is 0, Google likely can't see your content.

**Solutions (ranked by effectiveness):**

| Approach | Description | Effort |
|----------|------------|--------|
| SSR (Next.js, Remix) | Server renders full HTML on each request | High (framework change) |
| SSG (Static Site Generation) | Pre-build HTML at deploy time | Medium |
| Pre-rendering | Render SPA to static HTML for crawlers | Low-Medium |
| Meta tags only | At minimum, add static meta tags to index.html | Low |

For PolicyEngine calculator apps, **pre-rendering or SSG** is the sweet spot. The form/landing page is static content; only results are dynamic.

---

## Principle 2: One URL = One Page = One Topic

Google ranks **pages**, not websites. Each URL you want to rank for needs:
- Its own distinct URL path
- Unique title and description
- Content relevant to that specific topic

### Hash Routing is Invisible to SEO

```
https://example.com/#country=us&region=CA&head=45000
```

Google treats everything after `#` as the same page. All hash variations = one URL = one indexed page.

### Path-Based URLs Are Crawlable

```
https://example.com/us/california?head=45000
```

Query parameters (`?key=value`) ARE seen by Google (though they may be treated as variants). Path segments (`/us/california`) are treated as distinct pages.

---

## Principle 3: The Standalone vs Iframe Dual-Mode Problem

PolicyEngine apps often run in two modes:

1. **Standalone** — Deployed on GitHub Pages (e.g., `policyengine.github.io/us-marriage-incentive/`)
2. **Embedded** — Iframed inside policyengine.org research pages (e.g., `policyengine.org/us/research/marriage`)

### SEO Implications

| Concern | Standalone | Embedded (iframe) |
|---------|-----------|-------------------|
| Indexed by Google? | Yes (if crawlable) | No — Google indexes the parent page, not iframe content |
| Needs meta tags? | Yes — this is the version Google sees | No — parent page provides meta tags |
| Needs canonical URL? | Yes — should point to itself OR the parent page | N/A |
| Needs robots.txt? | Yes | N/A (inherits from parent domain) |
| Needs sitemap? | Yes | N/A (parent sitemap covers parent pages) |

### Canonical URL Strategy

If the **primary audience** should find the app via policyengine.org:
```html
<link rel="canonical" href="https://policyengine.org/us/research/marriage">
```
This tells Google: "The real version of this content lives on policyengine.org. Index that one."

If the **standalone version** is the primary:
```html
<link rel="canonical" href="https://policyengine.github.io/us-marriage-incentive/">
```

**Rule:** Every page needs exactly one canonical URL. Without it, Google may index both versions and split your ranking power between them (called "duplicate content dilution").

### Detecting Iframe Mode in Code

Most PolicyEngine apps already detect this:
```javascript
const isEmbedded = window.self !== window.top;
```

SEO-relevant behavior should NOT depend on this check — meta tags, titles, and structured data must be present in the static HTML regardless of runtime mode.

---

## Principle 4: Required Meta Tags

Every PolicyEngine web app needs these in `index.html`:

### Critical (must have)

```html
<!-- Basic SEO -->
<title>US Marriage Tax Calculator — Marriage Penalty & Bonus | PolicyEngine</title>
<meta name="description" content="Calculate how marriage affects your taxes and government benefits. See your marriage penalty or bonus across income levels for any US state.">
<link rel="canonical" href="https://policyengine.github.io/us-marriage-incentive/">

<!-- Open Graph (Facebook, LinkedIn, Slack, iMessage previews) -->
<meta property="og:type" content="website">
<meta property="og:title" content="US Marriage Tax Calculator">
<meta property="og:description" content="Calculate how marriage affects your taxes and government benefits.">
<meta property="og:image" content="https://policyengine.github.io/us-marriage-incentive/og-image.png">
<meta property="og:url" content="https://policyengine.github.io/us-marriage-incentive/">
<meta property="og:site_name" content="PolicyEngine">

<!-- Twitter / X -->
<meta name="twitter:card" content="summary_large_image">
<meta name="twitter:title" content="US Marriage Tax Calculator">
<meta name="twitter:description" content="Calculate how marriage affects your taxes and government benefits.">
<meta name="twitter:image" content="https://policyengine.github.io/us-marriage-incentive/og-image.png">
```

### Important (should have)

```html
<!-- Structured Data (JSON-LD) -->
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebApplication",
  "name": "US Marriage Tax Calculator",
  "description": "Calculate how marriage affects your taxes and government benefits.",
  "url": "https://policyengine.github.io/us-marriage-incentive/",
  "applicationCategory": "FinanceApplication",
  "operatingSystem": "Web",
  "offers": { "@type": "Offer", "price": "0", "priceCurrency": "USD" },
  "author": {
    "@type": "Organization",
    "name": "PolicyEngine",
    "url": "https://policyengine.org"
  }
}
</script>

<!-- Theme color for mobile browsers — use --pe-color-primary-500 value -->
<meta name="theme-color" content="#319795">
```

### Title Tag Rules

- Under 60 characters (Google truncates after that)
- Primary keyword first: "US Marriage Tax Calculator" not "PolicyEngine — Calculator"
- Include the brand at the end: "... | PolicyEngine"
- Be specific: "Marriage Tax Calculator" not "Calculator"
- Every page needs a unique title

### Meta Description Rules

- 150-160 characters
- Include a call to action ("Calculate", "Find out", "Compare")
- Include primary keywords naturally
- Describe what the user gets, not what the app is

### OG Image Rules

- Dimensions: 1200 x 630 pixels
- Format: PNG or JPG
- Must be an absolute URL (not a relative path)
- Should visually represent the app (screenshot, branded graphic)
- Place in `public/` directory so it's available at build output root

---

## Principle 5: Crawlability Files

### robots.txt

Place in `public/robots.txt` (Vite copies `public/` contents to build root):

```
User-agent: *
Allow: /

Sitemap: https://YOUR_DOMAIN/sitemap.xml
```

### sitemap.xml

Place in `public/sitemap.xml`:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
  <url>
    <loc>https://YOUR_DOMAIN/</loc>
    <lastmod>2025-01-01</lastmod>
    <changefreq>monthly</changefreq>
  </url>
</urlset>
```

For apps with multiple distinct pages, add each URL as a separate `<url>` entry.

### .nojekyll (GitHub Pages only)

**Always add an empty `.nojekyll` file to `public/`** when deploying to GitHub Pages. Without it, GitHub runs Jekyll processing which can mangle XML files like `sitemap.x