feat(theme): add opt-in severity-based colors for containers, alerts, and badges (#5373)

docs/en/guide/markdown.md

@@ -445,6 +445,8 @@ VitePress also supports [GitHub-flavored alerts](https://docs.github.com/en/get-
 > [!CAUTION]
 > Negative potential consequences of an action.
 
+By default, alert colors match GitHub's, with caution and danger both rendering in red. Enable [`themeConfig.gradedContainers`](../reference/default-theme-config#gradedcontainers) to use a graded severity scale: danger (red), warning (orange), and caution (yellow). Note that `[!DANGER]` is a VitePress extension and will render as a regular blockquote on GitHub.
+
 ## Syntax Highlighting in Code Blocks
 
 VitePress uses [Shiki](https://github.com/shikijs/shiki) to highlight language syntax in Markdown code blocks, using coloured text. Shiki supports a wide variety of programming languages. All you need to do is append a valid language alias to the beginning backticks for the code block:

docs/en/reference/default-theme-badge.md

@@ -14,7 +14,7 @@ You may use the `Badge` component which is globally available.
 ### Title <Badge type="info" text="default" />
 ### Title <Badge type="tip" text="^1.9.0" />
 ### Title <Badge type="warning" text="beta" />
-### Title <Badge type="danger" text="caution" />
+### Title <Badge type="danger" text="deprecated" />
 ```
 
 Code above renders like:
@@ -22,7 +22,7 @@ Code above renders like:
 ### Title <Badge type="info" text="default" />
 ### Title <Badge type="tip" text="^1.9.0" />
 ### Title <Badge type="warning" text="beta" />
-### Title <Badge type="danger" text="caution" />
+### Title <Badge type="danger" text="deprecated" />
 
 ## Custom Children
 
@@ -44,9 +44,21 @@ You can customize the style of badges by overriding css variables. The following
   --vp-badge-info-text: var(--vp-c-text-2);
   --vp-badge-info-bg: var(--vp-c-default-soft);
 
+  --vp-badge-note-border: transparent;
+  --vp-badge-note-text: var(--vp-c-note-1);
+  --vp-badge-note-bg: var(--vp-c-note-soft);
+
   --vp-badge-tip-border: transparent;
-  --vp-badge-tip-text: var(--vp-c-brand-1);
+  --vp-badge-tip-text: var(--vp-c-tip-1);
-  --vp-badge-tip-bg: var(--vp-c-brand-soft);
+  --vp-badge-tip-bg: var(--vp-c-tip-soft);
+
+  --vp-badge-important-border: transparent;
+  --vp-badge-important-text: var(--vp-c-important-1);
+  --vp-badge-important-bg: var(--vp-c-important-soft);
+
+  --vp-badge-caution-border: transparent;
+  --vp-badge-caution-text: var(--vp-c-caution-1);
+  --vp-badge-caution-bg: var(--vp-c-caution-soft);
 
   --vp-badge-warning-border: transparent;
   --vp-badge-warning-text: var(--vp-c-warning-1);
@@ -67,7 +79,7 @@ interface Props {
   // When `<slot>` is passed, this value gets ignored.
   text?: string
 
-  // Defaults to `tip`.
+  // Defaults to `tip`. Matches markdown containers/alerts colors.
-  type?: 'info' | 'tip' | 'warning' | 'danger'
+  type?: 'info' | 'note' | 'tip' | 'important' | 'caution' | 'warning' | 'danger'
 }
 ```

docs/en/reference/default-theme-config.md

@@ -484,6 +484,13 @@ Can be used to customize the label of the skip to content link. This link is sho
 
 Whether to show an external link icon next to external links in markdown.
 
+## gradedContainers
+
+- Type: `boolean`
+- Default: `false`
+
+Whether to color [custom containers](../guide/markdown#custom-containers), [GitHub-flavored alerts](../guide/markdown#github-flavored-alerts), and badges on a graded severity scale — danger red, warning orange, caution yellow. By default, colors match GitHub's alerts, where caution shares danger's red and warning is yellow.
+
 ## `useLayout` <Badge type="info" text="composable" />
 
 Returns layout-related data. The returned object has the following type:

src/client/theme-default/Layout.vue

@@ -19,7 +19,7 @@ const {
 
 registerWatchers({ closeSidebar })
 
-const { frontmatter } = useData()
+const { frontmatter, theme } = useData()
 
 const slots = useSlots()
 const heroImageSlotExists = computed(() => !!slots['home-hero-image'])
@@ -31,7 +31,10 @@ provide(layoutInfoInjectionKey, { heroImageSlotExists })
   <div
     v-if="frontmatter.layout !== false"
     class="Layout"
-    :class="frontmatter.pageClass"
+    :class="[
+      frontmatter.pageClass,
+      theme.gradedContainers && 'vp-graded-containers'
+    ]"
   >
     <slot name="layout-top" />
     <VPSkipLink />

src/client/theme-default/components/VPBadge.vue

@@ -1,9 +1,8 @@
 <script setup lang="ts">
-interface Props {
+withDefaults(defineProps<{
   text?: string
-  type?: 'info' | 'tip' | 'warning' | 'danger'
+  type?: 'info' | 'note' | 'tip' | 'important' | 'caution' | 'warning' | 'danger'
-}
+}>(), {
-withDefaults(defineProps<Props>(), {
   type: 'tip'
 })
 </script>
@@ -66,12 +65,30 @@ withDefaults(defineProps<Props>(), {
   background-color: var(--vp-badge-info-bg);
 }
 
+.VPBadge.note {
+  border-color: var(--vp-badge-note-border);
+  color: var(--vp-badge-note-text);
+  background-color: var(--vp-badge-note-bg);
+}
+
 .VPBadge.tip {
   border-color: var(--vp-badge-tip-border);
   color: var(--vp-badge-tip-text);
   background-color: var(--vp-badge-tip-bg);
 }
 
+.VPBadge.important {
+  border-color: var(--vp-badge-important-border);
+  color: var(--vp-badge-important-text);
+  background-color: var(--vp-badge-important-bg);
+}
+
+.VPBadge.caution {
+  border-color: var(--vp-badge-caution-border);
+  color: var(--vp-badge-caution-text);
+  background-color: var(--vp-badge-caution-bg);
+}
+
 .VPBadge.warning {
   border-color: var(--vp-badge-warning-border);
   color: var(--vp-badge-warning-text);

src/client/theme-default/styles/vars.css

@@ -69,6 +69,11 @@
   --vp-c-yellow-3: #9f6a00;
   --vp-c-yellow-soft: rgba(234, 179, 8, 0.14);
 
+  --vp-c-orange-1: #9a4224;
+  --vp-c-orange-2: #b95a00;
+  --vp-c-orange-3: #c16200;
+  --vp-c-orange-soft: rgba(249, 115, 22, 0.14);
+
   --vp-c-red-1: #b8272c;
   --vp-c-red-2: #d5393e;
   --vp-c-red-3: #e0575b;
@@ -103,6 +108,11 @@
   --vp-c-yellow-3: #a46a0a;
   --vp-c-yellow-soft: rgba(234, 179, 8, 0.16);
 
+  --vp-c-orange-1: #fb8c00;
+  --vp-c-orange-2: #e46a02;
+  --vp-c-orange-3: #b45309;
+  --vp-c-orange-soft: rgba(249, 115, 22, 0.16);
+
   --vp-c-red-1: #f66f81;
   --vp-c-red-2: #f14158;
   --vp-c-red-3: #b62a3c;
@@ -256,6 +266,18 @@
   --vp-c-caution-soft: var(--vp-c-red-soft);
 }
 
+:root:where(:has(.vp-graded-containers)) {
+  --vp-c-warning-1: var(--vp-c-orange-1);
+  --vp-c-warning-2: var(--vp-c-orange-2);
+  --vp-c-warning-3: var(--vp-c-orange-3);
+  --vp-c-warning-soft: var(--vp-c-orange-soft);
+
+  --vp-c-caution-1: var(--vp-c-yellow-1);
+  --vp-c-caution-2: var(--vp-c-yellow-2);
+  --vp-c-caution-3: var(--vp-c-yellow-3);
+  --vp-c-caution-soft: var(--vp-c-yellow-soft);
+}
+
 /**
  * Typography
  * -------------------------------------------------------------------------- */
@@ -438,6 +460,11 @@
   --vp-custom-block-important-bg: var(--vp-c-important-soft);
   --vp-custom-block-important-code-bg: var(--vp-c-important-soft);
 
+  --vp-custom-block-caution-border: transparent;
+  --vp-custom-block-caution-text: var(--vp-c-text-1);
+  --vp-custom-block-caution-bg: var(--vp-c-caution-soft);
+  --vp-custom-block-caution-code-bg: var(--vp-c-caution-soft);
+
   --vp-custom-block-warning-border: transparent;
   --vp-custom-block-warning-text: var(--vp-c-text-1);
   --vp-custom-block-warning-bg: var(--vp-c-warning-soft);
@@ -448,11 +475,6 @@
   --vp-custom-block-danger-bg: var(--vp-c-danger-soft);
   --vp-custom-block-danger-code-bg: var(--vp-c-danger-soft);
 
-  --vp-custom-block-caution-border: transparent;
-  --vp-custom-block-caution-text: var(--vp-c-text-1);
-  --vp-custom-block-caution-bg: var(--vp-c-caution-soft);
-  --vp-custom-block-caution-code-bg: var(--vp-c-caution-soft);
-
   --vp-custom-block-details-border: var(--vp-custom-block-info-border);
   --vp-custom-block-details-text: var(--vp-custom-block-info-text);
   --vp-custom-block-details-bg: var(--vp-custom-block-info-bg);
@@ -535,10 +557,22 @@
   --vp-badge-info-text: var(--vp-c-text-2);
   --vp-badge-info-bg: var(--vp-c-default-soft);
 
+  --vp-badge-note-border: transparent;
+  --vp-badge-note-text: var(--vp-c-note-1);
+  --vp-badge-note-bg: var(--vp-c-note-soft);
+
   --vp-badge-tip-border: transparent;
   --vp-badge-tip-text: var(--vp-c-tip-1);
   --vp-badge-tip-bg: var(--vp-c-tip-soft);
 
+  --vp-badge-important-border: transparent;
+  --vp-badge-important-text: var(--vp-c-important-1);
+  --vp-badge-important-bg: var(--vp-c-important-soft);
+
+  --vp-badge-caution-border: transparent;
+  --vp-badge-caution-text: var(--vp-c-caution-1);
+  --vp-badge-caution-bg: var(--vp-c-caution-soft);
+
   --vp-badge-warning-border: transparent;
   --vp-badge-warning-text: var(--vp-c-warning-1);
   --vp-badge-warning-bg: var(--vp-c-warning-soft);

types/default-theme.d.ts

@@ -135,6 +135,16 @@ export namespace DefaultTheme {
      */
     externalLinkIcon?: boolean
 
+    /**
+     * Color custom containers, GitHub-flavored alerts, and badges on a
+     * graded severity scale (danger red > warning orange > caution yellow)
+     * instead of matching GitHub's alert colors, where caution is red and
+     * warning is yellow.
+     *
+     * @default false
+     */
+    gradedContainers?: boolean
+
     /**
      * Customize text of 404 page.
      */