# gaipack — AI Working Protocol (AGENTS.md) > **Source of Truth:** The AI working protocol — norm priority, stop process, fail-loud reporting, checkpoints, and the core self-audit — for UI work on the gaipack site's design system. > > **Refer elsewhere for:** > > - Visual tokens, brand principles, high-level component visuals → `DESIGN.md` > - Implementation details (props, code examples, technology-specific prohibitions) → `COMPONENTS.md` > - Page and section patterns → `PATTERNS.md` > - Change history and recorded deviations → `CHANGELOG.md` > - Repository-wide engineering rules (commands, CMS, sync with the upstream repository) → the **repository-root** `AGENTS.md` (a different file — see "Two AGENTS.md files" below) > - Service facts, numbers, and wording → the service definitions under `docs/services/` (synced from the upstream source of truth; never edited in this repository) > > This file says **how the AI behaves**, not **what to build**. It contains no visual values and no component specifications. ## Why this file is named AGENTS.md, not CLAUDE.md The design system's four norm documents (`DESIGN.md` / `COMPONENTS.md` / `PATTERNS.md` / this file) are meant to be read by any AI coding agent — Claude Code, GitHub Copilot, Cursor, Gemini CLI. Naming the behavior file after one vendor's product would contradict the tool-and-agent independence this design system exists to provide, and it would conflict with gaipack's own convention: internally, `AGENTS.md` is the single source of truth for AI working rules, and a project's `CLAUDE.md` — where one exists — is only a thin pointer that tells Claude Code to go read `AGENTS.md` (this repository's own root `CLAUDE.md` does exactly that; GitHub Copilot points at the same file via `chat.useAgentsMdFile`). `AGENTS.md` is also becoming a cross-tool convention outside gaipack — several coding agents look for a file by that exact name. This file follows both precedents. ### Two AGENTS.md files in this repository This repository has two files named `AGENTS.md`, at different scopes: | File | Scope | Content | | --- | --- | --- | | `/AGENTS.md` (repository root) | The whole repository | Commands, architecture, CMS configuration, sync rules with the upstream repository | | `/public/AGENTS.md` (this file) | The design system only | AI working protocol for UI implementation — reading order, stop process, self-audit | They are not duplicates and do not conflict: the root file governs engineering work in general, this file governs UI implementation specifically, and this file's own "MANDATORY PRE-FLIGHT" section is what an agent reads once it is doing design-system work. Don't merge them. --- ## 1. MANDATORY PRE-FLIGHT When asked to implement or change UI, read in this order before writing code: 1. **The requirement** — the issue, PR description, or request (fix the scope) 2. **`PATTERNS.md`** — does an existing page or section pattern apply? 3. **`COMPONENTS.md`** — which components and props are available (§1 Primitives / §1.5 Common / §2 Layout) 4. **`DESIGN.md`** — visual tokens, brand principles, high-level component visuals 5. **`docs/services/.md`** — when the change touches service copy, numbers, or claims > Do not write code before reading. "I roughly know it" is an assumption. > Do not touch files or components outside the scope of the requirement (surgical changes). ### 1.1 Inference rules (absolute rules for AI judgment) 1. **Unspecified = default** - If the requirement does not specify a variant, use the component's default (`COMPONENTS.md`) - "Nothing was specified, so I chose something else" and "I picked the more prominent one" are prohibited - In particular, never promote a CTA to `primary` on your own; one primary action per screen 2. **Every judgment follows the decision tables in `COMPONENTS.md` / `PATTERNS.md` / `DESIGN.md`** - Deciding from "AI experience", "general practice", or "other products do it this way" is prohibited - If a decision flow reaches [STOP] or a condition is not in a mapping table, move to §3 (no autonomous continuation) 3. **Dark first, then light** - Write the dark look in base classes, then add `light:` overrides before declaring the change complete. A dark-only change is not complete 4. **Facts come from the source of truth** - Numbers, results, prices, and claims in the UI come from `docs/services/`. Never invent, round up, or strengthen them --- ## 2. Norm priority (on conflict the higher row wins) | Priority | Norm | Enforcement | | --- | --- | --- | | 1 | Accessibility (WCAG AA contrast, focus visibility, 44px tap targets, `aria-label` on icon-only controls) | Reject | | 2 | Lint syntax rules (`pnpm lint` = Biome on the changed files; `pnpm textlint` for Japanese copy) | Auto-reject | | 3 | `DESIGN.md` YAML tokens (colors / typography / spacing / rounded / components) | Reject on implementation | | 4 | `npx @google/design.md lint public/DESIGN.md` unexpected errors (expected warnings are listed in `DESIGN.md §11.4`) | Auto-reject | | 5 | `DESIGN.md` Markdown body (usage mappings, high-level visual principles, Do's and Don'ts) | Self-audit | | 6 | `COMPONENTS.md` / `PATTERNS.md` | Supporting reference | | 7 | Official documentation of the UI library (shadcn/ui, Tailwind CSS) | Reference only | | 8 | General AI knowledge | Lowest | **When you find a contradiction, do not average.** Choose the higher norm and report the lower contradiction as "⚠️ Contradiction detected: [location]". Resolving contradictions automatically is prohibited. > Legacy notations that `DESIGN.md` tolerates (e.g. `text-[#B9C2CC] light:text-content-muted`) may stay where they are; new work uses tokens. Do not mass-replace them unless the requirement asks for it. --- ## 3. Stop process When any of the following applies, **stop immediately** and report in this format: ``` [STOP] Reason: Requirement location: Closest existing UI: Proposal: A) / B) / C) ``` **When a component name is ambiguous** (an external framework name, an ARIA role, a design-tool name, a Japanese nickname), present candidates: ``` [NAME CHECK] Received name: "" (issue L__ / design file / verbal) Candidates: A) — B) — C) None of the above (new component) Which one is intended? ``` **Typical cases:** "button" → A) `` (marketing action) / B) `