An open source design system that's fully customizable and agent ready
TypeScript
spec(architecture): components are built from minimal DOM (#8300)
Cindy Zhangebfae1a3d1b6
diff --git a/docs/architecture/component-style-authoring.md b/docs/architecture/component-style-authoring.mdindex 401313c0eb..400d5627c6 100644--- a/docs/architecture/component-style-authoring.md+++ b/docs/architecture/component-style-authoring.md@@ -17,7 +17,7 @@ verified_by:internal/eslint-plugin-astryx/no-stylex-null-override.test.mjs,internal/eslint-plugin-astryx/no-style-only-wrapper.test.mjs,]-deciding_specs: [spec:AST-080/DEC-4]+deciding_specs: [spec:AST-080/DEC-4, spec:AST-017/DEC-26]---# Component style authoring architecture@@ -28,7 +28,7 @@ deciding_specs: [spec:AST-080/DEC-4]{"scope": "global","triggers": {- "styling": ["INV1", "INV2", "INV3", "INV4", "INV5", "INV6"]+ "styling": ["INV1", "INV2", "INV3", "INV4", "INV5", "INV6", "INV7"]}}```@@ -39,7 +39,7 @@ Astryx component styling should lower to valid maintained CSS, compose predictabwith supported consumer styling, keep relational state scoped to the intendedcomponent, and avoid DOM wrappers with no runtime responsibility.-This record owns six component-level authoring outcomes. It does not redefine+This record owns seven component-level authoring outcomes. It does not redefinesemantic tokens, public theme targets, extensible prop axes, public styling props,icon resolution, bidirectionality, or React Server Component boundaries.@@ -115,6 +115,54 @@ not evidence of conformance or violation.variable groups follow `spec:AST-066` FR3, and message catalogs follow`architecture:internationalization` INV15.+- **INV7 — Components are built from minimal DOM.** Every component, at+ rest and open, renders one element per semantic or interactive role it+ owns, one element for each themable part a current theme target paints+ (`architecture:component-theming-surface` INV4), and a wrapper only where+ INV5 names its responsibility: a semantic role (an ARIA need included),+ behavior or ref, a formatting context, outside spacing, or a style-bearing+ boundary the child cannot host. States and variants+ are expressed through attributes, classes, and styles on those elements,+ never through extra elements. A pseudo-element carries decoration that has+ no semantic role and never repeats content. Content renders once: no hidden+ twin to measure or reserve space, because CSS can size and reserve it on the+ element that shows it (INV2). A layer mounts exactly one presentation. The+ only second copy is one transient copy during an exit, a presentation+ switch, or a handoff between sheets, such as the cross-fade+ `design:reduced-motion` DR2 requires; it is made by one Core mechanism that+ every layer uses, rather than by each component, and is removed within 1+ second of the transition ending. Until that shared mechanism exists, a+ layer's own exit, presentation-switch, or handoff copy is a recorded conformance gap, not an+ exception. A change to a component prefers removing or+ merging nodes; any added element is justified against this invariant with+ measured element counts before and after. Two budgets follow from it:+ - **Surface components at rest** — Button, IconButton, ToggleButton, Item and+ other list rows, SegmentedControl, Switch, Badge, text and other inputs,+ CheckboxInput, and radio controls: no element beyond their roles, their+ themable parts, and the wrappers INV5 names, and no duplicated content,+ under any pointer. A pointer-specific presentation is a change of+ attributes and styles on the same elements; a pseudo-element stands in for+ an element only as decoration.+ - **Layers while open** — Popover, BottomSheet, DropdownMenu, ContextMenu,+ Lightbox, and Dialog: one presentation mounted, no content mounted twice+ outside the transient copy above, and the open layer under a coarse+ pointer has at most as many elements as under a fine pointer.++ Good: when a segmented control's selected label gets heavier, CSS on that+ one label element keeps the segment's width; Popover mounts its surface once+ and changes placement and presentation through styles. Bad: a hidden second+ copy of a label kept to reserve its width; a sheet and a popover both+ mounted with one hidden; a wrapper added only to carry a touch style.++ A component may exceed the budgets only through an exception its pull+ request states, with why existing elements cannot do the job and the+ measured element count before and after. Each exception is recorded as its+ own owner decision, in the component's current record or, when the+ component has none, in this record; either way it passes the spec-owner+ approval gate, and none is accepted silently. Element+ counts are `document.body.querySelectorAll('*').length` for the component's+ story, at rest and open, under a fine and a coarse pointer.+## Authoring guidanceThe following guidance helps satisfy the invariants but does not independently@@ -170,7 +218,8 @@ This record does not absorb adjacent audit rules:This record supplies shared authority for:-- **Q6 / T14:** wrapper responsibility through INV5;+- **Q6 / T14:** wrapper responsibility through INV5 and minimal construction+ through INV7;- the durable composability outcome behind **Q7** through INV3;- **T8:** component-local StyleX lowering and CSS-over-JS ownership throughINV1–INV2;@@ -201,7 +250,8 @@ Focused style-authoring review triggers when a component change adds or alters:- shorthand/reset/null behavior that can prevent independent consumer propertycomposition;- ancestor, descendant, or sibling visual state;-- a DOM wrapper around one component or one visual child;+- a DOM wrapper around one component or one visual child, or any added+ element, pseudo-element, or mounted presentation (INV7);- a component-owned inline SVG that may represent a shared semantic glyph; or- code or styles that run only on a coarse pointer, or a shared value table acomponent reads (INV6).@@ -222,18 +272,22 @@ before assigning a verdict.- `spec:AST-080/DEC-4` — every pull request reports component JavaScript andCSS size; touch-only JavaScript over 2 KB or CSS over 1 KB is flagged, andshared value tables ship only the rows a component uses (INV6).+- `spec:AST-017/DEC-26` — components are built from minimal DOM, with two+ budgets and an owner-recorded exception path; reducing DOM is compatible+ (INV7).The icon, theme-token, component-theming, public-API, bidirectionality, andRSC owners retain the delegated decisions above.## Verification-| Invariant | Evidence | Failure signal |-| ------------------- | ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| INV1 | StyleX capability scan plus component-source mutation | Shipped component styling bypasses the maintained lowering path without another named owner, including component-local raw CSS where that path supports the same result |-| INV2 | Equivalent CSS/JS mutation fixtures and real-browser presentation | JavaScript recreates CSS-resolvable presentation, flashes intermediate state, or disagrees with CSS conditions |-| INV3 | StyleX compile fixtures and independent consumer-property override mutations | Input lowers to invalid CSS or changing one supported property cannot compose without removing another |-| INV4 | Nested unrelated-owner browser fixture across hover, focus-within, active, and disabled states | Outer component state activates an inner component's visual treatment |-| INV5 | Wrapper mutations in default and host-composed render paths | Removing a wrapper changes no semantic, behavior/ref, formatting-context, outside-border-spacing, or required style-bearing DOM boundary |-| INV6 | Pull-request size report against base, with value-table import fixtures | A changed component with no base-against-head gzip JavaScript or CSS figure; a touch-only feature over 2 KB gzip JavaScript or 1 KB gzip CSS per component that is not flagged; importing a component pulls in value-table rows only other components read |-| Capability registry | Registry generation against the installed StyleX package | Recorded and installed StyleX versions differ, so capability-dependent cases are untestable |+| Invariant | Evidence | Failure signal |+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| INV1 | StyleX capability scan plus component-source mutation | Shipped component styling bypasses the maintained lowering path without another named owner, including component-local raw CSS where that path supports the same result |+| INV2 | Equivalent CSS/JS mutation fixtures and real-browser presentation | JavaScript recreates CSS-resolvable presentation, flashes intermediate state, or disagrees with CSS conditions |+| INV3 | StyleX compile fixtures and independent consumer-property override mutations | Input lowers to invalid CSS or changing one supported property cannot compose without removing another |+| INV4 | Nested unrelated-owner browser fixture across hover, focus-within, active, and disabled states | Outer component state activates an inner component's visual treatment |+| INV5 | Wrapper mutations in default and host-composed render paths | Removing a wrapper changes no semantic, behavior/ref, formatting-context, outside-border-spacing, or required style-bearing DOM boundary |+| INV6 | Pull-request size report against base, with value-table import fixtures | A changed component with no base-against-head gzip JavaScript or CSS figure; a touch-only feature over 2 KB gzip JavaScript or 1 KB gzip CSS per component that is not flagged; importing a component pulls in value-table rows only other components read |+| INV7 | Story element counts (`document.body.querySelectorAll('*').length`) at rest and open under a fine and a coarse pointer, base against head, plus render inspection for duplicated content | An element beyond the component's roles, themable parts, and INV5 wrappers, or a duplicated or hidden twin of content; a state or variant rendered as an extra element; a pseudo-element repeating content; a layer with two presentations mounted outside the transient copy, content mounted twice, more elements under a coarse pointer than a fine one, a transient copy made by a component itself, or one left past 1 second; an added element with no measured counts, or a budget exceeded with no recorded owner exception |+| Capability registry | Registry generation against the installed StyleX package | Recorded and installed StyleX versions differ, so capability-dependent cases are untestable |diff --git a/docs/architecture/component-theming-surface.md b/docs/architecture/component-theming-surface.mdindex 80b0bffd7e..dc98ff8b68 100644--- a/docs/architecture/component-theming-surface.md+++ b/docs/architecture/component-theming-surface.md@@ -7,7 +7,7 @@ authority: currentarchive_reason: nullsuperseded_by: nullapproved_by: cixzhang-approved_at: 2026-09-07+approved_at: 2026-10-24owners: [cixzhang, imdreamrunner]applies_to:[@@ -36,6 +36,7 @@ deciding_specs:spec:AST-012/DEC-3,spec:AST-012/DEC-5,spec:AST-017/DEC-1,+ spec:AST-017/DEC-26,spec:AST-087/DEC-9,]---@@ -164,7 +165,10 @@ but acceptance alone is best effort, not a compatibility promise.factual `none` are valid outcomes. A `none` reason distinguishes an intentionalcurrent boundary from a reachability gap or unsettled future exposure; it neversilently decides future themeability. When desktop and touch render different- parts or use different theming owners, they use separate anatomy rows.+ parts or use different theming owners, they use separate anatomy rows. Those+ rows describe alternatives that are never mounted together outside the one+ transient copy during a presentation switch, and both follow the minimal+ construction of `architecture:component-style-authoring` INV7.- **INV4 — Targets paint.** A target belongs on a stable visible element thatpaints theme-controlled output—not an event wrapper, speculative internalstructure, or a node created only for layout plumbing.@@ -426,24 +430,26 @@ how themes become output, or the design rationale for a component's appearance.values whose validity depends on theme enrollment.- `spec:AST-087/DEC-9` makes `Icon.variant` a theme-extensible axis whose nameseach theme lists once and whose fallback is the request without a variant.+- `spec:AST-017/DEC-26` builds components from minimal DOM; desktop and touch+ rows are never mounted together outside the one transient switch copy (INV3).- `spec:AST-017/DEC-1` owns published compatibility classification and migration:compatibility-path removal is breaking. This record owns the exact deprecatedtheming cohort and its approved 0.7.0 removal window.## Verification-| Invariant | Evidence | Failure signal |-| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |-| INV1 | Cross-package target/documentation inventory | An exported target in a participating package is invisible to metadata or CLI validation |-| INV2, INV3 | Bidirectional anatomy-disposition/target check | A current target has no semantic part owner, anatomy mechanically creates targets, or `none` silently becomes future policy |-| INV4, INV5 | Component review plus rendered DOM inspection | Public target lands on non-painting plumbing or aliases a child primitive without distinct semantics |-| INV6 | `themingTargets.test.ts` and `extensibleAxes.test.ts` | State/variant is invisible to the owner target or becomes an unnecessary parallel target |-| INV7, INV8 | Existing property fixtures (partial; gaps below) | A declared property is missing evidence, or an unlisted counterpart is treated as implied |-| INV9 | API docs and compatibility review | Generic property acceptance is presented as a supported compatibility promise |-| INV10, INV11 | Existing registry/public-var/runtime tests (partial; gaps below) | A public semantic var bypasses admission, or a consumer must write a private var to reach promised behavior |-| INV12, INV13 | Canonical-only runtime emission and discovery, removed-alias rejection, complete codemod mapping/tests, canonical maintained-theme/template inventory, and family-owner fixtures | A removed alias is emitted or discovered, the migration mapping is incomplete, canonical targets change, removed compatibility metadata survives, or ownership stays implicit |-| INV14 | Component contract, owner review, focused no-match fallback test, and structural `extensibleAxes.test.ts` coverage with its explicit artwork-axis exemption list | An ineligible axis opens, a missing rule changes behavior unpredictably, the map/reflection/docs wiring drifts, or an artwork axis gains reflection or loses its exemption |-| INV15 | Shared root/adaptation component-validation fixtures covering finite, open, enrolled, and unresolved domains | Root and adaptation disagree, a valid open value requires a root style, a rule conditionally enrolls a custom value, or unresolved behavior becomes adaptation-specific |+| Invariant | Evidence | Failure signal |+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |+| INV1 | Cross-package target/documentation inventory | An exported target in a participating package is invisible to metadata or CLI validation |+| INV2, INV3 | Bidirectional anatomy-disposition/target check | A current target has no semantic part owner, anatomy mechanically creates targets, or `none` silently becomes future policy; or separate desktop and touch rows are mounted at once outside the transient switch copy |+| INV4, INV5 | Component review plus rendered DOM inspection | Public target lands on non-painting plumbing or aliases a child primitive without distinct semantics |+| INV6 | `themingTargets.test.ts` and `extensibleAxes.test.ts` | State/variant is invisible to the owner target or becomes an unnecessary parallel target |+| INV7, INV8 | Existing property fixtures (partial; gaps below) | A declared property is missing evidence, or an unlisted counterpart is treated as implied |+| INV9 | API docs and compatibility review | Generic property acceptance is presented as a supported compatibility promise |+| INV10, INV11 | Existing registry/public-var/runtime tests (partial; gaps below) | A public semantic var bypasses admission, or a consumer must write a private var to reach promised behavior |+| INV12, INV13 | Canonical-only runtime emission and discovery, removed-alias rejection, complete codemod mapping/tests, canonical maintained-theme/template inventory, and family-owner fixtures | A removed alias is emitted or discovered, the migration mapping is incomplete, canonical targets change, removed compatibility metadata survives, or ownership stays implicit |+| INV14 | Component contract, owner review, focused no-match fallback test, and structural `extensibleAxes.test.ts` coverage with its explicit artwork-axis exemption list | An ineligible axis opens, a missing rule changes behavior unpredictably, the map/reflection/docs wiring drifts, or an artwork axis gains reflection or loses its exemption |+| INV15 | Shared root/adaptation component-validation fixtures covering finite, open, enrolled, and unresolved domains | Root and adaptation disagree, a valid open value requires a root style, a rule conditionally enrolls a custom value, or unresolved behavior becomes adaptation-specific |Known conformance and verification gaps:diff --git a/docs/specs/AST-017/spec.md b/docs/specs/AST-017/spec.mdindex e4637b086d..f57100d57a 100644--- a/docs/specs/AST-017/spec.md+++ b/docs/specs/AST-017/spec.md@@ -104,7 +104,9 @@ affects_consumer_docs: [release-process, templates]"DEC-16","DEC-22","FR59",- "DEC-25"+ "DEC-25",+ "FR60",+ "DEC-26"]}}@@ -741,6 +743,14 @@ one removal merged ahead of the decision to allow it.cross-device consistency change: it needs its own owner decision under thegoverning design or component record. Otherwise fine-pointer behavior andappearance stay as they were.+- **FR60 — Components are built from minimal DOM, and reducing it is compatible.**+ A component renders one element per role, themable part, or named wrapper,+ expresses states through attributes and styles, renders content once, and+ mounts one presentation per open layer, under the two budgets and the+ exception path `architecture:component-style-authoring` INV7 states. Removing+ or merging undocumented elements to meet it is compatible (FR3); an element a+ current theme target or documented anatomy names stays. A component exceeds a+ budget only through an owner exception recorded with its element counts.### Platform support@@ -891,6 +901,7 @@ lands, maintainers apply its requirement in review and release approval.| FR53 | Changeset classification review against the governing component record's accessibility evidence | a fix that replaces documented keyboard or focus behavior to meet an adopted APG pattern's required parts; a fix that changes a role, state, or accessible name to meet WCAG 2.2 A/AA; a fix that adds an optional prop | An accessibility fix is held for a minor, given a coexistence path, or classified `[breaking]`; or a change that needs an app-layer code edit, or that removes, renames, or narrows public surface, ships as an accessibility `[fix]` || FR54 | Changeset classification review against the surface's current record, then the same tier admission every Changeset receives | a CLI correction the CLI record classifies as `[fix]`; a CLI change the CLI record leaves undecided; a CLI change the CLI record classifies as `[breaking]` on a patch plan; a component change | A non-component change is classified by a rule this record restates instead of its surface record, a surface rule turns on risk or adoption, a surface-classified `[breaking]` change ships in a patch or a surface rule makes it patch-eligible, or a component change is classified by a surface record || FR59 | Pull request review of fine-pointer before-and-after evidence | a touch change that also fixes a defect fine-pointer users hit; a deliberate cross-device consistency change; a touch-only change; a new fine-pointer look proposed with touch work | A touch change alters fine-pointer behavior or appearance with neither reason, shows no fine-pointer before-and-after evidence, or ships a new fine-pointer look without its own owner decision |+| FR60 | Element counts per story at rest and open, fine and coarse pointer, against architecture INV7 | a surface component at rest; an open layer; a DOM reduction; a recorded exception | An element beyond INV7's budgets with no recorded owner exception, a hidden twin or second presentation, or a DOM reduction that removes a theme target or documented anatomy, or that is classified as breaking |## Decision log@@ -1349,6 +1360,21 @@ owner decision.Rejected: letting touch work change fine-pointer behavior freely, and forbidding every fine-pointer change, which would block real desktop fixes.+### DEC-26 — Components are built from minimal DOM++**Reference:** `spec:AST-017/DEC-26`+**Decider:** `cixzhang`, `2026-10-24`++Correct construction, not a running change budget, is what keeps components+light: one element per role, themable part, or named wrapper, states through+attributes and styles, content rendered once, and one presentation per open+layer. Two budgets make that checkable, one for surface components at rest and+one for open layers, and an owner-recorded exception path covers the cases that+genuinely need more. Because undocumented markup is not a released contract,+reducing DOM to meet the rule is compatible.++Rejected: a budget that only limits how many elements a change may add, which says nothing about what a correct component looks like.+## Open questionsNone.