diff --git a/content/4.guide/6.theming-guide/1.introduction.md b/content/4.guide/6.theming-guide/1.introduction.md new file mode 100644 index 00000000..eee89e45 --- /dev/null +++ b/content/4.guide/6.theming-guide/1.introduction.md @@ -0,0 +1,75 @@ +--- +toc: true +title: Theming Guide +--- +## Theming in Nuxt + +This document explains how to set up and manage **theming in Nuxt 3**, including: + +- Defining **brand colors** and **semantic colors** (primary, secondary, etc.) +- Structuring **theme tokens** for consistency +- Theming with **Tailwind CSS** and **PrimeVue** +- (Optional) Supporting light/dark mode and multiple themes + +--- + +## 1. What is Theming? + +**Theming** is the process of defining a consistent visual identity for your application. + +It usually includes: + +- 🟡 Defining **brand colors** (e.g., your company's primary palette) +- 🟢 Defining **semantic colors** (e.g., success, warning, error) +- 🔵 Applying these colors globally in UI components +- ⚫ Optionally enabling **light/dark** or multiple theme variants + +--- + +## 2. Options for Theming in Nuxt + +You can manage themes in Nuxt using: + +1. **Tailwind CSS** – Define colors in `tailwind.config.js` and use utility classes +2. **PrimeVue** – Use built-in themes or create custom theme overrides +3. **CSS variables** – For flexible, runtime theme switching + +--- + +## 3. Defining Brand & Semantic Colors (Base Layer) + +Even before Tailwind or PrimeVue, define your **color tokens** clearly. + +### Example color tokens: + +Brand colors: + +- `Primary`: #1D4ED8 + +- `Secondary`: #9333EA + +- `Accent`: #F59E0B + +Semantic colors: + +- `Success`: #10B981 + +- `Warning`: #F59E0B + +- `Error`: #EF4444 + +- `Info`: #3B82F6 + + +These tokens can be used across Tailwind and PrimeVue themes to keep the system **consistent**. + +--- + +## Final Notes + +* Use variables for colors, backgrounds, gradients, and even shadows. +* Combine Tailwind's arbitrary values with semantic CSS variables. +* Maintain consistent naming across light/dark modes. +* Document each variable clearly to help future developers. + +A scalable theming approach will improve maintainability, accessibility, and performance across your Vue or Nuxt projects. diff --git a/content/4.guide/6.theming-guide/2.nuxt-with-tailwind.md b/content/4.guide/6.theming-guide/2.nuxt-with-tailwind.md new file mode 100644 index 00000000..f6415d9e --- /dev/null +++ b/content/4.guide/6.theming-guide/2.nuxt-with-tailwind.md @@ -0,0 +1,131 @@ +--- +toc: true +title: Nuxt with Tailwind +--- + +## Tailwind Installation + +Using Tailwind CSS in your Nuxt project is only one command away. + +#### 1. Install `@nuxtjs/tailwindcss` dependency to your project: + +``` +npx nuxi@latest module add tailwindcss +``` +#### 2. If not already done, add it to your modules section in your nuxt.config: + +``` +export default defineNuxtConfig({ + modules: ['@nuxtjs/tailwindcss'] +}) +``` + +### Tailwind Files + +When running your Nuxt project, this module will look for these files: + +- `./assets/css/tailwind.css` +- `./tailwind.config.{js,cjs,mjs,ts}` + +If these files don't exist, the module will automatically generate a basic configuration for them, so you don't have to create these files manually. + +You can create the `tailwind.config.js` file by running the following command, as noted by the Tailwind CSS installation guide: + +``` +npx tailwindcss init +``` + +If the above fails, you can try `npx tailwindcss-cli init`. + +If you're going to create your own CSS file for Tailwind CSS, make sure to add the @tailwind directives: + +```css +@tailwind base; +@tailwind components; +@tailwind utilities; +``` + +### Module Configuration + +You can customize the module's behavior by using the tailwindcss property in nuxt.config: + +```js +export default defineNuxtConfig({ + modules: ['@nuxtjs/tailwindcss'], + tailwindcss: { + // Options + } +}) +``` + + +## Theming with Tailwind CSS + +### Step 1: Define Colors in Tailwind + +Edit `tailwind.config.js`: + +```js +export default { + darkMode: 'class', + theme: { + extend: { + colors: { + // Brand colors + brand: { + primary: '#1D4ED8', + secondary: '#9333EA', + accent: '#F59E0B' + }, + + // Semantic colors + semantic: { + success: '#10B981', + warning: '#F59E0B', + error: '#EF4444', + info: '#3B82F6' + } + } + } + } +} +``` + +✅ Now you can use these colors anywhere: + +```html + +
Success message
+``` + +### Step 2: (Optional) Use CSS Variables for Multiple Themes + +If you want multiple themes (e.g., light, dark, blue), define variables in a global CSS file. + +`assets/css/theme.css:` + +```css +:root { + --color-primary: #1D4ED8; + --color-secondary: #9333EA; + --color-bg: #ffffff; + --color-text: #000000; +} + +[data-theme="dark"] { + --color-primary: #60A5FA; + --color-secondary: #C084FC; + --color-bg: #0F172A; + --color-text: #ffffff; +} +``` + +Use in components: + +```html + +``` + +Or register these CSS variables as Tailwind colors if you prefer utility classes. diff --git a/content/4.guide/9.primevue-theming-guide.md b/content/4.guide/6.theming-guide/3.nuxt-with-primevue.md similarity index 89% rename from content/4.guide/9.primevue-theming-guide.md rename to content/4.guide/6.theming-guide/3.nuxt-with-primevue.md index 699a2f65..47caf704 100644 --- a/content/4.guide/9.primevue-theming-guide.md +++ b/content/4.guide/6.theming-guide/3.nuxt-with-primevue.md @@ -1,9 +1,9 @@ --- toc: true -title: PrimeVue Theming Guide +title: Nuxt with Primevue --- -## Introduction +## Theming with PrimeVue 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. @@ -13,7 +13,7 @@ This guide outlines a structured approach to applying theming in Vue and Nuxt ap - **[Install Tailwind CSS](https://tailwindcss.nuxtjs.org/getting-started/installation){:target="_blank"}** -## 1. Tailwind Setup +### 1. Tailwind Setup Ensure your project includes Tailwind’s base setup: @@ -23,7 +23,7 @@ Ensure your project includes Tailwind’s base setup: @tailwind utilities; ``` -## 2. Adding Dark Mode Support +### 2. Adding Dark Mode Support 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. @@ -62,12 +62,12 @@ theme: { } ``` -## 3. Defining Light and Dark Themes +### 3. Defining Light and Dark Themes 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. -### Light Theme +#### Light Theme ```css :root { @@ -101,7 +101,7 @@ Use CSS custom properties (`--var-name`) inside `:root` for light theme and a cu } ``` -### Dark Theme +#### Dark Theme ```css :root.my-app-dark { @@ -133,11 +133,11 @@ Use CSS custom properties (`--var-name`) inside `:root` for light theme and a cu --- -## 3. Using CSS Variables with Tailwind CSS +### 3. Using CSS Variables with Tailwind CSS While Tailwind doesn’t directly support variables in all utilities, **arbitrary values** allow us to use CSS variables in most cases: -### Practical Examples +#### Practical Examples ```html @@ -158,7 +158,7 @@ While Tailwind doesn’t directly support variables in all utilities, **arbitrar > ⚠️ Gradients and background images must be applied using `bg-[image:var(--bg-circle-subtle)]` to render properly. -## 4. Switching Between Light and Dark Themes +### 4. Switching Between Light and Dark Themes 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. @@ -174,7 +174,7 @@ function toggleDarkMode() {