Accessibility is one of those areas everyone agrees matters, but it often gets pushed down the development queue. Alt text is a good example.
Adding descriptive alt text to every image improves accessibility, helps screen-reader users understand a page, and can support SEO. But for sites with hundreds or thousands of images, writing it manually is repetitive and easy to neglect.
That problem led me to build an AI alt text generator for WordPress.
WordPress makes it easy to upload images, but maintaining accurate alt text across a large media library is another story. Site owners usually face one of three situations:
I wanted a tool that could cut that workload while keeping the site owner in control.
The goal isn't to remove human judgment — it's to make the first draft dramatically faster.
The project grew into more than a simple WordPress plugin. The current stack:
The WordPress plugin sends an authenticated generation request to the backend. The backend validates the user, checks available quota, processes the image, stores the usage result, and returns the generated description.
For billing, Stripe webhooks are the authoritative source for subscription status. The frontend never assumes a payment succeeded just because the user returned from checkout. One of the most useful lessons came from telemetry. At one point the analytics showed:
That looked like duplicated completion events. The real issue was that the two metrics measured different things: a generation start could represent one bulk job, while completion events represented each image inside that job. Comparing them directly was like comparing shopping trips with items purchased.
I replaced the ambiguous lifecycle with explicit events:
generation_job_started
generation_item_completed
generation_job_completed
generation_job_failed
Each job now has a generation_run_id
, and each image can have its own generation_item_id
. That makes it possible to answer useful questions:
Clear event semantics turned out to be as important as collecting the events.
Analytics code can fire more often than expected. Events may be duplicated by:
To make events retry-safe, I added stable PostHog $insert_id
values and defined which system owns each event:
This stops the same business action being counted two or three times by different parts of the app.
A single checkout can pass through:
WordPress → Backend API → Render logs → Stripe Checkout → Stripe webhook → Supabase → PostHog
Without a shared identifier, debugging that journey is painful. I introduced:
correlation_id
checkout_attempt_id
generation_run_id
signup_attempt_id
session_id
site_install_id
These let me trace one action from the plugin through the backend and into external services — especially useful when a checkout is abandoned or a login fails. Instead of searching disconnected systems by timestamp, the same correlation value appears throughout the journey.
A generic login_failed
event isn't very useful. It doesn't tell you whether the cause was incorrect credentials, a disabled account, rate limiting, a network timeout, an unavailable API, token-creation failure, or session-storage failure.
I added a controlled internal error taxonomy while keeping public error messages generic — that distinction matters because detailed public messages can reveal whether an account exists. The system now records safe internal codes such as:
invalid_credentials
account_disabled
rate_limited
network_timeout
api_unavailable
token_creation_failed
session_creation_failed
unknown_auth_error
Passwords, tokens, API keys, and raw server responses are stripped before telemetry is sent.
Product analytics can become a privacy problem surprisingly quickly. The telemetry layer now removes fields such as:
PostHog session recording is disabled unless explicitly enabled. The analytics should describe what happened without copying the content the user was working with.
If I started again, I'd define the analytics contract before building the dashboards, documenting each event with: Retrofitting clean telemetry is possible, but it's much more work than designing it properly up front. I'd also add correlation IDs from day one — they're cheap to implement and hugely valuable once an app spans multiple services.
The biggest lesson: building the AI generation feature was only one part of the product. A production-ready plugin also needs:
The AI part may be the headline feature, but reliability is what turns it into a usable product.
I'm also continuing to improve how generated alt text is reviewed and applied within WordPress.
I'd love to hear from other WordPress, accessibility, or SaaS developers: what's been the hardest part of making your plugin production-ready?