ByJoel GoldfootLast reviewed May 30, 2026

API & Attributes Reference

Complete technical specification for BiModal Design markup

This reference documents all data-agent-* custom attributes, ARIA patterns, Schema.org types, and semantic elements used in BiModal Design. Bookmark this page for quick lookup while developing.

Quick Navigation

data-agent-* Attributes ARIA Reference Schema.org Types HTML Elements JS Helpers Validation TypeScript

`data-agent-*` Attributes API

The data-agent-* namespace is the BiModal Design convention for annotating pages, components, content fields, and actions for AI agent consumption.

Page-Level Attributes

Applied to <html> or <body>

data-agent-framework

The rendering framework. Values: "nextjs", "astro", "nuxt", "sveltekit", "static"

data-agent-version

Framework or BiModal spec version.

data-agent-context

Page context. Values: "product", "article", "home", "checkout", etc.

data-agent-mode

Rendering mode. Values: "ssr", "ssg", "csr"

<html
  lang="en"
  data-agent-framework="nextjs"
  data-agent-version="1.0"
  data-agent-context="product"
  data-agent-mode="ssr"
>

Page Content Attributes

Applied to <main> or the primary content container

data-agent-page

Machine-readable page identifier. Values: "product-detail", "checkout", "home", "search-results", etc.

data-agent-intent

User goal for this page. Values: "purchase", "browse", "contact", "authenticate", etc.

data-agent-content-type

Primary content type. Values: "product", "article", "listing", "form", etc.

<main
  data-agent-page="product-detail"
  data-agent-intent="purchase"
  data-agent-content-type="product"
>
  <!-- page content -->
</main>

`data-agent-component`

Purpose:

Identifies a named UI component. Helps agents understand which section of the page they are looking at.

Common Values:

navigationhero-bannerproduct-listproduct-cardmain-contentsidebarfooterbreadcrumb

<nav
  aria-label="Main navigation"
  data-agent-component="navigation"
>
  <!-- nav links -->
</nav>

<article data-agent-component="product-card">
  <!-- product content -->
</article>

`data-agent-content`

Purpose:

Marks specific content fields so agents can reliably extract named values.

Common Values:

page-titlepage-descriptionproduct-nameproduct-descriptionproduct-pricesection-titlefallback-content

<article data-agent-component="product-card">
  <h1 data-agent-content="product-name">Premium Headphones</h1>
  <p data-agent-content="product-description">
    Noise-canceling wireless headphones
  </p>
  <span data-agent-content="product-price">$299.99</span>
</article>

`data-agent-action`

Purpose:

Identifies the action that a button, link, or form performs. Helps agents understand what user actions are available.

Common Values:

add-to-cartview-product-detailsgo-homebrowse-homeview-productsskip-to-contentget-support

<!-- Add to cart form -->
<form
  action="/cart/add"
  method="POST"
  data-agent-action="add-to-cart"
  data-agent-intent="purchase"
>
  <input type="hidden" name="product-id" value="12345">
  <button type="submit">Add to Cart</button>
</form>

<!-- Navigation links -->
<a href="/" data-agent-action="go-home">Home</a>
<a href="/products" data-agent-action="view-products">Products</a>

`data-agent-mitigation`

Purpose:

Marks elements that are mitigation strategies for CSR limitations, so agents can distinguish fallback content from real content.

Values:

skeletonnoscript

<!-- Loading skeleton -->
<div data-agent-mitigation="skeleton" aria-hidden="true">
  <!-- placeholder -->
</div>

<!-- Static fallback -->
<noscript data-agent-mitigation="noscript">
  <div data-agent-component="product-card">
    <h1 data-agent-content="product-name">Premium Headphones</h1>
    <span data-agent-content="product-price">$299.99</span>
  </div>
</noscript>

ARIA Quick Reference

Essential ARIA attributes for accessibility and agent comprehension.

Common Roles

role="navigation"

Navigation landmark

role="main"

Main content area

role="search"

Search region

role="button"

Interactive button

role="dialog"

Modal dialog

role="alert"

Important message

States & Properties

aria-label

Accessible name for element

aria-labelledby

ID of labeling element

aria-describedby

ID of describing element

aria-expanded

Expanded state (true/false)

aria-current

Current item (page/step/date)

aria-invalid

Validation state

Live Regions

aria-live="polite"

Announce when not busy

aria-live="assertive"

Announce immediately

aria-atomic="true"

Read entire region

Form Attributes

aria-required="true"

Required field

aria-invalid="true"

Invalid input

aria-errormessage

ID of error message

Schema.org Quick Reference

Common Schema.org types for structured data. Use JSON-LD format in <head>.

Product

{
  "@context": "https://schema.org",
  "@type": "Product",
  "name": "Product name",
  "description": "Product description",
  "image": ["https://example.com/image.jpg"],
  "brand": {
    "@type": "Brand",
    "name": "Brand name"
  },
  "offers": {
    "@type": "Offer",
    "price": "99.99",
    "priceCurrency": "USD",
    "availability": "https://schema.org/InStock",
    "url": "https://example.com/product"
  },
  "aggregateRating": {
    "@type": "AggregateRating",
    "ratingValue": "4.5",
    "reviewCount": "142"
  }
}

Article / BlogPosting

{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "Article title",
  "description": "Article description",
  "image": "https://example.com/image.jpg",
  "author": {
    "@type": "Person",
    "name": "Author name"
  },
  "publisher": {
    "@type": "Organization",
    "name": "Publisher name",
    "logo": {
      "@type": "ImageObject",
      "url": "https://example.com/logo.png"
    }
  },
  "datePublished": "2025-01-15T08:00:00Z",
  "dateModified": "2025-01-20T10:30:00Z"
}

LocalBusiness

{
  "@context": "https://schema.org",
  "@type": "LocalBusiness",
  "name": "Business name",
  "image": "https://example.com/image.jpg",
  "address": {
    "@type": "PostalAddress",
    "streetAddress": "123 Main St",
    "addressLocality": "City",
    "addressRegion": "State",
    "postalCode": "12345",
    "addressCountry": "US"
  },
  "telephone": "+1-555-123-4567",
  "openingHoursSpecification": {
    "@type": "OpeningHoursSpecification",
    "dayOfWeek": ["Monday", "Tuesday", "Wednesday", "Thursday", "Friday"],
    "opens": "09:00",
    "closes": "17:00"
  }
}

Other Common Types

Organization

HTML Semantic Elements

Landmarks

<header>

Page or section header

<nav>

Navigation section

<main>

Main content (one per page)

<aside>

Sidebar or tangential content

<footer>

Page or section footer

Content Sections

<article>

Self-contained content

<section>

Thematic grouping

<h1> - <h6>

Headings (hierarchy)

<p>

Paragraph

Text Semantics

<strong>

Strong importance

<em>

Emphasis

<time>

Date/time with datetime attr

<code>

Code snippet

<mark>

Highlighted text

Interactive

<button>

Clickable button

<a>

Hyperlink

<form>

Form container

<input>

Form input

<label>

Input label

JavaScript Helpers

Utility functions for working with BiModal markup.

Find components by type

function getComponentsByType(type) {
  return Array.from(
    document.querySelectorAll(`[data-agent-component="${type}"]`)
  );
}

// Usage
const productCards = getComponentsByType('product-card');
const navBar = getComponentsByType('navigation');

Extract content field from a component

function getAgentContent(component, fieldName) {
  const el = component.querySelector(`[data-agent-content="${fieldName}"]`);
  return el?.textContent.trim() || null;
}

// Usage
const card = document.querySelector('[data-agent-component="product-card"]');
const name = getAgentContent(card, 'product-name');
const price = getAgentContent(card, 'product-price');

Extract all content fields from a component

function extractComponent(component) {
  const type = component.dataset.agentComponent;
  const fields = {};

  component.querySelectorAll('[data-agent-content]').forEach(el => {
    const field = el.dataset.agentContent;
    fields[field] = el.textContent.trim();
  });

  return { type, fields };
}

// Usage
const card = document.querySelector('[data-agent-component="product-card"]');
const data = extractComponent(card);
// { type: 'product-card', fields: { 'product-name': '...', 'product-price': '...' } }

Find available actions on page

function getAvailableActions() {
  return Array.from(document.querySelectorAll('[data-agent-action]')).map(el => ({
    action: el.dataset.agentAction,
    intent: el.dataset.agentIntent || null,
    element: el,
  }));
}

// Usage
const actions = getAvailableActions();
// [{ action: 'add-to-cart', intent: 'purchase', element: ... }, ...]

TypeScript Definitions

Type definitions for BiModal data-agent-* attributes.

// bimodal.d.ts

declare namespace BiModal {
  // Page-level attributes (on <html> or <body>)
  type Framework = 'nextjs' | 'astro' | 'nuxt' | 'sveltekit' | 'static';
  type RenderMode = 'ssr' | 'ssg' | 'csr';

  // Component names
  type ComponentName =
    | 'navigation'
    | 'hero-banner'
    | 'product-list'
    | 'product-card'
    | 'main-content'
    | 'sidebar'
    | 'footer'
    | 'breadcrumb';

  // Content field names
  type ContentField =
    | 'page-title'
    | 'page-description'
    | 'product-name'
    | 'product-description'
    | 'product-price'
    | 'section-title'
    | 'fallback-content';

  // Action names
  type ActionName =
    | 'add-to-cart'
    | 'view-product-details'
    | 'go-home'
    | 'browse-home'
    | 'view-products'
    | 'skip-to-content'
    | 'get-support';

  // Mitigation strategies
  type MitigationType = 'skeleton' | 'noscript';

  // Extracted component data
  interface ComponentData {
    type: ComponentName;
    fields: Record<string, string>;
    element: HTMLElement;
  }

  // Extracted action data
  interface ActionData {
    action: ActionName;
    intent?: string;
    element: HTMLElement;
  }
}

export default BiModal;

Need More Help?

This reference covers the essentials. For more detailed examples and patterns, check out these resources:

View Code Examples Start Tutorial

API & Attributes Reference

Quick Navigation

`data-agent-*` Attributes API

Page-Level Attributes

Page Content Attributes

`data-agent-component`

`data-agent-content`

`data-agent-action`

`data-agent-mitigation`

ARIA Quick Reference

Common Roles

States & Properties

Live Regions

Form Attributes

Schema.org Quick Reference

Product

Article / BlogPosting

LocalBusiness

Other Common Types

HTML Semantic Elements

Landmarks

Content Sections

Text Semantics

Interactive

JavaScript Helpers

TypeScript Definitions

Validation Rules

BiModal Compliance Checklist

Validator Tools

Need More Help?

API & Attributes Reference

Quick Navigation

data-agent-* Attributes API

Page-Level Attributes

Page Content Attributes

data-agent-component

data-agent-content

data-agent-action

data-agent-mitigation

ARIA Quick Reference

Common Roles

States & Properties

Live Regions

Form Attributes

Schema.org Quick Reference

Product

Article / BlogPosting

LocalBusiness

Other Common Types

HTML Semantic Elements

Landmarks

Content Sections

Text Semantics

Interactive

JavaScript Helpers

TypeScript Definitions

Validation Rules

BiModal Compliance Checklist

Validator Tools

Need More Help?

`data-agent-*` Attributes API

`data-agent-component`

`data-agent-content`

`data-agent-action`

`data-agent-mitigation`