@aurea-uds/contracts 0.5.0 → 0.7.0

package/README.md

@@ -14,13 +14,30 @@ It states what the design system promises — identity, the vocabulary of the ca
 enumerations that component records are validated against — in a form a tool can read instead
 of a paragraph a person has to interpret.
 
+## The API surface
+
+```js
+import surface from "@aurea-uds/contracts/api-surface" with {type: "json"};
+```
+
+Every component `@aurea-uds/react` exports, with its props, and — where the type is a union of
+string literals — the values those props accept. It is **derived**, not written: the build reads
+the declaration output of the TypeScript compiler, so inheritance, `Omit`, `Pick` and chained
+aliases are resolved by the compiler rather than by a guess. Editing it by hand is the defect it
+exists to prevent.
+
+It is what lets a tool answer "which variants does this component take?" without parsing our
+source or trusting our prose — and it is what the validator checks the per-component records
+against, so the two cannot drift.
+
 ## What is not in here
 
 The per-component records live in the repository, not in this package. They are how the
 catalogue is generated and how the validator checks the library against itself; nothing
 outside the build consumes them, and a package should not ship files that exist only to
 answer a question nobody is asking. If you need them, say so in an issue and they get an
-entry point.
+entry point. The API surface above is the part of that answer a tool actually needs, and it
+ships for exactly that reason.
 
 ## Licence