Add CSS layer docs

assets/menu/menu.json

@@ -14,13 +14,11 @@
                 },
                 {
                     "name": "Nuxt",
-                    "to": "/nuxt",
+                    "to": "/nuxt"
-                    "badge": "NEW"
                 },
                 {
                     "name": "Playground",
-                    "to": "/playground",
+                    "to": "/playground"
-                    "badge": "NEW"
                 }
             ]
         },
@@ -522,14 +520,23 @@
             "href": "https://blocks.primevue.org"
         },
         {
-            "name": "PrimeFlex CSS",
+            "name": "Guides",
-            "icon": "pi pi-table",
+            "icon": "pi pi-book",
-            "href": "https://primeflex.org"
+            "children": [
-        },
+                {
-        {
+                    "name": "Accessibility",
-            "name": "Accessibility",
+                    "to": "/guides/accessibility"
-            "icon": "pi pi-users",
+                },
-            "to": "/accessibility"
+                {
+                    "name": "CSS Layer",
+                    "to": "/guides/csslayer"
+                },
+                {
+                    "name": "PrimeTV",
+                    "icon": "pi pi-youtube",
+                    "href": "https://www.youtube.com/channel/UCTgmp69aBOlLnPEqlUyetWw"
+                }
+            ]
         },
         {
             "name": "Support",
@@ -549,11 +556,6 @@
                 }
             ]
         },
-        {
-            "name": "PrimeTV",
-            "icon": "pi pi-youtube",
-            "href": "https://www.youtube.com/channel/UCTgmp69aBOlLnPEqlUyetWw"
-        },
         {
             "name": "Discover",
             "icon": "pi pi-search",
@@ -589,6 +591,11 @@
                 {
                     "name": "PrimeGear",
                     "href": "https://gear.primefaces.org"
+                },
+                {
+                    "name": "PrimeFlex CSS",
+                    "icon": "pi pi-table",
+                    "href": "https://primeflex.org"
                 }
             ]
         }

doc/guides/csslayer/BootstrapDoc.vue

@@ -0,0 +1,23 @@
+<template>
+    <DocSectionText v-bind="$attrs">
+        <p>Bootstrap has a <i>reboot</i> utility to reset the CSS of the standard elements. If you are including this utility, you may give it a layer while importing it.</p>
+        <DocSectionCode :code="code" />
+    </DocSectionText>
+</template>
+
+<script>
+export default {
+    data() {
+        return {
+            checked: false,
+            code: {
+                basic: `
+@layer bootstrap-reboot, primevue;
+
+@import "bootstrap-reboot.css" layer(bootstrap-rebooot);
+`
+            }
+        };
+    }
+};
+</script>

doc/guides/csslayer/NormalizeDoc.vue

@@ -0,0 +1,23 @@
+<template>
+    <DocSectionText v-bind="$attrs">
+        <p>Normalize is another utility to reset CSS of the standard elements. While importing the CSS file, assign it to a layer and define the layer order with primevue coming after the normalized layer.</p>
+        <DocSectionCode :code="code" />
+    </DocSectionText>
+</template>
+
+<script>
+export default {
+    data() {
+        return {
+            checked: false,
+            code: {
+                basic: `
+@layer normalize, primevue;
+
+@import "normalize.css" layer(normalize-reset);
+`
+            }
+        };
+    }
+};
+</script>

doc/guides/csslayer/ResetDoc.vue

@@ -0,0 +1,45 @@
+<template>
+    <DocSectionText v-bind="$attrs">
+        <p>
+            Ease of customization may present an issue if you have global styles on HTML elements like inputs and buttons that are also utilized by PrimeVue because global styles with a broader scope e.g. <i>button { }</i> and no layer always
+            override the PrimeVue components leading to unexpected results. A common use case for global styles applying to standard HTML elements is CSS reset utilities to remove the default styling of the browsers. In this case, best practice is
+            wrapping your CSS in a layer like <i>reset</i> and make sure <i>primevue</i> comes after your layer since layers defined after has higher precedence. This way, your Reset CSS does not get in the way of PrimeVue components.
+        </p>
+        <DocSectionCode :code="code" />
+        <p>If you are using Nuxt, use the built-in <i>cssLayerOrder</i> property of the PrimeVue nuxt module instead.</p>
+    </DocSectionText>
+</template>
+
+<script>
+export default {
+    data() {
+        return {
+            checked: false,
+            code: {
+                basic: `
+/* Order */
+@layer reset, primevue;
+
+/* Reset CSS */
+@layer reset {
+    button,
+    input {
+        /* CSS to Reset */
+    }
+}
+`
+            }
+        };
+    }
+};
+</script>
+
+<style>
+.my-switch-slider {
+    border-radius: 0;
+}
+
+.my-switch-slider:before {
+    border-radius: 0;
+}
+</style>

doc/guides/csslayer/SpecificityDoc.vue

@@ -0,0 +1,63 @@
+<template>
+    <DocSectionText v-bind="$attrs">
+        <p class="notification">A CSS layer is utilized in styled mode only, in unstyled mode the built-in CSS classes are not included and as a result no layer is defined. This documentation only applies to styled mode.</p>
+        <p>
+            The <i>@layer</i> is a standard CSS feature to define cascade layers for a customizable order of precedence. If you need to become more familiar with layers, visit the documentation at
+            <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/@layer">MDN</a> to begin with. In styled mode, PrimeVue wraps the built-in style classes under the <i>primevue</i> cascade layer to make the library styles easy to override. CSS in
+            your app without a layer has the highest CSS specificity, so you'll be able to override styles regardless of the location or how strong a class is written.
+        </p>
+        <p>
+            For example, let's assume you need to remove the rounded borders of the InputSwitch component defined by the theme in use. In order to achieve this, <i>.p-inputswitch .p-inputswitch-slider</i> selector needs to be overriden. Without the
+            layers, we'd have to write a stronger css or use <i>!important</i> however, with layers, this does not present an issue as your CSS can always override PrimeVue with a more straightforward class name such as <i>my-switch-slider</i>.
+            Another advantage of this approach is that it does not force you to figure out the built-in class names of the components.
+        </p>
+        <div class="card flex justify-content-center">
+            <InputSwitch v-model="checked" :pt="{ slider: 'my-switch-slider' }" />
+        </div>
+        <DocSectionCode :code="code" />
+        <p>Layers also make it possible to use CSS Modules, view the <NuxtLink to="/theming/#cssmodules">CSS Modules</NuxtLink> guide for examples.</p>
+    </DocSectionText>
+</template>
+
+<script>
+export default {
+    data() {
+        return {
+            checked: false,
+            code: {
+                basic: `
+<template>
+    <InputSwitch v-model="checked" :pt="{ slider: 'my-switch-slider' }" />
+</template>
+
+<script>
+import { ref } from "vue";
+
+const checked = ref(false);
+<\/script>
+
+<style>
+.my-switch-slider {
+    border-radius: 0;
+}
+
+.my-switch-slider:before {
+    border-radius: 0;
+}
+</style>
+`
+            }
+        };
+    }
+};
+</script>
+
+<style>
+.my-switch-slider {
+    border-radius: 0;
+}
+
+.my-switch-slider:before {
+    border-radius: 0;
+}
+</style>

doc/guides/csslayer/TailwindDoc.vue

@@ -0,0 +1,33 @@
+<template>
+    <DocSectionText v-bind="$attrs">
+        <p>
+            Tailwind CSS includes a reset utility in base called <a href="https://tailwindcss.com/docs/preflight" target="_blank" rel="noopener noreferrer">preflight</a>. If you are using this feature, wrap the base and utilities in separate layers
+            and make sure primevue layer comes after the base.
+        </p>
+        <DocSectionCode :code="code" />
+    </DocSectionText>
+</template>
+
+<script>
+export default {
+    data() {
+        return {
+            checked: false,
+            code: {
+                basic: `
+@layer tailwind-base, primevue, tailwind-utilities;
+
+@layer tailwind-base {
+  @tailwind base;
+}
+
+@layer tailwind-utilities {
+  @tailwind components;
+  @tailwind utilities;
+}
+`
+            }
+        };
+    }
+};
+</script>

doc/installation/StyledModeDoc.vue

@@ -4,7 +4,13 @@
             Styled mode is based on pre-skinned components with opinionated themes like Material, Bootstrap or PrimeOne themes. Theme is the required css file to be imported, visit the
             <NuxtLink to="/theming/#themes">Themes</NuxtLink> section for the complete list of available themes to choose from.
         </p>
-        <DocSectionCode :code="code" hideToggleCode importCode hideCodeSandbox hideStackBlitz />
+        <DocSectionCode :code="code1" hideToggleCode importCode hideCodeSandbox hideStackBlitz />
+        <p>
+            The classes of PrimeVue is defined under the <i>primevue</i> CSS layer to be easier to customize by having low specificity. If you are using a CSS library that styles default HTML elements such as Tailwind Preflight, Bootstrap, Normalize
+            or similar a custom CSS layer configuration might be necessary. Note that this only applies to Styled Mode as Unstyled Mode does not use any default styles or layers. Here is an example with Tailwind, visit the
+            <NuxtLink to="/guides/csslayer">CSS Layer</NuxtLink> for more information.
+        </p>
+        <DocSectionCode :code="code2" hideToggleCode importCode hideCodeSandbox hideStackBlitz />
     </DocSectionText>
 </template>
 
@@ -12,8 +18,22 @@
 export default {
     data() {
         return {
-            code: {
+            code1: {
                 basic: "\nimport 'primevue/resources/themes/lara-light-green/theme.css'\n"
+            },
+            code2: {
+                basic: `
+@layer tailwind-base, primereact, tailwind-utilities;
+
+@layer tailwind-base {
+  @tailwind base;
+}
+
+@layer tailwind-utilities {
+  @tailwind components;
+  @tailwind utilities;
+}
+`
             }
         };
     }

doc/nuxt/configuration/CSSLayerOrderDoc.vue

@@ -1,6 +1,6 @@
 <template>
     <DocSectionText v-bind="$attrs">
-        <p>Defines the CSS layer order setting for compatibility with libraries like Tailwind.</p>
+        <p>Defines the CSS layer order setting for compatibility with libraries like Tailwind and Bootstrap in styled mode. Visit the <NuxtLink to="/guides/csslayer">CSS Layer</NuxtLink> guide for detailed information.</p>
     </DocSectionText>
     <DocSectionCode :code="code1" importCode hideToggleCode hideCodeSandbox hideStackBlitz />
     <DocSectionCode :code="code2" importCode hideToggleCode hideCodeSandbox hideStackBlitz />

pages/guides/accessibility/index.vue

@@ -19,12 +19,12 @@
 </template>
 
 <script>
-import ColorsDoc from '@/doc/accessibility/ColorsDoc.vue';
+import ColorsDoc from '@/doc/guides/accessibility/ColorsDoc.vue';
-import FormControlsDoc from '@/doc/accessibility/FormControlsDoc.vue';
+import FormControlsDoc from '@/doc/guides/accessibility/FormControlsDoc.vue';
-import IntroductionDoc from '@/doc/accessibility/IntroductionDoc.vue';
+import IntroductionDoc from '@/doc/guides/accessibility/IntroductionDoc.vue';
-import SemanticHTMLDoc from '@/doc/accessibility/SemanticHTMLDoc.vue';
+import SemanticHTMLDoc from '@/doc/guides/accessibility/SemanticHTMLDoc.vue';
-import WAIAriaDoc from '@/doc/accessibility/WAIAriaDoc.vue';
+import WAIAriaDoc from '@/doc/guides/accessibility/WAIAriaDoc.vue';
-import WCAGDoc from '@/doc/accessibility/WCAGDoc.vue';
+import WCAGDoc from '@/doc/guides/accessibility/WCAGDoc.vue';
 
 export default {
     data() {

pages/guides/csslayer/index.vue

@@ -0,0 +1,68 @@
+<template>
+    <div>
+        <Head>
+            <Title>CSS Layer - PrimeVue</Title>
+            <Meta name="description" content="Best practices for the PrimeVue cascade layer in styled mode." />
+        </Head>
+
+        <div class="doc">
+            <div class="doc-main">
+                <div class="doc-intro">
+                    <h1>CSS Layer</h1>
+                    <p>Best practices for the PrimeVue cascade layer in styled mode.</p>
+                </div>
+                <DocSections :docs="docs" />
+            </div>
+            <DocSectionNav :docs="docs" />
+        </div>
+    </div>
+</template>
+
+<script>
+import BootstrapDoc from '@/doc/guides/csslayer/BootstrapDoc.vue';
+import NormalizeDoc from '@/doc/guides/csslayer/NormalizeDoc.vue';
+import ResetDoc from '@/doc/guides/csslayer/ResetDoc.vue';
+import SpecificityDoc from '@/doc/guides/csslayer/SpecificityDoc.vue';
+import TailwindDoc from '@/doc/guides/csslayer/TailwindDoc.vue';
+
+export default {
+    data() {
+        return {
+            docs: [
+                {
+                    id: 'css-specificity',
+                    label: 'CSS Specificity',
+                    component: SpecificityDoc
+                },
+                {
+                    id: 'reset',
+                    label: 'Reset',
+                    component: ResetDoc
+                },
+                {
+                    id: 'libraries',
+                    label: 'Libraries',
+                    description: 'Compatibility between PrimeVue and CSS libraries.',
+                    children: [
+                        {
+                            id: 'tailwind',
+                            label: 'Tailwind CSS',
+                            component: TailwindDoc
+                        },
+                        {
+                            id: 'bootstrap',
+                            label: 'Bootstrap',
+                            component: BootstrapDoc
+                        },
+                        {
+                            id: 'normalize',
+                            label: 'Normalize',
+                            component: NormalizeDoc
+                        }
+                    ]
+                }
+            ]
+        };
+    }
+};
+</script>

pages/roadmap/index.vue

@@ -165,8 +165,16 @@
                         <div class="flex-1 flex gap-3 flex-column"></div>
                     </div>
                     <div class="flex gap-3 border-bottom-1 surface-border pb-3">
-                        <div class="flex-shrink-0 p-3 bg-pink-500 text-white border-round font-bold text-lg flex align-items-center justify-content-center w-14rem">Designer</div>
+                        <div class="flex-shrink-0 p-3 bg-pink-500 text-white border-round font-bold text-lg flex align-items-center justify-content-center w-14rem">Design</div>
-                        <div class="flex-1 flex gap-3 flex-column"></div>
+                        <div class="flex-1 flex gap-3 flex-column">
+                            <div class="p-3 surface-card border-round border-pink-500" style="border-left: 6px solid">
+                                <h2 class="text-lg font-bold mt-0 mb-2">New UI Theme</h2>
+                                <p class="mt-0 mb-3 line-height-3">Brand new default theme with a modern and attractive design.</p>
+                                <div class="surface-200 border-round">
+                                    <div class="bg-pink-500 border-round" style="width: 0%; height: 4px"></div>
+                                </div>
+                            </div>
+                        </div>
                         <div class="flex-1 flex gap-3 flex-column">
                             <div class="p-3 surface-card border-round border-pink-500" style="border-left: 6px solid">
                                 <h2 class="text-lg font-bold mt-0 mb-2">New UI Based Theme Editor</h2>