@mintlify/cli 4.0.737 → 4.0.738

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mintlify/cli",
-  "version": "4.0.737",
+  "version": "4.0.738",
   "description": "The Mintlify CLI",
   "engines": {
     "node": ">=18.0.0"
@@ -39,13 +39,14 @@
     "format:check": "prettier . --check"
   },
   "dependencies": {
-    "@mintlify/common": "1.0.547",
-    "@mintlify/link-rot": "3.0.684",
+    "@mintlify/common": "1.0.548",
+    "@mintlify/link-rot": "3.0.685",
     "@mintlify/models": "0.0.230",
-    "@mintlify/prebuild": "1.0.671",
-    "@mintlify/previewing": "4.0.720",
+    "@mintlify/prebuild": "1.0.672",
+    "@mintlify/previewing": "4.0.721",
     "@mintlify/validation": "0.1.478",
     "chalk": "^5.2.0",
+    "color": "^4.2.3",
     "detect-port": "^1.5.1",
     "fs-extra": "^11.2.0",
     "gray-matter": "^4.0.3",
@@ -74,5 +75,5 @@
     "vitest": "^2.0.4",
     "vitest-mock-process": "^1.0.4"
   },
-  "gitHead": "e52bbb1b754a21125285e7be5a3b9c102e1c4208"
+  "gitHead": "69ad789dbb3ea65dd6c3998327e67d0131c5d196"
 }

package/src/accessibility.ts

@@ -0,0 +1,160 @@
+import Color from 'color';
+
+export const WCAG_STANDARDS = {
+  AA_NORMAL: 4.5,
+  AA_LARGE: 3,
+  AAA_NORMAL: 7,
+  AAA_LARGE: 4.5,
+} as const;
+
+export type ContrastResult = {
+  ratio: number;
+  meetsAA: boolean;
+  meetsAAA: boolean;
+  recommendation: 'pass' | 'warning' | 'fail';
+  message: string;
+};
+
+export function checkColorContrast(foreground: string, background: string): ContrastResult | null {
+  try {
+    const fg = Color(foreground);
+    const bg = Color(background);
+
+    const ratio = fg.contrast(bg);
+    const level = fg.level(bg);
+
+    const meetsAA = level === 'AA' || level === 'AAA';
+    const meetsAAA = level === 'AAA';
+
+    let recommendation: 'pass' | 'warning' | 'fail';
+    let message: string;
+
+    if (meetsAAA) {
+      recommendation = 'pass';
+      message = `Excellent contrast ratio: ${ratio.toFixed(2)}:1 (meets WCAG AAA)`;
+    } else if (meetsAA) {
+      recommendation = 'warning';
+      message = `Good contrast ratio: ${ratio.toFixed(
+        2
+      )}:1 (meets WCAG AA, consider AAA for better accessibility)`;
+    } else {
+      recommendation = 'fail';
+      message = `Poor contrast ratio: ${ratio.toFixed(2)}:1 (fails WCAG AA, minimum required: ${
+        WCAG_STANDARDS.AA_NORMAL
+      }:1)`;
+    }
+
+    return {
+      ratio,
+      meetsAA,
+      meetsAAA,
+      recommendation,
+      message,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export interface AccessibilityCheckResult {
+  primaryContrast: ContrastResult | null;
+  lightContrast: ContrastResult | null;
+  darkContrast: ContrastResult | null;
+  darkOnLightContrast: ContrastResult | null;
+  anchorResults: Array<{
+    name: string;
+    lightContrast: ContrastResult | null;
+    darkContrast: ContrastResult | null;
+  }>;
+  overallScore: 'pass' | 'warning' | 'fail';
+}
+
+export function checkDocsColors(
+  colors: {
+    primary?: string;
+    light?: string;
+    dark?: string;
+  },
+  background: {
+    lightHex: string;
+    darkHex: string;
+  },
+  navigation?: {
+    global?: {
+      anchors?: Array<{
+        anchor: string;
+        color?: {
+          light?: string;
+          dark?: string;
+        };
+      }>;
+    };
+  }
+): AccessibilityCheckResult {
+  const lightBackground = background.lightHex;
+  const darkBackground = background.darkHex;
+
+  const primaryContrast = colors.primary
+    ? checkColorContrast(colors.primary, lightBackground)
+    : null;
+
+  const lightContrast = colors.light ? checkColorContrast(colors.light, darkBackground) : null;
+
+  const darkContrast = colors.dark ? checkColorContrast(colors.dark, darkBackground) : null;
+
+  const darkOnLightContrast = colors.dark ? checkColorContrast(colors.dark, lightBackground) : null;
+
+  const anchorResults: Array<{
+    name: string;
+    lightContrast: ContrastResult | null;
+    darkContrast: ContrastResult | null;
+  }> = [];
+
+  if (navigation?.global?.anchors) {
+    for (const anchor of navigation.global.anchors) {
+      if (anchor.color) {
+        const lightContrast = anchor.color.light
+          ? checkColorContrast(anchor.color.light, lightBackground)
+          : null;
+        const darkContrast = anchor.color.dark
+          ? checkColorContrast(anchor.color.dark, darkBackground)
+          : null;
+
+        anchorResults.push({
+          name: anchor.anchor,
+          lightContrast,
+          darkContrast,
+        });
+      }
+    }
+  }
+
+  const results = [
+    primaryContrast,
+    lightContrast,
+    darkContrast,
+    darkOnLightContrast,
+    ...anchorResults.flatMap((anchor) => [anchor.lightContrast, anchor.darkContrast]),
+  ].filter(Boolean);
+
+  const hasFailure = results.some((result) => result!.recommendation === 'fail');
+  const hasWarning = results.some((result) => result!.recommendation === 'warning');
+
+  let overallScore: 'pass' | 'warning' | 'fail';
+  if (hasFailure) {
+    overallScore = 'fail';
+  } else if (hasWarning) {
+    overallScore = 'warning';
+  } else {
+    overallScore = 'pass';
+  }
+
+  return {
+    primaryContrast,
+    lightContrast,
+    darkContrast,
+    darkOnLightContrast,
+    anchorResults,
+    overallScore,
+  };
+}

package/src/accessibilityCheck.tsx

@@ -0,0 +1,150 @@
+import { getBackgroundColors } from '@mintlify/common';
+import { getConfigObj, getConfigPath } from '@mintlify/prebuild';
+import { addLog, ErrorLog, WarningLog } from '@mintlify/previewing';
+import { Text } from 'ink';
+
+import { checkDocsColors, type AccessibilityCheckResult } from './accessibility.js';
+import { ContrastResult } from './accessibility.js';
+import { CMD_EXEC_PATH } from './constants.js';
+import { checkForDocsJson } from './helpers.js';
+
+type TerminateCode = 0 | 1;
+
+export const accessibilityCheck = async (): Promise<TerminateCode> => {
+  try {
+    await checkForDocsJson();
+
+    const docsConfigPath = await getConfigPath(CMD_EXEC_PATH, 'docs');
+    const mintConfigPath = await getConfigPath(CMD_EXEC_PATH, 'mint');
+
+    if (!docsConfigPath && !mintConfigPath) {
+      addLog(
+        <ErrorLog message="No configuration file found. Please run this command from a directory with a mint.json or docs.json file." />
+      );
+      return 1;
+    }
+
+    const configType = docsConfigPath ? 'docs' : 'mint';
+    const config = await getConfigObj(CMD_EXEC_PATH, configType);
+
+    if (!config.colors) {
+      addLog(<WarningLog message="No colors section found in configuration file" />);
+      return 0;
+    }
+
+    const { colors, navigation } = config;
+
+    const { lightHex, darkHex } = getBackgroundColors(config);
+
+    const results: AccessibilityCheckResult = checkDocsColors(
+      colors,
+      { lightHex, darkHex },
+      navigation
+    );
+
+    const displayContrastResult = (
+      result: ContrastResult | null,
+      label: string,
+      prefix: string = ''
+    ) => {
+      if (!result) return;
+
+      const { recommendation, message } = result;
+      const icon =
+        recommendation === 'pass' ? 'PASS' : recommendation === 'warning' ? 'WARN' : 'FAIL';
+      const color =
+        recommendation === 'pass' ? 'green' : recommendation === 'warning' ? 'yellow' : 'red';
+
+      addLog(
+        <Text>
+          <Text bold={prefix === ''}>
+            {prefix}
+            {label}:{' '}
+          </Text>
+          <Text color={color}>
+            {icon} {message}
+          </Text>
+        </Text>
+      );
+    };
+
+    addLog(
+      <Text bold color="cyan">
+        Checking color accessibility...
+      </Text>
+    );
+    addLog(<Text></Text>);
+
+    displayContrastResult(
+      results.primaryContrast,
+      `Primary Color (${colors.primary}) vs Light Background`
+    );
+    displayContrastResult(
+      results.lightContrast,
+      `Light Color (${colors.light}) vs Dark Background`
+    );
+    displayContrastResult(results.darkContrast, `Dark Color (${colors.dark}) vs Dark Background`);
+    displayContrastResult(
+      results.darkOnLightContrast,
+      `Dark Color (${colors.dark}) vs Light Background`
+    );
+
+    const anchorsWithResults = results.anchorResults.filter(
+      (anchor) => anchor.lightContrast || anchor.darkContrast
+    );
+
+    if (anchorsWithResults.length > 0) {
+      addLog(<Text></Text>);
+      addLog(
+        <Text bold color="cyan">
+          Navigation Anchors:
+        </Text>
+      );
+
+      for (const anchor of anchorsWithResults) {
+        addLog(<Text bold> {anchor.name}:</Text>);
+        displayContrastResult(anchor.lightContrast, 'Light variant vs Light Background', '    ');
+        displayContrastResult(anchor.darkContrast, 'Dark variant vs Dark Background', '    ');
+      }
+    }
+
+    addLog(<Text></Text>);
+    const overallIcon =
+      results.overallScore === 'pass'
+        ? 'PASS'
+        : results.overallScore === 'warning'
+          ? 'WARN'
+          : 'FAIL';
+    const overallColor =
+      results.overallScore === 'pass'
+        ? 'green'
+        : results.overallScore === 'warning'
+          ? 'yellow'
+          : 'red';
+    const overallMessage =
+      results.overallScore === 'pass'
+        ? 'All colors meet accessibility standards!'
+        : results.overallScore === 'warning'
+          ? 'Some colors could be improved for better accessibility'
+          : 'Some colors fail accessibility standards and should be updated';
+
+    addLog(
+      <Text>
+        <Text bold color={overallColor}>
+          Overall Assessment: {overallIcon} {overallMessage}
+        </Text>
+      </Text>
+    );
+
+    return results.overallScore === 'fail' ? 1 : 0;
+  } catch (error) {
+    addLog(
+      <ErrorLog
+        message={`Accessibility check failed: ${
+          error instanceof Error ? error.message : 'Unknown error'
+        }`}
+      />
+    );
+    return 1;
+  }
+};

package/src/cli.tsx

@@ -16,6 +16,7 @@ import path from 'path';
 import yargs from 'yargs';
 import { hideBin } from 'yargs/helpers';
 
+import { accessibilityCheck } from './accessibilityCheck.js';
 import {
   checkPort,
   checkForMintJson,
@@ -238,6 +239,15 @@ export const cli = ({ packageName = 'mint' }: { packageName?: string }) => {
           await terminate(0);
         }
       )
+      .command(
+        'accessibility-check',
+        false,
+        () => undefined,
+        async () => {
+          const terminateCode = await accessibilityCheck();
+          await terminate(terminateCode);
+        }
+      )
       .command(
         ['version', 'v'],
         'display the current version of the CLI and client',