@wwtdev/bsds-components-vue3 2.0.3 → 2.0.5

package/README.md

@@ -19,7 +19,7 @@ import '@wwtdev/bsds-components-vue3/components.css'
 import '@wwtdev/bsds-icons-vue3/lib/style.css'
 ```
 
-**Note** that the CSS framework is _included_ in `@wwtdev/bsds-components-vue3/components.css`, along with a few additional styles needed for the Vue components.  This means that you do not need to import `@wwtdev/bsds-css/dist/wwt-bsds.min.css` separately.
+**Note** that the CSS framework is _included_ in `@wwtdev/bsds-components-vue3/components.css`, along with a few additional styles needed for the Vue components.  This means that you do not need to import `@wwtdev/bsds-css/dist/wwt-bsds.min.css` separately.  If you're using Tailwind in your project, see additional instructions below.
 
 #### Migration from v1
 1. Remove the `@wwtdev/bsds-components` package, as this Vue 3 package no longer depends on a base web component library.
@@ -56,3 +56,85 @@ import { BsIconCaretRight } from '@wwtdev/bsds-icons-vue3'
   </div>
 </template>
 ```
+
+### Usage with Tailwind
+
+If you're using Tailwind in your project, you'll need to take additional steps as follows:
+
+### 1. Add the WWT Preset to the Tailwind config.
+
+For new projects, we recommend that you use the provided config file as a [**preset**](https://tailwindcss.com/docs/presets).  When setting up the `tailwind.config.js` file, import the WWT preset from the CSS Framework package.  Note that `wwt-bsds-preset.js` sets `config.corePlugins.preflight: false` by default; we do this to apply our style resets instead of the Tailwind resets. 
+
+```javascript
+/* tailwind.config.js */
+
+module.exports = {
+  presets: [require('@wwtdev/bsds-css/dist/wwt-bsds-preset.js')]
+};
+```
+
+While the foregoing setup is our recommended method, we have still put in effort to ensure that `wwt-bsds-preset.js` works as a [**base configuration**](https://tailwindcss.com/docs/configuration) in conjunction with the tailwind defaults and reset as well.  So this _should_ still work as an alternative if needed, though it is not the focus/priority of our project:
+
+```javascript
+/* tailwind.config.js */
+
+const wwtConfig = require('@wwtdev/bsds-css/dist/wwt-bsds-preset.js')
+module.exports = {
+  ...wwtConfig,
+  corePlugins: { preflight: false }
+};
+```
+
+
+### 2. Tailwind CSS Directives
+
+To prevent conflicts with our CSS Framework, only include the `base` and `utilities` directives.
+
+Since our CSS has its own reset and default styles, we prevent Tailwind's `base` reset styles from loading, via a setting in our WWT Preset. The only styles that will be used from `base` are Tailwind CSS variables, which are needed in order to ensure all Tailwind classes work as expected.
+
+```css
+/* src/styles/tailwind.css */
+
+@tailwind base;
+@tailwind utilities;
+```
+
+Once you have completed the Tailwind installation steps, you can use the classes generated from the preset.
+
+### 3. 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.
+
+### 4. Order matters!
+
+In your project's stylesheet ordering, the base Tailwind styles should come first, _then_ the BSDS CSS framework.  
+
+Vue example:
+
+```javascript
+/* src/main.js */
+
+// TW
+import './styles/tailwind.css'
+
+// Blue Steel Styles
+import '@wwtdev/bsds-components-vue3/components.css'
+import '@wwtdev/bsds-icons-vue3/lib/style.css'
+
+```
+
+Nuxt example:
+
+```javascript
+/* nuxt.config.js */
+
+export default defineNuxtConfig({
+  ...
+  css: [
+    '~/assets/styles/tailwind.css',
+    '@wwtdev/bsds-components-vue3/components.css',
+    '@wwtdev/bsds-icons-vue3/lib/style.css'
+  ]
+})
+
+```