Styling & Design System

A consistent styling approach across the team is critical for maintainability and scalability. We do not use raw CSS for styling. Instead, we rely on UI libraries such as Tailwind, Bootstrap, or MUI. Tailwind is the preferred choice because it is flexible, utility-first, and integrates well with modern development patterns. Bootstrap can be used when dealing with templates that ship with it, but Tailwind must still be added. MUI is acceptable, but inline styles must be carefully controlled, as they can quickly become unmaintainable.

Colors, spacing, and typography must always be centralized in design tokens. No free or ad-hoc values are allowed. This ensures consistency and makes global adjustments easier.

Guidelines

• Use Tailwind as the default styling solution.
• If using templates, search for ones built with Tailwind. If a template uses Bootstrap, still install Tailwind and resolve preflight/build issues during project initialization and add a Tailwind prefix to avoid conflicts.
• MUI can be used, but avoid excessive inline styling with sx or style props. Wrap MUI components into reusable wrappers under @/components/ui/*.
• Inline styles are only allowed for very small dynamic cases. Avoid them otherwise.
• Never use free values like 12px or 13px. Instead, define them in a constants file (e.g. padding.sm, font.lg).
• Never use arbitrary Tailwind values like pt-[4px]. Always use predefined Tailwind spacing (pt-1, pt-2, etc.) or extend Tailwind config with design tokens.
• Colors, spacing, and fonts must be defined in a tokens file and consumed by Tailwind or component wrappers.

---