@kaizen/tailwind 1.2.14 → 1.3.0

package/src/_docs/pages/spacing/padding.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 = "p-"
+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/Padding",
+  parameters: {
+    a11y: { disable: true },
+    chromatic: { disable: false },
+    docsLayout: "fullPage",
+    docs: {
+      description: {
+        component: utilityDescription(prefix, classEntries[0].utilityClassName),
+      },
+    },
+  },
+} satisfies Meta
+
+export const Padding: StoryFn<{ isReversed: boolean }> = ({ isReversed }) => (
+  <TailwindStoryTemplate
+    compiledCssPropertyName="padding"
+    classKeyValues={classEntries}
+    renderExampleComponent={(utilityClass): React.ReactElement => (
+      <p
+        className={classnames(
+          "border border-purple-100 w-min rounded bg-blue-100",
+          utilityClass
+        )}
+      >
+        Padding
+      </p>
+    )}
+    isReversed={isReversed}
+  />
+)

package/src/_docs/pages/typography/font-family.mdx

@@ -0,0 +1,10 @@
+import { Description, Meta, Story } from "@storybook/blocks"
+import * as Examples from "./font-family.stories"
+
+<Meta of={Examples} />
+
+# Font Family
+
+<Description />
+
+<Story of={Examples.FontFamily} />

package/src/_docs/pages/typography/font-family.stories.tsx

@@ -0,0 +1,41 @@
+import React from "react"
+import { Meta, StoryFn } from "@storybook/react"
+import { TailwindStoryTemplate } from "~tailwind/_docs/utils/TailwindStoryTemplate"
+import { utilityDescription } from "~tailwind/_docs/utils/utilityDescription"
+import { kaizenTailwindTheme } from "~tailwind/tailwind-presets"
+
+const prefix = "font-"
+const classEntries: Array<{ utilityClassName: string; cssProperty: string }> =
+  Object.entries(kaizenTailwindTheme.fontFamily || []).map(
+    ([suffix, cssPropertyArr]) => ({
+      utilityClassName: `${prefix}${suffix}`,
+      cssProperty: cssPropertyArr[0],
+    })
+  )
+
+export default {
+  title: "Guides/Tailwind/Utility Class References/Typography/Font Family",
+  parameters: {
+    a11y: { disable: true },
+    chromatic: { disable: false },
+    docsLayout: "fullPage",
+    docs: {
+      description: {
+        component: utilityDescription(prefix, classEntries[0].utilityClassName),
+      },
+    },
+  },
+} satisfies Meta
+
+export const FontFamily: StoryFn<{ isReversed: boolean }> = ({
+  isReversed,
+}) => (
+  <TailwindStoryTemplate
+    compiledCssPropertyName="font-family"
+    classKeyValues={classEntries}
+    renderExampleComponent={(utilityClass): React.ReactElement => (
+      <p className={utilityClass}>Aa</p>
+    )}
+    isReversed={isReversed}
+  />
+)

package/src/_docs/pages/typography/font-size.mdx

@@ -0,0 +1,10 @@
+import { Description, Meta, Story } from "@storybook/blocks"
+import * as Examples from "./font-size.stories"
+
+<Meta of={Examples} />
+
+# Font Size
+
+<Description />
+
+<Story of={Examples.FontSize} />

package/src/_docs/pages/typography/font-size.stories.tsx

@@ -0,0 +1,38 @@
+import React from "react"
+import { StoryFn } from "@storybook/react"
+import { TailwindStoryTemplate } from "~tailwind/_docs/utils/TailwindStoryTemplate"
+import { utilityDescription } from "~tailwind/_docs/utils/utilityDescription"
+import { kaizenTailwindTheme } from "~tailwind/tailwind-presets"
+
+const prefix = "text-"
+const classEntries = Object.entries(kaizenTailwindTheme.fontSize || []).map(
+  ([suffix, cssProperty]) => ({
+    utilityClassName: `${prefix}${suffix}`,
+    cssProperty,
+  })
+)
+
+export default {
+  title: "Guides/Tailwind/Utility Class References/Typography/Font Size",
+  parameters: {
+    a11y: { disable: true },
+    chromatic: { disable: false },
+    docsLayout: "fullPage",
+    docs: {
+      description: {
+        component: utilityDescription(prefix, classEntries[0].utilityClassName),
+      },
+    },
+  },
+}
+
+export const FontSize: StoryFn<{ isReversed: boolean }> = ({ isReversed }) => (
+  <TailwindStoryTemplate
+    compiledCssPropertyName="font-size"
+    classKeyValues={classEntries}
+    renderExampleComponent={(utilityClass): React.ReactElement => (
+      <p className={utilityClass}>Aa</p>
+    )}
+    isReversed={isReversed}
+  />
+)

package/src/_docs/pages/typography/font-weight.mdx

@@ -0,0 +1,10 @@
+import { Description, Meta, Story } from "@storybook/blocks"
+import * as Examples from "./font-weight.stories"
+
+<Meta of={Examples} />
+
+# Font Weight
+
+<Description />
+
+<Story of={Examples.FontWeight} />

package/src/_docs/pages/typography/font-weight.stories.tsx

@@ -0,0 +1,41 @@
+import React from "react"
+import { Meta, StoryFn } from "@storybook/react"
+import { TailwindStoryTemplate } from "~tailwind/_docs/utils/TailwindStoryTemplate"
+import { utilityDescription } from "~tailwind/_docs/utils/utilityDescription"
+import { kaizenTailwindTheme } from "~tailwind/tailwind-presets"
+
+const prefix = "font-"
+const classEntries: Array<{ utilityClassName: string; cssProperty: string }> =
+  Object.entries(kaizenTailwindTheme.fontWeight || []).map(
+    ([suffix, cssProperty]) => ({
+      utilityClassName: `${prefix}${suffix}`,
+      cssProperty,
+    })
+  )
+
+export default {
+  title: "Guides/Tailwind/Utility Class References/Typography/Font Weight",
+  parameters: {
+    a11y: { disable: true },
+    chromatic: { disable: false },
+    docsLayout: "fullPage",
+    docs: {
+      description: {
+        component: utilityDescription(prefix, classEntries[0].utilityClassName),
+      },
+    },
+  },
+} satisfies Meta
+
+export const FontWeight: StoryFn<{ isReversed: boolean }> = ({
+  isReversed,
+}) => (
+  <TailwindStoryTemplate
+    compiledCssPropertyName="font-weight"
+    classKeyValues={classEntries}
+    renderExampleComponent={(utilityClass): React.ReactElement => (
+      <p className={utilityClass}>Aa</p>
+    )}
+    isReversed={isReversed}
+  />
+)

package/src/_docs/pages/typography/line-height.mdx

@@ -0,0 +1,10 @@
+import { Description, Meta, Story } from "@storybook/blocks"
+import * as Examples from "./line-height.stories"
+
+<Meta of={Examples} />
+
+# Line Height
+
+<Description />
+
+<Story of={Examples.LineHeight} />

package/src/_docs/pages/typography/line-height.stories.tsx

@@ -0,0 +1,44 @@
+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 = "leading-"
+const classEntries: Array<{ utilityClassName: string; cssProperty: string }> =
+  Object.entries(kaizenTailwindTheme.lineHeight || []).map(
+    ([suffix, cssProperty]) => ({
+      utilityClassName: `${prefix}${suffix}`,
+      cssProperty,
+    })
+  )
+
+export default {
+  title: "Guides/Tailwind/Utility Class References/Typography/Line Height",
+  parameters: {
+    a11y: { disable: true },
+    chromatic: { disable: false },
+    docsLayout: "fullPage",
+    docs: {
+      description: {
+        component: utilityDescription(prefix, classEntries[0].utilityClassName),
+      },
+    },
+  },
+} satisfies Meta
+
+export const LineHeight: StoryFn<{ isReversed: boolean }> = ({
+  isReversed,
+}) => (
+  <TailwindStoryTemplate
+    compiledCssPropertyName="line-height"
+    classKeyValues={classEntries}
+    renderExampleComponent={(utilityClass): React.ReactElement => (
+      <p className={classnames("w-0", utilityClass)}>
+        Tutant Meenage Neetle Teetles
+      </p>
+    )}
+    isReversed={isReversed}
+  />
+)

package/src/_docs/pages/typography/max-text-width.mdx

@@ -0,0 +1,12 @@
+import { Description, Meta, Story } from "@storybook/blocks"
+import * as Examples from "./max-text-width.stories"
+
+<Meta of={Examples} />
+
+# Max width of text elements
+
+Each of our paragraph text sizes has a suggested max width for optimal reading. Following the same naming conventions as for font size ("text-...") and line height ("leading-..."), you can use the appropriate max width class ("max-w-...").
+
+<Description />
+
+<Story of={Examples.MaxTextWidth} />

package/src/_docs/pages/typography/max-text-width.stories.tsx

@@ -0,0 +1,60 @@
+import React from "react"
+import { Meta, StoryFn } from "@storybook/react"
+import { TailwindStoryTemplate } from "~tailwind/_docs/utils/TailwindStoryTemplate"
+import { utilityDescription } from "~tailwind/_docs/utils/utilityDescription"
+import { kaizenTailwindTheme } from "~tailwind/tailwind-presets"
+
+const prefix = "max-w-"
+const classEntries = Object.entries(
+  kaizenTailwindTheme.extend.maxWidth || []
+).map(([suffix, cssPropertyArr]) => ({
+  utilityClassName: `${prefix}${suffix}`,
+  cssProperty: cssPropertyArr as string,
+}))
+
+export default {
+  title: "Guides/Tailwind/Utility Class References/Typography/Max Text Width",
+  parameters: {
+    a11y: { disable: true },
+    chromatic: { disable: false },
+    docsLayout: "fullPage",
+    docs: {
+      description: {
+        component: utilityDescription(prefix, classEntries[0].utilityClassName),
+      },
+    },
+  },
+} satisfies Meta
+
+const fontClasses = {
+  "max-w-paragraph-lede": "text-paragraph-lede leading-paragraph-lede",
+  "max-w-paragraph": "text-paragraph leading-paragraph",
+  "max-w-paragraph-sm": "text-paragraph-sm leading-paragraph-sm",
+  "max-w-paragraph-xs": "text-paragraph-xs leading-paragraph-xs",
+}
+
+const getFontClass = (utilityClass: string): string =>
+  fontClasses[utilityClass as keyof typeof fontClasses] || ""
+
+export const MaxTextWidth: StoryFn<{ isReversed: boolean }> = ({
+  isReversed,
+}) => (
+  <TailwindStoryTemplate
+    compiledCssPropertyName="max-width"
+    classKeyValues={classEntries}
+    renderExampleComponent={(utilityClass): React.ReactElement => (
+      <>
+        <p className={[utilityClass, getFontClass(utilityClass)].join(" ")}>
+          Lorem ipsum dolor sit amet consectetur adipisicing elit. Iusto, optio
+          incidunt explicabo facilis ipsam, porro magni vero libero itaque rerum
+          deserunt quo molestiae expedita dolor? Alias iusto ad maiores odit! (
+          {[utilityClass, getFontClass(utilityClass)].join(" ")})
+        </p>
+        <code className="text-paragraph-sm bg-gray-300 py-4 px-8">
+          {[utilityClass, getFontClass(utilityClass)].join(" ")}
+        </code>
+      </>
+    )}
+    isReversed={isReversed}
+  />
+)

package/src/_docs/pages/typography/text-color.mdx

@@ -0,0 +1,10 @@
+import { Description, Meta, Story } from "@storybook/blocks"
+import * as Examples from "./text-color.stories"
+
+<Meta of={Examples} />
+
+# Text Color
+
+<Description />
+
+<Story of={Examples.TextColor} />

package/src/_docs/pages/typography/text-color.stories.tsx

@@ -0,0 +1,52 @@
+import React from "react"
+import { StoryFn } from "@storybook/react"
+import classnames from "classnames"
+import { TailwindStoryTemplate } from "~tailwind/_docs/utils/TailwindStoryTemplate"
+import { flattenEntries } from "~tailwind/_docs/utils/flattenEntries"
+import { utilityDescription } from "~tailwind/_docs/utils/utilityDescription"
+import { kaizenTailwindTheme } from "~tailwind/tailwind-presets"
+
+const prefix = "text-"
+const classEntries = flattenEntries(prefix, kaizenTailwindTheme.colors || {})
+
+export default {
+  title: "Guides/Tailwind/Utility Class References/Typography/Text Color",
+  parameters: {
+    a11y: { disable: true },
+    chromatic: { disable: false },
+    docsLayout: "fullPage",
+    docs: {
+      description: {
+        component: utilityDescription(prefix, classEntries[0].utilityClassName),
+      },
+    },
+  },
+}
+
+export const TextColor: StoryFn<{ isReversed: boolean }> = ({ isReversed }) => (
+  <TailwindStoryTemplate
+    compiledCssPropertyName="color"
+    classKeyValues={classEntries}
+    renderExampleComponent={(utilityClass): React.ReactElement => (
+      <div className="flex items-center h-100">
+        <p
+          className={classnames(
+            "font-family-paragraph p-8 rounded font-weight-display text-heading-3 m-0 mr-16",
+            utilityClass
+          )}
+        >
+          Light bg
+        </p>
+        <p
+          className={classnames(
+            "font-family-paragraph p-8 bg-[black] rounded font-weight-display text-heading-3 m-0",
+            utilityClass
+          )}
+        >
+          Dark bg
+        </p>
+      </div>
+    )}
+    isReversed={isReversed}
+  />
+)

package/src/_docs/pages/utility-class-helpers-overview.mdx

@@ -0,0 +1,95 @@
+import { Meta, Unstyled } from "@storybook/blocks"
+import { LinkTo } from "~storybook/components/LinkTo"
+import CopyUtilityClass from "~tailwind/_docs/assets/copy-utility-class.gif?url"
+import UtilitySearchResult from "~tailwind/_docs/assets/utility-search-result.png?url"
+import { TailwindStoryTemplate } from "~tailwind/_docs/utils/TailwindStoryTemplate"
+
+<Meta title="Guides/Tailwind/Utility Class References/Overview" />
+
+# Utility Class References
+
+The Utility Class References section provides a list of utilities made available through the `@kaizen/tailwind` preset.
+For more information on the preset itself, see <LinkTo pageId="systems-tailwind-overview">here</LinkTo>.
+
+Note that this section only provides references for Kaizen's _custom_ utilities.
+In other words, if you can't find a utility class here, it's probably because it's unchanged from the Tailwind default.
+As an example, `borderColor` is listed in this section because we have a custom preset for it. `width` is _not_ here however, because it's unchanged from the Tailwind Default, and you can search for it in their [docs](https://tailwindcss.com/docs/width).
+
+- [Structure](#structure)
+- [Example usage](#example-usage)
+
+<br/>
+
+## Structure
+
+The references provide the following structure for each utility class:
+
+<Unstyled>
+<div className="w-100">
+  <TailwindStoryTemplate
+    compiledCssPropertyName="width"
+    classKeyValues={[{utilityClassName: "text-heading-1", cssProperty: "2.125rem"}]}
+    renderExampleComponent={cssProperty => (
+      <p style={{ fontSize: cssProperty }}>Aa</p>
+    )}
+  />
+</div>
+</Unstyled>
+
+<br/>
+<br/>
+
+### Utility Class
+
+This is the name of the utility class itself. This is the string that you pass to `class` or `className`.
+
+### Compiled CSS
+
+Represents the CSS property that Tailwind will compile for you when it recognizes the corresponding utility class.
+
+### Example
+
+A visual representation of the CSS generated by the utility class. You can inspect this element in the DOM to see the utility class in action.
+
+<br/>
+
+## Example usage
+
+**Goal:** Add our default border radius (`7px`) to the following component.
+
+```html
+<div className="border-solid w-max border-blue-500 bg-blue-100 px-12">
+  <p className="font-family-paragraph text-blue-700">Example</p>
+</div>
+```
+
+### 1. Locate the Border Radius docs
+
+<div className="max-w-[600px]">
+  <img src={UtilitySearchResult} alt="Utility class search result" />
+</div>
+
+<p>Can&apos;t find it here? That means we don&apos;t have a custom preset for it, and the utility class you need will be unchanged from the Tailwind Default.</p>
+<p>Search in the [Tailwind docs](https://tailwindcss.com/docs/installation) instead.</p>
+
+<br/>
+<br/>
+
+### 2. Find the utility class that compiles to the desired CSS, and copy it
+
+<img src={CopyUtilityClass} alt="Copy utility class" />
+
+<br/>
+<br/>
+
+### 3. Add the utility class to the element
+
+```tsx
+<div className="rounded ...">...</div>
+```
+
+```html
+<div className="rounded border-solid w-max border-blue-500 bg-blue-100 px-12">
+  <p className="font-family-paragraph text-blue-700">Example</p>
+</div>
+```

package/src/_docs/pages/working-with-tailwind.mdx

@@ -0,0 +1,85 @@
+import { Canvas, Meta } from "@storybook/blocks"
+import * as Examples from "./working-with-tailwind.stories"
+
+<Meta of={Examples} />
+
+# Working with Tailwind
+
+This page describes and demonstrates the main intended use cases for this package, as well as our recommended escape hatch.
+
+- [Spacing and layouts](#spacing-and-layouts)
+- [Altering Kaizen components with classnameOverride](#altering-kaizen-components-with-classnameoverride)
+- [Creating bespoke components](#creating-bespoke-components)
+- [Recommended escape hatch](#recommended-escape-hatch)
+
+<br/>
+
+## Spacing and layouts
+
+For information about Cultureamp's spacing and layout system in general, see [here](/story/systems-layout-and-spacing--page)
+
+When building a page, ideally [Kaizen](https://github.com/cultureamp/kaizen-design-system) components should be used as much as possible, with the front-end engineer responsible for the spacing between them. In these cases, our Tailwind preset makes it easy by adding our spacing tokens to Tailwind's core spacing modules.
+
+Here, Tailwind has been used to center a Kaizen button within a div.
+
+<Canvas of={Examples.TailwindExampleSpacingAndLayouts} />
+
+- `flex`: Adds `display: flex`
+- `justify-center`: Adds `justify-content: center`
+- `border-solid`: Adds `border-style: solid`
+- `p-16`: Adds `padding: 1rem` (`16px` = `1rem` - see the [layout and spacing docs](/story/systems-layout-and-spacing--page) for more on this)
+
+Here's a more complex example, where some `<Card>` components and text have been spaced and laid out with Tailwind:
+
+<Canvas of={Examples.TailwindExampleSpacingAndLayoutsComplex} />
+
+<br/>
+
+## Altering Kaizen components with classNameOverride
+
+If a Kaizen component supports classNameOverride, Tailwind classes can also be used.
+This is particularly useful for adding margins to Kaizen components. In this example, our preset is being used to add `margin-right: 1.5rem` to Kaizen's `<Card/>` component, without the need to wrap it in a div.
+
+<Canvas of={Examples.TailwindExampleClassNameOverrideMargin} />
+
+In this example, a Tailwind css rule is being applied to a Kaizen `<Heading />` component to ensure that the first letter is capitalized.
+
+<Canvas of={Examples.TailwindExampleClassNameOverrideHeading} />
+
+- first-letter:capitalize: Adds text-transform: capitalize on the first-letter pseudo selector
+
+<br/>
+
+## Creating bespoke components
+Occasionally snowflakes need to be created. This package provides common utilities based on our design tokens, such as color, border-radius, and font-family. Ideally, as much styling of bespoke components should be handled with Tailwind, but keep in mind that scss can still be used when necessary.
+
+Here is an example of our TW package being used to create a bespoke, non-Kaizen component:
+
+<Canvas of={Examples.TailwindExampleSnowflake} />
+
+<br/>
+
+### The container div
+- `w-[250px]`: Adds `width: 250px`. This is an example of an arbitrary value being used to inject a custom suffix
+- `rounded`: Adds `border-radius: 7px`. This is one of our custom preset values
+- `border-dashed`: Adds `border-style: dashed`
+- `border-red-500`: Adds `border-color: #c93b55` (our red-500 design token)
+- `bg-blue-100`: Adds `background: #e6f6ff` (our blue-100 design token)
+- `text-center`: Adds `text-align: center`
+
+### The p tag
+- `m-0`: Adds `margin: 0`
+- `p-12`: Adds `padding: .75rem` (12px = 0.75rem)
+- `pl-16`: Adds `padding-left: 1rem` (16px = 1rem)
+- `font-family-paragraph`: Adds `font-family: "Inter", "Noto Sans", ...`
+- `text-blue-500`: Adds `color: #0168b3` (our blue-500 design token)
+
+<br/>
+
+## Recommended Escape Hatch
+
+If you find yourself needing to add styles in a way that is unsupported or otherwise difficult in Tailwind, the recommended alternative is CSS. CSS classes can be added alongside Tailwind utility classes without trouble, and the Tailwind docs recommend some useful post-css plugins [here](https://tailwindcss.com/docs/using-with-preprocessors#using-sass-less-or-stylus).
+
+### Why not SCSS?
+- SCSS is currently a contained option, so writing new SCSS in our codebases is discouraged.
+- The Tailwind docs explicitly recommend <em>not</em> using Tailwind with preprocessors, as it leads to all sorts of quirks and work-arounds. Read more [here](https://tailwindcss.com/docs/using-with-preprocessors#using-sass-less-or-stylus).