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

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

### Step 7: Best practices

1. Run through the checklist in `references/best-practices.md`.

## 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 attribute syntax, or shadow-root querying questions. |
| `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.                     |