Usage

Start with these tokens when customizing admonitions:

--admonition-*-color and --admonition-*-color-dark to set type palettes

--admonition-border-width, --admonition-border-radius, and --admonition-accent-border-width for container shape

--admonition-title-font-size and --admonition-title-font-weight for heading tone

--admonition-title-background-tint and --admonition-content-background-tint to control surface fill

--admonition-icon-size and --admonition-chevron-* for icon and toggle affordances

Admonition type tokens follow the --admonition-<type>-* pattern (note, info, tip, success, warning, etc.). Collapsible variants use the chevron tokens for the <details>/<summary> toggle.

Tokens

Layout & Spacing Tokens

Controls for spacing, padding, and gaps within admonitions.

Token	Description	Default Value
`--admonition-spacing`	Top margin between admonitions (responsive)	`var(--content-spacing)`
`--admonition-padding`	Padding inside title and content areas	`var(--space-3)`
`--admonition-gap`	Gap between icon, title, and chevron	`var(--space-3)`

Border & Visual Tokens

Visual structure controls for borders, corners, and shadows.

Token	Description	Default Value
`--admonition-border-width`	Main border thickness	`var(--border-width-default)`
`--admonition-border-radius`	Corner rounding	`var(--border-radius-default)`
`--admonition-accent-border-width`	Left accent border width	`var(--border-width-default)`

Typography Tokens

Font controls for admonition titles/headers.

Token	Description	Default Value
`--admonition-title-font-family`	Title font family	`var(--text-font-family)`
`--admonition-title-font-size`	Title font size	`var(--text-font-size)`
`--admonition-title-font-weight`	Title font weight	`var(--font-weight-semibold)`
`--admonition-title-line-height`	Title line height	`var(--line-height-tight)`

Icon & Toggle Tokens

Controls for type-specific icons and collapsible chevron toggles.

Token	Description	Default Value
`--admonition-icon-size`	Size of type icon (via ::before)	`1.25em`
`--admonition-icon-gap`	Space after icon	`var(--space-3)`
`--admonition-chevron-size`	Size of chevron toggle (via ::after)	`0.875em`
`--admonition-chevron-transition`	Animation timing for chevron rotation	`transform var(--transition-duration-base)`
`--admonition-chevron-rotation`	Rotation angle when expanded	`90deg`

Color Derivation Tokens

Controls how base colors are transformed for borders, title text, and backgrounds using CSS color-mix().

Token	Description	Default Value
`--admonition-border-opacity`	Opacity of borders (higher = more opaque)	`40%`
`--admonition-title-color-weight`	Amount of base color mixed with black for title text	`95%`
`--admonition-title-background-tint`	Opacity/tint of base color for title background	`12.5%`
`--admonition-content-background-tint`	Opacity/tint of base color for content background	`0%`

Type-Specific Color Tokens

Base colors for each admonition type. Icons, accent borders, and backgrounds derive from these colors automatically.

Token	Description	Default Value
`--admonition-note-color`	Base color for Note admonitions	`var(--color-gray-600)`
`--admonition-note-color-dark`	Base color for Note in dark mode	`var(--color-gray-400)`
`--admonition-info-color`	Base color for Info admonitions	`var(--color-blue-600)`
`--admonition-info-color-dark`	Base color for Info in dark mode	`var(--color-blue-400)`
`--admonition-tip-color`	Base color for Tip admonitions	`var(--color-yellow-600)`
`--admonition-tip-color-dark`	Base color for Tip in dark mode	`var(--color-yellow-400)`
`--admonition-important-color`	Base color for Important admonitions	`var(--color-purple-600)`
`--admonition-important-color-dark`	Base color for Important in dark mode	`var(--color-purple-400)`
`--admonition-success-color`	Base color for Success admonitions	`var(--color-green-600)`
`--admonition-success-color-dark`	Base color for Success in dark mode	`var(--color-green-400)`
`--admonition-failure-color`	Base color for Failure admonitions	`var(--color-red-600)`
`--admonition-failure-color-dark`	Base color for Failure in dark mode	`var(--color-red-400)`
`--admonition-warning-color`	Base color for Warning admonitions	`var(--color-amber-600)`
`--admonition-warning-color-dark`	Base color for Warning in dark mode	`var(--color-amber-400)`
`--admonition-danger-color`	Base color for Danger admonitions	`var(--color-orange-600)`
`--admonition-danger-color-dark`	Base color for Danger in dark mode	`var(--color-orange-400)`
`--admonition-error-color`	Base color for Error admonitions	`var(--color-red-600)`
`--admonition-error-color-dark`	Base color for Error in dark mode	`var(--color-red-400)`

Examples

Default Admonitions

All nine admonition types with default styling:

:root {
  /* No design token overrides */
}

Note

This example demonstrates all nine admonition types using default styling with no token overrides. Each type displays its unique icon and color scheme.

Info

Notice how each admonition type uses a distinct base color that automatically controls the icon, border, and subtle background tints.

Tip

The spacing between admonitions inherits from --content-spacing, providing automatic responsive behavior on mobile and tablet devices.

Important

Icons are rendered via CSS ::before pseudo-elements using Bootstrap Icons, allowing flexible color control through design tokens.

Success

Dark mode variants are defined for all color tokens and applied automatically based on system preference or explicit user choice.

Failure

Border colors use 40% opacity mixing with transparent for softer, more subtle borders in both light and dark modes.

Warning

Title text uses 95% of the base color mixed with black, while title backgrounds use 12.5% tinting for subtle emphasis.

Danger

Content backgrounds default to 0% tinting (no background), but theme authors can increase --admonition-content-background-tint for colored backgrounds.

Error

Each admonition type follows consistent spacing, typography, and visual hierarchy controlled by centralized design tokens.

Admonitions with Titles

Admonitions can include custom titles:

:root {
  /* No design token overrides */
}

Custom Title

This example demonstrates how admonitions can include custom titles in addition to the type indicator. The title appears in the <summary> element alongside the type icon.

Title Typography

Title font family, size, weight, and line height are controlled by the --admonition-title-* design tokens, allowing customization independent of body content.

Collapsible Admonitions

Foldable admonitions using native <details> elements:

:root {
  /* No design token overrides */
}

Initially Expanded

This example demonstrates collapsible admonitions using native HTML <details> elements. The chevron toggle appears via CSS ::after pseudo-element and rotates smoothly when opened or closed—no JavaScript required.

Initially Collapsed

Click to reveal this content. The collapsible behavior is controlled by the is-folded attribute. Chevron size and rotation timing are customizable via --admonition-chevron-* design tokens.

Custom Spacing

Adjust spacing for different document contexts:

:root {
  --admonition-spacing: var(--space-12);
  --admonition-padding: var(--space-6);
}

Increased Spacing

This example uses --admonition-spacing: var(--space-12) for larger vertical margins and --admonition-padding: var(--space-6) for more generous internal padding, creating an open, airy layout.

Custom Typography

Customize title typography for different emphasis:

:root {
  --admonition-title-font-family: var(--font-family-serif);
  --admonition-title-font-size: var(--font-size-lg);
  --admonition-title-font-weight: 700;
}

Typography Customization

This example demonstrates title typography customization using serif font family (--admonition-title-font-family), larger font size (--admonition-title-font-size: var(--font-size-lg)), and bolder weight (--admonition-title-font-weight: 700).

Custom Colors

Customize admonition colors using type-specific color tokens. Each token controls icon, border, and background colors together:

:root {
  --admonition-warning-color: var(--color-orange-700);
  --admonition-tip-color: var(--color-cyan-600);
}

Color Customization

This example demonstrates color customization by setting --admonition-tip-color: var(--color-cyan-600). A single token change updates the icon, border, title text color, and background tint automatically through CSS color-mix() derivation.

Compact Admonitions

Reduce spacing for dense layouts:

:root {
  --admonition-padding: var(--space-2);
  --admonition-gap: var(--space-2);
}

Compact Spacing

This example demonstrates reduced spacing, creating a tighter, more condensed layout suitable for space-constrained designs.

Blocky Admonitions

Create vibrant, high-impact admonitions with solid colored backgrounds:

:root {
  --admonition-title-background-tint: 30%;
  --admonition-content-background-tint: 30%;
  --admonition-border-radius: 0;
  --admonition-border-width: 0;
  --admonition-accent-border-width: 4px;
}

Bold Styling

This example demonstrates vibrant, high-impact styling using 30% background tints for both title and content, no border radius, no main borders, and a thick 4px accent border.

Subtle Admonitions

Minimal visual emphasis with subtle backgrounds and reduced opacity for discrete callouts:

:root {
  --admonition-title-background-tint: 8%;
  --admonition-content-background-tint: 4%;
  --admonition-border-opacity: 50%;
  --admonition-border-width: 0;
  --admonition-accent-border-width: 3px;
  --surface-background: #1a1a1a;
  --text-color-primary: #e0e0e0;
}

Subtle Styling

This example demonstrates minimal visual emphasis using reduced background tints (8% title, 4% content), lighter borders (50% opacity), no main border, a 3px accent border, and a dark color scheme. Perfect for discrete callouts that don't dominate the page.

Tips

Type palettes: Set --admonition-<type>-color (and -dark) to update icon, border, and background tints together.

Spacing control: Use --admonition-spacing and --admonition-padding to tune layout without changing global --content-spacing.

Toggle affordances: Collapsible styles use --admonition-chevron-* tokens, so customize those to match your disclosure controls.

Title emphasis: Use --admonition-title-font-size and --admonition-title-font-weight to distinguish title hierarchy.