docs: strengthen RAC convention guidance in AGENTS.md#1929
Conversation
🦋 Changeset detectedLatest commit: 124cc8c The changes in this PR will be included in the next version bump. This PR includes changesets to release 0 packagesWhen changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
There was a problem hiding this comment.
https://react-aria.adobe.com/getting-started#working-with-ai also has things that might be useful for folks contributing to Launchpad!
|
|
||
| - **Use existing LaunchPad components and packages** (`@launchpad-ui/components`, `@launchpad-ui/icons`, etc.). Never create a custom component when a LaunchPad equivalent exists. | ||
| - **React Aria Components is the foundation.** Wrap and theme RAC primitives; do not reimplement keyboard/ARIA/focus behavior. The sanctioned escape hatches are `defaultProps`, slots, `useContextProps`, and render-props composition — see https://react-aria.adobe.com/customization. (`docs/adr-008-component-foundation.md`) | ||
| - **React Aria Components is the foundation.** Wrap and theme RAC primitives; do not reimplement keyboard/ARIA/focus behavior. The sanctioned escape hatches are `defaultProps`, slots, `useContextProps`, and render-props composition — see https://react-aria.adobe.com/customization. **Follow RAC's API conventions, not only its behavior:** when adding a prop, variant, or composition pattern, mirror the names and shapes RAC — and its reference implementation, [React Spectrum](https://react-spectrum.adobe.com) — already use (e.g. `description`/`errorMessage` for helper and validation text, `isDisabled`/`isInvalid` booleans, slot-based composition) rather than inventing new ones. Deviate only with a reason noted in the PR. (`docs/adr-008-component-foundation.md`) |
There was a problem hiding this comment.
Not sure how much this matters ultimately, but RAC added markdown versions of all their pages, accessible by appending .md to any URL, like https://react-aria.adobe.com/customization.md.
Again, not that I've measured anything here, but if the agent actually does decide to go read the docs, the markdown version would eat up fewer tokens, so you may want to use that version for links here.
There was a problem hiding this comment.
I saw that! They've also got a 'copy for LLM' button that also copies a docs page as markdown. Great idea, I will add this to our Jira backlog.
4 participants
Summary
Tightens the Component standards section of
AGENTS.mdso agents proactively follow and reference React Aria Components (RAC) when designing components — addressing a gap where the existing guidance covered only behavior ("don't reimplement keyboard/ARIA/focus"), not API shape or design-time reference.Two edits:
description/errorMessage,isDisabled/isInvalid, slot-based composition) rather than inventing new ones. Deviate only with a documented reason.Both additions are phrased as tool-agnostic repo convention (no tool- or assistant-specific wording), since
AGENTS.mdis the cross-tool source of truth read by multiple agents and contributors.Context: this came out of investigating
description-prop drift between the React components and the Figma library (tracked in DSYS-194). The guidance change is the durable, general fix; the component-level work is separate.Docs-only change to a root file (no package touched) — included an empty changeset so the changeset gate passes without a version bump.
Screenshots (if appropriate)
N/A — documentation only.
Testing approaches
pnpx @changesets/cli status --since=main→ exit 0 (no packages bumped; gate satisfied).Note
Low Risk
Docs and an empty changeset only; no runtime, package, or build behavior changes.
Overview
Documentation-only update to the Component standards section in
AGENTS.mdso AI agents and contributors align LaunchPad APIs with React Aria Components (RAC), not only accessibility behavior.The existing “React Aria Components is the foundation” bullet now requires matching RAC/React Spectrum prop names and composition (e.g.
description/errorMessage,isDisabled/isInvalid, slots) and documenting any intentional deviation in the PR.Two new bullets tell agents to use RAC/React Spectrum as the first design reference when adding components or props (to reduce API drift vs Figma), and to load RAC docs as Markdown (
.mdURLs) when fetching them programmatically.An empty changeset (
.changeset/agents-md-rac-convention-guidance.md) satisfies the changeset gate without bumping packages.Reviewed by Cursor Bugbot for commit 124cc8c. Bugbot is set up for automated code reviews on this repo. Configure here.