CLI Tool

CLI Tool#

The CM-Colors command-line interface automatically tunes color contrast in CSS files to meet accessibility standards.

Overview#

The CLI tool scans CSS files for color pairs (foreground and background colors), checks their contrast against WCAG standards, and automatically adjusts colors that fail to meet accessibility requirements. Modified CSS files are saved with a _cm suffix, and a visual HTML report is generated for successfully tuned pairs.

Installation#

Install CM-Colors with pip:

pip install cm-colors

The CLI tool is automatically available after installation.

Basic Usage#

Process a single CSS file:

cm-colors style.css

Process all CSS files in a directory:

cm-colors ./styles/

Process files in the current directory:

cm-colors .

Command-Line Options#

--default-bg#

Specifies the default background color for rules that do not explicitly define a background color.

Default: white

Example:

cm-colors style.css --default-bg "#f0f0f0"

This is useful when your CSS relies on a body-level background color that is not repeated in every rule.

Features#

CSS Variable Support#

The CLI supports tuning colors defined as CSS variables (custom properties).

  • Scope: Variables must be defined in :root or html blocks within the same file.

  • Behavior: When a variable is used in a color pair that requires tuning, the CLI updates the variable definition itself. This ensures that all other usages of that variable also benefit from the improved contrast.

Example Input:

:root {
    --text-primary: #ccc; /* Too light */
}
body {
    color: var(--text-primary);
    background: white;
}

Example Output (_cm.css):

:root {
    --text-primary: #767676; /* Tuned */
}
body {
    color: var(--text-primary);
    background: white;
}

Understanding the Output#

Summary Statistics#

The CLI displays a color-coded summary at the top of the output:

2 pairs already accessible (Great job on these)
3 pairs tuned
5 failed tuning (Please pick better starter colors for these)

  • Already accessible (cyan): Color pairs that already meet WCAG AA standards

  • Tuned (green): Color pairs that were successfully adjusted to meet standards

  • Failed tuning (red): Color pairs that could not be tuned within acceptable limits

Detailed Failure Information#

For pairs that could not be tuned, the CLI provides detailed information:

Could not tune 2 pairs:
  style.css -> .header
    #cccccc on #ffffff (Contrast: 1.61)
    Reason: Could not tune without too much changes

Each failure shows:

  • The file and CSS selector

  • The original color pair (highlighted in red)

  • The current contrast ratio

  • The reason for failure

Output Files#

Modified CSS Files#

For each processed CSS file, a modified version is created with the suffix _cm:

  • Input: style.css

  • Output: style_cm.css

The modified file contains the same CSS structure with tuned colors where necessary.

HTML Report#

When colors are successfully tuned, an HTML report is generated at cm_colors_report.html. This report provides a visual comparison of the before and after states for each tuned color pair.

Practical Examples#

Example 1: Single File Processing#

cm-colors navigation.css

Output:

Processing 1 files...

1 pairs already accessible (Great job on these)
2 pairs tuned

Report generated: /path/to/cm_colors_report.html
Have a chocolate

Example 2: Directory Processing#

cm-colors ./css/

Output:

Processing 5 files...

8 pairs already accessible (Great job on these)
4 pairs tuned
1 failed tuning (Please pick better starter colors for these)

Could not tune 1 pairs:
  main.css -> .warning
    #fff200 on #ffffff (Contrast: 1.13)
    Reason: Could not tune without too much changes

Report generated: /path/to/cm_colors_report.html
Have a chocolate

Troubleshooting#

Command Not Found#

If the cm-colors command is not found after installation:

  1. Verify installation: pip show cm-colors

  2. Check that the installation location is in your PATH

  3. Try using the module directly: python -m cm_colors.cli.main

No CSS Files Found#

If you see “No CSS files found”:

  • Verify the path is correct

  • Check that CSS files exist in the specified directory

  • Ensure files have the .css extension

  • Note that *_cm.css files are automatically excluded

Many Failures#

If many color pairs fail to tune:

Contents