@pantheon-systems/pds-toolkit-react 2.0.0-alpha.7 → 2.0.0-alpha.9

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@pantheon-systems/pds-toolkit-react",
 	"technology": "React",
-	"version": "2.0.0-alpha.7",
+	"version": "2.0.0-alpha.9",
 	"description": "PDS toolkit built using the React framework",
 	"publishConfig": {
 		"access": "public",
@@ -27,10 +27,13 @@
 			"types": "./dist/index.d.ts",
 			"import": "./dist/index.js"
 		},
+		"./tailwind/v3/preset": "./tailwind/v3/preset.cjs",
+		"./tailwind/v4/theme.css": "./tailwind/v4/theme.css",
 		"./*": "./dist/*"
 	},
 	"files": [
-		"dist"
+		"dist",
+		"tailwind"
 	],
 	"sideEffects": [
 		"*.css"
@@ -99,13 +102,13 @@
 		"@csstools/postcss-design-tokens": "^2.0.4",
 		"@csstools/postcss-global-data": "^1.0.3",
 		"@playwright/test": "^1.36.2",
-		"@storybook/addon-a11y": "^10.2.3",
-		"@storybook/addon-docs": "^10.2.3",
-		"@storybook/addon-links": "^10.2.3",
-		"@storybook/addon-mcp": "^0.2.0",
+		"@storybook/addon-a11y": "^10.3.0",
+		"@storybook/addon-docs": "^10.3.0",
+		"@storybook/addon-links": "^10.3.0",
+		"@storybook/addon-mcp": "^0.5.0",
 		"@storybook/addon-webpack5-compiler-swc": "^4.0.2",
-		"@storybook/react-vite": "^10.2.3",
-		"@storybook/react-webpack5": "^10.2.3",
+		"@storybook/react-vite": "^10.3.0",
+		"@storybook/react-webpack5": "^10.3.0",
 		"@types/prismjs": "^1.26.5",
 		"@types/react": "^19.2.2",
 		"@typescript-eslint/eslint-plugin": "^8.47.0",
@@ -124,7 +127,7 @@
 		"eslint-plugin-react": "^7.32.2",
 		"eslint-plugin-simple-import-sort": "^12.1.1",
 		"eslint-plugin-sort-destructure-keys": "^2.0.0",
-		"eslint-plugin-storybook": "^10.2.3",
+		"eslint-plugin-storybook": "^10.3.0",
 		"eslint-plugin-typescript-sort-keys": "^3.3.0",
 		"fast-glob": "^3.3.2",
 		"husky": "^8.0.3",
@@ -142,7 +145,8 @@
 		"prettier-plugin-css-order": "^2.1.2",
 		"react": "^18.2.0",
 		"react-dom": "^18.2.0",
-		"storybook": "^10.2.3",
+		"react-router-dom": "^6.13.0",
+		"storybook": "^10.3.0",
 		"tsc-alias": "^1.8.16",
 		"typescript": "^5.4.5",
 		"vite": "^7.2.2",
@@ -172,7 +176,7 @@
 		"react-code-block": "^1.1.1",
 		"react-day-picker": "^9.11.1",
 		"react-device-detect": "^2.2.3",
-		"react-router-dom": "^6.13.0",
+		"react-hotkeys-hook": "^4.5.1",
 		"react-toastify": "^9.0.3"
 	},
 	"optionalDependencies": {

package/tailwind/README.md

@@ -0,0 +1,220 @@
+# PDS Tailwind Configuration
+
+Tailwind CSS configs that map Pantheon Design System tokens to Tailwind utilities. Available for both Tailwind v3 and v4.
+
+> **Note:** Using Tailwind CSS alongside PDS is not the recommended approach. PDS components handle their own styling. This configuration is provided so that UI built outside the scope of PDS components uses correct design system values rather than arbitrary ones.
+
+---
+
+## Prerequisites
+
+Both configs require `pds-core.css` to be loaded globally in your app. This provides the `--pds-*` CSS custom properties that the Tailwind utilities reference at runtime.
+
+Import it as a JavaScript import in your app's root layout — this ensures reliable module resolution via the package `exports` map:
+
+```ts
+import '@pantheon-systems/pds-toolkit-react/css/pds-core.css';
+```
+
+> **Note:** Use `css/pds-core.css`, not `dist/css/pds-core.css`. The package exports map handles the `dist/` prefix automatically. Using a CSS `@import` instead of a JS import can cause resolution failures in some bundlers (including Next.js with Turbopack).
+
+---
+
+## Tailwind v4
+
+**Recommended for new projects.**
+
+### Setup
+
+In `app/layout.tsx` (or your root layout):
+
+```ts
+import '@pantheon-systems/pds-toolkit-react/css/pds-core.css';
+import './globals.css';
+```
+
+In `app/globals.css`:
+
+```css
+/* Tailwind layers — imported separately to exclude preflight */
+@import 'tailwindcss/theme' layer(theme);
+@import 'tailwindcss/utilities' layer(utilities);
+
+/* PDS theme overrides */
+@import '@pantheon-systems/pds-toolkit-react/tailwind/v4/theme.css';
+```
+
+> **Why not `@import "tailwindcss"`?**
+> The single `@import "tailwindcss"` shorthand includes Tailwind's preflight CSS reset, which conflicts with PDS base styles. Importing the layers individually lets you skip preflight.
+
+No `tailwind.config.js` is needed.
+
+---
+
+## Tailwind v3
+
+### Setup
+
+```bash
+npm install tailwindcss@3
+```
+
+`tailwind.config.js`:
+
+```js
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+	presets: [require('@pantheon-systems/pds-toolkit-react/tailwind/v3/preset')],
+	content: ['./src/**/*.{js,ts,jsx,tsx}'],
+};
+```
+
+In `app/layout.tsx` (or your root layout):
+
+```ts
+import '@pantheon-systems/pds-toolkit-react/css/pds-core.css';
+import './globals.css';
+```
+
+`app/globals.css`:
+
+```css
+/* Tailwind directives */
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+Preflight is disabled automatically by the preset.
+
+---
+
+## What's included
+
+### Colors
+
+All values reference PDS CSS custom properties — dark mode works automatically.
+
+| Group               | Example utility                | PDS token                               |
+| ------------------- | ------------------------------ | --------------------------------------- |
+| `bg-*`              | `bg-bg-default`                | `--pds-color-bg-default`                |
+| `fg-*`              | `text-fg-default`              | `--pds-color-fg-default`                |
+| `text-*`            | `text-text-secondary`          | `--pds-color-text-default-secondary`    |
+| `border-*`          | `border-border-input`          | `--pds-color-border-input`              |
+| `interactive-*`     | `text-interactive-link`        | `--pds-color-interactive-link-default`  |
+| `status-{type}-*`   | `bg-status-success-background` | `--pds-color-status-success-background` |
+| `brand-primary-*`   | `bg-brand-primary-400`         | `--pds-color-brand-primary-400`         |
+| `brand-secondary-*` | `bg-brand-secondary`           | `--pds-color-brand-secondary-default`   |
+| `brand-accent-*`    | `text-brand-accent`            | `--pds-color-brand-accent-default`      |
+
+### Spacing
+
+The PDS named scale replaces Tailwind's default numeric scale. Use semantic keys like `p-m`, `gap-xl`, `mt-2xl`.
+
+```html
+<div class="p-m gap-xl mt-2xl">...</div>
+```
+
+Common Tailwind numeric values are also aliased to their nearest PDS equivalent, so `p-4` still works and stays in sync with the token:
+
+| Tailwind | PDS key | Value   |
+| -------- | ------- | ------- |
+| `p-1`    | `p-4xs` | 0.25rem |
+| `p-2`    | `p-2xs` | 0.5rem  |
+| `p-3`    | `p-s`   | 0.75rem |
+| `p-4`    | `p-m`   | 1rem    |
+| `p-5`    | `p-l`   | 1.25rem |
+| `p-6`    | `p-xl`  | 1.5rem  |
+| `p-8`    | `p-2xl` | 2rem    |
+| `p-10`   | `p-3xl` | 2.5rem  |
+| `p-12`   | `p-4xl` | 3rem    |
+| `p-16`   | `p-5xl` | 4rem    |
+
+Values like `p-7`, `p-9`, `p-11` (which don't have a clean PDS equivalent) are not aliased and will not generate any CSS.
+
+> **Numeric aliases use CSS variable references**, not hardcoded values. If a PDS spacing token ever changes, `p-4` will automatically reflect the new value — no config update needed.
+
+### Typography
+
+```html
+<p class="font-sans text-m font-normal leading-m">Body text</p>
+<h2 class="font-sans text-2xl font-semibold leading-s">Heading</h2>
+```
+
+| Scale | Font size    | Font family             | Font weight                                     | Line height         | Letter spacing      |
+| ----- | ------------ | ----------------------- | ----------------------------------------------- | ------------------- | ------------------- |
+| Keys  | `xs` – `9xl` | `sans`, `serif`, `mono` | `light`, `normal`, `medium`, `semibold`, `bold` | `s`, `m`, `l`, `xl` | `s`, `m`, `l`, `xl` |
+
+### Border radius
+
+```html
+<div class="rounded-container">Card</div>
+<button class="rounded-button">Button</button>
+<input class="rounded-input" />
+```
+
+Keys: `none`, `DEFAULT` (`rounded`), `button`, `input`, `container`, `bar`, `full`
+
+### Z-index
+
+```html
+<div class="z-modal">Modal</div>
+<nav class="z-navigation">Nav</nav>
+```
+
+Keys: `navigation`, `dropdown`, `notifications`, `overlay`, `modal`, `max`
+
+### Max width
+
+Matches PDS `Container` component breakpoints. Use when building layout sections outside PDS container components.
+
+```html
+<div class="max-w-standard mx-auto px-m">...</div>
+```
+
+Keys: `narrow` (1024px), `standard` (1200px), `wide` (1440px), `x-wide` (1600px)
+
+---
+
+## Important caveats
+
+### Borders require an explicit border-style
+
+The PDS preset resets `border-style` to `none` on all elements so that borders are fully opt-in. This prevents phantom borders on elements that pick up a non-zero `border-width` from PDS components, inheritance, or browser defaults. When adding borders with Tailwind, always include a border-style class (`border-solid`, `border-dashed`, or `border-dotted`):
+
+```html
+<div class="border border-solid border-border-default">...</div>
+<div class="border-b border-solid border-border-separator">Divider</div>
+```
+
+### Opacity modifiers are not supported
+
+Tailwind's opacity modifier syntax (`bg-bg-default/50`) does not work with CSS variable color references. This is a known Tailwind limitation — the compiler cannot decompose a CSS variable into RGB channels. Avoid using opacity modifiers with PDS colors.
+
+### Apply Tailwind utilities to your own elements, not PDS components
+
+PDS components are styled with scoped BEM classes. Do not use Tailwind utilities to override PDS component styles — use component props and the `className` prop for layout adjustments only. Applying Tailwind utility classes to PDS component internals will lead to unpredictable results.
+
+```jsx
+// ✅ Tailwind for your layout, PDS for the component
+<div class="flex gap-m items-center">
+  <Button label="Save" variant="primary" />
+</div>
+
+// ❌ Don't override PDS component internals with Tailwind
+<Button label="Save" className="text-red-500 bg-blue-200" />
+```
+
+### Import order matters
+
+`pds-core.css` must be imported before Tailwind. If Tailwind's utilities load before PDS variables are defined, the CSS custom property references will resolve to empty values.
+
+### Scanning for class names (`@source` in v4)
+
+Tailwind v4 automatically scans your project files for class names. If your source files are outside the default scan path (common in monorepos), add a `@source` directive to your CSS entry point:
+
+```css
+@source './src/**/*.{js,ts,jsx,tsx}';
+```
+
+This is your project's responsibility — the PDS package does not need to be scanned (PDS components do not use Tailwind class names internally).