DEV Community: Petri Lahdelma

Why Your Tailwind Project Leaks Spacing (And How to Fix It in 5 Minutes)

Petri Lahdelma — Mon, 13 Apr 2026 10:12:53 +0000

Every Tailwind project starts clean. p-4, gap-2, m-8 — the spacing scale holds.

Then someone writes p-[13px].

Then another dev adds gap-[7px] because "it just looks better." Then a third person commits margin: 15px in a CSS Module because they didn't know about the scale.

Six months later, git grep finds 47 unique spacing values across 200 files. Your 8pt grid is a suggestion, not a rule.

This is spacing drift. It happens in every project that relies on convention instead of enforcement.

The problem with Tailwind's arbitrary values

Tailwind v4 made CSS-first configuration the default. That's great for tokens:

@theme {
  --spacing-1: 4px;
  --spacing-2: 8px;
  --spacing-3: 12px;
  --spacing-4: 16px;
}

But nothing stops a developer from writing p-[13px] in a component. Prettier won't catch it. ESLint won't catch it. TypeScript won't catch it.

Tailwind gives you a scale. It doesn't enforce it.

What Rhythmguard does

Rhythmguard is a Stylelint plugin that enforces your spacing scale and design tokens in both CSS declarations and Tailwind class strings.

Three rules, one purpose:

Rule	What it catches
`use-scale`	`padding: 13px` → "Use 12px or 16px"
`prefer-token`	`gap: 16px` → "Use var(--spacing-4)"
`no-offscale-transform`	`translateY(18px)` → "Use 16px or 24px"

All three autofix. 13px becomes 12px. 16px becomes var(--spacing-4). No manual cleanup.

Setup: 5 minutes for a Next.js + Tailwind project

npm install --save-dev stylelint stylelint-plugin-rhythmguard

.stylelintrc.json:

{
  "extends": ["stylelint-plugin-rhythmguard/configs/react-tailwind"]
}

That's it for CSS files. For Tailwind class strings in JSX/TSX, add the ESLint companion:

eslint.config.js:

import rhythmguard from 'stylelint-plugin-rhythmguard/eslint';

export default [
  {
    plugins: { 'rhythmguard-tailwind': rhythmguard },
    rules: {
      'rhythmguard-tailwind/tailwind-class-use-scale': [
        'error',
        { scale: [0, 4, 8, 12, 16, 24, 32] }
      ],
    },
  },
];

Now p-[13px] in your JSX gets caught and autofixed to p-[12px].

Tailwind v4: Zero-config token governance

If your project uses Tailwind v4 with @theme blocks:

@theme {
  --spacing-4: 16px;
  --spacing-3: 12px;
}

Rhythmguard automatically extracts these as token mappings. When you write padding: 16px, it autofixes to padding: var(--spacing-4). No tokenMap config needed.

Before/after: a real CSS Module

Before:

.card {
  padding: 13px;
  margin-bottom: 7px;
  gap: 15px;
  border-radius: 5px;
}

After autofix:

.card {
  padding: 12px;
  margin-bottom: 8px;
  gap: 16px;
  border-radius: 4px;
}

After token migration:

.card {
  padding: var(--spacing-3);
  margin-bottom: var(--spacing-2);
  gap: var(--spacing-4);
  border-radius: var(--radius-1);
}

Audit before you enforce

Not ready to enforce yet? Run an audit first:

npx rhythmguard audit ./src

Rhythmguard Audit: ./src

Files scanned:     47
Files with issues: 12 (25%)

Off-scale values: 34
  13px       ×8
  7px        ×6
  15px       ×5

Token opportunities: 18
  16px → var(--spacing-4)  ×9
  8px  → var(--spacing-2)  ×5

Paste this in a PR description. Your team lead will understand the problem immediately.

Works with your tools

Rhythmguard supports the token workflows modern teams actually use:

Tailwind v4 @theme — auto-extracted, zero config
Tailwind v3 config — reads theme.spacing from JS config
W3C DTCG tokens — Style Dictionary, Tokens Studio, Figma Variables export
CSS custom properties — var(--space-*) from any source
cn/clsx/cva/twMerge — ESLint rule catches arbitrary values in all utility helpers

Framework configs for React/Next.js, Vue, Lit, Astro, SvelteKit.

Why not just use Prettier / eslint-plugin-tailwindcss?

Prettier orders your classes. It doesn't know if p-[13px] is on your scale.

eslint-plugin-tailwindcss checks class name conventions. It doesn't enforce which values are allowed in arbitrary brackets.

Rhythmguard is the only tool that governs the actual spacing values — in CSS declarations AND in Tailwind class strings.

Get started

npm install --save-dev stylelint stylelint-plugin-rhythmguard
npx rhythmguard init
npx rhythmguard audit ./src

Three commands. Five minutes. Your spacing scale becomes a rule, not a suggestion.

GitHub: stylelint-plugin-rhythmguard
npm: stylelint-plugin-rhythmguard

I Gave My AI Agent a UX Audit Superpower: CLI + MCP in 5 Minutes

Petri Lahdelma — Sat, 11 Apr 2026 18:54:59 +0000

Most AI coding agents can generate a full page of UI in seconds. None of them can tell you whether the result is actually usable.

Missing alt texts. Broken tab order. Contrast ratios that fail WCAG. Focus traps that don't trap. These are the things that ship when accessibility is an afterthought and AI makes it worse because it ships faster.

I built VertaaUX to close that gap. It runs a deep UX and accessibility audit on any URL and returns scored, actionable findings across seven categories: usability, clarity, information architecture, accessibility, conversion, semantic markup, and keyboard navigation.

Today I want to show you two ways to use it: the CLI for your terminal workflow, and the MCP server for AI agents like Claude, Cursor, and Copilot.

The CLI: One Command, Full Audit

Install globally or run with npx:

npx @vertaaux/cli audit https://your-site.com

That's it. You get a scored report in your terminal with severity-ranked findings.

Here's a real run against vertaaux.ai itself:

$ vertaa audit https://vertaaux.ai --mode basic

[21:01:24] Running audit... (1/3) | 0 issues
[21:01:37] Audit Complete  score=72  issues=36  (12s)

Scores
──────────────────────────────────────────────
Overall: 72/100

Category              Score
──────────────────────────────────────────────
clarity               95
semantic              98
keyboard              82
usability             73
ia                    66
conversion            63
accessibility         62

Seven categories, scored in 12 seconds. We eat our own dogfood — and yes, we have work to do on our own accessibility score.

Audit Modes

Three levels of depth depending on your needs:

# Fast broad check
vertaa audit https://your-site.com --mode basic

# Standard analysis (default)
vertaa audit https://your-site.com --mode standard

# Deep WCAG-focused audit
vertaa audit https://your-site.com --mode deep

JSON Output for CI/CD

The --format json flag gives you structured output for piping:

vertaa audit https://your-site.com --format json | jq '.data.scores'

{
  "ia": 66,
  "clarity": 95,
  "keyboard": 82,
  "semantic": 98,
  "usability": 73,
  "conversion": 63,
  "accessibility": 62
}

Drilling Into Findings

Each issue comes with severity, business impact, and a recommended fix:

vertaa audit https://your-site.com --format json | jq '.data.issues[0]'

{
  "title": "Too many navigation links",
  "severity": "warning",
  "description": "Found 17 links in navigation. Consider grouping or reducing to improve scanability.",
  "businessImpact": "Cognitive overload reduces navigation efficiency by 40%",
  "recommendedFix": "<!-- Group into dropdown menus -->...",
  "estimatedEffort": "medium"
}

Not just "this is broken" — but why it matters and how to fix it.

GitHub Actions

Drop this into .github/workflows/a11y-gate.yml:

name: Accessibility Gate

on:
  pull_request:
    branches: [main]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: vertaaux/audit-action@v1
        with:
          url: ${{ vars.STAGING_URL }}
          api-key: ${{ secrets.VERTAAUX_API_KEY }}
          fail-on: critical

PRs with critical accessibility violations don't merge. No manual review needed for the things machines can catch.

The MCP Server: Give Your AI Agent Eyes

The CLI covers your terminal and CI. But what about the AI agents you're already using to write code?

This is where MCP (Model Context Protocol) comes in. MCP lets AI agents call external tools. The VertaaUX MCP server exposes 38 tools that turn any MCP-compatible agent into a UX auditor.

Install

npm install -g @vertaaux/mcp-server

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "vertaaux": {
      "command": "npx",
      "args": ["-y", "@vertaaux/mcp-server"],
      "env": {
        "VERTAAUX_API_KEY": "vx_live_..."
      }
    }
  }
}

Cursor / VS Code

Same config pattern — add the MCP server to your editor's MCP settings.

What Can the Agent Do?

Once connected, your AI agent can:

Audit a URL — "Audit staging.myapp.com and tell me the top 5 issues"
Explain findings — "Why does this contrast ratio fail? Show me the fix"
Generate patches — "Create a PR that fixes the critical accessibility issues"
Compare competitors — "Audit our site and competitor.com side by side"
Track regressions — "Compare this audit to last week's baseline"
Gate deployments — "Does this pass our vertaa.policy.yml?"

The agent doesn't hallucinate these capabilities. It calls real tools with real browser-based analysis.

Real Workflow: Audit → Fix → Verify

Here's what a typical session looks like in Claude Desktop:

You: "Audit staging.myapp.com for accessibility issues"

The agent calls audit_url, waits for the browser-based audit to complete, and returns scored findings.

You: "Fix the critical issues in the signup form"

The agent calls suggest_fix for each finding, generates framework-aware patches (it detects React/Vue/Svelte from your package.json), and shows you the diffs.

You: "Open a draft PR with those fixes"

The agent calls generate_pr, which applies the patches atomically via the Git Trees API. Draft PR — human review before merge.

You: "Verify the fixes landed on staging"

The agent calls verify_fixes against the baseline audit. Fixed issues, still-broken issues, and new regressions — all categorized.

One conversation. No context switching. No separate tooling.

CLI + MCP: Better Together

The CLI and MCP server share the same engine and scoring. Use them together:

Scenario	Surface
Local dev — quick check before pushing	CLI
CI/CD — automated quality gate	CLI + GitHub Action
Code review — "is this accessible?"	MCP in your editor
Bug triage — investigate a reported issue	MCP in Claude Desktop
Competitor analysis — how do we compare?	MCP or CLI
Sprint planning — what's our UX debt?	CLI with `--format json` output

Getting Started

Get an API key at vertaaux.ai/settings/api
Run your first audit: npx @vertaaux/cli audit https://your-site.com
Connect the MCP server to your AI agent of choice
Set up a CI gate to catch regressions automatically

The free tier gives you enough audits to evaluate. Pro unlocks all seven scoring categories and advanced fix generation.

Ready to Take It to the Next Level? Agent Skills.

The CLI and MCP server give your agent the tools. But tools without context produce generic results. What if your agent knew which audit profile to pick, how to interpret the scores, which CI thresholds to set, and how to chain audits into fix plans — without you spelling it out every time?

That's what VertaaUX Agent Skills do. They're published in the open Agent Skills format and work with Claude Code, Cursor, Codex, GitHub Copilot, Gemini CLI, and any host that supports the format.

Install with one command:

npx skills add VertaaUX/agent-skills

Or install just the VertaaUX skill:

npx skills add VertaaUX/agent-skills --skill vertaaux

What the skill gives your agent:

Audit profile selection — built-in profiles like quick-ux, wcag-aa, and ci-gate with a decision tree so the agent picks the right one for the task
Deterministic task recipes — step-by-step sequences for accessibility investigations, competitive reviews, CI setup, and remediation workflows
Guardrails — prevents the agent from hallucinating CLI flags or API parameters that don't exist
Skill composition contracts — explicit handoff conventions so the vertaaux skill chains cleanly into a11y-review, create-analyzer, and architecture-review

The difference: without the skill, your agent runs audit_url and dumps raw findings. With the skill, it picks the right profile, runs the audit, triages by severity, generates a fix plan, and sets up a CI gate — in one conversation.

Browse the skill on Smithery: petri-lahdelma/vertaaux — or just run npx skills add VertaaUX/agent-skills and start auditing.

If you're shipping UI with AI assistance, you need something checking whether that UI actually works for everyone. Lighthouse covers performance. VertaaUX covers the rest.

Links:

The European Accessibility Act Is the New GDPR — And You're Already Late

Petri Lahdelma — Mon, 23 Feb 2026 12:25:20 +0000

The EAA is now law. Fines are rolling in. France sued four retailers. Norway imposed daily penalties on a health app. Here's the 7 violations hiding in your codebase — with code fixes.

In November 2025, two French disability rights organizations filed emergency injunctions against four of France's largest grocery retailers — Auchan, Carrefour, E. Leclerc, and Picard Surgeles. The charge: digital discrimination against 2 million visually impaired people in France who cannot use these retailers' websites and mobile apps to shop independently.

In Norway, the Health Authority imposed compulsory daily fines of 50,000 kroner (~$5,360/day) on HelsaMi, a medical app used by nearly half a million residents, for failing to meet digital accessibility standards.

Sweden's Post and Telecom Agency launched its first regulatory cases targeting e-commerce. The Netherlands warned companies that incomplete compliance reports will trigger priority audits in early 2026. Italy began issuing 90-day remediation notices with fines up to 5% of annual turnover.

The European Accessibility Act is now law. Enforcement has begun. And most organizations are in the denial phase.

If you've been through GDPR, you've seen this movie before.

We've Seen This Movie Before

The GDPR and EAA timelines are almost identical:

Milestone	GDPR	EAA
Adopted	April 2016	June 2019 (Directive 2019/882)
Enforcement date	May 25, 2018	June 28, 2025
Grace period used by most companies	Ignored until ~6 months before	Ignored until ~6 months before
First wave of enforcement	2019 — France fined Google $57M	2025 — France sued 4 retailers
Cumulative fines (first 5 years)	$4.5B+	TBD — but the curve will be identical
Extraterritorial scope	Yes — applies to any org processing EU data	Yes — applies to any org serving EU customers

Here's the number that should concern every executive: 5,100+ digital accessibility lawsuits were filed globally in 2025, a 20% increase over 2024. And that's before EAA enforcement reached full speed.

Companies that waited until GDPR enforcement to begin compliance work spent 3-5x more than those who prepared during the grace period. The same dynamic is unfolding right now with the EAA.

The question isn't whether your organization will need to comply. It's whether you'll do it proactively — or under a court order.

What Executives Miss

If you're forwarding this article to your leadership team, this is the section that matters.

1. It's Extraterritorial

Like GDPR, the EAA applies based on where your customers are, not where your company is headquartered. If you sell digital products or services to anyone in the EU, you must comply. US companies, APAC companies, everyone.

2. The Fines Are Real and Varied

Each EU member state sets its own penalty structure:

Country	Maximum Fine	Notable Details
Germany	$500,000	Per violation
France	$250,000	Plus mandatory public disclosure
Italy	5% of annual turnover	90-day remediation window
Spain	$1,000,000	Graduated severity scale
Ireland	$60,000	Plus up to 18 months imprisonment
Norway	Daily fines ($5,360+/day)	Accumulating until remediation

3. Products Can Be Banned Entirely

This is the one executives don't see coming. Member states can prohibit the distribution of non-compliant products and services on their national market. Not just a fine — a market ban.

4. Daily Penalties Compound Fast

Norway's HelsaMi case is instructive. After the initial compliance order, daily fines of 50,000 kroner began accumulating. That's over $150,000/month of inaction. Multiply this across multiple products and markets, and the exposure grows exponentially.

5. The Risk Exposure Math

Here's a simplified formula every executive should run:

Risk Exposure = Digital Products x Avg Violations x Fine Per Violation

Example (mid-size SaaS):
  3 products (web app, mobile app, customer portal)
  x 15 violations each (average for an unaudited product)
  x $10,000 per violation (conservative EU average)
  = $450,000 minimum exposure

  + daily penalties if not remediated
  + potential market ban
  + reputational damage
  + legal costs

That's the conservative estimate. The real number is usually 3-5x higher.

The 7 Violations Hiding in Your Codebase

Here's where we get technical. These are the most common EAA violations we see in production codebases, along with the exact code to fix them.

Violation 1: Inaccessible Cookie Consent Banner

EAA Requirement: EN 301 549 (WCAG 2.1.1 Keyboard, 4.1.2 Name Role Value)

This one is a double violation — it breaks both the EAA and GDPR simultaneously. An inaccessible consent banner means users with disabilities cannot give or withhold consent. Under GDPR, that means you don't have valid consent for data processing.

Before — the violation:

<!-- No keyboard navigation, no screen reader support -->
<div class="cookie-banner" style="position: fixed; bottom: 0;">
  <p>We use cookies to improve your experience.</p>
  <div class="cookie-buttons">
    <div onclick="acceptCookies()" class="btn-accept">Accept All</div>
    <div onclick="rejectCookies()" class="btn-reject">Reject</div>
  </div>
</div>

After — the fix:

<!-- Keyboard accessible, screen reader announced, focus trapped -->
<dialog
  id="cookie-consent"
  role="alertdialog"
  aria-labelledby="cookie-title"
  aria-describedby="cookie-desc"
  aria-modal="true"
>
  <h2 id="cookie-title">Cookie Preferences</h2>
  <p id="cookie-desc">
    We use cookies to improve your experience.
    You can accept all or reject non-essential cookies.
  </p>
  <div class="cookie-actions">
    <button onclick="rejectCookies()" class="btn-secondary">
      Reject Non-Essential
    </button>
    <button onclick="acceptCookies()" class="btn-primary" autofocus>
      Accept All
    </button>
  </div>
</dialog>

Key changes:

<dialog> element provides native focus trapping and keyboard dismiss (Escape)
role="alertdialog" announces the banner to screen readers on open
<button> instead of <div> gives keyboard access and implicit role
aria-labelledby and aria-describedby provide context
Reject button is equally prominent (GDPR requirement)

Violation 2: Missing Form Labels and Autocomplete

EAA Requirement: EN 301 549 (WCAG 1.3.5 Identify Input Purpose, 3.3.2 Labels or Instructions)

Before — the violation:

// Placeholder-only inputs — invisible to screen readers
function CheckoutForm() {
  return (
    <form>
      <input type="text" placeholder="Full name" />
      <input type="text" placeholder="Email" />
      <input type="text" placeholder="Address" />
      <input type="text" placeholder="City" />
      <span className="error">Please fill in all fields</span>
    </form>
  );
}

After — the fix:

function CheckoutForm() {
  const [errors, setErrors] = useState<Record<string, string>>({});

  return (
    <form noValidate>
      <div className="field">
        <label htmlFor="name">Full name</label>
        <input
          id="name"
          type="text"
          autoComplete="name"
          aria-required="true"
          aria-invalid={!!errors.name}
          aria-describedby={errors.name ? "name-error" : undefined}
        />
        {errors.name && (
          <span id="name-error" role="alert">{errors.name}</span>
        )}
      </div>

      <div className="field">
        <label htmlFor="email">Email address</label>
        <input
          id="email"
          type="email"
          autoComplete="email"
          aria-required="true"
          aria-invalid={!!errors.email}
          aria-describedby={errors.email ? "email-error" : undefined}
        />
        {errors.email && (
          <span id="email-error" role="alert">{errors.email}</span>
        )}
      </div>

      <div className="field">
        <label htmlFor="address">Street address</label>
        <input
          id="address"
          type="text"
          autoComplete="street-address"
          aria-required="true"
        />
      </div>

      <div className="field">
        <label htmlFor="city">City</label>
        <input
          id="city"
          type="text"
          autoComplete="address-level2"
          aria-required="true"
        />
      </div>
    </form>
  );
}

Key changes:

<label> with htmlFor provides persistent, visible labels (placeholders disappear on input)
autoComplete attributes identify input purpose for assistive tech
aria-invalid and aria-describedby connect errors to their fields
role="alert" ensures errors are announced immediately

Violation 3: Insufficient Color Contrast

EAA Requirement: EN 301 549 (WCAG 1.4.3 Contrast Minimum)

The minimum contrast ratios: 4.5:1 for normal text, 3:1 for large text (18px+ or 14px+ bold).

Before — the violation:

/* These all fail WCAG contrast requirements */
.muted-text {
  color: #999999; /* on white: 2.85:1 — FAIL */
}

.placeholder {
  color: #aaaaaa; /* on white: 2.32:1 — FAIL */
}

.button-secondary {
  color: #7c7c7c; /* on #f5f5f5: 2.96:1 — FAIL */
  background: #f5f5f5;
}

.link {
  color: #5b9bd5; /* on white: 3.07:1 — FAIL for normal text */
}

After — the fix:

/* All pass WCAG 1.4.3 contrast requirements */
:root {
  --color-text-muted: #595959;    /* on white: 7.0:1 — PASS AAA */
  --color-text-placeholder: #767676; /* on white: 4.54:1 — PASS AA */
  --color-surface-subtle: #f5f5f5;
  --color-text-on-subtle: #4a4a4a; /* on #f5f5f5: 5.74:1 — PASS AA */
  --color-link: #1a6fb5;           /* on white: 5.08:1 — PASS AA */
}

.muted-text {
  color: var(--color-text-muted);
}

.placeholder {
  color: var(--color-text-placeholder);
}

.button-secondary {
  color: var(--color-text-on-subtle);
  background: var(--color-surface-subtle);
}

.link {
  color: var(--color-link);
}

You can calculate contrast ratios programmatically:

function getContrastRatio(
  rgb1: [number, number, number],
  rgb2: [number, number, number]
): number {
  const luminance = (rgb: [number, number, number]) => {
    const [r, g, b] = rgb.map((c) => {
      const s = c / 255;
      return s <= 0.03928 ? s / 12.92 : Math.pow((s + 0.055) / 1.055, 2.4);
    });
    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
  };

  const l1 = luminance(rgb1);
  const l2 = luminance(rgb2);
  const lighter = Math.max(l1, l2);
  const darker = Math.min(l1, l2);

  return (lighter + 0.05) / (darker + 0.05);
}

// Example usage
const ratio = getContrastRatio([153, 153, 153], [255, 255, 255]);
console.log(ratio); // 2.85 — FAIL

Violation 4: No Focus Management After SPA Route Changes

EAA Requirement: EN 301 549 (WCAG 2.4.3 Focus Order)

Single-page applications (React, Next.js, Vue) don't trigger a full page load on navigation. Without explicit focus management, keyboard and screen reader users get lost after every route change.

Before — the violation:

// Focus stays on the clicked link after navigation
// Screen reader users have no idea the page changed
function App() {
  return (
    <Router>
      <nav>
        <Link to="/dashboard">Dashboard</Link>
        <Link to="/settings">Settings</Link>
      </nav>
      <Routes>
        <Route path="/dashboard" element={<Dashboard />} />
        <Route path="/settings" element={<Settings />} />
      </Routes>
    </Router>
  );
}

After — the fix:

import { useEffect, useRef } from "react";
import { useLocation } from "react-router-dom";

function useRouteAnnouncer() {
  const location = useLocation();
  const mainRef = useRef<HTMLElement>(null);

  useEffect(() => {
    // Move focus to main content on route change
    if (mainRef.current) {
      mainRef.current.focus();
    }

    // Announce the new page to screen readers
    const title = document.title;
    const announcer = document.getElementById("route-announcer");
    if (announcer) {
      announcer.textContent = `Navigated to ${title}`;
    }
  }, [location.pathname]);

  return mainRef;
}

function App() {
  const mainRef = useRouteAnnouncer();

  return (
    <Router>
      {/* Screen reader announcement region */}
      <div
        id="route-announcer"
        role="status"
        aria-live="assertive"
        aria-atomic="true"
        className="sr-only"
      />

      <nav aria-label="Main navigation">
        <Link to="/dashboard">Dashboard</Link>
        <Link to="/settings">Settings</Link>
      </nav>

      <main ref={mainRef} tabIndex={-1}>
        <Routes>
          <Route path="/dashboard" element={<Dashboard />} />
          <Route path="/settings" element={<Settings />} />
        </Routes>
      </main>
    </Router>
  );
}

Key changes:

useRouteAnnouncer hook moves focus to <main> on every route change
aria-live="assertive" region announces the new page title
tabIndex={-1} on <main> makes it focusable without adding to tab order
aria-label on <nav> provides landmark context

Violation 5: Missing Skip Navigation

EAA Requirement: EN 301 549 (WCAG 2.4.1 Bypass Blocks)

Without a skip link, keyboard users must tab through your entire header, navigation, and sidebar on every single page load. On a typical enterprise app, that's 40+ tab stops before reaching the main content.

Before — the violation:

<!-- No way to bypass the navigation -->
<body>
  <header>
    <nav>
      <!-- 25 links in the navigation -->
    </nav>
  </header>
  <aside>
    <!-- 15 links in the sidebar -->
  </aside>
  <main>
    <!-- User must tab 40+ times to reach this -->
  </main>
</body>

After — the fix:

<body>
  <a href="#main-content" class="skip-link">
    Skip to main content
  </a>
  <header>
    <nav aria-label="Main navigation">
      <!-- 25 links -->
    </nav>
  </header>
  <aside aria-label="Sidebar">
    <!-- 15 links -->
  </aside>
  <main id="main-content" tabindex="-1">
    <!-- Immediately accessible via skip link -->
  </main>
</body>

.skip-link {
  position: absolute;
  top: -100%;
  left: 0;
  z-index: 9999;
  padding: 1rem 1.5rem;
  background: #000;
  color: #fff;
  font-weight: 600;
  text-decoration: none;
  transition: top 0.2s;
}

.skip-link:focus-visible {
  top: 0;
}

The skip link is invisible until a keyboard user hits Tab on page load — then it appears at the top of the viewport as the first focusable element.

Violation 6: Images and Icons Without Accessible Names

EAA Requirement: EN 301 549 (WCAG 1.1.1 Non-text Content)

Before — the violation:

// Images with no alt text, icon buttons with no labels
function ProductCard({ product }: { product: Product }) {
  return (
    <div className="card">
      <img src={product.image} />
      <h3>{product.name}</h3>
      <p>{product.price}</p>
      <div className="actions">
        <button onClick={addToCart}>
          <svg viewBox="0 0 24 24">
            <path d="M7 18c-1.1 0-1.99.9-1.99 2S5.9 22 7 22s2-.9 2-2-.9-2-2-2z" />
          </svg>
        </button>
        <button onClick={addToWishlist}>
          <svg viewBox="0 0 24 24">
            <path d="M12 21.35l-1.45-1.32..." />
          </svg>
        </button>
      </div>
    </div>
  );
}

After — the fix:

function ProductCard({ product }: { product: Product }) {
  return (
    <article className="card">
      <img
        src={product.image}
        alt={`${product.name} — ${product.color} variant`}
      />
      <h3>{product.name}</h3>
      <p>{product.price}</p>
      <div className="actions">
        <button onClick={addToCart} aria-label={`Add ${product.name} to cart`}>
          <svg viewBox="0 0 24 24" aria-hidden="true" focusable="false">
            <path d="M7 18c-1.1 0-1.99.9-1.99 2S5.9 22 7 22s2-.9 2-2-.9-2-2-2z" />
          </svg>
        </button>
        <button onClick={addToWishlist} aria-label={`Save ${product.name} to wishlist`}>
          <svg viewBox="0 0 24 24" aria-hidden="true" focusable="false">
            <path d="M12 21.35l-1.45-1.32..." />
          </svg>
        </button>
      </div>
    </article>
  );
}

Key changes:

alt text describes the image content, not just "product image"
aria-label on icon buttons provides context — "Add Nike Air Max to cart" not just "cart"
aria-hidden="true" on SVGs prevents duplicate announcements
<article> instead of <div> provides semantic card structure

Violation 7: Inaccessible Error Messages

EAA Requirement: EN 301 549 (WCAG 4.1.3 Status Messages)

Before — the violation:

// Error appears visually but is never announced
function LoginForm() {
  const [error, setError] = useState("");

  return (
    <form onSubmit={handleSubmit}>
      <input type="email" placeholder="Email" />
      <input type="password" placeholder="Password" />
      {error && <div className="error-text">{error}</div>}
      <button type="submit">Sign in</button>
    </form>
  );
}

After — the fix:

function LoginForm() {
  const [error, setError] = useState("");
  const errorRef = useRef<HTMLDivElement>(null);

  useEffect(() => {
    if (error && errorRef.current) {
      errorRef.current.focus();
    }
  }, [error]);

  return (
    <form onSubmit={handleSubmit} noValidate>
      <div className="field">
        <label htmlFor="login-email">Email address</label>
        <input
          id="login-email"
          type="email"
          autoComplete="email"
          aria-required="true"
        />
      </div>

      <div className="field">
        <label htmlFor="login-password">Password</label>
        <input
          id="login-password"
          type="password"
          autoComplete="current-password"
          aria-required="true"
        />
      </div>

      {/* Live region — announced automatically when content changes */}
      <div
        ref={errorRef}
        role="alert"
        aria-live="assertive"
        tabIndex={-1}
        className={error ? "error-banner" : "sr-only"}
      >
        {error}
      </div>

      <button type="submit">Sign in</button>
    </form>
  );
}

Key changes:

role="alert" with aria-live="assertive" announces errors immediately
Focus moves to the error message so keyboard users know what happened
Persistent <label> elements (not placeholder-only)
autoComplete attributes for password managers

The EAA Compliance Checklist

Use this checklist to assess your current exposure. The severity levels reflect how enforcement agencies are prioritizing audits.

Critical — Blocks Compliance

These are the violations enforcement agencies check first:

[ ] All interactive elements are keyboard accessible (no mouse-only interactions)
[ ] Color contrast meets 4.5:1 for text, 3:1 for large text and UI components
[ ] All form inputs have programmatic labels (not placeholder-only)
[ ] Cookie/consent dialogs are fully keyboard and screen reader accessible
[ ] Content is accessible without relying solely on color to convey information

High — Likely Flagged in Enforcement Audit

These will appear in any formal accessibility audit:

[ ] Focus is managed correctly on SPA route changes
[ ] Skip navigation link is present and functional
[ ] Error messages are announced to assistive technology
[ ] All images have appropriate text alternatives
[ ] Page language is declared (<html lang="...">)
[ ] Heading hierarchy is logical (no skipped levels)

Medium — Best Practice, Reduces Exposure

These demonstrate compliance maturity:

[ ] ARIA landmarks on all pages (<main>, <nav>, <aside>)
[ ] Touch targets are at least 44x44px on mobile
[ ] prefers-reduced-motion media query is respected
[ ] Focus indicators are clearly visible (not just outline: none)
[ ] Content reflows correctly at 400% zoom
[ ] Captions provided for video content

How to Audit Programmatically

You can run a baseline check with axe-core:

import { AxeBuilder } from "@axe-core/playwright";
import { test, expect } from "@playwright/test";

test("homepage has no critical accessibility violations", async ({ page }) => {
  await page.goto("https://your-product.eu");

  const results = await new AxeBuilder({ page })
    .withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"])
    .analyze();

  // Log violations for debugging
  for (const violation of results.violations) {
    console.log(
      `[${violation.impact}] ${violation.id}: ${violation.description}`
    );
    console.log(`  Affected: ${violation.nodes.length} element(s)`);
  }

  expect(
    results.violations.filter((v) => v.impact === "critical")
  ).toHaveLength(0);
});

But remember — axe-core catches 20-35% of WCAG issues. The violations above (cookie banners, SPA focus management, error announcements) often require deeper analysis.

Automate or Drown

The manual approach to EAA compliance looks like this:

Timeline: 2-4 weeks per product
Cost: $15,000-50,000 per audit (external consultancy)
Result: A PDF report that's outdated by the time you read it
Repeat: Every release, every product, every market

For organizations with multiple digital products, this is unsustainable. You're paying for point-in-time snapshots while shipping new violations with every sprint.

The alternative is continuous compliance monitoring. Run audits on every deploy. Catch violations before they reach production. Track compliance trends over time.

# Run a full UX and accessibility audit
npx vertaaux audit https://your-product.eu

Integrate it into your CI/CD pipeline:

# .github/workflows/accessibility.yml
name: EAA Compliance Check

on:
  pull_request:
    branches: [main]

jobs:
  accessibility-audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Start application
        run: npm run build && npm start &

      - name: Run VertaaUX audit
        run: npx vertaaux audit http://localhost:3000
          --format json
          --fail-on critical
          --output audit-results.json

      - name: Upload results
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: accessibility-audit
          path: audit-results.json

This catches violations in pull requests — before they ever reach production, before they ever reach enforcement agencies.

The Bottom Line

The European Accessibility Act is not a future concern. It's current law with active enforcement. France, Norway, Sweden, the Netherlands, and Italy have already taken action. Germany, Spain, and Ireland have penalty frameworks ready.

The companies that treated GDPR as a checkbox exercise — scrambling after enforcement began, paying consultants emergency rates, settling regulatory actions — paid the highest fines and spent the most money.

The EAA enforcement curve will be identical. The only variable is where your organization lands on it.

Start with the 7 violations above. They cover the most common failures we see across production codebases. Fix them, and you've addressed the majority of what enforcement audits are checking today.

Then automate. Because compliance isn't a one-time project — it's an ongoing requirement for every release, every product, and every market you serve.

VertaaUX detects EAA and WCAG violations automatically across your digital products. One URL. One audit. Full compliance visibility. Run your first audit free →

From Template to Tested Product: Launching the LLM Component Schema Standard

Petri Lahdelma — Sun, 22 Feb 2026 02:15:10 +0000

If you lead a design system, frontend platform, or design engineering team and you are trying to make AI-generated UI predictable in production, this is for you.

After a lot of positive feedback on the original LLM Component Schema Template, I expanded it into a fully tested and versioned standard with npm packages, CI enforcement, migration tooling, and release artifacts.

Quick links

Canonical repository: github.com/PetriLahdelma/llm-component-schema-template
Contracts package: npmjs.com/package/@petritapanilahdelma/llm-component-contracts
CLI package: npmjs.com/package/@petritapanilahdelma/llm-component-cli
Agentic design system playbook: WORLD_CLASS_AGENTIC_DESIGN_SYSTEM_PLAYBOOK.md
Claude + Figma Code Connect instructions: CLAUDE_FIGMA_CODE_CONNECT_INSTRUCTIONS.md

The core idea (short version)

Most AI UI output fails because component intent is implicit.

This project makes intent explicit and machine-readable:

Tokens define visual possibilities.
Component schema defines structure, behavior, accessibility, and constraints.
Generative rules define context-aware adaptation.
Storybook + CI + Code Connect enforce contract fidelity in delivery.

That shifts teams from "AI draws screens" to "AI follows a system."

What is now production-grade

This repository is no longer just templates. It now includes:

Reference implementations (examples/) with real components + schema.json pairs.
Golden test corpus (fixtures/) for valid and invalid schema behavior.
Schema drift detection across component props, schema fields, and Storybook args.
Versioned contracts + migration path (v1 -> v2).
Agent eval harness with pass/fail scenarios.
Failing examples library to train quality instincts.
Release automation with immutable artifacts and checksums.
Governance defaults (CODEOWNERS, PR template, schema issue templates).

Screenshots

Canonical repo structure

Tagged release pipeline output

npm packages (contracts + CLI)

Get started in minutes

Install contracts + CLI:

npm install @petritapanilahdelma/llm-component-contracts
npm install -D @petritapanilahdelma/llm-component-cli

Validate a schema, check drift, migrate contract versions, and scaffold a new component starter:

npx llm-component-schema validate examples/base/components/Button/schema.json
npx llm-component-schema drift-check --root . --out dist/schema-drift-report.json
npx llm-component-schema migrate --from v1 --to v2 --input v1.json --output v2.json
npx llm-component-schema init StatusChip --style tailwind --target examples/generated/components

Run the full quality gate locally:

scripts/schema-lint.sh
scripts/run-fixture-tests.sh
scripts/check-schema-drift.sh
scripts/run-agent-evals.sh

Use the contracts directly in code

import { schemas, schemaPaths, migrateV1ToV2 } from "@petritapanilahdelma/llm-component-contracts";

console.log("Current contract:", schemas.contracts.v2.title);
console.log("Base template path:", schemaPaths.templates.base);

const upgraded = migrateV1ToV2({
  version: "v1",
  componentName: "Button",
  props: [{ name: "label", type: "string", required: true }],
  variants: [],
  states: [],
  accessibility: { role: "button", keyboard: [] },
  behaviorRules: [],
  generativeRules: ["Follow design tokens"]
});

console.log("Upgraded version:", upgraded.version);

Example CI check (GitHub Actions)

name: Quality Gates

on:
  pull_request:
  push:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: scripts/schema-lint.sh
      - run: scripts/run-fixture-tests.sh
      - run: scripts/check-schema-drift.sh
      - run: scripts/run-agent-evals.sh

Where Claude + Figma Code Connect fits

The practical production loop:

Define component contract and generative rules.
Implement component + Storybook + schema in one folder.
Attach Code Connect stubs so design and implementation stay aligned.
Use Claude prompts from the playbook to generate/iterate safely.
Gate every change through drift checks + evals before merge.

This prevents "looks right, behaves wrong" output from entering your system.

Why this matters

For teams scaling AI-assisted UI delivery, the hard part is not generation speed. The hard part is contract fidelity across design, code, and runtime behavior.

This project is designed to make that fidelity enforceable.

If your team has drift incidents, inconsistent generated components, or repeated accessibility regressions, this gives you a concrete operating model to stop that at the system level.

What to do next

Clone the repo and run the full quality gates.
Start with one high-volume component (Button, Alert, Input) and model it end-to-end.
Add drift + eval checks as required CI gates.
Adopt versioned contracts and migration policy before broad rollout.

If useful, I can publish a follow-up with a real migration walkthrough (v1 -> v2) and a complete CI/CD setup for multi-package releases.

Enforcing Your Spacing Standards with Rhythmguard (A Custom Stylelint Plugin)

Petri Lahdelma — Tue, 17 Feb 2026 07:38:21 +0000

CSS drift is real.

Even on teams with a spacing scale and token system, random values still creep in:

13px margins
18px translate animations
raw literals where tokens should be used

That drift chips away at consistency and makes UI behavior harder to reason about over time.

I built Rhythmguard to stop that at lint time.

What Rhythmguard enforces

stylelint-plugin-rhythmguard focuses on three rules:

rhythmguard/use-scale

Checks spacing values against your approved scale and can autofix to the nearest allowed value.
rhythmguard/prefer-token

Enforces token usage over raw spacing literals and can autofix with an explicit tokenMap.
rhythmguard/no-offscale-transform

Applies scale rules to translation motion values (translateY, etc.) so motion rhythm stays aligned with layout rhythm.

Install and quick start

npm install --save-dev stylelint stylelint-plugin-rhythmguard

{
  "plugins": ["stylelint-plugin-rhythmguard"],
  "extends": ["stylelint-plugin-rhythmguard/configs/strict"]
}

You also get recommended and tailwind shared configs depending on how aggressively you want to enforce standards.

Why a plugin instead of guidelines

Docs and Figma tokens are necessary, but they’re not enforcement.

What teams actually need is:

fast feedback in CI and local linting
deterministic autofix for migration work
guardrails that encode system rules, not preferences

That’s the gap Rhythmguard fills.

How the rule logic works

At a high level, each rule does this:

Parse declaration values with postcss-value-parser.
Target spacing-sensitive properties (margin, padding, gap, inset, scroll spacing, transform translate functions, etc.).
Normalize units (rem, em, px) to a comparable numeric scale.
Report violations via Stylelint’s reporting API.
Apply a safe fix only when deterministic.

A simplified pattern looks like this:

const stylelint = require("stylelint");
const valueParser = require("postcss-value-parser");

const ruleName = "rhythmguard/use-scale";

module.exports = stylelint.createPlugin(ruleName, (enabled, opts = {}) => {
  return (root, result) => {
    if (!enabled) return;

    root.walkDecls((decl) => {
      if (!isSpacingProperty(decl.prop)) return;

      const ast = valueParser(decl.value);
      walkLengthNodes(ast, (node) => {
        const px = toPx(node.value, opts.baseFontSize ?? 16);
        if (onScale(px, opts.scale)) return;

        stylelint.utils.report({
          ruleName,
          result,
          node: decl,
          message: `Off-scale value "${node.value}"`,
          fix: opts.fixToScale ? () => (node.value = nearestScaleValue(px, opts.scale)) : undefined
        });
      });

      decl.value = ast.toString();
    });
  };
});

The key is the fix strategy: only deterministic fixes. No guessing.

Real example: before and after

In the demo repo, this input is intentionally broken:

.card {
  margin: 13px;
  padding: 18px 22px;
  gap: 12px;
  transform: translateY(18px) scale(1);
}

With scale + token rules and an explicit token map, autofix converges it to consistent, tokenized output.

That gives you two wins at once:

spacing values become scale-safe
literal values migrate toward design tokens

Tailwind note (important)

Rhythmguard enforces what Stylelint can parse: CSS declarations.

It does not lint Tailwind class strings like class="p-[13px] translate-y-[18px]".
For full Tailwind governance, pair Rhythmguard with Tailwind-aware ESLint/class tooling.

Rollout strategy that works

If you’re introducing this to an existing codebase, do it in phases:

Enable rhythmguard/use-scale with autofix.
Add rhythmguard/no-offscale-transform.
Introduce rhythmguard/prefer-token in migration mode.
Lock into strict token enforcement once your token map is complete.

This keeps the migration practical and avoids noisy, non-actionable linting.

Closing

Spacing consistency is one of those things teams care about until deadlines hit.

Rhythmguard turns that concern into enforceable, testable rules so standards survive real delivery pressure.

Sources: