UI: Add initial agents guidance mapping to contributing guidelines

[aduth]

What?

Adds an initial packages/ui/AGENTS.md agents context document as a compacted snapshot of existing contributing guidelines, adding a new "Design Principles" section to the contributing guidelines in the process.

Why?

Ultimately, the goal here is to try to reduce the amount of back-and-forth review that can happen for contributions to the design system based on basic tenets of building components, and reducing the up-front effort of the contributor in the process.

This also keeps us accountable to the principles around review feedback being documented somewhere, and not trapped within any one individual or group's personal knowledge.

We already have contributing guidelines, but these aren't readily accessible to an AI agent. And even if they were, they're quite verbose and written for human readers to rationalize decisions.

How?

First, I'll caveat to say this isn't meant to be exhaustive. It's a starting point.

But what was devised here was based on real-world observations on things that either come up in review or are flagged as intentional differences from how alternative equivalent components had been written (e.g. see #81358 "Differences from @wordpress/components").

• “Only add components when generic/reusable; if it can live in a higher-level package, it should.”
  • Examples:
    • "This component is essentially a pattern of existing components, and my instinct tells me it belongs to a higher level of abstraction."
    • "If it can live somewhere else, it should"
• “Prefer composing existing @wordpress/ui components over bespoke markup and styles.”
  • Examples:
    • "Use existing @wordpress/ui components [...] remove the need for custom markup/styles"
• “Components should not ship with outer margins.”
  • Examples:
    • "No default margin [...] callers can add spacing via className or style where needed."
• “Use semantic tokens; avoid hardcoded colors/spacing and arbitrary value props.”
  • Examples:
    • "I'd try to replace these all with @wordpress/theme style tokens."
    • "Differences from @wordpress/components [...] WPDS tokens"
• "Use interactive for clickable UI, content for static text; use -active/-disabled, don’t mix tones across states.”
  • Examples:
    • "Mixing and matching the tone (ie. neutral in the resting state, and brand in the hover state) should be avoided when using the tokens."
    • "We shouldn't mix and match these [states] categories"
    • "Per WPDS token guidance, we shouldn't mix and match: [...] content and interactive elements [...] neutral and brand tones for different states of the same UI"
• “Animation should respect prefers-reduced-motion.”
  • Examples:
    • "Differences from @wordpress/components [...] prefers-reduced-motion"

Testing Instructions

Review documents for accuracy.

Use of AI Tools

Research and implementation with Cursor IDE + Auto model, given related context for preexisting examples from pull requests and existing guidance. AI-produced content was reviewed for accuracy and manually edited accordingly.

[aduth]

I'll also caveat that some of this could and probably should be linted with ESLint rules as a better quality gate. For example, we could probably lint to encourage the use of design tokens for specific properties like background-color, width, font-size, etc. Again, the intention here is a light lift to get something in place for agents to be bound by.

[github-actions]

The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the props-bot label.

If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message.

Co-authored-by: aduth <aduth@git.wordpress.org>
Co-authored-by: ciampo <mciampini@git.wordpress.org>

To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook.

[ciampo]

Should we coordinate the changes from this PR with the existing #80597?

Apart from that, a couple of higher-level comments:

• I'm not sure about the choice to duplicate CONTRIBUTING.md into AGENTS.md. Shouldn't we generally avoid duplicating documentation, and instead just link to the document?
• re. the mention of the ui package as “the home for design system components", should we instead consider the DS as spread across components, dataviews, theme and ui packages?

[aduth]

Should we coordinate the changes from this PR with the existing #80597?

It's a good question. Yes, we should. I had also considered that this might supersede some of the previous AGENTS.md-specific efforts like in #78166 (partial) and #77264.

I think we could want both skills and AGENTS.md, and the way I had been thinking about it is skills = "here's how to navigate a specific workflow", AGENTS.md = "here's how to work with code in this folder".

What you've implemented in #80597 could likely be pretty successful at solving the underlying pain point, possibly even to the extent that we wouldn't need AGENTS.md, particularly if it ends up being redundant and duplicative of contribution guidelines. I think it hinges a lot on the description ("Use when planning or implementing a safe @wordpress/components, @wordpress/ui, or @wordpress/theme change [...]" from #80597 feels pretty good to me as a cue for agents) and, more importantly, whether agents follow links to and correctly absorb context from contributing guidelines. In my pull request, it was somewhat assumed that agents couldn't necessarily be trusted with this latter point, hence the partial redundancy.

In any case, I think regardless how we choose to proceed, one of the driving factors here was taking the real-world feedback we've seen and translating it into what an agent will most obviously and concisely absorb into its context when working in these packages. I'd like to make sure that the examples included here are captured.

[ciampo]

Yes, it feels like we should agree on the approach and pick the best of each currently opened PR (this PR, #80597, #78166, #77264)

whether agents follow links to and correctly absorb context from contributing guidelines. In my pull request, it was somewhat assumed that agents couldn't necessarily be trusted with this latter point, hence the partial redundancy.

In my experience, using AGENTS.md and skills as a way to point to existing documentation works quite well — of course, that documentation needs to be clear, understandable, and not overly large as a file (breaking it down into multiple files may help).

One thing that we should also work on is a way to eval these changes systematically (@jeryj worked on a potential approach in #80812), otherwise it's quite hard to understand their impact

[aduth]

Maybe as a starting point, we can just add AGENTS.md as a minimal pointer to CONTRIBUTING.md, and add the missing "design principles" sourced from the recurring friction points highlighted in my original pull request message. And in parallel we can continue development of the skills you've proposed. Would that work?

One of my biggest concerns right now is that we've written substantial documentation in packages/ui/CONTRIBUTING.md and packages/components/CONTRIBUTING.md, but I have little confidence that agents are even aware of its existence.