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.13.0

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 foundation and whatever components you added:

<!-- Foundation: reset + tokens + base layers -->
<link rel="stylesheet" href="rends/index.css">

<!-- All components in one file -->
<link rel="stylesheet" href="rends/components/index.css">

<!-- …or cherry-pick -->
<link rel="stylesheet" href="rends/components/primitives/ren-button/ren-button.css">

And use them:

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

<!-- Same component, also available as a custom element -->
<ren-button variant="primary">Click me</ren-button>

Import JavaScript only for the interactive composites that need it:

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

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

Manual install

If you'd rather not use the CLI, clone the repo and copy the rends/ folder into your project:

git clone https://github.com/Rensoconese/ren10.git
cp -r ren10/rends ./my-project/

Astro

Astro 7 projects can use the official adapter and generated component catalog:

npm install astro ren10 @ren10/astro

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):

<!-- Foundation -->
<link rel="stylesheet" href="rends/index.css">
<!-- Theme presets — only needed if you use [data-theme="..."] -->
<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

rends/
├── index.html          ← Marketing landing page
├── index.css           ← Import this for the foundation (reset + tokens + base)
├── 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              # all Playwright suites
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              # stylelint + eslint

Browser Support

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

License

MIT © 2025 Ren