figurelint 0.1.0

ESLint for academic figures.

FigureLint is an open-source linter for academic figures. It helps researchers and students catch common technical quality issues before submission.

Why

A figure can look fine on screen and still cause trouble during submission or production: low effective resolution, missing DPI metadata, tiny raster dimensions, accidental transparency, text converted to outlines, tiny labels, or strokes that become too thin in print.

FigureLint turns those checks into a repeatable command.

See it in action

Before — easy-to-miss problems	After — publication-safer export

Run FigureLint on the deliberately problematic example:

figurelint check examples/svg/before.svg

Typical findings:

warning  SVG_FONT_SMALL
Found 5 text element(s) below 7 pt; smallest resolved size is 5.00 pt.

warning  SVG_STROKE_THIN
Found 3 stroked element(s) below 0.5 pt; thinnest resolved stroke is 0.30 pt.

Now check the improved version:

figurelint check examples/svg/after.svg

It passes the current font-size and stroke-width checks with the default thresholds.

The demo files are intentionally simple and fully editable so you can inspect exactly what FigureLint is measuring.

Current checks

PNG / JPEG

• unreadable/corrupt image files
• missing or low DPI metadata
• suspiciously small raster dimensions
• transparency that may need flattening for some workflows
• JPEG usage (informational, because it is lossy)

SVG

• malformed/unreadable SVG files
• whether editable <text> elements are present
• suspiciously small or large resolvable font sizes
• suspiciously thin or thick resolvable strokes
• simple CSS resolution for tag, class, id, and tag.class selectors
• inline style and SVG presentation-attribute resolution

See SVG inspection details and assumptions.

PDF

• malformed/unreadable and password-protected PDF detection
• multi-page figure warnings
• unusually small or large page-size warnings
• editable-text detection
• font embedding checks
• effective DPI checks for embedded raster images
• raster soft-mask / alpha-channel detection

See PDF inspection details and assumptions.

Presets

FigureLint can apply named threshold profiles across raster, SVG, and PDF checks.

figurelint presets
figurelint check figure.svg --preset high-resolution
figurelint check figures/ --preset journal-generic
figurelint check figure.pdf --preset nature

Explicit threshold options override the selected preset, so you can start from a profile and change only one value.

Most built-in profiles are FigureLint convenience presets — not publisher policies. The nature profile is source-verified against Nature's official guidance and checks 5–7 pt ordinary SVG text, 8 pt bold upright panel labels, 0.25–1 pt SVG strokes, font-family consistency/preference, 300 dpi raster imagery, and a 247 mm PDF page-depth guardrail.

See preset engine details and Nature preset provenance.

GitHub Actions

FigureLint can emit native GitHub workflow annotations and can be used as a reusable composite action.

- uses: coocoomaomao/FigureLint@main
  with:
    path: figures/
    preset: nature
    strict: "true"

After the first tagged release, pin to @v0.1.0 instead of @main.

See GitHub Action usage.

Workflow

• recursive folder scanning
• CI-friendly exit codes
• optional strict mode
• configurable thresholds and named presets
• native GitHub Actions annotations

Planned next:

• PDF font-size and vector stroke checks
• color contrast and color-blind safety
• stronger editable-text / outlined-text analysis
• additional source-verified publisher presets

Install

Requires Python 3.10+.

PyPI

The v0.1.0 release is prepared for PyPI Trusted Publishing. Once the first public release is published:

pip install figurelint

From source

git clone https://github.com/coocoomaomao/FigureLint.git
cd FigureLint
python -m venv .venv
pip install -e .

For development:

pip install -e ".[dev]"
pytest

Maintainer release instructions are documented in docs/PUBLISHING.md.

Usage

Check one figure:

figurelint check path/to/figure.svg

Check a whole folder:

figurelint check figures/

Use a preset:

figurelint check figures/ --preset high-resolution
figurelint check figure.pdf --preset nature

List available presets:

figurelint presets

Use stricter CI behavior so warnings fail the command:

figurelint check figures/ --strict

Emit native GitHub Actions annotations:

figurelint check figures/ --preset nature --github-annotations

Customize raster thresholds:

figurelint check figure.png --min-dpi 300 --min-short-side 600

Customize SVG thresholds:

figurelint check figure.svg \
  --min-font-size-pt 5 \
  --max-font-size-pt 7 \
  --min-stroke-width-pt 0.25 \
  --max-stroke-width-pt 1

Check a PDF figure:

figurelint check figure.pdf

Customize PDF page-size guardrails:

figurelint check figure.pdf --min-pdf-short-side-in 1 --max-pdf-long-side-in 20

The existing --min-dpi option is also used for embedded raster images inside PDFs.

Example output:

┏━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ File       ┃ Severity ┃ Code            ┃ Message                      ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ figure.svg │ warning  │ SVG_FONT_SMALL  │ Found text below 7 pt.       │
└────────────┴──────────┴─────────────────┴──────────────────────────────┘

Exit codes

• 0: no errors; warnings are allowed unless --strict is used
• 1: warnings found in strict mode
• 2: one or more errors were found

Brand assets

The official FigureLint visual system uses a black cat + magnifying glass + check mark in navy, teal, orange, and soft gray.

• README banner
• Primary logo
• Icon / favicon source
• Dark-background logo
• Social preview artwork
• Brand guide

Philosophy

FigureLint should flag verifiable technical properties, not pretend that every journal has the same rules. Thresholds are configurable, and future journal presets will be documented with their source guidelines.

Release

The first public release is v0.1.0. See the v0.1.0 release notes.

Contributing

Ideas, bug reports, and pull requests are welcome. The first milestones are tracked in GitHub Issues.

License

MIT