Introduction

wayra-ui is a React 19 component library whose design system is plain CSS custom properties. A theme is a block of CSS, the styling API is a class plus data-* attributes, and none of it needs a provider, a context or a build step.

This page is the mental model. To get the package installed first, see Install.

Without a framework

Every component renders a stable class plus structural data attributes, and that pair is the public API. The stylesheet is written against it, so it works on hand-written markup:

<link rel="stylesheet" href="wayra-ui/styles.css" />

<button class="wayra-button" data-variant="filled" data-color="success">Save</button>
<span class="wayra-badge" data-variant="outline">Beta</span>

Only two things need JavaScript: Button’s ripple, and Checkbox’s indeterminate state. That second one is a DOM property rather than an attribute, so markup alone cannot set it.

Cascade layers

Everything ships inside @layer wayra.theme, wayra.components. Two consequences are worth knowing before you write your first override:

• Your unlayered CSS always wins. A className on a component beats the library’s own declarations no matter how specific they are. No !important, no specificity ladder.

• Layer your resets. Unlayered CSS beats all layered CSS, so a global * { padding: 0 } would strip the padding off every component. Declare the layer order first, then put the reset in a layer:

  @layer base, wayra;
  
  @layer base {
    * { box-sizing: border-box; padding: 0; margin: 0; }
  }

  Import that file before wayra-ui/styles.css. Layer order is fixed by whichever declaration comes first.

With Tailwind v4

Preflight is a layered reset, so import order alone is not enough. Whichever of the two layers is declared later wins. Pin the order explicitly as the first statement in your CSS, then import in any order:

@layer theme, base, wayra, components, utilities;

@import "tailwindcss";
@import "wayra-ui/styles.css";

Utilities then override component styles as expected, and preflight stays below them.

Browser support

Full theming needs light-dark(): Chrome 123+, Safari 17.5+, Firefox 120+.

Caution

Chrome 111–122 and Safari 16.4–17.4 fall back to the light palette through the @property initial values. Components stay styled. They just stop following the OS color scheme. The fallback is sharper for a named theme: the page drops all the way back to the default palette while keeping the theme’s geometry, and that pairing was never contrast-tested. Check light-dark() support before you rely on a named theme for brand fidelity.

Next

• Install — the package, the peer dependencies, and the stylesheet.
• Button — the component documented end to end.
• Theming — the sixteen tokens, the seven palettes, and the rule that shapes all of them.