@indico-data/design-system 3.22.1 → 3.23.0

package/AGENTS.md

@@ -0,0 +1,110 @@
+# AGENTS GUIDE
+
+This guide summarizes how to work in the `permafrost` repo (published as `@indico-data/design-system`) and the conventions every agent must follow when making changes.
+
+Permafrost is the code implementation of Indico's Figma design system. When behavior or styling is unclear, align with approved design-system specs before introducing new patterns.
+
+## Quick Reference
+
+| Task                 | Command                            |
+| -------------------- | ---------------------------------- |
+| Start Storybook      | `yarn dev` → http://localhost:6006 |
+| Build library        | `yarn build`                       |
+| Run tests            | `yarn test`                        |
+| Run Storybook tests  | `yarn test-storybook`              |
+| Lint                 | `yarn lint`                        |
+| Check latest release | `yarn latest-release`              |
+| Check all releases   | `yarn all-releases`                |
+
+## Project Structure
+
+```
+permafrost/
+├── src/
+│   ├── index.ts             # Public package API (`@indico-data/design-system`)
+│   ├── components/        # All component directories
+│   │   ├── index.ts         # Internal convenience barrel (`@/components`) for docs/stories/dev
+│   │   └── <component>/
+│   │       ├── index.ts           # Barrel export
+│   │       ├── Component.tsx      # Implementation
+│   │       ├── types.ts           # Props interface with JSDoc
+│   │       ├── styles/            # Component styles (SCSS-first)
+│   │       │   └── _tokens.scss   # Component-level design tokens
+│   │       ├── __tests__/         # Jest + Testing Library tests
+│   │       ├── Component.stories.tsx  # Storybook stories
+│   │       └── Component.mdx     # Storybook docs
+│   ├── styles/
+│   │   ├── primitives/    # Base tokens: colors, spacing, typography, borders
+│   │   └── tokens/        # Semantic tokens (light/dark via data-theme)
+│   ├── setup/             # Icon registration, test setup
+├── lib/                   # Build output (CJS + ESM + CSS + .d.ts)
+└── .storybook/            # Storybook configuration
+```
+
+## Editing Instructions
+
+### Adding or Modifying Components
+
+1. **Follow the component directory pattern**: each component lives in `src/components/<name>/` with an `index.ts` barrel, implementation file, `types.ts` for props, and co-located styles/tests/stories. (Not all legacy components fully conform yet — new components should follow this pattern.)
+2. **Props interfaces must have JSDoc** on every public prop — this feeds into Storybook's `react-docgen-typescript` for auto-generated docs.
+3. **Every component must have a Storybook story** (`.stories.tsx`) demonstrating its variants, and an MDX doc file showing usage.
+4. **Every component must have tests** using Jest + `@testing-library/react`. Tests live in `__tests__/` or as co-located `.test.tsx` files.
+5. **Export new components from `src/index.ts`** — this is the public API. If it's not exported here, consumers can't use it.
+6. **Treat `src/components/index.ts` as internal-only** — it is for repo-local imports (for example `@/components` in stories/docs). Do not treat it as consumer API, and keep naming/exports in `src/index.ts` authoritative.
+
+### Design Tokens and Styling
+
+- **Semantic tokens first** (`src/styles/tokens/_semantic-tokens.scss`): these are the default tokens for component styling and should be used in most cases.
+- **Primitives** (`src/styles/primitives/`): base values (`--pf-*-color-*`, spacing, typography, borders, shadows, breakpoints) that feed semantic tokens. Use directly only for limited foundation-level needs.
+- **Component tokens** (`src/components/*/styles/_tokens.scss`): exception, not the rule. Add only when there are component specific (non-semantic) colors used in designs.
+- Token names follow the pattern: `--pf-<layer>-<category>-<variant>` (e.g. `--pf-semantic-bg-primary`, `--pf-blue-color-500`).
+- When adding tokens, follow the existing hierarchy: primitives → semantic → component. Do not hardcode color values in components.
+
+### Styling Conventions
+
+- Use **SCSS** for new styling work.
+- Do not introduce new **styled-components** in new components. If touching legacy code that already uses styled-components, keep changes localized unless refactoring is explicitly in scope.
+- Use CSS custom properties (design tokens) for all colors, spacing, typography, and borders.
+
+### i18n
+
+- ESLint enforces `i18next/no-literal-string` and `@sanity/i18n/no-attribute-string-literals` for user-facing text in `label`, `placeholder`, `title`, `alt`, `aria-label`, and `tooltip` attributes.
+- These rules are relaxed for test files, stories, examples, docs, and mock data.
+- Components should accept user-facing text via a `text` prop object pattern to support i18n in consumer apps.
+
+## Release Conventions
+
+Releases are fully automated via [Semantic Release](https://github.com/semantic-release/semantic-release). The **PR title** controls versioning:
+
+| PR Title Tag | Release Type | Example                                   |
+| ------------ | ------------ | ----------------------------------------- |
+| `Fix`        | Patch        | `Fix: button hover state on dark theme`   |
+| `Update`     | Patch        | `Update: button color adjustment`         |
+| `New`        | Minor        | `New: [SNC-222] add dark mode`            |
+| `Breaking`   | Major        | `Breaking: remove deprecated Table props` |
+| `Docs`       | No release   | `Docs: update Button MDX`                 |
+| `Build`      | No release   | `Build: upgrade rollup`                   |
+| `Upgrade`    | No release   | `Upgrade: bump react-aria`                |
+| `Chore`      | No release   | `Chore: clean up test fixtures`           |
+
+**Critical rules:**
+
+- PR title **must** follow `<Tag>: <Short description>` format or merging is blocked.
+- Do **not** manually update `version` in `package.json` — it stays at `0.0.0-semantically-released`.
+- Do **not** manually publish to npm.
+
+## Review Guidelines
+
+- Every component change must include a Storybook story demonstrating the change.
+- Props interfaces must have JSDoc documentation.
+- New components must have tests.
+- Design tokens must follow the primitives → semantic → component hierarchy.
+- Verify `yarn lint` and `yarn test` pass before submitting.
+
+## Validation
+
+After any significant change, run:
+
+```bash
+yarn lint && yarn test && yarn build
+```

package/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/lib/components/alert/Alert.d.ts

@@ -0,0 +1,2 @@
+import { type AlertProps } from './types';
+export declare const Alert: ({ type, variant, size, tinted, title, children, actionText, onAction, onClose, closeAriaLabel, className, ...rest }: AlertProps) => import("react/jsx-runtime").JSX.Element;

package/lib/components/alert/Alert.stories.d.ts

@@ -0,0 +1,15 @@
+import { type Meta, type StoryObj } from '@storybook/react';
+import { Alert } from './Alert';
+declare const meta: Meta<typeof Alert>;
+export default meta;
+type Story = StoryObj<typeof Alert>;
+export declare const Default: Story;
+export declare const Types: Story;
+export declare const Variants: Story;
+export declare const WithTitle: Story;
+export declare const WithAction: Story;
+export declare const Closeable: Story;
+export declare const Combined: Story;
+export declare const SmallBordered: Story;
+export declare const SmallBorderedTinted: Story;
+export declare const SmallTintedWithClose: Story;

package/lib/components/alert/__tests__/Alert.test.d.ts

@@ -0,0 +1 @@
+export {};

package/lib/components/alert/index.d.ts

@@ -0,0 +1,2 @@
+export { Alert } from './Alert';
+export type { AlertProps, AlertType, AlertVariant, AlertSize } from './types';

package/lib/components/alert/types.d.ts

@@ -0,0 +1,26 @@
+import type React from 'react';
+export type AlertType = 'warning' | 'info' | 'success' | 'error';
+export type AlertVariant = 'soft' | 'bordered';
+export type AlertSize = 'small' | 'large';
+export interface AlertProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Semantic type — controls the icon and accent color */
+    type: AlertType;
+    /** Visual style: soft (subtle bg) or bordered (colored border) */
+    variant?: AlertVariant;
+    /** Size: large (banner) or small (compact inline) */
+    size?: AlertSize;
+    /** When true, the bordered variant uses a type-specific tinted background instead of surface-secondary */
+    tinted?: boolean;
+    /** Optional title — when provided, renders above the message */
+    title?: string;
+    /** Alert body / message content */
+    children: React.ReactNode;
+    /** Optional action button label */
+    actionText?: string;
+    /** Called when the action button is clicked */
+    onAction?: () => void;
+    /** Called when the close button is clicked — omit to hide the close button */
+    onClose?: () => void;
+    /** Accessible label for the close button (for i18n) */
+    closeAriaLabel?: string;
+}

package/lib/components/index.d.ts

@@ -21,6 +21,7 @@ export { InputDateRangePicker } from './forms/date/inputDateRangePicker';
 export { Modal, ConfirmationModal } from './modal';
 export { Badge } from './badge';
 export { Pill } from './pill';
+export { Alert } from './alert';
 export { Pagination } from './pagination';
 export { TanstackTable } from './tanstackTable';
 export { Tooltip } from './tooltip';

package/lib/components/pill/Pill.d.ts

@@ -1,2 +1,2 @@
 import { type PillProps } from './types';
-export declare const Pill: ({ children, color, size, variant, type, iconLeft, iconRight, dot, onClose, closeAriaLabel, className, ...rest }: PillProps) => import("react/jsx-runtime").JSX.Element;
+export declare const Pill: ({ children, color, size, variant, type, iconLeft, iconRight, dot, shade, shadeCount, onClose, closeAriaLabel, className, style, ...rest }: PillProps) => import("react/jsx-runtime").JSX.Element;

package/lib/components/pill/Pill.stories.d.ts

@@ -16,4 +16,7 @@ export declare const Closeable: Story;
 export declare const Combined: Story;
 export declare const FullMatrix: Story;
 export declare const CloseableMatrix: Story;
+export declare const Shaded: Story;
+export declare const ShadedSpectrum: Story;
+export declare const ShadedDynamicCount: Story;
 export declare const FigmaMatrix: Story;

package/lib/components/pill/types.d.ts

@@ -22,6 +22,10 @@ export interface PillProps extends React.HTMLAttributes<HTMLDivElement> {
     iconRight?: IconName;
     /** When true, renders a small colored dot indicator before the content */
     dot?: boolean;
+    /** 1-based shade index within a group. Used with shadeCount to vary background lightness via color-mix(). */
+    shade?: number;
+    /** Total shades in the group. Background blends lighter (white) below midpoint, darker (black) above. */
+    shadeCount?: number;
     /** When provided, renders a close button that calls this handler */
     onClose?: () => void;
     /** Accessible label for the close button (for i18n) */

package/lib/index.css

@@ -6562,7 +6562,7 @@ body div[class*=select__single-value] {
   padding: var(--pf-spacing-xs) var(--pf-spacing-sm) var(--pf-spacing-xs) var(--pf-spacing-lg);
 }
 .pill--solid-red {
-  background-color: var(--pf-pill-solid-red-bg);
+  background-color: color-mix(in srgb, var(--pf-pill-solid-red-bg) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
   color: var(--pf-pill-solid-red-text);
 }
 .pill--solid-red > .icon {
@@ -6579,7 +6579,7 @@ body div[class*=select__single-value] {
   background-color: var(--pf-pill-solid-red-close-hover-bg);
 }
 .pill--solid-purple {
-  background-color: var(--pf-pill-solid-purple-bg);
+  background-color: color-mix(in srgb, var(--pf-pill-solid-purple-bg) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
   color: var(--pf-pill-solid-purple-text);
 }
 .pill--solid-purple > .icon {
@@ -6596,7 +6596,7 @@ body div[class*=select__single-value] {
   background-color: var(--pf-pill-solid-purple-close-hover-bg);
 }
 .pill--solid-yellow {
-  background-color: var(--pf-pill-solid-yellow-bg);
+  background-color: color-mix(in srgb, var(--pf-pill-solid-yellow-bg) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
   color: var(--pf-pill-solid-yellow-text);
 }
 .pill--solid-yellow > .icon {
@@ -6613,7 +6613,7 @@ body div[class*=select__single-value] {
   background-color: var(--pf-pill-solid-yellow-close-hover-bg);
 }
 .pill--solid-blue {
-  background-color: var(--pf-pill-solid-blue-bg);
+  background-color: color-mix(in srgb, var(--pf-pill-solid-blue-bg) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
   color: var(--pf-pill-solid-blue-text);
 }
 .pill--solid-blue > .icon {
@@ -6630,7 +6630,7 @@ body div[class*=select__single-value] {
   background-color: var(--pf-pill-solid-blue-close-hover-bg);
 }
 .pill--solid-green {
-  background-color: var(--pf-pill-solid-green-bg);
+  background-color: color-mix(in srgb, var(--pf-pill-solid-green-bg) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
   color: var(--pf-pill-solid-green-text);
 }
 .pill--solid-green > .icon {
@@ -6647,7 +6647,7 @@ body div[class*=select__single-value] {
   background-color: var(--pf-pill-solid-green-close-hover-bg);
 }
 .pill--solid-gray {
-  background-color: var(--pf-pill-solid-gray-bg);
+  background-color: color-mix(in srgb, var(--pf-pill-solid-gray-bg) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
   color: var(--pf-pill-solid-gray-text);
 }
 .pill--solid-gray > .icon {
@@ -6664,7 +6664,7 @@ body div[class*=select__single-value] {
   background-color: var(--pf-pill-solid-gray-close-hover-bg);
 }
 .pill--solid-pink {
-  background-color: var(--pf-pill-solid-pink-bg);
+  background-color: color-mix(in srgb, var(--pf-pill-solid-pink-bg) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
   color: var(--pf-pill-solid-pink-text);
 }
 .pill--solid-pink > .icon {
@@ -6681,7 +6681,7 @@ body div[class*=select__single-value] {
   background-color: var(--pf-pill-solid-pink-close-hover-bg);
 }
 .pill--solid-orange {
-  background-color: var(--pf-pill-solid-orange-bg);
+  background-color: color-mix(in srgb, var(--pf-pill-solid-orange-bg) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
   color: var(--pf-pill-solid-orange-text);
 }
 .pill--solid-orange > .icon {
@@ -6698,7 +6698,7 @@ body div[class*=select__single-value] {
   background-color: var(--pf-pill-solid-orange-close-hover-bg);
 }
 .pill--solid-teal {
-  background-color: var(--pf-pill-solid-teal-bg);
+  background-color: color-mix(in srgb, var(--pf-pill-solid-teal-bg) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
   color: var(--pf-pill-solid-teal-text);
 }
 .pill--solid-teal > .icon {
@@ -6715,7 +6715,7 @@ body div[class*=select__single-value] {
   background-color: var(--pf-pill-solid-teal-close-hover-bg);
 }
 .pill--solid-soft {
-  background-color: var(--pf-pill-solid-soft-bg);
+  background-color: color-mix(in srgb, var(--pf-pill-solid-soft-bg) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
   color: var(--pf-pill-solid-soft-text);
 }
 .pill--solid-soft > .icon {
@@ -6732,9 +6732,9 @@ body div[class*=select__single-value] {
   background-color: var(--pf-pill-solid-soft-close-hover-bg);
 }
 .pill--outline-red {
-  background-color: var(--pf-pill-outline-red-bg);
+  background-color: color-mix(in srgb, var(--pf-pill-outline-red-bg) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
   color: var(--pf-pill-outline-red-text);
-  box-shadow: inset 0 0 0 1px var(--pf-pill-outline-red-border);
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--pf-pill-outline-red-border) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
 }
 .pill--outline-red > .icon {
   color: var(--pf-pill-outline-red-icon);
@@ -6750,9 +6750,9 @@ body div[class*=select__single-value] {
   background-color: var(--pf-pill-outline-red-close-hover-bg);
 }
 .pill--outline-purple {
-  background-color: var(--pf-pill-outline-purple-bg);
+  background-color: color-mix(in srgb, var(--pf-pill-outline-purple-bg) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
   color: var(--pf-pill-outline-purple-text);
-  box-shadow: inset 0 0 0 1px var(--pf-pill-outline-purple-border);
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--pf-pill-outline-purple-border) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
 }
 .pill--outline-purple > .icon {
   color: var(--pf-pill-outline-purple-icon);
@@ -6768,9 +6768,9 @@ body div[class*=select__single-value] {
   background-color: var(--pf-pill-outline-purple-close-hover-bg);
 }
 .pill--outline-yellow {
-  background-color: var(--pf-pill-outline-yellow-bg);
+  background-color: color-mix(in srgb, var(--pf-pill-outline-yellow-bg) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
   color: var(--pf-pill-outline-yellow-text);
-  box-shadow: inset 0 0 0 1px var(--pf-pill-outline-yellow-border);
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--pf-pill-outline-yellow-border) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
 }
 .pill--outline-yellow > .icon {
   color: var(--pf-pill-outline-yellow-icon);
@@ -6786,9 +6786,9 @@ body div[class*=select__single-value] {
   background-color: var(--pf-pill-outline-yellow-close-hover-bg);
 }
 .pill--outline-blue {
-  background-color: var(--pf-pill-outline-blue-bg);
+  background-color: color-mix(in srgb, var(--pf-pill-outline-blue-bg) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
   color: var(--pf-pill-outline-blue-text);
-  box-shadow: inset 0 0 0 1px var(--pf-pill-outline-blue-border);
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--pf-pill-outline-blue-border) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
 }
 .pill--outline-blue > .icon {
   color: var(--pf-pill-outline-blue-icon);
@@ -6804,9 +6804,9 @@ body div[class*=select__single-value] {
   background-color: var(--pf-pill-outline-blue-close-hover-bg);
 }
 .pill--outline-green {
-  background-color: var(--pf-pill-outline-green-bg);
+  background-color: color-mix(in srgb, var(--pf-pill-outline-green-bg) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
   color: var(--pf-pill-outline-green-text);
-  box-shadow: inset 0 0 0 1px var(--pf-pill-outline-green-border);
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--pf-pill-outline-green-border) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
 }
 .pill--outline-green > .icon {
   color: var(--pf-pill-outline-green-icon);
@@ -6822,9 +6822,9 @@ body div[class*=select__single-value] {
   background-color: var(--pf-pill-outline-green-close-hover-bg);
 }
 .pill--outline-gray {
-  background-color: var(--pf-pill-outline-gray-bg);
+  background-color: color-mix(in srgb, var(--pf-pill-outline-gray-bg) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
   color: var(--pf-pill-outline-gray-text);
-  box-shadow: inset 0 0 0 1px var(--pf-pill-outline-gray-border);
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--pf-pill-outline-gray-border) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
 }
 .pill--outline-gray > .icon {
   color: var(--pf-pill-outline-gray-icon);
@@ -6840,9 +6840,9 @@ body div[class*=select__single-value] {
   background-color: var(--pf-pill-outline-gray-close-hover-bg);
 }
 .pill--outline-pink {
-  background-color: var(--pf-pill-outline-pink-bg);
+  background-color: color-mix(in srgb, var(--pf-pill-outline-pink-bg) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
   color: var(--pf-pill-outline-pink-text);
-  box-shadow: inset 0 0 0 1px var(--pf-pill-outline-pink-border);
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--pf-pill-outline-pink-border) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
 }
 .pill--outline-pink > .icon {
   color: var(--pf-pill-outline-pink-icon);
@@ -6858,9 +6858,9 @@ body div[class*=select__single-value] {
   background-color: var(--pf-pill-outline-pink-close-hover-bg);
 }
 .pill--outline-orange {
-  background-color: var(--pf-pill-outline-orange-bg);
+  background-color: color-mix(in srgb, var(--pf-pill-outline-orange-bg) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
   color: var(--pf-pill-outline-orange-text);
-  box-shadow: inset 0 0 0 1px var(--pf-pill-outline-orange-border);
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--pf-pill-outline-orange-border) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
 }
 .pill--outline-orange > .icon {
   color: var(--pf-pill-outline-orange-icon);
@@ -6876,9 +6876,9 @@ body div[class*=select__single-value] {
   background-color: var(--pf-pill-outline-orange-close-hover-bg);
 }
 .pill--outline-teal {
-  background-color: var(--pf-pill-outline-teal-bg);
+  background-color: color-mix(in srgb, var(--pf-pill-outline-teal-bg) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
   color: var(--pf-pill-outline-teal-text);
-  box-shadow: inset 0 0 0 1px var(--pf-pill-outline-teal-border);
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--pf-pill-outline-teal-border) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
 }
 .pill--outline-teal > .icon {
   color: var(--pf-pill-outline-teal-icon);
@@ -6894,9 +6894,9 @@ body div[class*=select__single-value] {
   background-color: var(--pf-pill-outline-teal-close-hover-bg);
 }
 .pill--outline-soft {
-  background-color: var(--pf-pill-outline-soft-bg);
+  background-color: color-mix(in srgb, var(--pf-pill-outline-soft-bg) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
   color: var(--pf-pill-outline-soft-text);
-  box-shadow: inset 0 0 0 1px var(--pf-pill-outline-soft-border);
+  box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--pf-pill-outline-soft-border) var(--pill-shade-mix, 100%), var(--pill-shade-target, white));
 }
 .pill--outline-soft > .icon {
   color: var(--pf-pill-outline-soft-icon);
@@ -6932,6 +6932,190 @@ body div[class*=select__single-value] {
   transition: color 0.15s ease, background-color 0.15s ease;
 }
 
+:root,
+:root [data-theme=light] {
+  --pf-alert-bordered-warning-bg: var(--pf-yellow-color-150);
+  --pf-alert-bordered-warning-border: var(--pf-yellow-color-400);
+  --pf-alert-bordered-warning-text: var(--pf-yellow-color-600);
+  --pf-alert-bordered-warning-icon: var(--pf-yellow-color-400);
+  --pf-alert-bordered-info-bg: var(--pf-blue-color-150);
+  --pf-alert-bordered-info-border: var(--pf-secondary-color-400);
+  --pf-alert-bordered-info-text: var(--pf-secondary-color-500);
+  --pf-alert-bordered-info-icon: var(--pf-secondary-color-400);
+  --pf-alert-bordered-success-bg: var(--pf-green-color-150);
+  --pf-alert-bordered-success-border: var(--pf-green-color-450);
+  --pf-alert-bordered-success-text: var(--pf-green-color-600);
+  --pf-alert-bordered-success-icon: var(--pf-green-color-500);
+  --pf-alert-bordered-error-bg: var(--pf-red-color-150);
+  --pf-alert-bordered-error-border: var(--pf-red-color-250);
+  --pf-alert-bordered-error-text: var(--pf-red-color-500);
+  --pf-alert-bordered-error-icon: var(--pf-red-color-450);
+}
+
+:root [data-theme=dark] {
+  --pf-alert-bordered-warning-bg: var(--pf-yellow-color-800);
+  --pf-alert-bordered-warning-border: var(--pf-yellow-color-500);
+  --pf-alert-bordered-warning-text: var(--pf-yellow-color-300);
+  --pf-alert-bordered-warning-icon: var(--pf-yellow-color-300);
+  --pf-alert-bordered-info-bg: var(--pf-blue-color-700);
+  --pf-alert-bordered-info-border: var(--pf-secondary-color-500);
+  --pf-alert-bordered-info-text: var(--pf-secondary-color-250);
+  --pf-alert-bordered-info-icon: var(--pf-secondary-color-250);
+  --pf-alert-bordered-success-bg: var(--pf-green-color-800);
+  --pf-alert-bordered-success-border: var(--pf-green-color-600);
+  --pf-alert-bordered-success-text: var(--pf-green-color-300);
+  --pf-alert-bordered-success-icon: var(--pf-green-color-300);
+  --pf-alert-bordered-error-bg: var(--pf-red-color-700);
+  --pf-alert-bordered-error-border: var(--pf-red-color-500);
+  --pf-alert-bordered-error-text: var(--pf-red-color-300);
+  --pf-alert-bordered-error-icon: var(--pf-red-color-300);
+}
+
+.alert {
+  display: flex;
+  align-items: flex-start;
+  gap: var(--pf-spacing-md);
+  padding: var(--pf-spacing-2xl);
+  border-radius: var(--pf-border-radius-md);
+  background-color: var(--pf-semantic-background-secondary);
+  font-family: var(--pf-font-family);
+  box-shadow: 0 4px 6px -4px var(--pf-semantic-elevation-1), 0 10px 15px -3px var(--pf-semantic-elevation-1);
+}
+.alert--small {
+  padding: var(--pf-spacing-sm);
+  align-items: center;
+  box-shadow: none;
+}
+.alert--bordered {
+  border: 1px solid var(--alert-border-color);
+}
+.alert--soft-warning > .icon {
+  color: var(--pf-semantic-utility-warning-default);
+}
+.alert--soft-info > .icon {
+  color: var(--pf-semantic-utility-info-default);
+}
+.alert--soft-success > .icon {
+  color: var(--pf-semantic-utility-success-default);
+}
+.alert--soft-error > .icon {
+  color: var(--pf-semantic-utility-error-default);
+}
+.alert--bordered-warning {
+  --alert-border-color: var(--pf-alert-bordered-warning-border);
+}
+.alert--bordered-warning > .icon {
+  color: var(--pf-alert-bordered-warning-icon);
+}
+.alert--bordered-warning .alert__title {
+  color: var(--pf-alert-bordered-warning-text);
+}
+.alert--tinted.alert--bordered-warning {
+  background-color: var(--pf-alert-bordered-warning-bg);
+}
+.alert--bordered-info {
+  --alert-border-color: var(--pf-alert-bordered-info-border);
+}
+.alert--bordered-info > .icon {
+  color: var(--pf-alert-bordered-info-icon);
+}
+.alert--bordered-info .alert__title {
+  color: var(--pf-alert-bordered-info-text);
+}
+.alert--tinted.alert--bordered-info {
+  background-color: var(--pf-alert-bordered-info-bg);
+}
+.alert--bordered-success {
+  --alert-border-color: var(--pf-alert-bordered-success-border);
+}
+.alert--bordered-success > .icon {
+  color: var(--pf-alert-bordered-success-icon);
+}
+.alert--bordered-success .alert__title {
+  color: var(--pf-alert-bordered-success-text);
+}
+.alert--tinted.alert--bordered-success {
+  background-color: var(--pf-alert-bordered-success-bg);
+}
+.alert--bordered-error {
+  --alert-border-color: var(--pf-alert-bordered-error-border);
+}
+.alert--bordered-error > .icon {
+  color: var(--pf-alert-bordered-error-icon);
+}
+.alert--bordered-error .alert__title {
+  color: var(--pf-alert-bordered-error-text);
+}
+.alert--tinted.alert--bordered-error {
+  background-color: var(--pf-alert-bordered-error-bg);
+}
+.alert > .icon {
+  flex-shrink: 0;
+}
+.alert__body {
+  flex: 1;
+  min-width: 0;
+}
+.alert__title {
+  font-size: var(--pf-font-size-md);
+  font-weight: var(--pf-font-weight-semibold);
+  line-height: 20px;
+  color: var(--pf-semantic-font-regular);
+  margin-bottom: var(--pf-spacing-xxs);
+}
+.alert__message {
+  font-size: var(--pf-font-size-md);
+  font-weight: var(--pf-font-weight-regular);
+  line-height: 20px;
+  color: var(--pf-semantic-font-regular);
+}
+.alert__message a {
+  color: var(--pf-semantic-font-link);
+  text-decoration: underline;
+}
+.alert--has-title .alert__message {
+  color: var(--pf-semantic-font-soft);
+}
+.alert__actions {
+  display: flex;
+  align-items: center;
+  gap: var(--pf-spacing-sm);
+  flex-shrink: 0;
+  margin-left: auto;
+}
+.alert__action {
+  background: none;
+  border: none;
+  cursor: pointer;
+  font-family: var(--pf-font-family);
+  font-size: var(--pf-font-size-md);
+  font-weight: var(--pf-font-weight-medium);
+  line-height: 20px;
+  color: var(--pf-semantic-font-link);
+  padding: 0;
+  white-space: nowrap;
+}
+.alert__action:hover {
+  text-decoration: underline;
+}
+.alert__close {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  cursor: pointer;
+  border: none;
+  background: transparent;
+  padding: var(--pf-spacing-xxs);
+  border-radius: var(--pf-border-radius-xs);
+  color: var(--pf-semantic-font-soft);
+  line-height: 1;
+  transition: color 0.15s ease, background-color 0.15s ease;
+}
+.alert__close:hover {
+  color: var(--pf-semantic-font-regular);
+}
+
 @keyframes moveBg {
   0% {
     transform: translateX(0);

package/lib/index.d.ts

@@ -22,6 +22,32 @@ declare const Row: ({ ref: _ref, ...rest }: RowProps) => react_jsx_runtime.JSX.E
 
 declare const Col: ({ ref: _ref, ...rest }: ColProps) => react_jsx_runtime.JSX.Element;
 
+type AlertType = 'warning' | 'info' | 'success' | 'error';
+type AlertVariant = 'soft' | 'bordered';
+type AlertSize = 'small' | 'large';
+interface AlertProps extends React$1.HTMLAttributes<HTMLDivElement> {
+    /** Semantic type — controls the icon and accent color */
+    type: AlertType;
+    /** Visual style: soft (subtle bg) or bordered (colored border) */
+    variant?: AlertVariant;
+    /** Size: large (banner) or small (compact inline) */
+    size?: AlertSize;
+    /** When true, the bordered variant uses a type-specific tinted background instead of surface-secondary */
+    tinted?: boolean;
+    /** Optional title — when provided, renders above the message */
+    title?: string;
+    /** Alert body / message content */
+    children: React$1.ReactNode;
+    /** Optional action button label */
+    actionText?: string;
+    /** Called when the action button is clicked */
+    onAction?: () => void;
+    /** Called when the close button is clicked — omit to hide the close button */
+    onClose?: () => void;
+    /** Accessible label for the close button (for i18n) */
+    closeAriaLabel?: string;
+}
+
 /** Customizable text for form Label. */
 interface FormLabelText {
     /** Text appended to aria-label for required fields. Default: "(required)" */
@@ -249,6 +275,10 @@ interface PillProps extends React$1.HTMLAttributes<HTMLDivElement> {
     iconRight?: IconName;
     /** When true, renders a small colored dot indicator before the content */
     dot?: boolean;
+    /** 1-based shade index within a group. Used with shadeCount to vary background lightness via color-mix(). */
+    shade?: number;
+    /** Total shades in the group. Background blends lighter (white) below midpoint, darker (black) above. */
+    shadeCount?: number;
     /** When provided, renders a close button that calls this handler */
     onClose?: () => void;
     /** Accessible label for the close button (for i18n) */
@@ -852,7 +882,9 @@ type MenuProps = {
 };
 declare function Menu({ children, className, ...rest }: MenuProps): react_jsx_runtime.JSX.Element;
 
-declare const Pill: ({ children, color, size, variant, type, iconLeft, iconRight, dot, onClose, closeAriaLabel, className, ...rest }: PillProps) => react_jsx_runtime.JSX.Element;
+declare const Pill: ({ children, color, size, variant, type, iconLeft, iconRight, dot, shade, shadeCount, onClose, closeAriaLabel, className, style, ...rest }: PillProps) => react_jsx_runtime.JSX.Element;
+
+declare const Alert: ({ type, variant, size, tinted, title, children, actionText, onAction, onClose, closeAriaLabel, className, ...rest }: AlertProps) => react_jsx_runtime.JSX.Element;
 
 type BadgeSizes = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
 interface BadgeProps {
@@ -1159,4 +1191,4 @@ interface TruncateProps {
 
 declare const Truncate: ({ numLines, tooltipOptions, children, ...rest }: TruncateProps) => react_jsx_runtime.JSX.Element;
 
-export { Badge, BarSpinner, Button, Card, Checkbox, CirclePulse, Col, ConfirmationModal, Container, DatePicker, FloatUI, Form, Icon, IconTriggerDatePicker, LabeledInput as Input, InputDateRangePicker, Menu, Modal, Pagination, LabeledPasswordInput as PasswordInput, Pill, Radio as RadioInput, Row, LabeledSelect as SelectInput, type SelectOption, type SelectText, SingleInputDatePicker, SingleInputDateTimePicker, Skeleton, Stepper, Table, TanstackTable, LabeledTextarea as Textarea, TimePicker, Toggle as ToggleInput, Tooltip, Truncate, registerFontAwesomeIcons };
+export { Alert, Badge, BarSpinner, Button, Card, Checkbox, CirclePulse, Col, ConfirmationModal, Container, DatePicker, FloatUI, Form, Icon, IconTriggerDatePicker, LabeledInput as Input, InputDateRangePicker, Menu, Modal, Pagination, LabeledPasswordInput as PasswordInput, Pill, Radio as RadioInput, Row, LabeledSelect as SelectInput, type SelectOption, type SelectText, SingleInputDatePicker, SingleInputDateTimePicker, Skeleton, Stepper, Table, TanstackTable, LabeledTextarea as Textarea, TimePicker, Toggle as ToggleInput, Tooltip, Truncate, registerFontAwesomeIcons };