Skip to content

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.md
index 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 a
theme 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 stable
public 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 fixed
theme 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 or
family 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.md
new file mode 100644
index 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`.