Description

Implement eslint-plugin-tailwindcss to provide comprehensive linting and validation for Tailwind CSS usage across the design system. This plugin will complement our existing VS Code IntelliSense setup and enforce consistent Tailwind CSS practices, particularly important now that we've removed default Tailwind utilities to enforce design system component usage.

The plugin offers 8+ rules for enforcing best practices, with the key benefit being the no-custom-classname rule that prevents usage of invalid Tailwind classes - perfect for our goal of enforcing Text component usage and design system compliance.

Technical Details

Installation:

• Add eslint-plugin-tailwindcss as a dev dependency
• Configure ESLint flat config to use the plugin with our existing dual-config setup

Key Rules to Implement:

• no-custom-classname: Prevents invalid Tailwind classes (main enforcement mechanism)
• no-contradicting-classname: Prevents conflicting classes like text-left text-right
• classnames-order: Enforces consistent class ordering (complements prettier-plugin-tailwindcss)
• enforces-shorthand: Merges multiple classnames into shorthand (e.g. mx-5 my-5 → m-5)
• no-unnecessary-arbitrary-value: Suggests configuration-based classnames over arbitrary values

Configuration Strategy:

• Mirror existing VS Code IntelliSense setup with two configurations:
  • React Web: Use apps/storybook-react/tailwind.config.js
  • React Native: Use apps/storybook-react-native/tailwind-intellisense.config.js
• Configure callees to match existing setup: ["tw", "twMerge", "clsx", "cn", "cva"]
• Set classRegex to match existing patterns: "^(class(Name)?|tw(ClassName)?)$"

File Patterns:

• React Web Files: packages/design-system-react/src/**, apps/storybook-react/**, packages/design-tokens/stories/**
• React Native Files: packages/design-system-react-native/src/**, apps/storybook-react-native/stories/**

Acceptance Criteria

• eslint-plugin-tailwindcss is installed and configured in eslint.config.mjs
• ESLint validates Tailwind classes for both React and React Native file patterns
• Plugin uses correct Tailwind config for each platform (mirrors VS Code setup)
• no-custom-classname rule prevents usage of removed default utilities (e.g., text-sm, bg-red-500)
• ESLint validation works alongside existing VS Code IntelliSense validation
• yarn lint command catches invalid Tailwind classes
• CI/CD builds fail when invalid Tailwind classes are detected
• Plugin works with existing prettier-plugin-tailwindcss without conflicts
• All existing valid design system classes pass validation
• Documentation is updated with new linting rules and expectations

Success Indicators:

• Developers cannot use removed default Tailwind utilities without ESLint errors
• Class ordering and formatting remain consistent with existing Prettier setup
• Build failures occur when invalid classes are introduced
• Team receives immediate feedback on Tailwind CSS best practices

References

• Package: https://www.npmjs.com/package/eslint-plugin-tailwindcss
• Current VS Code Setup: .vscode/settings.json with tailwindCSS.validate: true
• Current ESLint Config: eslint.config.mjs using flat config format
• Prettier Config: .prettierrc.js with prettier-plugin-tailwindcss
• Related Work: Recent changes removing default font sizes and colors to enforce design system usage
• Tailwind Configs:
  • React: apps/storybook-react/tailwind.config.js
  • React Native: apps/storybook-react-native/tailwind-intellisense.config.js
• ESLint 9 Compatibility: Plugin supports flat config format (required for our setup)
• GitHub Repository: https://github.com/francoismassart/eslint-plugin-tailwindcss