Skip to content

The Postgres development platform. Supabase gives you a dedicated Postgres database to build your web, mobile, and AI applications.

chore(design-system): redo safer Admonition updates (#45618)

Danny White04c9fb7c3ead
diff --git a/apps/design-system/__registry__/index.tsx b/apps/design-system/__registry__/index.tsx
index 5b69704eecc..b442e4c0ecc 100644
--- a/apps/design-system/__registry__/index.tsx
+++ b/apps/design-system/__registry__/index.tsx
@@ -126,6 +126,17 @@ export const Index: Record<string, any> = {
subcategory: "undefined",
chunks: []
},
+ "admonition-description-only": {
+ name: "admonition-description-only",
+ type: "components:example",
+ registryDependencies: ["admonition"],
+ component: React.lazy(() => import("@/registry/default/example/admonition-description-only")),
+ source: "",
+ files: ["registry/default/example/admonition-description-only.tsx"],
+ category: "undefined",
+ subcategory: "undefined",
+ chunks: []
+ },
"admonition-warning": {
name: "admonition-warning",
type: "components:example",
@@ -137,6 +148,17 @@ export const Index: Record<string, any> = {
subcategory: "undefined",
chunks: []
},
+ "admonition-success": {
+ name: "admonition-success",
+ type: "components:example",
+ registryDependencies: ["admonition"],
+ component: React.lazy(() => import("@/registry/default/example/admonition-success")),
+ source: "",
+ files: ["registry/default/example/admonition-success.tsx"],
+ category: "undefined",
+ subcategory: "undefined",
+ chunks: []
+ },
"admonition-destructive": {
name: "admonition-destructive",
type: "components:example",
diff --git a/apps/design-system/content/docs/fragments/admonition.mdx b/apps/design-system/content/docs/fragments/admonition.mdx
index d9c0e89a4a9..c0adf6a7803 100644
--- a/apps/design-system/content/docs/fragments/admonition.mdx
+++ b/apps/design-system/content/docs/fragments/admonition.mdx
@@ -15,6 +15,12 @@ Admonition provides focus for situations that require a callout.
Use Admonition instead of [Alert](../components/alert) unless you specifically need the primitives. If in doubt, stick with Admonition.
+Use `title` for the heading slot when the callout needs its own heading. `title` is optional: short callouts may use `description` without a title when nearby content already provides enough context.
+
+Avoid title-only Admonitions in new code. A callout with `title` should also include `description` or `children` so it does not read like an incomplete heading.
+
+`label` is still supported for older Docs content, but new code should use `title`.
+
## Usage
```tsx
@@ -72,6 +78,24 @@ There are several components that wrap the `warning` Admonition type with reusab
AlertError for example rolls up consistent error handling and support contact methods.
+### Description only
+
+Use description-only Admonitions for short callouts that sit near a heading or form label with enough context.
+
+<ComponentPreview
+ name="admonition-description-only"
+ className="[&_.preview>[data-orientation=vertical]]:sm:max-w-[70%]"
+/>
+
+### Success
+
+Use `success` for positive, completed states where the user does not need to take corrective action.
+
+<ComponentPreview
+ name="admonition-success"
+ className="[&_.preview>[data-orientation=vertical]]:sm:max-w-[70%]"
+/>
+
### Destructive
<ComponentPreview
diff --git a/apps/design-system/registry/default/example/admonition-description-only.tsx b/apps/design-system/registry/default/example/admonition-description-only.tsx
new file mode 100644
index 00000000000..319432ad8f9
--- /dev/null
+++ b/apps/design-system/registry/default/example/admonition-description-only.tsx
@@ -0,0 +1,10 @@
+import { Admonition } from 'ui-patterns/admonition'
+
+export default function AdmonitionDescriptionOnly() {
+ return (
+ <Admonition
+ type="default"
+ description="Changes to these settings can take a few minutes to appear across all projects."
+ />
+ )
+}
diff --git a/apps/design-system/registry/default/example/admonition-success.tsx b/apps/design-system/registry/default/example/admonition-success.tsx
new file mode 100644
index 00000000000..70c8d25a2d5
--- /dev/null
+++ b/apps/design-system/registry/default/example/admonition-success.tsx
@@ -0,0 +1,11 @@
+import { Admonition } from 'ui-patterns/admonition'
+
+export default function AdmonitionSuccess() {
+ return (
+ <Admonition
+ type="success"
+ title="Connection confirmed"
+ description="You can now close this tab."
+ />
+ )
+}
diff --git a/apps/design-system/registry/examples.ts b/apps/design-system/registry/examples.ts
index 9f04225b28b..d5f9a19ae22 100644
--- a/apps/design-system/registry/examples.ts
+++ b/apps/design-system/registry/examples.ts
@@ -25,12 +25,24 @@ export const examples: Registry = [
registryDependencies: ['admonition'],
files: ['example/admonition-button.tsx'],
},
+ {
+ name: 'admonition-description-only',
+ type: 'components:example',
+ registryDependencies: ['admonition'],
+ files: ['example/admonition-description-only.tsx'],
+ },
{
name: 'admonition-warning',
type: 'components:example',
registryDependencies: ['admonition'],
files: ['example/admonition-warning.tsx'],
},
+ {
+ name: 'admonition-success',
+ type: 'components:example',
+ registryDependencies: ['admonition'],
+ files: ['example/admonition-success.tsx'],
+ },
{
name: 'admonition-destructive',
type: 'components:example',
diff --git a/packages/ui-patterns/src/Dialogs/ConfirmationModal.tsx b/packages/ui-patterns/src/Dialogs/ConfirmationModal.tsx
index b61cc41d361..e53cf6a9d24 100644
--- a/packages/ui-patterns/src/Dialogs/ConfirmationModal.tsx
+++ b/packages/ui-patterns/src/Dialogs/ConfirmationModal.tsx
@@ -85,6 +85,9 @@ export const ConfirmationModal = forwardRef<
if (loading_ !== undefined) setLoading(loading_)
}, [loading_])
+ const { title: _alertBaseTitle, children: _alertBaseChildren, ...alertBase } = alert?.base ?? {}
+ const alertTitleProps = alert?.title ? { label: alert.title } : {}
+
return (
<Dialog
open={visible}
@@ -108,10 +111,10 @@ export const ConfirmationModal = forwardRef<
{alert && (
<Admonition
type={variant as 'default' | 'destructive' | 'warning'}
- label={alert.title}
description={alert.description}
+ {...alertTitleProps}
className="border-x-0 rounded-none -mt-px"
- {...alert?.base}
+ {...alertBase}
/>
)}
{children && (
diff --git a/packages/ui-patterns/src/Dialogs/TextConfirmModal.tsx b/packages/ui-patterns/src/Dialogs/TextConfirmModal.tsx
index 68304821108..9222f46f289 100644
--- a/packages/ui-patterns/src/Dialogs/TextConfirmModal.tsx
+++ b/packages/ui-patterns/src/Dialogs/TextConfirmModal.tsx
@@ -128,6 +128,9 @@ export const TextConfirmModal = forwardRef<
return () => clearTimeout(timer)
}, [showCopied])
+ const { title: _alertBaseTitle, children: _alertBaseChildren, ...alertBase } = alert?.base ?? {}
+ const alertTitleProps = alert?.title ? { label: alert.title } : {}
+
return (
<Dialog
open={visible}
@@ -145,10 +148,10 @@ export const TextConfirmModal = forwardRef<
{alert && (
<Admonition
type={variant as 'default' | 'destructive' | 'warning'}
- label={alert.title}
description={alert.description}
+ {...alertTitleProps}
className="border-x-0 rounded-none -mt-px"
- {...alert?.base}
+ {...alertBase}
/>
)}
{children && (
diff --git a/packages/ui-patterns/src/admonition.test.tsx b/packages/ui-patterns/src/admonition.test.tsx
new file mode 100644
index 00000000000..7ac09e4c196
--- /dev/null
+++ b/packages/ui-patterns/src/admonition.test.tsx
@@ -0,0 +1,111 @@
+import { render, screen, within } from '@testing-library/react'
+import { describe, expect, it } from 'vitest'
+
+import { Admonition, type AdmonitionProps } from './admonition'
+
+const stringDescriptionProps = {
+ description: 'Description-only copy.',
+} satisfies AdmonitionProps
+
+void stringDescriptionProps
+
+describe('Admonition', () => {
+ it('renders description-only content', () => {
+ render(<Admonition type="default" description="Changes can take a few minutes to apply." />)
+
+ expect(screen.getByRole('alert')).toHaveTextContent('Changes can take a few minutes to apply.')
+ })
+
+ it('renders children-only rich MDX-like content', () => {
+ render(
+ <Admonition type="note">
+ <p>
+ This is a Postgres{' '}
+ <a href="/docs/guides/database/postgres/row-level-security">SECURITY DEFINER</a> function.
+ </p>
+ <ul>
+ <li>Keep privileges scoped.</li>
+ </ul>
+ </Admonition>
+ )
+
+ const alert = screen.getByRole('alert')
+ expect(within(alert).getByText('SECURITY DEFINER')).toHaveAttribute(
+ 'href',
+ '/docs/guides/database/postgres/row-level-security'
+ )
+ expect(within(alert).getByText('Keep privileges scoped.')).toBeVisible()
+ })
+
+ it('renders title and description together', () => {
+ render(
+ <Admonition
+ type="warning"
+ title="Manual approval required"
+ description="Review the pending changes before continuing."
+ />
+ )
+
+ const alert = screen.getByRole('alert')
+ expect(alert).toHaveTextContent('Manual approval required')
+ expect(alert).toHaveTextContent('Review the pending changes before continuing.')
+ })
+
+ it('renders title and children together', () => {
+ render(
+ <Admonition type="caution" title="Security definer function">
+ <p>Review ownership before exposing this function.</p>
+ </Admonition>
+ )
+
+ const alert = screen.getByRole('alert')
+ expect(alert).toHaveTextContent('Security definer function')
+ expect(alert).toHaveTextContent('Review ownership before exposing this function.')
+ })
+
+ it('renders success state with success styling', () => {
+ render(
+ <Admonition
+ type="success"
+ title="Connection confirmed"
+ description="You can now close this tab."
+ />
+ )
+
+ const alert = screen.getByRole('alert')
+ expect(alert).toHaveTextContent('Connection confirmed')
+ expect(alert).toHaveTextContent('You can now close this tab.')
+ expect(alert).toHaveClass('bg-brand-400/15')
+ expect(alert).toHaveClass('border-brand-400')
+ expect(alert.querySelector('svg path')?.getAttribute('d')).toContain('M10.5 19.5')
+ })
+
+ it('does not render the destructive icon when showIcon is false', () => {
+ render(
+ <Admonition
+ type="destructive"
+ showIcon={false}
+ title="Deletion blocked"
+ description="Resolve dependent resources before retrying."
+ />
+ )
+
+ const alert = screen.getByRole('alert')
+ expect(alert).toHaveTextContent('Deletion blocked')
+ expect(alert.querySelector('svg')).not.toBeInTheDocument()
+ })
+
+ it('prefers title over legacy label when both are provided', () => {
+ render(
+ <Admonition
+ type="note"
+ label="Legacy heading"
+ title="Preferred heading"
+ description="Body copy."
+ />
+ )
+
+ expect(screen.getByText('Preferred heading')).toBeVisible()
+ expect(screen.queryByText('Legacy heading')).not.toBeInTheDocument()
+ })
+})
diff --git a/packages/ui-patterns/src/admonition.tsx b/packages/ui-patterns/src/admonition.tsx
index 6700794f61b..a20321f904c 100644
--- a/packages/ui-patterns/src/admonition.tsx
+++ b/packages/ui-patterns/src/admonition.tsx
@@ -2,19 +2,24 @@ import { cva } from 'class-variance-authority'
import { ComponentProps, forwardRef, ReactNode } from 'react'
import { Alert_Shadcn_, AlertDescription_Shadcn_, AlertTitle_Shadcn_, cn } from 'ui'
+export type AdmonitionType =
+ | 'note'
+ | 'tip'
+ | 'caution'
+ | 'danger'
+ | 'deprecation'
+ | 'default'
+ | 'destructive'
+ | 'success'
+ | 'warning'
+
export interface AdmonitionProps {
- type:
- | 'note'
- | 'tip'
- | 'caution'
- | 'danger'
- | 'deprecation'
- | 'default'
- | 'destructive'
- | 'warning'
- label?: string
+ type?: AdmonitionType
title?: string
- description?: string | ReactNode
+ /** @deprecated Prefer title for new usage. label remains supported for existing MDX content. */
+ label?: string
+ description?: ReactNode
+ children?: ReactNode
showIcon?: boolean
childProps?: {
title?: ComponentProps<typeof AlertTitle_Shadcn_>
@@ -26,10 +31,7 @@ export interface AdmonitionProps {
className?: string
}
-const admonitionToAlertMapping: Record<
- AdmonitionProps['type'],
- 'default' | 'destructive' | 'warning'
-> = {
+const admonitionToAlertMapping: Record<AdmonitionType, 'default' | 'destructive' | 'warning'> = {
note: 'default',
tip: 'default',
caution: 'warning',
@@ -38,6 +40,7 @@ const admonitionToAlertMapping: Record<
default: 'default',
warning: 'warning',
destructive: 'destructive',
+ success: 'default',
}
const InfoIcon = () => (
@@ -55,6 +58,21 @@ const InfoIcon = () => (
</svg>
)
+const SuccessIcon = () => (
+ <svg
+ xmlns="http://www.w3.org/2000/svg"
+ viewBox="0 0 21 20"
+ className="w-6 h-6"
+ fill="currentColor"
+ >
+ <path
+ fillRule="evenodd"
+ clipRule="evenodd"
+ d="M10.5 19.5C5.25329 19.5 1 15.2467 1 10C1 4.75329 5.25329 0.5 10.5 0.5C15.7467 0.5 20 4.75329 20 10C20 15.2467 15.7467 19.5 10.5 19.5ZM14.7803 7.78033C15.0732 7.48744 15.0732 7.01256 14.7803 6.71967C14.4874 6.42678 14.0126 6.42678 13.7197 6.71967L9.25 11.1893L7.28033 9.21967C6.98744 8.92678 6.51256 8.92678 6.21967 9.21967C5.92678 9.51256 5.92678 9.98744 6.21967 10.2803L8.71967 12.7803C9.01256 13.0732 9.48744 13.0732 9.78033 12.7803L14.7803 7.78033Z"
+ />
+ </svg>
+)
+
export const WarningIcon = ({ className }: { className?: string }) => (
<svg
xmlns="http://www.w3.org/2000/svg"
@@ -74,15 +92,20 @@ const admonitionSVG = cva('', {
variants: {
type: {
default: `[&>svg]:bg-foreground-muted`,
+ success: `bg-brand-400/15 dark:bg-brand/10 border-brand-400 dark:border-brand-500 [&>svg]:text-white dark:[&>svg]:text-brand-link [&>svg]:bg-brand dark:[&>svg]:bg-brand-500/50`,
warning: ``,
destructive: ``,
},
},
})
+const admonitionBodyClassName =
+ '[&_p]:!mt-0 [&_p]:!mb-1.5 [&_p:last-child]:!mb-0 [&_p:only-child]:!mb-0 [&_ul]:!my-1.5 [&_ol]:!my-1.5 [&_li]:!my-0.5'
+
export const Admonition = forwardRef<
React.ElementRef<typeof Alert_Shadcn_>,
- React.ComponentPropsWithoutRef<typeof Alert_Shadcn_> & AdmonitionProps
+ Omit<React.ComponentPropsWithoutRef<typeof Alert_Shadcn_>, keyof AdmonitionProps | 'children'> &
+ AdmonitionProps
>(
(
{
@@ -102,6 +125,8 @@ export const Admonition = forwardRef<
ref
) => {
const typeMapped = variant ? admonitionToAlertMapping[variant] : admonitionToAlertMapping[type]
+ const typeStyle = type === 'success' ? 'success' : typeMapped
+ const heading = title ?? label
return (
<Alert_Shadcn_
@@ -114,13 +139,15 @@ export const Admonition = forwardRef<
// Container query context for responsive layout
layout === 'responsive' && '@container',
// SVG icon
- admonitionSVG({ type: typeMapped }),
+ admonitionSVG({ type: typeStyle }),
props.className
)}
>
{!!icon ? (
icon
- ) : (showIcon && typeMapped === 'warning') || typeMapped === 'destructive' ? (
+ ) : showIcon && typeStyle === 'success' ? (
+ <SuccessIcon />
+ ) : showIcon && (typeMapped === 'warning' || typeMapped === 'destructive') ? (
<WarningIcon />
) : showIcon ? (
<InfoIcon />
@@ -134,8 +161,8 @@ export const Admonition = forwardRef<
'flex-col @md:flex-row @md:items-center @md:justify-between @md:gap-x-6 @lg:gap-x-8'
)}
>
- {label || title ? (
- <div>
+ <div>
+ {heading && (
<AlertTitle_Shadcn_
{...childProps.title}
className={cn(
@@ -144,28 +171,35 @@ export const Admonition = forwardRef<
childProps.title?.className
)}
>
- {label || title}
+ {heading}
</AlertTitle_Shadcn_>
- {description && (
- <AlertDescription_Shadcn_ className={childProps.description?.className}>
- {description}
- </AlertDescription_Shadcn_>
- )}
- {/* // children is to handle Docs and MDX issues with children and <p> elements */}
- {children && (
- <AlertDescription_Shadcn_
- {...childProps.description}
- className={cn('', childProps?.description?.className)}
- >
- {children}
- </AlertDescription_Shadcn_>
- )}
- </div>
- ) : (
- <div className="text my-0.5 [&_p]:mt-0 [&_p]:mb-1.5 [&_p:last-child]:mb-0">
- {children}
- </div>
- )}
+ )}
+ {description && (
+ <AlertDescription_Shadcn_
+ {...childProps.description}
+ className={cn(
+ admonitionBodyClassName,
+ !heading && 'my-0.5',
+ childProps.description?.className
+ )}
+ >
+ {description}
+ </AlertDescription_Shadcn_>
+ )}
+ {/* // children is to handle Docs and MDX issues with children and <p> elements */}
+ {children && (
+ <AlertDescription_Shadcn_
+ {...childProps.description}
+ className={cn(
+ admonitionBodyClassName,
+ !heading && !description && 'my-0.5',
+ childProps?.description?.className
+ )}
+ >
+ {children}
+ </AlertDescription_Shadcn_>
+ )}
+ </div>
{actions && (
<div
className={cn(