# AGENTS.md — UNDRR Shared Web Assets & Mangrove 2.0 > Practical guidance for AI coding agents (Cursor, Copilot, Antigravity, Claude, ChatGPT) working on or consuming assets from the UNDRR Asset Library (`assets.undrr.org`). --- ## Machine-Readable Specifications & Context Mangrove publishes static, machine-readable specifications and token contracts after each Storybook deploy: | Resource | URL | Purpose | |---|---|---| | **Mangrove `llms.txt`** | [`https://mangrove.undrr.org/llms.txt`](https://mangrove.undrr.org/llms.txt) | Complete Mangrove 2 design system guide, token contracts & markup patterns | | **Component Index** | [`https://mangrove.undrr.org/ai-components/index.json`](https://mangrove.undrr.org/ai-components/index.json) | Complete catalog of available components and their schema endpoints | | **Per-Component Details** | `https://mangrove.undrr.org/ai-components/{id}.json` | Individual schema, HTML examples, and modifiers for a component (`button`, `card`, `table`, `tree`, `breadcrumb`, `tag`, `details`, `empty-state`, `stats-card`, etc.) | | **Design Tokens** | [`https://mangrove.undrr.org/tokens.json`](https://mangrove.undrr.org/tokens.json) | Complete CSS custom properties / token definitions | | **CSS Utilities** | [`https://mangrove.undrr.org/ai-components/utilities.json`](https://mangrove.undrr.org/ai-components/utilities.json) | Utility class inventory (`.mg-u-*`) | | **Editorial Manual** | [`https://mangrove.undrr.org/llms-editorial-manual.txt`](https://mangrove.undrr.org/llms-editorial-manual.txt) | Style rules for UI copy and docs: capitalization, punctuation, numbers and dates, UNDRR terminology, inclusive language | | **Writing guides** | [`https://assets.undrr.org/docs/editorial-guides/README.md`](https://assets.undrr.org/docs/editorial-guides/README.md) | Content-type writing guides (news, events, publications, blogs) and metadata guidance for undrr.org and PreventionWeb; mechanics defer to the editorial manual | | **Writing agent instructions** | [`https://assets.undrr.org/docs/editorial-guides/ai-agent-instructions.md`](https://assets.undrr.org/docs/editorial-guides/ai-agent-instructions.md) | Instructions to paste into an AI writing assistant: which guide answers which question, priority when guidance conflicts, core mechanics rules | | **Writing agent recipes** | [`https://assets.undrr.org/docs/editorial-guides/agent-recipes.md`](https://assets.undrr.org/docs/editorial-guides/agent-recipes.md) | Which guide files to upload to an AI tool that can't connect to SharePoint, with ready-made setups for common editorial jobs | | **Taxonomy reference** | [`https://assets.undrr.org/docs/editorial-guides/taxonomy.md`](https://assets.undrr.org/docs/editorial-guides/taxonomy.md) | Theme, hazard, country and region term IDs, generated from the production taxonomy | | **Page building** | [`https://mangrove.undrr.org/llms-page-building.txt`](https://mangrove.undrr.org/llms-page-building.txt) | Building landing pages in the UNDRR Drupal Gutenberg editor: custom blocks, attributes, markup and patterns | | **Search widget** | [`https://mangrove.undrr.org/llms-search-widget.txt`](https://mangrove.undrr.org/llms-search-widget.txt) | Configuring the UNDRR Search Widget block: settings, query syntax and field names | | **Asset Library `llms.txt`** | [`https://assets.undrr.org/llms.txt`](https://assets.undrr.org/llms.txt) | Index of the asset library: directory conventions, asset READMEs, the writing guides and links to the Mangrove guides | --- ## Coding Guidelines for this Repository ### 1. GitLab Commit Message Convention Commit messages are validated by a repository hook and **must** match: ```text undrr/web-backlog#: . ``` - Must start with `undrr/web-backlog#: ` - Must end with a period (`.`) - Example: `undrr/web-backlog#3026: Adopt Mangrove empty-state, sortable table, and sr-only classes.` ### 2. Mangrove Token & CSS Syntax Rules - **Color tokens are sRGB channel triplets**: Always wrap in `rgb()`, e.g. `color: rgb(var(--mg-color-interactive));` or `background: rgb(var(--mg-color-interactive) / 0.12);`. Bare `var(--mg-color-...)` without `rgb()` is invalid CSS and will be silently dropped. - **Font family roles**: Use semantic role variables rather than font family names: - `--mg-font-family-text` - `--mg-font-family-heading` - `--mg-font-family-display` - `--mg-font-family-ui` - `--mg-font-family-code` - **Z-index layers**: Use `--mg-z-index-*` tokens (`-behind`, `-nav`, `-sticky`, `-nav-toggle`, `-header`, `-drawer`, `-dropdown`, `-modal`, `-toast`). Backdrops are computed via `calc(var(--mg-z-index-drawer) - 1)`. - **Button stroke tokens**: Use `--mg-border-color-button-primary` and `--mg-border-color-button-secondary` (default `transparent`) for stroke contrast on dark or hero surfaces (`--mg-border-color-button-*`). ### 3. Component & Markup Standards - **Breadcrumbs**: Use `.mg-breadcrumb` (``). - **Buttons & Icon Buttons**: Use `.mg-button` and `.mg-button-primary` / `.mg-button-secondary`. Standalone icon buttons use `.mg-icon-button` (36px `inline-flex` square). - **Data Tables**: Use `` wrapped in `
`. Use `.mg-table__th--sticky`, `.mg-table__th--sortable`, `.mg-table__td--numeric`, and `.mg-table__td--code`. - **Empty States**: Use `.mg-empty-state`, `.mg-empty-state__media`, `.mg-empty-state__title` (choose heading level `h2`–`h4` fitting the page outline), and `.mg-empty-state__description`. - **Trees**: Use `.mg-tree`, `.mg-tree__item`, and `.mg-tree__label-container`. Target tree item DOM nodes via `data-mg-treeitem-id`. - **Screen-Reader Utility**: Use `.mg-u-sr-only` instead of custom `.visually-hidden`. - **Skip Links**: Use `Skip to content` with `tabindex="-1"` on `
`. - **Icons**: Use `.mg-icon` SVG mask patterns (`.mg-icon-search`, `.mg-icon-folder`, `.mg-icon-folder-open`, `.mg-icon-menu`, etc.) rather than unicode emojis. ### 4. Build & Verification Commands - `npm run generate-sitemap`: Rebuilds `sitemap.html` using the zero-dependency generator. - `npm test`: Runs test suite (`mangrove-version-filter.test.sh` and `deploy-index.test.js`). - `npm run deploy-index`: Updates generated `index.html` documentation pages from READMEs.