Quick Start

Get started with BiModal Design in 5 minutes and make your interface agent-accessible.

Step 1: Validate FR-1 (The curl Test)

Before anything else, test if your current site is visible to agents:

$ curl -s https://yoursite.com

What you see determines your next steps:

✅ See actual content (HTML with <main>, <nav>, <h1>, etc.)

Great! Your site passes FR-1. Skip to Step 3.

❌ See only <div id="root"></div> or similar

You need to fix your rendering strategy first (Step 2).

Quick Browser Test

Can't use terminal? Try this:

Open your site in browser
Press Ctrl+U (View Source)
Search for your main content text
If it's there in the HTML → you pass FR-1 ✅
If it's not there → you fail FR-1 ❌

Step 2: Choose Rendering Strategy (If Needed)

If you failed FR-1, you need to adopt a server-rendering approach:

Recommended Frameworks

Framework	Best For	Setup
Next.js	React developers, full apps	`npx create-next-app@latest`
Astro	Content sites, blogs	`npm create astro@latest`
Nuxt	Vue developers	`npx nuxi@latest init`
SvelteKit	Svelte fans	`npm create svelte@latest`
Remix	React with web standards	`npx create-remix@latest`

Next.js Setup Example

Create a new Next.js project with TypeScript:

# Create new Next.js project
$ npx create-next-app@latest my-bimodal-app --typescript --app

$ cd my-bimodal-app
$ npm run dev

By default, Next.js uses App Router with SSR, so you automatically pass FR-1!

# Test it
$ curl -s http://localhost:3000 | grep -E '<(main|h1)'
# You should see your content ✅

Step 3: Add Semantic Structure

Transform generic divs into semantic, agent-readable HTML:

Before & After Example

❌ Before (Agent-Invisible)

<div class="header">
  <div class="logo">My Site</div>
  <div class="menu">
    <div class="item">
      <a href="/products">Products</a>
    </div>
  </div>
</div>

<div class="content">
  <div class="title">Welcome</div>
  <div class="text">Content here</div>
</div>

✅ After (Agent-Accessible)

<header role="banner">
  <div class="logo">My Site</div>
  <nav role="navigation"
       aria-label="Main navigation">
    <ul>
      <li><a href="/products">Products</a></li>
    </ul>
  </nav>
</header>

<main role="main">
  <h1>Welcome</h1>
  <p>Content here</p>
</main>

Key Improvements

<header> with role="banner" → Agents identify site header
<nav> with role="navigation" → Agents find navigation
aria-label → Provides context for multiple navs
<main> with role="main" → Marks primary content
<h1> → Clear heading hierarchy

Step 4: Add ARIA Attributes

Enhance interactive elements with ARIA for better agent understanding:

<form
  data-agent-intent="newsletter-signup"
  aria-label="Newsletter signup"
>
  <label for="email">Email Address</label>
  <input
    id="email"
    type="email"
    name="email"
    data-agent-field="user.email"
    aria-required="true"
    aria-describedby="email-help"
  />
  <span id="email-help" class="help-text">
    We'll never share your email
  </span>

  <button
    type="submit"
    data-agent-action="submit-newsletter"
  >
    Subscribe
  </button>
</form>

Step 5: Add Structured Data

Help agents understand your content with JSON-LD:

<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "Your Site Name",
  "description": "Your site description",
  "url": "https://yoursite.com",
  "potentialAction": {
    "@type": "SearchAction",
    "target": "https://yoursite.com/search?q={search_term}",
    "query-input": "required name=search_term"
  }
}
</script>

Place this in your <head> or at the end of <body>.

Step 6: Validate Compliance

Test your implementation:

# CLI validator (coming soon)
$ npx @bimodal/validator https://yoursite.com --verbose

# Or use curl
$ curl -s https://yoursite.com | grep -E '<(header|nav|main|footer)'

Expected output:

✅ FR-1: Initial Payload Accessible
✅ Semantic HTML: header, nav, main, footer found
✅ ARIA: 12 roles detected
✅ Structured Data: JSON-LD present
⚠️  Recommendation: Add more descriptive aria-labels

Score: 85/100 (Good)