---
name: astro-component
description: Build one Astro component for the ai-for-dummies site from the project templates. Use when creating a primitive, block, or island, or when splitting existing markup into a component.
---

# Building an Astro component

## Decide it should exist

Three occurrences, or a name a person says out loud. Two is not enough — see
[`../../rules/componentization.md`](../../rules/componentization.md).

Then place it:

- `primitives/` — no domain knowledge (Eyebrow, Rule, Callout, CodeBlock)
- `blocks/` — composed, page-agnostic, takes props (RouteCard, PhasePanel)
- `islands/` — interactive, justified, a leaf

## Start from a template

```bash
cp .agents/templates/components/static-block.astro src/components/blocks/RouteCard.astro
# interactive? use island.astro instead
```

Templates exist so ten parallel agents produce one house style. Do not start
from a blank file.

## Write it

```astro
---
interface Props {
  number: string;
  title: string;
  summary: string;
  href: string;
}
const { number, title, summary, href } = Astro.props;
---
<article class="card">
  <b>{number}</b>
  <h2>{title}</h2>
  <p>{summary}</p>
  <a href={href}>Open chapter →</a>
</article>

<style>
  .card { display: grid; gap: 10px; padding: 22px; background: var(--paper); }
  b { color: var(--accent); font: var(--font-eyebrow); }
</style>
```

Rules that bite most often here:

- **No raw hex.** Tokens only. `check-tokens.mjs` will fail you.
- **No `client:*`** unless it is genuinely interactive, and say why in the PR.
- Keep the `gap:1px` over a coloured parent trick where the original used it —
  it is the house style, not a bug.
- Preserve every ARIA attribute from the markup you are replacing.

## Prove it

1. Render it at 560 / 800 / 1100 / 1600 px.
2. Tab to it. Focus ring visible (`outline: 3px solid #a7483f`).
3. Diff its rendered text against the markup it replaced.
4. Run [`../../checklists/before-component.md`](../../checklists/before-component.md).
5. `npm run verify` — green, with no assertion deleted.