docs: semantics docs

docs.json

@@ -207,6 +207,12 @@
                   "editor/layouts/scrolling"
                 ]
               },
+              {
+                "group": "Accessibility",
+                "pages": [
+                  "editor/accessibility/semantics"
+                ]
+              },
               "editor/libraries",
               "editor/keyboard-shortcuts",
               {

editor/accessibility/semantics.mdx

@@ -0,0 +1,215 @@
+---
+title: "Semantics"
+description: "Make your experiences accessible to screen readers by defining semantic types, properties, states, and actions"
+---
+
+<Note>
+  Semantics is currently only available in [Early Access](https://rive.app/downloads?utm_source=docs&utm_medium=content). Runtime support is in development or released as experimental.
+
+  Have feedback? Join the [Early Access community](https://community.rive.app/c/early-access/) to share your thoughts and help shape the feature.
+</Note>
+
+Semantics describe what an element is and how it should be understood. Adding semantics makes your experiences accessible, allowing screen readers to correctly describe and navigate your content.
+
+**Architecture: Role / Trait / State / Actions**
+
+- [Role](#semantic-role) — what the node is (button, checkbox, tab, etc.)
+- [Properties](#semantic-properties) — additional information like label, value, or hint
+- [Traits](#traits) — what the node can do (expandable, selectable, checkable, etc.)
+- [State](#state) — what the node is doing (expanded, selected, checked, etc.)
+- [Actions](#actions) - interactions triggered by the user (tap, increase, decrease)
+
+<Note>
+  **Semantics at Runtime**
+
+  At runtime, semantics are converted into the platform’s accessibility system.
+
+  On web, this creates accessible DOM elements (for example, divs with roles and attributes). On iOS and Android, a semantic tree is generated and exposed to the system’s accessibility APIs.
+
+  Rive handles mapping your semantics to each platform automatically. For details on which runtimes currently support semantics, see [Feature Support](/feature-support).
+</Note>
+
+## Adding Semantics
+
+![Adding semantics](/images/accessibility/semantics/adding-semantics.gif)
+
+<Steps>
+  <Step title="Add Semantics">
+    Select an element in your scene. In the right sidebar, click the `+` button in the **Semantics** panel to enable semantics for that element.
+  </Step>
+  <Step title="Choose a Role">
+    Use the dropdown to assign a [semantic role](#semantic-role), such as button, image, or heading.
+  </Step>
+  <Step title="Configure Properties">
+    Update the element’s [semantic properties](#semantic-properties), [Traits](#traits), and [State](#state).
+  </Step>
+</Steps>
+
+### Semantic Role
+
+The semantic role defines what the element *is* (for example, a button or image). Screen readers use this to describe the element and determine how it should behave.
+
+Each role has different available [properties](#semantic-properties).
+
+If your element doesn’t match a specific role, you can leave it set to **None**.
+
+<Info>
+  Some elements, like text, automatically infer their semantic role. See [Semantic Inference](#semantic-inference) for more info.
+</Info>
+
+## Semantic Properties
+
+Semantic properties provide additional information about an element, such as its label, value, or hint.
+
+Available properties vary depending on the selected semantic role.
+
+### Label
+
+The label describes what the element is or does. This is what screen readers announce.
+
+For example, a slider that controls volume might have the label:
+`Volume`
+
+<Info>
+  Text elements automatically use their text content as the label. See [Semantic Inference](#semantic-inference) for more info.
+</Info>
+
+### Heading (Text only)
+
+Text elements can be marked as headings to define structure and hierarchy.
+
+Options include **None** and **Heading 1** through **Heading 6**.
+
+Headings help screen reader users navigate your content more easily.
+
+<Info>
+  On web, Heading 1 maps to an `<h1>` element, Heading 2 to `<h2>`, and so on.
+</Info>
+
+### Value (Inputs only)
+
+Some elements, like sliders and switches, have a **Value** property that reflects their current state.
+
+For example, a volume slider might have a value of `70%`.
+
+Use data binding to keep the semantic value in sync with the visual state.
+
+---
+
+## Traits
+
+Traits define what an element *can do*, while states describe what it is doing right now.
+
+Some semantic roles include traits, such as **expandable** or **selectable**. Enabling a trait makes its corresponding [state](#state) available.
+
+The lock icon indicates a required trait for that semantic role. For example, a checkbox always includes the **selectable** trait.
+
+
+---
+
+## State
+
+States represent the current value of the node.
+
+For example, an element with the **selectable** trait will have a **selected** state.
+
+Some state flags are only meaningful when their corresponding trait is set. Without the trait, the platform sees the property as not applicable.
+
+Keep semantic states in sync with your Rive file. For example, bind a boolean from your view model to the **toggled** state of a switch. You could also key the **toggled** state in a timeline.
+
+### Hidden
+
+Hides the element from the accessibility tree.
+
+<Note>
+  Elements that are not visible (for example, hidden by layout or soloing) are automatically removed from the accessibility tree and do not require this property.
+
+  Use **Hidden** when an element is still present in the scene (for example, opacity is set to 0) but should not be exposed to assistive technologies.
+</Note>
+
+### Disabled
+
+Marks the element as disabled and not interactive.
+
+### Live Region
+
+Indicates that the element’s content may update dynamically and should be announced by screen readers.
+
+## Actions
+
+Semantic actions are interaction events triggered by assistive technologies. You can listen for these actions and update your experience in response.
+
+
+### Adding an Action
+
+<Steps>
+  <Step title="Create a Listener">
+    Select your object and [create a new Listener](/editor/state-machine/listeners).
+  </Step>
+  <Step title="Listen to a Semantic Action">
+    With your listener selected, in the right sidebar choose **Semantic Action** in the **Listen to** dropdown.
+  </Step>
+  <Step title="Set the action type">
+     Select the [action type](#types-of-actions) to listen for.
+  </Step>
+</Steps>
+
+### Types of Actions
+
+Actions include **tap**, **increase**, and **decrease**. Additional actions may be added in future releases.
+
+#### Tap
+
+Represents activating an element (similar to a click).
+
+When a user activates an element using a screen reader, a **tap** action is triggered. You should listen for this action and handle it the same way as a standard click or pointer interaction.
+
+<Note>
+  It’s common to add both a **Click** and a **Semantic Tap** listener to the same element to support pointer and assistive interactions.
+</Note>
+
+#### Increase / Decrease
+
+Used for adjustable elements like sliders.
+
+Users trigger these actions through assistive technologies—for example, by focusing a slider and swiping up or down with a screen reader, or using arrow keys on a keyboard.
+
+You should listen for **increase** and **decrease** and update your value accordingly.
+
+
+### Semantic Inference
+
+Some roles and properties are inferred based on the element they are applied to.
+
+For example, when adding semantics to a text element, the [Role](#semantic-role) is set to **Text**, and the [Value](#value) is automatically derived from the element’s text content.
+
+---
+
+## Testing Semantics
+
+Adding semantics is only the first step. You should always test your experience at runtime to make sure it behaves as expected.
+
+Small issues—like a missing label or incorrect state—can make elements confusing or unusable for screen reader users.
+
+### Runtime Testing
+
+The best way to test semantics is by using a screen reader.
+
+- **macOS / iOS**: VoiceOver
+- **Android**: TalkBack
+- **Windows**: Narrator or NVDA
+
+Turn on a screen reader and navigate through your experience:
+- Move between elements
+- Listen to how each element is announced
+- Interact with buttons, sliders, and inputs
+
+### What to Check
+
+As you test, pay attention to:
+
+- **Labels** — Does each element clearly describe what it is or does?
+- **Role** — Is the correct role announced (button, heading, etc.)?
+- **Value** — Do dynamic elements (like sliders) report the correct value?
+- **State** — Are states like selected, disabled, or expanded accurate?
+- **Order** — Does navigation follow a logical flow?

feature-support.mdx

@@ -84,6 +84,9 @@ Differences may reflect:
 
 ### Features
 
+<FeatureSupportGroup feature="semantics">
+  Accessibility voice over support with [Semantics](/editor/accessibility/semantics).
+</FeatureSupportGroup>
 <FeatureSupportGroup feature="scripting">
   Support for Rive files with [Scripting](/scripting).
 </FeatureSupportGroup>

runtimes/flutter/text.mdx

@@ -55,21 +55,4 @@ artboard.setText(value, path: path)
 
 <SemanticsForAccessibility />
 
-See Flutter's [documentation on Accessibility](https://docs.flutter.dev/accessibility-and-localization/accessibility) for more information. In this example you'll use the [Semantics widget](https://api.flutter.dev/flutter/widgets/Semantics-class.html) to provide a label that reflects the current value of the Rive Text component.
-
-```
-...
-
-final controller = RiveWidgetController(riveFile);
-final textValue = controller.artboard.getText('some_text_run_name').value;
-String semanticLabel = textValue;
-
-...
-
-Semantics(
-    label: semanticLabel,
-    child: RiveWidget(controller: controller);
-),
-```
-
 <Resources />

runtimes/react/text.mdx

@@ -121,18 +121,4 @@ return (
 
 <SemanticsForAccessibility />
 
-
-
-#### Adding ARIA Label
-
-At a minimum - if it is important to convey the text value displayed in the Rive animation to all users, add an `aria-label` to the `<canvas>` element with the text value from the animation. Screen readers may read this label out immediately as it parses out the DOM contents. You'll also want to add `role="img"` to the `<canvas>` element as well.
-
-#### Adding ARIA Live Region
-
-While ARIA labels are a direct method to manage a textual label for screen readers to read out as it parses web content, using an ARIA live region allows you a way to control when screen readers read out dynamic text content.
-
-Live regions are useful in cases where the text content in your Rive graphic becomes visible or changes on a particular state in a state machine, and you want screen readers to pick up on text changes. Another use case is when you only want screen readers to read your Rive text content when the `<canvas>` is scrolled into view.
-
-Read more on ARIA live regions [here](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Live_Regions).
-
 <Resources />

snippets/feature-support.jsx

@@ -53,6 +53,7 @@ export const FeatureSupportGroup = ({
     ]
 
     const featuresInOrder = [
+        "semantics",
         "scripting",
         "dataBindingListsImagesArtboards",
         "rightToLeftLayoutsText",
@@ -81,6 +82,27 @@ export const FeatureSupportGroup = ({
     ]
 
     const features = {
+        semantics: {
+            title: "Semantics",
+            runtimes: {
+                webCanvas: { supported: false, description: "Coming soon" },
+                webCanvasLite: { supported: false, description: "Not supported" },
+                webWebGL: { supported: false, description: "Not supported" },
+                webWebGL2: { supported: false, description: "Coming soon" },
+                reactCanvas: { supported: false, description: "Coming soon" },
+                reactCanvasLite: { supported: false, description: "Not supported" },
+                reactWebGL: { supported: false, description: "Not supported" },
+                reactWebGL2: { supported: false, description: "Coming soon" },
+                reactNative: { supported: false, description: "Coming soon" },
+                reactNativeLegacy: { supported: false, description: "Not supported" },
+                flutter: { supported: true, version: "0.14.6" },
+                apple: { supported: false, description: "Coming soon" },
+                android: { supported: false, description: "Coming soon" },
+                cpp: { supported: true, description: "Supported" },
+                unity: { supported: false, description: "Not yet supported" },
+                unreal: { supported: false, description: "Not yet supported" }
+            }
+        },
         scripting: {
             title: "Scripting",
             runtimes: {

snippets/runtimes/text/semantics-for-accessibility.mdx

@@ -1,10 +1,6 @@
 ### Semantics for Accessibility
 
-<Tip>
-  We recommend using [Data Binding](/editor/data-binding/overview) instead as
-  you'll be able to do a two-way text binding.
-</Tip>
 
-As Rive Text does not make use of the underlying platform text APIs, additional steps need to be taken to ensure it can be read by screen readers.
+Rive now supports screen readers through semantics.
 
-Please see the respective platform/SDKs developer documentation for additional information regarding accessibility concerns.
+See the [Semantics](/editor/accessibility/semantics) documentation for current guidance.