blume 1.5.3 → 1.6.1

package/src/cli/commands/build.ts

@@ -25,6 +25,7 @@ import {
   buildSkillsIndex,
   collectSkills,
 } from "../../ai/skills.ts";
+import type { SkillArtifact } from "../../ai/skills.ts";
 import {
   buildSignaturesDirectory,
   SIGNATURES_DIRECTORY_PATH,
@@ -46,6 +47,11 @@ import {
   injectWorkerNegotiation,
   NEGOTIATION_WORKER_FILE,
 } from "../../deploy/cloudflare-negotiation.ts";
+import {
+  auditVercelFunctions,
+  blumeDependencyNames,
+  functionBundleVerdict,
+} from "../../deploy/function-bundle.ts";
 import { buildNetlifyHeaders } from "../../deploy/headers.ts";
 import {
   buildNetlifyRedirects,
@@ -195,29 +201,29 @@ export const emitHeaderFiles = async (
 };
 
 /**
- * Publish the configured Agent Skills: copy each skill artifact under
- * `.well-known/agent-skills/` and emit the discovery index. A user-shipped
- * `public/.well-known/agent-skills/index.json` takes over the whole surface,
- * matching every other generated artifact.
+ * Collect the Agent Skills `ai.skills` publishes, once per build, so both the
+ * skills surface and llms.txt (which lists them) read the same set. Empty
+ * when the feature is off, the directory is missing, nothing in it is
+ * publishable (each with a warning), or a user-shipped
+ * `public/.well-known/agent-skills/index.json` already owns the surface.
  */
-const emitAgentSkills = async (
+const collectConfiguredSkills = async (
   project: BlumeProject,
   distDir: string
-): Promise<void> => {
+): Promise<SkillArtifact[]> => {
   const configured = project.config.ai.skills;
   if (!configured) {
-    return;
+    return [];
   }
   const dir = resolve(project.context.root, configured);
   if (!existsSync(dir)) {
     logger.warn(
       `ai.skills points at "${configured}" (${dir}), which does not exist; no skills published.`
     );
-    return;
+    return [];
   }
-  const outDir = join(distDir, AGENT_SKILLS_DIR.slice(1));
-  if (existsSync(join(outDir, "index.json"))) {
-    return;
+  if (existsSync(join(distDir, AGENT_SKILLS_DIR.slice(1), "index.json"))) {
+    return [];
   }
   const { skills, warnings } = await collectSkills(dir);
   for (const warning of warnings) {
@@ -225,8 +231,26 @@ const emitAgentSkills = async (
   }
   if (skills.length === 0) {
     logger.warn(`ai.skills: no publishable skills found in "${configured}".`);
+  }
+  return skills;
+};
+
+/**
+ * Publish the collected Agent Skills: copy each skill artifact under
+ * `.well-known/agent-skills/` and emit the discovery index. A user-shipped
+ * `public/.well-known/agent-skills/index.json` takes over the whole surface
+ * (the collector returns nothing then), matching every other generated
+ * artifact.
+ */
+const emitAgentSkills = async (
+  project: BlumeProject,
+  distDir: string,
+  skills: readonly SkillArtifact[]
+): Promise<void> => {
+  if (skills.length === 0) {
     return;
   }
+  const outDir = join(distDir, AGENT_SKILLS_DIR.slice(1));
   await Promise.all(
     skills.map(async (skill) => {
       const target = join(outDir, skill.path);
@@ -310,12 +334,18 @@ const emitVercelNegotiation = async (
   // endpoint stamps it on dev/server-rendered responses itself.
   const rawMarkdown = await buildRawMarkdown(project);
   const home = rawMarkdown["/"];
+  // The Markdown 404 routes point at the prerendered `404.md`; only wire them
+  // when the build actually emitted it (a project that owns `/404` gets none).
+  const notFoundMarkdown = existsSync(
+    join(root, ".vercel", "output", "static", "404.md")
+  );
   const injected = injectNegotiationRoutes(
     await readFile(configPath, "utf-8"),
     routePaths,
     buildHomeLinkHeader(config, routePaths),
     overrides,
-    home ? markdownTokenCount(agentMarkdown(home)) : undefined
+    home ? markdownTokenCount(agentMarkdown(home)) : undefined,
+    notFoundMarkdown
   );
   if (injected === null) {
     logger.warn(
@@ -329,6 +359,38 @@ const emitVercelNegotiation = async (
   );
 };
 
+/**
+ * Refuse to ship a Vercel function bundle that would crash at runtime: a bare
+ * import the adapter's dependency trace silently dropped (see
+ * `deploy/function-bundle.ts`). A missing package that is one of Blume's own
+ * dependencies is fatal — the generated runtime imports it, so every request
+ * would die; a project's own external import is reported as a warning and left
+ * to the author.
+ */
+const checkVercelFunctionBundles = async (
+  outputDir: string,
+  root: string
+): Promise<void> => {
+  const audits = await auditVercelFunctions(outputDir);
+  if (audits.length === 0) {
+    return;
+  }
+  const own = blumeDependencyNames();
+  let fatal = false;
+  for (const audit of audits) {
+    const verdict = functionBundleVerdict(audit, root, own);
+    if (verdict.fatal) {
+      fatal = true;
+      logger.error(verdict.message);
+    } else {
+      logger.warn(verdict.message);
+    }
+  }
+  if (fatal) {
+    process.exit(1);
+  }
+};
+
 const warnCloudflareNegotiationSkipped = (): void =>
   logger.warn(
     "Could not wire Accept: text/markdown negotiation into dist/server/wrangler.json — raw Markdown stays available at the .md URLs."
@@ -559,7 +621,8 @@ export const isolatedStaticDir = (
  */
 const publishLlmsFiles = async (
   project: BlumeProject,
-  distDir: string
+  distDir: string,
+  skills: readonly SkillArtifact[]
 ): Promise<void> => {
   const indexPath = join(distDir, "llms.txt");
   const fullPath = join(distDir, "llms-full.txt");
@@ -568,7 +631,7 @@ const publishLlmsFiles = async (
   if (!(writeIndex || writeFull)) {
     return;
   }
-  const { index, full } = await buildLlmsFiles(project);
+  const { index, full } = await buildLlmsFiles(project, { skills });
   const writes: Promise<void>[] = [];
   if (writeIndex) {
     writes.push(writeFile(indexPath, index, "utf-8"));
@@ -613,8 +676,10 @@ const publishBuildArtifacts = async (
     warn: (message) => logger.warn(message),
   });
 
+  // Collected once: llms.txt lists the skills the build publishes below.
+  const skills = await collectConfiguredSkills(project, distDir);
   if (project.config.ai.llmsTxt.enabled) {
-    await publishLlmsFiles(project, distDir);
+    await publishLlmsFiles(project, distDir, skills);
   }
 
   // A user's own public/ file (copied into dist by Astro) always wins.
@@ -652,7 +717,7 @@ const publishBuildArtifacts = async (
   }
 
   await emitWellKnownFiles(project.config, distDir);
-  await emitAgentSkills(project, distDir);
+  await emitAgentSkills(project, distDir, skills);
 
   await emitRedirectFiles(project.config, distDir);
   await emitHeaderFiles(project, distDir);
@@ -798,6 +863,15 @@ export const buildCommand = defineCommand({
     // 100` exiting 0 without measuring anything would be a silent false pass
     // in CI.
     if (runtimeDir) {
+      if (
+        project.config.deployment.output === "server" &&
+        project.config.deployment.adapter === "vercel"
+      ) {
+        await checkVercelFunctionBundles(
+          isolatedOutputDir(project.config, project.context),
+          root
+        );
+      }
       await runClientAssetChecks(
         isolatedStaticDir(project.config, project.context),
         args
@@ -831,6 +905,7 @@ export const buildCommand = defineCommand({
     }
 
     if (project.config.deployment.output === "server" && adapter === "vercel") {
+      await checkVercelFunctionBundles(join(root, ".vercel", "output"), root);
       await emitVercelNegotiation(project, markdownRoutePaths(project), root);
     }
 

package/src/cli/commands/dev.ts

@@ -19,8 +19,9 @@ import { prepareProject } from "../prepare.ts";
 
 /**
  * Resolve a `--host` flag value into what Astro/Vite's `server.host` expects.
- * citty (0.1) has no mixed string/boolean arg type, so `host` is declared as a
- * string and a bare `--host` parses as `""` — Node would bind all interfaces
+ * citty has no mixed string/boolean arg type, so `host` is declared as a
+ * string and a bare `--host` parses as `""` (the CLI entry rewrites it to
+ * `--host=` first; see `host-args.ts`) — Node would bind all interfaces
  * for `""`, but Vite's `resolveHostname` treats it as a literal hostname and
  * prints malformed URLs like `http://:4321/`. Match Astro's own `--host`
  * semantics instead: bare flag → `true` (bind all interfaces), `--host
@@ -219,7 +220,9 @@ export const devCommand = defineCommand({
     }).on("all", regenerate);
     const disposers = [
       ...project.sources.map((source) => source.watch?.(regenerate)),
-      () => void projectWatcher.close(),
+      () => {
+        void projectWatcher.close();
+      },
     ].filter((dispose) => dispose !== undefined);
 
     const shutdown = async () => {

package/src/cli/host-args.ts

@@ -0,0 +1,18 @@
+/**
+ * Rewrite a bare `--host` in the raw argv to `--host=` before citty parses it.
+ *
+ * `host` is a string arg (citty has no mixed string/boolean type), and citty
+ * 0.2 parses with `node:util.parseArgs`, where a string option consumes the
+ * next token as its value even when that token is another flag: `blume dev
+ * --host --open` would bind the literal hostname "--open" and drop `--open`.
+ * The `--host=` spelling parses as `""` without touching its neighbor, which
+ * `normalizeHost` then maps to Astro's "bind all interfaces".
+ */
+export const normalizeHostArgs = (rawArgs: readonly string[]): string[] =>
+  rawArgs.map((arg, index) => {
+    if (arg !== "--host") {
+      return arg;
+    }
+    const next = rawArgs[index + 1];
+    return next === undefined || next.startsWith("-") ? "--host=" : arg;
+  });

package/src/cli/index.ts

@@ -17,6 +17,7 @@ import { translateCommand } from "./commands/translate.ts";
 import { validateCommand } from "./commands/validate.ts";
 import { versionCommand } from "./commands/version.ts";
 import { loadEnvFiles } from "./env.ts";
+import { normalizeHostArgs } from "./host-args.ts";
 import { reportInternalError } from "./internal-error.ts";
 
 const main = defineCommand({
@@ -60,4 +61,4 @@ process.on("unhandledRejection", (error) => {
   process.exit(1);
 });
 
-runMain(main);
+runMain(main, { rawArgs: normalizeHostArgs(process.argv.slice(2)) });

package/src/cli/init/questions.ts

@@ -111,6 +111,7 @@ export const collectAnswers = async (
     message: "Where does your content live?",
     options: [
       { hint: "Local .mdx files", label: "filesystem", value: "filesystem" },
+      { hint: "An Obsidian vault", label: "obsidian", value: "obsidian" },
       {
         hint: "Changelog from GitHub Releases",
         label: "github-releases",

package/src/cli/init/scaffold.ts

@@ -15,6 +15,7 @@ export type PackageManager = (typeof PACKAGE_MANAGERS)[number];
 /** The content-source kinds `init` can scaffold a config block for. */
 export const SOURCE_KINDS = [
   "filesystem",
+  "obsidian",
   "github-releases",
   "notion",
   "sanity",
@@ -209,8 +210,12 @@ export const titleize = (raw: string): string => {
         .join(" ");
 };
 
-/** True when any selected source is remote (everything except `filesystem`). */
-const hasRemoteSource = (sources: SourceKind[]): boolean =>
+/**
+ * True when any selected source needs an explicit `content.sources` array —
+ * everything except `filesystem`, which is what the implicit default already
+ * desugars to.
+ */
+const needsExplicitSources = (sources: SourceKind[]): boolean =>
   sources.some((source) => source !== "filesystem");
 
 /**
@@ -239,6 +244,14 @@ const SOURCE_SNIPPETS = {
         database: "your-database-id",
         prefix: "notion",
       },`,
+  obsidian: `      // An Obsidian vault, read in place. No export step, and no
+      // generated notes in your repo. Point \`vault\` at your vault directory,
+      // relative to this config file.
+      {
+        type: "obsidian",
+        vault: "vault",
+        prefix: "notes",
+      },`,
   sanity: `      // Documents from a Sanity dataset. Private datasets read SANITY_TOKEN
       // from the environment.
       {
@@ -258,7 +271,7 @@ const SOURCE_SNIPPETS = {
 const contentBlockFor = (answers: InitAnswers): string => {
   const sources =
     answers.sources.length === 0 ? ["filesystem" as const] : answers.sources;
-  if (!hasRemoteSource(sources)) {
+  if (!needsExplicitSources(sources)) {
     return answers.contentDir === "docs"
       ? ""
       : `
@@ -267,7 +280,7 @@ const contentBlockFor = (answers: InitAnswers): string => {
   },`;
   }
   // Explicit sources replace the implicit filesystem desugar, so the local
-  // content dir must be listed alongside the remote sources to stay included.
+  // content dir must be listed alongside the other sources to stay included.
   const entries = SOURCE_KINDS.filter((kind) => sources.includes(kind)).map(
     (kind) =>
       kind === "filesystem"
@@ -328,6 +341,16 @@ export const buildPlan = (
         .map((file) => ({ ...file, path: join(root, file.path) }))
     );
   }
+  // The obsidian snippet points at `vault/`; seed the directory with a first
+  // note so the scaffolded project passes the source's `validate()` and boots
+  // before the user has opened Obsidian at all.
+  if (answers.sources.includes("obsidian")) {
+    files.push({
+      content:
+        "# Welcome\n\nThis folder is read by Blume's `obsidian` source. Open it as a vault in Obsidian and write notes — `[[Wikilinks]]` become site links.\n",
+      path: join(root, "vault", "Welcome.md"),
+    });
+  }
   return files;
 };
 

package/src/components/colors.ts

@@ -0,0 +1,142 @@
+/**
+ * Color classes shared by every component that draws a label over a tint of
+ * its own hue — method badges, response status chips, `<Badge>`, the sidebar's
+ * method badges — and by the typed callout/card icons. One table so the pairs
+ * can't drift between components.
+ *
+ * Contrast rule (light mode): text over a 15% tint of its hue must clear 4.5:1,
+ * the WCAG AA bar for text this size. `-700` does for most hues; green and
+ * orange need `-800`, the way yellow already does over its 20% tint. Dark mode
+ * clears the bar at `-300` throughout. Check any hue added here.
+ */
+
+export type Hue =
+  | "blue"
+  | "green"
+  | "orange"
+  | "purple"
+  | "red"
+  | "teal"
+  | "violet"
+  | "yellow";
+
+/** Label over a translucent tint of the same hue. */
+export const TINT = {
+  blue: "bg-blue-500/15 text-blue-700 dark:text-blue-300",
+  green: "bg-green-500/15 text-green-800 dark:text-green-300",
+  orange: "bg-orange-500/15 text-orange-800 dark:text-orange-300",
+  purple: "bg-purple-500/15 text-purple-700 dark:text-purple-300",
+  red: "bg-red-500/15 text-red-700 dark:text-red-300",
+  teal: "bg-teal-500/15 text-teal-700 dark:text-teal-300",
+  violet: "bg-violet-500/15 text-violet-700 dark:text-violet-300",
+  yellow: "bg-yellow-500/20 text-yellow-800 dark:text-yellow-300",
+} satisfies Record<Hue, string>;
+
+/**
+ * Label with a translucent border of the same hue and no fill. The label
+ * inherits whatever surface it sits on (a callout, a card, the muted panel), so
+ * it is held to the same values as `TINT`: green at `-700` is 4.47:1 on the
+ * default muted surface.
+ */
+export const STROKE = {
+  blue: "border-blue-500/40 text-blue-700 dark:text-blue-300",
+  green: "border-green-500/40 text-green-800 dark:text-green-300",
+  orange: "border-orange-500/40 text-orange-800 dark:text-orange-300",
+  purple: "border-purple-500/40 text-purple-700 dark:text-purple-300",
+  red: "border-red-500/40 text-red-700 dark:text-red-300",
+  teal: "border-teal-500/40 text-teal-700 dark:text-teal-300",
+  violet: "border-violet-500/40 text-violet-700 dark:text-violet-300",
+  yellow: "border-yellow-500/40 text-yellow-800 dark:text-yellow-300",
+} satisfies Record<Hue, string>;
+
+/** The neutral fallback every table falls through to. */
+export const MUTED = "bg-muted text-muted-foreground";
+
+/**
+ * HTTP methods, AsyncAPI actions, and GraphQL root-field kinds, as shown on an
+ * operation's badge and in a reference's sidebar. Type-page kinds fall through
+ * to the muted default so operation badges stay the loud ones.
+ */
+export const METHOD_COLORS = {
+  DELETE: TINT.red,
+  GET: TINT.green,
+  HEAD: MUTED,
+  MUTATION: TINT.blue,
+  OPTIONS: MUTED,
+  PATCH: TINT.yellow,
+  POST: TINT.blue,
+  PUT: TINT.orange,
+  QUERY: TINT.green,
+  RECEIVE: TINT.teal,
+  SEND: TINT.violet,
+  SUBSCRIPTION: TINT.violet,
+} satisfies Record<string, string>;
+
+const isMethod = (key: string): key is keyof typeof METHOD_COLORS =>
+  Object.hasOwn(METHOD_COLORS, key);
+
+export const methodColor = (method: string): string => {
+  const key = method.toUpperCase();
+  return isMethod(key) ? METHOD_COLORS[key] : MUTED;
+};
+
+/** Response status chips, by the status code's class. */
+export const statusColor = (status: string): string => {
+  if (status.startsWith("2")) {
+    return TINT.green;
+  }
+  if (status.startsWith("3")) {
+    return TINT.blue;
+  }
+  if (status.startsWith("4")) {
+    return TINT.orange;
+  }
+  if (status.startsWith("5")) {
+    return TINT.red;
+  }
+  return MUTED;
+};
+
+/**
+ * The small `deprecated` label beside an operation's path or field name. It
+ * draws on the page background, where orange needs `-700` for 4.5:1.
+ */
+export const DEPRECATED_LABEL_CLASS =
+  "font-medium text-[0.625rem] text-orange-700 uppercase tracking-wide dark:text-orange-400";
+
+/** The typed admonitions `<Callout>` and `<Card>` render; `check` is an alias of `success`. */
+export type AdmonitionType =
+  | "info"
+  | "note"
+  | "tip"
+  | "success"
+  | "warning"
+  | "danger";
+
+export const admonitionType = (
+  type: AdmonitionType | "check"
+): AdmonitionType => (type === "check" ? "success" : type);
+
+export const ADMONITION_ICON = {
+  danger: "circle-x",
+  info: "info",
+  note: "info",
+  success: "circle-check",
+  tip: "lightbulb",
+  warning: "triangle-alert",
+} satisfies Record<AdmonitionType, string>;
+
+/**
+ * An admonition's icon names its type, so it is meaningful UI held to the 3:1
+ * non-text bar against the tint behind it: green and amber need `-700` over
+ * their 10% tint, and the note icon is full-strength muted-foreground (at 70%
+ * it fell under the bar on the muted surface).
+ */
+export const ADMONITION_ICON_CLASS = {
+  danger: "text-red-600 dark:text-red-400",
+  info: "text-blue-600 dark:text-blue-400",
+  note: "text-muted-foreground",
+  success: "text-green-700 dark:text-green-400",
+  tip: "text-accent",
+  warning: "text-amber-700 dark:text-amber-400",
+} satisfies Record<AdmonitionType, string>;

package/src/components/content/Badge.astro

@@ -1,4 +1,5 @@
 ---
+import { STROKE, TINT } from "../colors.ts";
 import Icon from "../Icon.astro";
 
 type BadgeVariant = "default" | "accent" | "success" | "warning" | "danger";
@@ -44,34 +45,26 @@ const colorName =
   }[variant];
 const customColor = colorName.startsWith("#") ? colorName : null;
 
+// The hue rows come from the shared table (see colors.ts for the contrast
+// rule); the neutral and surface rows are Badge's own.
 const filledColorClass: Record<string, string> = {
-  blue: "bg-blue-500/15 text-blue-700 dark:text-blue-300",
+  ...TINT,
   gray: "bg-muted text-muted-foreground",
-  green: "bg-green-500/15 text-green-700 dark:text-green-300",
-  orange: "bg-orange-500/15 text-orange-700 dark:text-orange-300",
-  purple: "bg-purple-500/15 text-purple-700 dark:text-purple-300",
-  red: "bg-red-500/15 text-red-700 dark:text-red-300",
   surface: "bg-background text-muted-foreground ring-1 ring-border",
   "surface-destructive":
     "bg-background text-red-700 ring-1 ring-red-500/30 dark:text-red-300",
   white: "bg-white text-muted-foreground ring-1 ring-border dark:bg-white/10",
   "white-destructive":
     "bg-white text-red-700 ring-1 ring-red-500/30 dark:bg-white/10 dark:text-red-300",
-  yellow: "bg-yellow-500/20 text-yellow-800 dark:text-yellow-300",
 };
 
 const strokeColorClass: Record<string, string> = {
-  blue: "border-blue-500/40 text-blue-700 dark:text-blue-300",
+  ...STROKE,
   gray: "border-border text-muted-foreground",
-  green: "border-green-500/40 text-green-700 dark:text-green-300",
-  orange: "border-orange-500/40 text-orange-700 dark:text-orange-300",
-  purple: "border-purple-500/40 text-purple-700 dark:text-purple-300",
-  red: "border-red-500/40 text-red-700 dark:text-red-300",
   surface: "border-border text-muted-foreground",
   "surface-destructive": "border-red-500/40 text-red-700 dark:text-red-300",
   white: "border-border text-muted-foreground",
   "white-destructive": "border-red-500/40 text-red-700 dark:text-red-300",
-  yellow: "border-yellow-500/40 text-yellow-800 dark:text-yellow-300",
 };
 
 const sizeClass: Record<BadgeSize, string> = {

package/src/components/content/Callout.astro

@@ -1,64 +1,47 @@
 ---
+import {
+  ADMONITION_ICON,
+  ADMONITION_ICON_CLASS,
+  type AdmonitionType,
+  admonitionType,
+} from "../colors.ts";
 import Icon from "../Icon.astro";
 
-type CalloutType =
-  | "info"
-  | "note"
-  | "tip"
-  | "success"
-  | "check"
-  | "warning"
-  | "danger";
-
 interface Props {
-  type?: CalloutType;
+  type?: AdmonitionType | "check";
   title?: string;
   icon?: unknown;
   color?: string;
 }
 
 const { color, icon, type = "info", title } = Astro.props;
+// `check` is an alias of `success`; fold it once so the tables need one row.
+const kind = admonitionType(type);
 
-const iconByType: Record<CalloutType, string> = {
-  check: "circle-check",
-  danger: "circle-x",
-  info: "info",
-  note: "info",
-  success: "circle-check",
-  tip: "lightbulb",
-  warning: "triangle-alert",
-};
-
-const variantClass: Record<CalloutType, string> = {
-  check: "border-green-500/25 bg-green-500/10",
+const variantClass: Record<AdmonitionType, string> = {
   danger: "border-red-500/25 bg-red-500/10",
   info: "border-blue-500/25 bg-blue-500/10",
   note: "border-border bg-muted",
   success: "border-green-500/25 bg-green-500/10",
-  tip: "border-accent/25 bg-accent/10",
+  // 6% rather than the 10% the other variants use: this tint comes from the
+  // user-configurable accent, whose default is near black, and muted body
+  // text on a 10% black tint sits at 4.25:1. 6% clears WCAG AA (4.5:1)
+  // against any accent — 4.62:1 worst case on pure black.
+  tip: "border-accent/25 bg-accent/6",
   warning: "border-amber-500/25 bg-amber-500/10",
 };
-
-const iconClass: Record<CalloutType, string> = {
-  check: "text-green-600 dark:text-green-400",
-  danger: "text-red-600 dark:text-red-400",
-  info: "text-blue-600 dark:text-blue-400",
-  note: "text-muted-foreground/70",
-  success: "text-green-600 dark:text-green-400",
-  tip: "text-accent",
-  warning: "text-amber-600 dark:text-amber-400",
-};
 ---
 
 <aside
   class:list={[
     "not-prose my-5 flex flex-row items-start gap-2 rounded-blume border px-4 py-3 font-sans text-muted-foreground text-sm leading-6 [&_a]:underline [&_a]:decoration-current/50 [&_code]:font-mono",
-    color ? "bg-background" : variantClass[type],
+    color ? "bg-background" : variantClass[kind],
   ]}
+  data-blume-callout={kind}
   style={color ? `border:1px solid ${color};color:${color}` : undefined}
 >
-  <span class:list={["mt-0.5 shrink-0", color ? "" : iconClass[type]]}>
-    <Icon color={color} icon={icon ?? iconByType[type]} size={16} />
+  <span class:list={["mt-0.5 shrink-0", color ? "" : ADMONITION_ICON_CLASS[kind]]}>
+    <Icon color={color} icon={icon ?? ADMONITION_ICON[kind]} size={16} />
   </span>
   {/* The global prose rule leaks a 1rem margin onto these paragraphs/lists even
       though the callout is not-prose; with a title the body isn't the first

package/src/components/content/Card.astro

@@ -1,4 +1,9 @@
 ---
+import {
+  ADMONITION_ICON,
+  ADMONITION_ICON_CLASS,
+  admonitionType,
+} from "../colors.ts";
 import Icon from "../Icon.astro";
 import { withBase } from "../islands/base-path.ts";
 import { contentHref } from "./base-href.ts";
@@ -22,31 +27,20 @@ const external = href?.startsWith("http");
 const isHorizontal = horizontal === true || horizontal === "true";
 const showArrow =
   href && arrow === undefined ? external : arrow === true || arrow === "true";
-const iconByType = {
-  check: "circle-check",
-  danger: "circle-x",
-  info: "info",
-  note: "info",
-  tip: "lightbulb",
-  warning: "triangle-alert",
-};
-const iconClass = {
-  check: "text-green-600 dark:text-green-400",
-  danger: "text-red-600 dark:text-red-400",
-  info: "text-blue-600 dark:text-blue-400",
-  note: "text-muted-foreground/70",
-  tip: "text-accent",
-  warning: "text-amber-600 dark:text-amber-400",
-};
-const iconName = icon ?? (type ? iconByType[type] : undefined);
+// The typed icon shares Callout's table (and its contrast rule); the surface
+// tints are Card's own, a shade lighter than a callout's.
+const kind = type ? admonitionType(type) : undefined;
+const iconName = icon ?? (kind ? ADMONITION_ICON[kind] : undefined);
 const variantClass = {
-  check: "border-green-500/30 bg-green-500/10",
   danger: "border-red-500/30 bg-red-500/10",
   info: "border-blue-500/30 bg-blue-500/10",
   note: "border-border bg-muted/40",
-  tip: "border-accent/30 bg-accent/10",
+  success: "border-green-500/30 bg-green-500/10",
+  // 6% for the same reason as Callout: the accent defaults to near black, and
+  // muted body text on a 10% black tint misses WCAG AA.
+  tip: "border-accent/30 bg-accent/6",
   warning: "border-amber-500/30 bg-amber-500/10",
-}[type ?? "note"];
+}[kind ?? "note"];
 ---
 
 <Tag
@@ -75,7 +69,7 @@ const variantClass = {
   <div class="p-5">
   {
     iconName && (
-      <div class:list={["mb-2.5", color ? "" : type ? iconClass[type] : "text-accent"]}>
+      <div class:list={["mb-2.5", color ? "" : kind ? ADMONITION_ICON_CLASS[kind] : "text-accent"]}>
         <Icon color={color} name={iconName} size={20} />
       </div>
     )