docs: semantics docs by lancesnider · Pull Request #635 · rive-app/rive-docs

lancesnider · 2026-04-24T22:43:23Z

Remaining todo's:

Feature support (just need versions)
There's at least one page that says we don't support semantics
Runtime flags
Images (waiting for UI updates)

mintlify · 2026-04-24T22:43:26Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
rive	🟢 Ready	View Preview	Apr 24, 2026, 10:45 PM

💡 Tip: Enable Workflows to automatically generate PRs for you.

HayesGordon · 2026-04-28T16:04:22Z

                ]
              },
+              {
+                "group": "Accessibility & Interaction",


I recall us chatting about this, but I don't remember why we landed on & Interaction?

I'd prefer just Accessibility.

I think it was to better encompass focus, but I think "Accessibility" is good enough. :thu

HayesGordon · 2026-04-28T16:05:22Z

+
+At a high level, semantics are made up of:
+
+- [Type](#semantic-type) — what the element is (for example, button, image, or heading)


Not Type but Role

HayesGordon · 2026-04-28T16:07:33Z

+
+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.
+
+At a high level, semantics are made up of:


We should also include Semantic Actions somewhere.

HayesGordon · 2026-04-28T16:08:42Z

+
+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.
+
+At a high level, semantics are made up of:


I like this description for Roles, Traits, and States:

Architecture: Role / Trait / State

Role - what the node is (button, checkbox, tab, etc.)

Trait - what the node can do (expandable, selectable, checkable, etc.)

State - what the node is doing (expanded, selected, checked, etc.)

Some state flags are only meaningful when their corresponding trait is set. Without the trait, the platform sees the property as not applicable.

I like it. 👍

HayesGordon · 2026-04-28T16:09:12Z

+- [Type](#semantic-type) — what the element is (for example, button, image, or heading)
+- [Properties](#semantic-properties) — additional information like label, value, or hint
+- [Traits](#traits) — capabilities an element has (for example, selectable or expandable)
+- [State](#state) — the current value of a trait (for example, selected or disabled)


Not all states relate to a trait. It's just that some states are gated by a trait

What's the difference between a locked trait and a traitless state? What makes enableable a trait with a lock icon and obscured not a trait?

Never mind. Your other comment explains it " Some state flags are only meaningful when their corresponding trait is set. Without the trait, the platform sees the property as not applicable."

HayesGordon · 2026-04-28T16:11:30Z

+
+## Adding Semantics
+
+<img src="/images/accessibility-interaction/semantics/adding-semantics.gif" width="300" />


Might not be immediately clear where to find this, as the video doesn't show it's the inspector

Updated.

btw There are other gifs to add, but the ui is still WiP.

HayesGordon · 2026-04-28T16:13:06Z

+  <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 Type">


Role not Type

HayesGordon · 2026-04-28T16:15:40Z

+For example, a slider that controls volume might have the label:
+`Volume`
+
+<Info>


Let's remove this. This is true, but not all platforms and screen readers are equal. For example, the web might announce "expanded", but iOS does not. There might be times when authors want to provide a more unique experience by controlling the label instead of relying on the role.

HayesGordon · 2026-04-28T16:17:45Z

+  Avoid including the type in the label (for example, "slider" or "button"). Screen readers already announce the element’s type.
+</Info>
+
+<Info>


Let's add a new section called "Semantic Inference".

Here we can detail that certain Rive components will infer it's label (and other properties) automatically. At this time it's only a Text component that will automatically set its label to the text set.

I'm gonna push back a little. :)

Inference isn't a sibling section to traits and properties, it's a child of both. It's also not something you need to learn about - it feels like something most people will figure out on their own.

The only time people might look for it in the docs is if they've added a text field and can't figure out why they can't change the role. In that case, they'll go to the "Role" section, not the "semantic inference" section.

HayesGordon · 2026-04-28T16:19:36Z

+  Some elements, like text inputs, automatically infer their semantic type.
+</Info>
+
+## Semantic Properties


Might be nice to state the type these properties should be. At this stage it's all strings, but maybe in the future we others.

HayesGordon · 2026-04-28T16:21:22Z

+
+For example, an element with the **selectable** trait will have a **selected** state.
+
+Use data binding to 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 can also key the state on an animation timeline

HayesGordon · 2026-04-28T16:22:52Z

+
+Small issues—like a missing label or incorrect state—can make elements confusing or unusable for screen reader users.
+
+### How to Test


Maybe worth calling out that this should be tested at runtime, and not the editor. Or maybe soon we can say the mirror apps

HayesGordon · 2026-04-28T16:28:01Z

+description: ""
+---
+
+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.


At some point early in the document, we should highlight that this is in Early Access, and that runtime support is currently in development or released as experimental.

Inconsistencies should be reported to us, but it's worth noting that not all Roles we expose are valid across every runtime. We will document these over time.

We also need a runtime page to detail how to enable (opt-in at this stage), plus how to test etc. But that can be a separate PR.

Then we also need to update the feature support page to list out the state of this feature support on runtimes. Currently we can say that Flutter has experimental support from version 0.14.6

tylernij

Gordon has some suggestions but afterwards 👍

lancesnider · 2026-04-29T00:41:59Z

Thanks @HayesGordon and @tyler. I've implemented most of your feedback, though there are a couple of todo's I'll add to the description.

zplata · 2026-04-29T19:46:32Z

-
-#### 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.


nit: this small aria label section could still be useful as a "at a minimum, if semantic nodes are not used in your Rive graphic"

lancesnider added 2 commits April 21, 2026 17:06

add pages to nav

fb7e8e8

docs: semantics

8b7007f

lancesnider requested a review from a team as a code owner April 24, 2026 22:43

mintlify Bot deployed to staging April 24, 2026 22:45 View deployment

Add gif

4780d47

mintlify Bot deployed to staging April 24, 2026 23:15 View deployment

HayesGordon reviewed Apr 28, 2026

View reviewed changes

tylernij previously approved these changes Apr 28, 2026

View reviewed changes

gordon feedback

2672d35

lancesnider dismissed tylernij’s stale review via 2672d35 April 29, 2026 00:41

mintlify Bot deployed to staging April 29, 2026 00:42 View deployment

update ea note

9076479

mintlify Bot deployed to staging April 29, 2026 00:45 View deployment

add note on legacy text pages

8220e09

mintlify Bot deployed to staging April 29, 2026 00:57 View deployment

remove semantics docs from deprecated runtime/text pages

ddf82de

mintlify Bot deployed to staging April 29, 2026 18:11 View deployment

add feature support table

0d25d85

mintlify Bot deployed to staging April 29, 2026 18:28 View deployment

zplata reviewed Apr 29, 2026

View reviewed changes


		At a high level, semantics are made up of:

		- [Type](#semantic-type) — what the element is (for example, button, image, or heading)


		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.

		At a high level, semantics are made up of:


		## Adding Semantics

		<img src="/images/accessibility-interaction/semantics/adding-semantics.gif" width="300" />


		For example, an element with the selectable trait will have a selected state.

		Use data binding to 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.


		Small issues—like a missing label or incorrect state—can make elements confusing or unusable for screen reader users.

		### How to Test


		#### 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.

Conversation

lancesnider commented Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mintlify Bot commented Apr 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

HayesGordon Apr 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Architecture: Role / Trait / State

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

tylernij left a comment

Choose a reason for hiding this comment

Uh oh!

lancesnider commented Apr 29, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

lancesnider commented Apr 24, 2026 •

edited

Loading

mintlify Bot commented Apr 24, 2026 •

edited

Loading

HayesGordon Apr 28, 2026 •

edited

Loading