Veevart Design System

A professional design system built on HeroUI for creating consistent, accessible, and elegant user interfaces.

🎯 Overview

The Veevart Design System provides:

• Design Tokens: Colors, typography, and spacing systems
• Reusable Patterns: Navbar, Stepper, Footer components
• Page Templates: Complete layouts for common use cases
• 50+ HeroUI Components: All themed with Veevart brand colors

📦 Two Types of Builds

This project has two different build outputs for different purposes:

1️⃣ NPM Library Build (for developers)

Purpose: Publish components as an installable package

npm run build

Generates: dist/ folder with:

• Compiled JavaScript (ES + CJS)
• TypeScript definitions (.d.ts)
• CSS styles

Published to: NPM registry Used in: Other React projects that install the library

npm install @veevarts/design-system

2️⃣ Storybook Build (for documentation)

Purpose: Generate a static website to showcase components

npm run build-storybook

Generates: storybook-static/ folder with:

• Complete HTML/CSS/JS website
• Interactive component demos
• Full documentation

Deployed to: Vercel, Netlify, GitHub Pages, etc. Used by: Designers, developers, and stakeholders to browse the design system

🚀 Quick Start

Prerequisites

• Node.js: v20.19.0 (see .nvmrc)
• npm: v10+

Use nvm to install the correct version:

nvm use

Installation

npm install

Development

Run Storybook locally:

npm run storybook

Opens at http://localhost:6006

Run dev server:

npm run dev

Opens at http://localhost:5173

📜 Available Scripts

| Command | Description | |---------|-------------| | npm run dev | Start Vite dev server | | npm run build | Build library for NPM (→ dist/) | | npm run storybook | Run Storybook locally | | npm run build-storybook | Build Storybook site (→ storybook-static/) | | npm run deploy-storybook | Build + deploy Storybook to Vercel | | npm run lint | Run ESLint | | npm run preview | Preview production build |

🧪 Test Locally In Another Project

Use this flow when you want to validate the package in a different local repository before publishing.

1. Build and pack this design system

npm run build
npm pack

This generates a local tarball file like: veevarts-design-system-1.0.0-alpha.23.tgz

2. Install the tarball in another local project

npm install /absolute/path/to/Design-System/veevarts-design-system-1.0.0-alpha.23.tgz

Tip: after new changes, run npm run build && npm pack again and reinstall the updated tarball in the consumer project.

💻 Usage

Install in your project

Basic installation:

npm install @veevarts/design-system @heroui/react framer-motion lucide-react

If using RichTextArea component (additional TipTap dependencies):

npm install @tiptap/core @tiptap/react @tiptap/starter-kit @tiptap/pm \
  @tiptap/extension-color @tiptap/extension-highlight \
  @tiptap/extension-link @tiptap/extension-placeholder \
  @tiptap/extension-task-item @tiptap/extension-task-list \
  @tiptap/extension-text-align @tiptap/extension-underline

Import components

import { HeroUIProvider, Navbar, Footer, Button } from '@veevarts/design-system';

function App() {
  return (
    <HeroUIProvider>
      <Navbar />
      <main>
        <Button color="primary">Click me</Button>
      </main>
      <Footer copyrightText="© 2026 My Company" />
    </HeroUIProvider>
  );
}

Import HeroUI components

All HeroUI components are re-exported and themed:

import { Card, Input, Modal, Dropdown } from '@veevarts/design-system';

For complete HeroUI documentation, visit: HeroUI Storybook

Configure Tailwind CSS

To use the Veevart design tokens and HeroUI theme in your project, update your tailwind.config.js:

const { heroui } = require('@heroui/react');
const { veevartPreset, createHeroUIConfig } = require('@veevarts/design-system/tailwind');

module.exports = {
  presets: [veevartPreset],
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@heroui/theme/dist/**/*.{js,ts,jsx,tsx}',
  ],
  darkMode: 'class',
  plugins: [heroui(createHeroUIConfig())],
};

Custom Primary Color (Client Branding)

Override the primary color for client-specific branding:

const { heroui } = require('@heroui/react');
const { veevartPreset, createHeroUIConfig } = require('@veevarts/design-system/tailwind');

// Color from API, environment variable, or configuration
const clientPrimaryColor = process.env.CLIENT_PRIMARY_COLOR || '#C14615';

module.exports = {
  presets: [veevartPreset],
  content: [
    './src/**/*.{js,ts,jsx,tsx}',
    './node_modules/@heroui/theme/dist/**/*.{js,ts,jsx,tsx}',
  ],
  darkMode: 'class',
  plugins: [
    heroui(createHeroUIConfig({
      colors: {
        primary: clientPrimaryColor,
        // You can also override: secondary, success, warning, danger
      },
    })),
  ],
};

Available Tailwind Exports

| Export | Description | |--------|-------------| | veevartPreset | Complete Tailwind preset with all design tokens | | createHeroUIConfig(overrides?) | Creates HeroUI plugin config with optional color overrides | | tokens | All tokens: { colors, typography, spacing, tailwindTheme } | | colors | Color tokens (brand, semantic, neutral, palettes) | | typography | Typography tokens (fontFamily, fontSize, fontWeight, lineHeight) | | spacing | Spacing tokens |

🏗️ Project Structure

design-system/
├── src/
│   ├── index.ts                    # Main entry point
│   ├── foundations/                # Design tokens (colors, typography, spacing)
│   ├── patterns/                   # Composition components
│   │   ├── Navbar/
│   │   ├── Stepper/
│   │   └── Footer/
│   ├── templates/                  # Page layouts
│   │   ├── ConfirmationPageTemplate/
│   │   └── EventDetailsTemplate/
│   ├── providers/                  # HeroUIProvider wrapper
│   ├── theme/                      # Theme configuration
│   └── tokens/                     # Design tokens
├── .storybook/                     # Storybook configuration
├── dist/                           # NPM build output (gitignored)
├── storybook-static/              # Storybook build output (gitignored)
├── public/                         # Static assets (fonts, logos)
└── package.json

🎨 Design Principles

Pure Design System

• ✅ No backend logic or API integrations
• ✅ No business logic embedded
• ✅ Mock data for demonstrations only
• ✅ HeroUI as the foundational layer

Best Practices

• ✅ Composition over component creation
• ✅ Strict TypeScript for type safety
• ✅ Accessibility-first approach
• ✅ Comprehensive documentation

🌐 Deployment

Branch Deployment Flow

This project uses branch-based deployments for design system environments:

• Merge to staging to deploy to the dev environment
  • http://ds.dev.veev.veevartapp.com/
• Merge to prod to deploy to the prod environment
  • http://ds.veevartapp.com/

Deploy Storybook to Vercel

npm run deploy-storybook

Deploy Storybook to Netlify

1. Build Storybook:

   npm run build-storybook

2. Drag & drop storybook-static/ to Netlify Drop

Publish to NPM

1. Update version:

   npm version patch  # or minor, major

2. Build library:

   npm run build

3. Publish:

   npm publish

🤝 Contributing

We welcome contributions! Please follow these guidelines:

1. Create a branch for your feature/fix
2. Follow the existing code style
3. Add/update Storybook stories for new components
4. Test your changes locally with npm run storybook
5. Submit a pull request

📄 License

© 2026 Veevart. All rights reserved.

🔗 Links

• NPM Package: @veevarts/design-system
• HeroUI Documentation: storybook.heroui.com
• Veevart Website: veevart.com

Built with ❤️ by the Veevart team