seo-structured-data-audit

name	SEO & Structured Data Audit
description	Comprehensive audit of SEO implementation — sitemap, robots.txt, metadata, JSON-LD structured data, Open Graph tags, canonical URLs, hreflang alternates, and image alt text. Use when asked to audit SEO, structured data, metadata, Open Graph, sitemaps, or search engine optimization.
allowed-tools	Read, Grep, Glob, Bash

SEO & Structured Data Audit

Systematic audit of the SKAPARA storefront SEO implementation: sitemap generation, robots rules, page metadata, JSON-LD schemas, Open Graph/Twitter cards, canonical URLs, hreflang alternates, and image accessibility for search engines.

Prerequisites

Before starting, read these files for architectural context:

• CLAUDE.md — route groups, architecture overview, component standards
• frontend/src/app/[locale]/layout.tsx (lines 18-59) — root layout with metadata, OG, hreflang
• frontend/src/app/sitemap.ts — sitemap generation (67 lines)
• frontend/src/app/robots.ts — robots.txt rules (23 lines)

File Map

Keep this reference open throughout the audit. All paths relative to frontend/src/.

Core SEO Files

File	Role
app/sitemap.ts	Dynamic sitemap generation — 3 locales, daily priority
app/robots.ts	Robots.txt — disallows /api/, /auth/, /checkout/
app/manifest.ts	PWA manifest with icons (47 lines)
app/[locale]/layout.tsx	Root layout — OG image, twitter card, hreflang alternates (lines 18-59)

Metadata Coverage (32/39 pages have generateMetadata)

Status	Pages
HAS metadata	32 pages across all route groups
MISSING metadata	offline, pricing, wishlist (2 pages), editor, auth/callback, notifications

JSON-LD Structured Data

Schema Type	Location
Organization + WebSite	Landing page
Product	Shop, category, product detail pages
BreadcrumbList	Navigation breadcrumbs
BlogPosting	Blog/content pages

Open Graph & Social

Feature	Implementation
OG image	Root layout sets og-image.png 1200x630
Twitter card	twitter:summary_large_image
Canonical URLs	17 pages with explicit canonical
hreflang	alternates.languages for en/es/de + x-default

---

Workflow

Execute each phase sequentially. Record every finding with severity, file path, and line number.

Phase 1: Sitemap & Robots (6 checks)

1.1 Sitemap Completeness

• Read app/sitemap.ts
• Check: Sitemap includes ALL public pages (landing, shop, categories, product details, blog, about, legal)
• Check: Sitemap generates entries for all 3 locales (en, es, de)
• Check: Dynamic product pages are included (fetched from Supabase at build time)
• Check: Priority and changeFrequency values are reasonable (homepage=1.0/daily, products=0.8/weekly, legal=0.3/monthly)
• Check: lastModified uses real dates (product updated_at, not hardcoded)
• Benchmark: Google recommends sitemaps under 50,000 URLs and 50MB uncompressed

1.2 Robots.txt Rules

• Read app/robots.ts
• Check: Disallows sensitive paths: /api/, /auth/, /checkout/, /admin/
• Check: Does NOT disallow public pages (/shop/, /[locale]/, etc.)
• Check: References sitemap URL correctly (absolute URL with domain)
• Check: User-agent is set to * (applies to all crawlers)
• Severity: CRITICAL if /api/ or /auth/ endpoints are crawlable

1.3 Sitemap Discoverability

• Check: Sitemap is referenced in robots.txt
• Check: Sitemap URL is accessible at /sitemap.xml
• Check: Sitemap follows XML schema (xmlns="http://www.sitemaps.org/schemas/sitemap/0.9")

Phase 2: Page Metadata (8 checks)

2.1 Metadata Coverage

• Glob for generateMetadata or metadata exports across all page files in app/[locale]/
• Check: All 39 pages export generateMetadata or a static metadata object
• Check: The 7 MISSING pages are identified: offline, pricing, wishlist (2), editor, auth/callback, notifications
• Severity: FAIL for user-facing pages missing metadata; WARN for internal/utility pages

2.2 Title & Description Quality

• Read metadata from at least 10 representative pages
• Check: Titles are unique per page (not all "SKAPARA")
• Check: Titles are 50-60 characters (Google truncates at ~60)
• Check: Descriptions are 150-160 characters
• Check: Titles include primary keyword + brand name pattern ("Product Name | SKAPARA")
• Check: Dynamic product pages use actual product names in title

2.3 Metadata Translations

• Check: generateMetadata uses getTranslations for localized titles/descriptions
• Check: Metadata is different per locale (not all English)
• Check: Keywords/descriptions are culturally appropriate per locale
• Severity: FAIL if metadata is hardcoded English on localized pages

2.4 Root Layout Metadata

• Read app/[locale]/layout.tsx lines 18-59
• Check: metadataBase is set (required for OG image resolution)
• Check: Default title template includes brand name
• Check: Default description is meaningful
• Check: applicationName is set
• Check: icons are configured (favicon, apple-touch-icon)

Phase 3: Structured Data / JSON-LD (8 checks)

3.1 Organization Schema

• Search for Organization JSON-LD in landing page files
• Check: Schema includes name, url, logo, sameAs (social links)
• Check: logo URL is absolute and accessible
• Check: Validates against Google's Rich Results Test schema
• Benchmark: Google requires Organization for knowledge panel eligibility

3.2 WebSite Schema

• Search for WebSite JSON-LD
• Check: Schema includes name, url, potentialAction (SearchAction)
• Check: SearchAction target URL pattern is correct for site search
• Check: Schema is on the homepage/root layout only (not every page)

3.3 Product Schema

• Search for Product JSON-LD in shop/product pages
• Check: Schema includes required fields: name, description, image, offers
• Check: offers includes price, priceCurrency, availability, url
• Check: priceCurrency matches locale (EUR for all — EU-only store)
• Check: availability uses schema.org values (InStock, OutOfStock, PreOrder)
• Check: image is absolute URL
• Check: brand includes @type: Brand with name: SKAPARA
• Severity: FAIL if Product schema is missing on product detail pages (critical for Google Shopping)

3.4 BreadcrumbList Schema

• Search for BreadcrumbList JSON-LD
• Check: Schema includes correct hierarchy (Home > Category > Product)
• Check: Each item has name and item (URL)
• Check: Position numbering starts at 1 and is sequential

3.5 BlogPosting Schema

• Search for BlogPosting or Article JSON-LD
• Check: Includes headline, datePublished, author, image
• Check: datePublished is ISO 8601 format
• Check: author references Organization or Person

3.6 JSON-LD Injection Method

• Check: JSON-LD is injected via <script type="application/ld+json"> in page components
• Check: JSON is properly escaped (no XSS via product names in JSON-LD)
• Check: Multiple schemas on same page use @graph or separate script tags
• Severity: CRITICAL if user-supplied data in JSON-LD is unescaped

3.7 Structured Data Validation

• Check: No duplicate schemas on same page (e.g., two Product schemas)
• Check: No conflicting data between metadata and JSON-LD (title vs name)
• Check: All URLs in schemas are absolute (not relative paths)

3.8 Missing Schema Opportunities

• Check: FAQ schema on FAQ/help pages (if they exist)
• Check: Review/Rating schema (if product reviews exist)
• Check: CollectionPage schema on category pages
• Benchmark: Competitors with rich results get 20-30% higher CTR

Phase 4: Open Graph & Social (6 checks)

4.1 OG Tags Coverage

• Search for openGraph in metadata exports
• Check: All public pages have og:title, og:description, og:image, og:url, og:type
• Check: og:type is correct per page (website for home, product for product pages, article for blog)
• Check: og:image dimensions are 1200x630 (Facebook recommended)
• Check: og:url matches canonical URL

4.2 Twitter Card Tags

• Search for twitter in metadata exports
• Check: twitter:card is summary_large_image for pages with images
• Check: twitter:title and twitter:description are set
• Check: twitter:image is set and accessible
• Check: twitter:site handle is set (if SKAPARA has Twitter)

4.3 Dynamic OG Images

• Check: Product pages generate dynamic OG images with product photo + branding
• Check: Category pages have category-specific OG images
• Check: Fallback OG image exists for pages without specific images
• Benchmark: Dynamic OG images increase social sharing CTR by 2-3x

4.4 OG Image Accessibility

• Check: OG images are publicly accessible (no auth required)
• Check: OG images load within 2 seconds
• Check: OG image URLs do not contain query parameters that expire (signed URLs)

4.5 Social Preview Testing

• Check: Landing page would render correctly in Facebook/Twitter/LinkedIn card preview
• Check: Product pages would show product image, title, price in social previews
• Check: No truncation of critical information in social cards

4.6 WhatsApp/Telegram Preview

• Check: Pages include og:image for WhatsApp link previews
• Check: og:description is concise enough for messaging app previews (under 100 chars ideal)

Phase 5: Canonical URLs & hreflang (6 checks)

5.1 Canonical URL Coverage

• Search for canonical in metadata exports and layout files
• Check: All pages have canonical URLs (either explicit or via metadataBase)
• Check: Canonical URLs use the preferred domain (with or without www — consistent)
• Check: Canonical URLs include locale prefix (/en/, /es/, /de/)
• Check: No pages have self-referencing canonical loops
• Check: Paginated pages reference the canonical first page (if pagination exists)

5.2 hreflang Implementation

• Read app/[locale]/layout.tsx — alternates.languages section
• Check: Every page has hreflang tags for all 3 locales (en, es, de)
• Check: x-default hreflang points to English version
• Check: hreflang URLs are absolute
• Check: hreflang is reciprocal (en page links to es/de, es page links to en/de, etc.)
• Severity: FAIL if hreflang is missing — causes duplicate content penalties for multilingual sites

5.3 Locale URL Structure

• Check: URL prefix pattern is consistent: /en/shop, /es/shop, /de/shop
• Check: No mixed patterns (some with prefix, some without)
• Check: Default locale (en) still uses prefix (per prefix: 'always' config)

5.4 Redirect Rules

• Read middleware.ts for locale redirects
• Check: Root / redirects to /en/ (or detected locale)
• Check: Missing locale prefix redirects to default locale version
• Check: No redirect chains (A->B->C, should be A->C)
• Check: Redirects use 301 (permanent) not 302 (temporary) for SEO

5.5 Duplicate Content Prevention

• Check: Only one URL resolves to each page (no /shop and /en/shop both working without redirect)
• Check: Trailing slash behavior is consistent (all with or all without)
• Check: Query parameters don't create duplicate pages (sort, filter params)

5.6 Language Selector SEO

• Check: Language switcher links use proper hreflang-compatible URLs
• Check: Language switcher is not JavaScript-only (search engines can discover alternate versions)

Phase 6: Image SEO & Alt Text (5 checks)

6.1 Product Image Alt Text

• Search for <img and <Image tags in product-related components
• Check: All product images have descriptive alt text (product name + color/variant)
• Check: Alt text is NOT just "product image" or empty for meaningful images
• Check: Decorative images use alt="" (empty alt, not missing alt)
• Severity: FAIL if product images lack alt text — impacts Google Image Search ranking

6.2 Next.js Image Optimization

• Search for next/image usage vs raw <img> tags
• Check: Product images use <Image> component (automatic WebP, lazy loading, srcset)
• Check: Image sizes prop is set correctly for responsive images
• Check: priority prop is used for above-the-fold images (LCP optimization)
• Check: No raw <img> tags for content images (only acceptable for SVG icons)

6.3 Image File Names

• Check: Product image URLs contain descriptive slugs (not UUIDs or hashes only)
• Check: Image CDN preserves or rewrites to SEO-friendly filenames
• Benchmark: Google Images uses filename as ranking signal

6.4 Lazy Loading

• Check: Below-the-fold images have loading="lazy" (default in next/image)
• Check: Hero/banner images do NOT have lazy loading (they need priority loading)
• Check: Placeholder blur or skeleton shown during image load

6.5 Image Sitemap

• Check: Product images are included in sitemap (image:image extension)
• Check: Image captions/titles are included where available
• Benchmark: Image sitemap helps Google discover images faster

Phase 7: Technical SEO (5 checks)

7.1 Page Load Performance

• Check: Core Web Vitals friendly: no render-blocking scripts in head
• Check: Critical CSS is inlined or loaded with priority
• Check: Third-party scripts are deferred or loaded async
• Benchmark: LCP < 2.5s, FID < 100ms, CLS < 0.1

7.2 Semantic HTML

• Search for <main>, <nav>, <header>, <footer>, <article>, <section> usage
• Check: Pages use semantic HTML elements (not just div soup)
• Check: Only one <h1> per page
• Check: Heading hierarchy is correct (h1 > h2 > h3, no skipping levels)

7.3 Internal Linking

• Check: Navigation includes links to key category pages
• Check: Product pages link to related products
• Check: Breadcrumbs provide upward navigation links
• Check: Footer contains links to legal/policy pages

7.4 404 & Error Pages

• Check: Custom 404 page exists with helpful navigation
• Check: 404 page returns proper HTTP 404 status code
• Check: Error pages are localized
• Check: Soft 404s are avoided (don't return 200 for missing content)

7.5 URL Structure

• Check: URLs are clean and descriptive (/en/shop/category/product-slug not /en/shop?id=123)
• Check: URLs use hyphens (not underscores)
• Check: URLs are lowercase
• Check: No special characters in URLs (encoded properly if needed)

---

Output Format

Generate AUDIT_SEO_STRUCTURED_DATA_[DATE].md at the workspace root with the following structure:

# SEO & Structured Data Audit — [DATE]

## Executive Summary

[2-3 paragraph overview: overall SEO health, structured data coverage, critical gaps affecting search visibility. State readiness for Google indexing and rich results.]

## Scorecard

| Category | Checks | Pass | Warn | Fail | Critical | Score |
|---|---|---|---|---|---|---|
| Sitemap & Robots | 6 | X | X | X | X | X% |
| Page Metadata | 8 | X | X | X | X | X% |
| Structured Data / JSON-LD | 8 | X | X | X | X | X% |
| Open Graph & Social | 6 | X | X | X | X | X% |
| Canonical URLs & hreflang | 6 | X | X | X | X | X% |
| Image SEO & Alt Text | 5 | X | X | X | X | X% |
| Technical SEO | 5 | X | X | X | X | X% |
| **TOTAL** | **44** | **X** | **X** | **X** | **X** | **X%** |

## Findings

| ID | Severity | Category | Finding | File:Line | Recommendation |
|---|---|---|---|---|---|
| SEO-001 | CRITICAL | Structured Data | [description] | `src/app/[locale]/(app)/shop/[slug]/page.tsx:42` | [fix] |
| SEO-002 | FAIL | Metadata | [description] | `src/app/[locale]/(app)/wishlist/page.tsx:1` | [fix] |
| SEO-003 | WARN | Image SEO | [description] | `src/components/storefront/ProductCard.tsx:88` | [fix] |
| ... | ... | ... | ... | ... | ... |

## Critical Blockers (Must Fix Before Production)

1. [SEO-001] — [description and fix]
2. ...

## High Priority (Fix Within Sprint)

1. [SEO-0XX] — [description]
2. ...

## Warnings (Fix Before V2)

1. [SEO-0XX] — [description]
2. ...

## Priority Actions

1. Add `generateMetadata` to the 7 pages currently missing it
2. [Next highest priority]
3. ...

Severity Levels

• CRITICAL: Missing structured data on product pages (blocks Google Shopping), robots blocking public pages, XSS in JSON-LD, broken canonical causing deindexing. Blocks search visibility.
• FAIL: Missing metadata on user-facing pages, broken hreflang, missing OG tags on shareable pages. Must fix before launch.
• WARN: Suboptimal title length, missing image alt text on non-product images, missing schema opportunities. Fix for V2.
• PASS: Meets SEO best practices and search engine requirements.

Notes

• Always verify findings against actual code (read the file, cite the line number). Never report speculative issues.
• Test JSON-LD by reading the actual script tags rendered in pages, not just the data objects.
• For each CRITICAL or FAIL finding, include a concrete code-level recommendation (not just "fix this").
• Use Google's official documentation as the standard for structured data requirements.
• The 7 pages missing metadata are known — confirm they are still missing and note any that have been fixed.