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.mdindex 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 inthe 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 anon-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 asthe 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 theclaim 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 disagreediff --git a/docs/templates/knowledge/architecture.md b/docs/templates/knowledge/architecture.mdindex 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: 2kind: architectureid: 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 modeldiff --git a/docs/templates/knowledge/component-spec.md b/docs/templates/knowledge/component-spec.mdindex 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: 5kind: componentid: 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.mdindex 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: 2kind: moduleid: 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.jsonindex 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.mjsindex 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.mjsindex 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/,);});