English | 简体中文
Elements is the UI component library of By Sages: accessible, headless components styled entirely by design tokens compiled to CSS variables, and responsive through native CSS Container Queries — one design system, shipped as React, Vue, Solid, and Svelte components.
Documentation · AI Integration · Discussions · Report Issues
⭐ If Elements is useful to you, a star helps other developers find it.
- 🧩 Headless logic, our look — interaction, state, accessibility, and positioning live in proven headless state machines; every visual decision lives in one style layer, so behavior stays rock-solid while the design stays ours.
- 💡 Dynamic light, not static shadows — the lighting engine computes elevation, pigment bleed, and glow into CSS variables; component styles only consume light (以光为影 — light as shadow).
- 📐 Container-driven responsiveness — components respond to the space they are given (
@container), not the viewport; the same component composes correctly in a sidebar, a card, or a full page. - 🎨 Tokens all the way down — palettes, type, spacing, radius, elevation, and density are design tokens exposed as CSS custom properties. Themes (light/dark, accent pigments, contrast tiers, density tiers) are data, never hardcoded styles.
- 🖋 Paper and ink (以光为影) — interfaces are warm paper, content is ink, hierarchy is light. Primary actions default to ink with switchable mineral-pigment accent themes; semantic colors are fixed traditional pigments; controls are square-cut like seals while vessels stay round. The language bridges Chinese restraint (留白) and Western minimalism, with legible defaults and contrast/density tiers that serve both older and younger users.
- 🌐 Every framework, one anatomy — React, Vue, Solid, and Svelte wrappers share the same parts contract (
data-scope/data-part), so one stylesheet — and one mental model — serves them all. - 🤖 AI-native docs — the documentation speaks agent: every page is served as raw markdown, the whole site compiles to
llms.txt, and an MCP server exposes the docs to any client.
| Package | Version | Description |
|---|---|---|
| @bysages/tokens |  |
DTCG design tokens compiled with style-dictionary 4 → CSS variables + types |
| @bysages/core |  |
Theme engine, per-component styles, and the lighting engine |
| @bysages/react |  |
Components for React |
| @bysages/vue |  |
Components for Vue |
| @bysages/solid |  |
Components for Solid |
| @bysages/svelte |  |
Components for Svelte |
| @bysages/charts |  |
Token-themed charts |
| @bysages/workflow |  |
Headless workflow graph protocol + X6 canvas editor |
| @bysages/nuxt |  |
Nuxt module wrapping the Vue components |
| @bysages/docs-theme |  |
Nuxt Content layer for Elements documentation sites |
Pick the package for your framework — the theme engine and the token layer ride along as its own dependencies:
pnpm add @bysages/vue
# or @bysages/react / @bysages/solid / @bysages/svelteTheme the document — the theme engine is re-exported from the same package, and the first component import carries the token layer in:
import { applyTheme } from "@bysages/vue";
applyTheme({ mode: "system", accent: "ink" });Then use the components — Vue here; React, Solid, and Svelte mirror the same anatomy:
<script setup lang="ts">
import { Button, Dialog } from "@bysages/vue";
</script>
<template>
<Dialog.Root>
<Dialog.Trigger>Delete item</Dialog.Trigger>
<Teleport to="body">
<Dialog.Backdrop />
<Dialog.Positioner>
<Dialog.Content>
<Dialog.Title>Delete item</Dialog.Title>
<Dialog.Description>This action cannot be undone.</Dialog.Description>
<Dialog.CloseTrigger>×</Dialog.CloseTrigger>
</Dialog.Content>
</Dialog.Positioner>
</Teleport>
</Dialog.Root>
</template>Nuxt applications get every family auto-imported and SSR styling handled by the module — see @bysages/nuxt. The documentation site documents installation per framework, theming, and every component family with live demos.
The docs site is built for agents: every page is available as raw markdown, the whole site compiles to llms.txt, and an MCP server exposes the docs to any MCP client:
claude mcp add --transport http elements https://elements.bysages.com/mcpSee the AI integration guide for details.
- Node.js 18.x or higher
- pnpm 9.x or higher (recommended package manager)
- Git for version control
-
Clone the repository:
git clone https://github.com/bysages/elements.git cd elements -
Install dependencies:
pnpm install
-
Build all packages:
pnpm build
pnpm build # Build all packages
cd packages/<pkg> && pnpm build # Build one package
cd packages/<pkg> && pnpm exec vp test run # Test one package
pnpm exec vp check # Lint, format & type checkEach package serves its own component demos with vite from the package root (cd packages/<pkg> && pnpm dev).
This project follows Semantic Versioning. While the major version is 0 (pre-1.0), breaking API changes are released as minor version bumps (0.x.0) rather than patch releases — the public API is expected to keep evolving until the 1.0.0 stabilization release. Pin exact versions in downstream projects if you require stability between minor updates.
We welcome contributions! See CONTRIBUTING.md for the full contribution workflow, coding standards, and PR checklist.
- 📫 Report Issues
- 💬 Discussions — questions, ideas, and show-and-tell
If Elements is useful to you, a ⭐ star helps other developers find it.
The documentation site stands on the shoulders of Docus — our Nuxt Content layer began as a study of its structure (docs shell, raw-markdown twins, assistant) and many of its ideas are re-implemented here in our own UI. Thank you to the Nuxt Content team and community.
This project is licensed under the MIT License - see the LICENSE file for details.
Built with ❤️ by By Sages