# AGENTS.md — UNDRR Shared Web Assets

Guidance for agents working on or consuming `assets.undrr.org`. Read the relevant
asset README before editing. Use canonical URLs without `/static/`; preserve
published version directories. [llms.txt](llms.txt) is the discovery index.

## Choose the references for the task

| Task | Start with |
| --- | --- |
| Build or update UI | [Mangrove guide](https://mangrove.undrr.org/llms.txt), then the [component index](https://mangrove.undrr.org/ai-components/index.json) and only the needed component details |
| Add the UNDRR header, navigation and footer | [Static UNDRR shell recipe](mangrove/static-shell.md) |
| Prototype a page for later Drupal use | [Prototype handoff](docs/prototype-handoff.md) and [page-building guide](https://mangrove.undrr.org/llms-page-building.txt) |
| Write or edit copy | [Editorial manual](https://mangrove.undrr.org/llms-editorial-manual.txt), then the relevant [content-type guide](docs/editorial-guides/README.md) |
| Configure search | [Search widget guide](https://mangrove.undrr.org/llms-search-widget.txt) |
| Assign Drupal metadata | [Metadata guidance](docs/editorial-guides/metadata.md) and [taxonomy IDs](docs/editorial-guides/taxonomy.md) |

Follow each component index entry's `detailsUrl`; do not guess short IDs such as
`stats-card`. Its ID is `components-cards-stats-card`. Before custom markup, map
each section/control to an existing component or record why it needs custom work.
Check `vanillaHtml`, `vanillaModule`, `vanillaScripts` and `requiresReact` rather
than assuming CSS supplies interaction. Prefer documented properties over broad
component overrides. Keep custom behavior scoped to the consuming page.

## Mangrove contracts

- Pin new and updated pages, templates and demos to **2.3.0**:
  `https://assets.undrr.org/mangrove/2.3.0/css/style.css`. Versioned package assets
  are populated by the build; do not commit their generated directories.
- [tokens.json](https://mangrove.undrr.org/tokens.json) covers **theme-generated
  tokens**, not every public custom property. Read its `scope`; component
  properties are in each detail file's `customProperties`, and other global
  properties, including font roles, are described in the Mangrove guide. Absence
  from the theme dictionary alone does not make a property invalid. Check the
  pinned stylesheet when validating against a release.
- Follow value format, not the property-name prefix. Channel values need
  `rgb(var(--mg-color-interactive))` or `rgb(var(--mg-color-interactive) / 0.12)`.
  Complete color expressions, such as `var(--mg-color-text-tab)`, must be used
  directly. Follow `format`/`wrapInRgb` metadata and the dictionary's wrapping rules.
- Use font roles: `--mg-font-family-text`, `-heading`, `-display`, `-ui`, `-code`.
  Use `--mg-z-index-*` for global layers; derive drawer backdrops with
  `calc(var(--mg-z-index-drawer) - 1)`.
- Button strokes use `--mg-border-color-button-primary` and
  `--mg-border-color-button-secondary` (complete colors, default `transparent`).
  Check contrast and focus on dark/hero surfaces after customization.

## Markup and copy

Use Mangrove components for controls, navigation and empty/error states; fetch
their current markup rather than copy a partial local inventory. Use `.mg-button`
with `.mg-button-primary` or `.mg-button-secondary`, and `.mg-icon-button` for
standalone icon controls. Use `.mg-icon` SVG masks rather than emoji icons.
Use `.mg-u-sr-only` for screen-reader text and the
[utility inventory](https://mangrove.undrr.org/ai-components/utilities.json) for
other utilities.

Include `<a class="mg-skip-link" href="#main">Skip to content</a>` and
`<main id="main" tabindex="-1">`. Match heading levels to the page outline.
Use sentence-case headings and labels, preserving acronyms and official brand
marks. Do not apply forced uppercase styling; override component label transforms
locally where needed until upstream defaults change. This takes precedence over
the editorial manual's current allowance for uppercase presentation.

## Verification and contribution

- `npm test`: repository checks; the current suite list is in [package.json](package.json).
  Also check affected pages, keyboard interactions and narrow viewports. Automated
  accessibility scans do not replace manual review.
- `npm run deploy-index`: regenerate README documentation viewers; preserve
  authored app indexes. `npm run generate-sitemap`: regenerate the file inventory.
  Do not hand-edit generated pages. See [local setup](README.md#local-testing).
- Branches use `<issue-number>-<short-description>`. Commit subjects **and MR
  titles** use `undrr/web-backlog#<issue-number>: <Description of at least 15 characters>.`
  Enable `git config core.hooksPath .githooks`; validate the MR title with
  `sh scripts/validate-subject.sh "$title" "Merge request title" --merge-request`.
- Follow [CONTRIBUTING.md](CONTRIBUTING.md) for draft-title handling, new pipelines
  after title changes, and submission. Target `main`, enable squash and source
  branch removal, and reuse the subject as the title for a single-commit MR.