# SEO, AEO & Schema Requirements

> All components — both wrapped site components and library components — MUST follow these requirements to ensure the homepage is fully optimized for search engines, answer engines (ChatGPT, Perplexity, Gemini), and web indexing.

---

## Rule #1: Preserve All Existing SEO

**DO NOT remove or modify any existing SEO elements** from the target site:
- `<title>` tags
- `<meta name="description">` tags
- `<link rel="canonical">` tags
- Schema.org JSON-LD scripts
- Open Graph (`og:`) meta tags
- Twitter Card meta tags
- `robots.txt` rules
- `sitemap.xml` entries

These MUST remain in the page after Puck integration.

---

## Semantic HTML

All components MUST use proper semantic HTML elements:

| Purpose | Element | NOT |
|---|---|---|
| Page sections | `<section>` | `<div>` |
| Blog article cards | `<article>` | `<div>` |
| Navigation blocks | `<nav>` | `<div>` |
| Images with captions | `<figure>` + `<figcaption>` | `<div>` + `<p>` |
| Lists of items | `<ul>` / `<ol>` + `<li>` | `<div>` |
| Time/dates | `<time datetime="...">` | `<span>` |
| Main content area | `<main>` | `<div>` |
| Page header | `<header>` | `<div>` |
| Page footer | `<footer>` | `<div>` |
| Side content | `<aside>` | `<div>` |

---

## Heading Hierarchy

Every page MUST maintain proper heading structure:

```
<h1>  — ONE per page (usually in the hero section)
  <h2>  — Section headings
    <h3>  — Sub-sections, card titles within a section
      <h4>  — Sub-sub-sections (rare)
```

**Rules:**
- Only ONE `<h1>` per page
- Never skip levels (e.g., `<h1>` → `<h3>` without `<h2>`)
- `<h1>` should contain the page's primary keyword/topic
- Each `<h2>` should describe a major content section

**For component wrapping:** If the existing hero has `<h1>`, keep it. Other section headings should be `<h2>`.

---

## Image Optimization

Every `<img>` element MUST have:

```html
<img
  src="..."
  alt="Descriptive alt text in the page's language"
  loading="lazy"          <!-- for below-fold images -->
  width="..."
  height="..."            <!-- prevents layout shift -->
  className="..."
/>
```

**Rules:**
- **`alt` text is mandatory** — describe the image content, not the file name
- **`loading="lazy"`** for all images below the first viewport (above-fold images should NOT be lazy)
- **Width/height or aspect-ratio** to prevent Cumulative Layout Shift (CLS)
- Use Next.js `<Image>` component where possible for automatic optimization
- **Hero/banner images**: Use `loading="eager"` or `priority` (Next.js Image)

---

## Schema.org JSON-LD

Add structured data for components that support it. Each schema type is rendered as a `<script type="application/ld+json">` block.

### FAQ Component → FAQPage Schema

When a FAQ component is on the page, output:

```json
{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "質問テキスト",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "回答テキスト"
      }
    }
  ]
}
```

### Review/Ranking Components → Review Schema

```json
{
  "@context": "https://schema.org",
  "@type": "Review",
  "itemReviewed": {
    "@type": "Product",
    "name": "Product Name"
  },
  "reviewRating": {
    "@type": "Rating",
    "ratingValue": "4.5",
    "bestRating": "5"
  },
  "author": {
    "@type": "Person",
    "name": "Author Name"
  }
}
```

### Article Grid Components → ItemList Schema

```json
{
  "@context": "https://schema.org",
  "@type": "ItemList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "url": "https://site.com/post/article-slug"
    }
  ]
}
```

### Author Components → Person Schema

```json
{
  "@context": "https://schema.org",
  "@type": "Person",
  "name": "Author Name",
  "description": "Author Bio",
  "image": "https://site.com/avatar.jpg",
  "sameAs": [
    "https://twitter.com/...",
    "https://instagram.com/..."
  ]
}
```

### Steps/Process Components → HowTo Schema

```json
{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "手順タイトル",
  "step": [
    {
      "@type": "HowToStep",
      "name": "ステップ1",
      "text": "ステップの説明"
    }
  ]
}
```

---

## Answer Engine Optimization (AEO)

To make content extractable by AI systems (ChatGPT, Perplexity, Gemini):

### 1. Clear, direct answers
Component content should provide concise, factual answers that LLMs can extract:
- FAQ answers should directly answer the question in the first sentence
- Process steps should be numbered and self-contained
- Comparison tables should have clear column headers

### 2. Structured data formats
Use structured formats that AIs can parse:
- Tables for comparisons (use `<table>` with `<thead>` and `<tbody>`)
- Lists for features/benefits (use `<ul>` / `<ol>`)
- Definition-style content for glossaries (use `<dl>`, `<dt>`, `<dd>`)

### 3. Topical authority signals
- Author information with credentials (AuthorBox, AuthorProfile)
- Published/updated dates on article components
- Category taxonomy in navigation components
- Internal linking between related content

### 4. Content freshness
- Article components should show `publishedAt` dates
- Dynamic components should show recent content by default
- The editor should make it easy to update content regularly

---

## Internal Linking

### Use Next.js `<Link>` for internal links

All internal navigation links should use Next.js `<Link>` component for:
- Client-side navigation (faster page transitions)
- Automatic prefetching
- Proper handling of base paths

### Link attributes

| Link Type | `rel` Attribute | `target` |
|---|---|---|
| Internal navigation | (none needed) | (same tab) |
| External trusted site | `noopener noreferrer` | `_blank` |
| External untrusted/affiliate | `noopener noreferrer nofollow` | `_blank` |
| Sponsored/affiliate | `noopener noreferrer sponsored` | `_blank` |

Components with external links should have editable `rel` and `target` fields.

---

## Editor Page SEO

The editor page (`/page_editor_admin`) MUST be:

```typescript
// Already set in the template layout.tsx
export const metadata = {
  title: 'Homepage Editor',
  robots: { index: false, follow: false },
};
```

- **`noindex, nofollow`** — search engines must NOT index the editor
- No links from the public site should point to the editor page
- The editor page should NOT appear in sitemap.xml

---

## Core Web Vitals

### Largest Contentful Paint (LCP)
- Hero images: use `loading="eager"` or Next.js `priority`
- Hero video: preload poster image
- Above-fold text should render on the server (SSR), not client-side

### Cumulative Layout Shift (CLS)
- All images must have explicit width/height or aspect-ratio
- Dynamic components must reserve space (even with skeleton loaders)
- Font loading: use `font-display: swap`

### Interaction to Next Paint (INP)
- Event handlers should not block the main thread
- Heavy computations should be deferred
- Editor page can be heavier (it's not indexed) — focus CWV on the public homepage

---

## Accessibility

### Minimum requirements:
- All interactive elements must be keyboard-accessible
- Color contrast ratio ≥ 4.5:1 for text
- All images have `alt` text
- Form inputs have associated `<label>` elements
- Focus indicators are visible

### ARIA attributes:
- Expandable sections (FAQ, accordion): `aria-expanded`
- Navigation: `aria-label` on `<nav>` elements
- Icons without text: `aria-label` or `aria-hidden="true"` if decorative

---

## Checklist

After implementation, verify each item:

### SEO Essentials
- [ ] `<title>` tag is descriptive and unique
- [ ] `<meta name="description">` is compelling and under 160 chars
- [ ] `<link rel="canonical">` points to the correct URL
- [ ] Only ONE `<h1>` on the page
- [ ] Heading hierarchy is sequential (h1 → h2 → h3)
- [ ] All images have descriptive `alt` text
- [ ] Schema.org JSON-LD is present for FAQ, Reviews, Author (if those components are used)
- [ ] Page content is server-rendered (view source shows text)

### AEO Essentials
- [ ] FAQ answers are direct and factual (first sentence answers the question)
- [ ] Structured data is valid (test with Google Rich Results Test)
- [ ] Author information includes credentials and social profiles
- [ ] Tables have clear headers and structured data

### Technical
- [ ] Editor page has `noindex, nofollow`
- [ ] No CLS on page load (images have dimensions)
- [ ] Above-fold images use `loading="eager"`
- [ ] Below-fold images use `loading="lazy"`
- [ ] Internal links use Next.js `<Link>`
- [ ] External links have proper `rel` attributes
