### Install contrastrast

Source: https://github.com/ammuench/contrastrast/blob/main/README.md

Instructions for installing the contrastrast library using npm, yarn, pnpm, and Deno.

```bash
npm install --save contrastrast
```

```bash
yarn add contrastrast
```

```bash
pnpm install --save contrastrast
```

```bash
deno add jsr:@amuench/contrastrast
```

--------------------------------

### Deno Project Configuration

Source: https://github.com/ammuench/contrastrast/blob/main/CLAUDE.md

Example of a deno.json file used for project configuration, including tasks, linting rules, and import maps.

```JSON
{
  "tasks": {
    "build:npm": "deno run -A scripts/build_npm.ts"
  },
  "lint": {
    "rules": {
      "tags": [
        "recommended"
      ],
      "include": [
        "invalid-use-of-deno-namespace"
      ],
      "exclude": [
        "no-explicit-any"
      ]
    }
  },
  "fmt": {
    "options": {
      "lineWidth": 80,
      "indentWidth": 2
    }
  }
}
```

--------------------------------

### Quick Start: Color Manipulation and Analysis

Source: https://github.com/ammuench/contrastrast/blob/main/README.md

Demonstrates basic usage of the Contrastrast class for parsing colors, checking lightness/darkness, calculating contrast ratios, verifying WCAG compliance, and converting color formats.

```typescript
import { Contrastrast } from "contrastrast";

// Parse any color format, by default will throw an error if the color string is invalid
const color = new Contrastrast("#1a73e8");

// Check if the color is light or dark
console.log(color.isLight()); // false
console.log(color.isDark()); // true

// Get contrast ratio with another color
const ratio = color.contrastRatio("#ffffff"); // 4.5

// Check WCAG compliance
const meetsAA = color.meetsWCAG("#ffffff", "background", "AA"); // true

// Convert between formats
console.log(color.toHex()); // "#1a73e8"
console.log(color.toRgbString()); // "rgb(26, 115, 232)"
console.log(color.toHslString()); // "hsl(218, 80%, 51%)"
```

--------------------------------

### React Component Example with Dynamic Text Color

Source: https://github.com/ammuench/contrastrast/blob/main/README.md

Example of a React component that dynamically sets text color based on the background color's lightness using Contrastrast.

```tsx
import { Contrastrast } from "contrastrast";

interface ColorCardProps {
  backgroundColor: string;
  children: React.ReactNode;
}

const ColorCard: React.FC<ColorCardProps> = ({ backgroundColor, children }) => {
  const bgColor = new Contrastrast(backgroundColor);
  const textColor = bgColor.isLight() ? "#000000" : "#ffffff";

  return (
    <div style={{ backgroundColor, color: textColor }}>
      {children}
    </div>
  );
};
```

--------------------------------

### Convert Color to HSL

Source: https://github.com/ammuench/contrastrast/blob/main/README.md

Get HSL values as an object or string representation. Supports conversion from various color formats.

```typescript
const hsl = color.toHsl(); // { h: 0, s: 100, l: 50 }
```

```typescript
const hslString = color.toHslString(); // "hsl(0, 100%, 50%)"
```

--------------------------------

### Convert Color to RGB

Source: https://github.com/ammuench/contrastrast/blob/main/README.md

Get RGB values as an object or string representation. Supports conversion from various color formats.

```typescript
const rgb = color.toRgb(); // { r: 255, g: 0, b: 0 }
```

```typescript
const rgbString = color.toRgbString(); // "rgb(255, 0, 0)"
```

--------------------------------

### contrastrast API: Constructor and Factory Methods

Source: https://github.com/ammuench/contrastrast/blob/main/README.md

Details the primary ways to create Contrastrast instances: using the constructor with a color string, static factory methods for specific formats (hex, RGB, HSL), and handling parsing errors.

```typescript
new Contrastrast(colorString: string, parseOpts?: Partial<ParseOptions>)
Create a new Contrastrast instance from any supported color string.

const color1 = new Contrastrast("#ff0000");
const color2 = new Contrastrast("rgb(255, 0, 0)");
const color3 = new Contrastrast("hsl(0, 100%, 50%)");

// With error handling
const safeColor = new Contrastrast("invalid-color", {
  throwOnError: false,
  fallbackColor: "#000000",
});

Contrastrast.parse(colorString: string, parseOpts?: Partial<ParseOptions>): Contrastrast
Static method alias for the constructor. Also accepts the same `parseOpts` configuration object.

const color = Contrastrast.parse("#1a73e8");

// With error handling
const safeColor = Contrastrast.parse("invalid-color", {
  throwOnError: false,
  fallbackColor: "#ffffff",
});

Contrastrast.fromHex(hex: string): Contrastrast
Create from hex color (with or without #). Supports 3 and 6 digit codes.

const red1 = Contrastrast.fromHex("#ff0000");
const red2 = Contrastrast.fromHex("ff0000");
const shortRed = Contrastrast.fromHex("#f00");

Contrastrast.fromRgb(r: number, g: number, b: number): Contrastrast / Contrastrast.fromRgb(rgb: RGBValues): Contrastrast
Create from RGB values.

const red1 = Contrastrast.fromRgb(255, 0, 0);
const red2 = Contrastrast.fromRgb({ r: 255, g: 0, b: 0 });

Contrastrast.fromHsl(h: number, s: number, l: number): Contrastrast / Contrastrast.fromHsl(hsl: HSLValues): Contrastrast
Create from HSL values.

const red1 = Contrastrast.fromHsl(0, 100, 50);
const red2 = Contrastrast.fromHsl({ h: 0, s: 100, l: 50 });
```

--------------------------------

### Build and Distribution Commands (Deno)

Source: https://github.com/ammuench/contrastrast/blob/main/CLAUDE.md

Commands for building the NPM distribution package for the contrastrast library using Deno scripts. This includes creating the package and aliasing the task.

```Shell
deno run -A scripts/build_npm.ts
deno task build:npm
```

--------------------------------

### Contrastrast Class API (TypeScript)

Source: https://github.com/ammuench/contrastrast/blob/main/CLAUDE.md

Demonstrates the core Contrastrast class functionality, including factory methods for color instantiation, WCAG calculations, format conversions, and accessibility checks.

```TypeScript
// Factory methods:
Contrastrast.fromHex('#ffffff');
Contrastrast.fromRgb({ r: 255, g: 255, b: 255 });
Contrastrast.fromHsl({ h: 0, s: 0, l: 1 });
Contrastrast.parse('#fff');

// WCAG calculations:
color.contrastRatio();
color.meetsWCAG('AA', 'large');

// Format conversion:
color.toHex();
color.toRgb();
color.toHsl();
color.toRgbString();

// Accessibility checks:
color.isLight();
color.isDark();
```

--------------------------------

### Core Development Commands (Deno)

Source: https://github.com/ammuench/contrastrast/blob/main/CLAUDE.md

Provides essential commands for developing the contrastrast library using Deno, including running in watch mode, executing tests, linting, and formatting code.

```Shell
deno run --watch mod.ts
deno test
deno test <pattern>
deno lint
deno fmt
```

--------------------------------

### NPM Build Script (TypeScript)

Source: https://github.com/ammuench/contrastrast/blob/main/CLAUDE.md

The script used to build the NPM distribution package, handling package.json generation and asset copying for Node.js compatibility.

```TypeScript
// scripts/build_npm.ts
import { build, emptyDir } from "@deno/dnt";

await emptyDir("./npm");

await build({
  entryPoints: ["./mod.ts"],
  outDir: "./npm",
  test: false,
  typeCheck: false,
  packageManager: "npm",
  mappings: {
    "@std/testing/": "npm:@deno/std/testing/",
    "@std/expect/": "npm:@deno/std/expect/",
  },
  package: {
    name: "contrastrast",
    version: Deno.readTextFileSync("version.txt").trim(),
    description: "WCAG 2.1 compliant color contrast and accessibility library.",
    keywords: ["color", "contrast", "accessibility", "WCAG", "typescript", "deno"],
    license: "MIT",
    repository: {
      type: "git",
      url: "git+https://github.com/ammuench/contrastrast.git",
    },
    bugs: {
      url: "https://github.com/ammuench/contrastrast/issues",
    },
    author: "Ammuench <ammuench@gmail.com>",
    files: ["esm/", "script/", "LICENSE"],
    exports: {
      ".": {
        "import": "./esm/mod.js",
        "require": "./script/mod.js",
      },
    },
  },
});

// copy the README and LICENSE file to the npm package
await Deno.copyFile("README.md", "npm/README.md");
await Deno.copyFile("LICENSE", "npm/LICENSE");

console.log("NPM package built successfully!");

```

--------------------------------

### contrastrast API: Configuration and Result Types

Source: https://github.com/ammuench/contrastrast/blob/main/README.md

Defines TypeScript types for parsing options, contrast calculation options, and the detailed results of contrast ratio analysis, including WCAG compliance levels.

```typescript
type ParseOptions = {
  throwOnError: boolean; // Whether to throw on invalid colors
  fallbackColor?: string; // Fallback color when throwOnError is false
};

type ContrastOptions = {
  returnDetails?: boolean; // Return detailed WCAG analysis instead of just ratio
};

type ContrastResult = {
  ratio: number;
  passes: {
    AA_NORMAL: boolean; // WCAG AA normal text (4.5:1)
    AA_LARGE: boolean; // WCAG AA large text (3:1)
    AAA_NORMAL: boolean; // WCAG AAA normal text (7:1)
    AAA_LARGE: boolean; // WCAG AAA large text (4.5:1)
  };
};

type WCAGContrastLevel = "AA" | "AAA";
type WCAGTextSize = "normal" | "large";
```

--------------------------------

### WCAG Utilities (TypeScript)

Source: https://github.com/ammuench/contrastrast/blob/main/CLAUDE.md

Illustrates the usage of utility functions for WCAG analysis and contrast ratio calculations, providing detailed compliance reports and basic ratio computations.

```TypeScript
// Detailed WCAG analysis:
textContrast(color1, color2);

// Basic contrast ratio calculation:
contrastRatio(color1, color2);
```

--------------------------------

### Color Parsing Pipeline (TypeScript)

Source: https://github.com/ammuench/contrastrast/blob/main/CLAUDE.md

Shows the unified color parsing logic that supports various formats like HEX, RGB, and HSL, including error handling and fallback mechanisms.

```TypeScript
// Parsing various color formats:
parseColorString('#abcdef', { fallbackColor: '#000' });
parseColorString('rgb(255, 0, 0)');
parseColorString('hsl(120, 100%, 50%)');
```

--------------------------------

### ParseOptions Configuration for Color Parsing

Source: https://github.com/ammuench/contrastrast/blob/main/README.md

Configure color parsing behavior with `ParseOptions`. Options include `throwOnError` to control error throwing and `fallbackColor` for invalid inputs.

```typescript
interface ParseOptions {
  throwOnError: boolean; // Whether to throw on invalid colors (default: true)
  fallbackColor?: string; // Fallback color when throwOnError is false (default: "#000000")
}

// Safe parsing with fallback
const safeColor = Contrastrast.parse("invalid-color", {
  throwOnError: false,
  fallbackColor: "#333333",
});

// Will throw on invalid color (default behavior)
const strictColor = new Contrastrast("invalid-color"); // throws Error
```

--------------------------------

### Calculate Text Contrast Ratio and WCAG Analysis

Source: https://github.com/ammuench/contrastrast/blob/main/README.md

Calculates the contrast ratio between foreground and background colors. Optionally provides detailed WCAG analysis, including pass/fail status for AA and AAA standards at normal and large text sizes.

```typescript
import { textContrast } from "contrastrast";

// Simple ratio calculation
const ratio = textContrast("#000000", "#ffffff"); // 21

// Detailed WCAG analysis
const analysis = textContrast("#1a73e8", "#ffffff", { returnDetails: true });
// {
//   ratio: 4.5,
//   passes: {
//     AA_NORMAL: true,
//     AA_LARGE: true,
//     AAA_NORMAL: false,
//     AAA_LARGE: true
//   }
// }
```

--------------------------------

### Quality Assurance Commands (Deno)

Source: https://github.com/ammuench/contrastrast/blob/main/CLAUDE.md

Commands for ensuring code quality within the contrastrast project, including auto-fixing linting issues. Pre-commit hooks leverage these commands.

```Shell
deno lint --fix
```

--------------------------------

### contrastrast API: Color Format Conversion

Source: https://github.com/ammuench/contrastrast/blob/main/README.md

Provides methods to convert a Contrastrast color instance into different string formats, specifically hex, with an option to include or exclude the leading hash symbol.

```typescript
toHex(includeHash?: boolean): string
Convert to hex format.

const color = new Contrastrast("rgb(255, 0, 0)");
console.log(color.toHex()); // "#ff0000"
console.log(color.toHex(false)); // "ff0000"
```

--------------------------------

### Accessibility & Contrast Ratio Calculation

Source: https://github.com/ammuench/contrastrast/blob/main/README.md

Calculate the WCAG 2.1 contrast ratio between two colors. The `contrastRatio` method returns a number, while `textContrast` provides detailed WCAG compliance analysis.

```typescript
const bgColor = new Contrastrast("#1a73e8");
const ratio = bgColor.contrastRatio("#ffffff"); // 4.5
```

```typescript
// Simple ratio
const ratio = bgColor.textContrast("#ffffff"); // 4.5

// Detailed analysis
const result = bgColor.textContrast("#ffffff", "background", {
  returnDetails: true,
});
// {
//   ratio: 4.5,
//   passes: {
//     AA_NORMAL: true,
//     AA_LARGE: true,
//     AAA_NORMAL: false,
//     AAA_LARGE: true
//   }
// }
```

--------------------------------

### RGB Conversion System (TypeScript)

Source: https://github.com/ammuench/contrastrast/blob/main/CLAUDE.md

Details the functions responsible for converting colors between different formats, specifically focusing on HEX, HSL, and RGB string representations.

```TypeScript
// HEX to RGB:
extractRGBValuesFromHex('#ff0000');

// HSL to RGB:
extractRGBValuesFromHSL({ h: 0, s: 100, l: 50 });

// RGB String parsing:
extractRGBValuesFromRGBStrings('rgb(0, 0, 255)');
```

--------------------------------

### contrastrast API: Color Value Types

Source: https://github.com/ammuench/contrastrast/blob/main/README.md

Defines the TypeScript types for representing RGB and HSL color values, specifying the expected ranges for each component.

```typescript
type RGBValues = {
  r: number; // Red (0-255)
  g: number; // Green (0-255)
  b: number; // Blue (0-255)
};

type HSLValues = {
  h: number; // Hue (0-360)
  s: number; // Saturation (0-100)
  l: number; // Lightness (0-100)
};
```

--------------------------------

### Color Analysis: Luminance and Brightness

Source: https://github.com/ammuench/contrastrast/blob/main/README.md

Calculate WCAG 2.1 relative luminance (0-1) and perceived brightness using the AERT formula (0-255). Useful for accessibility checks.

```typescript
const black = new Contrastrast("#000000");
const white = new Contrastrast("#ffffff");
console.log(black.luminance()); // 0
console.log(white.luminance()); // 1
```

```typescript
const color = new Contrastrast("#1a73e8");
const brightness = color.brightness(); // ~102.4
```

--------------------------------

### Legacy API Function (TypeScript)

Source: https://github.com/ammuench/contrastrast/blob/main/CLAUDE.md

Provides the deprecated `textContrastForBGColor` function from the v0.3.x legacy API for backward compatibility.

```TypeScript
textContrastForBGColor(foregroundColor, backgroundColor);
```

--------------------------------

### Utility Method: Color Equality Check

Source: https://github.com/ammuench/contrastrast/blob/main/README.md

Compare two colors for equality. The `equals` method accepts either a Contrastrast object or a color string.

```typescript
const color1 = new Contrastrast("#ff0000");
const color2 = new Contrastrast("rgb(255, 0, 0)");
console.log(color1.equals(color2)); // true
```

--------------------------------

### Calculate Contrast Ratio Between Two Colors

Source: https://github.com/ammuench/contrastrast/blob/main/README.md

Calculates the WCAG 2.1 contrast ratio between any two colors. Supports various color formats including HEX, RGB, and HSL, and can accept either color strings or Contrastrast instances.

```typescript
import { contrastRatio } from "contrastrast";

const ratio1 = contrastRatio("#1a73e8", "#ffffff"); // 4.5
const ratio2 = contrastRatio("rgb(255, 0, 0)", "hsl(0, 0%, 100%)"); // 3.998

// Works with mixed formats
const ratio3 = contrastRatio("#000", "rgb(255, 255, 255)"); // 21
```

--------------------------------

### Validate Color Combination with Contrastrast

Source: https://github.com/ammuench/contrastrast/blob/main/README.md

Validates a color combination against WCAG AA standards using the Contrastrast class. It calculates the contrast ratio and determines if the combination meets AAA, AA, or fails.

```typescript
import { Contrastrast } from "contrastrast";

function validateColorCombination(background: string, foreground: string): {
  isValid: boolean;
  level: string;
  ratio: number;
} {
  const bgColor = new Contrastrast(background);
  const ratio = bgColor.contrastRatio(foreground);

  const meetsAAA = bgColor.meetsWCAG(foreground, "background", "AAA");
  const meetsAA = bgColor.meetsWCAG(foreground, "background", "AA");

  return {
    isValid: meetsAA,
    level: meetsAAA ? "AAA" : meetsAA ? "AA" : "FAIL",
    ratio,
  };
}

const result = validateColorCombination("#1a73e8", "#ffffff");
console.log(result); // { isValid: true, level: "AA", ratio: 4.5 }
```

--------------------------------

### WCAG Compliance Check

Source: https://github.com/ammuench/contrastrast/blob/main/README.md

Check WCAG compliance for specific requirements (AA, AAA, normal/large text sizes) between two colors. Returns a boolean indicating compliance.

```typescript
const bgColor = new Contrastrast("#1a73e8");

// Check different WCAG levels
const meetsAA = bgColor.meetsWCAG("#ffffff", "background", "AA"); // true
const meetsAAA = bgColor.meetsWCAG("#ffffff", "background", "AAA"); // false
const meetsAALarge = bgColor.meetsWCAG("#ffffff", "background", "AA", "large"); // true
```

--------------------------------

### Legacy textContrastForBGColor Function (Deprecated)

Source: https://github.com/ammuench/contrastrast/blob/main/README.md

A deprecated function for determining if text should be dark or light based on the background color. It is recommended to use the new class methods for contrast analysis.

```typescript
import { textContrastForBGColor } from "contrastrast";

// Legacy usage (deprecated)
const textColor = textContrastForBGColor("#1a73e8"); // "light"

// Recommended v1.0+ approach
const bgColor = new Contrastrast("#1a73e8");
const textColor = bgColor.isLight() ? "dark" : "light"; // "light"
```

--------------------------------

### Color Analysis: Light or Dark Determination

Source: https://github.com/ammuench/contrastrast/blob/main/README.md

Determine if a color is light or dark based on the AERT brightness threshold (124). Provides `isLight()` and `isDark()` methods.

```typescript
const lightColor = new Contrastrast("#ffffff");
const darkColor = new Contrastrast("#000000");
console.log(lightColor.isLight()); // true
console.log(darkColor.isDark()); // true
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.