@kaizen/tailwind 1.2.14 → 1.3.1

package/src/_docs/pages/borders/border-width.stories.tsx

@@ -0,0 +1,47 @@
+import React from "react"
+import { Meta, StoryFn } from "@storybook/react"
+import classnames from "classnames"
+import { TailwindStoryTemplate } from "~tailwind/_docs/utils/TailwindStoryTemplate"
+import { utilityDescription } from "~tailwind/_docs/utils/utilityDescription"
+import { kaizenTailwindTheme } from "~tailwind/tailwind-presets"
+
+const prefix = "border-"
+const classEntries: Array<{ utilityClassName: string; cssProperty: string }> =
+  Object.entries(kaizenTailwindTheme.borderWidth || []).map(
+    ([suffix, cssProperty]) => ({
+      utilityClassName: `${prefix}${suffix}`,
+      cssProperty,
+    })
+  )
+
+export default {
+  title: "Guides/Tailwind/Utility Class References/Borders/Border Width",
+  parameters: {
+    a11y: { disable: true },
+    chromatic: { disable: false },
+    docsLayout: "fullPage",
+    docs: {
+      description: {
+        component: utilityDescription(prefix, classEntries[1].utilityClassName),
+      },
+    },
+  },
+} satisfies Meta
+
+export const BorderWidth: StoryFn<{ isReversed: boolean }> = ({
+  isReversed,
+}) => (
+  <TailwindStoryTemplate
+    compiledCssPropertyName="border-width"
+    classKeyValues={classEntries}
+    renderExampleComponent={(utilityClass): React.ReactElement => (
+      <div
+        className={classnames(
+          "w-[100px] h-[100px] border rounded",
+          !utilityClass.includes("-DEFAULT") && utilityClass
+        )}
+      />
+    )}
+    isReversed={isReversed}
+  />
+)

package/src/_docs/pages/configuration.mdx

@@ -0,0 +1,78 @@
+import { Meta } from "@storybook/blocks"
+import { InlineNotification } from "~components/Notification"
+
+<Meta title="Guides/Tailwind/Configuration" />
+
+# Configuration
+
+This page provides guidance on potential configuration options and how they work with the preset and Kaizen components.
+
+- [Extending the Kaizen preset](#extending-the-kaizen-preset)
+- [Customising the important selector](#customising-the-important-selector)
+
+<br/>
+
+## Extending the Kaizen preset
+
+> Extending your config is a good option when you intend to _reuse_ the style.
+> If you need a value not available in our preset for a specific use case, consider using [arbitrary values](https://tailwindcss.com/docs/adding-custom-styles#using-arbitrary-values) instead.
+
+To extend upon the preset with values specific to your project, we recommend passing a theme object to `theme.extend`.
+
+```js
+const { Preset } = require("@kaizen/tailwind")
+
+module.exports = {
+  presets: [Preset],
+  theme: {
+    extend: {
+      colors: {
+        myCoolNewColor: "#ffffff",
+        "purple-100": "lime"
+      }
+    }
+  }
+}
+```
+
+Here, the Kaizen preset overwrites the default Tailwind preset, and the `extend` field adds in some new values.
+Be careful though! While adding in a _new_ field to `colors` won't overwrite any existing ones, passing in an existing field _will_. In this example, `purple-100` has unfortunately been overwritten.
+
+`<p className="text-sky">...` ❌ Default TW config overwritten by `Preset`
+
+`<p className="text-myCoolNewColor">` ✅ New color added
+
+`<p className="text-purple-100">` ️❗️ Value from `Preset` overwritten to "Lime"
+
+`<p className="text-purple-200">` ✅ Value from `Preset` not overwritten
+
+<br/>
+
+## Customising the important selector
+
+If the `"#root"` id selector is incompatible with your application wrapper or you are working with a mono-repo that needs to target a selector with lower specificity, you can change the `important` [configuration option](https://tailwindcss.com/docs/configuration#important-modifier) in your `tailwind.config.js`.
+
+If this is changed or you are not using the [Frontend Template](https://github.com/cultureamp/frontend-template), be sure that the `important` selector matches to an `id`, `class`, or `HTML Element` within your application, ie:
+
+``` tsx
+<div id="#root">
+ {/* Application code */}
+</div>
+```
+
+<InlineNotification
+  persistent
+  type="cautionary"
+  style="inline"
+  title="Changing the selector"
+>
+  We advise using an <code>id</code> with <code>&quot;#root&quot;</code> as the default selector. Using different id&apos;s, classes or HTML elements like <code>body</code> as the selector could result in:
+  <ul>
+    <li>
+      Utility classes not superseding Kaizen defaults when using <code>classNameOverride</code>
+    </li>
+    <li>
+      Duplication of utillity classes in your CSS bundle caused by consuming components with different <code>important</code> selectors
+    </li>
+  </ul>
+</InlineNotification>

package/src/_docs/pages/contributing.mdx

@@ -0,0 +1,38 @@
+import { Meta } from "@storybook/blocks"
+
+<Meta title="Guides/Tailwind/Contributing to this package" />
+
+# Contributing
+
+<br/>
+
+## Local Development within Kaizen
+
+Note: While Taiwlind utilities can be used within `.stories.tsx` and `.mdx` files for documentation and layout purposes, Kaizen components will not render or compile Tailwind styles in the final bundle, i.e: `mr-8` will not apply `margin-right: $spacing-8` if added to a classname in `Button.tsx`.
+
+### Gotchas
+
+**New preset created but not available / rendering in DOM**
+
+Any time you update the Tailwind presets, make sure you run `pnpm build` in the root `@kaizen/tailwind` folder.
+You may also need to reload the window for these to be picked up with TW IntelliSense.
+
+**Intellisense not working within the class attributes**
+
+For configuring IntelliSense refer to the [CONFIGURATION.md](/story/systems-tailwind-preset-configuration--page)
+
+Check the output in your terminal output for TailwindCSS IntelliSense.
+
+If you see the following:
+
+```
+Tailwind CSS: Can't resolve "@kaizen/design-tokens" in... '/Users/.../kaizen-design-system'
+// OR
+Tailwind CSS: Can't resolve '@kaizen/tailwind' in '/Users/.../kaizen-design-system'
+```
+
+**Solution**
+
+Run build in both the design-tokens and tailwind package folders.
+
+In consuming repos this will not be an issue but for local develop we are requiring on `/dist` folders having compile ts for the plugin to consume.

package/src/_docs/pages/effects/shadow.mdx

@@ -0,0 +1,10 @@
+import { Description, Meta, Story } from "@storybook/blocks"
+import * as Examples from "./shadow.stories"
+
+<Meta of={Examples} />
+
+# Box Shadow
+
+<Description />
+
+<Story of={Examples.BoxShadow} />

package/src/_docs/pages/effects/shadow.stories.tsx

@@ -0,0 +1,40 @@
+import React from "react"
+import { Meta, StoryFn } from "@storybook/react"
+import classnames from "classnames"
+import { TailwindStoryTemplate } from "~tailwind/_docs/utils/TailwindStoryTemplate"
+import { utilityDescription } from "~tailwind/_docs/utils/utilityDescription"
+import { kaizenTailwindTheme } from "~tailwind/tailwind-presets"
+
+const prefix = "shadow-"
+const classEntries: Array<{ utilityClassName: string; cssProperty: string }> =
+  Object.entries(kaizenTailwindTheme.boxShadow || []).map(
+    ([suffix, cssProperty]) => ({
+      utilityClassName: `${prefix}${suffix}`,
+      cssProperty,
+    })
+  )
+
+export default {
+  title: "Guides/Tailwind/Utility Class References/Effects/Box Shadow",
+  parameters: {
+    a11y: { disable: true },
+    chromatic: { disable: false },
+    docsLayout: "fullPage",
+    docs: {
+      description: {
+        component: utilityDescription(prefix, classEntries[0].utilityClassName),
+      },
+    },
+  },
+} satisfies Meta
+
+export const BoxShadow: StoryFn<{ isReversed: boolean }> = ({ isReversed }) => (
+  <TailwindStoryTemplate
+    compiledCssPropertyName="box-shadow"
+    classKeyValues={classEntries}
+    renderExampleComponent={(utilityClass): React.ReactElement => (
+      <div className={classnames("w-[100px] h-[100px]", utilityClass)} />
+    )}
+    isReversed={isReversed}
+  />
+)

package/src/_docs/pages/getting-started.mdx

@@ -0,0 +1,125 @@
+import { Meta } from "@storybook/blocks"
+import CssGeneration from "../assets/css-generation.png"
+import InlineFold from "../assets/inline-fold.gif"
+import TailwindPlay from "../assets/tailwind-play.gif"
+
+<Meta title="Guides/Tailwind/Getting Started" />
+
+# Getting Started
+
+This page describes the steps needed to use our [Kaizen Tailwind preset](https://github.com/cultureamp/kaizen-design-system/tree/main/packages/tailwind), not Tailwind itself.
+To learn more about Tailwind and how to install it in your project, check out there docs [here](https://tailwindcss.com/docs/installation).
+
+Note: Projects created from [frontend-template](https://github.com/cultureamp/frontend-template) should have steps 1 - 3 completed out of the box.
+If your project was created from this template, you should only need to do [Step 4: Useful tools](#4-useful-tools).
+
+- [1. Install the preset](#1-install-the-preset)
+- [2. Implement the preset](#2-implement-the-preset)
+- [3. Add the Tailwind directives](#3-add-the-tailwind-directives)
+- [4. Useful tools](#4-useful-tools)
+
+<br/>
+
+## 1. Install the preset
+
+```bash
+yarn add -D @kaizen/tailwind
+```
+
+## 2. Implement the Preset
+
+In your tailwind config file, import the preset and add it to your `presets` array.
+This will override the default Tailwind preset, and make ours available for use.
+
+```js
+// tailwind.config.js
+
+const { Preset } = require("@kaizen/tailwind")
+
+module.exports = {
+  // Glob pattern to match files containing TW classes. May be different for your project.
+  content: ["./**/*.{ts,tsx}"],
+  // Override the default Tailwind preset with the Kaizen one.
+  presets: [Preset],
+  // This should be a selector that wraps your app. It ensures that your Tailwind classes supersede component styles, by increasing their specificity with the chosen selector.
+  important: "#root",
+  // Preflight is a heavy-handed css reset. We recommend disabling it in your project.
+  corePlugins: {
+    preflight: false,
+  },
+}
+```
+
+For preset configuration options, see our [configuration docs](/story/systems-tailwind-configuration--page)
+
+## 3. Add the Tailwind Directives
+
+The following directives need to be included in your project's main css file.
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+These directives inject classes that are needed for certain Tailwind features.
+For more information, see [here](https://tailwindcss.com/docs/functions-and-directives).
+
+## 4. Useful tools
+
+### Tailwind Play
+
+Tailwind Play is an online code sandbox with Tailwind set up out of the box. The Kaizen Team has created an instance with the Kaizen Preset values [here](https://play.tailwindcss.com/OUogvUgXQR)
+
+Use this playground to get familiar with our preset, test out new config extensions, create a quick proof of concept, or share code examples with other engineers. Feel free to hit ‘Share’ - it’ll create a new url without overriding the one provided here.
+
+<img src={TailwindPlay} alt="Tailwind Play" />
+
+The playground also has a great “Generated CSS” feature that let’s you see which css classes are generated by your preset when you implement tailwind utilities. It’s a great way to see what Tailwind is doing under the hood.
+
+<div className="flex justify-center">
+  <img src={CssGeneration} alt="CSS Generation" />
+</div>
+
+### Tailwind CSS VSCode IntelliSense plugin
+
+Basic config for the [VSCode plugin](https://marketplace.visualstudio.com/items?itemName=bradlc.vscode-tailwindcss) for Tailwind IntelliSense lives in your project's `settings.json`.
+
+You can customise which keywords trigger IntelliSense using basic strings, or even regex expressions.
+Here are some examples you may wish to include in your own project:
+
+```
+"tailwindCSS.classAttributes": [
+  "class",
+  "className",
+  "ngClass",
+  "classNameOverride"
+],
+"tailwindCSS.experimental.classRegex": [
+  "classnames\\(([^)]*)\\)",
+  "classNames\\(([^)]*)\\)",
+  "clsx\\(([^)]*)\\)",
+  "csx\\(([^)]*)\\)"
+]
+```
+
+`tailwindCSS.experimental.classRegex` is used to provide intelliSense within your `classnames` functions in your codebase.
+Ideally you only add the pattern that is used in your repo.
+
+Calling out that this is still an experimental feature for the VSCode plugin.
+
+### Inline fold VSCode extension
+Using tailwind often results in long class names, that can even span over multiple lines.
+Inline fold is a great extension that hides/ shows long class strings.
+
+Check it out [here](https://marketplace.visualstudio.com/items?itemName=moalamri.inline-fold):
+
+
+<div className="flex justify-center">
+  <img src={InlineFold} alt="Inline fold VSCode extension" />
+</div>
+
+### Prettier plugin
+
+Tailwind now has prettier support! 🎉 This [prettier plugin](https://github.com/tailwindlabs/prettier-plugin-tailwindcss) will order your classnames for you.
+We’d highly recommend it for the sake of consistency. The Tailwind docs even have a guide [here](https://tailwindcss.com/blog/automatic-class-sorting-with-prettier).

package/src/_docs/pages/modifiers/media-queries.mdx

@@ -0,0 +1,16 @@
+import { Description, Meta, Story } from "@storybook/blocks"
+import * as Examples from "./media-queries.stories"
+
+<Meta of={Examples} />
+
+# Media Queries
+
+<Description />
+
+## Preset media queries
+
+<Story of={Examples.MediaQueries} />
+
+## Using arbitrary values
+
+<Story of={Examples.ArbitraryMediaQueries} />

package/src/_docs/pages/modifiers/media-queries.stories.tsx

@@ -0,0 +1,81 @@
+import React from "react"
+import { Meta, StoryFn } from "@storybook/react"
+import { Heading } from "~components/Heading"
+import { Text } from "~components/Text"
+
+export default {
+  title: "Guides/Tailwind/Utility Class References/Modifiers/Media Queries",
+  parameters: {
+    docsLayout: "fullPage",
+    docs: {
+      a11y: { disable: true },
+      description: {
+        component:
+          "Require @kaizen/tailwind and add it into your tailwind config",
+      },
+    },
+  },
+} satisfies Meta
+
+type QueryInfoProps = {
+  selector: string
+  selectorValue: string
+  children: React.ReactElement
+}
+const QueryInfo = ({
+  selector,
+  selectorValue,
+  children,
+}: QueryInfoProps): React.ReactElement => (
+  <div className="my-12">
+    <Text variant="intro-lede">Pseudo selector: {selector}</Text>
+    <Text variant="body">Breakpoint: {selectorValue}</Text>
+    <Text variant="body">In this example: {selector}:bg-blue-400</Text>
+    {/* Passing in as children, as dynamically creating the media query with interpolation fails */}
+    {children}
+  </div>
+)
+
+export const MediaQueries: StoryFn = () => (
+  <div className="py-32">
+    <Heading tag="p" variant="heading-4" classNameOverride="text-center">
+      These breakpoints activate <em>over</em> a certain screen width. Meaning
+      that bg-blue-400 will be applied when the screen gets <em>wider</em>.
+    </Heading>
+    <QueryInfo selector="md" selectorValue="768px">
+      <div className="border-solid md:bg-blue-400 h-[50px] w-full rounded" />
+    </QueryInfo>
+    <QueryInfo selector="lg" selectorValue="1080px">
+      <div className="border-solid lg:bg-blue-400 h-[50px] w-full rounded" />
+    </QueryInfo>
+  </div>
+)
+
+export const ArbitraryMediaQueries: StoryFn = () => (
+  <div className="py-32">
+    <Heading tag="p" variant="heading-4" classNameOverride="text-center">
+      Bespoke, one-off media queries can be created with arbitrary values. See
+      the{" "}
+      <a href="https://tailwindcss.com/docs/responsive-design#arbitrary-values">
+        Tailwind docs
+      </a>{" "}
+      for more info.
+    </Heading>
+
+    <div className="py-32">
+      <Text variant="body">
+        <strong>Min-width breakpoint</strong> (applied when the screen gets{" "}
+        <em>wider</em>)
+      </Text>
+      <Text variant="body">In this example: min-[500px]:bg-blue-400</Text>
+      <div className="border-solid min-[500px]:bg-blue-400 h-[50px] w-full rounded-default" />
+    </div>
+
+    <Text variant="body">
+      <strong>Max-width breakpoint</strong> (applied when the screen gets{" "}
+      <em>slimmer</em>)
+    </Text>
+    <Text variant="body">In this example: max-[500px]:bg-blue-400</Text>
+    <div className="border-solid max-[500px]:bg-blue-400 h-[50px] w-full rounded-default" />
+  </div>
+)

package/src/_docs/pages/modifiers/pseudo-states.mdx

@@ -0,0 +1,26 @@
+import { Description, Meta, Story, Unstyled } from "@storybook/blocks"
+import { Card } from "~components/Card"
+import * as Examples from "./pseudo-states.stories"
+
+<Meta of={Examples} />
+
+# Pseudo Selectors
+
+<Description />
+
+<Unstyled>
+  <Card variant="informative" classNameOverride="w-fit mb-24">
+    <div className="font-family-paragraph p-24">
+      <p>
+        Pseudo selectors can be used to apply standard Tailwind utility
+        classes under certain pseudo states, such as on hover or focus.
+      </p>
+      <p>
+        Read more on Tailwind&apos;s pseudo selectors
+        <a href="https://tailwindcss.com/docs/hover-focus-and-other-states#pseudo-classes">here</a>.
+      </p>
+    </div>
+  </Card>
+</Unstyled>
+
+<Story of={Examples.PseudoSelectors} />

package/src/_docs/pages/modifiers/pseudo-states.stories.tsx

@@ -0,0 +1,49 @@
+/* eslint-disable jsx-a11y/anchor-is-valid */
+import React from "react"
+import { Meta, StoryFn } from "@storybook/react"
+import { StickerSheet } from "~storybook/components/StickerSheet"
+
+export default {
+  title: "Guides/Tailwind/Utility Class References/Modifiers/Pseudo Selectors",
+  parameters: {
+    a11y: { disable: true },
+    docsLayout: "fullPage",
+    docs: {
+      description: {
+        component:
+          "Add a modifier before a standard tailwind utility class to have it apply in certain states. For example, hover:text-blue-500 will set the font color to blue-500 on hover.",
+      },
+    },
+  },
+} satisfies Meta
+
+export const PseudoSelectors: StoryFn<{ isReversed: boolean }> = ({
+  isReversed,
+}) => (
+  <StickerSheet isReversed={isReversed}>
+    <StickerSheet.Header
+      headings={["Utility Class", "Compiled CSS", "Example"]}
+    />
+    <StickerSheet.Row rowTitle="hover">
+      <p className="font-family-paragraph">hover:bg-blue-200</p>
+      <p className="font-family-paragraph">background-color: #bde2f5</p>
+      <button
+        type="button"
+        className="border-solid bg-white border-[black] font-family-paragraph w-[150px] rounded hover:bg-blue-200 py-16 px-12 text-center"
+      >
+        Hover me
+      </button>
+    </StickerSheet.Row>
+    <StickerSheet.Row rowTitle="focus">
+      <p className="font-family-paragraph">focus:bg-blue-200</p>
+      <p className="font-family-paragraph">background-color: #bde2f5</p>
+      <button
+        type="button"
+        tabIndex={0}
+        className="border-solid bg-white border-[black] font-family-paragraph w-[150px] rounded focus:bg-blue-200 py-16 px-12 text-center"
+      >
+        Focus me
+      </button>
+    </StickerSheet.Row>
+  </StickerSheet>
+)

package/src/_docs/pages/overview.mdx

@@ -0,0 +1,26 @@
+import { Meta } from "@storybook/blocks"
+import AnatomyDiagram from "../assets/tw-anatomy.png"
+
+<Meta title="Guides/Tailwind/Overview" />
+
+# Overview
+
+<br/>
+
+## Caveat before use
+This is an early release of the Kaizen Tailwind Preset - the API may change and evolve as we receive feedback from our teams. We will endeavour to assist where possible if classes or utilities are updated in the future.
+
+## What our package does
+The `@kaizen/tailwind` package is essentially a custom Tailwind preset. For more information about Tailwind presets, see their docs [here](https://tailwindcss.com/docs/presets). This package does not change how Tailwind works; it only defines the suffixes that can be applied when constructing utility classes.
+To see a list of utilities generated by our preset, see our [Utility Class Reference Docs](/story/systems-tailwind-utility-class-references-utility-class-references--page).
+The following diagram shows the construction of a utility class that adds a background of `blue-400` on hover. The modifier `hover:` and the prefix `bg-` are part of Tailwind by default. The suffix `gray-400` is defined by our preset, and represents one of our color design tokens.
+
+
+<img src={AnatomyDiagram} alt="Tailwind utility class anatomy" />
+
+```css
+.hover\:bg-blue-400:hover {
+  --tw-bg-opacity: 1;
+  background-color: rgb(0 139 214 / var(--tw-bg-opacity))
+}
+```

package/src/_docs/pages/spacing/margin.mdx

@@ -0,0 +1,27 @@
+import { Description, Meta, Story, Unstyled } from "@storybook/blocks"
+import { Card } from "~components/Card"
+import * as Examples from "./margin.stories"
+
+<Meta of={Examples} />
+
+# Margin
+
+<Description />
+
+<Unstyled>
+  <Card variant="informative" classNameOverride="w-fit mb-24">
+    <div className="font-family-paragraph p-24">
+      <p>
+        The padding prefix &apos;m-&apos; has been used in the examples in this
+        document, which compiles to the `margin` property in CSS.
+      </p>
+      <p>
+        Note that there are other prefixes (such as `ml-` for `margin-left`)
+        that can be used instead. Available padding prefixes can be referenced
+        <a href="https://tailwindcss.com/docs/margin#basic-usage">here</a>.
+      </p>
+    </div>
+  </Card>
+</Unstyled>
+
+<Story of={Examples.Margin} />

package/src/_docs/pages/spacing/margin.stories.tsx

@@ -0,0 +1,49 @@
+import React from "react"
+import { Meta, StoryFn } from "@storybook/react"
+import classnames from "classnames"
+import { TailwindStoryTemplate } from "~tailwind/_docs/utils/TailwindStoryTemplate"
+import { utilityDescription } from "~tailwind/_docs/utils/utilityDescription"
+import { kaizenTailwindTheme } from "~tailwind/tailwind-presets"
+
+const prefix = "m-"
+const classEntries: Array<{ utilityClassName: string; cssProperty: string }> =
+  Object.entries(kaizenTailwindTheme.spacing || []).map(
+    ([suffix, cssProperty]) => ({
+      utilityClassName: `${prefix}${suffix}`,
+      cssProperty,
+    })
+  )
+
+export default {
+  title: "Guides/Tailwind/Utility Class References/Spacing/Margin",
+  parameters: {
+    a11y: { disable: true },
+    chromatic: { disable: false },
+    docsLayout: "fullPage",
+    docs: {
+      description: {
+        component: utilityDescription(prefix, classEntries[0].utilityClassName),
+      },
+    },
+  },
+} satisfies Meta
+
+export const Margin: StoryFn<{ isReversed: boolean }> = ({ isReversed }) => (
+  <TailwindStoryTemplate
+    compiledCssPropertyName="margin"
+    classKeyValues={classEntries}
+    renderExampleComponent={(utilityClass): React.ReactElement => (
+      <div className="w-min border rounded">
+        <p
+          className={classnames(
+            "p-4 border border-dashed w-min rounded bg-blue-100",
+            utilityClass
+          )}
+        >
+          Margin
+        </p>
+      </div>
+    )}
+    isReversed={isReversed}
+  />
+)

package/src/_docs/pages/spacing/padding.mdx

@@ -0,0 +1,27 @@
+import { Description, Meta, Story, Unstyled } from "@storybook/blocks"
+import { Card } from "~components/Card"
+import * as Examples from "./padding.stories"
+
+<Meta of={Examples} />
+
+# Padding
+
+<Description />
+
+<Unstyled>
+  <Card variant="informative" classNameOverride="w-fit mb-24">
+    <div className="font-family-paragraph p-24">
+      <p>
+        The padding prefix &apos;p-&apos; has been used in the examples in this
+        document, which compiles to the `padding` property in CSS.
+      </p>
+      <p>
+        Note that there are other prefixes (such as `pl-` for `padding-left`)
+        that can be used instead. Available padding prefixes can be referenced
+        <a href="https://tailwindcss.com/docs/padding#basic-usage">here</a>.
+      </p>
+    </div>
+  </Card>
+</Unstyled>
+
+<Story of={Examples.Padding} />