Reader-First Design Audit

A reusable Codex skill that finds the few typography, structure, and CSS-system problems making interfaces harder to read.

Comment

Inspiration

AI-assisted websites can look polished while quietly making ordinary reading harder. The same patterns recur: nearly all copy is muted, display typefaces are pushed into body and interface roles, headings do not express the actual document structure, responsive layouts fall apart at a breakpoint, and one-off CSS decisions accrete into soup.

Many audits respond with a long conformance checklist or a pile of isolated CSS complaints. I wanted a blunter tool: Can people read and understand this? What are the three changes that matter most? What should be left alone?

What it does

Reader-First Design Audit is a reusable, read-only Codex skill for auditing a public website, a frontend repository, or both.

It examines:

  • orientation, hierarchy, scanning, and comprehension;
  • typography and reading comfort;
  • muted, thin, undersized, or role-inappropriate text;
  • semantic HTML for people, browsers, search and answer engines, and AI tools;
  • tokens, CSS drift, containers, responsive behavior, and interaction state;
  • directly supported accessibility safeguards without pretending to replace specialist assistive-technology testing.

The default report is deliberately compact:

  1. Can people read this? — a blunt verdict;
  2. Fix these first — three actions by reader impact;
  3. Leave this alone — strengths and intentional exceptions;
  4. Can people and machines understand the structure?
  5. Receipts — measurements, source ownership, confidence, and limitations.

The audit is bounded to one deeply inspected route plus up to two propagation checks unless more serious harm requires expansion.

How I built it

I developed the skill iteratively with Codex and GPT-5.6 from recurring problems in my own products and other real interfaces. Codex helped trace visible friction back to shared typography, token, component, container, and semantic causes, then turn those patterns into a reusable Agent Skill.

I forward-tested early versions against AI-assisted sites and repositories, one of my own products, and a mature non-AI control. Those tests changed the skill substantially:

  • a technically careful report was still too long to act on;
  • “WCAG and APCA disagreement” was meaningless without a reader-facing decision;
  • weak borders were being overreported even when the boundary was not necessary;
  • semantics needed their own plain-language section;
  • specialist screen-reader claims were outside the skill’s intended expertise;
  • obvious problems such as muted copy and display-font misuse needed to outrank abstruse details.

A final forward test added explicit scrutiny for small or visually thin Instrument Serif/Sans usage. The fonts are not blacklisted; the skill checks whether a distinctive display choice has been applied beyond the role it can comfortably serve.

Challenges

The hardest part was maintaining discipline. Readability overlaps accessibility, design systems, responsive behavior, semantics, SEO, and content design, but the skill should not become a substitute for every specialist.

The solution was to focus on the shared, high-leverage layer: readable presentation, coherent document structure, native behavior, meaningful machine-readable content, and the few systemic decisions producing most of the friction.

Another challenge was combining human judgment with technical evidence. A conventional contrast ratio can pass while text still feels unnecessarily thin, muted, or tiring. The skill therefore records WCAG and APCA separately, alongside the actual font, size, weight, role, and reading context.

Accomplishments

  • Produces an actionable 80/20 report instead of an exhaustive defect inventory.
  • Preserves intentional design character and explicitly says what not to change.
  • Supports site-only, source-only, and source-plus-site evidence.
  • Separates reader friction, confirmed standards failures, system causes, and recommendations.
  • Treats semantics as useful infrastructure for people and machines without making unsupported ranking or assistive-technology claims.
  • Includes installation, testing, and reviewer guidance in a small reusable repository.
  • Passes Codex’s skill package validator.

How to test it

After repository access is accepted:

git clone git@github.com:mvb-hfn/agent-skills.git
mkdir -p ~/.agents/skills
ln -s "$(pwd)/agent-skills/skills/design-system-audit" ~/.agents/skills/design-system-audit

Start a new Codex task and ask:

Use $design-system-audit to audit this website. Tell me plainly whether people and machines can understand it, what to fix first, and what to leave alone.

Provide a public URL, a local frontend repository, or both. No build step, sample data, account, or production dependency is required.

What I learned

The most useful audit language is not “hierarchy differentiation is insufficient.” It is “everything looks equally important.” Technical rigor matters, but people act on concrete consequences.

I also learned that the best scope is not all of accessibility or all of design systems. It is the important shared layer that a careful generalist can confirm, while clearly handing specialized questions to experts.

What’s next

I plan to keep forward-testing the skill across more frameworks and visual styles, expand its library of evidence-backed typography role checks without creating a font blacklist, and eventually include it in a broader public repository of reusable skills.

Built With

  • agent-skills
  • apca
  • codex
  • github
  • gpt-5.6
  • openai
  • wcag-2.2
Share this project:

Updates