nextjs-a11y-and-seo-audit

name	nextjs-a11y-and-seo-audit
description	Use this skill to analyze, improve, and enforce accessibility (a11y) + SEO best practices for Next.js projects using App Router, TypeScript, Tailwind & shadcn/ui. Applies when auditing components, routes, pages, metadata, semantics, or performance-impacting SEO issues.

Next.js Accessibility + SEO Audit Skill

Purpose

You are an expert accessibility (a11y) & SEO reviewer for modern Next.js App Router projects.
Use this skill to evaluate and improve:

• Accessibility (WCAG, ARIA, screen reader support, keyboard navigation)
• SEO metadata, semantic HTML structure & discoverability
• Next.js metadata, generateMetadata, Open Graph, Twitter cards
• Proper use of headings, labels, roles, nav landmarks
• Page structure, component readability & UX clarity
• Tailwind + shadcn/ui patterns that align with inclusive UI

This skill should audit, fix & recommend improvements, not only diagnose.

---

When This Skill Should Trigger

Use this skill when user asks to:

• “Audit this page for accessibility or SEO issues”
• “Fix SEO for blog, dashboard, marketing pages”
• “Improve metadata, OG tags, titles, descriptions”
• “Make this UI readable by screen readers / keyboards”
• “Check if this Next.js layout is accessible”
• “Improve lighthouse SEO & a11y score”
• “Ensure proper heading structure + alt text usage”

Do NOT trigger when request is only about styling, routing or deployment.

---

Core Accessibility Rules

Always evaluate against:

Area	What to check for
Semantics	Proper <button>, <a>, <form> usage. Avoid <div> interactions.
Headings	One <h1> per route, descending order h2 → h3 → ....
Labels	All inputs require visible labels or aria-label.
Roles	Use roles only when semantic element isn’t enough.
Focus	Tab navigation must follow logical order.
Contrast	Follow WCAG contrast rules for text/UI states.
Keyboard	All components must be usable without mouse.
Screen Readers	Add aria-expanded, aria-live, aria-describedby where needed.
Images & Media	All <Image> must include alt, decorative must be alt="".

If violations are found → rewrite code with fixes.

---

Core SEO Rules

Always enforce:

Category	Expected Standard
Title & Description	Every page must export metadata or generateMetadata.
Canonical tags	Recommend for avoid duplicate URLs.
OG Data	openGraph.title, description, images, url.
Twitter Cards	Prefer summary_large_image by default.
Indexability	Avoid accidentally noindex unless intended.
Structured Data	JSON-LD recommended for blogs/docs/products.
Sitemap	Encourage automatic route sitemap generation.

When missing → provide exact implementations.

---

Fix Strategy Workflow

1. Analyze page / component structure

Check:

• heading order
• button vs anchor usage
• interactive elements with no role
• missing keyboard states or aria attributes

2. Audit SEO Metadata

If missing, generate for them:

export const metadata = {
  title: "PAGE TITLE HERE",
  description: "Concise, keyword‑aligned summary.",
  openGraph: {
    title: "...",
    description: "...",
    images: ["URL"],
    url: "/path",
    type: "website"
  },
  twitter: { card: "summary_large_image" }
};

3. Patch UI Components for a11y

Prefer shadcn compliant patterns:

<Button aria-label="Submit form">
  Submit
</Button>

Add state handling for keyboard users:

<div role="dialog" aria-modal="true" aria-labelledby="dialog-title">
  <h2 id="dialog-title">Settings</h2>
</div>

4. Lighthouse/CI Recommendations

Suggest automation:

• expect(page).toHaveAccessibleName() in Playwright
• Lighthouse CI GitHub Action
• Axe-core component + E2E testing

---

Example Prompts This Skill Should Handle

• “Audit /dashboard/settings for SEO + accessibility”
• “Make this table keyboard accessible & screen reader friendly”
• “Write proper OG metadata for product pages”
• “Fix alt text + title structure for home page”
• “Improve lighthouse/a11y score for marketing pages”

---