SEO Meta Tags

Boilerplate and component library for production-ready metadata across three framework targets.

Decision Tree

Determine the correct framework path first:

Static HTML site or any-backend project — Read references/html.md
Next.js 13+ App Router — Read references/nextjs.md
Vite + React — Read references/vite.md, React section
Vite + Vue 3 — Read references/vite.md, Vue section
Multiple frameworks at once — Read all relevant reference files

Then determine action type:

Creating metadata from scratch? — Read matching reference → copy boilerplate → replace placeholders.
Updating existing metadata? — Load file → keep structure → change requested values → verify parity across tag families.
Auditing / reviewing metadata? — Run through Quality Gate below → report issues.
Migrating between frameworks? — Read source reference → read target reference → map fields.

Framework Selection

Framework	When to use	Reference
HTML	Static sites, any backend, SSGs	references/html.md
Next.js	Next.js 13+ App Router projects	references/nextjs.md
Vite	Vite + React or Vite + Vue apps	references/vite.md

Read only the reference file that matches the user's target framework.

Metadata Families

Every framework target must keep parity across these families. When modifying one family, verify the others remain consistent.

1. Essential / Primary

Tag	Constraint
`<title>` / `title`	Under 60 characters
`description`	150-160 characters
`keywords`	5-10 terms max, comma-separated
`author`	Full name
`robots`	`index, follow` by default; include `max-image-preview:large` , `max-snippet:-1` , `max-video-preview:-1`
`canonical`	Absolute URL, must match deployment URL
`viewport`	`width=device-width, initial-scale=1.0`

2. Open Graph (

og:*

)

Property	Notes
`og:type`	`website` for home/landing; `article` for blog posts; `product` for e-commerce
`og:url`	Absolute URL
`og:title`	Can differ from `<title>` for social context
`og:description`	Can differ from meta description
`og:image`	Absolute URL, 1200x630px, JPG or PNG, under 1 MB
`og:image:width` / `og:image:height`	`1200` / `630`
`og:image:alt`	Required when image is present
`og:site_name`	Brand name
`og:locale`	e.g. `en_US`

For

article

type also include:

article:published_time

article:modified_time

article:author

article:tag

3. Twitter Cards (

twitter:*

)

Property	Notes
`twitter:card`	`summary_large_image` (default) or `summary`
`twitter:site`	Organization handle with `@` prefix
`twitter:creator`	Author handle with `@` prefix
`twitter:title`	Under 70 characters
`twitter:description`	Under 200 characters
`twitter:image`	Same spec as OG image
`twitter:image:alt`	Required when image is present

4. Theme Color

Provide three values:

Default:
```
<meta name="theme-color" content="...">
```
or single value
Light:
```
media="(prefers-color-scheme: light)"
```
Dark:
```
media="(prefers-color-scheme: dark)"
```

Next.js uses the

themeColor

array in the Metadata object.

5. Icons and Manifest

Asset	Size	Format
`favicon.ico`	32x32 or multi-size	ICO
`icon-16x16.png`	16x16	PNG
`icon-32x32.png`	32x32	PNG
`apple-touch-icon.png`	180x180	PNG
`site.webmanifest`	n/a	JSON

Generate with favicon.io or RealFaviconGenerator.

6. Structured Data (JSON-LD)

Emit a

<script type="application/ld+json">

block (HTML/Vite) or use a separate Script component in Next.js. Required keys:

json

{
	"@context": "https://schema.org",
	"@type": "WebSite",
	"name": "",
	"description": "",
	"url": "",
	"image": { "@type": "ImageObject", "url": "", "width": 1200, "height": 630 },
	"author": { "@type": "Person", "name": "" },
	"publisher": {
		"@type": "Organization",
		"name": "",
		"logo": { "@type": "ImageObject", "url": "" }
	}
}

Common

@type

values:

WebSite

Article

Organization

Product

FAQPage

BreadcrumbList

7. Internationalization (hreflang)

html

<link rel="alternate" hreflang="en" href="https://example.com/en/" />
<link rel="alternate" hreflang="es" href="https://example.com/es/" />
<link rel="alternate" hreflang="x-default" href="https://example.com/" />

Next.js equivalent:

alternates.languages

in the Metadata object.

8. Performance Hints

Include when external resources are used:

html

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link rel="dns-prefetch" href="https://www.google-analytics.com" />

Placeholder Tokens

All boilerplate files use

{{PLACEHOLDER_NAME}}

tokens. Common tokens:

Token	Purpose
`{{PAGE_TITLE}}`	Page `<title>`
`{{PAGE_DESCRIPTION}}`	Meta description
`{{PAGE_URL}}`	Page URL (absolute)
`{{CANONICAL_URL}}`	Canonical URL
`{{KEYWORDS}}`	Comma-separated keywords
`{{AUTHOR_NAME}}`	Content author
`{{SITE_NAME}}`	Brand / site name
`{{THEME_COLOR}}` / `{{THEME_COLOR_LIGHT}}` / `{{THEME_COLOR_DARK}}`	Hex color codes
`{{OG_TITLE}}` / `{{OG_DESCRIPTION}}` / `{{OG_IMAGE_URL}}` / `{{OG_IMAGE_ALT}}`	Open Graph
`{{TWITTER_TITLE}}` / `{{TWITTER_DESCRIPTION}}` / `{{TWITTER_IMAGE_URL}}` / `{{TWITTER_IMAGE_ALT}}`	Twitter
`{{TWITTER_HANDLE}}` / `{{TWITTER_CREATOR_HANDLE}}`	Twitter handles
`{{SCHEMA_TYPE}}` / `{{SCHEMA_IMAGE_URL}}`	JSON-LD
`{{PUBLISHER_NAME}}` / `{{PUBLISHER_LOGO_URL}}`	Publisher org
`{{FAVICON_32x32_URL}}` / `{{FAVICON_16x16_URL}}` / `{{APPLE_TOUCH_ICON_URL}}`	Icons
`{{AUTHOR_URL}}`	Author website URL (Next.js)
`{{CREATOR_NAME}}`	Content creator name (Next.js)
`{{CATEGORY}}`	Site category (Next.js)
`{{GOOGLE_VERIFICATION_CODE}}` / `{{YANDEX_VERIFICATION_CODE}}` / `{{FACEBOOK_VERIFICATION_CODE}}`	Search engine verification codes (Next.js)
`{{EN_URL}}` / `{{ES_URL}}`	Language-specific alternate URLs (Next.js)
`{{ALTERNATE_EN_URL}}` / `{{ALTERNATE_DEFAULT_URL}}`	hreflang alternate URLs (HTML/Vite)

When implementing for a user, replace every

{{...}}

token. Never leave placeholders in production output.

Quality Gate

Run these checks before considering any metadata task complete:

No placeholders — grep for
```
{{
```
in all modified files; count must be zero.
Absolute URLs — canonical, OG url, OG image, Twitter image, JSON-LD url/image must start with
```
https://
```
.
Image alt text — every
```
og:image
```
/
```
twitter:image
```
must have a corresponding alt field.
No duplicate tags — no two conflicting
```
<title>
```
,
```
description
```
, or
```
canonical
```
tags in the same scope.
Title length — verify under 60 characters.
Description length — verify 150-160 characters.
JSON-LD validity — valid JSON with required
```
@context
```
and
```
@type
```
keys.
OG/Twitter parity — if OG title is set, Twitter title should also be set (and vice versa).
Canonical consistency — canonical URL matches the actual page URL or intended redirect target.
Theme color — includes both light and dark media variants.
hreflang — includes
```
x-default
```
when language alternates exist.
Robots — allows indexing unless user explicitly requests noindex.

Image Specifications

Use case	Dimensions	Ratio	Format	Max size
OG / Twitter	1200x630	1.91:1	JPG or PNG	1 MB
Favicon 32	32x32	1:1	PNG	n/a
Favicon 16	16x16	1:1	PNG	n/a
Apple Touch	180x180	1:1	PNG	n/a

Testing Tools

Recommend to users after deployment:

Common Mistakes

Mistake	Impact	Fix
Relative URLs in `og:image` or `twitter:image`	Social platforms can't fetch the image	Always use absolute URLs starting with `https://`
Missing `<HelmetProvider>` in Vite React	All `<SEO>` tags silently fail to render	Wrap app root in `<HelmetProvider>` in `main.tsx`
Missing `createHead()` in Vite Vue	`useHead()` throws at runtime	Call `app.use(createHead())` in `main.ts`
Committing verification codes to public repos	Exposes site ownership tokens	Use environment variables for `verification` values
Duplicate `<title>` or `description` tags	Crawlers pick an unpredictable one	Use only one source of truth per scope (layout vs. page)
`og:image` set without `og:image:alt`	Accessibility failure, some validators warn	Always pair image with alt text
Using `generateMetadata` for static pages	Unnecessary async overhead on every request	Use static `export const metadata` when values are known at build time
Leaving `{{...}}` placeholder tokens	Broken display on social platforms, poor SEO	Grep for `{{` before shipping
JSON-LD with trailing commas or comments	Invalid JSON, structured data ignored	Validate JSON before finishing
`twitter:card` set to `summary` when image is 1200x630	Image gets cropped to tiny square	Use `summary_large_image` for landscape images

Migration Paths

From	To	Notes
`react-helmet`	Vite React ( `SEO.tsx` )	Replace with `react-helmet-async` ; wrap root in `<HelmetProvider>`
`vue-meta`	Vite Vue ( `SEO.vue` )	Replace `metaInfo` with `@unhead/vue` `useHead()` composable
`next-seo`	Next.js ( `metadata.ts` )	Remove `<NextSeo>` ; use exported `metadata` or `generateMetadata`
Pages Router `<Head>`	App Router	Replace `import Head` with `export const metadata`

seo-meta-tags

NPX Install

Tags

SKILL.md Content

SEO Meta Tags

Decision Tree

Framework Selection

Metadata Families

1. Essential / Primary

2. Open Graph (
`og:*`
)

3. Twitter Cards (
`twitter:*`
)

4. Theme Color

5. Icons and Manifest

6. Structured Data (JSON-LD)

7. Internationalization (hreflang)

8. Performance Hints

Placeholder Tokens

Quality Gate

Image Specifications

Testing Tools

Common Mistakes

Migration Paths

seo-meta-tags

NPX Install

Tags

SKILL.md Content

SEO Meta Tags

Decision Tree

Framework Selection

Metadata Families

1. Essential / Primary

2. Open Graph (og:*)

3. Twitter Cards (twitter:*)

4. Theme Color

5. Icons and Manifest

6. Structured Data (JSON-LD)

7. Internationalization (hreflang)

8. Performance Hints

Placeholder Tokens

Quality Gate

Image Specifications

Testing Tools

Common Mistakes

Migration Paths

2. Open Graph (
`og:*`
)

3. Twitter Cards (
`twitter:*`
)