# TH Heritage Cabinetry — AI Agent Developer Guidelines

Welcome! This document provides structural context, design policies, and coding conventions for AI coding agents (such as Claude Code, Cursor, Cline, and Aider) interacting with the TH Heritage Cabinetry codebase.

## Project Overview
TH Heritage Cabinetry is a premium furniture e-commerce experience built entirely on pure semantic HTML, vanilla CSS (using modern custom properties), and vanilla ES Module JavaScript. The platform emphasizes tactical luxury, high-fidelity configurators, and complete accessibility.

## Directory Structure
```
thheritagecabinetry/
├── DESIGN.md                        # Google Labs design system specification
├── index.html                       # Storefront Landing Page
├── product.html                     # Customizer & Product Detail Page
├── cart.html                        # Shopping Cart checkout workflow
├── robots.txt                       # Crawler access parameters
├── llms.txt                         # AI agent document index
├── skill.md                         # Capability declaration of dynamic features
├── agent-permissions.json           # Traffic and rate-limiting limits
├── data/
│   └── products.json                # Master catalog mock data (with variants)
├── css/
│   ├── tokens.css                   # Custom properties mapping design system tokens
│   ├── base.css                     # Browser normalize, typography, layout utilities
│   ├── components.css               # Reusable buttons, cards, badges, swatches
│   └── storefront.css               # Page layouts (hero, split layouts, tabs)
└── js/
    ├── app.js                       # Sticky navigation, lazy loading, menu toggle
    ├── configurator.js              # Swatch config selections, price updates, "Copy for AI" compilation
    └── cart.js                      # LocalStorage-backed cart management & navbar syncing
```

## Coding Conventions
To maintain codebase health and satisfy rigorous security scans:
1. **ES Module JavaScript**: Use standard modern ES Modules. Avoid old commonJS modules.
2. **DOM Manipulation Security**:
   - **CRITICAL**: Do **NOT** use `innerHTML`, `outerHTML`, or `insertAdjacentHTML` under any circumstances.
   - **DO USE**: `textContent` or `innerText` to insert raw text. Use `document.createElement()`, `setAttribute()`, and `appendChild()` to build structural elements.
   - **DO USE**: `element.replaceChildren()` or `element.textContent = ''` to clear an element instead of `element.innerHTML = ''`.
   - **DO USE**: `DOMParser` to parse and insert complex static structures like SVGs to avoid `innerHTML`.
3. **Vanilla CSS styling**:
   - Strictly leverage custom properties declared in `css/tokens.css` (e.g. `var(--color-primary)`). Do not hardcode magic hex values or spacing.
   - Keep WCAG AA compliance (4.5:1 text contrast).
   - Ensure `cursor: pointer` on all clickable components and add 150-300ms transitions for hovers.
4. **No Emojis for Icons**:
   - Use Lucide SVG icons instead of emojis to preserve the upscale artisan brand aesthetic.

## Local Development & Verification
- Use any standard static web server to run locally, e.g.: `npx serve thheritagecabinetry`
- Run the agentic-seo audit suite to evaluate sitemaps and meta optimization:
  ```bash
  node bin/aeo.js thheritagecabinetry/
  ```

## Reference Documentation
- [Google Labs Design Spec](/DESIGN.md): Visual parameters, palettes, typography guidelines.
- [llms.txt Index](/llms.txt): Quick maps of key page segments.
- [Skill Reference](/skill.md): Detailed API capabilities and constraints.