Skip to content

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.md
index 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 predictab
with supported consumer styling, keep relational state scoped to the intended
component, 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 redefine
semantic 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 guidance
The 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 through
INV1–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 property
composition;
- 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 a
component reads (INV6).
@@ -222,18 +272,22 @@ before assigning a verdict.
- `spec:AST-080/DEC-4` — every pull request reports component JavaScript and
CSS size; touch-only JavaScript over 2 KB or CSS over 1 KB is flagged, and
shared 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, and
RSC 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.md
index 80b0bffd7e..dc98ff8b68 100644
--- a/docs/architecture/component-theming-surface.md
+++ b/docs/architecture/component-theming-surface.md
@@ -7,7 +7,7 @@ authority: current
archive_reason: null
superseded_by: null
approved_by: cixzhang
-approved_at: 2026-09-07
+approved_at: 2026-10-24
owners: [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 intentional
current boundary from a reachability gap or unsettled future exposure; it never
silently 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 that
paints theme-controlled output—not an event wrapper, speculative internal
structure, 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 names
each 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 deprecated
theming 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.md
index 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 the
governing design or component record. Otherwise fine-pointer behavior and
appearance 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 questions
None.