Skip to content

Commit 4e980f7

Browse files
themodernpkthemodernpk
authored
Merge pull request #281 from webreinvent/feature/doc-primevue-theming
Feature -> Develop | Primevue Theming Guide
2 parents f5971cc + cc8d523 commit 4e980f7

File tree

1 file changed

+206
-0
lines changed

1 file changed

+206
-0
lines changed

‎content/4.guide/7.primevue-theming-guide.md

Lines changed: 206 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,206 @@
1+
---
2+
toc: true
3+
title: PrimeVue Theming Guide
4+
---
5+
6+
## Introduction
7+
8+
This guide outlines a structured approach to applying theming in Vue and Nuxt apps using **CSS custom properties** alongside **Tailwind CSS** and **PrimeVue**. It helps ensure your application is both performant and maintainable with scalable light and dark modes.
9+
10+
📌 **Quick Installation Links**
11+
12+
- **[Install PrimeVue](https://primevue.org/nuxt){:target="_blank"}**
13+
14+
- **[Install Tailwind CSS](https://tailwindcss.nuxtjs.org/getting-started/installation){:target="_blank"}**
15+
16+
## 1. Tailwind Setup
17+
18+
Ensure your project includes Tailwind’s base setup:
19+
20+
```css
21+
@tailwind base;
22+
@tailwind components;
23+
@tailwind utilities;
24+
```
25+
26+
## 2. Adding Dark Mode Support
27+
28+
PrimeVue uses the `system` as the default `darkModeSelector` in theme configuration. If you have a dark mode switch in your application, set the `darkModeSelector` to the selector you utilize such as `.my-app-dark` in your nuxt config so that PrimeVue can fit in seamlessly with your color scheme.
29+
30+
```js
31+
import PrimeVue from 'primevue/config';
32+
import Aura from '@primeuix/themes/aura';
33+
34+
const nuxtConfig: NuxtConfig = {};
35+
36+
nuxtConfig.primevue = {
37+
options: {
38+
theme: {
39+
preset: Aura,
40+
options: {
41+
darkModeSelector: '.my-app-dark',
42+
}
43+
}
44+
}
45+
}
46+
```
47+
48+
In case you prefer to use dark mode all the time, apply the `darkModeSelector` initially and never change it.
49+
50+
```html
51+
<html class="my-app-dark">
52+
```
53+
54+
It is also possible to disable dark mode completely using `false` or `none` as the value of the selector.
55+
56+
```js
57+
theme: {
58+
preset: Aura,
59+
options: {
60+
darkModeSelector: false || 'none',
61+
}
62+
}
63+
```
64+
65+
## 3. Defining Light and Dark Themes
66+
67+
Use CSS custom properties (`--var-name`) inside `:root` for light theme and a custom class (e.g., `.my-app-dark`) for dark theme overrides. Add the theming vairables in your css file where tailwind is already setup.
68+
69+
70+
### Light Theme
71+
72+
```css
73+
:root {
74+
--pointer-x: 0;
75+
--pointer-y: 0;
76+
77+
/* Core Colors */
78+
--brand-primary: #501D71;
79+
--text-default: #000000;
80+
81+
/* Text Gradients */
82+
--text-gradient-start: #12DBFF;
83+
--text-gradient-end: #BA55FE;
84+
85+
/* Backgrounds */
86+
--surface-background: #EAEAEA;
87+
--element-background: #EAEAEA;
88+
--overlay-weak: #ffffff22;
89+
--brand-accent-dark: #360055;
90+
--card-background: #FAF5FF;
91+
--background-glow: #F6E9FF;
92+
93+
/* Gradients */
94+
--bg-circle-large: linear-gradient(160deg, rgba(255, 255, 255, 0) 30.43%, #ffffff88 54.53%, #ffffff 92.37%);
95+
--bg-circle-subtle: linear-gradient(291deg, #ffffff33 30.43%, #ffffff77 92.37%);
96+
--bg-circle-top-light: linear-gradient(157.91deg, rgba(255, 255, 255, 0) 9.32%, #ffffff55 86.78%);
97+
--bg-circle-highlight: linear-gradient(92.4deg, rgba(255, 255, 255, 0.5) 6.22%, rgba(245, 245, 245, 0.5) 93.78%);
98+
--bg-circle-spotlight: radial-gradient(62.25% 62.25% at 53.43% 51.39%, rgba(255, 255, 255, 0) 0%, #ffffff 100%);
99+
--bg-cms-card: linear-gradient(180deg,#B6A9FF 0%,#8564B3 100%);
100+
--border-cms-card: linear-gradient(180deg,#D3CBF7 0%,#7758AE 100%);
101+
}
102+
```
103+
104+
### Dark Theme
105+
106+
```css
107+
:root.my-app-dark {
108+
--pointer-x: 0;
109+
--pointer-y: 0;
110+
111+
/* Core Colors */
112+
--brand-primary: #AF66E4;
113+
--text-default: #ffffff;
114+
115+
/* Backgrounds */
116+
--surface-background: #190226;
117+
--element-background: #1F0035;
118+
--overlay-weak: #26004988;
119+
--brand-accent-dark: #360055;
120+
--card-background: #08000E;
121+
--background-glow: #22206D;
122+
123+
/* Gradients */
124+
--bg-circle-large: linear-gradient(136.28deg, rgba(51, 4, 79, 0) 30.43%, #26004988 54.53%, #360055 92.37%);
125+
--bg-circle-subtle: radial-gradient(62.25% 62.25% at 53.43% 51.39%, rgba(42, 1, 73, 0) 0%, #0B001344 100%);
126+
--bg-circle-top-light: linear-gradient(0.91deg, rgba(51, 4, 79, 0) 9.32%, #36006F 86.78%);
127+
--bg-circle-highlight: linear-gradient(93.26deg, rgba(18, 2, 44, 0.7) 55.39%, rgba(57, 14, 95, 0.7) 96.74%);
128+
--bg-circle-spotlight: radial-gradient(62.25% 62.25% at 53.43% 51.39%, rgba(42, 1, 73, 0) 0%, #0B0013 100%);
129+
--bg-cms-card: linear-gradient(180deg,#1C173A 0%,#0D0C28 100%);
130+
--border-cms-card: linear-gradient(180deg,#433B6A 0%,#211D52 100%);
131+
}
132+
```
133+
134+
---
135+
136+
## 3. Using CSS Variables with Tailwind CSS
137+
138+
While Tailwind doesn’t directly support variables in all utilities, **arbitrary values** allow us to use CSS variables in most cases:
139+
140+
### Practical Examples
141+
142+
```html
143+
<!-- Background from CSS variable -->
144+
<div class="bg-[var(--color-5)]"></div>
145+
146+
<!-- Gradient Background from CSS variable -->
147+
<div class="bg-[image:var(--bg-circle-subtle)]"></div>
148+
149+
<!-- Text color -->
150+
<p class="text-[var(--primary)]"></p>
151+
152+
<!-- Border color -->
153+
<div class="border border-[var(--color-3)]"></div>
154+
155+
<!-- Box Shadow (if defined in a class or via @layer) -->
156+
<div class="shadow-[var(--custom-shadow)]"></div>
157+
```
158+
159+
> ⚠️ Gradients and background images must be applied using `bg-[image:var(--bg-circle-subtle)]` to render properly.
160+
161+
## 4. Switching Between Light and Dark Themes
162+
163+
Following is a very basic example implementation of a dark mode switch, you may extend it further by involving `prefers-color-scheme` to retrieve it from the system initially and use `localStorage` to make it stateful. See this [article](https://dev.to/abbeyperini/dark-mode-toggle-and-prefers-color-scheme-4f3m){:target="_blank"} for more information.
164+
165+
Use class toggling on the `html` or `body` tag to switch between light and dark themes.
166+
167+
```js
168+
function toggleDarkMode() {
169+
document.documentElement.classList.toggle('my-app-dark');
170+
}
171+
```
172+
173+
```html
174+
<Button label="Toggle Dark Mode" @click="toggleDarkMode()" />
175+
```
176+
177+
## 5. Naming Best Practices
178+
179+
To keep your styles scalable:
180+
181+
* ✅ Prefer semantic names like `--surface-background`, `--brand-accent`, `--overlay-weak`, etc.
182+
* ❌ Avoid non-descriptive names like `--color-1`, `--gradient-1`, etc.
183+
184+
| Old Name | Suggested Semantic Name |
185+
| -------------- | ----------------------- |
186+
| `--color-1` | `--surface-background` |
187+
| `--color-2` | `--element-background` |
188+
| `--color-3` | `--overlay-weak` |
189+
| `--color-4` | `--brand-accent-dark` |
190+
| `--color-5` | `--card-background` |
191+
| `--gradient-1` | `--bg-circle-large` |
192+
| `--gradient-2` | `--bg-circle-subtle` |
193+
| `--gradient-3` | `--bg-circle-top-light` |
194+
| `--gradient-4` | `--bg-circle-highlight` |
195+
| `--gradient-5` | `--bg-circle-spotlight` |
196+
197+
---
198+
199+
## Final Notes
200+
201+
* Use variables for colors, backgrounds, gradients, and even shadows.
202+
* Combine Tailwind's arbitrary values with semantic CSS variables.
203+
* Maintain consistent naming across light/dark modes.
204+
* Document each variable clearly to help future developers.
205+
206+
A scalable theming approach will improve maintainability, accessibility, and performance across your Vue or Nuxt projects.

0 commit comments

Comments
 (0)