Discussion
  • Enterprise SEO

How do you get SEO requirements into a design system so components ship correct by default, and who owns them when they break?

Published 1 reply

Discussion starter: an enterprise SEO question, posted with an answer from Niraj Raut to open the thread. If you have dealt with this on a site, reply with what you saw, especially where it differs.

Disclosure: Niraj Raut, who posted this answer, runs the SEO consultancy linked at the end of it.

1 reply

  • admin
    Admin
    Original poster

    The approach that holds up is to treat SEO requirements the way mature teams already treat accessibility: as part of each component’s contract (the markup it emits for any valid set of props), enforced by types, lint rules and rendered-HTML tests in CI. A checklist that SEO reviews after launch does not survive contact with a busy release schedule. Requirements that fail a build do.

    The important qualification is that a component can only guarantee what it controls. Crawlable links, heading semantics, image attributes and content being present in the DOM belong inside components. Titles, canonicals, robots directives, HTTP status codes, rendering mode and what content goes on the page belong to the template, platform and content layers. Many “the design system broke SEO” incidents turn out to be one of those other layers, or a requirement nobody wrote down. On ownership, the working rule is: SEO owns the requirement and the detection, and the team whose code contains the defect owns the fix.

    Split requirements by the layer that can actually guarantee them

    The first mistake most teams make is writing one long “SEO requirements” document and handing it to the design system team. Half of it is outside their control, so it gets ignored, and then the half they could have owned gets ignored with it.

    Layer What it can guarantee Typical SEO requirements Who fixes it
    Component (design system) The markup emitted for any valid props Navigation renders as <a href>; heading level set independently of visual size; images carry an alt decision and dimensions; tab and accordion content present at load; pagination exposes real URLs; structured data generated from the same props as visible content Design system team
    Template or page composition How components are assembled One primary heading, sensible heading order, internal link modules, breadcrumbs, what is server-rendered Product or feature team that owns the template
    Platform, routing and head Document-level signals Titles, meta robots, canonicals, hreflang, HTTP status codes, rendering mode, HTML weight Platform or web infrastructure team
    Content and CMS What the page says Copy, alt text quality, anchor text, title wording Content owners
    SEO The standard itself Requirement specs, severity definitions, test assertions, monitoring SEO lead

    The component contracts that prevent most regressions

    You do not need SEO rules for every component. A handful of primitives generate most of the damage when they go wrong, and most other components are built from them.

    Link

    Google’s link best practices say: “Generally, Google can only crawl your link if it’s an <a> HTML element (also known as anchor element) with an href attribute.” The same page lists <a routerLink="..."> without an href, <span href="..."> and <a onclick="..."> as formats it cannot reliably parse. The classic design system failure is a clickable Card or a Button that navigates through an onClick handler. Make href a required prop on Link, render a real anchor whenever a component receives an href, and do not let Button navigate. For fully clickable cards, use a real anchor on the card title and stretch its click area with CSS, rather than making a div clickable.

    Heading

    Decouple visual size from semantic level, for example <Heading level={2} size="xl">. When a design system only offers “H1 style” as a component, designers use it wherever they want large text, and pages end up with several H1s and skipped levels. Heading order is a weaker ranking concern than many audits suggest (Google has said multiple H1s are not a problem for Search), but it matters for accessibility and for how clearly the page’s structure reads. Getting it right by default costs nothing.

    Image

    Require an explicit alt decision: either text, or a decorative flag that outputs alt="". Require dimensions or an aspect ratio to prevent layout shift. Default to native lazy loading for below-the-fold images, but let hero and other likely LCP images opt out. Render content images as <img> (inside <picture> if needed), not CSS backgrounds, because Google indexes images from image elements rather than from CSS.

    Disclosure: tabs, accordions, “read more”, load more

    Google’s lazy-loading guidance states that “Google Search does not interact with your page”. Content fetched only when a user clicks a tab is invisible to Google. The contract should be: panel content is in the DOM at render and hidden with CSS or the hidden attribute, never fetched on open. For infinite scroll and “load more”, the same guidance asks for each chunk to have “its own persistent, unique URL” with sequential links between them, so the list component needs a paginated fallback built in.

    Structured data

    Components that display products, breadcrumbs, articles or organisation details should emit JSON-LD from the same props that render the visible content, so markup cannot drift from the page. Two cautions. Do not build components around rich results that no longer exist (FAQ rich results were removed from Search in 2026, although the markup is harmless). And a product component must never emit an Offer without a price, because Google requires a price on every Offer for merchant listing eligibility. For discontinued items, keep the price and use https://schema.org/Discontinued as the availability value.

    Hypothetical example:

    A retailer’s design system ships version 4 of its ProductCard. To enlarge the click target, the team moves navigation onto an onClick on the card’s outer div and drops the inner anchor. Visually nothing changes. Every category page now renders product tiles with no crawlable links, so Google’s discovery of product URLs falls back to sitemaps and whatever other links remain. A rendered-HTML test asserting “ProductCard with an href prop renders exactly one <a href>” would have failed the build before release. Without it, the first signal might be weeks later in crawl stats or the Page indexing report.

    Requirements the design system cannot own, but must not undermine

    Some of the most damaging failures sit at the platform layer and only look like component problems.

    • Error and empty states. A NotFound component rendered inside a page that returns HTTP 200 produces “Soft 404” reports at scale. The component cannot set a status code, so the contract must say that any route rendering it returns 404 from the server. Google’s JavaScript SEO documentation also notes that pages with non-200 status codes might not be rendered, and that a noindex in the original HTML can stop rendering, so removing it later with JavaScript may not work.
    • HTML weight. Google documented in March 2026 that Googlebot fetches only the first 2MB of an HTML file, and bytes beyond that are not processed. Most pages are nowhere near that, but duplicated desktop and mobile navigation, inline SVG sprites and large serialised hydration state can push big category pages closer than anyone expects. An HTML size budget in CI catches this cheaply.
    • Head management. Titles, canonicals and robots directives should come from the routing layer, not from components deep in the tree that can override each other after hydration.

    How to make “correct by default” enforceable

    Types and props

    Required href on Link, required alt decision on Image, required level on Heading. Cheapest enforcement: the code does not compile.

    Lint rules

    Accessibility linters (for example jsx-a11y rules for valid anchors and alt text) catch many SEO issues because the two overlap. Many organisations already fund accessibility governance, especially with the European Accessibility Act applying to many EU consumer services since June 2025, so attach SEO rules to that rather than building a parallel process.

    Rendered-HTML tests

    Render each component story and each template to static HTML in CI and assert: navigation uses anchors with resolvable URLs, tab panels are not empty at load, JSON-LD parses and has required properties, HTML stays under budget.

    Staging crawls and monitoring

    Crawl staging on each release and diff against a baseline (status codes, canonicals, indexable URL count, internal links, heading counts). In production, watch the Page indexing report, “Soft 404” and “Duplicate, Google chose different canonical than user”, and check rendered HTML in URL Inspection for new templates.

    Document each component’s SEO contract next to its accessibility notes in the design system docs: what markup it guarantees, what the consumer must supply, and known misuse. That turns “ask SEO” into a lookup.

    Who owns it when it breaks

    Building codes are a reasonable analogy. The factory builds each power outlet to code, the builder installs outlets in the right places, the utility supplies the right voltage, and the inspector writes and checks the code but does not rewire the house. When an outlet sparks, the first question is whether it left the factory faulty or was wired wrong. In technical terms: separate owning the requirement from owning the fix, and route the fix by where the defect lives.

    Did the component emit wrong markup for valid props?
    ↓
    Yes: design system bug. The design system team fixes it once and the fix propagates to every consumer.
    ↓
    No: was the component used against its documented contract?
    ↓
    Yes: the consuming product team fixes usage. The design system team asks whether the API made misuse too easy.
    ↓
    No: is it a document-level signal (status, canonical, robots, rendering)?
    ↓
    Yes: platform team. No: the requirement was never written or tested, so SEO owns the gap, writes the rule and adds the test before routing the fix.

    Design systems cut both ways. One fix propagates everywhere, and so does one regression. That makes release process as important as ownership:

    Severity Examples Expected response
    Critical noindex or wrong canonicals shipped, navigation links not crawlable, main content missing from rendered HTML, error states returning 200 at scale Block the release or roll back; fix before anything else ships
    High Structured data errors on revenue templates, missing product image alt text, heading regressions across templates Next sprint, owned by the team where the defect lives
    Hygiene Minor heading order issues, decorative images with alt text Backlog

    Label design system changes that alter emitted markup, make SEO a required reviewer only on those, and canary a new design system version on one template before a full upgrade. If SEO has to approve every component change, it becomes a bottleneck and gets bypassed within a quarter.

    If I were starting this tomorrow, I would write contracts and tests for five primitives (Link, Heading, Image, Disclosure, List with pagination) plus three platform assertions (status codes on error states, canonical and robots from the router, HTML size budget). That covers the failures that cost real traffic. The tests should live in the repositories of the teams whose code they test, while SEO owns the specification and the alarm.

    Need help with this on your own site?

    Niraj Raut works with businesses in Nepal, Australia, the UK, Europe and the US on technical SEO, ecommerce SEO, local SEO and AI search.

    See SEO services

Add a reply

Replies are open to approved members. Log in or apply to join.