@vuecs/core

The engine of vuecs — a layered theme-resolution system, structured variants, behavioral defaults, and cross-cutting config for Vue 3. Every vuecs component package (and any third-party library that wants to be reskinnable through the same app.use() call) is built on it.

✨ What's inside

• 🎨 Theme system — CSS classes resolve through four layers (component defaults → themes → overrides → instance prop), with extend() to merge instead of replace. Pure resolution functions, zero Vue dependency, fully unit-testable.
• 🧬 Variant system — declarative variants / compoundVariants / defaultVariants (cva-style), merged across all theme layers. <VCButton :theme-variant="{ color: 'error', size: 'sm' }">.
• 🧩 defineTheme() — compose a new theme on top of one or more existing themes (extends: [a, b]), so brand themes ship as single self-contained packages.
• ⚙️ Behavioral defaults — useComponentDefaults() resolves non-class props (button text, placeholders, icon names) through instance → global → hardcoded layers. Accepts MaybeRef, so computed(() => t('actions.create')) makes every default i18n-reactive.
• 🌐 Cross-cutting config — useConfig() + <VCConfigProvider> for app-wide or subtree-scoped state (dir, locale, theme-augmented keys like nonce). useLocale() reads the active BCP-47 locale anywhere.
• 🪶 Headless composables — useForwardProps, useForwardExpose, useArrowNavigation, useTypeahead, useStateMachine, useSelectionMachine, useId, and more — ported in-tree so core stays zero-dep beyond Vue 3.
• 🧱 VCPrimitive — the as / asChild rendering building block, so downstream libraries get polymorphic elements without a reka-ui dependency.
• 🔍 auditTheme() — CI-friendly drift detection comparing any theme against the component-defaults catalog.
• 🛡️ Typed end-to-end — ThemeElements, ComponentDefaults, and Config are augmentable interfaces; component packages register themselves via declaration merging, giving you autocomplete + typo detection inside app.use(vuecs, { ... }).

📦 Installation

npm install @vuecs/core

⚡ Usage

Configure everything in one place:

import vuecs, { extend } from '@vuecs/core';
import tailwind from '@vuecs/theme-tailwind';
import lucide from '@vuecs/icons-lucide';

app.use(vuecs, {
    themes: [tailwind()],
    icons:  [lucide()],
    overrides: {
        elements: {
            button: { classes: { root: extend('shadow-lg') } },
        },
    },
    defaults: {
        formSelect: { placeholder: '-- Select --' },
    },
    config: { locale: 'de-DE' },
});

Author your own themable component with the same machinery vuecs uses internally:

import { defineComponent, h } from 'vue';
import { themableProps, useComponentTheme, useThemeProps } from '@vuecs/core';

export default defineComponent({
    name: 'MyChip',
    props: {
        color: { type: String, default: undefined },
        ...themableProps<{ root: string }>(),
    },
    setup(props, { slots }) {
        const theme = useComponentTheme('myChip', useThemeProps(props, 'color'), {
            classes: { root: 'my-chip' },
        });
        return () => h('span', { class: theme.value.root }, slots.default?.());
    },
});

📚 Documentation

• Theme system — layers, extend(), merge semantics
• Variants — variant axes + compound variants
• Composing themes — defineTheme() / mergeThemes()
• Behavioral defaults — i18n-friendly global defaults
• Headless composables · VCPrimitive
• Build a themable component

License

Made with 💚

Published under Apache 2.0 License.