---
name: rty-web-components-usage
description: Uses Riverty Web Components (@riverty/web-components) to build accessible, token-driven UI. Use when consuming, configuring, or composing Riverty components in an application; handling component custom events; styling components via CSS custom properties or CSS parts; or migrating between component API versions. Do not use for creating new custom components from scratch, or for projects that do not use Riverty Web Components.
metadata:
  skillshare-tags: component-api, component-usage, web-components
---

# Web Components Usage

Procedure for consuming `@riverty/web-components` in an application: pick the right component, configure it correctly, and handle its events and styling.

## Workflow

### Step 1: Confirm the project is set up

1. Verify `@riverty/web-components` is installed and `defineCustomElements()` runs before any `<r-*>` element renders. If not, read `references/installation-setup.md`.
2. Verify design tokens are loaded globally. If unsure, read `references/packages-relationship.md`.

### Step 2: Find the right component

1. Read `references/component-index.md` and locate the component that matches the UI requirement. The index is grouped by category and lists components with a brief description.
2. If nothing matches, stop and tell the user — do not create a new component from this skill.

### Step 3: Read the component API

1. Read `references/components/<tag>.md` for the tag. This file is the source of truth for props, events, slots, methods, CSS parts, and CSS custom properties.
2. Always check `references/deprecations.md` for deprecated props, events, and methods.
3. For prop casing rules, boolean attribute syntax, and Shadow DOM querying, see `references/core-principles.md`.

### Step 4: Compose the markup

1. Set required props from the API table.
2. Project child content only into slots documented in `references/components/<tag>.md`.
3. Follow the composition, labelling, and accessibility rules in `references/best-practices.md`.

### Step 5: Handle events

1. Attach listeners using the event names from the API table. For naming conventions see `references/core-principles.md`.
2. Read `event.detail` for the typed payload shown in the API table.
3. For event handling do/don'ts see `references/best-practices.md`.

### Step 6: Style the component

1. Use CSS Custom Properties and `::part()` selectors listed in the component API. For styling rules and Shadow DOM constraints, see `references/best-practices.md` and `references/core-principles.md`.
2. Preserve inherited `data-theme`, `data-r-ui`, and `data-r-ui-brand` context. Read `references/core-principles.md` before adding mode, Alta, brand, or inverse-specific styling.

### Step 7: Verify output

1. Read `references/best-practices.md` and confirm the implementation satisfies every item in the checklist before delivering output.
2. If any checklist item fails, return to the relevant step and fix the issue. Do not skip this verification.

## Error Handling

| Problem | Cause | Fix |
|---|---|---|
| `defineCustomElements()` not called | Package not initialised | Read `references/installation-setup.md` and follow the setup instructions |
| Component renders without styles | Design tokens not loaded globally | Read `references/packages-relationship.md` and load the token stylesheet |
| No component matches the UI requirement | Gap in the component library | Stop. Tell the user no matching component exists. Do not improvise a replacement |
| Component API file `references/components/<tag>.md` is missing | Tag not yet documented | Tell the user the reference file is absent and fall back to the package's own documentation |
| Deprecated prop or event used | API changed between versions | Read `references/deprecations.md` and apply the listed replacement |
| `::part()` selector has no effect | Part not exposed on that component | Check the CSS parts table in the component API file; only listed parts are styleable |

## Reference Map

| Reference file | When to read                                                                        |
|---|-------------------------------------------------------------------------------------|
| `references/installation-setup.md` | Understanding on how to install the package in a project                            |
| `references/packages-relationship.md` | Understanding of Riverty Design System's packages relationship                      |
| `references/core-principles.md` | Resolving prop casing, boolean attributes, Shadow DOM queries, or inherited theme context. |
| `references/component-index.md` | Choosing a component for a UI requirement.                                          |
| `references/components/<tag>.md` | Full API for a specific tag (props, events, slots, methods, CSS parts/variables).   |
| `references/best-practices.md` | Validating composition, event handling, styling, and accessibility patterns.        |
| `references/deprecations.md` | Finding replacements for deprecated props, events, and methods.                     |