SEO & Accessibility Spec

Recommended design seo_accessibility

Agent Prompt Snippet

Ensure the project has an SEO and accessibility specification covering meta tags, semantic markup, WCAG compliance, and performance budgets.

Purpose

An SEO and accessibility specification defines meta tag strategies, semantic markup requirements, WCAG compliance targets, and performance budgets that ensure discoverability and usability for all users.

This is a Recommended document — most projects benefit significantly from having one. While not strictly essential for every situation, its absence often leads to gaps in team understanding or quality.

Key Sections to Include

Meta tags
Semantic markup
WCAG compliance
Performance budgets

Agent hint: Ensure the project has an SEO and accessibility specification covering meta tags, semantic markup, WCAG compliance, and performance budgets.

What Makes It Good vs Bad

A strong version of this document:

Grounded in user research or validated assumptions about user needs
Includes interaction flows, not just static mockups
Specifies responsive behavior, accessibility, and edge states
Defines a consistent design language (typography, spacing, color)
Tested with real users or validated through usability heuristics

Warning signs of a weak version:

Only covers the happy path — no error, empty, or loading states
Pixel-perfect mockups with no guidance on responsive adaptation
Ignores accessibility requirements (color contrast, keyboard navigation, screen readers)
No connection to the design system or component library
Created without understanding technical constraints

Common Mistakes

Designing only for the ideal scenario and ignoring edge cases
Not testing designs with actual users before committing to implementation
Treating accessibility as an afterthought rather than a design constraint
Creating designs that can’t be built within technical constraints

How to Use This Document

Begin with user research or clearly stated assumptions about user needs. Design for the full range of states: empty, loading, error, partial, and success. Specify responsive behavior and ensure all interactive elements are keyboard-accessible. Document the design system tokens (colors, spacing, typography) so implementation is consistent.

For AI agents: Reference design documents when implementing UI components. Verify that implementations match specified states and responsive behaviors. Check accessibility requirements against WCAG 2.1 AA.

Starter Template

SpecBase includes a ready-to-use template for this document: kb/templates/design/seo_accessibility.md.tmpl. Use the SpecBase CLI or MCP integration to generate it pre-filled for your project.

# Generate stubs via CLI
specbase init <archetype> --features <features> --dir ./docs