@techsio/ui-kit 0.0.0

package/README.md

@@ -0,0 +1,165 @@
+# Web Revolution UI Library – Design System README
+
+Welcome to the Web Revolution UI Library! This guide explains our design system’s fundamentals, folder structure, theming, and customization rules. Follow these guidelines to keep our system consistent, flexible, and easy to maintain.
+
+---
+
+## 1. Overview
+
+Our design system is built with **Tailwind CSS v4** and React. It uses a **multi-layered design token approach** to control all colors, spacing, typography, and other visual aspects. We maintain one shared UI library, and we allow brand-specific customizations via a dedicated `brands` folder inside the library.
+
+**Key Points:**
+
+- **Multi-layered design tokens:** We separate tokens into three layers: global, semantic, and component.
+- **Single UI library:** All shared components live in one library (e.g. `ui`).
+- **Centralized CSS Variables:** All design tokens (CSS variables) are defined in one central place.
+- **Hybrid Structure:** Our UI library is organized into atoms, molecules, and domain-based organisms. Basic components (like buttons) are atoms or molecules; only composite, domain-specific components go into organisms.
+- **Clear Boundaries:** For example, a button is an atom or molecule. We never export a button from an organism.
+
+---
+
+## 2. Design Tokens
+
+### Multi-Layered Tokens
+
+1. **Global Tokens:**
+    - These are the raw design values (like our base color palette, spacing scales, etc.).
+    - They are defined in our central tokens files (e.g. `_colors.css`, `_spacing.css`).
+2. **Semantic Tokens:**
+    - These give meaning to global tokens by mapping them to their design role.
+    - For example, `-color-brand-primary` maps to a global blue value.
+    - All components will use semantic tokens rather than raw values.
+3. **Component Tokens:**
+    - These are defined for each component and act as a layer between the component and semantic tokens.
+    - For example, a Button component uses `-button-bg` which is set to `var(--color-brand-primary)`.
+    - **Important:** All component tokens are defined centrally, not near the component code.
+
+---
+
+## 3. Folder Structure
+
+Our UI library follows a hybrid approach with three main parts:
+
+### A. Basic Components (Atoms & Molecules)
+
+- **Atoms:**
+Small, reusable components such as buttons, inputs, icons, etc.
+- **Molecules:**
+Simple combinations of atoms like form groups or card headers.
+
+These live in folders such as:
+
+```
+ui/atoms/
+ui/molecules/
+
+```
+
+### B. Domain-Based Organisms
+
+- **Organisms:**
+Larger, composite components that are specific to a business domain (e.g. cart, checkout, navigation).**Note:** Organisms should not export basic building blocks like buttons. If you need a button, use the atom or molecule from the appropriate folder.
+
+Organisms are organized by domain:
+
+```
+ui/organisms/cart/
+ui/organisms/checkout/
+ui/organisms/navigation/
+
+```
+
+### C. Brand Customizations
+
+- **Brands Folder:**
+Custom, brand-specific overrides live in a dedicated folder. For example, if a brand needs a special Header, its custom component will live under:
+This keeps the shared UI library clean while allowing brands to override only what they need.
+
+    ```
+    ui/brands/customer-a/
+
+    ```
+
+
+> Note: Always use kebab-case for folder and component filenames. For example, use customer-a instead of customerA.
+>
+
+---
+
+## 4. Theming and CSS Variables
+
+### Centralized Tokens
+
+- **All CSS Variables:**
+We define all our design tokens in one central set of CSS files (e.g. in the `tokens/` directory). Do not scatter token definitions next to component code.
+- **Optional Default Theme:**
+We support a “default theme” file that you can import if you want to start with predefined values. However, the core system is theme-agnostic: our self-referencing palette contains only semantic tokens. If you want the default look, import the default theme; otherwise, you can define your own theme based on the semantic tokens.
+- **Using Tailwind’s `@theme`:**
+Our CSS token files use Tailwind’s `@theme` block to generate CSS variables, ensuring consistency with our Tailwind utilities.
+
+### How Overrides Work
+
+- Brand-specific override files (e.g. `ui/brands/customer-a/theme.css`) can override any semantic token.
+- In your app’s main CSS, import the global tokens first, then the brand override file. This cascade ensures that the brand’s values override the defaults.
+
+---
+
+## 5. Development Guidelines
+
+### Component Development
+
+- **Use Tokens Exclusively:**
+Always use component tokens (e.g. `-button-bg`) in your styles. Do not use semantic tokens directly in component code.
+- **Keep It Simple:**
+Build your atoms and molecules first. Organisms are domain-specific composites and should use the shared atoms/molecules.
+- **Export Only Where Appropriate:**
+For example, if a component is basic (like a Button), it belongs in atoms or molecules. Never export a Button from an organism.
+
+### Brand Customizations
+
+- **Custom Components:**
+If a customer needs a completely custom component, add it to the `brands/` folder. Do not modify the core shared components.
+- **Override Process:**
+When overriding, create a file in the brand folder and map the semantic tokens to the custom values. This way, the core remains untouched.
+
+### Documentation
+
+- We use **Storybook** for our component documentation and previews (for now). We may add other documentation tools later.
+- Our documentation explains all tokens, component usage, and override guidelines. Please refer to Storybook for live examples and further details.
+
+---
+
+## 6. Quick Reference
+
+- **Design Tokens:**
+    - Global Tokens: Defined in `tokens/_*.css` files.
+    - Semantic Tokens: Map global tokens to design roles (e.g. `-color-brand-primary`).
+    - Component Tokens: Defined centrally; used in component styling (e.g. `-button-bg`).
+- **Folder Organization:**
+    - **Atoms/Molecules:** `ui/atoms/` and `ui/molecules/`
+    - **Organisms:** Domain-based (e.g. `ui/organisms/cart/`)
+    - **Brands:** Overrides and customizations (e.g. `ui/brands/customer-a/`)
+- **Theming:**
+
+    Import tokens first, then any default or brand-specific theme overrides in your main CSS file.
+
+- **Guidelines:**
+    - Always use the token system.
+    - Never mix token definitions with component code.
+    - Keep overrides in dedicated brand folders.
+    - Basic components (e.g., Button) belong only in atoms/molecules.
+
+## 7. Publishing and releases
+
+- Build + publint: `pnpm -C libs/ui build` runs `rsbuild-plugin-publint` after the build; if exports/entrypoints are wrong, this command fails.
+- Exports only, no barrel: import from explicit subpaths (e.g. `@techsio/ui-kit/atoms/button`, `@techsio/ui-kit/templates/accordion`, `@techsio/ui-kit/utils`). The package root is intentionally not exported.
+- Automated releases: `libs/ui/release.config.mjs` uses semantic-release (tag format `ui-kit-v<version>`) to bump versions, update changelog, and publish to npm. While we are <1.0.0, `BREAKING CHANGE` commits are forced to “minor” bumps to stay in 0.x; remove that release rule when stabilizing for 1.0.0+ to restore SemVer majors.
+- Security posture: releases are restricted to GitHub Actions (`GITHUB_ACTIONS` required), npm publishes use provenance (`NPM_CONFIG_PROVENANCE=true`), and tokens live only in Actions secrets (`GH_TOKEN`, `NPM_TOKEN`). Keep secrets in a protected environment for extra safety.
+- CI workflow: `.github/workflows/ui-release.yml` builds `libs/ui` and runs semantic-release on `master`/`main` with `GH_TOKEN` and `NPM_TOKEN` secrets.
+- Local dry run: `pnpm -C libs/ui semantic-release --dry-run`.
+- Commit format: follow Conventional Commits (`feat:`, `fix:`, `chore:`, `BREAKING CHANGE:`) so semantic-release can infer the correct version bump.
+- Required CI secrets: `GH_TOKEN` (repo write) and `NPM_TOKEN` (publish).
+
+## 8. Conclusion
+
+This README serves as the single source of truth for building and maintaining our design system. By adhering to these guidelines, you ensure that our UI remains consistent, flexible, and scalable across multiple brands. If you have any questions or suggestions, please reach out to the design system team.

package/dist/atoms/badge.js

@@ -0,0 +1,66 @@
+import { jsx } from "react/jsx-runtime";
+import { tv } from "../utils.js";
+const badgeVariants = tv({
+    base: [
+        'inline-flex items-center justify-center',
+        'p-badge',
+        'rounded-badge border-badge-border',
+        'text-badge-size font-badge',
+        'border-(length:--border-width-badge-dynamic)'
+    ],
+    variants: {
+        variant: {
+            primary: [
+                'bg-badge-bg-primary text-badge-fg-primary border-badge-border-primary'
+            ],
+            secondary: [
+                'bg-badge-bg-secondary text-badge-fg-secondary border-badge-border-secondary'
+            ],
+            tertiary: [
+                'bg-badge-bg-tertiary text-badge-fg-tertiary border-badge-border-tertiary'
+            ],
+            discount: [
+                'bg-badge-bg-discount text-badge-fg-discount border-badge-border-discount'
+            ],
+            info: [
+                'bg-badge-bg-info text-badge-fg-info border-badge-border-info'
+            ],
+            success: [
+                'bg-badge-bg-success text-badge-fg-success border-badge-border-success'
+            ],
+            warning: [
+                'bg-badge-bg-warning text-badge-fg-warning border-badge-border-warning'
+            ],
+            danger: [
+                'bg-badge-bg-danger text-badge-fg-danger border-badge-border-danger'
+            ],
+            outline: [
+                'bg-badge-bg-outline text-badge-fg-outline border-badge-border-outline'
+            ],
+            dynamic: []
+        }
+    },
+    defaultVariants: {
+        variant: 'info'
+    }
+});
+function Badge({ variant, className, children, style, ...props }) {
+    const isDynamic = 'dynamic' === variant;
+    const { bgColor, fgColor, borderColor, ...restProps } = props;
+    const dynamicStyles = isDynamic ? {
+        ...style,
+        'background-color': bgColor,
+        color: fgColor,
+        'border-color': borderColor
+    } : style;
+    return /*#__PURE__*/ jsx("span", {
+        className: badgeVariants({
+            variant,
+            className
+        }),
+        style: dynamicStyles,
+        ...restProps,
+        children: children
+    });
+}
+export { Badge };

package/dist/atoms/button.js

@@ -0,0 +1,275 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { tv } from "../utils.js";
+import { Icon } from "./icon.js";
+const buttonVariants = tv({
+    base: [
+        'relative',
+        'inline-flex items-baseline justify-center cursor-pointer',
+        'font-medium',
+        'transition-all duration-200',
+        'focus:outline-none',
+        'focus-visible:ring',
+        'focus-visible:ring-button-ring',
+        'disabled:text-button-fg-disabled disabled:pointer-events-none'
+    ],
+    variants: {
+        variant: {
+            primary: '',
+            secondary: '',
+            tertiary: '',
+            danger: '',
+            warning: ''
+        },
+        theme: {
+            solid: 'disabled:bg-button-bg-disabled',
+            light: 'disabled:bg-button-bg-disabled',
+            borderless: 'bg-button-bg-borderless hover:bg-button-bg-borderless-hover active:bg-button-bg-borderless-active',
+            outlined: 'border disabled:border-button-border-disabled',
+            unstyled: ''
+        },
+        uppercase: {
+            true: 'uppercase'
+        },
+        size: {
+            sm: 'p-button-sm text-button-sm rounded-button-sm gap-button-sm',
+            md: 'p-button-md text-button-md rounded-button-md gap-button-md',
+            lg: 'p-button-lg text-button-lg rounded-button-lg gap-button-lg',
+            current: 'text-inherit gap-button-md'
+        },
+        block: {
+            true: 'w-full'
+        }
+    },
+    compoundVariants: [
+        {
+            variant: 'primary',
+            theme: 'solid',
+            className: [
+                'bg-button-bg-primary',
+                'hover:bg-button-bg-primary-hover',
+                'active:bg-button-bg-primary-active',
+                'text-button-fg-primary'
+            ]
+        },
+        {
+            variant: 'secondary',
+            theme: 'solid',
+            className: [
+                'bg-button-bg-secondary',
+                'hover:bg-button-bg-secondary-hover',
+                'active:bg-button-bg-secondary-active',
+                'text-button-fg-secondary'
+            ]
+        },
+        {
+            variant: 'tertiary',
+            theme: 'solid',
+            className: [
+                'bg-button-bg-tertiary',
+                'hover:bg-button-bg-tertiary-hover',
+                'active:bg-button-bg-tertiary-active',
+                'text-button-fg-tertiary'
+            ]
+        },
+        {
+            variant: 'warning',
+            theme: 'solid',
+            className: [
+                'bg-button-bg-warning',
+                'hover:bg-button-bg-warning-hover',
+                'active:bg-button-bg-warning-active',
+                'text-button-fg-warning'
+            ]
+        },
+        {
+            variant: 'danger',
+            theme: 'solid',
+            className: [
+                'bg-button-bg-danger',
+                'hover:bg-button-bg-danger-hover',
+                'active:bg-button-bg-danger-active',
+                'text-button-fg-danger'
+            ]
+        },
+        {
+            variant: 'primary',
+            theme: 'light',
+            className: [
+                'bg-button-bg-primary-light',
+                'hover:bg-button-bg-primary-light-hover',
+                'active:bg-button-bg-primary-light-active',
+                'text-button-fg-primary-light'
+            ]
+        },
+        {
+            variant: 'secondary',
+            theme: 'light',
+            className: [
+                'bg-button-bg-secondary-light',
+                'hover:bg-button-bg-secondary-light-hover',
+                'active:bg-button-bg-secondary-light-active',
+                'text-button-fg-secondary-light'
+            ]
+        },
+        {
+            variant: 'tertiary',
+            theme: 'light',
+            className: [
+                'bg-button-bg-tertiary-light',
+                'hover:bg-button-bg-tertiary-light-hover',
+                'active:bg-button-bg-tertiary-light-active',
+                'text-button-fg-tertiary-light'
+            ]
+        },
+        {
+            variant: 'warning',
+            theme: 'light',
+            className: [
+                'bg-button-bg-warning-light',
+                'hover:bg-button-bg-warning-light-hover',
+                'active:bg-button-bg-warning-light-active',
+                'text-button-fg-warning-light'
+            ]
+        },
+        {
+            variant: 'danger',
+            theme: 'light',
+            className: [
+                'bg-button-bg-danger-light',
+                'hover:bg-button-bg-danger-light-hover',
+                'active:bg-button-bg-danger-light-active',
+                'text-button-fg-danger-light'
+            ]
+        },
+        {
+            variant: 'primary',
+            theme: 'outlined',
+            className: [
+                'border-button-border-primary',
+                'hover:bg-button-bg-outlined-primary-hover',
+                'active:bg-button-bg-outlined-primary-active',
+                'text-button-fg-outlined-primary'
+            ]
+        },
+        {
+            variant: 'secondary',
+            theme: 'outlined',
+            className: [
+                'border-button-border-secondary',
+                'hover:bg-button-bg-outlined-secondary-hover',
+                'active:bg-button-bg-outlined-secondary-active',
+                'text-button-fg-outlined-secondary'
+            ]
+        },
+        {
+            variant: 'tertiary',
+            theme: 'outlined',
+            className: [
+                'border-button-border-tertiary',
+                'hover:bg-button-bg-outlined-tertiary-hover',
+                'active:bg-button-bg-outlined-tertiary-active',
+                'text-button-fg-outlined-tertiary'
+            ]
+        },
+        {
+            variant: 'warning',
+            theme: 'outlined',
+            className: [
+                'border-button-border-warning',
+                'hover:bg-button-bg-outlined-warning-hover',
+                'active:bg-button-bg-outlined-warning-active',
+                'text-button-fg-outlined-warning'
+            ]
+        },
+        {
+            variant: 'danger',
+            theme: 'outlined',
+            className: [
+                'border-button-border-danger',
+                'hover:bg-button-bg-outlined-danger-hover',
+                'active:bg-button-bg-outlined-danger-active',
+                'text-button-fg-outlined-danger'
+            ]
+        },
+        {
+            variant: 'primary',
+            theme: 'borderless',
+            className: [
+                'text-button-fg-primary-borderless'
+            ]
+        },
+        {
+            variant: 'secondary',
+            theme: 'borderless',
+            className: [
+                'text-button-fg-secondary-borderless'
+            ]
+        },
+        {
+            variant: 'tertiary',
+            theme: 'borderless',
+            className: [
+                'text-button-fg-tertiary-borderless'
+            ]
+        },
+        {
+            variant: 'warning',
+            theme: 'borderless',
+            className: [
+                'text-button-fg-warning-borderless'
+            ]
+        },
+        {
+            variant: 'danger',
+            theme: 'borderless',
+            className: [
+                'text-button-fg-danger-borderless'
+            ]
+        },
+        {
+            theme: 'outlined',
+            size: 'sm',
+            className: 'border-(length:--border-button-width-sm)'
+        },
+        {
+            theme: 'outlined',
+            size: 'md',
+            className: 'border-(length:--border-button-width-md)'
+        },
+        {
+            theme: 'outlined',
+            size: 'lg',
+            className: 'border-(length:--border-button-width-lg)'
+        }
+    ],
+    defaultVariants: {
+        variant: 'primary',
+        theme: 'solid',
+        size: 'md',
+        light: false
+    }
+});
+function Button({ variant, theme, size, block, isLoading, icon, iconPosition = 'left', uppercase = false, children, className, ...props }) {
+    return /*#__PURE__*/ jsxs("button", {
+        className: buttonVariants({
+            variant,
+            theme,
+            size,
+            block,
+            uppercase,
+            className
+        }),
+        disabled: isLoading,
+        ...props,
+        children: [
+            icon && 'left' === iconPosition && /*#__PURE__*/ jsx(Icon, {
+                icon: icon
+            }),
+            children,
+            icon && 'right' === iconPosition && /*#__PURE__*/ jsx(Icon, {
+                icon: icon
+            })
+        ]
+    });
+}
+export { Button, buttonVariants };

package/dist/atoms/error-text.js

@@ -0,0 +1,38 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { tv } from "../utils.js";
+import { Icon } from "./icon.js";
+const errorVariants = tv({
+    base: [
+        'text-error-fg',
+        'flex items-center gap-1'
+    ],
+    variants: {
+        size: {
+            sm: 'text-error-sm',
+            md: 'text-error-md',
+            lg: 'text-error-lg'
+        }
+    },
+    defaultVariants: {
+        size: 'md'
+    }
+});
+function ErrorText({ className, showIcon, children, ref, size, ...props }) {
+    return /*#__PURE__*/ jsxs("div", {
+        ref: ref,
+        className: errorVariants({
+            size,
+            className
+        }),
+        ...props,
+        children: [
+            showIcon && /*#__PURE__*/ jsx(Icon, {
+                icon: "token-icon-error"
+            }),
+            /*#__PURE__*/ jsx("span", {
+                children: children
+            })
+        ]
+    });
+}
+export { ErrorText };

package/dist/atoms/extra-text.js

@@ -0,0 +1,27 @@
+import { jsx } from "react/jsx-runtime";
+import { tv } from "../utils.js";
+const extraTextVariants = tv({
+    base: [
+        'text-helper-fg'
+    ],
+    variants: {
+        size: {
+            sm: 'text-helper-sm',
+            md: 'text-helper-md',
+            lg: 'text-helper-lg'
+        }
+    },
+    defaultVariants: {
+        size: 'md'
+    }
+});
+function ExtraText({ children, size, ...props }) {
+    return /*#__PURE__*/ jsx("span", {
+        className: extraTextVariants({
+            size
+        }),
+        ...props,
+        children: children
+    });
+}
+export { ExtraText };

package/dist/atoms/icon.js

@@ -0,0 +1,42 @@
+import { jsx } from "react/jsx-runtime";
+import { tv } from "../utils.js";
+const iconVariants = tv({
+    base: [
+        'inline-block flex-shrink-0 align-middle leading-none self-center'
+    ],
+    variants: {
+        size: {
+            current: '',
+            xs: 'text-icon-xs',
+            sm: 'text-icon-sm',
+            md: 'text-icon-md',
+            lg: 'text-icon-lg',
+            xl: 'text-icon-xl',
+            '2xl': 'text-icon-2xl'
+        },
+        color: {
+            current: 'text-current',
+            primary: 'text-primary',
+            secondary: 'text-secondary',
+            danger: 'text-danger',
+            success: 'text-success',
+            warning: 'text-warning'
+        }
+    },
+    defaultVariants: {
+        size: 'current',
+        color: 'current'
+    }
+});
+function Icon({ icon, size, color, className, ...props }) {
+    return /*#__PURE__*/ jsx("span", {
+        className: `${iconVariants({
+            size,
+            color,
+            className
+        })} ${icon}`,
+        "aria-hidden": "true",
+        ...props
+    });
+}
+export { Icon };

package/dist/atoms/image.js

@@ -0,0 +1,11 @@
+import { jsx } from "react/jsx-runtime";
+function Image({ as, src, alt, className, ...props }) {
+    const Component = as || 'img';
+    return /*#__PURE__*/ jsx(Component, {
+        src: src,
+        alt: alt,
+        className: className,
+        ...props
+    });
+}
+export { Image };