ry-ui

Framework-agnostic, Light DOM web components. CSS is the source of truth.

North Star

There are only so many types of things we do in any app. There should be one opinionated default way to do each of them. Invent all the wheels once, then never again.

Every app is a composition of the same finite primitives: layout, navigation, data display, data entry, feedback, actions, auth, state. The patterns are solved. The industry just keeps re-solving them because engineers enjoy the puzzle.

ry-ui normalizes this. No decisions to make. No architecture to debate. An LLM can leverage these primitives to build any app, anywhere, with a structure that is grokkable, dumb, and repeatable. Over-engineering becomes irrelevant when there's nothing left to over-engineer.

The goal: Write once in HTML/CSS/JS. Deploy to web, iOS, Android, desktop. The primitives are portable because they're universal.

FUNCTION / FORM / THEME

Every component is three independent layers:

• FUNCTION (JS) — Behavior. Extends RyElement. Manages state, events, keyboard, ARIA. Queries via data-ry-target.
• FORM (Structure CSS) — Layout. ry-structure.css. Display, flex, grid, padding, overflow, transform/opacity transitions. No colors.
• THEME (Visual CSS) — Appearance. ry-theme.css. Colors, shadows, borders, typography, focus rings. Entirely swappable.

These layers are independently replaceable. Structure works with any theme or no theme. Function works regardless of CSS loaded.

• [x] separate the css minimal structure from the theme
• [x] separate the component behavior from the design (see docs/arch/behavior-style-separation.md)

Next Up — Missing Primitives That Block Real Apps

• [ ] Table / Data Grid — sorting, column resize, virtual scrolling for large datasets. Highest-value missing component for any dashboard.
• [ ] Form — form orchestration around existing inputs. Validation, error states, submit handling, field grouping.
• [ ] Menu / Context Menu — right-click menus, nested submenus. Required for any desktop-targeting app.
• [ ] Command Palette — Cmd+K pattern. Table stakes for power-user apps and ry-os.
• [ ] Toast stacking — ry-toast exists but needs positioning, stacking multiple toasts, auto-dismiss timers, queue behavior.
• [ ] Breadcrumb, Pagination, Stepper — navigation patterns for any multi-page app.

Backlog

• [ ] Placeholder, Step/Wizard, Loader/Progress, Comment/Feed, Statistic/Graph, Hero, Calendar, Rating, Search, Shape, Sticky, dialog/alert, carousel, qr-code, diff, format-bytes-number-currency, mutation-observer and resize observer

• [ ] This is a theme on its own: https://codepen.io/oathanrex/pen/EayVMqZ

• [ ] bring in examples and extract and normalize - Flat Clean (accord/tailwind) / Flat Fun Waves (zevo) / Game (mario/astrobot/stardew/animal crossing) / Brute (square game) / Skeuomorphic / Glass ( dark and light, color sets 1,2,3 )

• [ ] cross-platform transpiler - Swift/SwiftUI (see docs/arch/cross-platform-transpiler.md)

• [ ] animation system with GSAP (see docs/plans/animation-system.md)

• [ ] could use to write apps on ry-os lol.. rust based linux DE with html/js/css -> Dioxus -> rust apps / with an llm on device

• [ ] https://github.com/GrapheneOS — hardened Android, good reference for security-first OS/DE design patterns

Codemap

src/
├── css/
│   ├── ry-tokens.css             Design tokens — colors, spacing, radii, shadows, easing
│   ├── ry-structure.css          Layout-only CSS — flex, grid, positioning (no colors)
│   └── ry-theme.css              Visual CSS — colors, shadows, borders, typography
├── themes/
│   ├── ocean.css                 Ocean theme — blue/teal token overrides
│   └── antigravity.css           Antigravity theme — corporate charcoal, pill radii
└── ts/
    ├── core/
    │   ├── ry-element.ts         Base class — setup/teardown, on(), emit(), state, focus trap
    │   ├── ry-transform.ts       <ry> wrapper — rewrites <tag> → <ry-tag> in templates
    │   └── ry-icons.ts           SVG icon registry
    ├── components/
    │   └── ry-*.ts               One file per component — extends RyElement
    ├── ry-ui.ts                  Entry point — exports all components
    └── types.ts                  Shared TypeScript types
scripts/
└── theme-darkify.mjs             Auto-generate light-dark() pairs for theme files
docs/
└── workflows/
    └── extract.md                Playbook for decomposing any page into ry-ui
dist/                             Built output — ry-ui.js, ry-ui.css, types

Quick Start

<link rel="stylesheet" href="https://cdn.example.com/ry-ui.css">
<script type="module" src="https://cdn.example.com/ry-ui.js"></script>

Components

Layout (CSS-only)

• <ry-page> - Page container
• <ry-header> / <ry-footer> - Page sections
• <ry-main> / <ry-section> - Content areas
• <ry-grid cols="3"> - Responsive grid
• <ry-stack> / <ry-cluster> - Flex layouts

Layout

• <ry-split> - Resizable two-column layout with optional persist for localStorage-backed width

Interactive

• <ry-button> - Buttons with variants
• <ry-modal> - Modal dialogs
• <ry-drawer> - Slide-out panels
• <ry-accordion> - Collapsible sections
• <ry-tabs> - Tabbed content
• <ry-dropdown> - Dropdown menus
• <ry-select> - Custom select
• <ry-combobox> - Searchable dropdown
• <ry-switch> - Toggle switch
• <ry-tooltip> - Hover tooltips
• <ry-toast> - Notifications
• <ry-theme-panel> - Floating theme/mode selector (none, default, ocean, antigravity + light/dark)
• <ry-testimonial> - Customer testimonial / quote card with avatar and star rating

Forms

• <ry-field> - Form field wrapper with auto label, error, and hint

Display

• <ry-card> - Card containers
• <ry-badge> - Status badges
• <ry-alert> - Alert messages

Clean Syntax

Use <ry> wrapper to write unprefixed markup:

<ry>
  <accordion>
    <accordion-item title="FAQ" open>
      No ry- prefix needed inside the wrapper.
    </accordion-item>
  </accordion>
</ry>

Examples

<!-- Modal -->
<ry-button modal="demo">Open Modal</ry-button>
<ry-modal id="demo" title="Hello">Content here</ry-modal>

<!-- Drawer -->
<ry-button drawer="menu">Open</ry-button>
<ry-drawer id="menu" side="left">Menu content</ry-drawer>

<!-- Select -->
<ry-select placeholder="Country" name="country">
  <ry-option value="us">United States</ry-option>
  <ry-option value="uk">United Kingdom</ry-option>
</ry-select>

<!-- Split Panel (resizable, persistent) -->
<ry-split resizable persist="sidebar">
  <main>Main content</main>
  <aside>Sidebar</aside>
</ry-split>

<!-- Form Field -->
<ry-field label="Email" error="Invalid email">
  <input type="email" name="email">
</ry-field>

<!-- Toast (programmatic) -->
<script>
RyToast.success('Saved!');
RyToast.error('Failed');
</script>

Themes

Theme and mode are orthogonal — every theme supports light and dark:

<!-- Theme controls visual skin -->
<html data-ry-theme="ocean">

<!-- Mode controls light/dark (independent of theme) -->
<html data-ry-mode="dark">

<!-- "none" theme shows pure structure (no visual styling) -->
<html data-ry-theme="none">

Available themes: none, default, ocean, antigravity Available modes: auto (OS preference), light, dark

Use <ry-theme-panel> for an interactive floating selector.

Dark Mode

Every theme supports light and dark mode via light-dark() CSS values. To auto-generate dark mode for a custom theme:

npm run darkify -- src/themes/your-theme.css

The script parses each --ry-color-* token, inverts lightness in oklch space, and wraps in light-dark(light, dark). Tokens already using light-dark() are left untouched, so you can hand-tune any value after running and safely re-run the script.

CSS Architecture

ry-ui separates structure (layout/behavior) from theme (visual styling):

ry-tokens.css     # Design tokens (CSS variables)
ry-structure.css  # Pure layout - no colors, shadows, or borders + Preflight reset
ry-theme.css      # All visual styling
ry-ui.css         # Bundled (all three combined)

Preflight Reset

Add data-ry-reset to <body> to normalize all descendant elements (Tailwind Preflight-equivalent). Resets box-sizing, margins, form inheritance, media elements, lists, tables.

<body data-ry-reset>

Without the attribute, only ry-* components are reset.

Custom Themes

For completely custom styling, load only structure + your own theme:

<!-- Use default look -->
<link rel="stylesheet" href="ry-ui.css">

<!-- OR: Custom theme -->
<link rel="stylesheet" href="ry-structure.css">
<link rel="stylesheet" href="your-tokens.css">
<link rel="stylesheet" href="your-theme.css">

Structure CSS contains only:

• Display modes, positioning, flexbox, grid
• Sizing, padding, margins, gaps
• State transitions (opacity, visibility, transform)

Theme CSS contains:

• Colors, backgrounds, borders
• Shadows, border-radius
• Typography styling
• Focus rings

Development

npm install
npm run dev      # Dev server with HMR
npm run build    # Production build
npm run typecheck

Publishing

npm run release

Automatically available on CDN via unpkg and jsdelivr.

TypeScript Philosophy

ry-ui is written in strict TypeScript with a "vanilla-first" approach:

No Decorators, No Magic

We use plain class syntax with private fields (#field) instead of decorators. The code reads like standard JavaScript with type annotations.

// What we do
class RySelect extends RyElement {
  #highlightedIndex = -1;
  #typeahead = '';

  setup(): void { ... }
}

// What we avoid
@customElement('ry-select')
class RySelect extends LitElement {
  @property() value = '';
  @state() private _open = false;
}

Strict Mode, No Exceptions

{
  "strict": true,
  "noUncheckedIndexedAccess": true,
  "noImplicitReturns": true
}

Type Patterns

Explicit over inferred for public APIs:

get value(): string { return this.getAttribute('value') ?? ''; }
emit<T = void>(name: string, detail?: T): boolean { ... }

Union types for constrained values:

type ToastVariant = 'info' | 'success' | 'warning' | 'error';
static observedAttributes = ['value', 'disabled'] as const;

Extend globals for custom events:

declare global {
  interface HTMLElementEventMap {
    'ry:change': CustomEvent<{ value: string }>;
  }
}

Build Output

Single bundled ESM file for CDN simplicity:

dist/
├── ry-ui.js      # 32KB (7KB gzip)
├── ry-ui.js.map  # Source maps
└── ry-ui.d.ts    # Type declarations

Vite builds with esbuild for speed, Rollup for optimization, and generates .d.ts for library consumers.

Inspiration

• Kibo — Beautiful blocks and templates for shadcn/ui
• /e/OS — deGoogled Android OS focused on privacy and user freedom
• Ramotion — UI/UX design inspiration on Dribbble
• Landing Folio — Landing page design inspiration and components
• Impeccable — CSS-first web component library by Paul Bakaus

See CLAUDE.md for component development guide.