DEV Community: rohit raghuvansh

I Built a Security Scanner for AI Agents in a Weekend. Making It Honest Took a Lot Longer.

rohit raghuvansh — Mon, 20 Jul 2026 05:11:13 +0000

The idea started small enough to fit in a Saturday: I'd built an AI agent, and I had no real way to check whether it was safe to put in front of people. Not "does it work" — I could see that. "Can someone talk it into doing something it shouldn't." That question had no obvious answer, and as far as I could tell, no obvious tool either. So I decided to build a small one for myself.

What that became is AgentGuard — a locally-run testing platform that points a structured battery of attack scenarios at an AI agent and comes back with a plain-language report: a letter grade, findings ranked by severity, evidence, and specific fixes. Think of it as something closer to a virus scanner than a penetration-testing suite — built for the growing number of people assembling agents with no-code and low-code tools who have no security background and no way to check their work before it meets real users.

I'm writing this less as a launch post and more as a record of what the project actually taught me, because the interesting part was never the idea. It was everything the idea ran into once it met real agents.

Engine first, face later

The build order matters here, because it wasn't the order I expected going in. I didn't start with a friendly wizard and bolt a testing engine onto it later. I built the core testing engine and the report generator first — the part that actually runs the attack scenarios and decides what a good and bad outcome looks like — and only once that worked did I build the frontend wizard that makes it approachable for someone who isn't going to read a stack trace.

That ordering turned out to be the right call for a reason I didn't anticipate: the engine is where the real product decisions live. The frontend can be redesigned in an afternoon. The question of what counts as a security failure, and how confident the tool is allowed to sound about it, is much harder to walk back once real users are reading real reports. Getting that right first meant the UX work that came after had something honest to represent.

The scoped, incremental build didn't come from a plan drawn up in advance — it came from testing the engine against my own agent, then a second one, then a third, and each one broke something I hadn't thought about. That's really the shape of this whole story.

Then it broke

The first real test wasn't my own agent. AgentGuard's entire testing approach was built on one quiet assumption: every agent takes free-text chat input, the way a chatbot does. The agent I pointed it at didn't. It had a structured, parameter-based interface — no chat box, no free-text field to inject a prompt into.

The instinct in that moment is to patch around it — special-case this one interface shape, add an if-statement for "when it looks like this, do X." I didn't do that, because the actual problem wasn't the one agent in front of me. It was that the tool didn't know what it was talking to before it started talking to it. So instead of a patch, I built a proper input-discovery layer: a step that inspects an agent's actual interface before any test runs, so the tool understands the real shape of the input space instead of assuming it. That decision cost more time than the patch would have. It's also the reason the tool now works on agents I hadn't specifically built it for.

The bug that looked like a chat box

Not every problem was architectural — some were embarrassingly literal. During one test run, the tool's visibility-detection step found what it decided was a chat box. It wasn't. It was a hidden, unrelated form field, buried somewhere in the page's markup, that had nothing to do with the agent I was trying to test. The tool spent over thirty minutes patiently trying to talk to a piece of dead HTML before it finally gave up and failed.

Thirty minutes of silent, confident wrongness is a bad failure mode for any tool, but it's a particularly bad one for a security product — a tool whose entire premise is "trust what I tell you about your risk." The fix wasn't just tightening the detection logic, though that mattered too. It was making sure that when the tool can't find what it's looking for, it says so immediately and clearly, instead of grinding forward on a bad guess. That same class of failure now surfaces in under a second, with a plain explanation of what wasn't found and why — a worse-sounding result that is, in every way that matters, a better one.

When the tool lied without meaning to

The bug that stuck with me most wasn't visible at all unless you were looking for it. Somewhere in the pipeline, a fallback session identifier — a piece of internal bookkeeping, never meant to be shown to anyone — was, under a specific condition, silently standing in for an actual reply from the agent under test. The tool didn't error out. It didn't flag anything unusual. It took that fallback value, treated it as if it were real content the agent had said, and graded it like a real response.

Nothing about that failure looked like a bug from the outside. The tool ran to completion, produced a report, gave a score. That's exactly what makes it worth writing about: "the tool ran successfully" and "the tool told the truth" are not the same claim, and it is entirely possible to satisfy the first while failing the second. In most software that distinction is an annoyance. In a security tool, whose entire job is telling someone what to trust, it's disqualifying. Finding and closing that gap mattered more to the project than any feature I've added.

The line I decided not to cross

Somewhere in the middle of fixing bugs like that one, I made a deliberate decision to narrow what AgentGuard claims to do. The obvious, more exciting pitch is "test any AI agent." The actual product promises something narrower: test an agent you built or manage.

That's not a limitation I'm apologizing for — it's a boundary I chose on purpose. A tool that runs adversarial attack scenarios against a target has an obvious dual-use problem if it will point at anything with a URL attached. Scoping it to agents you own or manage isn't a technical constraint I ran into; it's a consent and honesty line I drew before anyone asked me to. It's a smaller promise than the one that would sound better in a headline, and I think it's the right one.

What the product actually looks like

Underneath the story, the shape of the product is where a lot of the actual thinking shows up, so it's worth walking through it plainly. Here's the whole path, end to end, before drilling into any one step:

The wizard doesn't open by asking a user to pick a connection protocol. It asks one plain-language question — how do you talk to your agent right now — and offers four everyday answers: a chat box on a webpage, an API endpoint and key, your own code, or just a system prompt with no live agent yet. Each of those maps invisibly to the right underlying testing method. The user never has to know or care which one.

Before any real test runs, there's a fast sanity check — a cheap pre-flight step that catches an unreachable or misconfigured target in seconds. Nothing is worse than watching a full test suite grind for minutes against a target that was never going to respond, so the tool fails fast and says why, before it ever gets to the expensive part.

Once a target passes that check, the tool runs its introspection step and shows the user, in plain language, what it actually found — the agent's real inputs, and any gap between what a webpage's interface suggests you can send it and what its underlying API will actually accept. That gap is exactly what broke the tool's first assumption, and it's now a first-class thing the user gets to see, not just something the tool quietly works around.

After that comes a short, optional, bounded interview: a handful of plain questions about what a bad outcome would actually look like for this specific agent, used to sharpen judgment on ambiguous results later. It's deliberately small and fixed in scope — a few questions, not an open-ended interrogation — because the goal is better context, not a second onboarding flow.

Every agent tested lands in a running dashboard, too, so nothing disappears once its report closes — a plain history of what's been scanned, how it scored, and what's still failing:

The test run itself produces the report: an overall grade with an honest explanation of how it was computed, findings grouped by severity with real evidence and specific suggested fixes, and — given equal visual weight, not buried at the bottom — a section describing what couldn't be tested and why. Treating "we don't know" as a legitimate, clearly labeled product state instead of hiding it behind a falsely clean score was one of the harder UX calls in the whole build, and it's the one I'd defend most.

Under the hood, that whole experience is four components doing distinct jobs: the input-discovery layer figures out what the target actually looks like, the test engine runs the attack battery against it, an AI judge grades each reply against what that scenario is checking for, and the report generator turns verdicts into something a person can act on. Nothing in the report is inferred — every claim traces back to a real exchange with the target agent.

Zoomed in further, here's what actually happens for a single attack scenario, from submission to a graded finding — including the fail-fast sanity check and the loop that repeats per scenario:

What this actually demonstrates

I'm naming this directly because the point of writing it down is to make the skills legible, not just hope they show through.

AI product development. Most of this was built working with AI coding tools as a genuine engineering partner rather than a code-generation shortcut — writing precise, scoped fix requests instead of vague ones, insisting on verification with real numbers instead of accepting "looks good" as an answer, catching regressions before they shipped, and knowing when a spec's literal wording should bend to a better real-world answer (the input-discovery layer over the one-off patch is the clearest example of that judgment call).

UX and product thinking. Recognizing when a technically correct feature still confuses a non-technical user, and redesigning around plain language and honest partial answers instead of false confidence — the "what we couldn't test" section is the clearest artifact of that instinct, and so is the decision to narrow the product's own promise rather than oversell it.

Information architecture. The actual shape of the product — one plain-language entry question standing in for four technical connection methods, a cheap pre-flight check ahead of an expensive test run, an introspection step that surfaces gaps instead of hiding them, a small bounded interview instead of an open one, and a report that treats uncertainty as a designed state — is itself the evidence. None of that shape was accidental, and all of it came from watching real agents break real assumptions.

Where it actually stands

The core engine, the report generator, and the frontend wizard are built and working end to end. The last stretch of work has been less about adding features and more about making the tool honest and adaptable: fixing the class of bug where it could silently misreport a result, building the input-discovery layer described above, and adding a first mechanical check for whether an agent's API actually enforces the same limits its interface shows a user.

There's more ahead of it, plainly: deeper adversarial testing of an agent's actual input parameters, and a way to check scan results from another device on the same network. This is a real, evolving project, not a finished showcase — and I think that's worth saying outright rather than dressing it up as more complete than it is. If nothing else, this project taught me that the honesty in the tool's own reports had to start with the honesty in how I describe it.

👨‍💻 Connect With Me

Rohit Raghuvansh
💡 UX Thinker · AI Builder · Making complex tech human-centered

Connect & Follow

LinkedIn — Rohit Raghuvansh

📢 Found This Article Helpful?

If this article added value to your learning journey:

✅ Share it with your network ✅ Bookmark it for future reference ✅ Follow for more

Keep Learning. Keep Building. Keep Growing. 🚀

Information Architecture for AI Chatbots: Why Your Bot Needs a Sitemap

rohit raghuvansh — Mon, 20 Jul 2026 04:26:17 +0000

Ask a UX team to show you the sitemap for their website and they'll pull it up in seconds. Ask the same team to show you the "map" of their chatbot and you'll get a shrug, a Notion doc with forty half-finished intents, or a shrug followed by "the model just figures it out." That gap is why so many chatbots feel lost: nobody drew the floor plan before construction started.

Information architecture used to mean organizing pages, labels, and navigation so people could find things on a site. Conversational products need the same discipline, just applied to a structure you can't see: intents, turns, and context. Skip it and you get a bot that answers the first question well and falls apart by the third.

Your Chatbot Already Has an IA, It's Just Invisible

Every chatbot has an implicit architecture whether anyone designed it or not. There's a set of things the bot can do, a way it decides which thing you're asking for, and a path it follows once it's decided. On a website, that structure is a sitemap and a nav bar. In a chatbot, it's an intent taxonomy and a dialogue manager, and if nobody drew it out, the model is improvising it from training data and prompt scaffolding.

That improvisation is where trouble starts. Research on conversational product evaluation points to four things that separate a bot people trust from one they abandon: whether it's clear what the bot can actually do (capability transparency), what happens when it gets something wrong (recovery patterns), how confident it seems about its own answers, and whether the whole thing works for people using assistive tech. Three of those four are architecture problems, not model problems. You can have the best language model available and still fail all three if nobody designed the structure underneath it.

The fix isn't exotic. It's the same exercise IA practitioners already know: card-sort the things users actually come to your bot for, group them into a hierarchy, and write down the paths between groups. The difference is that instead of a sitemap with pages, you end up with a taxonomy of intents and the transitions allowed between them.

Intent Taxonomies Are Sitemaps for Conversation

An intent taxonomy is the closest thing conversational design has to a sitemap, and it deserves the same rigor. Microsoft's approach with Copilot Chat is a useful reference: they built a two-level hierarchy, with top-level categories and sub-intents underneath, and populated it two ways at once. Bottom-up, by mining real conversation logs to see what people actually asked for. Top-down, by having product teams curate the categories that mattered for the business. Neither approach alone was enough. Pure bottom-up taxonomies mirror what happened, not what should happen. Pure top-down taxonomies miss the weird, real ways people phrase requests.

The most common failure at this layer isn't a missing intent, it's overlap. When two categories share vocabulary and the boundary between them isn't crisp, classification accuracy is capped no matter how good the underlying model is. "Cancel my order" and "return my order" sound almost identical to a classifier if your taxonomy doesn't force a clean split with clear business rules behind it. This is pure IA work: same discipline as untangling two nav categories that both claim "Resources."

Treat the taxonomy as a living document, not a one-time deliverable. Review transcripts monthly, look for questions the bot mis-routed, and check whether new intents are forming that don't fit anywhere. A taxonomy that hasn't changed in six months isn't stable, it's stale.

The Context Window Is Not the Same as Memory

This is where most teams get the mental model wrong, and it costs them. A context window is not memory. It's short-term working space, and it has a hard limit. Memory, if your product has it, is a separate system that decides what gets pulled back into that window later. Conflating the two is how you end up with a bot that "forgot" something it technically still has stored somewhere, just not where it can currently see it.

Good conversational IA treats the context window like prime real estate on a homepage: valuable, limited, and worth fighting over. Every turn, something has to earn its place in that window. Some information belongs there for the whole session, like the user's stated goal or account context. Some belongs there for a turn or two and then should get summarized down to a line instead of carried verbatim. Some should be dropped entirely once it's served its purpose. Deciding which is which, turn by turn, is an architecture decision, and right now most teams are letting it happen by default rather than by design.

The payoff for getting this right is measurable. Systems that maintain contextual memory well see meaningfully better accuracy and user satisfaction compared to stateless ones, because the bot stops asking users to repeat themselves. The payoff for getting it wrong shows up just as clearly: a large share of users report that their chatbot fails to understand intent or resolve their issue at all, and a big chunk of that traces back to the bot losing the thread mid-conversation rather than failing to understand a single message in isolation.

Wayfinding When the User Gets Lost

Websites have breadcrumbs, back buttons, and search bars for the moment someone takes a wrong turn. Chatbots need the conversational equivalent, and most don't have one. When a user asks something the bot can't confidently classify, what happens next is entirely an IA decision: does it guess, does it ask a clarifying question, does it offer a menu of likely intents, or does it hand off to a human?

Well-designed recovery loops give the user a way out that doesn't require starting over. That might mean quick-reply buttons that let someone pivot without retyping their whole question, a citation that lets them verify a factual claim themselves, or a clean handoff to a person that carries the conversation context along instead of dropping it at the door. The interfaces that handle this best don't rely on chat alone. They blend free text with structured elements like buttons and cards, so users can choose whichever is faster for them in the moment. That's a hybrid UI decision, and it belongs in the same architecture conversation as the taxonomy and the context strategy, not bolted on afterward.

The cost of skipping this is steep and well documented: a majority of users abandon a chatbot interaction after getting stuck in a loop, and roughly half walk away entirely after a single bad experience. Those aren't model failures. They're the conversational equivalent of a 404 page with no search bar and no way back to the homepage.

Draw the Map Before You Build the Bot

None of this requires new tools. It requires treating a chatbot the way you'd treat any other product with a structure users need to navigate: map the intents, decide what belongs in working memory versus long-term memory, and design the recovery paths before launch instead of patching them in after support tickets pile up. The model handles language. The architecture is still your job.

👨‍💻 Connect With Me

Rohit Raghuvansh
💡 UX Thinker · AI Builder · Making complex tech human-centered

Connect & Follow

LinkedIn — Rohit Raghuvansh

📢 Found This Article Helpful?

If this article added value to your learning journey:

✅ Share it with your network ✅ Bookmark it for future reference ✅ Follow for more

Keep Learning. Keep Building. Keep Growing. 🚀

Design Tokens in 2026: Figma Variables vs Tokens Studio

rohit raghuvansh — Thu, 16 Jul 2026 04:18:15 +0000

Design token adoption jumped from 56% of product teams to 84% in a single year. That is not a slow trend, that is a stampede. And it landed right as the W3C shipped the first stable version of the Design Tokens Format Module, backed by Adobe, Google, Meta, Figma, Salesforce, and Shopify. For years, two camps fought over how tokens should actually work. That fight just got a lot less interesting, and the reason why is worth understanding before your team picks a side out of habit.

Here is the tension. Camp one says: keep it native, keep it simple, let Figma Variables own the source of truth. Camp two says: Figma Variables alone can't handle real complexity, bring in Tokens Studio and a proper build pipeline. Both camps have shipped production design systems. Both camps have also watched their approach buckle under specific conditions. Let's look at what each one actually gets right, then settle it.

Camp One: Figma Variables, the native path

Figma Variables shipped in 2023 and mostly replaced Styles as the way teams store colors, spacing, and type values. The pitch is obvious: no plugin to install, no second tool to keep in sync, designers work in one file and the values live right there next to the components.

The 2026 upgrade changes the calculus. Figma now exports Variables as DTCG-compliant JSON with no plugins or custom export scripts required. That matters because DTCG (the Design Tokens Community Group format) gives every token a $value and a $type, a shape that Style Dictionary, Theo, Specify, Supernova, and Penpot all already read. Native Figma tokens are no longer a walled garden. They come out the other side in a format the rest of your toolchain understands.

Where native still struggles: multi-mode theming at scale. Variables handle light and dark mode fine. Once you're juggling eight brands, three densities, and platform-specific overrides, the flat mode system starts fighting you.

Camp two: Tokens Studio, the power path

Tokens Studio treats tokens as a multi-file system with direct git sync, which is exactly what Camp One's native approach lacks once things get complicated. A design system with real theming needs, multiple brands, multiple platforms, needs the extra structure: token sets that compose, aliasing across files, and a direct pipe into your repo instead of a manual export step.

The catch is Tokens Studio's format predates DTCG, so bridging to Style Dictionary means running @tokens-studio/sd-transforms first. That's one more dependency, one more thing that can drift out of version sync. It is a real cost, just a smaller one than it used to be, because the underlying token shapes are converging anyway.

There's a genuine case study here worth sitting with: one team built a unified design system in 1.5 months to support eight distinct brands migrating onto a shared platform, using Figma variables for brand-level theming without duplicating a single component. That is the kind of complexity where Camp Two's extra tooling investment pays for itself immediately, and where Camp One's simplicity starts to strain.

What actually changed in 2026

The real story isn't Figma versus Tokens Studio. It's that the fight over format is over. Before the DTCG spec stabilized in October 2025, every tool had its own JSON shape, and picking a token tool meant picking a lock-in. Now there's one shape, $value and $type everywhere, and both camps export into it.

That single change is why a rebrand that used to take weeks can now push through core UI in two days with full rollout in three. When your color, spacing, and typography decisions live as data instead of scattered hex codes in fifty component files, a brand refresh becomes a find-and-replace on a token file, not a design QA marathon.

Salesforce coined the term "design token" back in 2014 through the Lightning Design System, specifically to solve visual consistency without relying on documentation nobody reads. Twelve years later, the industry finally has a shared format to make that promise actually portable across tools, not just within one company's walls.

Tokens as the source AI agents read too

There's a fourth party at the table now that neither camp fully accounted for: AI coding agents. When you ask an agent to build a settings page or a new component, it needs to know your brand's exact blue, not a plausible-looking blue. A structured token file gives it that. This is why a pattern called DESIGN.md is spreading fast: a single markdown file with token values as YAML front matter and design rationale in prose underneath, referenced from a project's AGENTS.md alongside the other instruction files an agent reads first.

The tokens give an agent the right values. The prose gives it judgment for decisions the tokens didn't anticipate, like what to do when a new component needs a state color nobody defined yet. Teams skipping this step are the ones complaining about "AI slop" in generated interfaces. Teams that dropped a DTCG export and a one-page DESIGN.md into their repo are not having that problem nearly as often.

Underneath both camps, the actual architecture that makes any of this work is a three-tier hierarchy: core tokens (raw values like blue.500), semantic tokens (color.brand.primary) that point at core values, and component tokens (button.background) that point at semantic ones. Change a brand color once at the semantic layer and it cascades everywhere it's referenced, without touching a single component file.

The verdict

Pick native Figma Variables plus a DTCG export into Style Dictionary if you're a single brand, a handful of platforms, and a team that wants one less tool to maintain. That setup covers most teams honestly, and it just got dramatically more capable with zero extra plugin cost.

Pick Tokens Studio if you're managing multiple brands, complex theming, or you already have a mature git-synced pipeline that a switch would only disrupt. The extra transform step is a small tax against the alternative of rebuilding your whole theming system in a tool that isn't built for it yet.

What you should not do is pick based on which one your last job used. The format war that used to make this choice permanent is over. Both paths now speak the same JSON. Choose based on your actual theming complexity today, not tribal loyalty to a tool you learned two years ago.

👨‍💻 Connect With Me

Rohit Raghuvansh
💡 UX Thinker · AI Builder · Making complex tech human-centered

Connect & Follow

LinkedIn — Rohit Raghuvansh

📢 Found This Article Helpful?

If this article added value to your learning journey:

✅ Share it with your network ✅ Bookmark it for future reference ✅ Follow for more

Keep Learning. Keep Building. Keep Growing. 🚀

Accessibility in AI Interfaces: What Most Builders Miss

rohit raghuvansh — Tue, 14 Jul 2026 04:38:30 +0000

Most teams think they've handled accessibility once someone adds aria-live to the chat window and closes the ticket. I've watched this happen on three separate AI products now. The screen reader demo works in the sprint review. Then a real blind user opens the product three weeks later and can't tell if the assistant answered at all.

That gap between "we tested it" and "it works" is the whole story of accessibility in AI interfaces right now. Builders are shipping conversational UI faster than they're shipping the plumbing that makes it legible to assistive technology, and the checkbox mentality is making it worse, not better.

The checkbox that doesn't check anything

Here's the belief that's costing teams the most: that screen reader support is a line item you can bolt on after the interface is built. It isn't. A live region only works if the container announcing new content is present in the DOM before the update happens, if the urgency level matches the content, and if the message itself is short enough to be useful when read aloud mid-conversation.

Most AI chat widgets fail at least one of those three. Message containers often lack ARIA live regions entirely, so screen readers announce nothing when the assistant responds, even though the text is fully visible on screen. The response exists. The user just doesn't know it happened.

This isn't a hypothetical gap. Across the top million homepages, the vast majority still carry detectable WCAG 2.2 failures, and automated scanners, the tools most teams lean on to feel compliant, only catch a slice of the real problems. Screen reader compatibility, cognitive load, and complex interactive components need a human tester with a screen reader, not a lint rule.

Streaming broke the one thing that used to work

Static text was never the hard problem. Screen readers have handled static pages fine for two decades. What's new, and what most teams haven't adjusted for, is token-by-token streaming: the thing every AI product does now to feel responsive.

Streaming is a screen reader's worst case. NVDA and JAWS are built to read stable content, not text that's rewriting itself multiple times a second. When a response streams in, screen readers can mispronounce partial tokens, freeze mid-read, or stop responding to the user's commands entirely until the stream finishes. There's an open GitHub issue on Claude Code asking for a dedicated screen-reader mode specifically because NVDA locks up during token streaming, forcing users to restart their screen reader mid-session just to regain control.

Notice who found the workaround. Not the vendor. A developer built claude-a11y, a browser extension and CLI wrapper that reformats AI chat output into something a screen reader can actually parse, layered on top of tools that shipped without that consideration built in. Blind engineers are patching accessibility gaps in AI products faster than the companies that own those gaps are fixing them. That's not a compliment to the ecosystem. It's an indictment of it.

Agentic UI adds a layer nobody accounted for

It gets worse once the product isn't just chatting, it's reasoning. Agentic interfaces show their work now: a "thinking" indicator, a tool call, a status line that says it's searching, then reading, then writing. Sighted users get a lightweight animation they can glance at and ignore. Screen reader users get every one of those transient states read aloud, in sequence, competing for the same live region as the actual answer.

That's a cognitive load problem most teams never budget for. A blind user trying to follow a multi-step agent has to track state changes that a sighted user processes peripherally in half a second. If every intermediate step fires an announcement, the meaningful content, the actual answer, gets buried under process narration. If nothing announces, the user has no idea whether the agent is still working or has silently failed. Neither default is acceptable, and I haven't seen a mainstream agentic product pick a deliberate middle ground yet.

The fix here isn't exotic engineering. It's editorial judgment applied to live regions: decide which state changes matter enough to announce, suppress the rest, and give users a way to check status on demand instead of narrating every micro-step at them. Nobody's shipping this because it requires someone to actually sit down and decide what's worth saying out loud, which is slower than just wiring up aria-live and calling the ticket done.

What screen readers actually hear

Set streaming aside for a second. Even a fully rendered, static AI response usually fails on structure. Screen readers don't read pixels, they read the DOM: headings, lists, landmarks, labeled buttons. That's how a blind user skips to the third point in a numbered list instead of listening to the whole response top to bottom.

Generated AI content routinely skips all of it. No heading tags to distinguish a section title from a sentence. No list semantics around what's visually a bulleted list. No labels on the buttons rendered inline in a response. What a sighted user sees as a clean, skimmable answer, a screen reader user hears as one unbroken wall of text, no way to tell where an idea starts or a new one begins.

Six recurring problems account for the overwhelming majority of detected accessibility errors industry-wide: low contrast, missing alt text, empty links, unlabeled inputs, missing buttons, missing language tags. None of these are exotic. They're the basics, and AI-generated interfaces are reproducing them at scale because the models generating the markup were never scored against whether a screen reader could parse the output.

The fix nobody wants to build

WCAG 2.2's Success Criterion 4.1.3, Status Messages, already covers exactly this case: users need to be informed when content updates without their focus moving to it. That's precisely what happens every time an AI assistant finishes a response while the user's focus sits in the input box. The standard isn't missing. The implementation discipline is.

Fixing this for real means a few unglamorous things. Message containers need aria-live="polite" present in the DOM from page load, not injected after the fact. Streaming needs a throttled or chunked announcement strategy instead of firing an update on every token. Generated responses need semantic structure, actual heading and list tags, not visual formatting that only sighted users benefit from. And someone with a real screen reader needs to sit with the product before launch, because automated tools are only catching a fraction of what's actually broken.

There's also a widening legal backdrop pushing this from "nice to have" to "required." California's AB-331, in effect since the start of this year, mandates algorithmic accessibility assessments for public-facing AI systems, and regulators are increasingly citing WCAG directly in settlements involving AI interfaces. Roughly one in four adults in the US lives with a disability. Treating their access to your product as a post-launch patch isn't just a UX failure, it's a growing compliance one too.

The teams that get this right won't be the ones with the most accessibility statements on their marketing page. They'll be the ones who tested with a screen reader before the demo, not after the complaint.

👨‍💻 Connect With Me

Rohit Raghuvansh
💡 UX Thinker · AI Builder · Making complex tech human-centered

Connect & Follow

LinkedIn — Rohit Raghuvansh

📢 Found This Article Helpful?

If this article added value to your learning journey:

✅ Share it with your network ✅ Bookmark it for future reference ✅ Follow for more

Keep Learning. Keep Building. Keep Growing. 🚀

System Design Thinking for AI Products: Why Your Architecture Diagram Needs an Empathy Map

rohit raghuvansh — Mon, 13 Jul 2026 03:45:25 +0000

System Design Thinking for AI Products: Why Your Architecture Diagram Needs an Empathy Map

City planners stopped designing roads by staring at traffic counts a long time ago. They started walking the intersections, watching where pedestrians actually crossed instead of where the crosswalk was painted, and noticing that the "optimal" signal timing on paper created a bottleneck nobody predicted because it ignored how people actually moved through the space. Somewhere along the way, software architecture lost that habit. We draw boxes and arrows, we optimize for throughput and latency, and we rarely ask what it feels like to be a request moving through the system we built.

That gap is becoming expensive. In June 2026 alone, a Zendesk AI agent outage traced back to an upstream EU service disruption rippled through customer-facing flows for the better part of an hour, and separately, researchers cataloging agentic AI failures found that the underlying cause is almost always architectural: teams treat the model as the product instead of treating context, validation, and observability as the product. Multi-step agents that chain 20, 50, or 100 actions together compound failure probability at every hop, and nobody mapped what those hops actually looked like from the inside until something broke.

Design thinking has spent two decades building tools for exactly this problem: understanding a system by walking through it from someone else's position instead of reasoning about it in the abstract. It just never got pointed at architecture diagrams. It's time it did.

The Pattern Behind Every Cascading Failure

Look at enough postmortems and a shape starts to repeat. A component times out. Instead of failing loudly, it passes a partial or stale result downstream. The next component, built with the assumption that upstream always hands it clean data, does something reasonable with unreasonable input. The error doesn't announce itself until three or four layers later, usually in front of a user, usually far from the place that actually broke.

Incident review culture already knows the fix in spirit: blameless postmortems exist precisely to reconstruct what a system "experienced" at each stage rather than assigning blame to a person. But the most common failure mode isn't the analysis, it's the follow-through. Teams write a sharp root cause document and then never close the loop, because the next sprint's feature work always feels more urgent than a diagram nobody will look at again. The postmortem becomes a eulogy instead of a blueprint.

This is where the outside-in habit matters. A journey map doesn't just document a timeline of events, it documents a subject's experience across that timeline, including where the friction was and how it felt in the moment. Applied to a system, a journey map turns "the embedding service timed out at 14:23 UTC" into "the request waited 500ms for a response that never came, then got silently rerouted to a keyword search fallback with no signal to anyone downstream that quality had degraded." One version is a log line. The other is a design problem you can actually fix.

Borrowing the Empathy Map, Not Just the Mindset

The classic empathy map has four quadrants: what the subject says, thinks, does, and feels. It sounds soft until you translate it literally into system terms, at which point it maps almost perfectly onto observability data that most teams already collect but never organize this way.

What it says becomes your logs and structured events: the explicit, stated output of each component. What it does becomes your traces: the actual sequence of calls, retries, and fallbacks, independent of what the logs claim happened. What it feels becomes your health signals: latency percentiles, error budgets, saturation, the equivalent of stress. The interesting quadrant is what it thinks, because most systems have no equivalent. It's the assumption baked into a component about the state of everything around it: "the feature store will always respond in under 200ms," "the upstream service will never send a null." Those assumptions are almost never written down anywhere, which means they're also never tested until reality contradicts them.

Filling in that fourth quadrant for your core services is a half-day exercise, not a research project, and it surfaces exactly the kind of hidden coupling that causes cascading failures. If three services all silently assume "the orchestrator retries failed calls," and none of them retry themselves, you've found a gap before it found you in production.

Mapping the Data Flow Like a User Journey

Modern AI-native architecture tends to converge on the same rough shape: data moves from sources into ingestion, through a feature store, and then splits into offline training and online inference paths that ultimately power a user-facing action. An orchestration layer sits in the middle, deciding how to route a request through models, tools, and retrieval steps. Every one of those handoffs is a place where a journey map earns its keep, because every handoff is a place where an assumption from the empathy-map exercise gets tested against reality.

Timeout cascades are the clearest example. A well-designed system defines, at each layer, what happens when the layer below is too slow. Skip embedding generation past 500ms and fall back to keyword search. Skip the personalization model past 200ms and serve the generic ranking. These aren't reliability footnotes, they're UX decisions wearing engineering clothes, and they only get made deliberately if someone walks the journey end to end and asks "what does this stage feel like when it's degraded, not just when it's healthy."

Feature flags do similar work for AI systems specifically, more than they do for traditional software, because model behavior itself changes unpredictably between versions in a way a simple code diff never will. A journey map that includes "which flag governs this stage, and what's the fallback behavior" turns an abstract resilience checklist into a concrete walk-through anyone on the team can follow, including the product manager who has never opened the orchestration code.

Where This Actually Pays Off

The payoff isn't a prettier diagram. It's that the four architectural pieces most AI-native systems now converge on, the agent orchestrator, the knowledge plane doing retrieval, the feature store, and a causal tracing engine that links model decisions back to system outcomes, only work together if someone has already mapped how a request feels moving between them. Causal tracing in particular is just an empathy map turned into infrastructure: it exists to answer "what did the system think was true at the moment it made this decision," which is precisely the quadrant most teams skip.

Teams that adopt this habit tend to report the same shift: incident reviews get faster because the mental model of "how does a request move through this thing" already exists before the incident, instead of getting reconstructed under pressure at 2am. Architecture reviews catch coupling assumptions before they ship instead of after they page someone. And new engineers ramp up faster because a journey map is a far more honest onboarding document than a component diagram that shows every possible path and specifies none of the real ones.

None of this replaces good engineering judgment. It just gives that judgment a discipline for noticing what it's easy to design around: not the happy path, but the moment something is slow, wrong, or missing, and what happens next because of it.

👨‍💻 Connect With Me

Rohit Raghuvansh
💡 UX Thinker · AI Builder · Making complex tech human-centered

Connect & Follow

LinkedIn — Rohit Raghuvansh

📢 Found This Article Helpful?

If this article added value to your learning journey:

✅ Share it with your network ✅ Bookmark it for future reference ✅ Follow for more

Keep Learning. Keep Building. Keep Growing. 🚀

Designing Error States for AI Products: A UX Deep Dive

rohit raghuvansh — Thu, 09 Jul 2026 04:04:33 +0000

Seven. That's how many publicly logged AI errors researchers counted in Q1 2024, the kind serious enough to make it into an incident tracker: wrong medical advice, fabricated legal citations, that sort of thing. By Q1 2026 that number was 226. Thirty two times higher, in two years, while the underlying models got objectively more capable on every benchmark that matters.

That gap is the whole problem. Models are getting smarter and failing more often in ways users actually notice, because more of them are shipping into more products, touching more edge cases, in front of more people who never signed up to be QA testers. Traditional software fails in predictable, discrete ways: a null pointer, a 500 error, a timeout. You write a try/catch and move on. AI products fail continuously, probabilistically, and often while sounding completely confident about it. That's a UX problem before it's an engineering problem, and most teams are still designing for it like it's 2019.

Here's what the data and the pattern libraries actually say about handling it.

Four failure modes, and only one of them looks like a bug

Most design systems have one error state: something broke, show a red banner, offer a retry button. AI products need at least four, because the failures aren't the same shape.

Hallucination. The system generates false information and presents it with the same tone and formatting as true information. Nothing crashes. No error code fires. The output just isn't real, and a user who doesn't already know the answer has no way to tell.

Timeout and latency collapse. Long-running inference, tool calls, or multi-agent chains can stall well past what a normal API user tolerates. Where a REST call fails in 200ms, an agent workflow can hang for 30 seconds before you know anything went wrong.

Partial results. A multi-step task completes 3 of 5 subtasks and stalls on the rest. Traditional software treats this as failure. AI products need to treat it as a different kind of success, one that requires very deliberate framing.

Low-confidence ambiguity. The system understood the request but isn't sure which of several interpretations is right, and guesses instead of asking.

Only the second one, timeout, resembles a failure state a pre-AI design system already knows how to handle. The other three require new patterns, and treating all four as "just show an error" is where most AI product UX breaks down.

Confidence is not accuracy, and your interface can't pretend otherwise

The most dangerous failure mode in production AI systems isn't the system being wrong. It's the system being confidently wrong, in a way that looks identical to the system being confidently right.

Look at how the major assistants already handle this, because the pattern is more consistent than you'd expect. High-confidence outputs (roughly 90%+ by the model's own internal signal) get delivered as direct statements or immediate actions, "Setting alarm for 7 AM," no hedging. Medium-confidence outputs (60-89%) get softened with a verification prompt: "This seems likely, but you may want to double check." Low-confidence outputs (under 60%) get an explicit disclaimer: "I'm not sure about this, you should verify with current sources."

Three tiers, three visual and linguistic treatments. That's the minimum viable pattern. What most teams skip is the part where the interface actually surfaces which tier it's in, instead of letting every response look identical regardless of how uncertain the model actually was internally. If your product has access to a confidence score and isn't using it anywhere in the UI, you're sitting on a signal that could prevent a real number of bad outcomes, and just not showing it to anyone.

Ambiguity handling follows the same logic. When Siri can't confidently resolve a request, it doesn't guess and hope: it says "I found several options" and shows a list, or asks a direct clarifying question. That's a deliberate design decision to trade one extra tap for a much lower chance of doing the wrong thing. Most AI chat interfaces default to guessing instead, because a clarifying question feels like friction. It is friction. It's also usually cheaper than the alternative.

A useful 80% answer beats a useless 0% answer

When part of a multi-step AI task fails, the instinct in traditional engineering is to fail the whole operation and surface one clean error. That instinct is wrong here, and the research on agent failure handling is blunt about why: graceful degradation means the system answers with what it has and tells the user what it couldn't get, and that's the difference between a useful 80% answer and a useless 0% answer.

Concretely, that means three things at the interface level. First, streaming matters more than people give it credit for: a response that renders token by token can deliver real value even if the connection drops before the final sentence, where a response that appears all at once has nothing to show for a failure at the 90% mark. Second, partial completions need explicit framing, not silence: "Completed 3 of 5 steps, the pricing lookup failed, here's what I have" is a fundamentally different user experience than the same output with no caveat attached, even though the underlying data is identical. Third, retries should default to resuming from the failure point, not restarting the whole chain, because nothing erodes trust in an agentic product faster than watching it redo work it already finished successfully.

The pattern that keeps showing up in agent-system postmortems is connection recovery through automatic reconnection with exponential backoff, paired with a visible status indicator so the user isn't left guessing whether the system is still working or just silent. Silence is the one state users trust the least, more than an explicit error message.

Recovery patterns worth stealing

Across the products that handle this well, a small set of recovery patterns repeat, and they're worth treating as defaults rather than reinventing per feature.

Plain-language explanations beat error codes every time; "the pricing service didn't respond in time" tells a user something actionable, "Error 504" does not. Pairing that explanation with 2 to 3 concrete next steps, retry now, wait in a queue, or fall back to a simpler mode, gives users a path forward instead of a dead end. Surfacing what succeeded before what failed matters too: leading with the win and following with the gap keeps the interaction from feeling like a wholesale failure when it mostly wasn't. And for anything irreversible, a generated email, a filed ticket, a code change, a confirmation step before the action fires is worth the extra click, because AI systems fail exactly the times you didn't expect them to.

None of this is exotic. It's mostly discipline: building four failure states instead of one, wiring confidence signals into the interface instead of hiding them, and treating partial success as its own state rather than a lesser form of failure. The teams getting called out publicly for bad AI UX right now aren't failing because their models are worse. They're failing because their error states were designed for software that doesn't fail the way this software fails.

👨‍💻 Connect With Me

Rohit Raghuvansh
💡 UX Thinker · AI Builder · Making complex tech human-centered

Connect & Follow

LinkedIn — Rohit Raghuvansh

📢 Found This Article Helpful?

If this article added value to your learning journey:

✅ Share it with your network ✅ Bookmark it for future reference ✅ Follow for more

Keep Learning. Keep Building. Keep Growing. 🚀

RAG Systems Explained With Diagrams: What Every Tech Writer Should Know

rohit raghuvansh — Wed, 08 Jul 2026 03:56:07 +0000

RAG Systems Explained With Diagrams: What Every Tech Writer Should Know

Ask a product team what RAG stands for and you'll get a confident answer within two seconds. Ask them to sketch what actually happens between the moment a user types a question and the moment an answer shows up on screen, and the room goes quiet. That gap, between knowing the acronym and understanding the mechanism, is where most bad product decisions about AI search get made.

Retrieval-Augmented Generation isn't a single model or a single feature. It's a pipeline with several distinct stages, and each stage fails in its own particular way. If you write documentation, specs, or user-facing copy for a product that touches RAG, you need the mechanism, not the buzzword.

So What Is RAG, Really?

Here's the simplest way to think about it: a language model only knows what it learned during training, plus whatever you hand it in the prompt. RAG is the system that decides what to hand it.

When someone asks a question, the system doesn't just send that question straight to the model. First it searches a knowledge base, usually a vector database, for chunks of text that are semantically related to the question. Those chunks get stuffed into the prompt alongside the original question. Only then does the model generate an answer, now grounded in whatever text got retrieved.

That's the whole idea: retrieval before generation, instead of generation alone. It sounds simple. The complexity lives entirely in how well the retrieval step actually finds the right text.

The market has caught up to this idea fast. The RAG market was valued at roughly $3.33 billion in 2026 and is projected to reach $81.51 billion by 2035, growing at a compound rate above 40% a year. Enterprise adoption is following the same curve: about 80% of enterprise software developers now say RAG is the most effective way to ground a language model in factual data, and roughly 65% of Fortune 500 companies are piloting RAG-based internal knowledge bases right now. Companies that deploy it well are reporting 30 to 70% efficiency gains in knowledge-heavy workflows, the kind of work that used to mean digging through wikis and shared drives by hand.

So why, with all that investment, do RAG answers still go wrong so often?

Where the Pipeline Actually Breaks

Here's a finding that surprises most people the first time they hear it: when a RAG system produces a bad answer, the retrieval step is at fault about 73% of the time, not the generation step. The model isn't usually the weak link. The search is.

That reframes the whole problem. Teams spend months tuning prompts and swapping models, when the actual defect is upstream: the system searched the knowledge base and pulled back the wrong chunks, or fragments of the right chunk with the middle cut off.

There's an even stranger failure mode buried in the research: cases where the system retrieves exactly the right document, hands it to the model, and the model still answers incorrectly. Researchers don't fully agree on why this happens. Leading theories point to attention drifting toward irrelevant tokens in the context window, or the model averaging across conflicting signals when multiple retrieved chunks disagree with each other. Retrieval isn't the only place things break. It's just where they break most often.

This is exactly why teams evaluating RAG products need a way to talk about failure precisely instead of just saying "the AI got it wrong." A framework called RAGAS breaks evaluation into four measurable dimensions: faithfulness (does the answer avoid contradicting the retrieved text), answer relevancy (does it actually address the question), context precision (how much of what got retrieved was useful), and context recall (did retrieval miss something important that existed in the knowledge base). Writing about a RAG feature without naming which of these four is failing is like writing a bug report that just says "it's broken."

Chunking: The Decision Nobody Documents

If retrieval is where most failures happen, chunking is where most retrieval failures start. Chunking is the process of breaking a knowledge base into pieces small enough to search and embed individually. Get the chunk size wrong and everything downstream inherits the problem.

Fixed-size chunking is the naive default: split every document into blocks of, say, 500 tokens, regardless of what's in them. It's fast to implement and it's also how you end up with a chunk that ends mid-sentence, or a table split across two unrelated fragments, or a code function cut in half. A 2026 benchmark found that recursive splitting around 512 tokens hit roughly 69% end-to-end accuracy, the best result of any single strategy tested in isolation, but "best single strategy" and "good enough" aren't the same thing.

Semantic chunking tries to fix this by splitting where meaning actually shifts. It computes embeddings sentence by sentence and starts a new chunk when the similarity between adjacent sentences drops below a threshold, instead of counting tokens blindly.

The pattern that's become the default in production by 2026, though, is hierarchical chunking. It keeps small chunks for precise matching and larger parent chunks for context, resolving a real tension: small chunks are easier to search accurately, but large chunks give the model more surrounding context once something is found. You retrieve on the small piece and hand the model the bigger piece it belongs to.

One more myth worth killing: chunk overlap, the practice of duplicating 10 to 20% of text between adjacent chunks so context isn't lost at the boundary, has long been treated as free insurance. A systematic analysis published in January 2026 found that overlap produced no measurable accuracy benefit in several test sets and only added indexing cost. The lesson for anyone documenting or spec'ing a RAG system: don't inherit best practices as gospel. Test them against your own queries.

What This Looks Like in Production

None of this is theoretical. GitHub Copilot's retrieval architecture has run in production on AWS for eight months, serving around 2,000 active developers across three enterprise deployments, referencing internal documentation and code context alongside the model's training data. A marketing analytics SaaS company built hybrid retrieval, combining vector search with traditional keyword search (BM25), over two million documents, then added a reranking step. The result: a 42% drop in irrelevant citations, with latency held to 900 milliseconds at the 95th percentile after precomputing query rewrites and batching the reranking calls.

Notice what both examples have in common. Neither one is "add a chatbot." Both are closer to "rebuild the search layer, then let the model speak from it." That's the real shape of a RAG project, and it's worth saying plainly in a spec or a stakeholder update, because it changes the timeline and the skill set the project actually needs.

The enterprise RAG platform market has split into three distinct layers as a result: turnkey platforms like Glean or Vectara that you buy and configure, cloud-native services tied to a specific hyperscaler like AWS Bedrock Knowledge Bases or Azure AI Search, and fully custom infrastructure assembled from open frameworks. Picking between those three is a build-versus-buy decision with real tradeoffs in control, cost, and how fast you can ship, and it deserves to be treated as one instead of getting bundled into a vague "add AI search" ticket.

If you take one thing from all this: the next time someone says a RAG feature "hallucinated," ask which stage actually failed. Was it retrieval pulling the wrong chunks? A chunking boundary that split the answer in half? Or generation genuinely inventing something despite good context? Those are three different bugs with three different fixes, and conflating them is how RAG products stay broken longer than they need to.

👨‍💻 Connect With Me

Rohit Raghuvansh
💡 UX Thinker · AI Builder · Making complex tech human-centered

Connect & Follow

LinkedIn — Rohit Raghuvansh

📢 Found This Article Helpful?

If this article added value to your learning journey:

✅ Share it with your network ✅ Bookmark it for future reference ✅ Follow for more

Keep Learning. Keep Building. Keep Growing. 🚀

How to Design Chat Interfaces That Don't Frustrate Users

rohit raghuvansh — Tue, 07 Jul 2026 12:38:24 +0000

Open any product roadmap in 2026 and there's a chat box on it somewhere. Support, onboarding, search, even settings are getting rebuilt as "just ask." The problem is that most teams ship the chat bubble and skip the interface design underneath it. The result is a box that looks simple and behaves like a black hole: you type something in, and you have no idea if it heard you, understood you, or is about to waste your afternoon.

Chat interfaces don't fail because the model is bad. They fail because of the same handful of UX gaps, over and over: silence where feedback should be, errors that don't help, threads that lose context, and inputs that assume you only ever want to type one line of plain text.

The silence problem: loading states are trust states

Every chat product has a moment between "user hits send" and "response appears." How you fill that gap decides whether people trust the tool at all.

The data on this is blunt. Tidio's 2026 research found that 82% of customers expect an instant response, and abandonment climbs roughly 7% for every additional second of delay. Without a typing indicator or status cue, users don't conclude "it's thinking." They conclude "it's broken," and they either resend the message or leave. For natural-feeling back and forth, end-to-end response time needs to stay under about 800 milliseconds. Anything slower needs to be dressed up with feedback, or it reads as a stall.

The fix isn't making the model faster. It's making the wait legible. A typing indicator is the floor, not the ceiling. Better patterns show what stage the system is in: "searching your documents," "checking three sources," "drafting a reply." That's not decoration, it's the same reason a progress bar with steps feels shorter than a spinner with none. Users tolerate latency they can interpret. They don't tolerate latency they can't explain.

If your product routes to different backends (a fast cached answer versus a slow agent call), the loading state should say so. A generic spinner treats a two-second lookup and a twenty-second agent chain the same way, and that mismatch is where trust erodes fastest.

When it doesn't understand you: error states that keep people moving

Traditional software fails loudly and specifically: a red border, a field-level message, a clear next step. Chat interfaces fail quietly and vaguely, because natural language input has no field to underline. "I didn't understand that" is the chat equivalent of a 500 error with no stack trace.

The fix is specificity. A clarifying question beats a generic failure every time: "Did you mean X or Y?" keeps the user in motion. "I didn't understand that" sends them looking for the exit. The same logic applies to malformed input: "That email doesn't look quite right, did you mean gmail.com instead of gmal.com?" solves the problem in the same breath it names it.

There's a second failure mode that's worse than a bad error message: no way out of the conversation. Bots without an escape route (to a human, a search fallback, or a structured form) turn a single misunderstanding into abandonment within two or three failed exchanges. The conversation the user can't escape, and has to restart from zero by repeating everything they already said, is worse than the form the chatbot replaced.

Four mistakes account for most of the failures here: dumping a wall of text instead of one idea per message, giving the bot an over-humanized personality that sets expectations it can't meet, leaving users unsure what the system can even do, and, again, no escape hatch. Fixing the escape hatch alone removes most of the worst outcomes, because it turns a dead end into a recoverable moment.

Threading and memory: don't make people repeat themselves

Long conversations create a structural problem plain chat UI wasn't built for: as the thread grows, earlier context becomes invisible, and users can't tell what the system still remembers. Visual separators, timestamps, and light indentation for replies help, but the deeper question is whether you need branching threads at all.

Full threading, with conversation branching and merge logic, is a real pattern for multi-agent or research-heavy tools where a user genuinely explores parallel lines of inquiry. But for most SaaS products, that's more complexity than the use case needs. A linear conversation, backed by solid history and search, gets the same job done with a fraction of the interaction cost. The mistake isn't picking linear over threaded, it's picking threaded because it looks sophisticated rather than because the workflow requires branching.

Where this shows up concretely: a user references something from ten messages ago, and the system either has to re-derive it or admit it lost the thread. Products that handle this well summarize and surface prior context instead of hiding it, so the user never has to re-explain themselves. Products that handle it badly ask the same qualifying questions twice in one session, which reads as the system not paying attention.

Input affordances: chat isn't only text

The "input box" in most chat UIs is still a single-line text field with an ambitious name. But conversational interfaces increasingly need to accept more than typed sentences: images, file attachments, voice, and structured selections all need a home in the same input surface.

This matters for a concrete reason. Intercom's data on conversational lead-qualification flows found 35 to 40% higher completion rates compared to traditional multi-field forms, largely because the input adapts to what's actually being asked rather than forcing every answer through a keyboard. A well-designed chat input offers quick-reply chips for constrained choices, drag-and-drop or paste for images, and a visibly distinct treatment in the thread so a pasted screenshot doesn't get flattened into "user sent a message."

The rule of thumb: if the answer is naturally a choice from a short list, don't make the user type it. If the answer is naturally visual, don't force it through text. The input should flex to the question, not the other way around.

Putting it together

None of these fixes require a better model. They require treating the chat window like the interface it is, one with states, failure modes, and affordances, rather than a text field bolted onto an AI endpoint. Show your work while the system thinks. Fail specifically, and always leave a way out. Don't add threading complexity the workflow doesn't need. Let the input match the question. Do those four things and the "just ask" interface stops being a black hole and starts being something people actually trust.

👨‍💻 Connect With Me

Rohit Raghuvansh
💡 UX Thinker · AI Builder · Making complex tech human-centered

Connect & Follow

LinkedIn — Rohit Raghuvansh

📢 Found This Article Helpful?

If this article added value to your learning journey:

✅ Share it with your network ✅ Bookmark it for future reference ✅ Follow for more

Keep Learning. Keep Building. Keep Growing. 🚀

Model Context Protocol Explained for Designers and PMs

rohit raghuvansh — Mon, 06 Jul 2026 04:11:03 +0000

Model Context Protocol Explained for Designers and PMs

Someone on your engineering team said "we're adding an MCP server for that" in standup, and you nodded like you understood. You didn't, and that's fine, because most of what gets written about MCP is written by developers, for developers, full of JSON snippets and SDK references that tell you nothing about what it means for your product.

Here's the plain version: Model Context Protocol is quietly becoming the wiring standard for how AI agents connect to the rest of the software you already use. If you're a PM scoping an agentic feature or a designer trying to figure out what's actually possible, you need the concept, not the code.

What MCP Actually Is

Think about USB-C for a second. Before it existed, every device had its own charging cable, its own port shape, its own adapter. Then one standard showed up and suddenly your laptop, phone, and headphones all plugged into the same kind of port. MCP is that idea applied to AI.

Before MCP, if you wanted an AI model to read your company's Notion docs, check Slack, and create a Jira ticket, someone had to build three separate custom integrations, each with its own authentication, its own data format, its own maintenance burden. Multiply that across every tool and every AI product your company ships, and you get a combinatorial mess: N tools times M AI products equals N times M custom connectors, each one fragile and none of them reusable.

MCP replaces that mess with three defined roles. The Host is the application the user actually sees, something like Claude Desktop, an IDE, or a custom agent your team built. The Client lives inside the Host and manages the connection to one specific server. The Server is the external program, maybe a Slack integration or a database connector, that exposes what it can do in a standard format the model understands.

Once a server speaks MCP, any MCP-compatible host can use it without custom code. Your Slack connector doesn't need to be rebuilt every time a new AI tool wants to talk to Slack. It just needs to speak the protocol once.

The Three Things a Server Can Actually Offer

This is the part that matters most for product thinking, because it defines the shape of what your agent can do.

A server exposes three kinds of capability. Tools are actions the model can take: send a message, create a record, run a query, book a meeting. These are the things that make an agent feel like it's actually doing work instead of just talking about it. Resources are data the model can pull in as context: a file, a customer record, a document, a support ticket. This is how an agent grounds its answers in your actual company data instead of guessing. Prompts are reusable templates the server provides, a standardized way of telling the model "when someone asks about refunds, approach it this way." This is less visible to users but it's how organizations bake their own playbooks into how an agent behaves.

When you're scoping a feature and an engineer says "we can expose that as an MCP tool," what they mean is: the model will be able to actually perform that action, not just describe it. That distinction should change how you write the spec. A chatbot that can tell you your order status is a resource problem. A chatbot that can cancel your order is a tool problem, and it needs a completely different level of confirmation UX, error handling, and audit logging.

Why This Is Showing Up on Your Roadmap Whether You Asked For It Or Not

MCP isn't a niche developer preference anymore. Since Anthropic introduced it in late 2024, the ecosystem has grown at a pace that's genuinely unusual even by AI standards. By March 2026, the protocol was seeing roughly 97 million monthly SDK downloads, a 970x increase in about 18 months, with the official MCP registry tracking more than 9,600 active servers. Fortune 500 enterprise adoption has reportedly reached around 28% in under two years, and analysts estimate close to a third of enterprise application vendors will ship their own MCP server sometime in 2026.

More concretely, the tools your company probably already uses have first-party MCP servers now. Slack's server lets an agent search threads and post updates. GitHub's official server lets an agent read repos, open issues, and submit pull requests. Notion shipped a server that lets an agent read, write, and search across your workspace. Zapier's MCP server acts as a bridge to thousands of other apps, so instead of waiting for a native integration, a team can often get "close enough" connectivity immediately.

For product teams, this changes the build-versus-connect calculus. A feature that once required a dedicated integration sprint might now be a matter of wiring up an existing MCP server. That's good news for velocity. It also means the differentiation in your product is shifting away from "we connected to Salesforce" (increasingly commoditized) toward how well you design the experience around what the agent does with that connection: the confirmations, the context it shows, the way it recovers when something goes wrong.

The Questions You Should Be Asking Before You Ship

Here's the part that doesn't show up in the marketing copy. MCP servers are, by design, giving a model the ability to take real actions and pull in real data, and that creates a genuinely new risk surface that product and design decisions directly affect.

Security researchers have flagged a handful of specific concerns worth knowing the names of, even if you're not the one fixing them. Over-privileged access happens when an agent is connected to a server with far broader permissions than the task requires, the equivalent of giving an intern the admin password because it was easier than setting up a limited account. Tool poisoning is when an attacker manipulates a tool's description or metadata to smuggle in hidden instructions the model might follow without the user ever seeing them. One analysis of open-source MCP servers found roughly 5.5% exhibited these kinds of attack patterns. Indirect prompt injection, where malicious instructions arrive embedded in a document or webpage the agent reads rather than in the user's own request, remains, in the words of one well-known security researcher, an issue the industry has known about for years without a convincing fix.

The 2026 update to the MCP spec introduced incremental scope consent, meaning a client can request only the minimum access needed for a specific operation rather than a blanket grant upfront. That's an engineering fix, but it's also a design opportunity. If your product asks a user to authorize "full calendar access" once during onboarding and never mentions it again, you've built the fragile version. If it asks, in context, "this agent wants to create one event on your calendar, allow it?" every time the stakes go up, you've built the version that survives an incident without losing user trust.

As a PM or designer, you don't need to architect the permission system. You do need to ask your engineering team, explicitly, what scope of access every MCP server connection actually grants, and whether the user has any visibility into that scope at all. That question alone puts you ahead of most teams shipping agentic features right now.

Where This Leaves You

MCP is infrastructure, and infrastructure is usually invisible until it breaks or until it unlocks something your competitors ship faster than you do. Understanding it at the level covered here, host, client, server, tools versus resources versus prompts, and the consent questions that come with real action-taking agents, is enough to sit in a planning meeting and ask the right questions instead of nodding along.

The teams that win the next round of agentic product design won't be the ones who understand the JSON-RPC handshake. They'll be the ones who understood early that a "tool" is a real action with real consequences, and designed the experience around that fact instead of discovering it after launch.

👨‍💻 Connect With Me

Rohit Raghuvansh
💡 UX Thinker · AI Builder · Making complex tech human-centered

Connect & Follow

LinkedIn — Rohit Raghuvansh

📢 Found This Article Helpful?

If this article added value to your learning journey:

✅ Share it with your network ✅ Bookmark it for future reference ✅ Follow for more

Keep Learning. Keep Building. Keep Growing. 🚀

The UX of AI Agents: Designing for Autonomy and Trust

rohit raghuvansh — Mon, 29 Jun 2026 10:11:54 +0000

The UX of AI Agents: Designing for Autonomy and Trust

Your agent works perfectly in the demo. Your users still don't trust it. Here's why, and what to actually do about it.

The question used to be "can AI do this?" In 2026, that question is largely settled. The harder question now is: "Can I trust AI to do this for me, without watching every step?"

Gartner projects that 40% of enterprise applications will embed task-specific AI agents by end of 2026, up from under 5% in 2025. That's a massive wave of agentic products about to land on real users. Most of them will fail the trust test, not the capability test.

This is a UX problem. And it's yours to solve.

Why AI Agents Break Traditional UX Assumptions

Traditional software does what you tell it, when you tell it. The user is always in control. The feedback loop is instant: click, then result.

AI agents operate on a completely different contract. You describe what you want, and the agent decides how to get there, taking multiple steps, using multiple tools, making micro-decisions you never explicitly authorised. The result might arrive 30 seconds later, or 5 minutes later, after a chain of actions the user never saw.

This breaks three UX assumptions that designers have relied on for decades.

Predictability breaks. Users can't anticipate what the agent will do next, because the agent is making judgment calls.

Reversibility breaks. Some agent actions like sending an email, booking a meeting, or submitting a form can't be undone. The stakes of a misstep are real.

Visibility breaks. The traditional feedback loop is gone. The agent works in the background, and silence feels like nothing happening.

When these three assumptions break, trust breaks too. And unlike a slow-loading page, a trust deficit is very hard to recover from.

Transparency Is a Design Surface, Not a Setting

The instinct of most teams is to hide complexity. Clean UI, minimal chrome, just show the output. This is exactly wrong for agentic products.

The "black box launch" is one of the most common failure patterns in agentic UX. A team ships an agent with a polished interface that shows inputs and outputs but nothing in between. Users see a spinner, then a result. They have no idea what happened. Because they don't know what happened, they can't verify the result. Because they can't verify it, they don't trust it.

What to build instead:

Reasoning panels are collapsible sidebars or inline sections showing the agent's step-by-step actions in plain English. Not a raw log. Something like: "Searched your emails for invoices from March, found 3 matching, summarised totals." Users rarely read this in detail, but knowing it exists dramatically increases confidence.

Action cards surface a brief confirmation before the agent executes anything consequential: "I'm about to send this email to your manager. Confirm or edit?" This single intervention point removes most of the fear associated with autonomous actions.

Confidence signals tell the truth about uncertainty. "I found 2 possible matches. Here's the one I think you meant, but check the other if this looks wrong." Uncertainty expressed honestly builds more trust than false confidence.

The key insight: transparency is not a feature you add at the end. It is a design surface you plan from the beginning, the same way you plan navigation or error states.

Control Surfaces: Give Users the Wheel Even When They Don't Need It

There's a real paradox in agentic UX. Users want agents to work autonomously, but they also want to feel in control. The trick is designing control surfaces that exist without interrupting.

Progressive autonomy is the most effective pattern here. Start the agent in supervised mode, where every significant action requires a quick confirmation. As the user sees the agent make good decisions consistently, let them unlock more autonomy. The agent now acts without asking for low-stakes tasks, but still surfaces high-stakes ones. This mirrors how you'd delegate to a new colleague: micromanage at first, then step back as trust is earned.

The override button should always be visible. Not buried in a settings menu. Visible, in context, at all times. "Stop" and "Undo last action" are not edge cases. They are the core of the trust contract. If a user knows they can always stop the agent, they are far more willing to let it run.

Sandbox mode is worth a dedicated mention for high-stakes workflows in finance, healthcare, or legal contexts. Let users run a simulation first: "Preview what this agent would do" before it actually does it. This converts the most sceptical users into willing adopters.

Designing for Failure, Because Agents Fail Differently

Traditional software fails with error codes. AI agents fail in much messier ways.

Ambiguous input is where most teams get surprised. The user said "send an update to the team." Which team? What kind of update? Traditional software throws a validation error. An agent might guess, and guess wrong. The design response: when the agent detects ambiguity, it surfaces a clarifying question before acting, not an apology after.

Partial results happen when an agent hits a permission wall or a service error halfway through a task. The wrong response is to fail silently or pretend the result is complete. The right response is to show exactly what was retrieved, mark what's missing, and give the user a clear path to resolve the gap.

Hallucination and low-confidence outputs are the trickiest failure mode. Unlike a 404 error, a hallucinated answer looks like a real answer. The design obligation is to make confidence levels visible at the output level, not hidden in a tooltip or a settings page. If the agent is uncertain, that uncertainty should be in the UI.

Timeout and abandonment will happen on long-running tasks. Design a clear recovery state: "Your agent paused on step 3 of 7. Resume or start over?" Users can tolerate interruption. They cannot tolerate losing their work invisibly.

The New UX Contract

For most of UX history, the designer's job was to make things usable, accessible, and satisfying to use. That contract has expanded significantly.

Designing agentic products now means owning accountability for the rules of engagement between human and machine. When should the agent act independently? When should it ask? When should it refuse entirely? These are not engineering decisions. They are design decisions with ethical weight.

Designers working on agentic products need to think about three things that were not in the job description before:

Consent architecture means asking what the user actually authorised, and whether they understood it when they did. An onboarding toggle labelled "Allow agent to manage my calendar" is not meaningful consent.

Auditability means users can review everything the agent did, after the fact. A full action log is not a developer tool. It is a basic user expectation for any autonomous system acting on their behalf.

Refusal design means thinking carefully about how the agent communicates what it cannot or will not do, without eroding the user's trust in the product overall.

This is genuinely new territory for most UX practitioners. It is also the most interesting design problem of the decade.

Closing Thoughts

The capability gap between humans and AI agents is closing fast. The trust gap is where the real work is.

Trust in agentic products is not built through marketing copy or onboarding tooltips. It is built through every design decision you make about transparency, control, and failure. Users will forgive an agent that makes a mistake and recovers well. They will not forgive one that fails silently.

The teams shipping trustworthy AI agents in 2026 will not necessarily be the ones with the most powerful models. They will be the ones who thought hardest about what users see, what they can control, and how the system behaves when things go wrong.

That is a UX problem. And it is one worth getting right.

👨‍💻 Connect With Me

Rohit Raghuvansh
💡 UX Thinker · AI Builder · Making complex tech human-centered

Connect & Follow

LinkedIn — Rohit Raghuvansh

📢 Found This Article Helpful?

If this article added value to your learning journey:

✅ Share it with your network ✅ Bookmark it for future reference ✅ Follow for more

Keep Learning. Keep Building. Keep Growing. 🚀