npm - @ryanhelsing/ry-ui - Versions diffs - 1.0.10 → 1.0.12 - Mend

@ryanhelsing/ry-ui 1.0.10 → 1.0.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (23) hide show

package/README.dev.md +302 -0
package/README.md +460 -199
package/dist/themes/antigravity.css +56 -0
package/package.json +3 -5
package/AGENT.md +0 -492
package/AGENTS.md +0 -57
package/examples/starter-local.html +0 -252
package/examples/starter-minimal.html +0 -252
package/examples/themes/skeuomorphic/css-dark-neon-led-volume-dial/LICENSE.txt +0 -21
package/examples/themes/skeuomorphic/css-dark-neon-led-volume-dial/README.md +0 -7
package/examples/themes/skeuomorphic/css-dark-neon-led-volume-dial/dist/index.html +0 -23
package/examples/themes/skeuomorphic/css-dark-neon-led-volume-dial/dist/style.css +0 -126
package/examples/themes/skeuomorphic/css-dark-neon-led-volume-dial/src/index.html +0 -5
package/examples/themes/skeuomorphic/css-dark-neon-led-volume-dial/src/style.scss +0 -161
package/examples/themes/skeuomorphic/led-controls/LICENSE.txt +0 -21
package/examples/themes/skeuomorphic/led-controls/README.md +0 -7
package/examples/themes/skeuomorphic/led-controls/dist/index.html +0 -17
package/examples/themes/skeuomorphic/led-controls/dist/script.js +0 -27
package/examples/themes/skeuomorphic/led-controls/dist/style.css +0 -135
package/examples/themes/skeuomorphic/led-controls/src/index.html +0 -1
package/examples/themes/skeuomorphic/led-controls/src/script.ts +0 -59
package/examples/themes/skeuomorphic/led-controls/src/style.scss +0 -253
package/llms.txt +0 -346

package/README.md CHANGED Viewed

@@ -1,294 +1,555 @@
 # ry-ui
-Framework-agnostic, Light DOM web components. CSS is the source of truth.
+Framework-agnostic, Light DOM web components. Zero dependencies. CSS is the source of truth.
-## North Star
+## Setup (2 lines)
-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.
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ryanhelsing/ry-ui/dist/css/ry-ui.css">
+<script type="module" src="https://cdn.jsdelivr.net/npm/@ryanhelsing/ry-ui/dist/ry-ui.js"></script>
+```
-**The goal:** Write once in HTML/CSS/JS. Deploy to web, iOS, Android, desktop. The primitives are portable because they're universal.
+```bash
+# or npm
+npm install @ryanhelsing/ry-ui
+```
-### FUNCTION / FORM / THEME
+Set theme: `<html data-ry-theme="light">` — `light` | `dark` | omit for OS preference
+Set body: `<body style="background: var(--ry-color-bg); color: var(--ry-color-text);">`
-Every component is three independent layers:
+## DON'T / DO
-- **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.
+DON'T write flexbox/grid CSS for page layout.
+DO: `<ry-page><ry-header>H</ry-header><ry-main>M</ry-main><ry-footer>F</ry-footer></ry-page>`
-These layers are independently replaceable. Structure works with any theme or no theme. Function works regardless of CSS loaded.
+DON'T write a custom modal with backdrop, focus trap, escape handling.
+DO: `<ry-button modal="m">Open</ry-button><ry-modal id="m" title="T">Content</ry-modal>`
----
+DON'T write a slide-out drawer with CSS transforms.
+DO: `<ry-button drawer="d">Open</ry-button><ry-drawer id="d" side="left">Content</ry-drawer>`
-- [x] separate the css minimal structure from the theme
-- [x] separate the component behavior from the design (see `docs/arch/behavior-style-separation.md`)
+DON'T write tab switching logic or CSS.
+DO: `<ry-tabs><ry-tab title="A" active>A</ry-tab><ry-tab title="B">B</ry-tab></ry-tabs>`
-### Next Up — Missing Primitives That Block Real Apps
+DON'T write a custom select dropdown with keyboard navigation.
+DO: `<ry-select placeholder="Pick"><ry-option value="a">A</ry-option></ry-select>`
-- [ ] **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.
+DON'T write CSS variables for colors, spacing, shadows.
+DO: Use `--ry-color-*`, `--ry-space-*`, `--ry-radius-*`, `--ry-shadow-*` tokens.
-### Backlog
+DON'T write button styles with hover/active/focus states.
+DO: `<ry-button variant="primary">Click</ry-button>`
-- [ ] 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
+DON'T write toast/notification CSS and JS.
+DO: `RyToast.success('Saved!')` / `RyToast.error('Failed')`
-- [ ] This is a theme on its own: https://codepen.io/oathanrex/pen/EayVMqZ
+DON'T write accordion expand/collapse logic.
+DO: `<ry-accordion><ry-accordion-item title="Q" open>A</ry-accordion-item></ry-accordion>`
-- [ ] 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
+DON'T write a toggle switch from scratch.
+DO: `<ry-switch name="notify" checked></ry-switch>`
-## Quick Start
+## Full Page Template
 ```html
-<link rel="stylesheet" href="https://cdn.example.com/ry-ui.css">
-<script type="module" src="https://cdn.example.com/ry-ui.js"></script>
+<!DOCTYPE html>
+<html lang="en" data-ry-theme="light">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>My App</title>
+  <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ryanhelsing/ry-ui/dist/css/ry-ui.css">
+</head>
+<body style="background: var(--ry-color-bg); color: var(--ry-color-text);">
+  <ry-page>
+    <ry-header sticky>
+      <ry-cluster>
+        <strong>My App</strong>
+        <ry-nav>
+          <a href="/" aria-current="page">Home</a>
+          <a href="/about">About</a>
+        </ry-nav>
+      </ry-cluster>
+      <ry-actions>
+        <ry-theme-toggle themes="light,dark"></ry-theme-toggle>
+      </ry-actions>
+    </ry-header>
+    <ry-main>
+      <ry-section>
+        <h1>Hello World</h1>
+        <p>Your content here.</p>
+      </ry-section>
+    </ry-main>
+    <ry-footer>Built with ry-ui</ry-footer>
+  </ry-page>
+  <script type="module" src="https://cdn.jsdelivr.net/npm/@ryanhelsing/ry-ui/dist/ry-ui.js"></script>
+</body>
+</html>
 ```
-## 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-button-group>` - Segmented control / radio button group
-- `<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 + 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:
+Wrap markup in `<ry>` to use unprefixed tags:
 ```html
 <ry>
   <accordion>
-    <accordion-item title="FAQ" open>
-      No ry- prefix needed inside the wrapper.
-    </accordion-item>
+    <accordion-item title="FAQ" open>No ry- prefix needed.</accordion-item>
   </accordion>
 </ry>
 ```
-## Examples
+---
+## Component Catalog
+### Layout (CSS-only, no JS)
+| Component | Attributes | Description |
+|-----------|-----------|-------------|
+| `<ry-page>` | — | Root page container, flex column, min-height 100dvh |
+| `<ry-header>` | `sticky` | Flex row, space-between. `sticky` pins to top |
+| `<ry-main>` | — | Content area, max-width 1200px, centered |
+| `<ry-footer>` | — | Footer with border-top |
+| `<ry-section>` | — | Block section with bottom margin |
+| `<ry-grid>` | `cols="1-6\|auto-fit\|auto-fill"`, `cols-sm`, `cols-md`, `cols-lg` | CSS grid. [Details](docs/components/layout.md) |
+| `<ry-stack>` | `gap="sm\|md\|lg\|xl"` | Vertical flex column |
+| `<ry-cluster>` | `gap="sm\|md\|lg"` | Horizontal flex row, wraps |
+| `<ry-split>` | `resizable`, `persist="key"` | Two-column with drag resize. [Details](docs/components/layout.md) |
+| `<ry-center>` | — | Flex center (both axes) |
+| `<ry-nav>` | — | Horizontal nav links. Active: `a[aria-current="page"]` |
+| `<ry-logo>` | — | Inline-flex, bold text |
+| `<ry-actions>` | — | Flex row for action buttons |
+| `<ry-divider>` | `vertical` | Horizontal line; `vertical` for inline separator |
+| `<ry-aside>` | — | Sidebar content area |
+### Interactive Components
+| Component | Key Attributes | Events |
+|-----------|---------------|--------|
+| `<ry-button>` | `variant="primary\|secondary\|outline\|ghost\|danger\|accent"`, `size="sm\|lg"`, `disabled`, `pressed`, `modal="id"`, `drawer="id"` | `ry:click` |
+| `<ry-button-group>` | `name`, `value` | `ry:change` `{value}` |
+| `<ry-toggle-button>` | `pressed`, `name`, `value`, `size`, `icon`, `disabled` | `ry:change` `{pressed, value}` |
+| `<ry-modal>` | `id`, `title` | Trigger: `<ry-button modal="id">`. [Details](docs/components/modal.md) |
+| `<ry-drawer>` | `id`, `position="left\|right"`, `size` | Trigger: `<ry-button drawer="id">`. [Details](docs/components/drawer.md) |
+| `<ry-accordion>` | — | Container for accordion-items. [Details](docs/components/accordion.md) |
+| `<ry-accordion-item>` | `title`, `open` | Collapsible section |
+| `<ry-tabs>` | — | Children: `<ry-tab title="..." active>`. [Details](docs/components/tabs.md) |
+| `<ry-dropdown>` | — | [Details](docs/components/dropdown.md) |
+| `<ry-select>` | `placeholder`, `name`, `value`, `disabled` | `ry:change` `{value}`. Children: `<ry-option>` |
+| `<ry-combobox>` | `placeholder`, `name`, `value`, `disabled` | `ry:change` `{value, label}`, `ry:input` — searchable dropdown |
+| `<ry-switch>` | `checked`, `disabled`, `name` | `ry:change` `{value, label}` — value is `"true"`/`"false"` string |
+| `<ry-tooltip>` | `content`, `position` | [Details](docs/components/tooltip.md) |
+| `<ry-toast>` | — | `RyToast.success()`, `.error()`, `.warning()`, `.info()`. [Details](docs/components/toast.md) |
+| `<ry-slider>` | `min`, `max`, `step`, `value`, `color`, `disabled` | `ry:change` `{value}`. [Details](docs/components/slider.md) |
+| `<ry-knob>` | `min`, `max`, `step`, `value`, `color`, `size` | `ry:change` `{value}`. [Details](docs/components/knob.md) |
+| `<ry-number-select>` | `min`, `max`, `step`, `value`, `arrows`, `prefix`, `suffix` | `ry:change` `{value}`. [Details](docs/components/number-select.md) |
+| `<ry-color-picker>` | `value`, `format` | `ry:change` `{value}`. [Details](docs/components/color.md) |
+| `<ry-color-input>` | `value`, `format` | `ry:change` `{value}` |
+| `<ry-gradient-picker>` | `value` | `ry:change` `{value}` |
+| `<ry-tree>` | `data` (JSON) | `ry:select`, `ry:move`. [Details](docs/components/tree.md) |
+| `<ry-tag>` | `removable` | `ry:remove` |
+| `<ry-tag-input>` | `name`, `value`, `placeholder` | `ry:change` `{tags}` |
+| `<ry-carousel>` | `autoplay`, `interval` | `ry:change` `{index}` |
+| `<ry-theme-toggle>` | `themes="light,dark"` | Cycles through themes |
+| `<ry-theme-panel>` | `theme`, `mode` | Floating theme/mode selector. Persists to localStorage |
+| `<ry-testimonial>` | `stars` | Quote card with avatar, name, role slots |
+### Display Components
+| Component | Key Attributes | Description |
+|-----------|---------------|-------------|
+| `<ry-card>` | `interactive`, `href` | Card container. `interactive` adds click/keyboard. `href` navigates |
+| `<ry-badge>` | `variant="primary\|success\|warning\|danger\|accent"` | Pill badge. Custom: `style="--ry-badge-color: #8B5CF6"` |
+| `<ry-alert>` | `type="info\|success\|warning\|danger"` | Alert box with optional `[slot="title"]` |
+| `<ry-field>` | `label`, `error`, `hint` | Form field wrapper. [Details](docs/components/forms.md) |
+| `<ry-icon>` | `name` | SVG icon from registry |
+| `<ry-code>` | `language`, `title` | Syntax-highlighted code block |
+| `<ry-hero>` | `size="sm\|lg"`, `full-bleed`, `align="left"` | Marketing hero section |
+| `<ry-stat>` | `size="sm\|lg"` | Stat card with `slot="value"`, `slot="label"` |
+| `<ry-feature>` | `icon` | Feature card with icon |
+| `<ry-feature-grid>` | `cols="2\|3\|4"` | Responsive grid for feature cards |
+| `<ry-pricing>` | — | Container for pricing cards |
+| `<ry-pricing-card>` | `featured` | Pricing tier. `featured` scales up with bold border |
+---
+## Patterns
+### Grid
+```html
+<!-- Fixed columns (auto-responsive: 3-6 → 2 at ≤1024px → 1 at ≤640px) -->
+<ry-grid cols="3">...</ry-grid>
+<!-- Explicit per-breakpoint -->
+<ry-grid cols="5" cols-md="3" cols-sm="1">...</ry-grid>
+<!-- Fluid auto-fit -->
+<ry-grid cols="auto-fit">...</ry-grid>
+<ry-grid cols="auto-fit" style="--ry-grid-min: 240px">...</ry-grid>
+```
+### Split Layout
 ```html
-<!-- 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 resizable persist="sidebar" style="--ry-split-width: 400px">
+  <div>Main content</div>
+  <div>Resizable sidebar — drag, arrow keys, double-click to reset</div>
 </ry-split>
+```
-<!-- Button Group -->
-<ry-button-group value="monthly">
-  <ry-button value="monthly">Monthly</ry-button>
-  <ry-button value="annually">Annually</ry-button>
-</ry-button-group>
+CSS vars: `--ry-split-width`, `--ry-split-min-width`, `--ry-split-max-width`
+Keyboard: Arrow (±10px), Shift+Arrow (±50px), Home/End, double-click reset
+Event: `ry:resize` `{ width }`
+### Forms
-<!-- Form Field -->
-<ry-field label="Email" error="Invalid email">
-  <input type="email" name="email">
+```html
+<ry-field label="Email" hint="We'll never share your email">
+  <input type="email" placeholder="you@example.com">
 </ry-field>
-<!-- Toast (programmatic) -->
-<script>
-RyToast.success('Saved!');
-RyToast.error('Failed');
-</script>
+<ry-field label="Password" error="Must be at least 8 characters">
+  <input type="password">
+</ry-field>
 ```
-## Themes
+Error hides hint automatically. Set `error=""` to clear.
-Theme and mode are orthogonal — every theme supports light and dark:
+### Button Group
 ```html
-<!-- Theme controls visual skin -->
-<html data-ry-theme="ocean">
+<ry-button-group name="billing" value="monthly">
+  <ry-button value="monthly">Monthly</ry-button>
+  <ry-button value="annually">Annually</ry-button>
+</ry-button-group>
+```
-<!-- Mode controls light/dark (independent of theme) -->
-<html data-ry-mode="dark">
+### Button Variants
-<!-- "none" theme shows pure structure (no visual styling) -->
-<html data-ry-theme="none">
+```html
+<ry-button>Default</ry-button>
+<ry-button variant="primary">Primary</ry-button>
+<ry-button variant="secondary">Secondary</ry-button>
+<ry-button variant="outline">Outline</ry-button>
+<ry-button variant="ghost">Ghost</ry-button>
+<ry-button variant="danger">Danger</ry-button>
+<ry-button variant="accent">Accent</ry-button>
+<ry-button size="sm">Small</ry-button>
+<ry-button size="lg">Large</ry-button>
 ```
-Available themes: `none`, `default`, `ocean`
-Available modes: `auto` (OS preference), `light`, `dark`
-Use `<ry-theme-panel>` for an interactive floating selector.
+### Modal & Drawer
-## CSS Architecture
+```html
+<ry-button modal="confirm">Open Modal</ry-button>
+<ry-modal id="confirm" title="Confirm Action">
+  <p>Are you sure?</p>
+  <ry-cluster>
+    <ry-button variant="danger">Delete</ry-button>
+    <ry-button variant="ghost">Cancel</ry-button>
+  </ry-cluster>
+</ry-modal>
+<ry-button drawer="settings">Settings</ry-button>
+<ry-drawer id="settings" position="right" size="400px">
+  <h3>Settings</h3>
+</ry-drawer>
+```
-ry-ui separates **structure** (layout/behavior) from **theme** (visual styling):
+### Nav Bar
+```html
+<ry-header sticky>
+  <ry-cluster>
+    <ry-logo>MyApp</ry-logo>
+    <ry-divider vertical></ry-divider>
+    <ry-nav>
+      <a href="/" aria-current="page">Home</a>
+      <a href="/docs">Docs</a>
+    </ry-nav>
+  </ry-cluster>
+  <ry-actions>
+    <ry-button variant="ghost" size="sm">Login</ry-button>
+    <ry-button size="sm">Sign Up</ry-button>
+  </ry-actions>
+</ry-header>
 ```
-ry-tokens.css     # Design tokens (CSS variables)
-ry-structure.css  # Pure layout - no colors, shadows, or borders
-ry-theme.css      # All visual styling
-ry-ui.css         # Bundled (all three combined)
-```
-### Custom Themes
+### Hero
+```html
+<ry-hero>
+  <h1>Build faster with ry-ui</h1>
+  <p>Framework-agnostic components for any app.</p>
+  <ry-cluster>
+    <ry-button size="lg">Get Started</ry-button>
+    <ry-button variant="outline" size="lg">View Docs</ry-button>
+  </ry-cluster>
+</ry-hero>
+```
-For completely custom styling, load only structure + your own theme:
+### Pricing
 ```html
-<!-- Use default look -->
-<link rel="stylesheet" href="ry-ui.css">
+<ry-pricing>
+  <ry-pricing-card>
+    <h3>Free</h3>
+    <div class="ry-pricing__price">$0<span>/mo</span></div>
+    <ul class="ry-check-list">
+      <li>3 projects</li>
+      <li>Basic support</li>
+    </ul>
+    <ry-button variant="outline">Get Started</ry-button>
+  </ry-pricing-card>
+  <ry-pricing-card featured>
+    <h3>Pro</h3>
+    <div class="ry-pricing__price">$19<span>/mo</span></div>
+    <ul class="ry-check-list">
+      <li>Unlimited projects</li>
+      <li>Priority support</li>
+    </ul>
+    <ry-button>Upgrade</ry-button>
+  </ry-pricing-card>
+</ry-pricing>
+```
-<!-- OR: Custom theme -->
-<link rel="stylesheet" href="ry-structure.css">
-<link rel="stylesheet" href="your-tokens.css">
-<link rel="stylesheet" href="your-theme.css">
+### Interactive Card Grid
+```html
+<ry-grid cols="3">
+  <ry-card interactive href="/feature-a">
+    <h3>Feature A</h3>
+    <p>Description</p>
+  </ry-card>
+</ry-grid>
 ```
-Structure CSS contains only:
-- Display modes, positioning, flexbox, grid
-- Sizing, padding, margins, gaps
-- State transitions (opacity, visibility, transform)
+### Dropdown Menu
-Theme CSS contains:
-- Colors, backgrounds, borders
-- Shadows, border-radius
-- Typography styling
-- Focus rings
+```html
+<ry-dropdown>
+  <ry-button slot="trigger">Actions</ry-button>
+  <ry-menu>
+    <ry-menu-item>Edit</ry-menu-item>
+    <ry-menu-item>Duplicate</ry-menu-item>
+    <ry-menu-item>Delete</ry-menu-item>
+  </ry-menu>
+</ry-dropdown>
+```
 ---
-## Development
+## Events
-```bash
-npm install
-npm run dev      # Dev server with HMR
-npm run build    # Production build
-npm run typecheck
+All events prefixed with `ry:`:
+```javascript
+element.addEventListener('ry:change', (e) => console.log(e.detail));
+element.addEventListener('ry:open', () => {});
+element.addEventListener('ry:close', () => {});
+element.addEventListener('ry:click', () => {});
 ```
-## Publishing
+### Programmatic Control
-```bash
-npm run release
+```javascript
+document.querySelector('ry-modal').open();
+document.querySelector('ry-modal').close();
+document.querySelector('ry-drawer').toggle();
+document.querySelector('ry-select').value = 'new-value';
 ```
-Automatically available on CDN via [unpkg](https://unpkg.com/@ryanhelsing/ry-ui/) and [jsdelivr](https://cdn.jsdelivr.net/npm/@ryanhelsing/ry-ui/).
+---
-## TypeScript Philosophy
+## CSS Token System
-ry-ui is written in strict TypeScript with a "vanilla-first" approach:
+All visual properties use CSS custom properties. Override in your own CSS to customize.
-### 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.
+### Colors
-```typescript
-// What we do
-class RySelect extends RyElement {
-  #highlightedIndex = -1;
-  #typeahead = '';
+| Token | Purpose |
+|-------|---------|
+| `--ry-color-primary` / `-hover` / `-active` | Primary action color |
+| `--ry-color-secondary` / `-hover` / `-active` | Secondary muted color |
+| `--ry-color-accent` / `-hover` / `-active` | Accent/highlight color |
+| `--ry-color-success` | Green for positive states |
+| `--ry-color-warning` | Yellow/orange for caution |
+| `--ry-color-danger` / `-hover` | Red for destructive actions |
+| `--ry-color-info` | Blue for informational |
+| `--ry-color-text` / `-muted` / `-inverse` | Text colors |
+| `--ry-color-bg` / `-subtle` / `-muted` | Background colors |
+| `--ry-color-border` / `-strong` | Border colors |
+| `--ry-color-overlay` | Modal/drawer backdrop |
-  setup(): void { ... }
-}
+Each color also has `-bg` and `-text` variants for alert/badge backgrounds.
-// What we avoid
-@customElement('ry-select')
-class RySelect extends LitElement {
-  @property() value = '';
-  @state() private _open = false;
-}
+### Spacing
+`--ry-space-{0,1,2,3,4,5,6,8,10,12,16,20}` — 0 to 5rem
+### Typography
+| Token | Value |
+|-------|-------|
+| `--ry-font-sans` | system-ui stack |
+| `--ry-font-mono` | ui-monospace stack |
+| `--ry-text-{xs,sm,base,lg,xl,2xl,3xl,4xl}` | 0.75rem to 2.25rem |
+| `--ry-font-{normal,medium,semibold,bold}` | 400 to 700 |
+### Borders & Shadows
+| Token | Value |
+|-------|-------|
+| `--ry-radius-{none,sm,md,lg,xl,2xl,full}` | 0 to 9999px |
+| `--ry-shadow-{sm,md,lg,xl}` | Elevation shadows |
+| `--ry-border-width` | 1px |
+### Transitions
+| Token | Value |
+|-------|-------|
+| `--ry-duration-{fast,normal,slow}` | 100ms, 200ms, 300ms |
+| `--ry-ease` / `-in` / `-out` | Cubic bezier easing |
+### Z-Index
+| Token | Value |
+|-------|-------|
+| `--ry-z-dropdown` | 1000 |
+| `--ry-z-sticky` | 1020 |
+| `--ry-z-modal-backdrop` | 1040 |
+| `--ry-z-modal` | 1050 |
+| `--ry-z-tooltip` | 1070 |
+| `--ry-z-toast` | 1080 |
+---
+## Theming
+Three CSS layers, loaded in order:
+1. **ry-tokens.css** — CSS custom properties (colors, spacing, etc.)
+2. **ry-structure.css** — Pure layout (no colors)
+3. **ry-theme.css** — All visual styling (colors, shadows, borders)
+### Custom Theme
+Load structure-only and bring your own:
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@ryanhelsing/ry-ui/dist/css/ry-structure.css">
+<link rel="stylesheet" href="your-tokens.css">
+<link rel="stylesheet" href="your-theme.css">
 ```
-### Strict Mode, No Exceptions
-```json
-{
-  "strict": true,
-  "noUncheckedIndexedAccess": true,
-  "noImplicitReturns": true
+### Override Tokens
+No build step needed:
+```css
+:root {
+  --ry-color-primary: oklch(0.541 0.218 293);
+  --ry-color-primary-hover: oklch(0.491 0.234 292);
+  --ry-radius-md: 0;
 }
 ```
-### Type Patterns
+### Themes & Modes
-**Explicit over inferred for public APIs:**
-```typescript
-get value(): string { return this.getAttribute('value') ?? ''; }
-emit<T = void>(name: string, detail?: T): boolean { ... }
-```
+Theme and mode are independent:
-**Union types for constrained values:**
-```typescript
-type ToastVariant = 'info' | 'success' | 'warning' | 'error';
-static observedAttributes = ['value', 'disabled'] as const;
+```html
+<html data-ry-theme="ocean" data-ry-mode="dark">
 ```
-**Extend globals for custom events:**
-```typescript
-declare global {
-  interface HTMLElementEventMap {
-    'ry:change': CustomEvent<{ value: string }>;
+Themes: `default`, `ocean`, `none` (structure only)
+Modes: `auto` (OS preference), `light`, `dark`
+Use `<ry-theme-panel>` for an interactive floating selector.
+---
+## TypeScript
+```ts
+import { RyElement, RyButton, RyToast } from '@ryanhelsing/ry-ui';
+RyToast.success('Saved!');
+document.querySelector('ry-select')?.addEventListener('ry:change', (e: CustomEvent) => {
+  console.log(e.detail.value);
+});
+// Extend components
+class MyWidget extends RyElement {
+  setup() {
+    this.on(this, 'click', () => this.emit('activate'));
   }
 }
 ```
-### Build Output
+## Icon Registry
+Built-in: `settings`, `heart`, `star`, `chevron-up`, `chevron-down`, `chevron-left`, `chevron-right`, `check`, `x`, `plus`, `minus`, `search`, `sun`, `moon`, `copy`, `trash`, `edit`, `eye`, `folder`, `file`, `drag`
+```ts
+import { registerIcon, registerIcons } from '@ryanhelsing/ry-ui';
-Single bundled ESM file for CDN simplicity:
+registerIcon('custom', '<svg>...</svg>');
+registerIcons({ 'app-logo': '<svg>...</svg>' });
 ```
-dist/
-├── ry-ui.js      # 32KB (7KB gzip)
-├── ry-ui.js.map  # Source maps
-└── ry-ui.d.ts    # Type declarations
+## Vendoring
+Copy into your project instead of using CDN:
+```bash
+npm pack @ryanhelsing/ry-ui && tar -xf ryanhelsing-ry-ui-*.tgz
+cp -r package/dist ./vendor/ry-ui && rm -rf package ryanhelsing-ry-ui-*.tgz
 ```
-Vite builds with esbuild for speed, Rollup for optimization, and generates `.d.ts` for library consumers.
+```html
+<link rel="stylesheet" href="/vendor/ry-ui/css/ry-ui.css">
+<script type="module" src="/vendor/ry-ui/ry-ui.js"></script>
+```
 ---
-See [CLAUDE.md](CLAUDE.md) for component development guide.
+## Detailed Docs
+Per-component docs with full attributes, events, and examples:
+| Doc | Components |
+|-----|-----------|
+| [layout](docs/components/layout.md) | page, header, main, footer, section, grid, stack, cluster, split, center, card, nav, divider |
+| [button](docs/components/button.md) | button, toggle-button |
+| [button-group](docs/components/button-group.md) | button-group |
+| [accordion](docs/components/accordion.md) | accordion, accordion-item |
+| [tabs](docs/components/tabs.md) | tabs, tab |
+| [modal](docs/components/modal.md) | modal |
+| [drawer](docs/components/drawer.md) | drawer |
+| [dropdown](docs/components/dropdown.md) | dropdown, menu, menu-item |
+| [tooltip](docs/components/tooltip.md) | tooltip |
+| [toast](docs/components/toast.md) | toast |
+| [forms](docs/components/forms.md) | field, select, switch |
+| [slider](docs/components/slider.md) | slider |
+| [knob](docs/components/knob.md) | knob |
+| [number-select](docs/components/number-select.md) | number-select |
+| [color](docs/components/color.md) | color-picker, color-input, gradient-picker |
+| [tree](docs/components/tree.md) | tree |
+| [display](docs/components/display.md) | badge, alert, icon, code |
+| [theme-toggle](docs/components/theme-toggle.md) | theme-toggle |
+| [theming](docs/theming.md) | tokens, custom themes, structure-only loading |
+## AI-Friendly
+This package includes a `.claude/skills/ry-ui-builder` skill so Claude Code can build with these components automatically. The detailed docs above serve as the complete agent reference.
+## License
+MIT