Theming doc updates
Cagatay Civici
parent
18367429f6
commit
fbc12930b1
|
|
@ -1,6 +1,7 @@
|
|||
<template>
|
||||
<DocSectionText v-bind="$attrs">
|
||||
<p>Design tokens can be scoped to a certain component using CSS variables. In this example, first switch uses the global tokens whereas second one overrides the global with its own tokens.</p>
|
||||
<p>Design tokens can be scoped to a certain component using the <i>dt</i> property. In this example, first switch uses the global tokens whereas second one overrides the global with its own tokens.</p>
|
||||
<p>This approach is recommended over the <i>:deep()</i> as it offers a cleaner API while avoiding the hassle of CSS rule overrides.</p>
|
||||
</DocSectionText>
|
||||
<div class="card flex justify-center gap-4">
|
||||
<ToggleSwitch v-model="checked1" />
|
||||
|
|
|
|||
|
|
@ -42,7 +42,7 @@ options: {
|
|||
options: {
|
||||
cssLayer: {
|
||||
name: 'primevue',
|
||||
order: 'tailwind-base, primevue, tailwind-utilities'
|
||||
order: 'app-styles, primevue, another-css-library'
|
||||
}
|
||||
}
|
||||
`
|
||||
|
|
|
|||
|
|
@ -1,9 +1,8 @@
|
|||
<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.
|
||||
In case PrimeVue components have visual issues in your application, a Reset CSS may be the culprit. CSS layers would be an efficient solution that involves enabling the PrimeVue layer, wrapping the Reset CSS in another layer and defining
|
||||
the layer order. This way, your Reset CSS does not get in the way of PrimeVue components.
|
||||
</p>
|
||||
<DocSectionCode :code="code" hideToggleCode importCode hideStackBlitz />
|
||||
</DocSectionText>
|
||||
|
|
|
|||
|
|
@ -1,71 +1,13 @@
|
|||
<template>
|
||||
<DocSectionText v-bind="$attrs">
|
||||
<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" class="doc-link">MDN</a> to begin with. In styled mode, when the <i>cssLayer</i> option is enabled at theme configuration, 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. The <i>cssLayer</i> is disabled by default to avoid compatibility issues with 3rd party CSS libraries which require a layer configuration for compatibility that is discussed in the next reset section.
|
||||
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" class="doc-link">MDN</a> to begin with.
|
||||
</p>
|
||||
<p>
|
||||
For example, let's assume you need to remove the rounded borders of the ToggleSwitch component defined by the theme in use. In order to achieve this, <i>.p-toggleswitch .p-toggleswitch-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.
|
||||
The <i>cssLayer</i> is disabled by default, when it is enabled at theme configuration, 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>
|
||||
<div class="card flex justify-center">
|
||||
<ToggleSwitch v-model="checked" :pt="{ slider: 'my-switch-slider', handle: 'my-switch-handle', icon: 'my-switch-icon' }" />
|
||||
</div>
|
||||
<DocSectionCode :code="code" hideToggleCode hideStackBlitz />
|
||||
<p>Layers also make it easier to use CSS Modules, view the CSS Modules guide for examples.</p>
|
||||
</DocSectionText>
|
||||
</template>
|
||||
|
||||
<script>
|
||||
export default {
|
||||
data() {
|
||||
return {
|
||||
checked: false,
|
||||
code: {
|
||||
basic: `
|
||||
<template>
|
||||
<ToggleSwitch v-model="checked" :pt="{ slider: 'my-switch-slider', handle: 'my-switch-handle', icon: 'my-switch-icon' }" />
|
||||
</template>
|
||||
|
||||
<script>
|
||||
import { ref } from "vue";
|
||||
|
||||
const checked = ref(false);
|
||||
<\/script>
|
||||
|
||||
<style>
|
||||
.my-switch-slider {
|
||||
border-radius: 0;
|
||||
}
|
||||
|
||||
.my-switch-handle {
|
||||
border-radius: 0;
|
||||
}
|
||||
|
||||
.my-switch-icon {
|
||||
display: none !important;
|
||||
}
|
||||
</style>
|
||||
`
|
||||
}
|
||||
};
|
||||
}
|
||||
};
|
||||
</script>
|
||||
|
||||
<style>
|
||||
.my-switch-slider {
|
||||
border-radius: 0;
|
||||
}
|
||||
|
||||
.my-switch-handle {
|
||||
border-radius: 0;
|
||||
}
|
||||
|
||||
.my-switch-icon {
|
||||
display: none !important;
|
||||
}
|
||||
</style>
|
||||
|
|
|
|||
|
|
@ -4,10 +4,7 @@
|
|||
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>
|
||||
<p>The example preset configuration adds a new <i>accent</i> button with custom <i>button.accent.color</i> and <i>button.accent.inverse.color</i> tokens. It is also possible to add tokens globally to share them within the components.</p>
|
||||
</DocSectionText>
|
||||
<DocSectionCode :code="code" hideToggleCode importCode hideStackBlitz />
|
||||
</template>
|
||||
|
|
@ -20,26 +17,40 @@ export default {
|
|||
basic: `
|
||||
const MyPreset = definePreset(Aura, {
|
||||
components: {
|
||||
toggleswitch: {
|
||||
// custom button tokens and additional style
|
||||
button: {
|
||||
extend: {
|
||||
root: {
|
||||
myDisabledOpacity: '0.7'
|
||||
},
|
||||
handle: {
|
||||
myCheckedDisabledBackground: '{primary.color}'
|
||||
}
|
||||
accent: {
|
||||
color: '#f59e0b',
|
||||
inverseColor: '#ffffff'
|
||||
}
|
||||
}
|
||||
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')};
|
||||
css: ({ dt }) => \`
|
||||
.p-button-accent {
|
||||
background: \${dt('button.accent.color')};
|
||||
color: \${dt('button.accent.inverse.color')};
|
||||
transition-duration: \${dt('my.transition.fast')};
|
||||
}
|
||||
\`
|
||||
},
|
||||
}
|
||||
}
|
||||
},
|
||||
// common tokens and styles
|
||||
extend: {
|
||||
my: {
|
||||
transition: {
|
||||
slow: '0.75s'
|
||||
normal: '0.5s'
|
||||
fast: '0.25s'
|
||||
},
|
||||
imageDisplay: 'block'
|
||||
}
|
||||
},
|
||||
css: ({ dt }) => \`
|
||||
/* Global CSS */
|
||||
img {
|
||||
display: \${dt('my.image.display')};
|
||||
}
|
||||
\`
|
||||
});
|
||||
`
|
||||
}
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
<template>
|
||||
<DocSectionText v-bind="$attrs">
|
||||
<p>
|
||||
The <i>noir</i> mode is the nickname of a variant that uses black tones as the primary and requires and additional <i>colorScheme</i> configuration to implement. A sample preset configuration with black and white variants as the primary
|
||||
The <i>noir</i> mode is the nickname of a variant that uses surface tones as the primary and requires and additional <i>colorScheme</i> configuration to implement. A sample preset configuration with black and white variants as the primary
|
||||
color;
|
||||
</p>
|
||||
</DocSectionText>
|
||||
|
|
|
|||
|
|
@ -2,7 +2,7 @@
|
|||
<DocSectionText v-bind="$attrs">
|
||||
<p>
|
||||
The color scheme palette that varies between light and dark modes is specified with the surface tokens. Example below uses <i>zinc</i> for light mode and <i>slategray</i> for dark mode. With this setting, light mode, would have a
|
||||
grayscale tone and dark mode would include blue tone.
|
||||
grayscale tone and dark mode would include bluish tone.
|
||||
</p>
|
||||
</DocSectionText>
|
||||
<DocSectionCode :code="code" hideToggleCode importCode hideStackBlitz />
|
||||
|
|
|
|||
|
|
@ -9,7 +9,7 @@
|
|||
<div class="doc-main">
|
||||
<div class="doc-intro">
|
||||
<h1>Styled Mode</h1>
|
||||
<p>Choose from a variety of pre-styled themes or develop your own..</p>
|
||||
<p>Choose from a variety of pre-styled themes or develop your own.</p>
|
||||
</div>
|
||||
<DocSections :docs="docs" />
|
||||
</div>
|
||||
|
|
@ -30,7 +30,6 @@ import ScaleDoc from '@/doc/theming/styled/ScaleDoc.vue';
|
|||
import ScopedTokensDoc from '@/doc/theming/styled/ScopedTokensDoc.vue';
|
||||
import OptionsDoc from '@/doc/theming/styled/configuration/OptionsDoc.vue';
|
||||
import ThemeDoc from '@/doc/theming/styled/configuration/ThemeDoc.vue';
|
||||
import LibrariesDoc from '@/doc/theming/styled/csslayer/LibrariesDoc.vue';
|
||||
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';
|
||||
|
|
@ -113,16 +112,16 @@ export default {
|
|||
label: 'Primary',
|
||||
component: PrimaryDoc
|
||||
},
|
||||
{
|
||||
id: 'noir',
|
||||
label: 'Noir',
|
||||
component: NoirDoc
|
||||
},
|
||||
{
|
||||
id: 'surface',
|
||||
label: 'Surface',
|
||||
component: SurfaceDoc
|
||||
},
|
||||
{
|
||||
id: 'noir',
|
||||
label: 'Noir',
|
||||
component: NoirDoc
|
||||
},
|
||||
{
|
||||
id: 'font',
|
||||
label: 'Font',
|
||||
|
|
@ -205,11 +204,6 @@ export default {
|
|||
id: 'reset',
|
||||
label: 'Reset',
|
||||
component: ResetDoc
|
||||
},
|
||||
{
|
||||
id: 'libraries',
|
||||
label: 'Libraries',
|
||||
component: LibrariesDoc
|
||||
}
|
||||
]
|
||||
},
|
||||
|
|
|
|||
Loading…
Reference in New Issue