ReOrient

ReOrient turns UI redesigns into verified release notes for screen-reader and keyboard users.

Comment

Inspiration

The idea started with a mismatch I had taken for granted. When a familiar app is redesigned, I can scan the screen and build a new mental map in seconds. A person who navigates by landmarks, headings, labels, or a remembered sequence of Tab presses may instead discover each change one interaction at a time.

A public discussion by blind users about disruptive layout changes made the problem concrete: familiarity is useful accessibility context, yet release notes rarely explain what moved in terms of the route a returning user already knows. That discussion motivated ReOrient; it does not prove how common the problem is or validate this solution.

I wanted to build the missing release artifact: a trustworthy map from the old interface to the new one, generated before the update ships.

What it does

ReOrient compares two releases of a web interface and explains how its accessible structure changed. It captures landmarks, headings, controls, accessible names, roles, and derived tab order; preserves product identity across the redesign; and emits a stable receipt for each move, rename, role change, reorder, or tab-order change.

Developers can then:

  • replay a familiar keyboard route against the new release;
  • compare declared task flows and cite their first structural divergence;
  • fail CI when a release crosses a breaking-change threshold;
  • publish a before-and-after report for returning users; and
  • expose the same evidence to coding agents through a default-deny MCP server.

GPT-5.6 adds interpretation only after those facts exist. Luna classifies navigation impact, Terra maps old paths to new ones, and Sol writes concise cited guidance. Plain TypeScript checks every receipt reference and quoted control name before the guidance is accepted.

How we built it

I used the Codex CLI throughout. Codex helped turn the initial idea into a working TypeScript and Next.js product, split the engine into five public npm packages, implement security boundaries, investigate failed approaches, write tests, and drive headed Playwright walkthroughs of the finished experience.

The package boundaries mirror how the tool is used. @reorient/browser and @reorient/react let an application declare durable identities without adding wrapper DOM. @reorient/cli captures both releases in headed Chromium. @reorient/core performs matching, diffing, replay, gates, and verification without a browser or model dependency. @reorient/mcp makes those operations available as typed local agent tools.

The model workflow is intentionally narrow. Each GPT-5.6 model receives bounded, delimited evidence for one job, each response is schema-validated, and deterministic code has the final say. The hosted Next.js experience presents the authored storefront, verified report, SDK samples, and local release-workspace concept.

I also used Codex use to direct my demo video!!

Challenges we ran into

The hardest problem was identity. A cart can move to another landmark, change from a link to a button, and jump from tab stop eight to tab stop one while still being the same product concept. A simple DOM or text diff either loses that identity or floods the report with removals and additions. We built a deterministic three-pass matcher and explicit SDK identities so the report keeps one traceable Cart story.

The second challenge was making model output useful without letting polished language outrun the evidence. An early verifier could accept a real receipt id attached to an invented control name. We tightened the boundary so both the citation and the quoted name must come from that receipt, and planted a fabricated “Newsletter signup” claim to prove the rejection path.

Packaging exposed less visible failures: a browser walker worked from source but was missing from a packed CLI tarball, redirect checks had to happen at the request layer rather than only on the starting URL, and React identity boundaries had to follow product concepts instead of component containers. Those fixes became package smoke tests, security tests, and documented Codex decision episodes rather than demo-only patches.

Accomplishments that we're proud of

  • Published five coordinated @reorient packages at 1.0.0: core, browser, React, CLI, and MCP.
  • Delivered a hosted, live product walkthrough at https://reorient-nine.vercel.app/demo/storefront
  • Pushed forward for accessibility tech by open-sourcing ReOrient

What we learned

The biggest lesson was that familiarity itself can be an accessibility asset. Traditional single-page checks matter, but they do not answer the release question: “What route did a returning user learn, and where does that route lead now?”

We also learned that a model is more trustworthy after deterministic work, not instead of it. GPT-5.6 was strongest when each phase had a small job, inspectable receipts, and a code verifier waiting after it. Explicit product identities likewise beat clever DOM guessing: the SDK can state what a concept is while the matcher still provides a useful fallback for uninstrumented pages.

Finally, honest boundaries improved the product. Headed browser automation is not a screen reader, authored fixtures are not user validation, and structural continuity is not WCAG certification. Naming those limits made it clearer what Reorient actually does.

What's next for ReOrient

The next priority is moderated research with screen-reader and keyboard users, including a privacy and consent review, to learn which change notes and route remaps are genuinely useful. That work must happen before making outcome or efficacy claims.

On the product side, the roadmap is durable platform storage and authentication, hosted capture workers, additional framework adapters, and a public change-map format that product teams can publish beside ordinary release notes. We also want to measure whether teams resolve breaking UI before release - not infer disability, frustration, or user intent from telemetry.

Built With

Share this project:

Updates