--- applyTo: "**/*.tsx" --- # SEO & AI Optimization Patterns These rules ensure components are optimized for Google's generative AI features (AI Overviews, AI Mode) and browser-agent interactions: agent-friendly HTML, a clean accessibility tree, semantic structure, and E-E-A-T signals. Pairs with the `ai-seo-optimization` skill and the `audit-ai-seo` prompt. --- ## Semantic HTML (CRITICAL) ### Interactive Elements **NEVER use `
` or `` with click handlers. Use proper semantic elements.** ```tsx // ✅ CORRECT: Semantic button // ✅ CORRECT: Navigation link Go to page // ❌ WRONG: Non-semantic clickable div
Click me
// ❌ WRONG: Span with role hack Click me ``` ### Form Inputs **Every input MUST have an associated label. Placeholder is NOT a substitute.** ```tsx // ✅ CORRECT: Label with htmlFor // ✅ CORRECT: Wrapped label (implicit association) // ❌ WRONG: Placeholder only (invisible to accessibility tree) // ❌ WRONG: aria-label without visible label (poor for agents) ``` ### Heading Hierarchy **Headings must follow logical order. Never skip levels.** ```tsx // ✅ CORRECT: Proper hierarchy

Page Title

Section Title

Subsection

// ❌ WRONG: Skipping h2

Page Title

Subsection

// ❌ WRONG: Using heading for styling only

Small bold text

// Use

with classes instead ``` ### Lists ```tsx // ✅ CORRECT: Semantic list

// ❌ WRONG: Div-based list
{items.map(item =>
{item.name}
)}
``` --- ## Accessibility for AI Agents ### Skip-to-Content Link The root layout MUST include a skip-to-content link as the first focusable element: ```tsx Skip to main content {/* Header/Navigation */}
{children}
``` ### Accessible Names All interactive elements MUST have an accessible name: ```tsx // ✅ CORRECT: Button with text content (name from content) // ✅ CORRECT: Icon button with aria-label // ❌ WRONG: Icon button without accessible name ``` ### Image Alt Text ```tsx // ✅ CORRECT: Descriptive alt text Two-story brick building with a landscaped courtyard entrance // ✅ CORRECT: Decorative image (empty alt) // ❌ WRONG: Generic alt text photo image 1 // ❌ WRONG: Missing alt ``` --- ## Metadata & SEO ### generateMetadata Pattern Every page with dynamic content MUST implement `generateMetadata`: ```tsx export async function generateMetadata({ params }: PageProps): Promise { const { slug } = await params; const data = await getData(slug); if (!data) return {}; return { title: data.title, description: data.description, openGraph: { title: data.title, description: data.description, images: data.image ? [{ url: data.image }] : undefined, }, alternates: { canonical: getCanonicalUrl(slug), }, }; } ``` ### No Snippet Blocking **NEVER add `nosnippet` to content pages.** This prevents AI feature inclusion: ```tsx // ❌ WRONG: Blocks AI features export const metadata = { robots: { index: true, follow: true, nosnippet: true }, }; // ✅ CORRECT: Allow snippets (default behavior) export const metadata = { robots: { index: true, follow: true }, }; ``` --- ## Structured Data (JSON-LD) ### Implementation Pattern Use a dedicated JSON-LD component in layout components: ```tsx export function JsonLd({ data }: { data: Record }) { return (