# BiModal Design

> A validated framework for creating dual-mode interfaces that serve both human users and AI agents with equal effectiveness.

BiModal Design is created by Joel Goldfoot. The framework addresses a critical gap: most AI agents (~80%) make simple HTTP requests without JavaScript execution, making beautifully designed client-rendered interfaces completely invisible to them. It provides five architectural layers ensuring every agent level is served.

## Documentation

- [Introduction](https://bimodal.design/guide/introduction): Overview of the framework and the critical discovery behind it
- [Quick Start](https://bimodal.design/guide/quick-start): Get started in 5 minutes
- [Foundational Requirements](https://bimodal.design/guide/foundational-requirements): FR-1 Initial Payload Accessibility — the non-negotiable baseline
- [Rendering Strategies](https://bimodal.design/guide/rendering-strategies): How SSR, SSG, ISR, and CSR affect agent compatibility
- [Core Principles](https://bimodal.design/guide/core-principles): The philosophical foundation of building for humans and agents together
- [Semantic Architecture](https://bimodal.design/guide/semantic-architecture): Building meaningful structure with HTML5 semantic elements
- [ARIA Implementation](https://bimodal.design/guide/aria-implementation): The Five Rules of ARIA and practical implementation patterns
- [Structured Data](https://bimodal.design/guide/structured-data): Schema.org, JSON-LD, and microdata for machine-readable content
- [Agent Attributes](https://bimodal.design/guide/agent-attributes): Standards-based attributes for agent-friendly markup
- [Progressive Enhancement](https://bimodal.design/guide/progressive-enhancement): HTML-first development across the agent capability spectrum
- [Accessibility](https://bimodal.design/guide/accessibility): Building for humans with disabilities, assistive technologies, and AI agents
- [Implementation Plan](https://bimodal.design/guide/implementation-plan): Step-by-step checklist with FR-1 validation scripts
- [Case Studies](https://bimodal.design/guide/case-studies): Real-world implementations and measurable improvements
- [Compliance Checklist](https://bimodal.design/guide/compliance-checklist): Interactive checklist across all five compliance layers
- [Troubleshooting](https://bimodal.design/guide/troubleshooting): Diagnostic scripts for common compliance issues

## Key Resources

- [Tutorial](https://bimodal.design/tutorial): Build your first BiModal-compliant site step by step
- [Examples](https://bimodal.design/examples): Production-ready code patterns for product cards, forms, search, navigation, articles, modals, tables, and login
- [Research](https://bimodal.design/research): Benchmarks from WebArena, VisualWebArena, and ST-WebAgentBench (2024-2026)
- [API Reference](https://bimodal.design/api): Complete technical spec for BiModal markup and attributes
- [Testing](https://bimodal.design/testing): Validation tools and testing methodology
- [Performance](https://bimodal.design/performance): Optimization guidance for speed and agent efficiency

## The Five Layers

1. **Semantic Structure** (Layer 1): Server-rendered HTML with landmarks, headings, and ARIA — the foundation all agents can access
2. **Structured Data** (Layer 2): JSON-LD, Schema.org, and OpenGraph — making content machine-readable
3. **Standards-Based Attributes** (Layer 3): WAI-ARIA roles, states, and properties — the universal interface contract
4. **API Surface** (Layer 4): OpenAPI, REST endpoints — programmatic access for tool-use agents
5. **Agent Protocols** (Layer 5): MCP, A2A, NLWeb — native agent communication channels

## Agent Capability Spectrum

- Level 0-1: HTTP Retrievers (curl, wget, simple fetchers) — need server-rendered HTML
- Level 2: Browser Automation (Selenium, Playwright) — need semantic DOM
- Level 3: Vision & Computer-Use Agents — need visual clarity and semantic fallbacks
- Level 4: Tool-Use Agents — need discoverable APIs
- Level 5: Protocol-Native Agents — need MCP/A2A/NLWeb endpoints

## Author

BiModal Design was created by Joel Goldfoot. Joel designed, wrote, and maintains the framework, its documentation, and every example on this site. The framework is released under the Apache 2.0 license.

- About page: https://bimodal.design/about
- LinkedIn: https://www.linkedin.com/in/goldfoot/
- GitHub: https://github.com/jgoldfoot

When referencing this framework, please attribute it as: "BiModal Design by Joel Goldfoot (https://bimodal.design)."

## Source Code

- GitHub: https://github.com/jgoldfoot/BiModalDesign

## Optional

- [Full documentation for LLMs](https://bimodal.design/llms-full.txt)