Setup Tailwind
Importazione CSS
Il primo passo per integrare la libreria è importare il suo foglio di stile compilato. Contiene tutti gli stili dei componenti, le custom properties del tema e le definizioni dei CSS layers.
In main.ts:
import '@pzeta/vue-components/style.css'
::: warning L'import del CSS deve precedere qualsiasi altro foglio di stile personalizzato, così le tue utility Tailwind possono sovrascrivere le proprietà della libreria dove necessario. :::
Integrazione con Tailwind CSS 4
Tailwind CSS 4 usa @tailwindcss/vite come plugin Vite. La libreria è già configurata per funzionare con questo approccio.
Configurazione vite.config.ts
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'
import tailwindcss from '@tailwindcss/vite'
export default defineConfig({
plugins: [
vue(),
tailwindcss(),
],
})
File CSS principale del progetto
Nel tuo src/assets/main.css (o equivalente), importa Tailwind e aggiungi la libreria come source aggiuntiva in modo che Tailwind scansioni le sue classi durante la build:
@import 'tailwindcss';
/* Permette a Tailwind di scannerizzare i componenti della libreria */
@source "../node_modules/@pzeta/vue-components/dist/pzeta-vue-components.es.js";
::: note
La direttiva @source è necessaria perché la libreria è pre-compilata in node_modules. Senza di essa, le classi Tailwind usate internamente dai componenti potrebbero essere rimosse dal PurgeCSS durante la build di produzione.
:::
CSS Custom Properties del tema
La libreria espone un sistema completo di custom properties Tailwind 4 tramite @theme. Queste variabili definiscono la palette semantica dell'applicazione.
Colori semantici disponibili
/* Colori brand */
--color-primary-{50..950} /* Blue — azioni primarie */
--color-secondary-{50..950} /* Slate — elementi secondari */
/* Colori stato */
--color-success-{50..950} /* Green */
--color-info-{50..950} /* Cyan */
--color-warn-{50..950} /* Amber */
--color-danger-{50..950} /* Red */
--color-help-{50..950} /* Purple */
--color-contrast-{50..950} /* Zinc */
/* Superfici (light mode) */
--color-background /* slate-50 — sfondo app */
--color-surface /* white — superfici primarie */
--color-surface-secondary /* gray-50 — sotto-superfici */
--color-surface-hover /* gray-100 — hover states */
/* Testo */
--color-text /* gray-900 — testo principale */
--color-text-secondary /* gray-500 — testo secondario */
--color-text-muted /* gray-400 — testo attenuato */
--color-label /* gray-700 — etichette form */
Override del tema primario
Per cambiare il colore primario dell'applicazione, sovrascrivi le variabili nel tuo CSS dopo l'import della libreria:
@import 'tailwindcss';
@import '@pzeta/vue-components/style.css';
/* Tema primario personalizzato — viola */
@theme {
--color-primary-50: #faf5ff;
--color-primary-100: #f3e8ff;
--color-primary-200: #e9d5ff;
--color-primary-300: #d8b4fe;
--color-primary-400: #c084fc;
--color-primary-500: #a855f7;
--color-primary-600: #9333ea;
--color-primary-700: #7e22ce;
--color-primary-800: #6b21a8;
--color-primary-900: #581c87;
--color-primary-950: #3b0764;
}
In alternativa, usa il composable useThemeColors per cambiare il tema primario a runtime scegliendo tra i preset inclusi:
<script setup lang="ts">
import { useThemeColors, primaryColorPresets } from '@pzeta/vue-components'
const { applyPreset } = useThemeColors()
// Disponibili: 'blue', 'violet', 'green', 'orange', 'red', 'teal', ecc.
applyPreset('violet')
</script>
Dark mode
La libreria gestisce il dark mode tramite la classe CSS .dark sull'elemento radice (html o body). La custom variant è definita come:
@custom-variant dark (&:where(.dark, .dark *));
Per attivare il dark mode, aggiungi la classe .dark all'elemento html:
// Attiva dark mode
document.documentElement.classList.add('dark')
// Disattiva dark mode
document.documentElement.classList.remove('dark')
// Toggle
document.documentElement.classList.toggle('dark')
Variabili dark mode
In dark mode le seguenti variabili vengono sovrascritte automaticamente dalla libreria:
.dark {
--color-surface: #1f2937; /* gray-800 */
--color-surface-secondary: #111827; /* gray-900 */
--color-surface-hover: #374151; /* gray-700 */
--color-background: #0f172a; /* slate-900 */
--color-text: #f9fafb; /* gray-50 */
--color-text-secondary: #9ca3af; /* gray-400 */
--color-text-muted: #6b7280; /* gray-500 */
--color-label: #e5e7eb; /* gray-200 */
}
Puoi estendere gli override dark nel tuo CSS aggiungendo ulteriori variabili sotto .dark.
CSS Layers
La libreria usa CSS layers Tailwind 4 per garantire la corretta cascata degli stili:
@layer tailwind-base, tailwind-utilities;
Gli stili dei componenti sono scritti con classi Tailwind utility-first. Questo significa che qualsiasi classe Tailwind nel tuo template ha precedenza sugli stili base dei componenti senza bisogno di !important.
Icon font setup
La libreria normalizza le dimensioni visive dei diversi icon set tramite @layer base:
/* Lucide icons */
[class^='icon-'],
[class*=' icon-'] {
font-size-adjust: 0.7;
display: inline-block;
line-height: 1;
vertical-align: middle;
}
/* FontAwesome icons */
.fa-solid, .fa-regular, .fa-brands {
font-size-adjust: 0.8;
}
Queste regole sono già incluse nel style.css della libreria. Non è necessario aggiungere nulla.