@vaneui/ui 0.2.1-alpha.20250813194307.2bb87da → 0.2.1-alpha.20250820100624.167a145

package/README.md

@@ -2,11 +2,65 @@
 
 [![npm version](https://img.shields.io/npm/v/%40vaneui/ui.svg?style=flat)](https://www.npmjs.com/package/%40vaneui/ui)
 
-VaneUI is a React + TypeScript component library powered by Tailwind CSS. It uses a boolean-prop API for variants (size, appearance, shape, layout, typography, etc.) and a flexible theme system so you can set defaults, add extra classes, or programmatically override styles.
+VaneUI helps you build beautiful, consistent UIs faster by turning common design decisions into expressive, readable boolean props. Instead of memorizing property names and values, you compose intent: `primary`, `lg`, `outline`, `rounded`. The result is cleaner code, fewer decisions per component, and a smoother path from wireframe to production.
 
-- Boolean prop API: <Button primary lg pill> instead of stringly typed props
-- ThemeProvider with defaults (themeDefaults), extra classes (extraClasses), and programmatic override (themeOverride)
-- Built CSS you can import directly (no Tailwind setup required to consume)
+## How VaneUI works
+
+At its core, VaneUI maps boolean props to thoughtfully curated CSS classes. You write the JSX using booleans like this:
+
+```tsx
+<Button primary lg pill filled>
+  Get started
+</Button>
+```
+The component resolves those booleans to semantic styles:
+- `primary` → semantic color token
+- `lg` → size scale for paddings, border radius, typography size
+- `pill` → shape preset
+- `filled` → variant preset
+
+Tailwind classes and CSS variables power the final styles:
+- Tailwind utilities for performance and composability
+- CSS variables for theming and per-app overrides
+- Each CSS class can be changed using ThemeProvider
+- Each component has a customizable set of default values for boolean props
+
+You can always mix in your own Tailwind classes via className to fine‑tune any edge case:
+```tsx
+<Button primary lg pill filled className="hover:opacity-80">
+  Get started
+</Button>
+```
+
+## Traditional approach vs VaneUI
+
+Instead of writing verbose prop configurations, VaneUI uses intuitive boolean props that make your code cleaner and more readable:
+
+```tsx
+// Traditional approach
+<Button appearance="primary" size="lg" variant="filled" />
+
+// VaneUI approach  
+<Button primary lg filled />
+```
+
+## Prop combinations
+
+Boolean props can be combined naturally to create the exact styling you need:
+
+```tsx
+<Button primary lg pill shadow>
+  Large primary pill button with shadow
+</Button>
+
+<Card secondary padding border rounded>
+  Secondary card with padding, border and rounded corners
+</Card>
+
+<Stack column itemsCenter>
+  Vertical stack with gap and centered items
+</Stack>
+```
 
 ## Installation
 
@@ -53,6 +107,67 @@ export default function App() {
 }
 ```
 
+## Every Class is Customizable
+
+Behind each boolean prop are carefully crafted CSS classes that you can completely override.
+
+### CSS Variables
+
+You can customize the VaneUI by overriding the CSS variables:
+
+```css
+:root {
+  --text-color-primary: #8b5cf6;      /* Primary text color */
+  --ui-border-radius-md: 1rem;        /* Medium UI radius */
+}
+```
+
+### Tailwind Overrides
+
+Each component can be changed by using the regular Tailwind CSS classes:
+
+```tsx
+<Button primary className="bg-purple-600 hover:bg-purple-700">
+  Custom Primary
+</Button>
+```
+
+### Theme Overrides
+
+You can set up default values of all boolean props by providing `themeDefaults` in ThemeProvider:
+
+```tsx
+const defaults: ThemeDefaults = {
+  button: {
+    pill: true,
+    lg: true,
+  },
+};
+
+return (
+  <ThemeProvider themeDefaults={defaults}>
+    <Button>This button is large and pill-shaped</Button>
+  </ThemeProvider>
+);
+```
+
+You can change default CSS classes of all components by providing `themeOverride` in ThemeProvider:
+
+```tsx
+const overrideFunc = (theme: ThemeProps) => {
+  theme.button.themes.appearance.text.outline.default.base = 'text-blue-200';
+  theme.button.themes.appearance.text.outline.default.hover = 'hover:text-blue-700';
+  theme.button.themes.appearance.text.outline.default.active = 'active:text-blue-900';
+  return theme;
+};
+
+return (
+  <ThemeProvider themeOverride={overrideFunc}>
+    <Button>This button has blue colors</Button>
+  </ThemeProvider>
+);
+```
+
 ## Theming
 
 All components work out of the box with defaults. For deeper customization, wrap your app with ThemeProvider.
@@ -91,12 +206,12 @@ export function App() {
 ## Boolean Props Model
 
 Each component exposes optional boolean props generated from category keys. Common examples:
-- Size: xs, sm, md, lg, xl
-- Appearance: default, primary, secondary, tertiary, accent, success, danger, warning, info, transparent
-- Variant: filled, outline
-- Shape: pill, rounded, sharp
-- Typography: sans, serif, mono, thin…black, italic/notItalic, underline/lineThrough/overline, uppercase/lowercase/capitalize
-- Layout: gap/noGap, inline/block/flex/grid, justify*, items*, padding/noPadding, shadow/noShadow, ring/noRing
+- Size: `xs`, `sm`, `md`, `lg`, `xl`
+- Appearance: `default`, `primary`, `secondary`, `tertiary`, `accent`, `success`, `danger`, `warning`, `info`, `transparent`
+- Variant: `filled`, `outline`
+- Shape: `pill`, `rounded`, `sharp`
+- Typography: `sans`, `serif`, `mono`, `thin`…`black`, `italic`/`notItalic`, `underline`/`lineThrough`/`overline`, `uppercase`/`lowercase`/`capitalize`
+- Layout: `gap`/`noGap`, `inline`/`block`/`flex`/`grid`, `justify*`, `items*`, `padding`/`noPadding`, `shadow`/`noShadow`, `ring`/`noRing`
 
 Only the categories relevant to a component are used. The theme maps these booleans to Tailwind utility classes.
 

package/dist/components/ui/theme/appearance/genericVariantTheme.d.ts

@@ -10,6 +10,7 @@ export declare class GenericVariantTheme<T extends BaseTheme> extends BaseTheme
     getClasses(extractedKeys: CategoryProps): string[];
     static createUIElementTextTheme(): GenericVariantTheme<AppearanceTheme>;
     static createUIElementShadowTheme(): GenericVariantTheme<ShadowAppearanceTheme>;
+    static createLayoutShadowTheme(): GenericVariantTheme<ShadowAppearanceTheme>;
     static createBorderAppearanceTheme(): GenericVariantTheme<AppearanceTheme>;
     static createUIElementBorderTheme(): GenericVariantTheme<AppearanceTheme>;
     static createUIElementRingTheme(): GenericVariantTheme<AppearanceTheme>;

package/dist/components/ui/theme/appearance/shadowAppearanceTheme.d.ts

@@ -5,7 +5,9 @@ export interface ShadowAppearanceTheme extends Record<AppearanceKey, Record<Size
 }
 export declare class ShadowAppearanceTheme extends BaseTheme {
     private static readonly defaultShadow;
+    private static readonly layoutShadow;
     constructor(initial?: Partial<Record<AppearanceKey, Record<SizeKey, Record<ModeKey, string>> | null>>);
     getClasses(extractedKeys: CategoryProps): string[];
     static createTheme(src?: Partial<Record<AppearanceKey, Record<SizeKey, Record<ModeKey, string>> | null>>): ShadowAppearanceTheme;
+    static createLayoutTheme(src?: Partial<Record<AppearanceKey, Record<SizeKey, Record<ModeKey, string>> | null>>): ShadowAppearanceTheme;
 }

package/dist/index.esm.js

@@ -3769,6 +3769,15 @@ class ShadowAppearanceTheme extends BaseTheme {
     static createTheme(src = {}) {
         return new ShadowAppearanceTheme(src);
     }
+    static createLayoutTheme(src = {}) {
+        const theme = new ShadowAppearanceTheme(src);
+        ComponentKeys.appearance.forEach((key) => {
+            if (theme[key] === ShadowAppearanceTheme.defaultShadow) {
+                theme[key] = ShadowAppearanceTheme.layoutShadow;
+            }
+        });
+        return theme;
+    }
 }
 ShadowAppearanceTheme.defaultShadow = {
     xs: { base: "shadow-2xs", hover: "hover:shadow-xs", active: "" },
@@ -3777,6 +3786,13 @@ ShadowAppearanceTheme.defaultShadow = {
     lg: { base: "shadow-md", hover: "hover:shadow-lg", active: "" },
     xl: { base: "shadow-lg", hover: "hover:shadow-xl", active: "" }
 };
+ShadowAppearanceTheme.layoutShadow = {
+    xs: { base: "shadow-2xs", hover: "", active: "" },
+    sm: { base: "shadow-xs", hover: "", active: "" },
+    md: { base: "shadow-sm", hover: "", active: "" },
+    lg: { base: "shadow-md", hover: "", active: "" },
+    xl: { base: "shadow-lg", hover: "", active: "" }
+};
 
 class GenericVariantTheme extends BaseTheme {
     constructor(variantInstances) {
@@ -3811,6 +3827,12 @@ class GenericVariantTheme extends BaseTheme {
             filled: ShadowAppearanceTheme.createTheme({})
         });
     }
+    static createLayoutShadowTheme() {
+        return new GenericVariantTheme({
+            outline: ShadowAppearanceTheme.createLayoutTheme({}),
+            filled: ShadowAppearanceTheme.createLayoutTheme({})
+        });
+    }
     static createBorderAppearanceTheme() {
         return new GenericVariantTheme({
             outline: AppearanceTheme.createTheme({ base: borderAppearanceClasses }),
@@ -4024,7 +4046,7 @@ const defaultBadgeTheme = new ComponentTheme("span", "w-fit h-fit transition-all
         text: GenericVariantTheme.createUIElementTextTheme(),
         border: GenericVariantTheme.createUIElementBorderTheme(),
         ring: GenericVariantTheme.createUIElementRingTheme(),
-        shadow: GenericVariantTheme.createUIElementShadowTheme()
+        shadow: GenericVariantTheme.createLayoutShadowTheme()
     },
     layout: {
         ...defaultLayoutTheme,
@@ -4065,7 +4087,7 @@ const defaultChipTheme = new ComponentTheme("span", "w-fit h-fit transition-all
         text: GenericVariantTheme.createUIElementTextTheme(),
         border: GenericVariantTheme.createUIElementBorderTheme(),
         ring: GenericVariantTheme.createUIElementRingTheme(),
-        shadow: GenericVariantTheme.createUIElementShadowTheme()
+        shadow: GenericVariantTheme.createLayoutShadowTheme()
     },
     layout: {
         ...defaultLayoutTheme,
@@ -4105,7 +4127,7 @@ const defaultCodeTheme = new ComponentTheme("code", "", {
         text: GenericVariantTheme.createUIElementTextTheme(),
         border: GenericVariantTheme.createUIElementBorderTheme(),
         ring: GenericVariantTheme.createUIElementRingTheme(),
-        shadow: GenericVariantTheme.createUIElementShadowTheme()
+        shadow: GenericVariantTheme.createLayoutShadowTheme()
     },
     layout: {
         ...defaultLayoutTheme,
@@ -4386,7 +4408,7 @@ const defaultCardTheme = new ComponentTheme("div", "", {
         wrap: new WrapTheme(),
         direction: new DirectionTheme(),
         breakpoint: new BreakpointTheme(),
-        shadow: ShadowAppearanceTheme.createTheme(),
+        shadow: ShadowAppearanceTheme.createLayoutTheme(),
     },
     appearance: {
         background: AppearanceTheme.createLayoutBgTheme(),
@@ -4426,7 +4448,7 @@ const defaultRowTheme = new ComponentTheme("div", "", {
         background: AppearanceTheme.createLayoutBgTheme(),
         border: GenericVariantTheme.createUIElementBorderTheme(),
         ring: GenericVariantTheme.createUIElementRingTheme(),
-        shadow: GenericVariantTheme.createUIElementShadowTheme(),
+        shadow: GenericVariantTheme.createLayoutShadowTheme(),
     }
 }, {
     row: true,
@@ -4482,7 +4504,7 @@ const defaultContainerTheme = new ComponentTheme("div", "flex-col mx-auto w-full
         text: AppearanceTheme.createTheme({ base: textAppearanceClasses }),
         border: AppearanceTheme.createTheme({ base: borderAppearanceClasses }),
         ring: AppearanceTheme.createTheme({ base: ringAppearanceClasses }),
-        shadow: GenericVariantTheme.createUIElementShadowTheme(),
+        shadow: GenericVariantTheme.createLayoutShadowTheme(),
     }
 }, {
     noRing: true,
@@ -4511,7 +4533,7 @@ const defaultColTheme = new ComponentTheme("div", "", {
         background: AppearanceTheme.createLayoutBgTheme(),
         border: GenericVariantTheme.createUIElementBorderTheme(),
         ring: GenericVariantTheme.createUIElementRingTheme(),
-        shadow: GenericVariantTheme.createUIElementShadowTheme(),
+        shadow: GenericVariantTheme.createLayoutShadowTheme(),
     }
 }, {
     column: true,
@@ -4544,7 +4566,7 @@ const defaultStackTheme = new ComponentTheme("div", "", {
         background: AppearanceTheme.createLayoutBgTheme(),
         border: GenericVariantTheme.createUIElementBorderTheme(),
         ring: GenericVariantTheme.createUIElementRingTheme(),
-        shadow: GenericVariantTheme.createUIElementShadowTheme(),
+        shadow: GenericVariantTheme.createLayoutShadowTheme(),
     }
 }, {
     md: true,
@@ -4584,7 +4606,7 @@ const defaultSectionTheme = new ComponentTheme("div", "w-full flex-col", {
         text: AppearanceTheme.createTheme({ base: textAppearanceClasses }),
         border: AppearanceTheme.createTheme({ base: borderAppearanceClasses }),
         ring: AppearanceTheme.createTheme({ base: ringAppearanceClasses }),
-        shadow: ShadowAppearanceTheme.createTheme(),
+        shadow: ShadowAppearanceTheme.createLayoutTheme(),
     },
     layout: {
         ...defaultLayoutTheme,
@@ -4745,7 +4767,7 @@ const defaultImgTheme = new ComponentTheme("img", "object-cover", // Default to
     appearance: {
         border: GenericVariantTheme.createUIElementBorderTheme(),
         ring: GenericVariantTheme.createUIElementRingTheme(),
-        shadow: GenericVariantTheme.createUIElementShadowTheme()
+        shadow: GenericVariantTheme.createLayoutShadowTheme()
     }
 }, {
     rounded: true,