Skip to content

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

TypeScript
9.8 KB
Raw Blame

schema_version: 3 template_version: 7 kind: component id: component: authority: draft archive_reason: null superseded_by: null approved_by: null approved_at: null owners: [] review_triggers: [public-api, behavior, layout, theming, accessibility] verified_by: [] modules: [module:/] families: [family:] design_specs: [design:] architecture: [architecture:] contributing: [contributing:] system_specs: [spec:AST-000/DEC-0]

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.

Intent

Compatibility and migration

  • Released default preserved: <yes, no, or not yet released>
  • Compatibility class: <state the compatibility effect>
  • Controlled/uncontrolled behavior: <unchanged or stated transition>
  • Migration decision: <component DEC or system spec link>

Consumer migration instructions belong in consumer docs and release notes.

Ownership boundary

Owns

  • <responsibility>

Does not own / non-goals

  • <responsibility> — owned by family:<family> / component:<Other> / product callsite.

Public concepts

Concept Closed values or states Meaning Availability by variant/orientation/state Default Owner Stability Invalid-value behavior
<concept> <values> <meaning> <where emitted> <default> component:<Name> <stable or experimental> <reject, ignore, or fallback>

Behavioral and layout contract

Draft requirements identify their basis so observed code is not mistaken for an intentional decision. A current contract contains no unresolved rows.

ID Candidate invariant Basis Draft review state
FR1 <The component MUST …> <existing DEC, documented promise, standard, current behavior, or proposal> <settled, verify, or human decision>

Allowed variation

  • AV1 — <dimension>. <What may vary without becoming a regression.>

Representative states

State Required invariant Allowed variation
<state> <invariant> <variation>

Transformation and precedence order

  • ORD1 — <pipeline>. <The final invariant and the required order, such as snap → round → clamp.>

Performance and resources

  • PR1 — <constraint>. <Measurement, render, listener, observer, or initialization behavior that MUST remain true.>

Current measurements belong in the audit record; this subsection owns only durable constraints and their verification target.

Accessibility contract

  • AR1 — <obligation>. <The component MUST …>

Design relationships

Anatomy or state Design requirement Representation authority Hierarchy role Component contract
<role/state> design:<surface>/DR1 <prescribed, human-selected, or unsettled> <prominent or supporting> <FR/AR reference>

The component implements design requirements without copying their rationale. An unsettled representation remains a human decision; principles do not let an agent invent the answer.

Use the optional table below only for durable component-local visual intent that a future redesign must reconsider. Reuse or amend an existing row before adding one. Exact pixel tuning normally stays in code and visual evidence. Put shared or cross-component rules in docs/design/ and link them from the relationship table above. Use DD1, DD2, and so on; IDs remain stable and unique within this record.

Design decisions

ID Decision Intent or reason Applies to Allowed variation

Theming anatomy

{
  "<root part>": {"target": "<target>"},
  "<inherited part>": {"inherits": "<parent-or-root-target>"},
  "<delegated part>": {
    "delegatesTo": {"owner": "component:<Owner>", "target": "<target>"}
  },
  "<currently unreachable part>": {
    "none": {
      "reason": "<intentional | reachability-gap | unsettled>: <required factual reason>"
    }
  }
}

Family and system relationships

Frontmatter lists structural modules links plus only current family, design, architecture, and system relationships. A module backlink may name an active draft because it records ownership rather than adopting draft behavior. Candidate family or design records list proposed members on the candidate itself; do not edit an existing component contract merely to backlink to those drafts.

  • module:<Name>/<PublicName> owns <independent public module contract>; this component owns aggregate module protocol, ordering, and composition.
  • family:<family-name> owns <shared concept>; this component <adopts or deliberately differs>.

Verification map

Contract Verification Representative states Mutation or failure expectation Audit section
FR1 <test or browser evidence> <states> <removing behavior makes this fail because …> audit:<Name>/<section>

Decision log

DEC-1 — <component-local decision>

Reference: component:<Name>/DEC-1 Decider: <person>, <YYYY-MM-DD>

<Reason and user impact.>

Rejected: <include only when the alternative is consequential and likely to recur; otherwise delete this line>.

Open questions

  • OQ1 — <question> (checkable | human-design | human-api)

Content boundary

This file does not duplicate consumer prop tables/examples, current audit results, implementation steps, or family/system rules. It links to their owners.