From c3b6af01408ade3d9ea98e7b0a3b09e361795210 Mon Sep 17 00:00:00 2001
From: Cagatay Civici <cagatay.civici@gmail.com>
Date: Sat, 5 Oct 2024 11:43:14 +0300
Subject: [PATCH] New docs for the styled mode

---
 .../doc/theming/styled/ArchitectureDoc.vue    |   6 +-
 .../showcase/doc/theming/styled/ColorsDoc.vue |   5 +-
 .../doc/theming/styled/PresetsDoc.vue         | 403 +++++++++++++++++-
 .../doc/theming/styled/ReservedKeysDoc.vue    |   2 +-
 .../styled/configuration/OptionsDoc.vue       |   4 +-
 .../styled/customization/ExtendDoc.vue        |  49 +++
 apps/showcase/pages/theming/styled/index.vue  |  26 +-
 7 files changed, 472 insertions(+), 23 deletions(-)
 create mode 100644 apps/showcase/doc/theming/styled/customization/ExtendDoc.vue

diff --git a/apps/showcase/doc/theming/styled/ArchitectureDoc.vue b/apps/showcase/doc/theming/styled/ArchitectureDoc.vue
index 268eb759b..c70ef19c3 100644
--- a/apps/showcase/doc/theming/styled/ArchitectureDoc.vue
+++ b/apps/showcase/doc/theming/styled/ArchitectureDoc.vue
@@ -3,7 +3,7 @@
         <p>
             PrimeVue is a design agnostic library so unlike some other UI libraries it does not enforce a certain styling such as material design. Styling is decoupled from the components using the themes instead. A theme consists of two parts;
             <i>base</i> and <i>preset</i>. The base is the style rules with CSS variables as placeholders whereas the preset is a set of design tokens to feed a base by mapping the tokens to CSS variables. A base may be configured with different
-            presets, currently Aura, Lara and Nora are the available presets and in upcoming version more presets will be available such as Material Design.
+            presets, currently Aura, Material, Lara and Nora are the available built-in options.
         </p>
         <img alt="Architecture" src="https://primefaces.org/cdn/primevue/images/primevue-v4-styled-architecture.png" class="w-full mb-4" />
         <p>The core of the styled mode architecture is based on a concept named <i>design token</i>, a preset defines the token configuration in 3 tiers; <i>primitive</i>, <i>semantic</i> and <i>component</i>.</p>
@@ -33,9 +33,9 @@
         </p>
 
         <h3>Video Tutorial</h3>
-        <p>Watch the <b>PrimeVue Theming Demystified</b> video to learn more about the architecture with examples.</p>
+        <p>Watch the <b>PrimeVue Theming Demystified</b> series to learn more about the architecture with examples.</p>
         <div class="video-container">
-            <iframe width="560" height="315" src="https://www.youtube.com/embed/J3KFw5sih98" frameborder="0" allowfullscreen></iframe>
+            <iframe width="560" height="315" src="https://www.youtube.com/embed/videoseries?si=nlVVyxrwgiJCL9U7&amp;list=PLC9bp-OHi-Wm2LqlXk1i-haW-1kESMIqh" frameborder="0" allowfullscreen></iframe>
         </div>
     </DocSectionText>
 </template>
diff --git a/apps/showcase/doc/theming/styled/ColorsDoc.vue b/apps/showcase/doc/theming/styled/ColorsDoc.vue
index efe863f0e..fb1e4bf61 100644
--- a/apps/showcase/doc/theming/styled/ColorsDoc.vue
+++ b/apps/showcase/doc/theming/styled/ColorsDoc.vue
@@ -1,9 +1,6 @@
 <template>
     <DocSectionText v-bind="$attrs">
-        <p>
-            Color palette of a preset is defined by the <i>primitive</i> design token group. The default colors are derived from the Tailwind colors with some extensions to make it consistent with the Tailwind Presets projects of the unstyled mode.
-        </p>
-        <p>Colors can be accessed at CSS as a variable and programmatically using the <i>$dt</i> utility.</p>
+        <p>Color palette of a preset is defined by the <i>primitive</i> design token group. You can access colors using CSS variables or the <i>$dt</i> utility.</p>
     </DocSectionText>
     <DocSectionCode :code="code1" importCode hideToggleCode hideStackBlitz />
     <div class="card">
diff --git a/apps/showcase/doc/theming/styled/PresetsDoc.vue b/apps/showcase/doc/theming/styled/PresetsDoc.vue
index a9979c2e1..bbd43a73a 100644
--- a/apps/showcase/doc/theming/styled/PresetsDoc.vue
+++ b/apps/showcase/doc/theming/styled/PresetsDoc.vue
@@ -1,20 +1,20 @@
 <template>
     <DocSectionText v-bind="$attrs">
-        <p>Currently Aura, Lara and Nora are the available presets, a new preset based on Material Design is planned by the end of 2024.</p>
+        <p>currently Aura, Material, Lara and Nora are the available built-in options.</p>
     </DocSectionText>
     <div class="card">
         <Tabs value="aura">
             <TabList>
                 <Tab value="aura">Aura</Tab>
+                <Tab value="material">Material</Tab>
                 <Tab value="lara">Lara</Tab>
                 <Tab value="nora">Nora</Tab>
-                <Tab value="material">Material</Tab>
             </TabList>
             <TabPanels>
                 <TabPanel value="aura"><DocSectionCode :code="aura" hideToggleCode importCode hideStackBlitz /></TabPanel>
+                <TabPanel value="material"><DocSectionCode :code="material" hideToggleCode importCode hideStackBlitz /></TabPanel>
                 <TabPanel value="lara"><DocSectionCode :code="lara" hideToggleCode importCode hideStackBlitz /></TabPanel>
                 <TabPanel value="nora"><DocSectionCode :code="nora" hideToggleCode importCode hideStackBlitz /></TabPanel>
-                <TabPanel value="material">Coming soon with a future update.</TabPanel>
             </TabPanels>
         </Tabs>
     </div>
@@ -410,6 +410,403 @@ export default {
         // ... other components
     }
 };
+`
+            },
+            material: {
+                basic: `
+import accordion from '@primevue/themes/aura/accordion';
+// ... imports of other component tokens
+
+export default {
+    primitive: {
+        borderRadius: {
+            none: '0',
+            xs: '2px',
+            sm: '4px',
+            md: '6px',
+            lg: '8px',
+            xl: '12px'
+        },
+        emerald: { 50: '#E8F6F1', 100: '#C5EBE1', 200: '#9EDFCF', 300: '#76D3BD', 400: '#58C9AF', 500: '#3BBFA1', 600: '#35AF94', 700: '#2D9B83', 800: '#268873', 900: '#1A6657', 950: '#0d3329' },
+        green: { 50: '#E8F5E9', 100: '#C8E6C9', 200: '#A5D6A7', 300: '#81C784', 400: '#66BB6A', 500: '#4CAF50', 600: '#43A047', 700: '#388E3C', 800: '#2E7D32', 900: '#1B5E20', 950: '#0e2f10' },
+        lime: { 50: '#F9FBE7', 100: '#F0F4C3', 200: '#E6EE9C', 300: '#DCE775', 400: '#D4E157', 500: '#CDDC39', 600: '#C0CA33', 700: '#AFB42B', 800: '#9E9D24', 900: '#827717', 950: '#413c0c' },
+        red: { 50: '#FFEBEE', 100: '#FFCDD2', 200: '#EF9A9A', 300: '#E57373', 400: '#EF5350', 500: '#F44336', 600: '#E53935', 700: '#D32F2F', 800: '#C62828', 900: '#B71C1C', 950: '#5c0e0e' },
+        orange: { 50: '#FFF3E0', 100: '#FFE0B2', 200: '#FFCC80', 300: '#FFB74D', 400: '#FFA726', 500: '#FF9800', 600: '#FB8C00', 700: '#F57C00', 800: '#EF6C00', 900: '#E65100', 950: '#732900' },
+        amber: { 50: '#FFF8E1', 100: '#FFECB3', 200: '#FFE082', 300: '#FFD54F', 400: '#FFCA28', 500: '#FFC107', 600: '#FFB300', 700: '#FFA000', 800: '#FF8F00', 900: '#FF6F00', 950: '#803800' },
+        yellow: { 50: '#FFFDE7', 100: '#FFF9C4', 200: '#FFF59D', 300: '#FFF176', 400: '#FFEE58', 500: '#FFEB3B', 600: '#FDD835', 700: '#FBC02D', 800: '#F9A825', 900: '#F57F17', 950: '#7b400c' },
+        teal: { 50: '#E0F2F1', 100: '#B2DFDB', 200: '#80CBC4', 300: '#4DB6AC', 400: '#26A69A', 500: '#009688', 600: '#00897B', 700: '#00796B', 800: '#00695C', 900: '#004D40', 950: '#002720' },
+        cyan: { 50: '#E0F7FA', 100: '#B2EBF2', 200: '#80DEEA', 300: '#4DD0E1', 400: '#26C6DA', 500: '#00BCD4', 600: '#00ACC1', 700: '#0097A7', 800: '#00838F', 900: '#006064', 950: '#003032' },
+        sky: { 50: '#E1F5FE', 100: '#B3E5FC', 200: '#81D4FA', 300: '#4FC3F7', 400: '#29B6F6', 500: '#03A9F4', 600: '#039BE5', 700: '#0288D1', 800: '#0277BD', 900: '#01579B', 950: '#012c4e' },
+        blue: { 50: '#E3F2FD', 100: '#BBDEFB', 200: '#90CAF9', 300: '#64B5F6', 400: '#42A5F5', 500: '#2196F3', 600: '#1E88E5', 700: '#1976D2', 800: '#1565C0', 900: '#0D47A1', 950: '#072451' },
+        indigo: { 50: '#E8EAF6', 100: '#C5CAE9', 200: '#9FA8DA', 300: '#7986CB', 400: '#5C6BC0', 500: '#3F51B5', 600: '#3949AB', 700: '#303F9F', 800: '#283593', 900: '#1A237E', 950: '#0d123f' },
+        violet: { 50: '#EDE7F6', 100: '#D1C4E9', 200: '#B39DDB', 300: '#9575CD', 400: '#7E57C2', 500: '#673AB7', 600: '#5E35B1', 700: '#512DA8', 800: '#4527A0', 900: '#311B92', 950: '#190e49' },
+        purple: { 50: '#F3E5F5', 100: '#E1BEE7', 200: '#CE93D8', 300: '#BA68C8', 400: '#AB47BC', 500: '#9C27B0', 600: '#8E24AA', 700: '#7B1FA2', 800: '#6A1B9A', 900: '#4A148C', 950: '#250a46' },
+        fuchsia: { 50: '#FDE6F3', 100: '#FBC1E3', 200: '#F897D1', 300: '#F56DBF', 400: '#F34DB2', 500: '#F12DA5', 600: '#E0289D', 700: '#CC2392', 800: '#B81E88', 900: '#951777', 950: '#4b0c3c' },
+        pink: { 50: '#FCE4EC', 100: '#F8BBD0', 200: '#F48FB1', 300: '#F06292', 400: '#EC407A', 500: '#E91E63', 600: '#D81B60', 700: '#C2185B', 800: '#AD1457', 900: '#880E4F', 950: '#440728' },
+        rose: { 50: '#FFF0F0', 100: '#FFD9D9', 200: '#FFC0C0', 300: '#FFA7A7', 400: '#FF8E8E', 500: '#FF7575', 600: '#FF5252', 700: '#FF3838', 800: '#F71C1C', 900: '#D50000', 950: '#3E0000' },
+        slate: { 50: '#f8fafc', 100: '#f1f5f9', 200: '#e2e8f0', 300: '#cbd5e1', 400: '#94a3b8', 500: '#64748b', 600: '#475569', 700: '#334155', 800: '#1e293b', 900: '#0f172a', 950: '#020617' },
+        gray: { 50: '#f9fafb', 100: '#f3f4f6', 200: '#e5e7eb', 300: '#d1d5db', 400: '#9ca3af', 500: '#6b7280', 600: '#4b5563', 700: '#374151', 800: '#1f2937', 900: '#111827', 950: '#030712' },
+        zinc: { 50: '#fafafa', 100: '#f4f4f5', 200: '#e4e4e7', 300: '#d4d4d8', 400: '#a1a1aa', 500: '#71717a', 600: '#52525b', 700: '#3f3f46', 800: '#27272a', 900: '#18181b', 950: '#09090b' },
+        neutral: { 50: '#fafafa', 100: '#f5f5f5', 200: '#e5e5e5', 300: '#d4d4d4', 400: '#a3a3a3', 500: '#737373', 600: '#525252', 700: '#404040', 800: '#262626', 900: '#171717', 950: '#0a0a0a' },
+        stone: { 50: '#fafaf9', 100: '#f5f5f4', 200: '#e7e5e4', 300: '#d6d3d1', 400: '#a8a29e', 500: '#78716c', 600: '#57534e', 700: '#44403c', 800: '#292524', 900: '#1c1917', 950: '#0c0a09' }
+    },
+    semantic: {
+        transitionDuration: '0.2s',
+        focusRing: {
+            width: '0',
+            style: 'none',
+            color: 'unset',
+            offset: '0'
+        },
+        disabledOpacity: '0.38',
+        iconSize: '1rem',
+        anchorGutter: '0',
+        primary: {
+            50: '{emerald.50}',
+            100: '{emerald.100}',
+            200: '{emerald.200}',
+            300: '{emerald.300}',
+            400: '{emerald.400}',
+            500: '{emerald.500}',
+            600: '{emerald.600}',
+            700: '{emerald.700}',
+            800: '{emerald.800}',
+            900: '{emerald.900}',
+            950: '{emerald.950}'
+        },
+        formField: {
+            paddingX: '0.75rem',
+            paddingY: '0.75rem',
+            borderRadius: '{border.radius.sm}',
+            focusRing: {
+                width: '2px',
+                style: 'solid',
+                color: '{primary.color}',
+                offset: '-2px',
+                shadow: 'none'
+            },
+            transitionDuration: '{transition.duration}'
+        },
+        list: {
+            padding: '0.5rem 0',
+            gap: '0',
+            header: {
+                padding: '0.75rem 1rem'
+            },
+            option: {
+                padding: '0.75rem 1rem',
+                borderRadius: '{border.radius.none}'
+            },
+            optionGroup: {
+                padding: '0.75rem 1rem',
+                fontWeight: '700'
+            }
+        },
+        content: {
+            borderRadius: '{border.radius.sm}'
+        },
+        mask: {
+            transitionDuration: '0.15s'
+        },
+        navigation: {
+            list: {
+                padding: '0.5rem 0',
+                gap: '0'
+            },
+            item: {
+                padding: '0.75rem 1rem',
+                borderRadius: '{border.radius.none}',
+                gap: '0.5rem'
+            },
+            submenuLabel: {
+                padding: '0.75rem 1rem',
+                fontWeight: '700'
+            },
+            submenuIcon: {
+                size: '0.875rem'
+            }
+        },
+        overlay: {
+            select: {
+                borderRadius: '{border.radius.sm}',
+                shadow: '0 5px 5px -3px rgba(0,0,0,.2), 0 8px 10px 1px rgba(0,0,0,.14), 0 3px 14px 2px rgba(0,0,0,.12)'
+            },
+            popover: {
+                borderRadius: '{border.radius.sm}',
+                padding: '1rem',
+                shadow: '0 11px 15px -7px rgba(0,0,0,.2), 0 24px 38px 3px rgba(0,0,0,.14), 0 9px 46px 8px rgba(0,0,0,.12)'
+            },
+            modal: {
+                borderRadius: '{border.radius.sm}',
+                padding: '1.5rem',
+                shadow: '0 11px 15px -7px rgba(0,0,0,.2), 0 24px 38px 3px rgba(0,0,0,.14), 0 9px 46px 8px rgba(0,0,0,.12)'
+            },
+            navigation: {
+                shadow: '0 2px 4px -1px rgba(0,0,0,.2), 0 4px 5px 0 rgba(0,0,0,.14), 0 1px 10px 0 rgba(0,0,0,.12)'
+            }
+        },
+        colorScheme: {
+            light: {
+                focusRing: {
+                    shadow: '0 0 1px 4px {surface.200}'
+                },
+                surface: {
+                    0: '#ffffff',
+                    50: '{slate.50}',
+                    100: '{slate.100}',
+                    200: '{slate.200}',
+                    300: '{slate.300}',
+                    400: '{slate.400}',
+                    500: '{slate.500}',
+                    600: '{slate.600}',
+                    700: '{slate.700}',
+                    800: '{slate.800}',
+                    900: '{slate.900}',
+                    950: '{slate.950}'
+                },
+                primary: {
+                    color: '{primary.500}',
+                    contrastColor: '#ffffff',
+                    hoverColor: '{primary.400}',
+                    activeColor: '{primary.300}'
+                },
+                highlight: {
+                    background: 'color-mix(in srgb, {primary.color}, transparent 88%)',
+                    focusBackground: 'color-mix(in srgb, {primary.color}, transparent 76%)',
+                    color: '{primary.700}',
+                    focusColor: '{primary.800}'
+                },
+                mask: {
+                    background: 'rgba(0,0,0,0.32)',
+                    color: '{surface.200}'
+                },
+                formField: {
+                    background: '{surface.0}',
+                    disabledBackground: '{surface.300}',
+                    filledBackground: '{surface.100}',
+                    filledHoverBackground: '{surface.200}',
+                    filledFocusBackground: '{surface.100}',
+                    borderColor: '{surface.400}',
+                    hoverBorderColor: '{surface.900}',
+                    focusBorderColor: '{primary.color}',
+                    invalidBorderColor: '{red.800}',
+                    color: '{surface.900}',
+                    disabledColor: '{surface.600}',
+                    placeholderColor: '{surface.600}',
+                    floatLabelColor: '{surface.600}',
+                    floatLabelFocusColor: '{primary.600}',
+                    floatLabelActiveColor: '{surface.600}',
+                    floatLabelInvalidColor: '{red.800}',
+                    iconColor: '{surface.600}',
+                    shadow: 'none'
+                },
+                text: {
+                    color: '{surface.900}',
+                    hoverColor: '{surface.900}',
+                    mutedColor: '{surface.600}',
+                    hoverMutedColor: '{surface.600}'
+                },
+                content: {
+                    background: '{surface.0}',
+                    hoverBackground: '{surface.100}',
+                    borderColor: '{surface.300}',
+                    color: '{text.color}',
+                    hoverColor: '{text.hover.color}'
+                },
+                overlay: {
+                    select: {
+                        background: '{surface.0}',
+                        borderColor: '{surface.0}',
+                        color: '{text.color}'
+                    },
+                    popover: {
+                        background: '{surface.0}',
+                        borderColor: '{surface.0}',
+                        color: '{text.color}'
+                    },
+                    modal: {
+                        background: '{surface.0}',
+                        borderColor: '{surface.0}',
+                        color: '{text.color}'
+                    }
+                },
+                list: {
+                    option: {
+                        focusBackground: '{surface.100}',
+                        selectedBackground: '{highlight.background}',
+                        selectedFocusBackground: '{highlight.focus.background}',
+                        color: '{text.color}',
+                        focusColor: '{text.hover.color}',
+                        selectedColor: '{highlight.color}',
+                        selectedFocusColor: '{highlight.focus.color}',
+                        icon: {
+                            color: '{surface.600}',
+                            focusColor: '{surface.600}'
+                        }
+                    },
+                    optionGroup: {
+                        background: 'transparent',
+                        color: '{text.color}'
+                    }
+                },
+                navigation: {
+                    item: {
+                        focusBackground: '{surface.100}',
+                        activeBackground: '{surface.200}',
+                        color: '{text.color}',
+                        focusColor: '{text.hover.color}',
+                        activeColor: '{text.hover.color}',
+                        icon: {
+                            color: '{surface.600}',
+                            focusColor: '{surface.600}',
+                            activeColor: '{surface.600}'
+                        }
+                    },
+                    submenuLabel: {
+                        background: 'transparent',
+                        color: '{text.color}'
+                    },
+                    submenuIcon: {
+                        color: '{surface.600}',
+                        focusColor: '{surface.600}',
+                        activeColor: '{surface.600}'
+                    }
+                }
+            },
+            dark: {
+                focusRing: {
+                    shadow: '0 0 1px 4px {surface.700}'
+                },
+                surface: {
+                    0: '#ffffff',
+                    50: '{zinc.50}',
+                    100: '{zinc.100}',
+                    200: '{zinc.200}',
+                    300: '{zinc.300}',
+                    400: '{zinc.400}',
+                    500: '{zinc.500}',
+                    600: '{zinc.600}',
+                    700: '{zinc.700}',
+                    800: '{zinc.800}',
+                    900: '{zinc.900}',
+                    950: '{zinc.950}'
+                },
+                primary: {
+                    color: '{primary.400}',
+                    contrastColor: '{surface.900}',
+                    hoverColor: '{primary.300}',
+                    activeColor: '{primary.200}'
+                },
+                highlight: {
+                    background: 'color-mix(in srgb, {primary.400}, transparent 84%)',
+                    focusBackground: 'color-mix(in srgb, {primary.400}, transparent 76%)',
+                    color: 'rgba(255,255,255,.87)',
+                    focusColor: 'rgba(255,255,255,.87)'
+                },
+                mask: {
+                    background: 'rgba(0,0,0,0.6)',
+                    color: '{surface.200}'
+                },
+                formField: {
+                    background: '{surface.950}',
+                    disabledBackground: '{surface.700}',
+                    filledBackground: '{surface.800}',
+                    filledHoverBackground: '{surface.700}',
+                    filledFocusBackground: '{surface.800}',
+                    borderColor: '{surface.600}',
+                    hoverBorderColor: '{surface.400}',
+                    focusBorderColor: '{primary.color}',
+                    invalidBorderColor: '{red.300}',
+                    color: '{surface.0}',
+                    disabledColor: '{surface.400}',
+                    placeholderColor: '{surface.400}',
+                    floatLabelColor: '{surface.400}',
+                    floatLabelFocusColor: '{primary.color}',
+                    floatLabelActiveColor: '{surface.400}',
+                    floatLabelInvalidColor: '{red.300}',
+                    iconColor: '{surface.400}',
+                    shadow: 'none'
+                },
+                text: {
+                    color: '{surface.0}',
+                    hoverColor: '{surface.0}',
+                    mutedColor: '{surface.400}',
+                    hoverMutedColor: '{surface.400}'
+                },
+                content: {
+                    background: '{surface.900}',
+                    hoverBackground: '{surface.800}',
+                    borderColor: '{surface.700}',
+                    color: '{text.color}',
+                    hoverColor: '{text.hover.color}'
+                },
+                overlay: {
+                    select: {
+                        background: '{surface.900}',
+                        borderColor: '{surface.900}',
+                        color: '{text.color}'
+                    },
+                    popover: {
+                        background: '{surface.900}',
+                        borderColor: '{surface.900}',
+                        color: '{text.color}'
+                    },
+                    modal: {
+                        background: '{surface.900}',
+                        borderColor: '{surface.900}',
+                        color: '{text.color}'
+                    }
+                },
+                list: {
+                    option: {
+                        focusBackground: '{surface.800}',
+                        selectedBackground: '{highlight.background}',
+                        selectedFocusBackground: '{highlight.focus.background}',
+                        color: '{text.color}',
+                        focusColor: '{text.hover.color}',
+                        selectedColor: '{highlight.color}',
+                        selectedFocusColor: '{highlight.focus.color}',
+                        icon: {
+                            color: '{surface.400}',
+                            focusColor: '{surface.400}'
+                        }
+                    },
+                    optionGroup: {
+                        background: 'transparent',
+                        color: '{text.muted.color}'
+                    }
+                },
+                navigation: {
+                    item: {
+                        focusBackground: '{surface.800}',
+                        activeBackground: '{surface.700}',
+                        color: '{text.color}',
+                        focusColor: '{text.hover.color}',
+                        activeColor: '{text.hover.color}',
+                        icon: {
+                            color: '{surface.400}',
+                            focusColor: '{surface.400}',
+                            activeColor: '{surface.400}'
+                        }
+                    },
+                    submenuLabel: {
+                        background: 'transparent',
+                        color: '{text.muted.color}'
+                    },
+                    submenuIcon: {
+                        color: '{surface.400}',
+                        focusColor: '{surface.400}',
+                        activeColor: '{surface.400}'
+                    }
+                }
+            }
+        }
+    },
+    components: {
+        accordion,
+        // ... other components
+    }
+};
 `
             },
             lara: {
diff --git a/apps/showcase/doc/theming/styled/ReservedKeysDoc.vue b/apps/showcase/doc/theming/styled/ReservedKeysDoc.vue
index 7fac1b0af..f084f1df6 100644
--- a/apps/showcase/doc/theming/styled/ReservedKeysDoc.vue
+++ b/apps/showcase/doc/theming/styled/ReservedKeysDoc.vue
@@ -2,7 +2,7 @@
     <DocSectionText v-bind="$attrs">
         <p>
             Following keys are reserved in the preset scheme and cannot be used as a token name; <i>primitive</i>, <i>semantic</i>, <i>components</i>, <i>directives</i>, <i>colorscheme</i>, <i>light</i>, <i>dark</i>, <i>common</i>, <i>root</i>,
-            <i>states</i>.
+            <i>states</i>, and <i>extend</i>.
         </p>
     </DocSectionText>
 </template>
diff --git a/apps/showcase/doc/theming/styled/configuration/OptionsDoc.vue b/apps/showcase/doc/theming/styled/configuration/OptionsDoc.vue
index 5caa114e4..99064ff17 100644
--- a/apps/showcase/doc/theming/styled/configuration/OptionsDoc.vue
+++ b/apps/showcase/doc/theming/styled/configuration/OptionsDoc.vue
@@ -12,8 +12,8 @@
         <DocSectionCode :code="code2" importCode hideToggleCode hideStackBlitz />
         <h4>cssLayer</h4>
         <p>
-            Defines whether the styles should be defined inside a <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/@layer" target="_blank" rel="noopener noreferrer">CSS layer</a> named <i>primeui</i> by default or not. A CSS layer would be
-            handy to declare a custom cascade layer for easier customization. The default is <i>false</i>.
+            Defines whether the styles should be defined inside a <a href="https://developer.mozilla.org/en-US/docs/Web/CSS/@layer" target="_blank" rel="noopener noreferrer">CSS layer</a> by default or not. A CSS layer would be handy to declare a
+            custom cascade layer for easier customization if necessary. The default is <i>false</i>.
         </p>
         <DocSectionCode :code="code3" importCode hideToggleCode hideStackBlitz />
     </DocSectionText>
diff --git a/apps/showcase/doc/theming/styled/customization/ExtendDoc.vue b/apps/showcase/doc/theming/styled/customization/ExtendDoc.vue
new file mode 100644
index 000000000..cb6c1bc29
--- /dev/null
+++ b/apps/showcase/doc/theming/styled/customization/ExtendDoc.vue
@@ -0,0 +1,49 @@
+<template>
+    <DocSectionText v-bind="$attrs">
+        <p>
+            The theming system can be extended by adding custom design tokens and additional styles. This feature provides a high degree of customization, allowing you to adjust styles according to your needs, as you are not limited to the default
+            tokens.
+        </p>
+        <p>
+            Use the <i>extend</i> property to add custom tokens along with the <i>css</i> property to utilize them. As an example, let's customize the disabled state of the ToggleSwitch component to add an opacity token, and use the primary color for
+            the handle. By default, there is no opacity option available, and the disabled switch uses a gray handle by design.
+        </p>
+    </DocSectionText>
+    <DocSectionCode :code="code" hideToggleCode importCode hideStackBlitz />
+</template>
+
+<script>
+export default {
+    data() {
+        return {
+            code: {
+                basic: `
+const MyPreset = definePreset(Aura, {
+    components: {
+        toggleswitch: {
+            extend: {
+                root: {
+                    myDisabledOpacity: '0.7' 
+                },
+                handle: {
+                    myCheckedDisabledBackground: '{primary.color}'
+                } 
+            }
+        },
+        css: ({ dt }) => \`
+.p-toggleswitch.p-disabled .p-toggleswitch-slider {
+    opacity: \${dt('toggleswitch.my.disabled.opacity')};
+}
+
+.p-toggleswitch.p-disabled .p-toggleswitch-handle {
+    background: \${dt('toggleswitch.my.checked.disabled.background')};
+}
+\`
+    }
+});
+`
+            }
+        };
+    }
+};
+</script>
diff --git a/apps/showcase/pages/theming/styled/index.vue b/apps/showcase/pages/theming/styled/index.vue
index 389d324d0..c94d1471d 100755
--- a/apps/showcase/pages/theming/styled/index.vue
+++ b/apps/showcase/pages/theming/styled/index.vue
@@ -35,6 +35,7 @@ import ResetDoc from '@/doc/theming/styled/csslayer/ResetDoc.vue';
 import SpecificityDoc from '@/doc/theming/styled/csslayer/SpecificityDoc.vue';
 import ComponentDoc from '@/doc/theming/styled/customization/ComponentDoc.vue';
 import DefinePresetDoc from '@/doc/theming/styled/customization/DefinePresetDoc.vue';
+import ExtendDoc from '@/doc/theming/styled/customization/ExtendDoc.vue';
 import FocusRingDoc from '@/doc/theming/styled/customization/FocusRingDoc.vue';
 import FontDoc from '@/doc/theming/styled/customization/FontDoc.vue';
 import FormsDoc from '@/doc/theming/styled/customization/FormsDoc.vue';
@@ -88,6 +89,16 @@ export default {
                     label: 'Reserved Keys',
                     component: ReservedKeysDoc
                 },
+                {
+                    id: 'colors',
+                    label: 'Colors',
+                    component: ColorsDoc
+                },
+                {
+                    id: 'darkmode',
+                    label: 'Dark Mode',
+                    component: DarkModeDoc
+                },
                 {
                     id: 'customization',
                     label: 'Customization',
@@ -131,6 +142,11 @@ export default {
                             id: 'component',
                             label: 'Component',
                             component: ComponentDoc
+                        },
+                        {
+                            id: 'extend',
+                            label: 'Extend',
+                            component: ExtendDoc
                         }
                     ]
                 },
@@ -175,16 +191,6 @@ export default {
                         }
                     ]
                 },
-                {
-                    id: 'colors',
-                    label: 'Colors',
-                    component: ColorsDoc
-                },
-                {
-                    id: 'darkmode',
-                    label: 'Dark Mode',
-                    component: DarkModeDoc
-                },
                 {
                     id: 'csslayer',
                     label: 'CSS Layer',