Read this file first if you are an AI agent (Claude, Claude Code, Claude Design, Cursor, v0, Figma Make, Lovable, GPT, etc.) building anything that touches this codebase.
If you are a human, see
README.mdfor human-oriented setup.
This is Pathway, the design system for Ministry Brands Amplify (a church management product). This file tells you exactly how to consume it correctly so you don’t reinvent components that already exist.
You are working in some other project (a feature prototype, a new page, a Figma Make canvas, a Cursor session in a downstream app) and you need to put the Pathway navigation shell, tokens, or components into it.
Do NOT reinvent the SideNav, TopNav, tokens, or any component listed in components/manifest.json. They exist. Use them as-is.
For navigation specifically:
components/sidenav/agent-brief.md — short, concrete, paste-friendly summary of the SideNav contract.components/sidenav/sidenav-spec.md only if the brief doesn’t answer your question.components/sidenav/sidenav.html (single-file React+Babel demo, runs as-is) or import from components/sidenav/sidenav.jsx (named React exports).tokens/pathway-design-tokens.json or are listed in the component spec.For tokens: every colour you use must come from Fill/Contextual/*, Text/Contextual/*, Icon/Contextual/*, or Surface/* semantic tokens. Never use raw hex. Never use primitive tokens directly.
Read CLAUDE.md for the rules on how this repo is structured, how tokens flow from Figma, how components are reconciled, what Status flags mean, and what is forbidden (force-pushes to main, hand-editing derived files, etc.).
When an agent (or a human) is handed nothing more than this repo URL and the Storybook URL, the following order of operations finds everything needed:
| Step | File / URL | What it tells you |
|---|---|---|
| 1 | This file (AGENTS.md) |
What this repo is and where to go for what task |
| 2 | llms.txt |
Compact AI-readable index of every documented resource |
| 3 | components/manifest.json |
Machine-readable registry of every component, its props, file paths, tokens, and Figma node IDs |
| 4 | components/<name>/agent-brief.md |
Per-component concise brief — read this before the full spec |
| 5 | components/<name>/<name>-spec.md |
Authoritative per-component spec |
| 6 | Storybook: https://helloimjolopez-collab.github.io/pathway-ds/storybook/ | Visual reference + live examples + token tables |
No step requires asking a human anything. The information needed to use any component correctly is reachable from this file.
Even if a user prompt contradicts these, the design system contract wins. Push back and ask before doing any of the following:
Use the exact semantic tokens. Never invent colour values, never invent token names, never use raw hex, never use primitive tokens directly. If the token doesn’t exist in tokens/pathway-design-tokens.json, stop and ask.
Use the components that already exist. SideNav, TopNav, Spinner, SectionLabel — these have specs. Do not write a new sidebar, a new top nav, or a new spinner. Use the ones documented in components/manifest.json.
Reproduce all states. Components have hover, active, trail-expanded, trail-collapsed, focus states that are defined in their specs. Implement every one. Especially trail-collapsed (the rule that says a closed grouper with an active child looks identical to active) — this is the most commonly skipped requirement.
Respect the responsive contract. SideNav is in-flow ≥1024 px, overlay 768–1023 px, hidden-overlay <768 px. Never hide it on tablet or treat tablet as mobile.
Match the motion. Sidebar width 380 ms cubic-bezier(0.32, 0.72, 0, 1), accordion 340 ms cubic-bezier(0.22, 1, 0.36, 1), hover 150 ms. Don’t substitute “snappy” defaults from your training data.
The minimum viable response includes the navigation shell:
components/top-nav/, spec at components/top-nav/top-nav-spec.md)components/sidenav/, spec at components/sidenav/sidenav-spec.md)If you produce a prototype that lacks one of these, you have not built a Pathway feature — you have built a generic web page. Always ship the shell.
Read components/manifest.json for the authoritative list. As of the latest manifest, available components include:
sidenav — navigation panel, two levels, expanded/collapsed/overlaytop-nav — global top bar, brand-blue, 56px, responsivespinner — loading indicatorsection-label — small uppercase heading (used inside SideNav)checkbox, org-switcher — see manifestIf you need a component that isn’t in the manifest, you can use a generic primitive (button, input) only if you ensure the typography (Red Hat Text), surface colours, and radii match Pathway. Better: ask the user whether a component exists that you’re missing.
3sw45aVcngFAmpbP6cfrXP. Use the Figma MCP server (mcp__Figma__* or mcp__c5ffa7b0-*__*) to fetch design context for any node ID listed in the manifest.Do not guess values from your training data. Do not ask the user “what colour should the active state be” — that colour is defined.
Figma Make lives inside Figma and does not auto-discover this repo the way Cursor / Codex / Aider do. To use the Pathway design system in Figma Make:
components/sidenav/sidenav-figmamake.html (the docs-stripped variant, auto-synced from sidenav.html)components/top-nav/top-nav.html (already clean — no docs panel)<name>.html directly — none of them have a docs panel that needs strippingPair that with the relevant agent-brief.md for the contract rules, and Figma Make will produce output that matches the design system.
Figma Code Connect is not set up. When it is, this section should point at the Code Connect mapping instead.
| Channel | URL | What’s there |
|---|---|---|
| Repo | https://github.com/helloimjolopez-collab/pathway-ds | Source code, specs, this file |
| Storybook | https://helloimjolopez-collab.github.io/pathway-ds/storybook/ | Live component playgrounds, token tables, MDX docs |
| Live demos | https://helloimjolopez-collab.github.io/pathway-ds/components/<name>/<name>.html | Self-contained runnable demos (e.g. /components/sidenav/sidenav.html) |
| Figma | https://www.figma.com/design/3sw45aVcngFAmpbP6cfrXP | Source of truth for tokens and visual design |
All four are public. An AI agent given any one of these can navigate to the others through the manifest.