Skip to content

AGENTS.md

Latest commit

 

History

History
72 lines (50 loc) · 5.06 KB

AGENTS.md

File metadata and controls

72 lines (50 loc) · 5.06 KB
Raw

AGENTS.md

Guidance for working in the react-spectrum monorepo.

Repo layout

The repo is layered. Changes flow up from the lowest level:

  • @internationalized/* and @react-stately/* — the two lowest levels (i18n utilities and state management).
  • @react-aria/* — behavior and accessibility hooks built on the above.
  • react-aria-components (RAC) and some React Spectrum v3 (RSP) — component layer built on the hooks.
  • RSP S2 (@react-spectrum/s2) — the Spectrum 2 design system, built on RAC, the highest level.

Toolchain guardrails

This repo does not use the conventional JS toolchain — use these, don't swap in defaults:

  • Format with yarn format (oxfmt), not Prettier. Lint with yarn lint (oxlint), not ESLint. Type-check with yarn check-types (tsc, TypeScript 7's native compiler). Build with yarn build (Parcel), not rollup/tsc.
  • Don't run yarn chromatic / yarn chromatic:forced-colors — maintainers run the VRT suites.
  • All commonly used commands live in the root package.json scripts.

Visual verification with Storybook and docs

When you need to inspect a component or verify a visual/interaction change, use the Parcel 3 development commands. They start much faster than their non-Parcel-3 counterparts:

Prefer a Storybook story's isolation URL over the manager UI when verifying a specific example. It loads only the story canvas, which is faster and easier to inspect or automate:

http://localhost:9003/iframe.html?id=accordion--default&viewMode=story
http://localhost:6006/iframe.html?id=accordion--example&viewMode=story

Story IDs usually follow <title>--<export-name>, so use the obvious ID when it is clear. If the title/name is customized, the ID is uncertain, or the story does not render, look up the exact id in the relevant Storybook's /index.json. Filter the index locally instead of printing the whole file. Keep the URL quoted when passing it to a shell command because it contains &.

Run only one of the Parcel 3 Storybooks at a time: both public Storybook servers use an internal Parcel server on port 3000. There is currently no Parcel 3 counterpart for the legacy React Spectrum docs command (yarn start:docs), so use that only when those legacy docs are specifically needed.

Contributing

  • Match the surrounding code — follow the naming, structure, and patterns of neighboring files.
  • Commit format — use conventional-commit prefixes (fix:, feat:, chore:, docs:) as seen in the git history.

Filing GitHub issues

This repository uses GitHub issue forms defined in .github/ISSUE_TEMPLATE/ (Bug_Report.yml, Feature_Request.yml, Documentation.yml, Feedback.yml). Blank issues are disabled, and CONTRIBUTING.md asks contributors to follow the templates. Please do the same when filing on a user's behalf:

  • Search first. Check existing open and closed issues to avoid duplicates.
  • Prefer the web flow so the correct form is applied: https://github.com/adobe/react-spectrum/issues/new/choose
  • If filing via the gh CLI, replicate the template's fields in the body. gh issue create --template does not render these YAML issue forms, so passing --template alone will not produce a valid issue. Instead, fill in the chosen template's fields manually. For a bug report (Bug_Report.yml), include:
    • a general summary
    • Expected Behavior
    • Current Behavior
    • Possible Solution (optional)
    • Context (how it affects you / what you're trying to accomplish)
    • Steps to Reproduce, a minimal repro, ideally a StackBlitz
    • Version, Browsers, Operating System
  • Questions and open-ended discussion belong in Discussions, not the issue tracker.
  • Security issues must not be filed on the public tracker. Follow the process in CONTRIBUTING.md.

Task-specific workflows

Read the relevant file before starting that kind of work (other agents: read the file directly; Claude will surface it):