{ "name": "sbean", "version": "0.29.3", "description": "CLI tool for adding SoybeanUI components to your Vue apps — copy-paste, like shadcn/ui.", "homepage": "https://github.com/soybeanjs/soybean-ui/tree/main/packages/sbean", "bugs": { "url": "https://github.com/soybeanjs/soybean-ui/issues" }, "license": "MIT", "author": { "name": "Soybean", "email": "soybeanjs@outlook.com", "url": "https://github.com/soybeanjs" }, "repository": { "type": "git", "url": "https://github.com/soybeanjs/soybean-ui.git", "directory": "packages/sbean" }, "bin": { "sbean": "./dist/index.js" }, "files": [ "dist" ], "type": "module", "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js", "require": "./dist/index.js" }, "./registry": { "types": "./dist/registry/index.d.ts", "import": "./dist/registry/index.js", "require": "./dist/registry/index.js" }, "./schema": { "types": "./dist/schema/index.d.ts", "import": "./dist/schema/index.js", "require": "./dist/schema/index.js" }, "./preset": { "types": "./dist/preset/index.d.ts", "import": "./dist/preset/index.js", "require": "./dist/preset/index.js" }, "./utils": { "types": "./dist/utils/index.d.ts", "import": "./dist/utils/index.js", "require": "./dist/utils/index.js" }, "./mcp": { "types": "./dist/mcp/index.d.ts", "import": "./dist/mcp/index.js", "require": "./dist/mcp/index.js" } }, "scripts": { "build": "vp pack", "build:registry": "tsx src/index.ts build packages/sbean/registry.json -o ../../apps/docs/public/r --cwd ../..", "build:schema": "tsx scripts/schema.ts", "clean": "rimraf dist", "dev": "tsx src/index.ts", "start": "node dist/index.js", "test": "vp test", "typecheck": "tsc --noEmit" }, "dependencies": { "@modelcontextprotocol/sdk": "^1.30.0", "commander": "^15.0.0", "dedent": "^1.7.2", "deepmerge": "^4.3.1", "fast-glob": "^3.3.3", "fs-extra": "^11.4.0", "kleur": "^4.1.5", "ora": "^9.4.1", "prompts": "^2.4.2", "valibot": "^1.4.2" }, "devDependencies": { "@types/fs-extra": "^11.0.4", "@types/node": "^26.1.2", "@types/prompts": "^2.4.9", "@valibot/to-json-schema": "^1.7.1", "rimraf": "^6.1.3", "tsx": "^4.23.5", "typescript": "7.0.2", "vite-plus": "catalog:", "vitest": "4.1.10" } }

SoybeanUI

English | 中文

SoybeanUI is an elegant, modern, accessible and high-quality UI component library with shadcn-like design for Vue 3, built on top of a robust headless foundation. It provides a comprehensive set of accessible, customizable, and performant components.

📚 Architecture

SoybeanUI's component runtime uses a strict two-layer separation. In the diagram below, arrows mean “depends on”:

Consumer ──> @soybeanjs/ui ──> @soybeanjs/headless
                    │
                    └───────> @soybeanjs/shadcn-theme

UnoCSS config ──> @soybeanjs/unocss-shadcn
                    └───────> @soybeanjs/shadcn-theme

Packages

The compile-time dependency is strictly one-way: @soybeanjs/ui imports public @soybeanjs/headless entry points, while headless never imports UI. At runtime, styled wrappers inject slot class maps through provideXUi(computedUi), and the wrapped headless parts read them through useUiContext().

“Headless” means that no visual theme is packaged with the logic layer. Behavior-critical CSS variables or inline layout values may still be used for positioning and interaction.

Some multi-slot headless components also expose Compact aggregators, such as AccordionCompact and TableCompact. They keep item iteration and default content/icon composition inside headless, while the UI layer stays focused on styling and prop forwarding.

Current Compact-style coverage also includes flows such as card, date-field, dialog, editable, hover-card, layout, navigation-menu, pagination, popover, and stepper, when those structures are stable enough to live in headless.

Workspace Overview

The monorepo also publishes @soybeanjs/shadcn-theme, @soybeanjs/unocss-shadcn, the sbean source-distribution CLI, and @soybeanjs/ui-skills. Private apps provide the documentation site, playground, and Nuxt integration fixture.

See Project architecture for the complete workspace map, dependency graph, build/test flows, and sources of truth. See Architecture and quality assessment for prioritized improvements and acceptance criteria.

Style Injection

Every multi-slot headless component exposes a provide{Name}Ui function. The styled wrapper computes classes with @soybeanjs/cva recipes and injects them:

// In the styled wrapper (packages/ui/)
const ui = computed(() => accordionVariants({ size: props.size }, props.ui, { root: props.class }));
provideAccordionUi(ui); // headless reads this via useAccordionUi()

Theme System

• ThemeColor — 8 semantic colors: primary · destructive · success · warning · info · carbon · secondary · accent
• ThemeSize — 6 sizes: xs · sm · md · lg · xl · 2xl (base 16px at md)
• ConfigProvider — sets global dir, locale, nonce, and default tooltip config for the entire component tree, including RTL layout switching

Locale Support

ConfigProvider supports the following locale bundles:

Only en and zh-CN are pre-registered by default. registerLocale supports two registration styles:

• Pass a LocaleRegistry object. Built-in locale files from @soybeanjs/headless/locale/{code} already export this shape, including dir metadata.
• Pass a locale key plus LocaleMessages for a lightweight custom locale.

The shorthand registerLocale(key, messages) form uses the key as the locale name and falls back to ltr. Use the object form when you need explicit metadata such as rtl.

import { en, registerLocale } from '@soybeanjs/headless/locale';
import type { LocaleMessages } from '@soybeanjs/headless/locale';
import ar from '@soybeanjs/headless/locale/ar';

registerLocale(ar);

const customMessages: LocaleMessages = {
  ...en.messages,
  pagination: {
    ...en.messages.pagination,
    nextPage: 'Next →',
    prevPage: '← Prev'
  }
};

registerLocale('custom', customMessages);

Package Exports

@soybeanjs/headless ships fine-grained sub-paths:

import { AccordionRoot } from '@soybeanjs/headless'; // all components
import { useControllableState } from '@soybeanjs/headless/composables'; // 27 composables
import { transformPropsToContext } from '@soybeanjs/headless/shared'; // pure TS utils
import { createMonth } from '@soybeanjs/headless/date'; // shared date helpers
import { registerLocale } from '@soybeanjs/headless/locale'; // locale registry
import * as Headless from '@soybeanjs/headless/namespaced'; // namespace object
import type { AccordionUiSlot } from '@soybeanjs/headless/accordion'; // per-component
import type { UiClass } from '@soybeanjs/headless/types'; // shared type surface

Framework integrations are also available from @soybeanjs/headless/nuxt and @soybeanjs/headless/resolver.

@soybeanjs/ui exports:

import { SButton, SAccordion } from '@soybeanjs/ui'; // all components
import '@soybeanjs/ui/styles.css'; // pre-built UnoCSS stylesheet
// Also: @soybeanjs/ui/nuxt · @soybeanjs/ui/resolver

🛠 Development Workflow

If you contribute new public components, exports, or API descriptions, keep generated surfaces in sync through the official scripts instead of editing generated files by hand.

pnpm sui headless                 # sync headless component names and namespaced exports
pnpm sui ui                       # sync ui component names
pnpm sui api                      # regenerate docs api json and locale baseline data
pnpm sui api-locales              # refresh api locale template data only
pnpm sui changelog                # regenerate docs changelog json and locale baseline data
pnpm sui api-translate -- --locale zh-CN
pnpm sui changelog-translate -- --locale zh-CN

The docs site now renders component docs through UsageCode, PlaygroundGallery, and ComponentApi. Component detail pages and /releases also read generated changelog data from apps/docs/src/generated/changelog/ and apps/docs/src/generated/changelog-locales/.

Public API or demo delivery changes should keep docs, playground examples, and generated API data aligned. Changelog mapping, release presentation, and changelog locale template changes should keep generated changelog data aligned as well.

📦 Installation

Using the Styled UI Library (Recommended)

If you want ready-to-use components with a modern design:

pnpm add @soybeanjs/ui

Using the Headless Library

If you want to build your own design system from scratch:

pnpm add @soybeanjs/headless

🚀 Usage

@soybeanjs/ui

1. Import Styles

   Import the CSS file in your main entry file (e.g., main.ts):

import '@soybeanjs/ui/styles.css';

2. Global Registration (Optional)

   You can register components globally or import them on demand.

3. On-demand Import (Recommended)

   We recommend using unplugin-vue-components for auto-importing components.

// vite.config.ts
import Components from 'unplugin-vue-components/vite';
import UiResolver from '@soybeanjs/ui/resolver';

export default defineConfig({
  plugins: [
    Components({
      resolvers: [UiResolver()]
    })
  ]
});

4. Nuxt Module

// nuxt.config.ts
export default defineNuxtConfig({
  modules: ['@soybeanjs/ui/nuxt']
});

@soybeanjs/headless

The headless components provide the functionality without the styles.

For data-driven multi-slot patterns, prefer the exported Compact variant when it exists. It is the headless entry point for opinionated composition, while the regular parts remain available for fully manual assembly.

<script setup>
import { AccordionRoot, AccordionItem, AccordionTrigger, AccordionContent } from '@soybeanjs/headless';
</script>

<template>
  <AccordionRoot>
    <AccordionItem value="item-1">
      <AccordionTrigger>Is it accessible?</AccordionTrigger>
      <AccordionContent>Yes. It adheres to the WAI-ARIA design pattern.</AccordionContent>
    </AccordionItem>
  </AccordionRoot>
</template>

✨ Features

• Accessible: Follows WAI-ARIA patterns for roles, focus management, and keyboard navigation.
• RTL ready: Switch supported components between LTR and RTL layouts with ConfigProvider.
• Headless-first: Logic and styles are fully separated — use @soybeanjs/headless alone to build any design system.
• Type Safe: Written in strict TypeScript. All props, emits, slots, and context values are typed.
• Customizable at every level: Override individual slot classes via the ui prop, or swap the entire style layer.
• Lightweight & Tree-shakable: Import only the components you use. Each component is individually tree-shakable.
• Nuxt ready: First-class Nuxt module with auto-registration (@soybeanjs/ui/nuxt).
• unplugin support: Auto-import resolver for unplugin-vue-components (@soybeanjs/ui/resolver).

🤝 How to Contribute

We welcome contributions of all kinds! Please read CONTRIBUTING.md for setup instructions, coding conventions, and the pull request process.

💝 Credits

• reka-ui
• oku-ui
• shadcn-vue
• shadcn/ui
• nuxt-ui
• unocss