RenDS

A vanilla, accessible, atomic design system. No framework required.

Built with pure HTML, CSS, and Web Components. You own the code — copy what you need, override what you want, no build step required.

Current version: 0.14.1 (source checkout). The published npm version is shown by the badge above; see the registry status before installing the Astro adapter.

Documentation · Components · Theme Builder

AI agents: AGENTS.md is the routing index for AI assistants (Claude, Cursor, Windsurf, Copilot, etc.). Load it first. Every colocated component.md / pattern.md carries an aiHints YAML block with selection criteria, canonical imports, required markup, forbidden patterns, and accessibility rules. The npm package also ships a queryable graph in knowledge/ for agents that need search over contracts, selectors, tokens, docs, and examples.

Quick Start

The fastest way to start is the CLI, which scaffolds a rends/ folder into your project (shadcn/ui style — you own the files):

Package name: the npm package is ren10 (the repo on GitHub is also ren10). The CLI it installs is also named ren10, but everything it creates inside your project lives under rends/ because that's the design-system convention — same separation as tailwindcss (the package) vs tailwind.config.js (the local file).

npx ren10 init
npx ren10 add button dialog tooltip
# or grab everything
npx ren10 add --all

Then link the generated entrypoint. It includes tokens, base styles, appearance presets, and the components you added:

<link rel="stylesheet" href="rends/index.css">

Native buttons work without JavaScript:

<button class="ren-btn">Click me</button>
<button class="ren-btn ren-btn-secondary">Cancel</button>

For the optional custom element, load its JavaScript too:

<script type="module" src="rends/components/button/ren-button.js"></script>
<ren-button variant="primary">Click me</ren-button>

Load other behavior only when used, for example a dialog:

<script type="module" src="rends/components/dialog/ren-dialog.js"></script>

CLI copies use flat component folders: rends/components/button/ren-button.css, rends/components/dialog/ren-dialog.js, and so on. The generated rends/components/index.css imports the CSS for the components you add; there is no need to link it a second time after rends/index.css.

That's it. No build step, no bundler, no framework.

npm install

For a project with a CSS-aware bundler, use the published core package:

npm install ren10

import 'ren10/foundation.css';
import 'ren10/components/primitives/ren-button/ren-button.css';
// Only needed for <ren-button>; native .ren-btn buttons are CSS-only.
import 'ren10/components/primitives/ren-button/ren-button.js';

The npm package keeps the source primitives/, composites/, and patterns/ folders. These package imports are different from the flattened CLI copy paths. For all component styles, use import 'ren10' instead of the foundation and individual CSS imports; JavaScript remains opt-in.

Manual install

If you'd rather not use the CLI or a bundler, copy the runtime files from the repository root into your project's rends/ directory:

git clone https://github.com/Rensoconese/ren10.git
mkdir -p my-project/rends
cp -R ren10/index.css ren10/foundation.css ren10/tokens ren10/base ren10/components ren10/utils ren10/themes my-project/rends/

This preserves the source layout, unlike the CLI copy. Link rends/index.css for the full CSS system, and load optional behavior from paths such as rends/components/primitives/ren-button/ren-button.js or rends/components/composites/ren-dialog/ren-dialog.js. Add rends/themes/appearance.css when using the named presets.

Astro

Astro 7 projects can use the official adapter and generated component catalog. Check matching core and adapter versions using the registry guide. If the adapter version returns E404 (observed for the 0.14.0 release on 2026-09-30), follow the local build and tarball installation for matching packages. After installation, configure the integration:

import { defineConfig } from 'astro/config';
import ren10 from '@ren10/astro';

export default defineConfig({ integrations: [ren10()] });

---
import Button from '@ren10/astro/components/Button';
---

<Button variant="primary">Save</Button>

See docs/astro.md for all 53 adapters, the starter, agent discovery, and theme generation from visual references.

Core Concepts

Token System

Every visual property comes from a design token. Three layers:

Primitives — Raw values (--blue-500, --space-4, --text-base). Don't consume these directly in components.

Semantic — Purpose-based (--color-accent, --color-text-muted, --color-surface). This is the layer you normally work with.

Component — Per-component overrides for theming (--ren-btn-bg, --ren-card-radius).

Layers flow top-down: change a primitive to re-skin everything, change a semantic to affect a group, change a component token for surgical overrides.

Motion Tokens

Durations and easings are semantic, not time-based:

• --duration-tactile / --duration-state / --duration-enter / --duration-exit / --duration-overlay / --duration-route / --duration-emphasize
• --ease-enter / --ease-exit / --ease-state-change / --ease-playful

Legacy aliases (--duration-fast, --ease-out, etc.) still resolve, so existing consumers keep working.

Layout Primitives

Composable layout classes — use them instead of hand-rolling flexbox/grid:

| Need | Use | | ----------------------- | ----------------------- | | Vertical stack | ren-stack | | Items that wrap | ren-cluster | | Horizontal row | ren-row | | Spread left + right | ren-row-spread | | Centered container | ren-center | | Responsive grid | ren-grid, ren-grid-3| | Sidebar + content | ren-with-sidebar | | Full-screen centered | ren-cover |

Theming

The presets and the hex→tokens generator ship as separate files so you only pay for what you use.

Preset themes (opt-in):

<!-- Full RenDS styles -->
<link rel="stylesheet" href="rends/index.css">
<!-- Presets: omit this extra link with the CLI-generated index.css -->
<link rel="stylesheet" href="rends/themes/appearance.css">

Then apply via data attribute on <html>:

<html data-theme="ocean" data-shape="rounded" data-density="comfortable">

Built-in themes: slate, ocean, forest, sunset, rose, purple, amber-editorial, cyber, minimal-mono. Shape: sharp, rounded, pill. Density: compact, comfortable (default), spacious.

Dark mode is automatic via color-scheme: light dark. Force it with data-theme="dark" or data-theme="light".

Custom palette from a single hex (AA-safe theme generator):

import { generateTheme } from 'ren10/themes/theme-generator.js';

const { css, report } = generateTheme('#5b6cff', { level: 'AA' });
document.head.insertAdjacentHTML('beforeend', `<style>${css}</style>`);

For higher-legibility interfaces, opt into the shipped AAA scope with data-contrast="aaa" on the root (or a subtree). It sets normal text and solid accent pairs to at least 7:1 in both color schemes. Custom elements are progressive enhancements and remain visible without JavaScript; use the explicit [data-ren-pending] attribute only when an application deliberately needs to hide content while an upgrade is pending.

There's also an interactive UI at themes/preview.html you can open locally to dial in the palette before committing the generated CSS.

CSS Cascade Layers

@layer reset, tokens, base, components, utilities;

Any CSS you write outside a layer automatically overrides RenDS styles. No !important needed.

Architecture

Source repository and npm package layout (the CLI copy flattens component folders):

ren10/
├── index.html          ← Marketing landing page
├── index.css           ← Full CSS entrypoint (foundation + all components)
├── foundation.css      ← Tokens + reset + base, without component CSS
├── ren-design.md       ← Agent-facing RenDS contract and routing map
├── tokens/             ← Primitives, semantic, component tokens + motion
├── base/               ← Reset, classless styles, layouts, utilities, motion presets
├── components/
│   ├── index.css       ← Bundle import of every component's CSS
│   ├── primitives/     ← Button, Badge, Card, Field, Link, Progress, Tag…
│   ├── composites/     ← Dialog, Select, Tabs, Tooltip, Calendar, Date Picker…
│   └── patterns/       ← Nav, Sidebar, Data Table, Form Validation, Empty State…
├── utils/              ← JS utilities (focus trap, keyboard nav, portals, live-region)
├── themes/             ← Theme presets + hex→token generator
├── templates/          ← Full page examples (landing, auth, dashboard, settings, blog, blog-post)
├── create/             ← Theme Builder (interactive token generator)
├── cli/                ← `npx ren10` CLI (init, add, list, search, build, doctor)
├── site/               ← Doc-site chrome (top nav, sidebar, footer)
└── docs/               ← Component catalog, per-component pages, foundations

53 components in total: 19 primitives, 26 composites, 8 patterns. Every component has a dedicated documentation page under docs/components/.

CLI Reference

npx ren10 init                           Initialize a new RenDS project
npx ren10 init --scale perfect-fourth    Use a modular type scale
npx ren10 init --scale minor-third --fluid  Fluid clamp() responsive typography
npx ren10 add <component>...             Add one or more components
npx ren10 add --all                      Add every component
npx ren10 list                           List all available components
npx ren10 manifest --json                Emit the self-describing agent manifest
npx ren10 component button --dense       Read one component contract summary
npx ren10 docs layouts --dense           Read dense design/token/layout docs
npx ren10 search "dialog workflow" --json  Search components, docs, examples, selectors, tokens
npx ren10 build "dashboard with sidebar" --json  Get a composition kit
npx ren10 doctor                         Diagnose package and agent-readiness
npx ren10 agent-docs --agent all         Install/update generated agent guidance
npx ren10 scales                         List available type scale ratios
npx ren10 knowledge                      Show packaged graph paths
npx ren10 knowledge query "ren-ai"       Search contracts, selectors, tokens, docs
npx ren10 knowledge query "ren-ai" --json  Emit typed JSON results
npx ren10 knowledge query "ren-ai" --source-json  Force JSON graph source
npx ren10 knowledge check                Validate packaged graph files
npx ren10 help                           Show help

Accessibility

All components meet WCAG 2.1 AA as a baseline, with an AAA opt-in mode in the theme generator:

• Full keyboard navigation on every interactive component
• ARIA attributes, roles, and live regions wired by default
• Visible focus rings that respect user overrides
• 44px minimum touch targets
• prefers-reduced-motion respected across all transitions and animations
• 4.5:1 minimum color contrast (7:1 in AAA mode)

Run the a11y suite locally:

npm run test:a11y

Testing

npm run test              # portable Node and browser suites
npm run test:all          # portable suites + pinned Linux visual gate
npm run test:a11y         # axe-core accessibility audit
npm run test:visual       # visual regression (baselines per-project)
npm run test:components   # per-component demo render + scoped a11y
npm run lint              # CSS, tokens, contracts, aiHints and JS

Browser Support

Chrome, Edge, Firefox, Safari — latest 2 versions. No IE 11.

License

MIT © 2025 Ren

Independent mode and scoped themes

Use data-mode="light|dark|auto" independently of a named data-theme, for example <html data-theme="forest" data-mode="dark">. Existing data-theme="light|dark" remains supported. Named theme scopes recompute semantic aliases for links and focus rings. data-density can scope bare stacks, card padding and form rhythm; explicit component overrides and fixed stack modifiers keep their values. AAA follows the effective color scheme, including manually forced mode.