docs: align callout names with GitHub alerts (#242)

johnleider · web-flow · commit 45745fb4a265 · 2026-05-23T11:10:31.000-05:00
Rename `info` → `note` and `error` → `caution`, add `important`
(uses accent color). Move `askai` to secondary. Migrate 11 pages
from `[!INFO]` to `[!NOTE]`.
diff --git a/.claude/rules/docs.md b/.claude/rules/docs.md
@@ -273,8 +273,10 @@ Real worked examples on master:
 | `::: code-group` | Tabbed code blocks |
 | `::: faq` | FAQ section with `???` questions |
 | `> [!TIP]` | Informational callout (empty tip surfaces a random tip from curated pool) [intent:340, intent:341] |
+| `> [!NOTE]` | Neutral informational callout |
 | `> [!WARNING]` | Cautionary callout |
-| `> [!ERROR]` | Error/danger callout |
+| `> [!CAUTION]` | Danger/severe callout |
+| `> [!IMPORTANT]` | Critical-emphasis callout |
 | `[^name]` | Footnote anchor — see [Footnotes](#footnotes) |
 | `` ```vue Anatomy playground `` `` | Live anatomy preview |
 | `` ```ts collapse `` `` | Collapsible code block |
diff --git a/apps/docs/CLAUDE.md b/apps/docs/CLAUDE.md
@@ -139,7 +139,7 @@ build/
 
 | Component | Purpose |
 |-----------|---------|
-| `DocsCallout` | GitHub-style callouts (`> [!TIP]`, `> [!WARNING]`, `> [!ERROR]`, `> [!ASKAI]`) |
+| `DocsCallout` | GitHub-style callouts (`> [!TIP]`, `> [!NOTE]`, `> [!WARNING]`, `> [!CAUTION]`, `> [!IMPORTANT]`, `> [!ASKAI]`) |
 | `DocsExample` | Live examples from `examples/` with code |
 | `DocsMarkup` | Syntax-highlighted code blocks |
 | `DocsApi` | Auto-generated API tables with inline/links toggle |
@@ -194,7 +194,7 @@ import BasicExampleRaw from '@/examples/components/tabs/basic.vue?raw'
 - UnoCSS utilities for all styling
 - Prefer markdown for documentation pages
 - **Examples**: Use `::: example` blocks in `.md` pages for live demos; use `<DocsExample>` directly only in `.vue` pages
-- **Callouts**: Use `> [!TIP]`, `> [!WARNING]`, `> [!ERROR]` for alerts. Use `> [!ASKAI] question` to prompt Ask AI—phrase as a question the user would ask (e.g., "How do I add validation?"), not a question to the user. Use `> [!TOUR] tour-id` to embed a clickable tour callout—the tour name and description are pulled from the discovery registry automatically.
+- **Callouts**: Use `> [!TIP]`, `> [!NOTE]`, `> [!WARNING]`, `> [!CAUTION]`, `> [!IMPORTANT]` for alerts (GitHub-aligned). Use `> [!ASKAI] question` to prompt Ask AI—phrase as a question the user would ask (e.g., "How do I add validation?"), not a question to the user. Use `> [!TOUR] tour-id` to embed a clickable tour callout—the tour name and description are pulled from the discovery registry automatically.
 - **Vue code in markdown fences**: Indent `<script>` and `<style>` content by 2 spaces for visual alignment with `<template>`
 - Examples: `src/examples/components/{component}/` or `src/examples/composables/{composable}/`
 - Component docs: `pages/components/{category}/{component}.md`
diff --git a/apps/docs/build/markdown.ts b/apps/docs/build/markdown.ts
@@ -270,15 +270,15 @@ export function applyMarkdownPlugins (md: MarkdownIt, highlighter: DocsHighlight
       : '</p>'
   }
 
-  // GitHub-style callouts: > [!TIP], > [!INFO], > [!WARNING], > [!ERROR], > [!ASKAI], > [!DISCORD], > [!TOUR]
+  // GitHub-style callouts: > [!TIP], > [!NOTE], > [!WARNING], > [!CAUTION], > [!IMPORTANT], > [!ASKAI], > [!DISCORD], > [!TOUR]
   const defaultBlockquoteOpen = md.renderer.rules.blockquote_open
   const defaultBlockquoteClose = md.renderer.rules.blockquote_close
 
   md.renderer.rules.blockquote_open = (tokens, index, options, env, self) => {
     // Look ahead: blockquote_open -> paragraph_open -> inline
     const inlineToken = tokens[index + 2]
     if (inlineToken?.type === 'inline' && inlineToken.content) {
-      const match = inlineToken.content.match(/^\[!(TIP|INFO|WARNING|ERROR|ASKAI|DISCORD|TOUR)\]\s*(.*)/)
+      const match = inlineToken.content.match(/^\[!(TIP|NOTE|WARNING|CAUTION|IMPORTANT|ASKAI|DISCORD|TOUR)\]\s*(.*)/)
       if (match) {
         const type = match[1].toLowerCase()
         env._calloutType = type
@@ -314,8 +314,8 @@ export function applyMarkdownPlugins (md: MarkdownIt, highlighter: DocsHighlight
         if (inlineToken.children?.length) {
           const firstChild = inlineToken.children[0]
           if (firstChild?.type === 'text') {
-            // Only TIP|INFO|WARNING|ERROR reach here - ASKAI, DISCORD, TOUR return early with cleared content
-            firstChild.content = firstChild.content.replace(/^\[!(TIP|INFO|WARNING|ERROR)\]\s*/, '')
+            // Only TIP|NOTE|WARNING|CAUTION|IMPORTANT reach here - ASKAI, DISCORD, TOUR return early with cleared content
+            firstChild.content = firstChild.content.replace(/^\[!(TIP|NOTE|WARNING|CAUTION|IMPORTANT)\]\s*/, '')
           }
         }
 
diff --git a/apps/docs/src/components/docs/DocsAskMessage.vue b/apps/docs/src/components/docs/DocsAskMessage.vue
@@ -12,6 +12,9 @@
   import { decodeBase64 } from '@/utilities/decodeBase64'
   import { getCurrentInstance, h, nextTick, onBeforeUnmount, render, toRef, useTemplateRef, watch } from 'vue'
 
+  // Types
+  import type { CalloutType } from './calloutConfig'
+
   const props = defineProps<{
     role: 'user' | 'assistant'
     content: string
@@ -88,7 +91,7 @@
 
   function mountAlertComponents () {
     mountTo('[data-alert]', el => {
-      const type = el.dataset.type as 'tip' | 'info' | 'warning' | 'error'
+      const type = el.dataset.type as CalloutType
       const encoded = el.dataset.content
       if (!type || !encoded) return null
       return h(DocsCallout, { type }, {
diff --git a/apps/docs/src/components/docs/DocsCallout.vue b/apps/docs/src/components/docs/DocsCallout.vue
@@ -31,7 +31,7 @@
    * Callout props - certain props are required based on type:
    * - type: 'askai' requires `question`
    * - type: 'tour' requires `tourId`
-   * - type: 'tip' | 'info' | 'warning' | 'error' | 'discord' have no additional required props
+   * - type: 'tip' | 'note' | 'warning' | 'caution' | 'important' | 'discord' have no additional required props
    */
   export interface DocsCalloutProps {
     type: CalloutType
diff --git a/apps/docs/src/components/docs/calloutConfig.ts b/apps/docs/src/components/docs/calloutConfig.ts
@@ -9,33 +9,38 @@ export interface CalloutConfig {
   classes: string
 }
 
-export type CalloutType = 'tip' | 'info' | 'warning' | 'error' | 'askai' | 'discord' | 'tour'
+export type CalloutType = 'tip' | 'note' | 'warning' | 'caution' | 'important' | 'askai' | 'discord' | 'tour'
 
 const CALLOUT_CONFIG: Record<CalloutType, CalloutConfig> = {
   tip: {
     icon: 'lightbulb',
     title: 'Tip',
     classes: 'bg-success-10 border-success-50 text-success',
   },
-  info: {
+  note: {
     icon: 'info',
-    title: 'Info',
+    title: 'Note',
     classes: 'bg-info-10 border-info-50 text-info',
   },
   warning: {
     icon: 'alert',
     title: 'Warning',
     classes: 'bg-warning-10 border-warning-50 text-warning',
   },
-  error: {
+  caution: {
     icon: 'error',
-    title: 'Error',
+    title: 'Caution',
     classes: 'bg-error-10 border-error-50 text-error',
   },
+  important: {
+    icon: 'alert-circle',
+    title: 'Important',
+    classes: 'bg-accent-10 border-accent-50 text-accent',
+  },
   askai: {
     icon: 'create',
     title: 'Ask AI',
-    classes: 'bg-accent-10 border-accent-50 text-accent cursor-pointer hover:bg-accent-20 transition-colors',
+    classes: 'bg-secondary-10 border-secondary-50 text-secondary cursor-pointer hover:bg-secondary-20 transition-colors',
   },
   discord: {
     icon: 'discord',
diff --git a/apps/docs/src/composables/useMarkdown.ts b/apps/docs/src/composables/useMarkdown.ts
@@ -7,7 +7,7 @@
  *
  * TODO: Dedupe with build/markdown.ts - shared logic includes:
  * - Table wrapping (overflow-x-auto)
- * - Callout detection ([!TIP], [!INFO], etc.)
+ * - Callout detection ([!TIP], [!NOTE], etc.)
  * - Mermaid code block handling
  * - VUE_API_NAMES inline code detection
  * - Shiki themes and createApiTransformer()
@@ -66,14 +66,14 @@ function getMarked (hl: Highlighter): Marked {
         return `<div class="overflow-x-auto mb-4"><table>${thead}${tbody}</table></div>`
       },
       blockquote ({ raw }) {
-        // GitHub-style callouts: > [!TIP], > [!INFO], > [!WARNING], > [!ERROR], > [!TRY], > [!TOUR]
+        // GitHub-style callouts: > [!TIP], > [!NOTE], > [!WARNING], > [!CAUTION], > [!IMPORTANT], > [!TRY], > [!TOUR]
         const innerContent = raw
           .split('\n')
           .map(line => line.replace(/^>\s?/, ''))
           .join('\n')
           .trim()
 
-        const match = innerContent.match(/^\[!(TIP|INFO|WARNING|ERROR|TRY|TOUR)\]\s*([\s\S]*)/)
+        const match = innerContent.match(/^\[!(TIP|NOTE|WARNING|CAUTION|IMPORTANT|TRY|TOUR)\]\s*([\s\S]*)/)
         if (match) {
           const type = match[1].toLowerCase()
           const rest = match[2].trim()
diff --git a/apps/docs/src/pages/components/semantic/image.md b/apps/docs/src/pages/components/semantic/image.md
@@ -49,7 +49,7 @@ Headless image component with state-driven placeholder and error fallback. Track
 </template>
 ```
 
-> [!INFO]
+> [!NOTE]
 > `src` is the only native image attribute that doesn't live on `Image.Img` because it drives the load state machine — the `idle → loading → loaded | error` lifecycle can't function without knowing the URL to track, so `Image.Root` owns it. Every other image attribute (`alt`, `width`, `height`, `srcset`, `sizes`, `crossorigin`, `referrerpolicy`, `decoding`, `loading`, `fetchpriority`) is a pure rendering concern and lives on `Image.Img`, where it describes the element that actually renders it.
 
 ## Architecture
diff --git a/apps/docs/src/pages/composables/plugins/use-date.md b/apps/docs/src/pages/composables/plugins/use-date.md
@@ -62,7 +62,7 @@ app.use(
 )
 ```
 
-> [!INFO]
+> [!NOTE]
 > The `adapter` option is **required**. The `V0DateAdapter` is exported from a separate subpath (`@vuetify/v0/date`) to avoid bundling the Temporal polyfill unless explicitly used. If you don't need date functionality, simply don't install the plugin—no polyfill will be loaded.
 
 ## Usage
diff --git a/apps/docs/src/pages/guide/essentials/using-the-docs.md b/apps/docs/src/pages/guide/essentials/using-the-docs.md
@@ -436,10 +436,14 @@ The documentation uses callout boxes to highlight important information:
 
 > [!TIP] Best practices and helpful hints you can apply immediately.
 
-> [!INFO] Additional context and notes for deeper understanding.
+> [!NOTE] Additional context and notes for deeper understanding.
+
+> [!IMPORTANT] Critical information you should not miss.
 
 > [!WARNING] Cautions and common mistakes to avoid.
 
+> [!CAUTION] Severe issues or destructive operations to watch out for.
+
 > [!ASKAI] How do I find the right composable for what I'm building?
 
 > [!TOUR] using-the-docs
diff --git a/apps/docs/src/pages/guide/fundamentals/building-frameworks.md b/apps/docs/src/pages/guide/fundamentals/building-frameworks.md
@@ -21,7 +21,7 @@ When building a component framework, you're often reimplementing the same patter
 
 <DocsPageFeatures :frontmatter />
 
-> [!INFO] Prerequisites
+> [!NOTE] Prerequisites
 > This guide builds on concepts from [Core](/guide/fundamentals/core), [Components](/guide/fundamentals/components), and [Composables](/guide/fundamentals/composables). Read those first if you're new to v0.
 
 ## Getting Started
diff --git a/apps/docs/src/pages/guide/fundamentals/styling.md b/apps/docs/src/pages/guide/fundamentals/styling.md
@@ -49,7 +49,7 @@ All v0 components expose state via `data-*` attributes in the `attrs` object:
 | [Popover](/components/disclosure/popover) | <span class="whitespace-nowrap">`data-open`</span> | Activator element |
 | [Dialog](/components/disclosure/dialog) | <span class="whitespace-nowrap">`data-open`</span> | Activator element |
 
-> [!INFO]
+> [!NOTE]
 > Attributes are only present when `true`. Use `[data-selected]` not `[data-selected="true"]`.
 
 > [!ASKAI] What data attributes does Selection.Item expose and how do I style them?
diff --git a/apps/docs/src/pages/guide/integration/building-docs.md b/apps/docs/src/pages/guide/integration/building-docs.md
@@ -76,7 +76,7 @@ The `DocsCodeGroup` component powers all tabbed code examples. It uses `createSi
 </template>
 ```
 
-> [!INFO]
+> [!NOTE]
 > **Why this works:** `createSingle` handles the selection logic. `useProxyRegistry` exposes registered items for iteration. The component owns all styling and accessibility attributes.
 
 ### Mobile Navigation
diff --git a/apps/docs/src/pages/guide/integration/devkey.md b/apps/docs/src/pages/guide/integration/devkey.md
@@ -25,7 +25,7 @@ DevKey ([live](https://devkey.vuetifyjs.com), [source](https://github.com/vuetif
 > [!TIP]
 > Looking for the fastest way to start? Run `pnpm create vuetify0` to scaffold a fresh DevKey-shaped project locally.
 
-> [!INFO]
+> [!NOTE]
 > Want a guided walkthrough? The [Vuetify0 alpha announcement](https://vuetifyjs.com/blog/announcing-vuetify0-alpha) builds DevKey step-by-step as a reusable UI library — landing page, auth flow, dashboard, and command palette.
 
 ## Preview
@@ -105,7 +105,7 @@ bun install
 
 :::
 
-> [!INFO]
+> [!NOTE]
 > `create vuetify0` produces the same layout as the DevKey repository. Cloning directly is useful if you want to track upstream changes.
 
 ## Scripts
diff --git a/apps/docs/src/pages/guide/tooling/vuetify-cli.md b/apps/docs/src/pages/guide/tooling/vuetify-cli.md
@@ -249,7 +249,7 @@ bunx @vuetify/cli docs
 
 :::
 
-> [!INFO]
+> [!NOTE]
 > The CLI auto-detects your installed Vuetify version and opens the correct documentation site.
 
 ### analyze
diff --git a/apps/docs/src/pages/introduction/getting-started.md b/apps/docs/src/pages/introduction/getting-started.md
@@ -167,7 +167,7 @@ vuetify0(app)
 app.mount('#app')
 ```
 
-> [!INFO]
+> [!NOTE]
 > For additional plugins, theming options, and advanced configuration, see the [Guide](/guide).
 
 ## Requirements
diff --git a/apps/docs/src/pages/roadmap.md b/apps/docs/src/pages/roadmap.md
@@ -24,7 +24,7 @@ Track the development of @vuetify/v0. Milestones are organized by time horizon:
 
 <DocsRoadmap />
 
-> [!INFO] Want to help shape the future of this project? [Become a Founder Supporter](mailto:john@vuetifyjs.com?subject=Founder%20Supporter%20Inquiry) and gain a guiding voice in what we build next.
+> [!NOTE] Want to help shape the future of this project? [Become a Founder Supporter](mailto:john@vuetifyjs.com?subject=Founder%20Supporter%20Inquiry) and gain a guiding voice in what we build next.
 
 ## Alpha
 
diff --git a/apps/docs/src/styles/tokens.css b/apps/docs/src/styles/tokens.css
@@ -95,6 +95,11 @@
 .bg-accent-20, .hover\:bg-accent-20:hover { background: color-mix(in srgb, var(--v0-accent), transparent 80%); }
 .border-accent-50 { border-color: color-mix(in srgb, var(--v0-accent), transparent 50%); }
 
+/* Secondary */
+.bg-secondary-10 { background: color-mix(in srgb, var(--v0-secondary), transparent 90%); }
+.bg-secondary-20, .hover\:bg-secondary-20:hover { background: color-mix(in srgb, var(--v0-secondary), transparent 80%); }
+.border-secondary-50 { border-color: color-mix(in srgb, var(--v0-secondary), transparent 50%); }
+
 /* Discord */
 .bg-discord-10 { background: color-mix(in srgb, var(--v0-discord), transparent 90%); }
 .bg-discord-20, .hover\:bg-discord-20:hover { background: color-mix(in srgb, var(--v0-discord), transparent 80%); }

Original file line number	Diff line number	Diff line change
`@@ -62,7 +62,7 @@ app.use(`
`62`	`62`	`)`
`63`	`63`	```
`64`	`64`
`65`		`-> [!INFO]`
	`65`	`+> [!NOTE]`
`66`	`66`	> The `adapter` option is required. The `V0DateAdapter` is exported from a separate subpath (`@vuetify/v0/date`) to avoid bundling the Temporal polyfill unless explicitly used. If you don't need date functionality, simply don't install the plugin—no polyfill will be loaded.
`67`	`67`
`68`	`68`	`## Usage`