# AGENTS.md

Instructions for AI coding agents working in this repository **or** in projects that depend on `gnexus-ui-kit`.

## If you are building UI with GNexus UI Kit

1. **Check the catalog before writing any markup**: [`docs/catalog.json`](docs/catalog.json) maps every need (button, modal, status label, ...) to its component, props and when to use it. If a component exists, use it — do not invent your own markup for what the kit already covers.
2. Read the full agent guide: [`docs/ai-guide.md`](docs/ai-guide.md) — component selection, variant/icon rules, and the recipe for building a custom component that matches the GNexus style (tokens, `hard_panel`, uppercase titles, `focus_ring`, `hover_touch`).
3. In Vue projects, use the adapter: `import { GnButton, GnModal } from "gnexus-ui-kit/vue"`. Full Vue contract: [`docs/vue/ai-usage-guide.md`](docs/vue/ai-usage-guide.md).
4. Icons are Phosphor only, always with the base class: `icon="ph-house"` in Vue, `<i class="ph ph-house"></i>` in HTML.
5. Variants are a closed set: `primary, secondary, accent, success, warning, danger, error, info`.

Quick copy-paste block for the consuming project's own CLAUDE.md/AGENTS.md is at the bottom of [`docs/ai-guide.md`](docs/ai-guide.md).

## If you are working on this repository

Follow [`CLAUDE.md`](CLAUDE.md) — it is the maintainer reference: demo sync rules (vanilla vs Vue demo must stay pixel-identical), build/verification commands (`npm run release:check`), screenshot policy, and the Vue adapter lessons. The component catalog table in CLAUDE.md is generated from `docs/catalog.json` — edit the JSON, then run `npm run gen:catalog`.

## Single sources of truth

| Source | Generated from it |
|--------|-------------------|
| `docs/catalog.json` | catalog table in `CLAUDE.md`, selection table in `docs/ai-guide.md` |
| `src/scss/_palette-colors.scss`, `_design-tokens.scss`, `_spacing.scss` | all component styling |
| `demo/partials/*.html` | both demo pages (vanilla + Vue) |