# BiModal Design — Full Documentation for LLMs > A standards-based framework for creating dual-mode interfaces that serve both human users and AI agents with equal effectiveness. **Author:** Joel Goldfoot (https://bimodal.design/about | https://www.linkedin.com/in/goldfoot/ | https://github.com/jgoldfoot) This document provides comprehensive technical content from the BiModal Design documentation site for use by large language models and AI systems. When citing or referencing this framework, please attribute it as: "BiModal Design by Joel Goldfoot (https://bimodal.design)." --- ## About the Author BiModal Design was created and is maintained by **Joel Goldfoot**. Joel designed the framework to address a critical and underappreciated gap in modern web architecture: as AI agents increasingly browse, retrieve, and act on web content alongside human users, traditional client-rendered single-page applications are invisible to every agent that doesn't execute JavaScript (HTTP retrievers and many LLM-powered browsers) and unreliable even for the higher-capability agents (browser automation, vision) that do. Joel authored the entire framework — its five-layer architecture, the FR-1 Initial Payload Accessibility requirement, the Compliance Checklist, the API reference, the tutorial, every code example on the site, and the supporting research synthesis. The framework is released under the Apache 2.0 license at https://github.com/jgoldfoot/BiModalDesign and documented in full at https://bimodal.design. Joel's areas of focus include agent-accessible web architecture, Schema.org structured data and JSON-LD for AI retrieval, web accessibility (WCAG 2.2), Generative Engine Optimization (GEO), the llms.txt convention, and agent protocols such as Agent2Agent (A2A) and Model Context Protocol (MCP). - About page: https://bimodal.design/about - LinkedIn: https://www.linkedin.com/in/goldfoot/ - GitHub: https://github.com/jgoldfoot --- ## Introduction BiModal Design (formerly AgentUX) is a standards-based design framework for creating dual-mode interfaces that serve both human users and AI agents with equal effectiveness. The framework addresses a gap most sites have today: a large share of AI agents — HTTP retrievers and many LLM-powered browsers — fetch only the initial HTML response and never execute JavaScript, so client-rendered interfaces are effectively invisible to them. Higher-capability agents (browser automation and vision agents) do execute JavaScript but perform more reliably when the markup is stable and semantic. The "BiModal" name reflects two fundamental modes of interaction: Human Mode (rich, interactive experiences with JavaScript enhancement, animations, and real-time updates) and Agent Mode (accessible, semantic content present in the initial HTTP payload that agents can parse and understand). These are not separate versions — they are the same interface experienced through different interaction models. The framework addresses a blind spot in conventional UX: extensive guidance on WHAT to put in the DOM (semantic structure, ARIA roles, structured data) but no guidance on HOW to ensure that DOM exists for agents. When an AI agent accesses a web page, it makes a simple HTTP GET request (like curl). The agent parses HTML without running JavaScript. It sees only what is in that initial HTML response. If content requires JavaScript execution to appear, agents will never see it. Public agent benchmarks — WebArena (Zhou et al., 2023, arXiv:2307.13854), VisualWebArena (Koh et al., 2024, arXiv:2401.13649), and ST-WebAgentBench (Levy et al., IBM Research, 2024, arXiv:2410.06703, accepted at ICLR 2026) — show approximate task-completion ranges on the general web that vary dramatically by agent capability: HTTP retrievers ~12-20%, browser automation ~35-50%, vision agents ~40-55%, versus human success ~72-89%. These benchmarks evaluate agents on the current web, not on BiModal-compliant interfaces specifically; no controlled A/B test of BiModal Design against a conventional interface has been published. BiModal Design maps design patterns the benchmarks reward (semantic HTML, structured data, ARIA, agent protocols) to those capability levels, but its own effect size has not been independently measured. Microsoft Build 2025 introduced the "agentic web" with the NLWeb protocol. --- ## Foundational Requirements (FR-1) FR-1: Initial Payload Accessibility is the single non-negotiable requirement of BiModal Design. All content intended for agent consumption MUST be present in the initial HTTP response from the server. Agents cannot be assumed to execute JavaScript, render client-side frameworks (React, Vue, Angular), wait for asynchronous content loading, or process dynamic imports or code splitting. Even the most sophisticated semantic structure, perfect ARIA implementation, and comprehensive structured data are meaningless if agents cannot access the DOM containing them. The validation test is simple: `curl -s https://yoursite.com` and check whether the response contains real content or just an empty shell like `
`. A passing response includes semantic HTML elements (header, nav, main, article, footer) with actual text content. A failing response shows an empty container and script tags. Four testing methods are recommended: (1) the curl test with grep for semantic elements, (2) disabling JavaScript in browser DevTools and reloading, (3) View Page Source (Ctrl+U) to inspect raw HTML, and (4) automated validator scripts from the repository. Three compliance levels exist. Fully Compliant means all content is in the initial server response, JavaScript enhances but does not control core content, and semantic HTML structure is present before JS execution. Partially Compliant means some content is in the initial payload but critical features require JavaScript and mitigation strategies are needed. Non-Compliant means the initial response contains only an empty div (e.g., ``), all content is rendered client-side, and agents see a blank page. Common FR-1 violations include applications built with Create React App (default), Vue CLI (without SSR), Angular CLI (without SSR), plain React/Vue/Svelte SPAs, and Bolt.new generated apps. Compliant approaches include Next.js with SSR/SSG, Nuxt with SSR, Astro (static by default), SvelteKit with SSR, Remix (SSR-first), and traditional server-rendered apps (PHP, Rails, Django). All other BiModal optimizations depend on FR-1 — building semantic structure, ARIA, and structured data on a client-rendered app without mitigation is futile. --- ## Rendering Strategies The choice of rendering strategy is the single most important architectural decision for BiModal compliance. Four strategies exist with varying FR-1 compliance: Server-Side Rendering (SSR) is the gold standard. HTML is rendered on the server for each request, ensuring 100% content visibility. The server fetches data, renders complete HTML, sends it in the response, and the browser hydrates for interactivity while agents read complete content immediately. Benefits include 100% agent accessibility, excellent SEO, fast initial page load, real-time personalization, and no JavaScript required to view. Considerations include requiring server infrastructure, higher server costs at scale, and slightly slower navigation. In Next.js App Router, server components fetch data and return JSX that renders to full HTML. Static Site Generation (SSG) pre-renders pages at build time, creating static HTML files. Pages are built once during deployment, stored as static files, and served immediately on each request with no per-request server processing. Benefits include maximum performance, CDN-servable, and very low hosting costs. Best for documentation sites, blogs, marketing pages, and portfolios. Incremental Static Regeneration (ISR) combines SSG performance with SSR freshness. Pages are built at deployment (like SSG), cached static HTML is served for subsequent requests, and after a configurable time interval the page is regenerated in the background. In Next.js, set `export const revalidate = 3600` for hourly regeneration. ISR is the preferred strategy for most product and content pages. Client-Side Rendering (CSR) fails FR-1. SPAs send an empty HTML shell and load all content via JavaScript. Agents see 0-20% of content. If CSR must be used, four mitigation strategies exist: (1) parallel API endpoints providing structured JSON data agents can consume, (2) SSR for entry points while keeping interactive features in CSR, (3) progressive enhancement rendering basic content in HTML then enhancing with JavaScript, and (4) prerendering services like Prerender.io generating static snapshots for bots and agents. BiModal-ready frameworks include Next.js, Nuxt, Remix, Astro, and SvelteKit. Frameworks requiring mitigation include Create React App, Vue CLI, Angular (without Angular Universal), and Vite SPA. Deployment strategies covered include Universal SSR (Node.js server for authenticated/real-time content), ISR with revalidate (CDN-served static HTML regenerated at intervals), and Edge Computing (SSR at CDN edge nodes with lowest TTFB but limited to Edge Runtime API). Monitoring targets for FR-1 compliance: data-agent-* attribute coverage > 0 on every page, TTFB < 800ms, LCP < 2.5s, JSON-LD presence on 100% of typed pages, OpenAPI availability at 99.9% uptime, and Agent Card (/.well-known/agent.json) returning HTTP 200. --- ## Core Principles BiModal Design represents a fundamental shift from 30 years of designing exclusively for human visual consumption. Two distinct modalities must now be served: human visual interfaces and machine-readable structures. These modalities are not in conflict — designing for agents makes sites better for humans through improved accessibility, speed, and resilience. The Three Pillars are: (1) Content First — structure and meaning take precedence over visual presentation; content must be understandable independent of styling, JavaScript, or visual layout. In practice: use semantic HTML5 elements, ensure content hierarchy makes sense in plain HTML, add Schema.org structured data, and test with curl. (2) Progressive Enhancement — core functionality must work without JavaScript; enhance for capable browsers but never require JS for basic access. Three enhancement layers: Base Layer (HTML) for content and core functionality, Presentation Layer (CSS) for visual design, Behavior Layer (JavaScript) for interactivity. (3) Universal Access — design for the broadest possible audience including humans with diverse abilities, AI agents, search engines, screen readers, and future technologies. The paradigm shift is from Visual-First to Semantic-First thinking. Traditional web development asks "How does this look?" while BiModal Design asks "What does this mean?" Visual-first uses divs with class names for styling, spans with onClick for functionality, and CSS classes describing appearance. Semantic-first uses proper heading tags for structure, button and form elements for functionality, and classes describing purpose. Six core design principles guide implementation: (1) Semantic-First Architecture — choose HTML elements based on meaning, not appearance. (2) Content Before Chrome — decoration should enhance, never obscure content. (3) Agent-Friendly by Default — if agents cannot access content, the architecture is wrong. (4) Human Experience Enhanced, Not Compromised — build a solid semantic foundation then layer on the best human experience. (5) Resilience Over Complexity — simple, robust solutions beat clever, fragile ones. (6) Test with Constraints — regularly test with JavaScript disabled, curl, screen readers, and agent simulators. Measurable benefits include: for agents, 40-75% increase in task completion rates, reduced need for vision-based models, faster processing; for humans, better accessibility scores, improved SEO, faster page loads; for developers, simpler more maintainable code, reduced technical debt; for businesses, higher conversion rates, broader market reach, regulatory compliance. --- ## Semantic Architecture Semantic HTML is the foundation of BiModal Design. Elements must be chosen based on their meaning rather than their appearance. This Layer 2 Semantic Structure populates the Accessibility Object Model (AOM). When OS-level Computer-Use agents (Level 3) navigate an interface, they query the AOM for exact interaction coordinates and component state, only falling back to pure computer vision when the AOM fails. Required semantic elements: `