@wwtdev/bsds-components-vue3 2.6.0 → 2.7.0

package/README.md

@@ -138,6 +138,62 @@ export default defineNuxtConfig({
 
 ```
 
+#### Using CSS Layers with Tailwind
+
+You can optionally leverage native CSS `@layer` to ensure TW utilities will always trump the component styles for easier overrides.   
+
+```css
+/* src/styles/index.css (or wherever your app styles live) */
+
+@layer app-base, external, app, utils;
+
+/* -- BASE -- */
+@import "@wwtdev/bsds-components-vue3/components.css" layer(app-base);
+
+/* -- EXTERNAL: any external stylesheets, e.g. from other 3d party libs -- */
+@import "some-other-pkg/dist/style.css" layer(external);
+
+/* -- APP / INTERNAL STYLES, e.g. your site's base styles -- 
+   All .vue <style> code will automatically be added to this layer (see "vueWrapCssWithLayerPlugin" in vite.config.js)
+*/
+@import "some-content.css" layer(app);
+
+/* -- UTILITY CLASSES --
+  Due to how native CSS @layer works, and our defined layer order at the top of this file, utility classes will always trump any other styles in the app (as long as those styles are in one of our defined layers)
+*/
+
+@layer utils {
+  @tailwind base;
+  @tailwind utilities;
+}
+
+```
+
+And then in your vite config:
+
+```javascript
+/* vite.config.js */
+
+// We'll need a plugin to pick up styles from our app's Vue SFCs and add them to the app layer
+const vueWrapCssWithLayerPlugin = {
+  name: 'vue-wrap-css-with-layer',
+  transform(code, id) {
+    // if not a .vue <style> block, do nothing
+    if (!/vue&type=style/.test(id)) return
+    
+    // wrap the <style> code in our "app" css layer (ensures utility classes always trump other styles, see index.css)
+    return { code: `@layer app { ${code} }`, map: null }
+  }
+}
+
+export default defineConfig({
+  plugins: [ ...yourOtherPlugins, vueWrapCssWithLayerPlugin ],
+  /* 
+    *** other configs **
+  */
+})
+```
+
 ### 4. Dark Mode-compatible "semantic" color utilities
 
 We've extended the TW theme with color utilities that will automatically adjust when using dark mode.  These classes require the CSS custom properties defined in the global stylesheet (`wwt-bsds.css`).  If you're not bringing that stylesheet in, either disregard these classes or manually include the properties from [tokens.css](https://github.wwt.com/custom-apps/wwt-blue-steel/blob/main/packages/css-framework/src/styles/tokens.css) and [global.css](https://github.wwt.com/custom-apps/wwt-blue-steel/blob/main/packages/css-framework/src/styles/global.css) in your project.