Skip to content

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

TypeScript

docs(specs): add reader-first contract summaries (#6317)

Cindy Zhang1c4033d4978f
diff --git a/docs/architecture/knowledge-contracts.md b/docs/architecture/knowledge-contracts.md
index 138202ce50..f1e19db068 100644
--- a/docs/architecture/knowledge-contracts.md
+++ b/docs/architecture/knowledge-contracts.md
@@ -199,9 +199,10 @@ Every record is either:
## Writing specifications and contracts
-These rules guide writing. They do not permit semantic compaction. They come from
-directional evidence and project-owner judgment; the agent benchmark did not
-measure human readability, so this is not a quantified readability claim.
+These rules preserve semantic fidelity while putting the decisions a reader needs
+first. They are authoring guidance, not a quantified claim about human readability.
+They apply prospectively to new or materially revised architecture, component, and
+module specifications; they do not require historical rewrites.
Before writing:
@@ -212,12 +213,49 @@ Before writing:
new record only when the fact has a distinct owner and explain that boundary in
the pull-request summary.
-Then write the contract:
+Begin each component or module contract with this reader-first projection after its
+title:
+
+| Area | Contract |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | State the exact public API, concept, or syntax delta; write `None` when none changes. |
+| Behavior | State the observable governing behavior, including the decisive default, boundary, or precedence rule. |
+| End-user impact | Name who is affected, in what state, and what improves, worsens, or remains unchanged. |
+| Builder impact | Name migration work and every new caller choice; write `None` when there is no new burden. |
+| Compatibility/readiness | State default compatibility, additive/breaking status, authority and implementation state, and material evidence still pending. |
+| Review checks | List the few concrete conditions that make an implementation or proposal rejectable under this contract. |
+| Governing rules | Link the canonical owner and only the current clauses needed to justify the projection. |
+
+Architecture records use the same position and footer with architecture-specific
+rows:
+
+| Area | Contract |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
+| Governing contract | Name the observable current decisions this architecture serves; write `None` when no product contract changes. |
+| System behavior | State shipped system behavior, including the decisive invariant, boundary, or precedence rule. |
+| End-user impact | Name who is affected, in what state, and what improves, worsens, or remains unchanged. |
+| Builder impact | Name the implementation decisions, coordination work, or workarounds this architecture removes or adds. |
+| Compatibility/readiness | State compatibility effect, authority and implementation state, and material evidence still pending. |
+| Review checks | List boundary violations, product-API mechanism leaks, or lost invariants/evidence distinctions that make a change rejectable. |
+| Governing rules | Link the deciding specs and only the current clauses needed to justify the projection. |
+
+The table is a review projection; the body remains authoritative. The projection
+itself does not make a record shorter. Size falls only when authors remove true
+duplication from the body without dropping contract semantics. `Review checks`
+project settled requirements and boundaries from the body; they do not invent
+policy or reopen a decision. When citing a list-item clause such as an AST-002 FR,
+use its exact visible label and canonical file link. Do not invent a fragment URL
+for a clause that has no stable heading or explicit anchor.
+
+Then write the authoritative body:
- Use familiar words and short, direct sentences.
-- State each rule once, beside the conditions and exceptions that control it.
+- State each rule fully once, beside the conditions and exceptions that control it.
+ Later sections cite its ID or canonical owner instead of restating the prose.
- Contract only the semantic slice being decided. Name adjacent behavior as a
non-goal or uncontracted gap; do not fill it merely to make the record `current`.
+- Do not duplicate consumer prop tables, usage recipes, shared-system mechanics,
+ current audit dumps, or implementation steps. Link their canonical owners.
- Use readable tables for branches or state matrices when they improve scanning.
Never remove contract content merely to shorten a record.
@@ -234,15 +272,11 @@ rewrite. When reshaping a rule, keep its action, activating conditions,
exceptions or non-goals, owner, and evidence state in the same row or bullet as
the claim they limit.
-Aim to keep a single specification record at or below 200 lines. This is a soft
-readability ceiling, not a schema rule, validation gate, deletion target, or
-reason to migrate accepted history. Exceed it when the full contract, exact
-conditions, evidence boundaries, decisions, or required template structure need
-more room. First remove true duplication, shorten prose without changing meaning,
-use readable tables or lists, and link genuinely shared authority as INV2
-requires. If the record still exceeds 200 lines, keep the content and explain why
-in pull-request review. Do not minify tables or paragraphs to game the count;
-human scanability wins.
+Do not optimize for a line, word, byte, or percentage-reduction target. First
+remove true duplication, shorten prose without changing meaning, use readable
+tables or lists, and link genuinely shared authority as INV2 requires. Keep every
+load-bearing condition, qualifier, boundary, decision, and evidence distinction
+that remains. Human scanability and semantic fidelity win over size.
### Same rule, plainer form
@@ -270,8 +304,11 @@ The plain version changes the shape, not the meaning.
- [ ] Confirm each rule's action, conditions, qualifiers, exceptions or non-goals,
owner, authority verb, and evidence state remain explicit and adjacent to the
claim they limit.
-- [ ] Confirm tables and lists improve scanning without hiding content; if the
- record exceeds 200 lines, explain why it needs the extra space.
+- [ ] Confirm the projection states the public delta, behavior, end-user and builder
+ impact, compatibility/readiness, rejection checks, and governing rules without
+ replacing or contradicting the authoritative body.
+- [ ] Confirm tables and lists improve scanning without hiding content, and no
+ content was removed merely to meet a size target.
### When current records disagree
diff --git a/docs/templates/knowledge/architecture.md b/docs/templates/knowledge/architecture.md
index 0cdbfdcb31..d12f3992e8 100644
--- a/docs/templates/knowledge/architecture.md
+++ b/docs/templates/knowledge/architecture.md
@@ -1,6 +1,6 @@
---
schema_version: 1
-template_version: 1
+template_version: 2
kind: architecture
id: architecture:<surface>
authority: draft
@@ -16,6 +16,22 @@ deciding_specs: [spec:AST-000/DEC-0]
# <Surface> architecture
+## Contract at a glance
+
+| Area | Contract |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| Governing contract | `<Observable current decisions this architecture serves; write “None” when no product contract changes.>` |
+| System behavior | `<Shipped system behavior, including the decisive invariant, boundary, or precedence rule.>` |
+| End-user impact | `<Who is affected, in what state, and what improves, worsens, or remains unchanged.>` |
+| Builder impact | `<Which implementation decisions, coordination work, or workarounds this architecture removes or adds.>` |
+| Compatibility/readiness | `<Compatibility effect; authority and implementation state; material evidence still pending.>` |
+| Review checks | `<Reject specific boundary violations, mechanism leaks into product API, or lost invariants/evidence distinctions already forbidden below.>` |
+| Governing rules | `<Deciding specs and only the current clauses needed to justify this projection.>` |
+
+This table is a review projection; the body below is authoritative.
+
+<!-- Keep each cell compact. Architecture projects deciding product contracts but never broadens them. Review checks project settled body rules; they do not create policy. -->
+
## Purpose
## System model
diff --git a/docs/templates/knowledge/component-spec.md b/docs/templates/knowledge/component-spec.md
index 9bee2098ba..08632127cf 100644
--- a/docs/templates/knowledge/component-spec.md
+++ b/docs/templates/knowledge/component-spec.md
@@ -1,6 +1,6 @@
---
schema_version: 3
-template_version: 4
+template_version: 5
kind: component
id: component:<Name>
authority: draft
@@ -21,6 +21,22 @@ system_specs: [spec:AST-000/DEC-0]
# <Name> component contract
+## Contract at a glance
+
+| Area | Contract |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `<Exact public API, concept, or syntax delta; write “None” when none changes.>` |
+| Behavior | `<Observable governing behavior, including the decisive default, boundary, or precedence rule.>` |
+| End-user impact | `<Who is affected, in what state, and what improves, worsens, or remains unchanged.>` |
+| Builder impact | `<Migration and each new caller choice; write “None” when there is no new burden.>` |
+| Compatibility/readiness | `<Default compatibility; additive/breaking status; authority and implementation state; material evidence still pending.>` |
+| Review checks | `<Reject specific contradictions, invalid states, wrong-owner APIs, or lost boundaries/precedence/evidence distinctions already forbidden below.>` |
+| Governing rules | `<Canonical owners and only the current clauses needed to justify this projection.>` |
+
+This table is a review projection; the body below is authoritative.
+
+<!-- Keep each cell compact. Review checks project settled body rules; they do not create policy. Link AST-002 list-item clauses with an exact visible label and the canonical file URL, never an invented fragment. -->
+
## Intent
<!-- Why this component exists and the system-level job it owns. Consumer usage belongs in <Name>.doc.mjs. -->
diff --git a/docs/templates/knowledge/module-spec.md b/docs/templates/knowledge/module-spec.md
index 7278a72d4d..d837a00942 100644
--- a/docs/templates/knowledge/module-spec.md
+++ b/docs/templates/knowledge/module-spec.md
@@ -1,6 +1,6 @@
---
schema_version: 3
-template_version: 1
+template_version: 2
kind: module
id: module:<ParentComponent>/<PublicName>
authority: draft
@@ -17,6 +17,22 @@ references: [architecture:<surface>, design:<surface>, spec:AST-000/DEC-0]
# <PublicName> module contract
+## Contract at a glance
+
+| Area | Contract |
+| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Public contract | `<Exact public API, concept, or syntax delta; write “None” when none changes.>` |
+| Behavior | `<Observable governing behavior, including the decisive default, boundary, or precedence rule.>` |
+| End-user impact | `<Who is affected, in what state, and what improves, worsens, or remains unchanged.>` |
+| Builder impact | `<Migration and each new caller choice; write “None” when there is no new burden.>` |
+| Compatibility/readiness | `<Default compatibility; additive/breaking status; authority and implementation state; material evidence still pending.>` |
+| Review checks | `<Reject specific contradictions, invalid states, wrong-owner APIs, or lost boundaries/precedence/evidence distinctions already forbidden below.>` |
+| Governing rules | `<Canonical owners and only the current clauses needed to justify this projection.>` |
+
+This table is a review projection; the body below is authoritative.
+
+<!-- Keep each cell compact. Review checks project settled body rules; they do not create policy. Link AST-002 list-item clauses with an exact visible label and the canonical file URL, never an invented fragment. -->
+
## 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. A current module record may contract one named semantic slice; state that boundary and leave adjacent behavior uncontracted rather than filling it for completeness. -->
diff --git a/docs/templates/knowledge/versions.json b/docs/templates/knowledge/versions.json
index 55f7db5807..546df9fb20 100644
--- a/docs/templates/knowledge/versions.json
+++ b/docs/templates/knowledge/versions.json
@@ -1,10 +1,10 @@
{
- "architecture": 1,
- "component": 4,
+ "architecture": 2,
+ "component": 5,
"design": 1,
"family": 1,
"implementation-plan": 1,
- "module": 1,
+ "module": 2,
"system-spec": 1,
"theme": 1
}
diff --git a/scripts/check-knowledge.mjs b/scripts/check-knowledge.mjs
index 38e5ad75f6..d0b01c2401 100644
--- a/scripts/check-knowledge.mjs
+++ b/scripts/check-knowledge.mjs
@@ -27,6 +27,18 @@ const HERE = path.dirname(fileURLToPath(import.meta.url));
const DEFAULT_ROOT = path.resolve(HERE, '..');
const MODULE_ID_PATTERN =
/^module:([A-Z][A-Za-z0-9]*)\/([A-Za-z][A-Za-z0-9]*)$/;
+const READER_FIRST_TEMPLATE_KINDS = new Set([
+ 'architecture',
+ 'component',
+ 'module',
+]);
+const CONTRACT_AT_A_GLANCE_SECTION = 'Contract at a glance';
+
+function expectedTemplateSections(kind, requiredSections) {
+ return READER_FIRST_TEMPLATE_KINDS.has(kind)
+ ? [CONTRACT_AT_A_GLANCE_SECTION, ...requiredSections]
+ : requiredSections;
+}
export function parseKnowledgeDocument(content, filePath = '<document>') {
const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/);
@@ -984,11 +996,13 @@ function validateAgainstSchema(
`${filePath}: template fields are missing from the schema: ${extraFields.join(', ')}.`,
);
}
- if (
- JSON.stringify(sections) !== JSON.stringify(kindSchema.requiredSections)
- ) {
+ const expectedSections = expectedTemplateSections(
+ kind,
+ kindSchema.requiredSections,
+ );
+ if (JSON.stringify(sections) !== JSON.stringify(expectedSections)) {
problems.push(
- `${filePath}: template section order must exactly match the schema; bump the schema and migrate active records for a structural change.`,
+ `${filePath}: template section order must exactly match the schema plus its allowed editorial sections; bump the schema and migrate active records for any other structural change.`,
);
}
return problems;
diff --git a/scripts/check-knowledge.test.mjs b/scripts/check-knowledge.test.mjs
index ede6be8195..59d75f2543 100644
--- a/scripts/check-knowledge.test.mjs
+++ b/scripts/check-knowledge.test.mjs
@@ -766,6 +766,97 @@ describe('knowledge validation', () => {
expect(await validateKnowledgeRoot(fixtureRoot())).toEqual([]);
});
+ it('uses the reader-first projection only in architecture, component, and module templates', () => {
+ const readerFirstTemplates = new Map([
+ [
+ 'architecture.md',
+ [
+ 'Governing contract',
+ 'System behavior',
+ 'End-user impact',
+ 'Builder impact',
+ 'Compatibility/readiness',
+ 'Review checks',
+ 'Governing rules',
+ ],
+ ],
+ [
+ 'component-spec.md',
+ [
+ 'Public contract',
+ 'Behavior',
+ 'End-user impact',
+ 'Builder impact',
+ 'Compatibility/readiness',
+ 'Review checks',
+ 'Governing rules',
+ ],
+ ],
+ [
+ 'module-spec.md',
+ [
+ 'Public contract',
+ 'Behavior',
+ 'End-user impact',
+ 'Builder impact',
+ 'Compatibility/readiness',
+ 'Review checks',
+ 'Governing rules',
+ ],
+ ],
+ ]);
+
+ for (const [fileName, projectionRows] of readerFirstTemplates) {
+ const content = fs.readFileSync(
+ path.join(repoRoot, 'docs/templates/knowledge', fileName),
+ 'utf8',
+ );
+ expect(parseKnowledgeDocument(content).sections[0]).toBe(
+ 'Contract at a glance',
+ );
+ for (const row of projectionRows) {
+ expect(
+ content
+ .split('\n')
+ .some(line => line.trimStart().startsWith(`| ${row} `)),
+ ).toBe(true);
+ }
+ expect(content).toContain(
+ 'This table is a review projection; the body below is authoritative.',
+ );
+ }
+
+ for (const fileName of [
+ 'design-spec.md',
+ 'family-contract.md',
+ 'implementation-plan.md',
+ 'system-spec.md',
+ 'theme-spec.md',
+ ]) {
+ const content = fs.readFileSync(
+ path.join(repoRoot, 'docs/templates/knowledge', fileName),
+ 'utf8',
+ );
+ expect(parseKnowledgeDocument(content).sections).not.toContain(
+ 'Contract at a glance',
+ );
+ }
+ });
+
+ it('accepts an optional reader-first projection in an older record', async () => {
+ const root = fixtureRoot();
+ const directory = path.join(root, 'packages/core/src/Button');
+ fs.mkdirSync(directory);
+ fs.writeFileSync(
+ path.join(directory, 'Button.spec.md'),
+ componentRecord().replace(
+ '## Intent',
+ '## Contract at a glance\n\nProjection.\n\n## Intent',
+ ),
+ );
+ expect(await validateKnowledgeRoot(root)).toEqual([]);
+ });
+
it('rejects a structural template change without a schema update', async () => {
const root = fixtureRoot();
const template = path.join(
@@ -774,7 +865,7 @@ describe('knowledge validation', () => {
);
fs.appendFileSync(template, '\n## Undeclared section\n');
expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
- /template section order must exactly match the schema/,
+ /template section order must exactly match the schema plus its allowed editorial sections/,
);
});
@@ -1590,10 +1681,10 @@ describe('knowledge validation', () => {
fs.mkdirSync(directory);
fs.writeFileSync(
path.join(directory, 'Button.spec.md'),
- componentRecord({template_version: '5'}),
+ componentRecord({template_version: '6'}),
);
expect((await validateKnowledgeRoot(root)).join('\n')).toMatch(
- /template_version 5 is newer than 4/,
+ /template_version 6 is newer than 5/,
);
});