migrate jsx attribute refs and attribute directives

Author: LadyBluenotes

src/routes/reference/jsx-attributes/attr.mdx

@@ -1,29 +1,50 @@
 ---
 title: "attr:*"
 use_cases: >-
-  web components, custom elements, forcing attributes, html attributes, dom
-  properties
+  custom elements, forcing attribute assignment, writing HTML attributes
 tags:
   - attributes
-  - web-components
   - dom
-  - props
-  - typescript
   - custom-elements
 version: "1.0"
 description: >-
-  Force props as HTML attributes instead of properties in SolidJS. Essential for
-  Web Components and custom element attribute handling.
+  Force a JSX key to be written as an attribute instead of a property.
 ---
 
-Forces the prop to be treated as an attribute instead of a property.
-Useful for Web Components where you want to set attributes.
-
-```tsx
-<my-element attr:status={props.status} />
-```
+`attr:*` forces a JSX key to be written as an attribute instead of a property.
 
 :::note[Strong-Typing Custom Attributes]
 Type definitions are required when using TypeScript.
 See the[TypeScript](/configuration/typescript#forcing-properties-and-custom-attributes) page for examples.
 :::
+
+## Syntax
+
+```tsx
+<my-element attr:status={value} />
+```
+
+## Value
+
+- **Type:** attribute value
+
+Value written to the attribute after the `attr:` prefix is removed.
+
+## Behavior
+
+- `attr:name={value}` writes the value to the `name` attribute.
+- The `attr:` prefix is removed before the attribute is written.
+- This is useful when an element expects data through attributes rather than DOM properties.
+
+## Examples
+
+### Basic usage
+
+```tsx
+<my-element attr:status={props.status} />
+```
+
+## Related
+
+- [`prop:*`](/reference/jsx-attributes/prop)
+- [`bool:*`](/reference/jsx-attributes/bool)

src/routes/reference/jsx-attributes/bool.mdx

@@ -1,39 +1,59 @@
 ---
 title: "bool:*"
 use_cases: >-
-  web components, custom elements, conditional attributes, boolean attributes,
-  dynamic attribute presence
+  boolean attributes, custom elements, controlling attribute presence
 tags:
   - attributes
-  - web-components
   - boolean
-  - conditional
-  - dynamic
+  - custom-elements
 version: "1.0"
 description: >-
-  Control attribute presence with bool:* directive in SolidJS. Add or remove
-  attributes dynamically based on truthy/falsy values for web components.
+  Control whether an attribute is present by writing through `bool:*`.
 ---
 
-`bool:*` controls the presence of an attribute in an element.
-When the value is `truthy` it adds the `attribute` to the element.
-Alternatively, when the value is `falsy` it removes the `attribute` from the element.
-This attribute is most useful for Web Components.
+`bool:*` controls whether an attribute is present on an element.
+
+:::note[Strong-Typing Custom Boolean Attributes]
+Type definitions are required when using TypeScript.
+See the [TypeScript](/configuration/typescript#forcing-properties-and-custom-attributes) page for examples.
+:::
+
+## Syntax
 
 ```tsx
-<my-element bool:status={prop.value} />
+<my-element bool:status={value} />
 ```
 
+## Value
+
+- **Type:** any truthy or falsy value
+
+Truthy values add the attribute. Falsy values remove it.
+
+## Behavior
+
+- `bool:name={value}` adds `name` when `value` is truthy.
+- `bool:name={value}` removes `name` when `value` is falsy.
+- When present, the attribute is written as an empty string attribute.
+
+## Examples
+
+### Basic usage
+
+```tsx
+<my-element bool:status={props.value} />
+```
+
+### Resulting markup
+
 ```tsx
-// Assuming `prop.value` is `truthy`, then it becomes
+// props.value is truthy
 <my-element status />
 
-// And when `falsy`, then it becomes
+// props.value is falsy
 <my-element />
-
 ```
 
-:::note[Strong-Typing Custom Boolean Attributes]
-Type definitions are required when using TypeScript.
-See the [TypeScript](/configuration/typescript#forcing-properties-and-custom-attributes) page for examples.
-:::
+## Related
+
+- [`attr:*`](/reference/jsx-attributes/attr)

src/routes/reference/jsx-attributes/prop.mdx

@@ -2,27 +2,50 @@
 title: "prop:*"
 order: 6
 use_cases: >-
-  dom properties, scrolltop manipulation, custom properties, property vs
-  attribute, direct property access
+  forcing property assignment, writing DOM properties, custom element property
+  access
 tags:
   - properties
   - dom
   - attributes
-  - manipulation
-  - custom
 version: "1.0"
 description: >-
-  Force DOM property assignment with prop:* in SolidJS. Set properties directly
-  instead of attributes for specific DOM manipulation needs.
+  Force a JSX key to be written as a DOM property instead of an attribute.
 ---
 
-Forces the prop to be treated as a property instead of an attribute.
-
-```tsx
-<div prop:scrollTop={props.scrollPos + "px"} />
-```
+`prop:*` forces a JSX key to be written as a DOM property instead of an attribute.
 
 :::note[Strong-Typing Custom Properties]
 Type definitions are required when using TypeScript.
 See the [TypeScript](/configuration/typescript#forcing-properties-and-custom-attributes) page for examples.
 :::
+
+## Syntax
+
+```tsx
+<div prop:scrollTop={value} />
+```
+
+## Value
+
+- **Type:** property value
+
+Value assigned to the property after the `prop:` prefix is removed.
+
+## Behavior
+
+- `prop:name={value}` assigns the value to the `name` property.
+- The `prop:` prefix is removed before the assignment happens.
+- This is useful when an element expects data through properties rather than attributes.
+
+## Examples
+
+### Basic usage
+
+```tsx
+<div prop:scrollTop={props.scrollPos} />
+```
+
+## Related
+
+- [`attr:*`](/reference/jsx-attributes/attr)

src/routes/reference/jsx-attributes/ref.mdx

@@ -2,37 +2,56 @@
 title: ref
 order: 7
 use_cases: >-
-  dom access, element manipulation, focus management, measurements, third-party
-  libraries, animations
+  element references, imperative DOM access, component refs
 tags:
   - refs
   - dom
   - elements
-  - access
-  - manipulation
-  - components
 version: "1.0"
 description: >-
-  Access DOM elements directly in SolidJS with refs. Get references to rendered
-  elements for imperative operations and third-party integrations.
+  Capture a rendered element or forwarded component ref.
 ---
 
-Refs are a way of getting access to underlying DOM elements in our JSX. While it is true one could just assign an element to a variable, it is more optimal to leave components in the flow of JSX. Refs are assigned at render time but before the elements are connected to the DOM. They come in 2 flavors.
+`ref` captures a rendered element or forwarded component ref.
+
+## Syntax
+
+```tsx
+<div ref={value} />
+```
+
+## Value
+
+- **Type:** variable binding or callback function
+
+Receives the rendered element or forwarded ref value.
+
+## Behavior
+
+- Refs are assigned during rendering before the element is connected to the DOM.
+- A variable ref assigns the rendered element to the referenced variable.
+- A callback ref is called with the rendered element.
+- Component refs work only when the component forwards the `ref` prop to an underlying element or child component.
+
+## Examples
+
+### Variable ref
 
 ```tsx
-// variable assigned directly by ref
 let myDiv;
 
-// use onMount or createEffect to read after connected to the DOM
 onMount(() => console.log(myDiv));
 
-<div ref={myDiv} />
+<div ref={myDiv} />;
+```
+
+### Callback ref
 
-// Or, callback function (called before connected to the DOM)
-<div ref={el => console.log(el)} />
+```tsx
+<div ref={(el) => console.log(el)} />
 ```
 
-Refs can also be used on Components. They still need to be attached on the other side.
+### Component ref
 
 ```tsx
 function MyComp(props) {