Riverty Design System: Web Components

Riverty, 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

Contributing

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

Development Setup

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

Creating Components

1. Generate a new component:

   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

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

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

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):

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):

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