hb-vue-theme

v1.0.8

Published

7 months ago

Custom PrimeVue 4 theme with 'hb' prefix using design tokens and PrimeFlex

0High
0Medium
0Low

garp360

vue primevue theme design-tokens primeflex css-variables ui-components vue3

HB Vue Theme - PrimeVue 4 Design Token System

A custom theme for PrimeVue 4 using the new Design Token System and PrimeFlex utilities. This theme demonstrates how to create installable presets that can be easily integrated into any Vue 3 + PrimeVue 4 project.

🚀 Features

PrimeVue 4 Design Tokens: Uses the new design token system for consistent theming
PrimeFlex Integration: Custom utility classes built on top of PrimeFlex
Installable Preset: Easy installation in any Vue 3 + PrimeVue 4 project
Custom Prefix: Uses 'hb' prefix for all components and utilities
Comprehensive Design System: Complete color palette, typography, spacing, and component tokens
TypeScript Support: Full TypeScript support for design tokens
Responsive Design: Mobile-first responsive design system

📦 Installation

1. Install Dependencies

npm install primevue@^4.0.0 primeflex@^3.3.1 primeicons@^6.0.0

2. Install HB Theme

npm install hb-vue-theme

3. Setup in Your Vue App

Option A: Using the Published Library (Recommended)

This is the exact configuration used in the demo app:

// In your main.js
import { createApp } from 'vue'
import PrimeVue from 'primevue/config'
import Tooltip from 'primevue/tooltip'

// Import our published theme library
import { HBThemePlugin, passthroughConfig } from 'hb-vue-theme'

// Import PrimeFlex for utility classes
import 'primeflex/primeflex.css'

// Import PrimeIcons
import 'primeicons/primeicons.css'

// Import our published theme CSS (choose one method below)
import 'hb-vue-theme/css'  // Method 1: Direct import (works with Vite/Webpack)
// OR
import 'hb-vue-theme/dist/theme.css'  // Method 2: Direct path import
// OR
import 'hb-vue-theme/scss'  // Method 3: SCSS import (if using SCSS)

// Import our main App component
import App from './App.vue'

// Create Vue app
const app = createApp(App)

// Configure PrimeVue with unstyled mode and PassThrough
app.use(PrimeVue, {
  // Use unstyled mode to completely replace CSS classes
  unstyled: true,
  
  // Configure component prefix
  prefix: 'hb',
  
  // Enable ripple effects
  ripple: true,
  
  // Configure input styles
  inputStyle: 'filled',
  
  // PassThrough configuration to map our custom classes
  pt: passthroughConfig
})

// Install our custom theme
app.use(HBThemePlugin, {
  autoInstall: true,
  force: false
})

// Register global directives
app.directive('tooltip', Tooltip)

// Mount the app
app.mount('#app')

Alternative CSS Import Methods:

If the direct CSS import doesn't work in your environment, you can use these alternatives:

HTML Link Tag (works in any environment):

<!-- In your index.html -->
<link rel="stylesheet" href="node_modules/hb-vue-theme/dist/theme.css">

Copy CSS to your project:

# Copy the CSS file to your public directory
cp node_modules/hb-vue-theme/dist/theme.css public/hb-theme.css

Then import it in your HTML:

<link rel="stylesheet" href="/hb-theme.css">

Import in your main CSS file:

/* In your main.css or App.vue style section */
@import 'hb-vue-theme/dist/theme.css';

Using the theme installer with CSS:

import { installHBTheme } from 'hb-vue-theme/preset'

// This will automatically inject the CSS
installHBTheme({
  autoInstall: true,
  injectCSS: true  // Automatically injects the CSS
})

Option B: Using Design Tokens Only

// Import just the design tokens
import { hbPreset } from 'hb-vue-theme/tokens'

// Apply tokens to document
Object.entries(hbPreset.tokens).forEach(([property, value]) => {
  document.documentElement.style.setProperty(property, value)
})

Option C: Using Preset Installer

// Import the preset installer
import { installHBTheme } from 'hb-vue-theme/preset'

// Install the theme
const theme = installHBTheme({
  autoInstall: true,
  customTokens: {
    // Add your custom tokens here
    '--hb-primary': '#your-custom-color'
  }
})

🎨 Design Token System

Color Tokens

The theme includes a comprehensive color system:

/* Primary Colors */
--hb-primary-50: #eff6ff;
--hb-primary-500: #3b82f6;
--hb-primary-900: #1e3a8a;

/* Semantic Colors */
--hb-success: #22c55e;
--hb-warning: #f59e0b;
--hb-danger: #ef4444;
--hb-info: #0ea5e9;

/* Text Colors */
--hb-text-primary: #171717;
--hb-text-secondary: #525252;
--hb-text-muted: #737373;

Typography Tokens

/* Font Families */
--hb-font-family-primary: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;

/* Font Sizes */
--hb-font-size-xs: 0.75rem;
--hb-font-size-base: 1rem;
--hb-font-size-2xl: 1.5rem;

/* Font Weights */
--hb-font-weight-normal: 400;
--hb-font-weight-medium: 500;
--hb-font-weight-bold: 700;

Spacing Tokens

/* Spacing Scale (4px grid) */
--hb-spacing-1: 0.25rem;
--hb-spacing-4: 1rem;
--hb-spacing-8: 2rem;
--hb-spacing-16: 4rem;

Component Tokens

/* Button Tokens */
--button-padding: var(--hb-spacing-3) var(--hb-spacing-4);
--button-border-radius: var(--hb-border-radius-md);
--button-font-weight: var(--hb-font-weight-medium);

/* Input Tokens */
--input-padding: var(--hb-spacing-3) var(--hb-spacing-4);
--input-border-radius: var(--hb-border-radius-md);
--input-border-color: var(--hb-border-medium);

🛠️ Usage

Using Design Tokens in Components

<template>
  <div class="custom-component">
    <h1 class="title">My Component</h1>
    <p class="description">Using design tokens</p>
  </div>
</template>

<style>
.custom-component {
  background-color: var(--hb-bg-primary);
  padding: var(--hb-spacing-6);
  border-radius: var(--hb-border-radius-lg);
}

.title {
  font-size: var(--hb-font-size-2xl);
  font-weight: var(--hb-font-weight-bold);
  color: var(--hb-text-primary);
  margin-bottom: var(--hb-spacing-4);
}

.description {
  font-size: var(--hb-font-size-base);
  color: var(--hb-text-secondary);
  line-height: var(--hb-line-height-relaxed);
}
</style>

Using PrimeFlex Utilities

<template>
  <div class="hb-p-6 hb-bg-primary hb-rounded-lg hb-shadow-md">
    <h2 class="hb-text-primary hb-font-bold hb-mb-4">Card Title</h2>
    <p class="hb-text-secondary">Card content using PrimeFlex utilities</p>
  </div>
</template>

Using PassThrough Configuration

The theme includes a comprehensive PassThrough configuration that maps PrimeVue's internal component structure to our custom hb- prefixed classes. This ensures complete control over styling while maintaining the same component structure.

Basic Usage

// In your main.js
import { createApp } from 'vue'
import PrimeVue from 'primevue/config'
import { passthroughConfig } from '@hb-vue/theme'

const app = createApp(App)

app.use(PrimeVue, {
  unstyled: true,
  prefix: 'hb',
  pt: passthroughConfig
})

app.mount('#app')

Customizing PassThrough Configuration

import { passthroughConfig, mergePassthroughConfig } from '@hb-vue/theme'

// Merge with custom configuration
const customPassthrough = mergePassthroughConfig({
  button: {
    root: { class: 'my-custom-button' },
    label: { class: 'my-custom-button-label' }
  }
})

app.use(PrimeVue, {
  unstyled: true,
  prefix: 'hb',
  pt: customPassthrough
})

Using Specific Component Configurations

import { getPassthroughConfig } from '@hb-vue/theme'

// Get configuration for specific components only
const datatableConfig = getPassthroughConfig(['datatable', 'column'])

app.use(PrimeVue, {
  unstyled: true,
  prefix: 'hb',
  pt: datatableConfig
})

Available PassThrough Mappings

The PassThrough configuration includes mappings for all major PrimeVue components:

DataTable: datatable, column
Form Components: button, inputtext, select, inputnumber, checkbox, radiobutton, textarea, password, multiselect
Layout Components: panel, card, divider
Overlay Components: dialog, overlaypanel, sidebar, tooltip
Navigation Components: menu, tabview, accordion
Data Display: message, toast, confirmdialog
File Upload: fileupload
Input Components: rating, slider, togglebutton, tristatecheckbox
Tree Components: tree, treetable

Customizing the Theme

// Create a custom preset
import { createCustomPreset } from './preset-installer.js'

const customPreset = createCustomPreset({
  // Custom color tokens
  '--hb-primary': '#6366f1',
  '--hb-secondary': '#8b5cf6',
  
  // Custom spacing
  '--hb-spacing-custom': '3rem',
  
  // Custom component tokens
  '--button-border-radius': '1rem'
}, {
  // Custom PrimeFlex utilities
  'hb-custom-utility': 'background: linear-gradient(45deg, #6366f1, #8b5cf6)'
})

// Install custom preset
installHBTheme({
  customTokens: customPreset.tokens,
  customUtilities: customPreset.utilities
})

📁 Project Structure

hbvue-theme-1/
├── src/
│   ├── styles/
│   │   ├── design-tokens.js          # Design token definitions
│   │   ├── theme-installer.js        # Theme installer for Vue
│   │   └── variables.scss            # Legacy SASS variables
│   ├── components/
│   │   └── DataTableDemo.vue         # Example component
│   ├── App.vue                       # Main app component
│   └── main.js                       # App entry point
├── preset-installer.js               # Standalone preset installer
├── package.json                      # Dependencies
└── README.md                         # This file

🔧 Configuration

PrimeVue Configuration

app.use(PrimeVue, {
  // Enable design tokens
  designTokens: true,
  
  // Set component prefix
  prefix: 'hb',
  
  // Enable ripple effects
  ripple: true,
  
  // Configure input styles
  inputStyle: 'filled'
})

Vite Configuration

// vite.config.js
export default {
  css: {
    preprocessorOptions: {
      scss: {
        additionalData: `@import "./src/styles/variables.scss";`
      }
    }
  }
}

🎯 Available Utilities

Spacing Utilities

.hb-p-1, .hb-p-2, .hb-p-3, .hb-p-4, .hb-p-5, .hb-p-6  /* Padding */
.hb-m-1, .hb-m-2, .hb-m-3, .hb-m-4, .hb-m-5, .hb-m-6  /* Margin */

Color Utilities

.hb-text-primary, .hb-text-secondary, .hb-text-muted    /* Text colors */
.hb-bg-primary, .hb-bg-secondary, .hb-bg-tertiary       /* Background colors */

Border Radius Utilities

.hb-rounded-sm, .hb-rounded, .hb-rounded-md, .hb-rounded-lg, .hb-rounded-xl, .hb-rounded-full

Shadow Utilities

.hb-shadow-sm, .hb-shadow, .hb-shadow-md, .hb-shadow-lg, .hb-shadow-xl

🔄 Theme Management

Getting Theme Information

// Get theme info
const themeInfo = theme.getInfo()
console.log(themeInfo)
// {
//   name: 'hb-theme',
//   version: '1.0.0',
//   isInstalled: true,
//   tokenCount: 150,
//   utilityCount: 25
// }

Updating Theme

// Update specific tokens
theme.update({
  '--hb-primary': '#new-color',
  '--hb-spacing-4': '1.5rem'
})

Uninstalling Theme

// Remove theme completely
theme.uninstall()

📤 Exporting Themes

Export as CSS Variables

import { exportAsCSS } from './preset-installer.js'

const cssVariables = exportAsCSS()
console.log(cssVariables)
// :root {
//   --hb-primary-50: #eff6ff;
//   --hb-primary-500: #3b82f6;
//   ...
// }

Export as SCSS Variables

import { exportAsSCSS } from './preset-installer.js'

const scssVariables = exportAsSCSS()
console.log(scssVariables)
// $hb-primary-50: #eff6ff;
// $hb-primary-500: #3b82f6;
// ...

🚀 Quick Start

Clone the repository

git clone <repository-url>
cd hbvue-theme-1

Install dependencies
```
npm install
```
Start development server
```
npm run dev
```
View the demo Open http://localhost:5173 to see the themed DataTable component.

🤝 Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

PrimeVue for the excellent component library
PrimeFlex for the utility-first CSS framework
Vue.js for the progressive JavaScript framework

📞 Support

For support and questions:

Create an issue in the repository
Check the PrimeVue documentation
Review the Vue.js documentation

Built with ❤️ using Vue 3, PrimeVue 4, and Design Tokens