maintainable-frontend-styles

Maintainable Frontend Styles

Prefer following repository conventions: when Tailwind is installed, use utility classes for regular component styling, and converge complex local rules into a CSS/SCSS Module colocated with the component. Do not replace a problem that has not yet repeated with a new abstraction, and do not replace component boundaries with a single giant stylesheet.

Core Principles

Priority	Approach	Scope of Application
1	Tailwind class	Layout, spacing, typography, color, borders, responsiveness, theming, and interaction states
2	.module.css / .module.scss	Complex selectors, pseudo-elements, keyframes, content styling, third-party overrides, or local rules where utilities significantly reduce readability
3	Global CSS	reset、@font-face, theme tokens, Tailwind entry points, and genuinely global third-party base styles
4	inline style	Values generated at runtime that cannot be statically enumerated should preferably be passed via CSS custom properties

Place the repository's explicit rules before this table. When conflicts are found, explain the differences and request a decision; do not silently rewrite the project's styling architecture.

Workflow

1. Inspect the current repository

First read the relevant components, adjacent styles,package.json, framework configuration, Tailwind version, Sass dependencies, global style entry points, design tokens, class merging utilities, and lint/format scripts.

Confirm:

• Whether the project actually uses Tailwind v3 or v4, and do not mix the syntax of the two versions.
• Whether there is already clsx、cn、CVA、tailwind-variants or tailwind-merge。
• Whether the project already has a component library, style file naming, and colocation conventions.
• Whether the change is a local implementation, a code review, or an authorized migration.

2. Choose the styling layer

Choose the shallowest maintainable approach according to the core principles:

• When it can be clearly expressed with existing Tailwind tokens and variants, write the full class directly.
• When DOM relationships, pseudo-elements, keyframes, or controlled third-party selectors are needed, use a component Module.
• When visual and structural reuse across components is needed, prefer extracting a React component rather than sharing a large CSS class.
• Only themes, resets, fonts, or external global constraints may go into global styles.

Do not switch approaches just to reduce the number of class characters. Do not write runtime-enumerable states as dynamically concatenated Tailwind classes.

3. Handle dependencies and migration

When the project lacks Tailwind or Sass:

1. List the dependencies to be added, configuration, entry files, expected benefits, and migration scope.
2. Request user approval.
3. Before approval, do not install dependencies, modify build configuration, or carry out a repository-wide migration.
4. When the user rejects migration, use the existing approach; when local scoping is needed, prefer what the framework already supports .module.css。

Do not interpret "implement one component" as "migrate the entire project".

4. Implement or review

• Tailwind tasks must read references/tailwind-patterns.md。
• CSS/SCSS Module, giant Module splitting, or Sass reuse tasks must read references/scss-modules-patterns.md。
• Code review, migration suggestions, or visually unchanged refactoring must read references/review-playbook.md。

Only modify the files required by the task. Preserve the style of adjacent code; do not refactor unrelated styles along the way.

5. Verify

Run the repository's existing checks relevant to the change:

1. formatter or Tailwind class sorter;
2. Stylelint, ESLint, and type checking;
3. component tests or visual tests;
4. Next.js/Vite production build.

At minimum, manually confirm responsive breakpoints, hover/focus-visible/disabled states, dark theme, reduced motion preference, and CSS order in the production build. Checks that cannot be run must be clearly reported and must not be written as passed.

Completion criteria

• Conventional styles do not fall back to raw global CSS without reason.
• Tailwind classes are complete and statically detectable, with no conflicting utilities.
• Module and component responsibilities are consistent, with no newly added giant shared style file.
• Duplicate styles are handled in the order "loops → components → variants → local composition".
• New dependencies, configuration, or migrations have all received explicit authorization.
• The results pass the relevant checks, and any still-unverified visual or browser risks are explained.