# Riverty Design System: Web Components

> [Riverty](https://riverty.com/), your flexible Payment Companion. 25+ million users, 1+ billion secure transactions.

Riverty Design System: a design and development toolkit tailor-made for Riverty teams and collaborators.

→ [designsystem.riverty.com](https://designsystem.riverty.com/)

## Contributing

We welcome contributions to the Web Components package! Here's how to get started:

### Development Setup

```bash
cd packages/components
npm install
npm run develop  # Starts watch mode
```

### Creating Components

1. **Generate a new component**:
   ```bash
   npx stencil generate component-name
   ```

2. **Follow the component checklist**:
   - [ ] TypeScript definitions with JSDoc comments
   - [ ] Sass styles following BEM methodology
   - [ ] Responsive design
   - [ ] Dark mode support (via CSS variables)
   - [ ] Storybook story in `packages/storybook/stories/`
   - [ ] Unit tests (Jest)
   - [ ] Accessibility (ARIA labels, keyboard navigation)
   - [ ] Documentation

### Component Structure

```typescript
import { Component, Prop, h } from '@stencil/core';

@Component({
  tag: 'r-component',
  styleUrl: 'component.scss',
  shadow: true,
})
export class RComponent {
  /** Description of prop */
  @Prop() myProp: string;

  render() {
    return <div>{this.myProp}</div>;
  }
}
```

### Testing

```bash
# Run unit tests
npm run test

# Run in watch mode
npm run test -- --watch
```

### Best Practices

- Use web component standards
- Follow StencilJS conventions
- Ensure accessibility (WCAG 2.1/2.2 AA)
- Support keyboard navigation
- Test with screen readers
- Include all component variants in Storybook
- Write meaningful JSDoc comments

### Enter key behavior

- `r-input` is the single source-of-truth for Enter-key implicit form submission. It handles Enter on `keydown` with guards for IME composition, modifier keys, and repeated key events. Wrapppers (e.g., `r-input-password`, `r-input-phone-number`) must not trigger submits themselves — they should forward events to `r-input` and avoid calling submission helpers. See `src/utils/implicit-submit.ts` for the helper used to emulate native implicit submission rules in tests and wrappers.

### Useful Commands

- `npm run build` - Build the component library (also regenerates and verifies skill docs)
- `npm run develop` - Watch mode for development
- `npm run test` - Run unit tests
- `npm run generate` - Generate new component
- `npm run generate:skill-docs` - Regenerate the agent skill catalog (`skills/rty-web-components-usage/references/`: `component-index.md`, `components/<tag>.md`, `deprecations.md`) from `custom-elements-manifest.json`
- `npm run verify:skill-docs` - Verify the generated skill catalog is present and consistent with the manifest

For complete contribution guidelines, see [CONTRIBUTING.md](../../CONTRIBUTING.md) in the repository root.

## Agent Skills

This package includes an agent skill (`rty-web-components-usage`) that describes component behavior, usage rules, and application context. It helps AI agents understand how to correctly use Riverty Web Components in an application.

### Installation

You can automatically sync the bundled skill from your `node_modules`:

```bash
npx skills experimental_sync
```

You can also install the skill locally using the GitHub CLI (installs for GitHub Copilot by default). You can use the `--agent` flag to specify a different AI assistant (e.g., `claude-code`):

```bash
gh skill install node_modules/@riverty/web-components/skills/rty-web-components-usage --from-local
```

Alternatively, since the skill is bundled in this npm package, you can manually copy it into your project's AI context directory (e.g., `.agents/skills`):

```bash
cp -r node_modules/@riverty/web-components/skills/rty-web-components-usage .agents/skills/
```