Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs: add intent-specific pull request templates (#6257)

Cindy Zhang6c5304cd590a
diff --git a/.github/PULL_REQUEST_TEMPLATE/bug-fix.md b/.github/PULL_REQUEST_TEMPLATE/bug-fix.md
new file mode 100644
index 0000000000..bb06f03134
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE/bug-fix.md
@@ -0,0 +1,31 @@
+<!-- Use this template only when the primary intent is to restore broken behavior. -->
+
+## User impact
+
+<!-- Who encounters the defect, in what state, and what fails? -->
+
+## Expected behavior and authority
+
+<!-- Link the current contract, standard, documented promise, or regression history that defines the expected outcome. -->
+
+## Smallest restoration
+
+<!-- Explain the narrow fix. Remove or split new API, visual affordances, layout changes, cleanup, and other tagalongs. -->
+
+## Evidence
+
+- Reproduction before the change:
+- Result after the change:
+- Representative unchanged path:
+- Regression test or other mutation-sensitive proof:
+
+## Scope
+
+- [ ] One defect is restored.
+- [ ] Separable contradictory or unsettled tagalongs were removed or split.
+- [ ] No new public API, visual representation, default, or interaction model is hidden under the bug-fix label.
+- [ ] Public text and artifacts contain no internal Meta context.
+
+## Testing
+
+<!-- Commands and real-browser states where behavior depends on layout, pixels, focus, scrolling, hit testing, or input modality. -->
diff --git a/.github/PULL_REQUEST_TEMPLATE/documentation.md b/.github/PULL_REQUEST_TEMPLATE/documentation.md
new file mode 100644
index 0000000000..a9d48f326a
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE/documentation.md
@@ -0,0 +1,27 @@
+<!-- Use this template only when documentation is the primary intent. -->
+
+## Reader impact
+
+<!-- Who is misled, blocked, or missing guidance, and what can they do after this change? -->
+
+## Source of truth
+
+<!-- Link the code, current contract, generated schema, or other authority the documentation must match. -->
+
+## Correction
+
+<!-- State the incorrect or missing guidance and the exact corrected meaning. -->
+
+## Evidence
+
+<!-- Rendered page, generated output, link/check result, or example validation. -->
+
+## Scope
+
+- [ ] This PR changes documentation only, or names every necessary generated artifact.
+- [ ] Runtime, API, visual, and policy changes were removed or split.
+- [ ] Public text and artifacts contain no internal Meta context.
+
+## Testing
+
+<!-- Documentation checks, generated-file verification, link checks, or rendered review. -->
diff --git a/.github/PULL_REQUEST_TEMPLATE/maintenance.md b/.github/PULL_REQUEST_TEMPLATE/maintenance.md
new file mode 100644
index 0000000000..aaff259181
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE/maintenance.md
@@ -0,0 +1,29 @@
+<!-- Use this template for CI, tests, tooling, refactors, dependencies, or repository maintenance with no intended product behavior change. -->
+
+## Maintainer impact
+
+<!-- What operational or engineering problem occurs, for whom, and under what conditions? -->
+
+## Intended invariant
+
+<!-- Link current tooling/architecture authority or state the maintained behavior that must remain unchanged. -->
+
+## Change
+
+<!-- Explain the smallest mechanism change and why it belongs in maintenance rather than product behavior. -->
+
+## Evidence
+
+- Failure before the change:
+- Success after the change:
+- Product/runtime behavior verified unchanged:
+
+## Scope
+
+- [ ] No intended public API, product behavior, visual direction, or policy change.
+- [ ] Product changes discovered during the work were removed or split.
+- [ ] Public text and artifacts contain no internal Meta context.
+
+## Testing
+
+<!-- Commands, failure injection, CI dry run, generated output, or performance evidence. -->
diff --git a/.github/PULL_REQUEST_TEMPLATE/new-feature.md b/.github/PULL_REQUEST_TEMPLATE/new-feature.md
new file mode 100644
index 0000000000..95760f3bb7
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE/new-feature.md
@@ -0,0 +1,32 @@
+<!-- Use this template only when adding a new user-facing capability is the primary intent. -->
+
+## User need
+
+<!-- Who needs this capability, in what state, and why existing composition does not solve it? -->
+
+## Current specification
+
+<!-- Link the current owner and exact decision admitting the capability and any public API. -->
+
+## Public delta
+
+<!-- List observable behavior, API/types/defaults, compatibility, theming, and accessibility changes. Include representative consumer syntax when API changes. -->
+
+## Design and alternatives
+
+<!-- Explain the chosen model and the meaningful alternatives rejected by the specification. -->
+
+## Evidence
+
+<!-- Prove default, configured, composed, edge, accessibility, visual, and unchanged legacy paths as applicable. -->
+
+## Scope
+
+- [ ] One capability is added.
+- [ ] Unrelated fixes, cleanup, and policy changes were removed or split.
+- [ ] Consumer docs, focused tests, and migration evidence ship with the feature.
+- [ ] Public text and artifacts contain no internal Meta context.
+
+## Testing
+
+<!-- Commands and real-browser/state matrix. -->
diff --git a/.github/PULL_REQUEST_TEMPLATE/other.md b/.github/PULL_REQUEST_TEMPLATE/other.md
new file mode 100644
index 0000000000..d25729c90d
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE/other.md
@@ -0,0 +1,27 @@
+<!-- Use this only when no more specific template fits. Explain why. -->
+
+## Primary intent
+
+<!-- Why does this PR exist, and why do the other templates not fit? -->
+
+## User or maintainer impact
+
+<!-- Who is affected, in what state, and what changes? -->
+
+## Authority
+
+<!-- Link current requirements or the owner-approved decision. -->
+
+## Change and evidence
+
+<!-- Describe the smallest change and the reproducible proof. -->
+
+## Scope
+
+- [ ] This PR has one primary intent.
+- [ ] Independently removable deltas were removed or split.
+- [ ] Public text and artifacts contain no internal Meta context.
+
+## Testing
+
+<!-- Commands and relevant browser/state evidence. -->
diff --git a/.github/PULL_REQUEST_TEMPLATE/specification.md b/.github/PULL_REQUEST_TEMPLATE/specification.md
new file mode 100644
index 0000000000..669ac0ddac
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE/specification.md
@@ -0,0 +1,38 @@
+<!-- Use this template only when recording a durable decision is the primary intent. Do not include implementation. -->
+
+## Exact decision needed
+
+<!-- State the smallest unresolved public behavior, API, ownership, compatibility, theme, or design claim. -->
+
+## Existing authority searched
+
+<!-- Name current records, affected paths/exports, semantic terms, and overlapping open PRs inspected. Explain why no existing claim settles this decision. -->
+
+## Decision
+
+<!-- State the approved requirement, conditions, defaults, exceptions, compatibility, and owner. -->
+
+## Rejected alternatives
+
+<!-- Record only consequential alternatives likely to recur. -->
+
+## Claim scope and non-goals
+
+<!-- A current record governs only these explicit claims. Leave adjacent behavior uncontracted instead of filling it for completeness. -->
+
+## Evidence and implementation relationship
+
+<!-- Evidence supporting the decision; linked implementation PR if one exists. The specification must remain valid without it. -->
+
+## Scope
+
+- [ ] This PR contains specification records only.
+- [ ] It records one intentional durable decision, not a review transcript or rescue for a separable tagalong.
+- [ ] Adjacent API, visual, accessibility, composition, and implementation facts remain outside scope unless this exact decision depends on them.
+- [ ] Public text and artifacts contain no internal Meta context.
+
+## Validation
+
+- `pnpm check:knowledge`
+- Prettier
+- `git diff --check`
diff --git a/.github/PULL_REQUEST_TEMPLATE/visual-update.md b/.github/PULL_REQUEST_TEMPLATE/visual-update.md
new file mode 100644
index 0000000000..50c9be21ed
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE/visual-update.md
@@ -0,0 +1,31 @@
+<!-- Use this template only when appearance is the primary intent. -->
+
+## User impact
+
+<!-- Who is affected, in what visual state, and what becomes clearer, more consistent, or more usable? -->
+
+## Visual authority
+
+Choose one and link it:
+
+- [ ] Correction already settled by current component, family, design, theme, or objective accessibility authority.
+- [ ] New visual direction settled by an owner-approved current specification.
+
+## Before and after
+
+<!-- Embed matched real-browser screenshots. Keep viewport, content, theme, and state identical except for the change. -->
+
+## State matrix
+
+<!-- Cover relevant themes, light/dark modes, viewport/container sizes, LTR/RTL, input states, and the unchanged legacy/default path. -->
+
+## Scope
+
+- [ ] Appearance is the primary intent.
+- [ ] Behavior, API, interaction model, and unrelated layout changes were removed or split.
+- [ ] The evidence shows the changed pixels actively running, not only source or computed styles.
+- [ ] Public text and artifacts contain no internal Meta context.
+
+## Testing
+
+<!-- Visual regression, focused tests, and browser checks. -->
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
new file mode 100644
index 0000000000..511d251368
--- /dev/null
+++ b/.github/pull_request_template.md
@@ -0,0 +1,35 @@
+<!--
+Choose the template matching this PR's primary intent from
+.github/PULL_REQUEST_TEMPLATE/. See docs/contributing/pull-requests.md.
+Keep one primary intent; remove or split independently reviewable tagalongs.
+-->
+
+## Primary intent
+
+<!-- Bug fix, visual update, new feature, documentation, specification, maintenance, or other. Why does this PR exist? -->
+
+## User or maintainer impact
+
+<!-- Who is affected, in what state, and what improves? -->
+
+## Authority
+
+<!-- Link current requirements or the owner-approved decision. Say "none found" only after searching. -->
+
+## Change
+
+<!-- Describe the smallest change that satisfies the primary intent. -->
+
+## Evidence
+
+<!-- Show the affected before/after state and representative unchanged paths. Use real-browser pixels for visual claims. -->
+
+## Scope
+
+- [ ] This PR has one primary intent.
+- [ ] Independently removable API, visual, layout, behavior, cleanup, and policy changes were removed or split.
+- [ ] Public text and artifacts contain no internal Meta context.
+
+## Testing
+
+<!-- Commands, browser/state matrix, generated output, or other reproducible checks. -->
diff --git a/AGENTS.md b/AGENTS.md
index b38389c495..5887263203 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -17,6 +17,9 @@ nested `AGENTS.md`.
`packages/cli/assets/docs/`.
- Contributors: read `CONTRIBUTING.md` and the relevant guidance linked from
`docs/README.md`.
+- Pull requests: choose one primary intent and use its template under
+ `.github/PULL_REQUEST_TEMPLATE/`; read `docs/contributing/pull-requests.md`
+ before opening or reviewing a mixed change.
- Component work: read the component's `{Name}.spec.md` when one exists, then
any `module:*` records it lists for the public module being changed, followed by
consumer docs, tests, and implementation.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index a053b7960f..aa3079e961 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -4,6 +4,7 @@ For the full contribution process — what we accept, how to propose new compone
Key pages:
+- **[Pull request intents](docs/contributing/pull-requests.md)** — choose one primary intent, its evidence bar, and the matching PR template
- **[API conventions guide](docs/contributing/api-conventions.md)** — practical naming, composition, styling, proposal, and review guidance linked to current owner records
- **[Design Conventions](https://github.com/facebook/astryx/wiki/Design-Conventions)** — the design-side bar: tokens, spacing, radius, elevation, type, color, motion, and state representations
- **[Specification Protocol](https://github.com/facebook/astryx/wiki/Component-Specification-Protocol)** — the 9-phase process for new components
diff --git a/docs/contributing/README.md b/docs/contributing/README.md
index 984a26cd35..811ea24e16 100644
--- a/docs/contributing/README.md
+++ b/docs/contributing/README.md
@@ -4,6 +4,8 @@ These guides turn current Astryx owner records into practical contribution steps
They do not create policy or replace architecture, specifications, family
contracts, or component contracts.
+- [Pull request intents](pull-requests.md): choose one primary intent, use the
+ matching template, and supply the right evidence without absorbing tagalongs.
- [API conventions](api-conventions.md): shape, propose, implement, and review a
public component API.
- [CLI conventions](cli-conventions.md): propose, implement, and review a change
diff --git a/docs/contributing/pull-requests.md b/docs/contributing/pull-requests.md
new file mode 100644
index 0000000000..4848c8610d
--- /dev/null
+++ b/docs/contributing/pull-requests.md
@@ -0,0 +1,46 @@
+# Pull requests: one primary intent
+
+A pull request should make one reviewable change for one reason. Choose the template that matches its primary intent; supporting tests and docs belong with that intent, but unrelated API, visual, layout, behavior, or policy changes do not.
+
+GitHub uses the default template automatically. To choose another, add `?template=<file>.md` to the new-pull-request URL, or copy the matching file from `.github/PULL_REQUEST_TEMPLATE/` into the description.
+
+| Primary intent | Template | Minimum evidence |
+| ---------------------------------------------------- | ------------------ | -------------------------------------------------------------------------------------------------------- |
+| Restore broken behavior | `bug-fix.md` | reproduction, expected authority, before/after result, unchanged representative path |
+| Correct or intentionally change appearance | `visual-update.md` | current visual authority or owner decision, real-browser before/after pixels, relevant state matrix |
+| Add a capability | `new-feature.md` | user need, current specification, complete public delta, behavior and compatibility evidence |
+| Correct contributor or consumer documentation | `documentation.md` | reader impact, source of truth, rendered or generated result |
+| Record a durable decision | `specification.md` | exact unresolved claim, existing authority searched, decision, rejected alternatives, explicit non-goals |
+| Change tooling, tests, CI, or repository maintenance | `maintenance.md` | operational problem, failure proof, success proof, unchanged product behavior |
+| Anything else | `other.md` | primary intent, user or maintainer impact, authority, evidence |
+
+## Keep the intent atomic
+
+Before requesting review, partition every observable delta:
+
+- **Primary:** the reason this pull request exists.
+- **Supporting:** evidence or documentation required to make the primary change complete.
+- **Tagalong:** independently removable behavior, visual, API, layout, policy, or cleanup.
+
+Remove or split tagalongs. A bug fix does not become a feature because a nearby affordance could also improve. A feature does not absorb unrelated cleanup because the same file is open.
+
+## Use specifications last, not first
+
+Review should produce the smallest ideal change that can land:
+
+1. Apply current component, module, family, design, theme, architecture, and system authority to each delta.
+2. If a delta violates current authority, conform or remove it. Do not propose changing the specification merely to rescue the implementation.
+3. If a delta is unsettled but separable, remove or split it and keep reviewing the primary intent.
+4. Propose a specification only for a surviving, intentional durable decision the team wants to pursue.
+
+A current record governs only its explicit claims inside its ownership boundary. It does not imply that the whole named component or module is fully specified.
+
+## Visual corrections
+
+A visual change does not automatically need a new specification. It may proceed as a correction when current component, family, design, theme, or objective accessibility authority already settles the exact outcome. Show that authority and verify the affected state with real-browser pixels, plus representative unchanged states.
+
+A new visual representation, subjective direction, or interaction model remains a design decision. Put that decision in its own specification or owner-reviewed visual update instead of attaching it to a bug fix.
+
+## Public repository boundary
+
+Descriptions, screenshots, commits, tests, and specification records are public. Do not include internal links, identifiers, hostnames, tools, or operational context.
diff --git a/docs/templates/knowledge/module-spec.md b/docs/templates/knowledge/module-spec.md
index 09dd976d5e..7278a72d4d 100644
--- a/docs/templates/knowledge/module-spec.md
+++ b/docs/templates/knowledge/module-spec.md
@@ -19,7 +19,7 @@ references: [architecture:<surface>, design:<surface>, spec:AST-000/DEC-0]
## Intent
-<!-- Why this public semantic module exists and the component-local job it owns. Private implementation helpers do not need records. Consumer usage belongs in the module's .doc.mjs. -->
+<!-- Why this public semantic module exists and the component-local job it owns. Private implementation helpers do not need records. Consumer usage belongs in the module's .doc.mjs. A current module record may contract one named semantic slice; state that boundary and leave adjacent behavior uncontracted rather than filling it for completeness. -->
## Compatibility and migration