Skip to content

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

TypeScript

docs(governance): design owners approve design rules on their own pull requests (#10266)

Cindy Zhang96df1b8eb80a
diff --git a/.github/scripts/spec-owner-reconcile.test.mjs b/.github/scripts/spec-owner-reconcile.test.mjs
index 7c7f910126..0c317292a3 100644
--- a/.github/scripts/spec-owner-reconcile.test.mjs
+++ b/.github/scripts/spec-owner-reconcile.test.mjs
@@ -1471,6 +1471,27 @@ describe('spec owner workflow reconciliation', () => {
);
});
+ it("accepts a DESIGNOWNER author's own /approve-spec on a design record", async () => {
+ const harness = createDesignHarness();
+
+ await run(harness, context({runId: 100n, author: 'ernestt'}));
+ expect(latestReviewGate(harness.state).state).toBe('pending');
+
+ await commentRun(
+ harness,
+ ownerComment(
+ `/approve-spec ${head}`,
+ '2026-08-30T10:05:00Z',
+ 'ernestt',
+ ),
+ 101n,
+ );
+ expect(latestReviewGate(harness.state)).toMatchObject({
+ state: 'success',
+ description: expect.stringContaining('Spec approved by @ernestt'),
+ });
+ });
+
it.each([
['a commit that changes no spec text', 'currentRecord', 'review'],
['the draft-to-current flip', 'draftRecord', 'command'],
diff --git a/docs/architecture/knowledge-contracts.md b/docs/architecture/knowledge-contracts.md
index d8890a325d..091952e909 100644
--- a/docs/architecture/knowledge-contracts.md
+++ b/docs/architecture/knowledge-contracts.md
@@ -879,7 +879,10 @@ this flow passes the historical review benchmark and is enforced on pull request
request and binds the approved spec content, not a commit. Approval for every
record kind derives from `.github/ENGOWNERS`; current design and theme records,
normative design assets, and DD-only current component/module changes
- additionally accept `.github/DESIGNOWNERS`. A mixed DD plus other
+ additionally accept `.github/DESIGNOWNERS`, except that a design owner's
+ approval (a review or `/approve-spec`) does not alone approve an accessibility
+ requirement or a deprecation, even inside a current design or theme record
+ (DEC-14). A mixed DD plus other
component/module edit requires both groups. An owner-gated Markdown file with
no authority of its own, such as a generated table beside a spec, requires an
engineering owner. Record metadata never
@@ -1177,7 +1180,20 @@ supplies it.
owner approves again. Reactions are not approvals.
Eligibility follows the owner groups above. An ENGOWNER author may approve
their own pull request with `/approve-spec`; an approving review by the
- author never counts.
+ author never counts. Design owners listed in `.github/DESIGNOWNERS` approve
+ design and theme records (design rules and decisions: the visual and
+ interaction look), including on their own pull requests with
+ `/approve-spec`. Public API, behavior rules, accessibility requirements and
+ deprecations need an engineering owner (`.github/ENGOWNERS`): a design
+ owner's approval (a review or `/approve-spec`) does not alone approve an
+ accessibility requirement or a deprecation, even inside a current design or
+ theme record. Current gap: the gate routes approval by record kind, so a
+ design owner's approval alone clears a current design or theme record whose
+ change carries an accessibility requirement or a deprecation, both their own
+ `/approve-spec` on their pull request and their approving review on a
+ contributor's pull request. `.github/scripts/spec-owner-decision.cjs` picks
+ the owner group by record kind only and has no check for an accessibility
+ requirement or a deprecation.
- **What keeps approval.** Commits that change only other paths, merges from
the base branch, rebases, and approval bookkeeping keep the fingerprint, so
@@ -1264,22 +1280,23 @@ because the reader never sees the hook wired.
## Verification
-| Invariant | Evidence | Failure signal |
-| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| INV1, INV6 | `scripts/check-knowledge.test.mjs` | An unapproved current record or unmigrated active record passes |
-| INV5, INV7 | `.github/scripts/change-scope.test.mjs` | A template, schema, guidance, architecture, code change, unsafe rename, or truncated list qualifies as spec-only |
-| Approval follows the spec content | `.github/scripts/spec-owner-decision.test.mjs` | An approval of other spec content clears the gate, a self-declared owner becomes an approver, or the wrong owner group approves a current record |
-| INV3, INV4, INV11 | Blinded historical review benchmark | Reviewer re-asks a settled decision, invents a new one, approves an unsettled public delta, or treats a contradiction as preserves |
-| INV10 | Record-content and review-disposition fixtures | A spec assigns a PR verdict, or a reviewer treats a PR link as authority |
-| INV13 | Blinded spec-authorship fixture plus overlap-search receipt | An author creates parallel authority, searches only landed records or filenames, misses open work on the canonical owner, or treats an open PR as authority |
-| INV14, INV15 | Narrow-decision and mixed-intent review fixtures | A current visual slice is forced to contract its whole module, a separable tagalong blocks a repair, or review reports a gap without a landing-ready remedy |
-| INV16, INV17 | Spec-first review and missing-context fixtures | Generated checklist completeness overrides authority, review invents product direction, restates supplied context, or fails to identify an unrelated tagalong or affected caller state |
-| INV18 | Spec-review mechanism analysis plus owner migration receipt | A new/amended product spec requires a private mechanism without proving it is public, silently invalidates an existing current record, or leaves touched architecture wording in the product contract |
-| INV19 | Spec-review ownership-collision receipt and human decision | Automated review approves a product contract, omits current/open owner overlap, misses a collision or architecture leak, or returns only a human hold without actionable written analysis |
-| INV20, DEC-9 | `scripts/check-knowledge.test.mjs` and `scripts/review-global-baselines.mjs` | A matching review misses a current global claim, loads a draft/nonmatching claim, loses base-commit provenance, or treats the rest of a routed record as authority |
-| INV21, DEC-10 | `.github/scripts/component-design-decisions.test.mjs`, `.github/scripts/review-signal-decision.test.mjs`, `.github/scripts/spec-owner-decision.test.mjs`, and `.github/scripts/lib/classify-visual.test.mjs` | A malformed/local DD escapes validation, stale approval clears a new head, owner routing loses mixed-change gates, or executable/API/unknown runtime code is misclassified as appearance-only |
-| DEC-14 | `.github/scripts/spec-owner-reconcile.test.mjs`, `.github/scripts/spec-owner-decision.test.mjs`, `.github/scripts/spec-owner-workflow.test.mjs`, and `.github/scripts/knowledge-paths.test.mjs` | A non-spec commit, base merge, rebase, or status flip resets approval; changed spec text or a new spec path keeps it; a command naming other spec content, a reaction, a non-owner act, or an author review approves; `review-required` succeeds while spec approval is missing or before the spec decision is published; a revoke or request for changes naming other spec content is ignored; a missing approval reports failure; an evaluation leaves its head without a terminal state; or a current record `check:knowledge` discovers, or an owner-gated Markdown file with no authority of its own, changes without an owner |
-| DEC-11 | `.github/scripts/review-signal-decision.test.mjs`, `.github/scripts/review-clear-workflow.test.mjs`, and `.github/scripts/review-signal-workflow.test.mjs` | An app approval clears a read-only or fork author or an earlier head; a later app request for changes or dismissal leaves the gate clear; an app approval overrides an ENGOWNER request for changes; or an unset app or unreadable permission clears the gate |
+| Invariant | Evidence | Failure signal |
+| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| INV1, INV6 | `scripts/check-knowledge.test.mjs` | An unapproved current record or unmigrated active record passes |
+| INV5, INV7 | `.github/scripts/change-scope.test.mjs` | A template, schema, guidance, architecture, code change, unsafe rename, or truncated list qualifies as spec-only |
+| Approval follows the spec content | `.github/scripts/spec-owner-decision.test.mjs` | An approval of other spec content clears the gate, a self-declared owner becomes an approver, or the wrong owner group approves a current record |
+| INV3, INV4, INV11 | Blinded historical review benchmark | Reviewer re-asks a settled decision, invents a new one, approves an unsettled public delta, or treats a contradiction as preserves |
+| INV10 | Record-content and review-disposition fixtures | A spec assigns a PR verdict, or a reviewer treats a PR link as authority |
+| INV13 | Blinded spec-authorship fixture plus overlap-search receipt | An author creates parallel authority, searches only landed records or filenames, misses open work on the canonical owner, or treats an open PR as authority |
+| INV14, INV15 | Narrow-decision and mixed-intent review fixtures | A current visual slice is forced to contract its whole module, a separable tagalong blocks a repair, or review reports a gap without a landing-ready remedy |
+| INV16, INV17 | Spec-first review and missing-context fixtures | Generated checklist completeness overrides authority, review invents product direction, restates supplied context, or fails to identify an unrelated tagalong or affected caller state |
+| INV18 | Spec-review mechanism analysis plus owner migration receipt | A new/amended product spec requires a private mechanism without proving it is public, silently invalidates an existing current record, or leaves touched architecture wording in the product contract |
+| INV19 | Spec-review ownership-collision receipt and human decision | Automated review approves a product contract, omits current/open owner overlap, misses a collision or architecture leak, or returns only a human hold without actionable written analysis |
+| INV20, DEC-9 | `scripts/check-knowledge.test.mjs` and `scripts/review-global-baselines.mjs` | A matching review misses a current global claim, loads a draft/nonmatching claim, loses base-commit provenance, or treats the rest of a routed record as authority |
+| INV21, DEC-10 | `.github/scripts/component-design-decisions.test.mjs`, `.github/scripts/review-signal-decision.test.mjs`, `.github/scripts/spec-owner-decision.test.mjs`, and `.github/scripts/lib/classify-visual.test.mjs` | A malformed/local DD escapes validation, stale approval clears a new head, owner routing loses mixed-change gates, or executable/API/unknown runtime code is misclassified as appearance-only |
+| DEC-14 | `.github/scripts/spec-owner-reconcile.test.mjs`, `.github/scripts/spec-owner-decision.test.mjs`, `.github/scripts/spec-owner-workflow.test.mjs`, and `.github/scripts/knowledge-paths.test.mjs` | A non-spec commit, base merge, rebase, or status flip resets approval; changed spec text or a new spec path keeps it; a command naming other spec content, a reaction, a non-owner act, or an author review approves; `review-required` succeeds while spec approval is missing or before the spec decision is published; a revoke or request for changes naming other spec content is ignored; a missing approval reports failure; an evaluation leaves its head without a terminal state; or a current record `check:knowledge` discovers, or an owner-gated Markdown file with no authority of its own, changes without an owner |
+| DEC-14 (design owner's own PR) | `.github/scripts/spec-owner-reconcile.test.mjs` "accepts a DESIGNOWNER author's own /approve-spec on a design record"; the accessibility-requirement and deprecation limit has no gate check (the Current gap in DEC-14) | A DESIGNOWNER author's own `/approve-spec` does not approve a current design record on their own pull request; the accessibility-requirement and deprecation limit has no failure signal because the gate does not check it (Current gap) |
+| DEC-11 | `.github/scripts/review-signal-decision.test.mjs`, `.github/scripts/review-clear-workflow.test.mjs`, and `.github/scripts/review-signal-workflow.test.mjs` | An app approval clears a read-only or fork author or an earlier head; a later app request for changes or dismissal leaves the gate clear; an app approval overrides an ENGOWNER request for changes; or an unset app or unreadable permission clears the gate |
| Invariant | Evidence | Failure signal |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |