DEV Community

Cover image for 19 Custom Lint Rules Killed Design-System Drift in Two Production Flutter Apps
Sagar Ghag
Sagar Ghag

Posted on Originally published at doi.org

19 Custom Lint Rules Killed Design-System Drift in Two Production Flutter Apps

Colors.red in a Flutter widget. Sounds harmless. In a production app with a design system, it's a landmine: one developer uses Colors.red, another uses Theme.of(context).colorScheme.error, and six months later your app ships with two shades of red on the same screen and nobody can explain why.

We had this problem across two production Flutter codebases (105K LOC and 59K LOC). Instead of writing a style guide nobody reads, we wrote 19 custom lint rules using the custom_lint framework. 13 are org-wide (published as kx_lints on pub.dev). 6 are project-specific.

I wrote a preprint measuring the results: DOI: 10.5281/zenodo.24263596.

The Drift Problem

Design-system drift is when developers bypass your theme and use hardcoded values. In Flutter, the most common forms are:

  • Colors.red instead of Theme.of(context).colorScheme.error
  • TextStyle(fontSize: 16) instead of Theme.of(context).textTheme.bodyLarge
  • Direct import 'package:flutter/material.dart' in files that should only use the design system's re-export

PR review catches some of this. But a reviewer scanning a 400-line diff will miss a Colors.grey buried on line 287. And even if they don't, the fix is always the same: "use the theme." You're paying a human to do a grep.

What the Rules Enforce

The 13 org-wide rules in kx_lints cover:

  • no_material_colors: flags any use of Colors.* constants
  • no_hardcoded_text_style: flags TextStyle() constructors outside the theme definition file
  • prefer_theme_colors: flags hex colour literals in widget code
  • no_direct_material_import: flags import 'package:flutter/material.dart' in favour of the design system's re-export

The 6 project-specific rules cover patterns unique to one codebase: a particular naming convention for route constants, a required parameter order for the project's base widget, and restrictions on which packages can import which.

The Numbers

We measured violation density (violations per thousand lines of code) across monthly snapshots in the Alpha codebase (105K LOC, 7 months of history):

  • Colors.* violations dropped from 0.72 to 0.00 per KLOC after the rules landed
  • Theme.of() density fell 91% as developers moved to the typed theme extension
  • The rules caught 258 material.dart imports across the org that the org-wide rules alone missed (project-specific rules were needed because some files legitimately import material.dart for widget definitions)

In the Beta codebase (59K LOC, 34 days of history), we could only do a HEAD-only analysis. Too little history for a time series. But at HEAD: zero Colors.* violations, because the rules were in place from day one.

What Surprised Me

Project-specific rules exposed violations that org-wide rules missed. The no_direct_material_import rule flagged 258 imports across the org, but some of those imports were legitimate (widget definition files need material.dart). The project-specific version of the rule had an allowlist for those files. Without it, developers would either ignore the lint or disable it globally, which defeats the point.

The other surprise: the rules paid for themselves in the first week. One rule (no_material_colors) caught 23 violations in existing code on its first run. Each violation was a hardcoded colour that diverged from the theme. Fixing them took one developer half a day. Finding them without the rule would have taken longer.

Setup

The rules use custom_lint and analyzer_plugin. Setup is one pubspec.yaml dependency and a short analysis_options.yaml include. The rules are open source: kx_lints on pub.dev.

I would not call the developer experience perfect. custom_lint occasionally needs a restart of the analysis server, and the error messages could be more specific about which theme accessor to use instead. But the cost of those rough edges is lower than the cost of the drift they prevent.

The Paper

Full methodology, violation density timelines, and the mining scripts: doi.org/10.5281/zenodo.24263596.

If you've built custom lint rules for your Flutter project (or any Dart project), I'm curious whether you went org-wide, project-specific, or both, and how you handled the allowlist problem.

Top comments (0)