Does Stylelint have an HTML formatter?

Not built in. Its formatters are string, compact, github, json, tap, unix and verbose. `stylelint-junit-formatter` is a custom formatter that emits JUnit XML, which converts to HTML with the usual tools.

How do I use a custom formatter?

Pass the module path: `stylelint '**/*.css' --custom-formatter node_modules/stylelint-junit-formatter > stylelint.xml`.

Can I report on CSS-in-JS or SCSS?

Yes — with the relevant syntax package configured (`postcss-scss`, `postcss-styled-syntax`), the findings appear in the same output and publish identically.

Why would a designer care?

Because a good share of Stylelint findings are design-system questions wearing a lint hat: a hard-coded hex that should be a token, a duplicate breakpoint. Those need the person who owns the token, not just the person who owns the file.

Should the report step fail the build?

No. Keep a separate unmuted `stylelint` step as the gate and mute the reporting step with `|| true`.

Share a Stylelint report

Most Stylelint findings are trivial. The interesting ones are not lint problems at all — they are design-system problems: a hex value that should have been a token, a fourth definition of the same breakpoint, a z-index of 9999 that somebody will regret.

The person who can settle those usually does not have the repo checked out.

JUnit formatter → HTML

npm i -D stylelint stylelint-junit-formatter
pip install junit2html

npx stylelint "src/**/*.{css,scss}" \
  --custom-formatter node_modules/stylelint-junit-formatter \
  > stylelint.xml || true
junit2html stylelint.xml stylelint.html

Custom formatters take a module path rather than a name, which is the part that trips people up.

Publish it

Drag stylelint.html into the app, or from CI:

curl -fsS -X PATCH "https://commareports.com/api/v1/reports/$REPORT_ID" \
  -H "Authorization: Bearer $COMMA_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile html stylelint.html \
        --arg title "Stylelint — $GITHUB_REF_NAME" '{title: $title, html: $html}')"

Getting design into the loop

A link is the only format that reaches somebody without a checkout. Once the findings are a URL:

Anchored threads on the hard-coded colour — "that's --surface-2, I'll add it to the token doc" — from the person who owns the token, without a seat, a repo or a local Node version. See commenting on HTML.
Revisions, so a token migration has a visible finish line.
Access per report — private, team, domain-gated, or named reviewers. See the sharing model.

Custom-property rules (declaration-property-value-no-unknown, custom-property-pattern) are where this pays off most: they generate the findings a design system actually cares about.

Limits

Entry HTML: 5 MB. Assets: 25 MB per file, 250 MB and 500 files total.
60 requests/minute per token.

Try it

Comma is free — unlimited reports, unlimited commenters, unlimited revision history.

Publish a lint report →