Skip to content
Fallow home
All docs pages

Docs home

Styling

Find unused CSS Module classes, broken class references and style drift in CSS, SCSS, Tailwind and CSS-in-JS with fallow.

Stylesheets collect old classes, copied blocks and one-off values. Nothing tells you when a class is no longer used, or when a name points nowhere. In the example on this page, a spinner uses the animation spin, and no file defines @keyframes spin: the page loads, and the spinner never turns. Fallow finds the CSS Module classes that no component reads, and it rates the quality of each stylesheet.

npx fallow health --css

What fallow finds

The demo project has no styles. This page adds a component, src/ui/ReceiptCard.tsx, with a CSS Module and a plain stylesheet, and imports the component in src/index.ts:

/* src/ui/ReceiptCard.module.css */
.card {
  display: flex;
}

.voided {
  opacity: 0.5;
}
/* src/ui/receipt.css */
.receipt-title {
  font-weight: 600;
}

.spinner {
  animation: spin 1s linear infinite;
}

body main .receipt > .lines ul li a.active:hover {
  color: red !important;
}
// src/ui/ReceiptCard.tsx
import "./receipt.css";
import styles from "./ReceiptCard.module.css";

export const ReceiptCard = () => (
  <div className={styles.card}>
    <h2 className="receipt-title">Receipt</h2>
    <span className="spinner" />
  </div>
);

Unused CSS Module classes

Fallow reads each class of a CSS Module as an export. The component reads styles.card and never styles.voided, so fallow dead-code reports voided as an unused export, next to the three unused exports of the demo:

● Unused exports (4)
  src/ui/ReceiptCard.module.css
    :5 voided
  Exported symbols with no known consumers
  https://fallow.tools/docs/explanations/dead-code/#unused-exports

Style quality

A plain stylesheet has no exports, so its problems need another check. fallow health --css adds a CSS health section to the health report:

CSS health
  Styling health: ~79 B (CSS quality, scored separately from the code health score)
  Low confidence: graded from only 5 declarations across 2 stylesheets
  Deductions: structural -10.0 · dead surface -8.0 · broken refs -3.0
  2 stylesheets · 5 rules · 20.0% !important · 0 empty · max nesting 0
  value sprawl: 1 distinct color · 0 font sizes · 0 z-index values
  undefined @keyframes: 1 referenced but defined nowhere (candidates; likely typo or defined in CSS-in-JS): spin (src/ui/receipt.css)
  3 global CSS classes referenced by no in-project markup (candidates; verify no email / server template / CMS / Markdown applies them):
  src/ui/ReceiptCard.module.css:5: .voided
  src/ui/receipt.css:9: .active
  src/ui/receipt.css:9: .lines
  src/ui/receipt.css:9  specificity (0,4,5) · complexity 15 · 1 !important · nesting 0
LineMeaning
Styling health: ~79 BA score from 0 to 100 and a grade for the styles. Fallow scores it apart from the health score, and it never changes an exit code.
Low confidenceThe project has too few styles for a reliable score. The ~ marks the same.
DeductionsThe areas that lower the score: dead styles, broken references, copied blocks, values outside the design tokens, and structure.
undefined @keyframesAn animation names a @keyframes block that no file defines: spin.
referenced by no in-project markupA class that no markup in the project uses, for example .active in the selector on line 9.
specificity (0,4,5)A selector that is hard to override: the selector on line 9.

Styling findings

Fallow turns these signals into findings of five issue types:

Issue typeReports
css-dead-surfaceStyles that nothing uses: classes, @theme tokens, @keyframes, font faces and CSS-in-JS style bindings.
css-broken-referenceA class or an animation name with no definition, for example a typo one letter away from a real class.
css-duplicate-blockThe same block of declarations in two rules or more.
css-selector-complexityA selector that is too specific, too deep or uses !important.
css-token-driftA fixed value that goes around the design tokens, for example a Tailwind value such as w-[13px].

All five rules have the severity warn by default.

How fallow decides

Fallow reads .css, .scss, .sass and .less files, and the <style> blocks of Vue and Svelte files. It also reads CSS-in-JS code such as styled-components, Emotion, StyleX, vanilla-extract and PandaCSS.

For the module graph, a stylesheet is a file like any other:

  • @import, @use and @forward are imports. Fallow resolves SCSS partials, such as _button.scss for @use 'button'. A used stylesheet is never an unused file.
  • In a .module.css, .module.scss, .module.sass or .module.less file, each class is an export. styles.card uses the class card. When code uses the whole styles object, each class counts as used.
  • @tailwind, @apply and @plugin use the tailwindcss package and each plugin package, so fallow does not report them as unused dependencies.

For the quality checks, fallow compares the classes in the stylesheets with the classes in the markup. Markup is JSX, Vue, Svelte, Astro and HTML. It also reads server templates such as .liquid, .njk, .hbs and .twig. Add other template extensions with markupExtensions.

A class can be in use in a way that fallow cannot see, so each styling finding is a candidate. Each finding has a confidence and a fix hint in the JSON output.

Act on a finding

The confidence decides the next step. On a branch that adds the receipt card, fallow audit checks the styles of the changed files and sorts the findings into two groups:

── Styling ────────────────────────────────────────
  Fix confidently
    src/ui/receipt.css:9  css-selector-complexity  1 !important declaration across 1 declaration  (advisory: rules.css-selector-complexity=warn, introduced design-system drift since main)
  Verify first
    src/ui/ReceiptCard.module.css:5  css-dead-surface  voided  (advisory: rules.css-dead-surface=warn, introduced design-system drift since main)
    src/ui/receipt.css:1  css-broken-reference  spin  (advisory: rules.css-broken-reference=warn, introduced design-system drift since main)
    src/ui/receipt.css:9  css-dead-surface  active  (advisory: rules.css-dead-surface=warn, introduced design-system drift since main)
    + 1 more styling finding
GroupAction
Fix confidentlyThe code alone shows the problem. Simplify the selector, or merge the copied block.
Verify firstSearch for other users before you delete. An email template, a CMS or a class name that the code builds when it runs can use the class.

For an unused CSS Module class, delete the class. For a broken reference, correct the name in the markup or add the definition: here, add @keyframes spin. For token drift, use a token of your design system in place of the fixed value.

To accept one finding, add the suppression comment that the rule page of its issue type gives. For Tailwind values that are correct on purpose, list them in health.tailwindIgnorePatterns.

Fail a run

The styling findings do not fail a run by default: each line of the audit above says advisory. To fail on one issue type, set its rule to error:

// .fallowrc.jsonc
{
  "rules": {
    "css-broken-reference": "error"
  }
}

fallow audit checks the styles by default, so a styling finding at error that the change introduces makes its verdict fail. Add --no-css to skip the styling checks. Bare fallow does not run them. Changed code and baselines explains the verdict.

What fallow cannot see

  • A class name that the code builds when it runs, for example `btn-${size}`.
  • A use in HTML outside the project, for example in an email or a CMS. Such a class looks unused.
  • Sass and Less structure that needs a compile. Fallow does not expand mixins or loops.

In fallow health --css, unused global classes, unused tokens and broken references are candidates in the CSS health section. fallow audit reports them as findings.

Reference