# ran

> ran provides three independent pillars: Ran Design for product design and acceptance, ranui for native Web Components, and ranuts for typed utilities. The unified ran agent plugin routes tasks to design, ranui and ranuts skills.

ranui is built on native Custom Elements (`<r-*>` tags), so it works in any framework
or plain HTML. It ships first-class TypeScript types, light/dark theming via Geist-based
CSS variables, Shadow DOM encapsulation, SSR/SSG support, and PWA. ranuts is a broad,
tree-shakeable collection: DOM/BOM and string/object/number/colour helpers, debounce and
throttle, storage (guarded localStorage, IndexedDB), a Web Worker client, a postMessage
bridge, ZIP read/write, prefetching, i18n, scoped event management, microphone audio
recording and Web Speech API speech-to-text, a 2D rendering engine (Canvas/WebGL/WebGPU),
and a virtual DOM.

## Docs

- [Ran Design](https://ran.chaxus.com/src/design/): design methodology and canonical references
- [Agents](https://ran.chaxus.com/src/agents/): unified plugin skills, installation and publication status

- [ranui — Web Components UI library](https://ran.chaxus.com/src/ranui/): button, input, select, checkbox, radio, card, tabs, modal, popover, dropdown, progress, message, icon, and more `<r-*>` elements, with theming, i18n, routing and SSR
- [ranui design system](https://ran.chaxus.com/src/ranui/design-system/): the Geist-based token catalog — colour ladder, semantic tokens, spacing, typography, radius, elevation, stacking, motion
- [ranui design guidelines](https://ran.chaxus.com/src/ranui/design-guides/): the rules for building a screen with it — pick a role, let the token supply the value, design every state
- [ranui coding guidelines](https://ran.chaxus.com/src/ranui/coding-guides/): entry points, the attribute/property/event contract, styling across the Shadow DOM boundary, SSR, testing, antipatterns
- [ranui element API](https://ran.chaxus.com/src/ranui/api): all 40 custom elements with their attributes, properties, events (detail shape + dispatch flags), slots and ::part() names, generated from source
- [ranui builder](https://ran.chaxus.com/src/ranui/builder/): the fluent DOM builder with fine-grained reactivity — signals, Show/For/Index, ownership and teardown
- [ranui server rendering](https://ran.chaxus.com/src/ranui/ssr/): declarative shadow DOM via renderHTMLToString / renderToStream, and what the client rebuilds
- [ranui style tokens](https://ran.chaxus.com/src/ranui/style-tokens): the CSS custom properties and ::part() names every element exposes, extracted from its stylesheet
- [ranui changelog](https://ran.chaxus.com/src/ranui/changelog): what changed and why, plus the dated engineering notes — ranui is alpha and ships breaking changes
- [ranuts — utility library](https://ran.chaxus.com/src/ranuts/): functional (debounce, throttle, once, singleFlight, compose), string/object/number/colour utils, storage and IndexedDB, Web Worker request/response on both ends, Service Worker caching and precache, text pagination, postMessage bridge, ZIP, i18n, audio recording, speech-to-text, a 2D rendering engine, virtual DOM, TOTP
- [ranuts — choosing a utility](https://ran.chaxus.com/src/ranuts/choosing/): which of two similar exports to reach for (debounce vs throttle, once vs singleFlight, localStorage vs IndexedDB, bridge vs worker client) and when the platform already has it
- [Articles](https://ran.chaxus.com/src/article/doc_preview): front-end engineering notes — web document preview, video encryption, a 2D/WebGL/WebGPU rendering engine, sorting algorithms, functional programming, AI agents, linear algebra

## Entry points

Both packages are multi-entry so consumers import only what they use:

- `ranui` (all components), `ranui/<component>`, `ranui/builder`, `ranui/theme`, `ranui/i18n`, `ranui/ssr`
- `ranuts` (root barrel), `ranuts/utils`, `ranuts/visual` (browser only), `ranuts/vnode`, `ranuts/i18n`, `ranuts/sw` (service worker only)

## Reference

- [Full documentation corpus for LLMs](https://ran.chaxus.com/llms-full.txt): every doc page concatenated as plain text
- [Sitemap — all pages](https://ran.chaxus.com/sitemap.xml)
- [GitHub repository](https://github.com/chaxus/ran)
- [ranui on npm](https://www.npmjs.com/package/ranui)
- [ranuts on npm](https://www.npmjs.com/package/ranuts)

Both npm packages ship AI-facing files inside the tarball: `CLAUDE.md` (orientation —
entry points, runtime constraints, conventions) and, for ranuts, `docs/API.md` (every
exported symbol with its signature and description). An assistant with the package
installed can read them from `node_modules` without fetching anything.

## Optional

- [简体中文文档 (Simplified Chinese docs)](https://ran.chaxus.com/cn/)