Posts

Posted on

AI Accessibility: A Practical Framework for Making Software Understandable to AI Agents

As AI agents become part of everyday software development, one problem keeps showing up: every new session starts cold.

\n
\n

The agent does not know the product. It does not know the architecture. It does not know which files matter, which rules are important, or where work should happen. So teams compensate with giant prompts, long chat histories, repeated explanations, and expensive context loading.

\n
\n

That works for a while, but it does not scale.

\n
\n

AI Accessibility is a file-based framework for making an application easier for AI agents to understand, navigate, and work on. Its purpose is simple: give any AI model a reliable operating layer so it can load the right context at the right time without scanning the whole codebase or depending on memory from previous conversations.

\n
\n

The Problem

\n
\n

Most codebases are built for humans first.

\n
\n

Humans learn a project gradually. They ask teammates questions, remember architectural decisions, infer conventions, and build mental models over time. AI agents do not have that continuity by default.

\n
\n

A new AI session often needs to rediscover:

\n
\n

    \n

  • what the product does

    • \n

  • how the frontend is structured

    • \n

  • how the backend works

    • \n

  • where business logic belongs

    • \n

  • what naming conventions are used

    • \n

  • what accessibility rules matter

    • \n

  • how QA should verify changes

    • \n

  • where documentation or release notes should go

    • \n

\n
\n

Without a routing system, the agent either loads too little context and makes bad assumptions, or loads too much context and wastes tokens.

\n
\n

Both are expensive.

\n
\n

What AI Accessibility Means

\n
\n

AI Accessibility is the idea that software should be structured so AI agents can understand and contribute to it efficiently.

\n
\n

It is not the same as writing more documentation.

\n
\n

Traditional documentation explains the application to humans. AI Accessibility routes machine collaborators through the application. It tells the agent:

\n
\n

    \n

  • where to start

    • \n

  • what context to load

    • \n

  • what not to load

    • \n

  • which workflow stage it is in

    • \n

  • what output is expected

    • \n

  • which files own which concerns

    • \n

  • when to stop and ask questions

    • \n

\n
\n

The goal is not to create a huge knowledge base. The goal is to create a lightweight context map.

\n
\n

The Core Principle: Context Routing

\n
\n

The heart of the framework is context routing.

\n
\n

Instead of giving every agent a massive prompt, the repository contains a small routing system:

\n
\n


\nAI entry file
\n  → canonical router
\n    → workflow CONTEXT.md
\n      → shared rules
\n        → targeted source files
\n

\n
\n

For example, a frontend task should not need to read backend migration rules, release note templates, or every product document. It should load only what matters.

\n
\n

This keeps every agent focused and efficient.

\n
\n

How the Framework Is Structured

\n
\n


\n.docs/
\n  AI-ACCESSIBILITY.md
\n  HOW-TO-USE.md
\n
\n  _shared/
\n    product-glossary.md
\n    brand-voice.md
\n    accessibility-rules.md
\n    engineering-principles-frontend.md
\n    engineering-principles-backend.md
\n    ui-patterns.md
\n    naming-conventions.md
\n
\n  01-intake/
\n    CONTEXT.md
\n
\n  02-product-strategy/
\n    CONTEXT.md
\n
\n  03-design-system/
\n    CONTEXT.md
\n
\n  04-frontend-delivery/
\n    CONTEXT.md
\n
\n  04b-backend-delivery/
\n    CONTEXT.md
\n
\n  05-qa-accessibility/
\n    CONTEXT.md
\n
\n  06-docs-comms/
\n    CONTEXT.md
\n
\n  07-agents-automation/
\n    CONTEXT.md
\n

\n
\n

The most important file is AI-ACCESSIBILITY.md. It acts as the canonical router that defines how context is loaded and how work flows through the system.

\n
\n

Tool-specific files like AGENTS.md or CLAUDE.md should remain lightweight and simply point back to this central router.

\n
\n

The Goal

\n
\n

The goal of AI Accessibility is to make AI-assisted development:

\n
\n

    \n

  • faster

    • \n

  • cheaper

    • \n

  • more consistent

    • \n

  • less dependent on chat history

    • \n

  • less prone to hallucination

    • \n

  • easier to resume across sessions

    • \n

  • safer across all parts of the stack

    • \n

\n
\n

A well-designed system should let an agent quickly answer:

\n
\n

    \n

  • What kind of task is this?

    • \n

  • What context do I need?

    • \n

  • What rules apply?

    • \n

  • Where should the work happen?

    • \n

  • What should I produce?

    • \n

  • How should I verify it?

    • \n

\n
\n

Where the Savings Come From

\n
\n

The efficiency gains come from reducing unnecessary context loading and rework.

\n
\n

    \n

  • fewer tokens spent on repeated prompts

    • \n

  • less scanning of irrelevant files

    • \n

  • fewer incorrect implementations

    • \n

  • faster onboarding for new sessions

    • \n

  • more consistent output across models

    • \n

  • better QA handoffs

    • \n

\n
\n

The framework does not eliminate cost. It makes context intentional.

\n
\n

Why This Is Not Overengineering

\n
\n

This system is deliberately simple.

\n
\n

It does not rely on databases, embeddings, or external orchestration tools. It uses plain Markdown files stored alongside the codebase.

\n
\n

Shared rules are centralized, avoiding duplication and keeping the system maintainable.

\n
\n

A Practical Example

\n
\n

Task: Add an empty state to the grocery trip screen.

\n
\n

Instead of scanning the entire codebase, the agent routes the task through:

\n
\n

    \n

  • Frontend delivery

    • \n

  • Design system

    • \n

  • Accessibility rules

    • \n

  • Domain-specific context

    • \n

\n
\n

This focused approach leads to better, more consistent results.

\n
\n

The Bigger Idea

\n
\n

AI Accessibility treats AI agents as real collaborators that need a structured environment.

\n
\n

Just as accessibility improves usability for people, AI Accessibility improves usability for machines.

\n
\n

It reduces ambiguity, enforces consistency, and makes software easier to navigate.

\n
\n

Conclusion

\n
\n

AI Accessibility is a lightweight framework for making applications easier for AI agents to work on.

\n
\n

Its purpose is not to create more documentation, but to route context effectively.

\n
\n

By giving agents a clear map of product, design, engineering, QA, and documentation workflows, teams can reduce costs, improve consistency, and make AI-assisted development more reliable.

\n
\n

The future of AI development will not depend only on better models. It will depend on better-prepared codebases.

\n
\n

AI Accessibility is one way to prepare them.

Posted on

Fighting the Good Fight for Web Page Performance

Banner depicting a loading icon

The front-end world can be riddled with problems that seek out the best in us at times and occasionally bring out maddening frustration. But nonetheless we are expected to prevail even when the increasingly odds grow against us. For a lucky few these challenges become an opportunity to develop a sense of engineering maturity. One such challenge is the ever changing landscape of web page optimization. The challenge is really about solving a cluster of micro-problems, some easily resolvable and others perplexing. And if you are familiar with web page optimization then you are probably aware that the ecosystem has evolved and has become critical to a website’s success. When I first started developing websites I thought my responsibilities ended with HTML, CSS and Javascript. There was occasional talk about performance but no concrete guidelines at the time, then came Google PageSpeed. With the simple action of copy, paste and click you could get a detailed analysis of game changing performance recommendations. To my surprise most of them were way beyond my skill set…at the time. The result was a letter grade which stuck in my mind and developed into an obsession.

Posted on

Optimized, Dynamic Resumes with GTM and Google Analytics

Person typing on laptop

Are you looking for a game plan for your next round in the interview gauntlet? With a little extra work you can get the upper hand by using simple query strings alongside GTM and Google Analytics to see exactly how companies traverse your portfolio/website. You can even tailor the experience to each potential employer so that they feel like they are getting special treatment. Though this tutorial is primarily for front-end developers, it can help anyone looking to get an edge in the marketplace.

A Little Bit About This Tutorial

I try to write concise, coherent tutorials that anyone can understand. Trust me, I may be an engineer but I learned by making a lot of mistakes and pulling out most of my hair. So if I can do it, then you can too. You will need the following online services to complete this tutorial. I encourage you to retrieve the free services I’m about to list out before you start so that you may be able to focus as we go through the steps.

Requirements:
Personal Resume
Personal Website
Google Tag Manager
Google Analytics
Hotjar

Personal Resume: Your resume will be the entry point where all traffic will be funneled through. If you’re a front-end developer then you should have a personal website. Most employers will skim through your skills, work history but a majority of them will click on your website to see what kind of game you have. So make your website link noticeable like you’re trying to capture a lead.

Personal Website: We are going to layout our website similar to a landing page. If you coded your own website then good for the following will be easy. If you created your website via Wix, Squarespace or WordPress then just make sure you have access to the code. Most web services either allow you to insert custom code or add plugins so it shouldn’t be too difficult to install GTM.

Google Tag Manager: GTM is a service from Google that allows you to manage your third-party analytics and pixel tracking from one central location. The benefits are clean separation of third-party tools from your source code, easy enough for a non-coder such as marketer or PPC manager but advanced enough for a hardcore engineer. GTM will open a whole new level of possibilities that are not listed in the documentation. One of which we will be working through in this tutorial.

Google Analytics: You can choose any flavor of data analytics you want but we will be using Google Analytics in this tutorial. You need to be able to set up funnels and goals which most platforms do, possibly event send custom events. Just try to follow along.

Hotjar: This is an awesome tool. Primarily used for recording user session Hotjar also has heatmaps and funnels build in. We only care about the recording of user sessions and the heatmaps. If you find this part a little creepy then feel free not to use this tool. But I will point out that you can suppress some data from being collected. And since we are not working with payments then we are in the clear.

Still with me? Okay, Great! Let’s get started.

 

Posted on

Track Video with GTM

Image of gtm & google analytics with a analytics dashboard

You are only limited by your imagination. Be so very light. Be a gentle whisper. This is truly an almighty mountain.

Trees cover up a multitude of sins. You can do it. Automatically, all of these beautiful, beautiful things will happen. There isn’t a rule. You just practice and find out which way works best for you. Just a little indication.

All you need to paint is a few tools, a little instruction, and a vision in your mind. There are no limits in this world. We’ll paint one happy little tree right here. And I will hypnotize that just a little bit. How do you make a round circle with a square knife? That’s your challenge for the day. Just let this happen. We just let this flow right out of our minds.


    p { color: red }

    .slide-fade-enter-active {
      transition: all .2s ease;
    }

    .slide-fade-leave-active {
      transition: all .2s cubic-bezier(1.0, 0.5, 0.8, 1.0);
    }

    .slide-fade-enter, .slide-fade-leave-active {
      padding-left: 10px;
      opacity: 0;
    }
  

    import { get, call } from 'vuex-pathify'
    import RouteGetters from '@/mixins/RouteGetters'
    import PrismMount from '@/mixins/PrismMount'
    import Jumbotron from '@/views/components/Jumbotron'

    export default {
      mixins: [RouteGetters, PrismMount],
      components: {
        Jumbotron
      },
      head () {
        return {
          title: this.post.title
        }
      },
      computed: {
        post: get('Blog/currentPost')
      },
      methods: {
        fetchPost: call('Blog/fetchPost')
      },
      mounted () {
        let data = {
          id: this.route.params.id,
          params: {
            '_embed': ''
          }
        }

        this.fetchPost(data)
      }
    }

Maybe we got a few little happy bushes here, just covered with snow. Let’s go up in here, and start having some fun Just beat the devil out of it. This is gonna be a happy little seascape. Talk to trees, look at the birds. Whatever it takes. Without washing the brush, I’m gonna go right into some Van Dyke Brown, some Burnt Umber, and a little bit of Sap Green.

Those great big fluffy clouds. Let’s make a happy little mountain now. When you buy that first tube of paint it gives you an artist license. Of course he’s a happy little stone, cause we don’t have any other kind.

Every day I learn. A beautiful little sunset. These trees are so much fun. I get started on them and I have a hard time stopping. This present moment is perfect simply due to the fact you’re experiencing it. Working it up and down, back and forth.

And that’s when it becomes fun – you don’t have to spend your time thinking about what’s happening – you just let it happen. That’s what painting is all about. It should make you feel good when you paint. Everything’s not great in life, but we can still find beauty in it. There he comes. Every time you practice, you learn more.

Posted on

Setting Up Google Tag Manager From Scratch

Google Tag Manager Integration

Google Tag Manager…what is it and why should I use it? Let me ask you a few questions:

Do you use Google Analytics?
Do you use Facebook or Any other Pixel Tracking?
Do you use page optimization tools?

If you answered yes to any of those questions then you have a pretty good basis for using Google Tag Manager