Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

docs(spec): Core hydrates to the server markup; entry animation starts after hydration (#7621)

Cindy Zhangc9f265949703
diff --git a/docs/specs/AST-013/spec.md b/docs/specs/AST-013/spec.md
index 5d7e0c2dbd..85cfd51a17 100644
--- a/docs/specs/AST-013/spec.md
+++ b/docs/specs/AST-013/spec.md
@@ -14,7 +14,8 @@ affects_architecture:
[architecture:layer-runtime, architecture:public-component-api]
affects_families: [family:overlay-dismissal]
affects_contributing: [contributing:api-conventions]
-affects_consumer_docs: [browser-support, useLayer, Popover, Toast, Dialog]
+affects_consumer_docs:
+ [browser-support, useLayer, Popover, Toast, Dialog, useEntryAnimation]
---
# Browser and platform support system spec
@@ -34,7 +35,8 @@ affects_consumer_docs: [browser-support, useLayer, Popover, Toast, Dialog]
"FR8",
"FR9",
"FR10",
- "FR12"
+ "FR12",
+ "FR13"
]
}
}
@@ -103,11 +105,15 @@ requirements. Assistive-technology evidence remains separately owned.
or `NaN` geometry, hide essential content, make controls unreachable, orphan or
trap focus, block the surrounding page, corrupt controlled state, remain stuck
pending, or flash a false open, closed, loading, positioned, or styled state.
-- **FR9 — SSR and hydration are consistent.** SSR-capable components do not read
- browser capability, geometry, input modality, or user-agent state during server
- render. The first client render matches the server contract. Post-hydration
- enhancement begins from a usable state and introduces no mismatch, broken
- intermediate state, or visible false state.
+- **FR9 — SSR and hydration are consistent.** A Core component is SSR-capable
+ unless its component spec records an FR12 exception. A client directive does
+ not exempt a component, because frameworks render client components on the
+ server. SSR-capable components do not read browser capability, geometry, input
+ modality, paint timing, or user-agent state during server render or during the
+ client render that hydrates server markup. The hydrating render produces the
+ same markup as the server. Post-hydration enhancement begins from a usable
+ state and introduces no mismatch, broken intermediate state, or visible false
+ state.
- **FR10 — Browser-owned behavior needs real-browser evidence.** Source, unit, and
jsdom tests may prove guards and deterministic state. Changes to layout, paint,
focus, native Popover or Dialog behavior, top-layer order, browser event timing,
@@ -134,6 +140,12 @@ requirements. Assistive-technology evidence remains separately owned.
`spec:AST-013` and record only stricter requirements or explicit exceptions. An
exception names the affected capability, observable reduction, preserved
FR7–FR9 obligations, evidence, owner, and review condition.
+- **FR13 — Server-rendered elements skip their mount animation.** An element present in
+ server markup hydrates in its settled state and does not play the animation it
+ plays when it mounts (its entry animation). That mount animation plays only for
+ an element the client mounts after hydration, or in a client-only root after
+ the first paint. Later open, show, and state transitions of a hydrated element
+ are outside this requirement, and reduced-motion behavior is unchanged.
### Platform support
@@ -155,15 +167,27 @@ support. Routine changes may land with evidence appropriate to their claims.
Defects reproduced in an explicitly supported browser remain actionable whether
or not an automated lane exists.
+`useEntryAnimation`, and FieldStatus through it, decides whether to animate from a
+first-paint flag captured on its first render. When markup hydrates after the
+page paints, the hydrating render produces entry-animation classes the server did
+not send, and the hook's consumer documentation says it does not support server
+rendering.
+
+Other known FR9 and FR13 gaps: a Dialog rendered open in server markup plays its
+entry animation on page load; CodeBlock's collapse chevron plays its reveal
+animation on page load; and CodeBlock chooses between token-span and Highlight
+API markup from browser capability and user-agent checks during render, so the
+hydrating render can differ from the server's markup.
+
## Verification
-| Contract | Required evidence | Failure signal |
-| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| FR1–FR5 | Generated-row check plus guide/package/support/test reconciliation | A handwritten/build version becomes a support claim, explicit support rows disappear, or supported behavior is reduced |
-| FR6–FR8 | Feature-present/absent tests and active fallback fixtures | Browser sniffing selects ordinary behavior, or fallback is unusable, inaccessible, unstable, or visibly broken |
-| FR9 | Server render, hydration, and post-hydration browser fixture | Markup diverges, browser state is read on the server, or a false/broken state flashes |
-| FR10 | Real-browser evidence for browser-owned behavior; the actual named browser for specific claims, browser-only defects, and compatibility changes | Browser-owned behavior is credited to jsdom, another engine stands in for a named-browser claim, or a supported-browser defect is dismissed for lack of a lane |
-| FR11–FR12 | Release review and knowledge-record checks | A floor/fallback disappears without compatibility treatment, or a component silently overrides the baseline |
+| Contract | Required evidence | Failure signal |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| FR1–FR5 | Generated-row check plus guide/package/support/test reconciliation | A handwritten/build version becomes a support claim, explicit support rows disappear, or supported behavior is reduced |
+| FR6–FR8 | Feature-present/absent tests and active fallback fixtures | Browser sniffing selects ordinary behavior, or fallback is unusable, inaccessible, unstable, or visibly broken |
+| FR9, FR13 | Server render then hydrate: no hydration warning or recoverable error, hydrated attributes equal the server markup, a client mount after hydration still plays its mount animation, plus a real-browser server render, hydration, and post-hydration fixture | Markup diverges, browser state is read on the server or while hydrating, a server-rendered element plays its mount animation, or a false/broken state flashes |
+| FR10 | Real-browser evidence for browser-owned behavior; the actual named browser for specific claims, browser-only defects, and compatibility changes | Browser-owned behavior is credited to jsdom, another engine stands in for a named-browser claim, or a supported-browser defect is dismissed for lack of a lane |
+| FR11–FR12 | Release review and knowledge-record checks | A floor/fallback disappears without compatibility treatment, or a component silently overrides the baseline |
## Decision log
@@ -191,6 +215,18 @@ browser-specific claim, fixes a defect reproduced only there, or changes
compatibility. Missing automation neither narrows support nor justifies dismissing
a reproduced defect.
+### DEC-3 — Core hydrates to the server markup; server-rendered elements skip their mount animation
+
+**Reference:** `spec:AST-013/DEC-3`
+**Decider:** `cixzhang`, `2026-10-15`
+
+Core components render the same markup on the server and in the hydrating client
+render, including client components, and a server-rendered element stays settled
+rather than playing its mount animation. Rejected: consumer-doc "does not support
+SSR" exceptions, because FR12 records exceptions only in component specs.
+Rejected: a "has painted" snapshot that turns true after hydration, because it
+animates elements present on page load.
+
## Open questions
None.