diff --git a/src/routes/reference/components/suspense.mdx b/src/routes/reference/components/suspense.mdx
index 45a66d75a..89f0173a7 100644
--- a/src/routes/reference/components/suspense.mdx
+++ b/src/routes/reference/components/suspense.mdx
@@ -13,150 +13,78 @@ tags:
- data-fetching
version: '1.0'
description: >-
- Handle async operations elegantly in SolidJS with Suspense. Show loading
- states while resources load without blocking UI rendering.
+ Coordinate loading states for async resources with a suspense boundary in Solid.
---
-A component that tracks all resources read under it and shows a fallback placeholder state until they are resolved. What makes `Suspense` different than `Show` is that it is non-blocking in the sense that both branches exist at the same time even if not currently in the DOM. This means that the fallback can be rendered while the children are loading. This is useful for loading states and other asynchronous operations.
+`Suspense` is the core boundary for async rendering in Solid.
+Renders `fallback` content while tracked resources are pending.
+
+## Import
```tsx
import { Suspense } from "solid-js"
-import type { JSX } from "solid-js"
-
-function Suspense(props: {
- fallback?: JSX.Element
- children: JSX.Element
-}): JSX.Element
-
```
-Here's an example of a `Suspense` component that shows a loading spinner while the `User` component is loading.
+## Type signature
```tsx
-}>
-
-
+import type { JSX } from "solid-js"
+function Suspense(props: {
+ fallback?: JSX.Element;
+ children: JSX.Element;
+}): JSX.Element;
```
-## Nested Suspense
-
-`` is triggered whenever a resource is read under the suspense boundary, and waits until all resources read
-under the suspense boundary have resolved. Often, however, you may not want this behavior. For example, if your entire page is
-wrapped in suspense, you may not want a resource that only populates a certain part of the page to trigger suspense.
-In that case, you can wrap that resource usage in its own suspense boundary, and the resource will only trigger the
-closest suspense boundary.
-
-For example, in the code below, only the `title()` resource will trigger the top level suspense boundary, and only the `data()`
-resource will trigger the nested suspense boundary:
-
-```jsx
-const MyComponent = () => {
- const [title] = createResource(async () => { /* fetcher code here */ })
- const [data] = createResource(async () => { /* fetcher code here */ })
-
- {title()}
-
- {data()}
-
-
-}
+## Parameters
-```
+### `fallback`
-## The purpose of ``
+- **Type:** `JSX.Element`
+- **Required:** No
-To understand the purpose of suspense, let's consider the following code snippets. These snippets will have some drawbacks which we will solve by using suspense. We will also see how it is possible to use `Suspense` yet not reap its benefits.
+Content rendered while tracked resources are pending.
-Our example use case is to display a user profile. A naive snippet would look like this:
+### `children`
-```jsx
-const MyComponentWithOptionalChaining = () => {
- const [profile] = createResource(async () => {
- /* fetcher code here */
- })
- return (
- <>
- {profile()?.name}
- {profile()?.email}
-
- )
-}
+- **Type:** `JSX.Element`
+- **Required:** Yes
-```
+Content rendered after tracked resources resolve.
-In this code, `profile()` starts as `undefined`, and when the fetcher code finishes, resolves to an object with `name` and `email` properties. Although the resource has not resolved yet, the two `div`s are already created and attached to the document body, albeit with empty text nodes. Once the resource resolves, the `div`s are updated with the appropriate data.
+## Return value
-The downside of this approach is that the user is shown an empty component - let's see if we can do better than that in this next snippet:
+- **Type:** `JSX.Element`
-```jsx
-const MyComponentWithShow = () => {
- const [profile] = createResource(async () => {
- /* fetcher code here */
- })
- return (
- fetching user data}>
- {profile().name}
- {profile().email}
-
- )
-}
+Returns a suspense boundary component that controls what renders to the DOM.
+Component execution continues while the fallback is visible, preparing child content for display once resources resolve.
-```
-
-In this snippet, we first show a fallback when the resource hasn't resolved yet, and then switch to showing the profile data once it has. This results in a better user experience.
+## Examples
-On the other hand, there is a slight downside to this approach. In our first example (using optional chaining), the divs were created immediately, and once the resource resolves all that is needed to be done is to fill in the text of the `div`s. But in our second example (using ``), the `div`s are only created once the resource has resolved, which means there is more work that needs to be done after the resource has resolved before the data can be shown to the user (of course, in this toy example the amount of DOM work is relatively trivial).
+### Basic usage
-We can have the best of both worlds by using {""}:
+Use a boundary whenever a subtree reads async resources and requires an explicit loading state.
-```jsx
-const MyComponentWithSuspense = () => {
- const [profile] = createResource(async () => {
- /* fetcher code here */
- })
- return (
- fetching user data}>
- {profile()?.name}
- {profile()?.email}
-
- )
-}
+```tsx
+}>
+
+
```
-In this case, the `div`s are created immediately, but instead of being attached to the document body, the fallback is shown. Once the resource resolves, the text in the `div`s is updated, and then they are attached to the document (and the fallback removed).
-
-It is important to note that _the execution of the component does not pause_ when using suspense. Instead, when a resource is read under a suspense boundary, it ensures that the nodes are not attached to the document until after the resource has resolved. Suspense allows us to have the best of both worlds: do as much work as we can _before_ the resource resolves, and also show a fallback until then.
-
-With this in mind, we can understand that there isn't much gained from suspense in the following code:
-
-```jsx
-const MyComponentWithSuspenseAndShow = () => {
- const [profile] = createResource(async () => {
- /* fetcher code here */
- })
- return (
- fetching user data}>
-
- {profile().name}
- {profile().email}
-
-
- )
-}
-```
+### Nested boundaries
+
+Nested boundaries scope loading states to the nearest boundary, preventing one slow resource from blocking unrelated UI.
-In this code, we don't create _any_ DOM nodes inside {""} before the resource resolves, so it is pretty much the same as the second example where we only used ``.
-:::note
- Suspense is triggered by reading a resource inside the {""}{" "}
- boundary. Components wrapped with suspense still run fully, just as they would
- without suspense. However, code wrapped in `onMount` and `createEffect` only
- run after the resource resolves.
-:::
+```tsx
+const [title] = createResource(fetchTitle)
+const [data] = createResource(fetchData)
-## Props
+Loading title...}>
+ {title()}
+ Loading details...}>
+ {String(value)}
;
+}
+```
+
+## Related
+
+- [`relatedApi`](/reference/path/to/related-api)
diff --git a/templates/jsx-attribute-syntax.mdx b/templates/jsx-attribute-syntax.mdx
new file mode 100644
index 000000000..e36697cc9
--- /dev/null
+++ b/templates/jsx-attribute-syntax.mdx
@@ -0,0 +1,45 @@
+---
+title: Attribute name
+description: One-sentence factual description of what this JSX attribute or syntax form does.
+---
+
+# `attributeName`
+
+Add one or two short sentences that define the syntax and where it applies.
+
+## Syntax
+
+```tsx
+
+```
+
+## Value
+
+- **Type:** `ValueType`
+
+Describe the accepted value shape and any important variants.
+
+## Behavior
+
+Describe how Solid interprets, compiles, or applies this syntax.
+Keep this section factual and limited to semantics needed to use the feature correctly.
+
+## Constraints
+
+- Add ordering rules, spread limitations, SSR caveats, or DOM constraints only when needed.
+
+## Examples
+
+### Basic usage
+
+```tsx
+function Example() {
+ let element!: HTMLDivElement;
+
+ return ;
+}
+```
+
+## Related
+
+- [`relatedApi`](/reference/path/to/related-api)