@pantheon-systems/pds-toolkit-react 2.0.0-alpha.1 → 2.0.0-alpha.11

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).

package/tailwind/TESTING.md

@@ -0,0 +1,457 @@
+# Tailwind Configuration — Testing Plan
+
+Test the v3 preset and v4 theme against real Next.js projects before shipping.
+Create one project per Tailwind version.
+
+---
+
+## Setup: Install PDS Locally
+
+Before creating test projects, pack the local PDS package into a tarball.
+This is more reliable than `npm link` and tests exactly what would be published.
+
+```bash
+# In the pds-toolkit-react repo root — run build:lib first so dist/ exists
+npm run build:lib
+
+# Pack into a tarball (creates e.g. pantheon-systems-pds-toolkit-react-2.0.0-alpha.7.tgz)
+npm pack
+```
+
+You'll reference this tarball when installing into each test project.
+
+---
+
+## Project A — Tailwind v3
+
+### 1. Create the project
+
+```bash
+npx create-next-app@latest pds-tw-test-v3 \
+  --typescript --no-tailwind --no-eslint --no-src-dir --app
+cd pds-tw-test-v3
+npm install tailwindcss@3 postcss autoprefixer
+npx tailwindcss init -p
+```
+
+### 2. Install PDS locally
+
+```bash
+npm install /path/to/pds-toolkit-react/pantheon-systems-pds-toolkit-react-*.tgz
+```
+
+### 3. Configure Tailwind
+
+Replace `tailwind.config.js` contents:
+
+```js
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+	presets: [require('@pantheon-systems/pds-toolkit-react/tailwind/v3/preset')],
+	content: ['./app/**/*.{js,ts,jsx,tsx}'],
+};
+```
+
+### 4. Configure global CSS
+
+Add to the top of `app/layout.tsx` (before `./globals.css`):
+
+```tsx
+import '@pantheon-systems/pds-toolkit-react/css/pds-core.css';
+import './globals.css';
+```
+
+Replace `app/globals.css` contents:
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+> **Note:** Import pds-core.css as a JS import in layout.tsx rather than a CSS
+> `@import` in globals.css. Next.js module resolution handles package `exports`
+> maps correctly for JS imports; CSS `@import` resolution is less reliable.
+> The path is `css/pds-core.css` (not `dist/css/`) — the package exports map
+> handles the `dist/` prefix automatically.
+
+### 5. Run the project
+
+```bash
+npm run dev
+```
+
+---
+
+## Project B — Tailwind v4
+
+### 1. Create the project
+
+```bash
+npx create-next-app@latest pds-tw-test-v4 \
+  --typescript --no-tailwind --no-eslint --no-src-dir --app
+cd pds-tw-test-v4
+npm install tailwindcss@latest
+```
+
+### 2. Install PDS locally
+
+```bash
+npm install /path/to/pds-toolkit-react/pantheon-systems-pds-toolkit-react-*.tgz
+```
+
+### 3. Configure global CSS
+
+Add to the top of `app/layout.tsx` (before `./globals.css`):
+
+```tsx
+import '@pantheon-systems/pds-toolkit-react/css/pds-core.css';
+import './globals.css';
+```
+
+Replace `app/globals.css` contents:
+
+```css
+@import 'tailwindcss/theme' layer(theme);
+@import 'tailwindcss/utilities' layer(utilities);
+
+@import '@pantheon-systems/pds-toolkit-react/tailwind/v4/theme.css';
+```
+
+No `tailwind.config.js` needed.
+
+### 4. Run the project
+
+```bash
+npm run dev
+```
+
+---
+
+## Test Page
+
+Replace `app/page.tsx` in both projects with the following. It exercises every
+token category and gives you a single visual reference to review.
+
+```tsx
+export default function Page() {
+	return (
+		<div className='p-xl font-sans'>
+			<h1 className='text-2xl font-semibold leading-s tracking-s mb-xl text-text-default'>
+				PDS Tailwind Test Page
+			</h1>
+
+			{/* ── Colors ──────────────────────────────────────────────── */}
+			<section className='mb-2xl'>
+				<h2 className='text-l font-semibold mb-m text-text-default'>Colors</h2>
+
+				<div className='flex gap-m flex-wrap mb-m'>
+					<div className='p-m rounded-container bg-bg-default border border-border-default'>
+						<span className='text-text-default text-s'>bg-default</span>
+					</div>
+					<div className='p-m rounded-container bg-bg-secondary border border-border-default'>
+						<span className='text-text-default text-s'>bg-secondary</span>
+					</div>
+					<div className='p-m rounded-container bg-bg-reverse'>
+						<span className='text-text-reverse text-s'>bg-reverse</span>
+					</div>
+				</div>
+
+				<div className='flex gap-m flex-wrap mb-m'>
+					<div className='p-m rounded-container bg-status-info-background'>
+						<span className='text-status-info-foreground text-s'>info</span>
+					</div>
+					<div className='p-m rounded-container bg-status-success-background'>
+						<span className='text-status-success-foreground text-s'>
+							success
+						</span>
+					</div>
+					<div className='p-m rounded-container bg-status-warning-background'>
+						<span className='text-status-warning-foreground text-s'>
+							warning
+						</span>
+					</div>
+					<div className='p-m rounded-container bg-status-critical-background'>
+						<span className='text-status-critical-foreground text-s'>
+							critical
+						</span>
+					</div>
+					<div className='p-m rounded-container bg-status-discovery-background'>
+						<span className='text-status-discovery-foreground text-s'>
+							discovery
+						</span>
+					</div>
+				</div>
+
+				<div className='flex gap-m flex-wrap'>
+					<div className='p-m rounded-container bg-brand-primary'>
+						<span className='text-white text-s'>brand-primary</span>
+					</div>
+					<div className='p-m rounded-container bg-brand-primary-200'>
+						<span className='text-text-default text-s'>brand-primary-200</span>
+					</div>
+					<div className='p-m rounded-container bg-brand-secondary'>
+						<span className='text-text-default text-s'>brand-secondary</span>
+					</div>
+					<div className='p-m rounded-container bg-brand-accent'>
+						<span className='text-white text-s'>brand-accent</span>
+					</div>
+				</div>
+			</section>
+
+			{/* ── Interactive / Links ──────────────────────────────────── */}
+			<section className='mb-2xl'>
+				<h2 className='text-l font-semibold mb-m text-text-default'>
+					Interactive
+				</h2>
+				<a
+					href='#'
+					className='text-interactive-link hover:text-interactive-link-hover text-m'
+				>
+					Interactive link
+				</a>
+			</section>
+
+			{/* ── Spacing ─────────────────────────────────────────────── */}
+			<section className='mb-2xl'>
+				<h2 className='text-l font-semibold mb-m text-text-default'>Spacing</h2>
+				<div className='flex gap-xs items-end'>
+					{[
+						'6xs',
+						'5xs',
+						'4xs',
+						'3xs',
+						'2xs',
+						'xs',
+						's',
+						'm',
+						'l',
+						'xl',
+						'2xl',
+					].map((size) => (
+						<div
+							key={size}
+							className={`bg-brand-primary-200 w-m`}
+							style={{ height: `var(--pds-spacing-${size})` }}
+						/>
+					))}
+				</div>
+				<p className='text-s text-text-secondary mt-s'>
+					Spacing scale 6xs → 2xl (heights driven by CSS vars, gap uses Tailwind
+					spacing)
+				</p>
+			</section>
+
+			{/* ── Typography ──────────────────────────────────────────── */}
+			<section className='mb-2xl'>
+				<h2 className='text-l font-semibold mb-m text-text-default'>
+					Typography
+				</h2>
+				<p className='font-sans text-xs mb-xs text-text-default'>
+					font-sans / text-xs — Inter
+				</p>
+				<p className='font-sans text-m mb-xs text-text-default'>
+					font-sans / text-m
+				</p>
+				<p className='font-sans text-xl font-semibold mb-xs text-text-default'>
+					font-sans / text-xl / font-semibold
+				</p>
+				<p className='font-compact text-xl mb-xs text-text-default'>
+					font-compact / text-xl — Inter Tight
+				</p>
+				<p className='font-serif text-xl mb-xs text-text-default'>
+					font-serif / text-xl — IBM Plex Serif
+				</p>
+				<p className='font-mono text-m text-text-default'>
+					font-mono / text-m — Source Code Pro
+				</p>
+			</section>
+
+			{/* ── Border Radius ───────────────────────────────────────── */}
+			<section className='mb-2xl'>
+				<h2 className='text-l font-semibold mb-m text-text-default'>
+					Border Radius
+				</h2>
+				<div className='flex gap-m flex-wrap'>
+					{[
+						'rounded',
+						'rounded-button',
+						'rounded-input',
+						'rounded-container',
+						'rounded-bar',
+						'rounded-full',
+					].map((cls) => (
+						<div
+							key={cls}
+							className={`${cls} bg-brand-primary-200 p-m text-s text-text-default`}
+						>
+							{cls}
+						</div>
+					))}
+				</div>
+			</section>
+
+			{/* ── Z-index ─────────────────────────────────────────────── */}
+			<section className='mb-2xl'>
+				<h2 className='text-l font-semibold mb-m text-text-default'>Z-index</h2>
+				<div className='relative h-xl'>
+					<div className='absolute z-navigation bg-brand-primary-200 p-xs rounded text-xs text-text-default'>
+						z-navigation (100)
+					</div>
+				</div>
+				<p className='text-s text-text-secondary mt-xs'>
+					Inspect computed style to confirm z-index values resolve correctly.
+				</p>
+			</section>
+
+			{/* ── Max Width ───────────────────────────────────────────── */}
+			<section className='mb-2xl'>
+				<h2 className='text-l font-semibold mb-m text-text-default'>
+					Max Width
+				</h2>
+				<div className='max-w-narrow bg-bg-secondary p-m rounded-container mb-s border border-border-default'>
+					<span className='text-s text-text-default'>
+						max-w-narrow (1024px)
+					</span>
+				</div>
+				<div className='max-w-standard bg-bg-secondary p-m rounded-container border border-border-default'>
+					<span className='text-s text-text-default'>
+						max-w-standard (1200px)
+					</span>
+				</div>
+			</section>
+
+			{/* ── Dark Mode ───────────────────────────────────────────── */}
+			<section className='mb-2xl'>
+				<h2 className='text-l font-semibold mb-m text-text-default'>
+					Dark Mode
+				</h2>
+				<p className='text-s text-text-secondary mb-m'>
+					The box below manually applies the PDS dark theme attribute. Colors
+					inside should switch — no Tailwind dark: prefix needed.
+				</p>
+				<div data-theme='dark' className='p-xl rounded-container'>
+					<div className='bg-bg-default p-m rounded-container'>
+						<p className='text-text-default text-m font-semibold'>
+							Dark bg-default
+						</p>
+						<p className='text-text-secondary text-s'>Dark text-secondary</p>
+						<div className='mt-m p-m rounded-container bg-status-info-background'>
+							<span className='text-status-info-foreground text-s'>
+								Dark status-info
+							</span>
+						</div>
+					</div>
+				</div>
+			</section>
+		</div>
+	);
+}
+```
+
+---
+
+## Checklist
+
+Work through both projects and check each item. Open browser DevTools to
+inspect computed styles when you need to verify a value resolves correctly.
+
+### Preflight
+
+- [ ] Browser default margins on `<h1>`, `<p>`, `<ul>` are **not** reset (preflight is disabled — headings should still have default browser size/weight until you explicitly set them)
+- [ ] PDS base styles from `pds-core.css` are applied (e.g. correct font on `body`)
+- [ ] Borders only appear on elements that explicitly include `border-solid` — no global border bleed (preflight normally sets `border-style: solid` globally; without it you must add `border-solid` per element)
+
+### Colors — backgrounds and foregrounds
+
+- [ ] `bg-bg-default` renders white (light mode)
+- [ ] `bg-bg-secondary` renders light gray
+- [ ] `bg-bg-reverse` renders dark
+- [ ] `text-fg-reverse` is visible on `bg-bg-reverse`
+- [ ] `text-fg-default` and `text-fg-secondary` are both visible on light surfaces
+
+### Colors — status
+
+- [ ] All five status backgrounds render distinct colors (info, success, warning, critical, discovery)
+- [ ] Status foreground text is readable on its status background
+- [ ] Status border color is visible when `border border-solid border-status-info-border` is applied
+- [ ] Status dot colors render as small circles
+
+### Colors — data visualization
+
+- [ ] `bg-datavis-1` through `bg-datavis-5` each render a distinct color
+
+### Dark mode
+
+- [ ] Inside `data-theme="dark"`, `bg-bg-default` renders dark (not white)
+- [ ] `text-fg-default` is light-colored inside the dark section
+- [ ] Status colors shift appropriately in dark mode
+- [ ] No Tailwind `dark:` prefix was needed — color changes happen via CSS vars
+
+### Interactive
+
+- [ ] `text-interactive-link` renders the PDS link color
+- [ ] `:hover` changes to `text-interactive-link-hover` (test in browser)
+
+### Spacing
+
+- [ ] `gap-m`, `p-xl`, `mb-2xl` all produce visible spacing
+- [ ] Inspect computed style on a `p-m` element — should show the rem value from `--pds-spacing-m`
+- [ ] `gap-xs` in the spacing row produces tighter gaps than `gap-m`
+
+### Typography
+
+- [ ] `text-xs` is noticeably smaller than `text-xl`
+- [ ] `font-semibold` is visually heavier than `font-normal`
+- [ ] PDS body font (Inter) is applied globally via `pds-core.css` — no Tailwind font-family utility needed
+
+### Border radius
+
+- [ ] `rounded` (DEFAULT) is slightly rounded
+- [ ] `rounded-input` is slightly more rounded than `rounded`
+- [ ] `rounded-container` is more rounded than `rounded-input`
+- [ ] `rounded-button` and `rounded-bar` are pill-shaped (both map to `--pds-border-radius-button` / `--pds-border-radius-bar`)
+
+### Z-index
+
+- [ ] Inspect computed `z-index` on `z-navigation` element — should be `100`
+- [ ] `z-modal` should compute to `900`
+
+### Max width
+
+- [ ] `max-w-narrow` constrains width at 1024px
+- [ ] `max-w-standard` is wider than `max-w-narrow`
+- [ ] `max-w-wide` is wider than `max-w-standard`
+- [ ] `max-w-x-wide` is wider than `max-w-wide`
+- [ ] All four blocks visually confirm the width difference on a wide viewport
+
+---
+
+## v4-Specific Checks
+
+- [ ] No `tailwind.config.js` exists in the project — v4 works without it
+- [ ] Removing the `@import 'tailwindcss/theme'` line breaks utilities (confirms the layer import is working)
+- [ ] Swap to `@import 'tailwindcss'` (the shorthand) — verify preflight fires and breaks PDS styles, then revert
+- [ ] Inspect `--color-bg-default` in DevTools `:root` — should be present as a CSS custom property
+
+## v3-Specific Checks
+
+- [ ] `tailwind.config.js` preset resolves without error on startup
+- [ ] Running `npx tailwindcss --content './app/**/*.tsx' --input ./app/globals.css` produces output CSS with PDS class names
+- [ ] `p-4` generates output and resolves to the same value as `p-m` (confirms numeric alias is working)
+- [ ] `p-7` generates no output (confirms unmapped in-between values are intentionally excluded)
+- [ ] Adding a truly unknown class (e.g. `p-99`) produces nothing in the output
+
+---
+
+## If Something Doesn't Work
+
+| Symptom                                    | Likely cause                                                                                                                    |
+| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| All colors render as empty / transparent   | `pds-core.css` not loaded before Tailwind, or CSS vars not resolving                                                            |
+| Preflight styles are active                | v4: Using `@import 'tailwindcss'` shorthand instead of individual layers                                                        |
+| Utility classes not generated              | v3: `content` array doesn't match file paths; v4: files outside auto-scan root                                                  |
+| Font doesn't change to Inter               | Google Fonts not loaded — pds-core.css includes the font import, confirm it is loading before Tailwind                          |
+| Dark mode section looks identical to light | `pds-core.css` dark mode vars may need `data-theme="dark"` on a parent element — check the PDS dark mode implementation         |
+| `rounded-button` same as `rounded`         | Expected — they share the same token value (`--pds-border-radius-button` = `--pds-border-radius-default`)                       |
+| Borders invisible despite `border` class   | Preflight is disabled — add `border-solid` alongside every `border` class. Without preflight, `border-style` defaults to `none` |