statewave-web copilot-instructions.md

Copilot / AI agent instructions for statewave-web

These conventions should be followed when generating or modifying code in this repository. They reflect deliberate UI/UX decisions, not stylistic preferences.

---

Heading anchors (mandatory for all section titles)

Every <h1> / <h2> / <h3> that introduces a navigable section of a page must be rendered with the <Heading> component (src/components/Heading.tsx) — never as a raw <h2> tag.

import { Heading } from '../components/Heading'

// Correct
<Heading id="core-loop" className="text-2xl font-bold text-theme-primary mb-12">
  The core loop
</Heading>

// Incorrect — no anchor affordance, no shareable link
<h2 className="text-2xl font-bold text-theme-primary mb-12">The core loop</h2>

Why

Visitors should be able to deep-link any section of the marketing site. The component renders a permanently visible # icon next to the title; clicking it copies an absolute URL with the section hash to the clipboard. Without it, sharing a specific subsection means screenshotting or asking a teammate to scroll.

Rules

1. Always pass an explicit id. Slug-style: lowercase, dashes, no stop words. Stable across copy edits — once shipped, the id is part of the URL contract. Examples: core-loop, privacy, who-this-is-for, vs-alternatives.
2. One id per page. Don't reuse an id between two <Heading> instances or between a <Heading> and a <Section id=...> — duplicate ids are invalid HTML and break browser anchor resolution.
3. Default level is 2. Pass level={1 | 3 | 4} when needed. Page-title <h1> doesn't need <Heading> (a hero title is rarely deep-linked).
4. Inherit existing typography via className — pass the same Tailwind classes the original <h2> used. The component does not impose a font size or weight; it only adds the anchor button.
5. scroll-mt-20 is built in so anchor jumps land below the fixed navbar. Do not add scroll offsets to the className.