# Agent-Friendly Design Specification: ShopWave (E-commerce) > Generated by Agentify · 2025-03-20 ## Table of Contents - [1. Executive Summary](#1-executive-summary) - [2. Semantic HTML](#2-semantic-html) - [3. ARIA Patterns](#3-aria-patterns) - [4. Naming Conventions](#4-naming-conventions) - [5. Structured Data](#5-structured-data) - [6. Form Patterns](#6-form-patterns) > Truncated example showing expected depth for the first 6 sections. --- ## 1. Executive Summary ShopWave is a Next.js e-commerce platform. Agent-friendliness is critical because: - **Price comparison agents** need reliable product data extraction - **Shopping assistants** need to navigate, filter, and add to cart - **SEO crawlers** need structured data for rich results - **Automated testing** needs stable selectors surviving redesigns Target: improve from D (55) to A (90+). --- ## 2. Semantic HTML ### 2.1 Page Structure (P0) ```html

Page Title

``` ### 2.2 Product Card (P0) ```jsx

{product.name}

{formatPrice(product.price)}

``` --- ## 3. ARIA Patterns ### 3.1 Cart Button (P0) ```jsx ``` ### 3.2 Product Filters (P0) ```jsx ``` ### 3.3 Quantity Selector (P1) ```jsx

Quantity

``` --- ## 4. Naming Conventions ### 4.1 data-testid Scheme (P0) Format: `{component}-{element}-{type}` | Element | data-testid | |---------|-------------| | Product card | `product-card` | | Product title | `product-name` | | Add to cart | `add-to-cart-btn` | | Cart item row | `cart-item` | | Cart remove | `cart-item-remove-btn` | | Checkout form | `checkout-form` | | Email input | `email-input` | | Search input | `search-input` | ### 4.2 Entity Attributes (P1) ```jsx

``` --- ## 5. Structured Data ### 5.1 Product Page (P0) ```json { "@context": "https://schema.org", "@type": "Product", "name": "Wireless Headphones Pro", "image": "https://shopwave.com/images/whp.jpg", "sku": "WHP-001", "brand": { "@type": "Brand", "name": "ShopWave Audio" }, "offers": { "@type": "Offer", "price": "149.99", "priceCurrency": "USD", "availability": "https://schema.org/InStock" }, "aggregateRating": { "@type": "AggregateRating", "ratingValue": "4.5", "reviewCount": "128" } } ``` ### 5.2 Breadcrumbs (P1) ```json { "@context": "https://schema.org", "@type": "BreadcrumbList", "itemListElement": [ { "@type": "ListItem", "position": 1, "name": "Home", "item": "https://shopwave.com" }, { "@type": "ListItem", "position": 2, "name": "Electronics", "item": "https://shopwave.com/electronics" }, { "@type": "ListItem", "position": 3, "name": "Headphones" } ] } ``` ### 5.3 Homepage (P1) ```json { "@context": "https://schema.org", "@type": "WebSite", "name": "ShopWave", "url": "https://shopwave.com", "potentialAction": { "@type": "SearchAction", "target": "https://shopwave.com/search?q={search_term_string}", "query-input": "required name=search_term_string" } } ``` --- ## 6. Form Patterns ### 6.1 Checkout Form (P0) ```jsx ```