An open source design system that's fully customizable and agent ready
TypeScript
spec(AST-071): every styling input works from every styling system (#7277)
Cindy Zhange3c1cfdd5097
diff --git a/docs/architecture/public-component-api.md b/docs/architecture/public-component-api.mdindex 9f63579316..a4ace46075 100644--- a/docs/architecture/public-component-api.md+++ b/docs/architecture/public-component-api.md@@ -30,6 +30,7 @@ deciding_specs:spec:AST-005/DEC-1,spec:AST-012/DEC-1,spec:AST-012/DEC-2,+ spec:AST-071/DEC-1,]---@@ -138,6 +139,11 @@ guidance owns the process used to propose and test APIs.- **INV14 — Shared breakpoint names keep one meaning.** Components that accept atheme width point use `sm`/`md`/`lg`/`xl`/`2xl` from the active Theme. A`below` boundary is exclusive, so equality belongs to the wider side.+- **INV15 — A part's styling inputs come as a set.** Styling for an element other+ than the root is accepted as `<part>Xstyle`, `<part>ClassName`, and+ `<part>Style` together, reaching that element and composing as INV6 describes.+ No public prop accepts StyleX styles for an element that cannot also take a+ class name and inline styles, following `spec:AST-071/DEC-1`.This record applies to stable public packages. Lab components are not stablepublic promises until promotion.@@ -192,6 +198,8 @@ public promises until promotion.destination-safety decision.- `spec:AST-012/DEC-1` and `spec:AST-012/DEC-2` — components reuse the fixedtheme width names and inclusive-`from`/exclusive-`below` edge meanings.+- `spec:AST-071/DEC-1` — every styling input works from every styling system,+ so a part's styling inputs come as a set.Transition Action sequencing and pending behavior belong to their component orfamily contract. This record links that owner once it is current; it does not@@ -209,6 +217,7 @@ copy the component matrix.| INV11 | Public-API admission review plus owning theming/component tests | A public semantic custom property exposes derivable or unsupported implementation detail || INV12, INV13 | Generated declaration/export/behavior inventory plus canonical-owner mapping | A reachable supporting type or behavior is called internal, or mechanical evidence is treated as permission to accept it || INV14 | `AppShell.test.tsx` | A component hardcodes a divergent point or treats equality as below |+| INV15 | Public-API review of the generated declaration inventory | A part or StyleX-typed styling prop ships without class-name and inline-style counterparts on the same element || Consumer-doc projection | `docPropReferences.test.ts` and `docPropLiterals.test.ts` | Docs name a nonexistent prop or omit public literal choices |Known verification gaps:diff --git a/docs/specs/AST-071-styling-library-compat/spec.md b/docs/specs/AST-071-styling-library-compat/spec.mdnew file mode 100644index 0000000000..917f0c5bdb--- /dev/null+++ b/docs/specs/AST-071-styling-library-compat/spec.md@@ -0,0 +1,97 @@+---+schema_version: 4+template_version: 2+kind: system-spec+id: spec:AST-071+authority: current+archive_reason: null+superseded_by: null+approved_by: cixzhang+approved_at: 2026-10-11+phase: accepted+owners: [cixzhang]+affects_architecture: [architecture:public-component-api]+affects_families: []+affects_contributing: []+affects_consumer_docs: []+---++# Styling-library compatibility system spec++## Intent++A product styles Astryx components with whatever its codebase already uses:+StyleX, class-name CSS (CSS modules, utility classes, global stylesheets), or+inline styles. Every styling input a component accepts reaches its element from+each of those systems, so no part of a component can be styled from StyleX+alone.++## Non-goals++- Whether a component exposes styling for a part at all. A part input is a new+ public prop and is admitted under `spec:AST-002/DEC-1`; this spec shapes a+ part input once it is admitted.+- The order in which styling inputs compose on one element, owned by+ `architecture:public-component-api` INV6.+- Theme tokens and theme targets, owned by `architecture:theme-tokens` and the+ theming records.+- Equivalent internal implementations remain valid when they satisfy this contract.++## Requirements++- **FR1 — A part's styling inputs come as a set.** A component that accepts a+ styling input for an element other than its root MUST accept all three of+ `<part>Xstyle`, `<part>ClassName`, and `<part>Style` for that element, with+ the same `<part>` word in each. All three MUST reach the same element and+ compose there as the root's `xstyle`, `className`, and `style` do.+- **FR2 — No StyleX-only styling input.** A public prop that styles an element+ MUST NOT accept StyleX styles unless the same element also accepts a class+ name and inline styles through public props.++### Platform support++- Supported feature/engine floor: unchanged; this contract adds no CSS feature.+- Unsupported behavior: none; class names and inline styles work in every+ supported engine.+- Browser evidence: not required; FR1 and FR2 are proven at the declaration and+ render layer.++## Current-state impact++- `architecture:public-component-api` gains an invariant that a part's styling+ inputs come as a set, decided by `spec:AST-071/DEC-1`.+- Released public props that do not conform to FR1 and FR2 are+ `ComplexSelector.contentXstyle`, `ContextMenu.triggerXstyle`, and+ `BaseTypeahead.inputXStyle`. They are known gaps, not precedent: no new part+ input is admitted by citing them.++## Verification++| Contract | Verification | Representative states | Mutation or failure expectation |+| -------- | -------------------------------------------------------------------------------- | --------------------------------------------------------- | --------------------------------------------------------------------------------------------- |+| FR1 | Public-API review of the generated declaration inventory; component render tests | A part input styled from StyleX, a class name, and inline | A `<part>Xstyle` without `<part>ClassName` and `<part>Style`, or one landing elsewhere, fails |+| FR2 | Public-API review of every exported prop typed with StyleX styles | Root and part inputs across exported components | A StyleX-typed prop with no class-name and inline-style counterpart on its element fails |++Known verification gap: no automated check enforces FR1 or FR2; public-API+review applies them.++## Decision log++### DEC-1 — Every styling input works from every styling system++**Reference:** `spec:AST-071/DEC-1`+**Decider:** `cixzhang`, 2026-10-09++Astryx is adopted by products that do not use StyleX. A part reachable only+through `xstyle` leaves a codebase that styles with class names or inline styles+no way to reach that part, and each such prop is the precedent the next part+copies. So a part's styling input is the full set the root already takes, or it+is not admitted.++Rejected: admitting a part `xstyle` alone and adding its counterparts on request — non-StyleX callers stay locked out until someone asks.++## Open questions++- **OQ1 — How the known non-conforming props reach conformance** (`human-api`):+ `ComplexSelector.contentXstyle`, `ContextMenu.triggerXstyle`, and+ `BaseTypeahead.inputXStyle`.