[
{
"No": "1",
"Category": "Animation",
"Guideline": "Use Tailwind animate utilities",
"Description": "Built-in animations are optimized and respect reduced-motion",
"Do": "Use animate-pulse animate-spin animate-ping",
"Don't": "Custom @keyframes for simple effects",
"Code Good": "animate-pulse",
"Code Bad": "@keyframes pulse {...}",
"Severity": "Medium",
"Docs URL": "https://tailwindcss.com/docs/animation"
},
{
"No": "2",
"Category": "Animation",
"Guideline": "Limit bounce animations",
"Description": "Continuous bounce is distracting and causes motion sickness",
"Do": "Use animate-bounce sparingly on CTAs only",
"Don't": "Multiple bounce animations on page",
"Code Good": "Single CTA with animate-bounce",
"Code Bad": "5+ elements with animate-bounce",
"Severity": "High",
"Docs URL": ""
},
{
"No": "3",
"Category": "Animation",
"Guideline": "Transition duration",
"Description": "Use appropriate transition speeds for UI feedback",
"Do": "duration-150 to duration-300 for UI",
"Don't": "duration-1000 or longer for UI elements",
"Code Good": "transition-all duration-200",
"Code Bad": "transition-all duration-1000",
"Severity": "Medium",
"Docs URL": "https://tailwindcss.com/docs/transition-duration"
},
{
"No": "4",
"Category": "Animation",
"Guideline": "Hover transitions",
"Description": "Add smooth transitions on hover state changes",
"Do": "Add transition class with hover states",
"Don't": "Instant hover changes without transition",
"Code Good": "hover:bg-gray-100 transition-colors",
"Code Bad": "hover:bg-gray-100 (no transition)",
"Severity": "Low",
"Docs URL": ""
},
{
"No": "5",
"Category": "Z-Index",
"Guideline": "Use Tailwind z-* scale",
"Description": "Consistent stacking context with predefined scale",
"Do": "z-0 z-10 z-20 z-30 z-40 z-50",
"Don't": "Arbitrary z-index values",
"Code Good": "z-50 for modals",
"Code Bad": "z-[9999]",
"Severity": "Medium",
"Docs URL": "https://tailwindcss.com/docs/z-index"
},
{
"No": "6",
"Category": "Z-Index",
"Guideline": "Fixed elements z-index",
"Description": "Fixed navigation and modals need explicit z-index",
"Do": "z-50 for nav z-40 for dropdowns",
"Don't": "Relying on DOM order for stacking",
"Code Good": "fixed top-0 z-50",
"Code Bad": "fixed top-0 (no z-index)",
"Severity": "High",
"Docs URL": ""
},
{
"No": "7",
"Category": "Z-Index",
"Guideline": "Negative z-index for backgrounds",
"Description": "Use negative z-index for decorative backgrounds",
"Do": "z-[-1] for background elements",
"Don't": "Positive z-index for backgrounds",
"Code Good": "-z-10 for decorative",
"Code Bad": "z-10 for background",
"Severity": "Low",
"Docs URL": ""
},
{
"No": "8",
"Category": "Layout",
"Guideline": "Container max-width",
"Description": "Limit content width for readability",
"Do": "max-w-7xl mx-auto for main content",
"Don't": "Full-width content on large screens",
"Code Good": "max-w-7xl mx-auto px-4",
"Code Bad": "w-full (no max-width)",
"Severity": "Medium",
"Docs URL": "https://tailwindcss.com/docs/container"
},
{
"No": "9",
"Category": "Layout",
"Guideline": "Responsive padding",
"Description": "Adjust padding for different screen sizes",
"Do": "px-4 md:px-6 lg:px-8",
"Don't": "Same padding all sizes",
"Code Good": "px-4 sm:px-6 lg:px-8",
"Code Bad": "px-8 (same all sizes)",
"Severity": "Medium",
"Docs URL": ""
},
{
"No": "10",
"Category": "Layout",
"Guideline": "Grid gaps",
"Description": "Use consistent gap utilities for spacing",
"Do": "gap-4 gap-6 gap-8",
"Don't": "Margins on individual items",
"Code Good": "grid gap-6",
"Code Bad": "grid with mb-4 on each item",
"Severity": "Medium",
"Docs URL": "https://tailwindcss.com/docs/gap"
},
{
"No": "11",
"Category": "Layout",
"Guideline": "Flexbox alignment",
"Description": "Use flex utilities for alignment",
"Do": "items-center justify-between",
"Don't": "Multiple nested wrappers",
"Code Good": "flex items-center justify-between",
"Code Bad": "Nested divs for alignment",
"Severity": "Low",
"Docs URL": ""
},
{
"No": "12",
"Category": "Images",
"Guideline": "Aspect ratio",
"Description": "Maintain consistent image aspect ratios",
"Do": "aspect-video aspect-square",
"Don't": "No aspect ratio on containers",
"Code Good": "aspect-video rounded-lg",
"Code Bad": "No aspect control",
"Severity": "Medium",
"Docs URL": "https://tailwindcss.com/docs/aspect-ratio"
},
{
"No": "13",
"Category": "Images",
"Guideline": "Object fit",
"Description": "Control image scaling within containers",
"Do": "object-cover object-contain",
"Don't": "Stretched distorted images",
"Code Good": "object-cover w-full h-full",
"Code Bad": "No object-fit",
"Severity": "Medium",
"Docs URL": "https://tailwindcss.com/docs/object-fit"
},
{
"No": "14",
"Category": "Images",
"Guideline": "Lazy loading",
"Description": "Defer loading of off-screen images",
"Do": "loading='lazy' on images",
"Don't": "All images eager load",
"Code Good": "<img loading='lazy'>",
"Code Bad": "<img> without lazy",
"Severity": "High",
"Docs URL": ""
},
{
"No": "15",
"Category": "Images",
"Guideline": "Responsive images",
"Description": "Serve appropriate image sizes",
"Do": "srcset and sizes attributes",
"Don't": "Same large image all devices",
"Code Good": "srcset with multiple sizes",
"Code Bad": "4000px image everywhere",
"Severity": "High",
"Docs URL": ""
},
{
"No": "16",
"Category": "Typography",
"Guideline": "Prose plugin",
"Description": "Use @tailwindcss/typography for rich text",
"Do": "prose prose-lg for article content",
"Don't": "Custom styles for markdown",
"Code Good": "prose prose-lg max-w-none",
"Code Bad": "Custom text styling",
"Severity": "Medium",
"Docs URL": "https://tailwindcss.com/docs/typography-plugin"
},
{
"No": "17",
"Category": "Typography",
"Guideline": "Line height",
"Description": "Use appropriate line height for readability",
"Do": "leading-relaxed for body text",
"Don't": "Default tight line height",
"Code Good": "leading-relaxed (1.625)",
"Code Bad": "leading-none or leading-tight",
"Severity": "Medium",
"Docs URL": "https://tailwindcss.com/docs/line-height"
},
{
"No": "18",
"Category": "Typography",
"Guideline": "Font size scale",
"Description": "Use consistent text size scale",
"Do": "text-sm text-base text-lg text-xl",
"Don't": "Arbitrary font sizes",
"Code Good": "text-lg",
"Code Bad": "text-[17px]",
"Severity": "Low",
"Docs URL": "https://tailwindcss.com/docs/font-size"
},
{
"No": "19",
"Category": "Typography",
"Guideline": "Text truncation",
"Description": "Handle long text gracefully",
"Do": "truncate or line-clamp-*",
"Don't": "Overflow breaking layout",
"Code Good": "line-clamp-2",
"Code Bad": "No overflow handling",
"Severity": "Medium",
"Docs URL": "https://tailwindcss.com/docs/text-overflow"
},
{
"No": "20",
"Category": "Colors",
"Guideline": "Opacity utilities",
"Description": "Use color opacity utilities",
"Do": "bg-black/50 text-white/80",
"Don't": "Separate opacity class",
"Code Good": "bg-black/50",
"Code Bad": "bg-black opacity-50",
"Severity": "Low",
"Docs URL": "https://tailwindcss.com/docs/background-color"
},
{
"No": "21",
"Category": "Colors",
"Guideline": "Dark mode",
"Description": "Support dark mode with dark: prefix",
"Do": "dark:bg-gray-900 dark:text-white",
"Don't": "No dark mode support",
"Code Good": "dark:bg-gray-900",
"Code Bad": "Only light theme",
"Severity": "Medium",
"Docs URL": "https://tailwindcss.com/docs/dark-mode"
},
{
"No": "22",
"Category": "Colors",
"Guideline": "Semantic colors",
"Description": "Use semantic color naming in config",
"Do": "primary secondary danger success",
"Don't": "Generic color names in components",
"Code Good": "bg-primary",
"Code Bad": "bg-blue-500 everywhere",
"Severity": "Medium",
"Docs URL": ""
},
{
"No": "23",
"Category": "Spacing",
"Guideline": "Consistent spacing scale",
"Description": "Use Tailwind spacing scale consistently",
"Do": "p-4 m-6 gap-8",
"Don't": "Arbitrary pixel values",
"Code Good": "p-4 (1rem)",
"Code Bad": "p-[15px]",
"Severity": "Low",
"Docs URL": "https://tailwindcss.com/docs/customizing-spacing"
},
{
"No": "24",
"Category": "Spacing",
"Guideline": "Negative margins",
"Description": "Use sparingly for overlapping effects",
"Do": "-mt-4 for overlapping elements",
"Don't": "Negative margins for layout fixing",
"Code Good": "-mt-8 for card overlap",
"Code Bad": "-m-2 to fix spacing issues",
"Severity": "Medium",
"Docs URL": ""
},
{
"No": "25",
"Category": "Spacing",
"Guideline": "Space between",
"Description": "Use space-y-* for vertical lists",
"Do": "space-y-4 on flex/grid column",
"Don't": "Margin on each child",
"Code Good": "space-y-4",
"Code Bad": "Each child has mb-4",
"Severity": "Low",
"Docs URL": "https://tailwindcss.com/docs/space"
},
{
"No": "26",
"Category": "Forms",
"Guideline": "Focus states",
"Description": "Always show focus indicators",
"Do": "focus:ring-2 focus:ring-blue-500",
"Don't": "Remove focus outline",
"Code Good": "focus:ring-2 focus:ring-offset-2",
"Code Bad": "focus:outline-none (no replacement)",
"Severity": "High",
"Docs URL": ""
},
{
"No": "27",
"Category": "Forms",
"Guideline": "Input sizing",
"Description": "Consistent input dimensions",
"Do": "h-10 px-3 for inputs",
"Don't": "Inconsistent input heights",
"Code Good": "h-10 w-full px-3",
"Code Bad": "Various heights per input",
"Severity": "Medium",
"Docs URL": ""
},
{
"No": "28",
"Category": "Forms",
"Guideline": "Disabled states",
"Description": "Clear disabled styling",
"Do": "disabled:opacity-50 disabled:cursor-not-allowed",
"Don't": "No disabled indication",
"Code Good": "disabled:opacity-50",
"Code Bad": "Same style as enabled",
"Severity": "Medium",
"Docs URL": ""
},
{
"No": "29",
"Category": "Forms",
"Guideline": "Placeholder styling",
"Description": "Style placeholder text appropriately",
"Do": "placeholder:text-gray-400",
"Don't": "Dark placeholder text",
"Code Good": "placeholder:text-gray-400",
"Code Bad": "Default dark placeholder",
"Severity": "Low",
"Docs URL": ""
},
{
"No": "30",
"Category": "Responsive",
"Guideline": "Mobile-first approach",
"Description": "Start with mobile styles and add breakpoints",
"Do": "Default mobile + md: lg: xl:",
"Don't": "Desktop-first approach",
"Code Good": "text-sm md:text-base",
"Code Bad": "text-base max-md:text-sm",
"Severity": "Medium",
"Docs URL": "https://tailwindcss.com/docs/responsive-design"
},
{
"No": "31",
"Category": "Responsive",
"Guideline": "Breakpoint testing",
"Description": "Test at standard breakpoints",
"Do": "320 375 768 1024 1280 1536",
"Don't": "Only test on development device",
"Code Good": "Test all breakpoints",
"Code Bad": "Single device testing",
"Severity": "High",
"Docs URL": ""
},
{
"No": "32",
"Category": "Responsive",
"Guideline": "Hidden/shown utilities",
"Description": "Control visibility per breakpoint",
"Do": "hidden md:block",
"Don't": "Different content per breakpoint",
"Code Good": "hidden md:flex",
"Code Bad": "Separate mobile/desktop components",
"Severity": "Low",
"Docs URL": "https://tailwindcss.com/docs/display"
},
{
"No": "33",
"Category": "Buttons",
"Guideline": "Button sizing",
"Description": "Consistent button dimensions",
"Do": "px-4 py-2 or px-6 py-3",
"Don't": "Inconsistent button sizes",
"Code Good": "px-4 py-2 text-sm",
"Code Bad": "Various padding per button",
"Severity": "Medium",
"Docs URL": ""
},
{
"No": "34",
"Category": "Buttons",
"Guideline": "Touch targets",
"Description": "Minimum 44px touch target on mobile",
"Do": "min-h-[44px] on mobile",
"Don't": "Small buttons on mobile",
"Code Good": "min-h-[44px] min-w-[44px]",
"Code Bad": "h-8 w-8 on mobile",
"Severity": "High",
"Docs URL": ""
},
{
"No": "35",
"Category": "Buttons",
"Guideline": "Loading states",
"Description": "Show loading feedback",
"Do": "disabled + spinner icon",
"Don't": "Clickable during loading",
"Code Good": "<Button disabled><Spinner/></Button>",
"Code Bad": "Button without loading state",
"Severity": "High",
"Docs URL": ""
},
{
"No": "36",
"Category": "Buttons",
"Guideline": "Icon buttons",
"Description": "Accessible icon-only buttons",
"Do": "aria-label on icon buttons",
"Don't": "Icon button without label",
"Code Good": "<button aria-label='Close'><XIcon/></button>",
"Code Bad": "<button><XIcon/></button>",
"Severity": "High",
"Docs URL": ""
},
{
"No": "37",
"Category": "Cards",
"Guideline": "Card structure",
"Description": "Consistent card styling",
"Do": "rounded-lg shadow-md p-6",
"Don't": "Inconsistent card styles",
"Code Good": "rounded-2xl shadow-lg p-6",
"Code Bad": "Mixed card styling",
"Severity": "Low",
"Docs URL": ""
},
{
"No": "38",
"Category": "Cards",
"Guideline": "Card hover states",
"Description": "Interactive cards should have hover feedback",
"Do": "hover:shadow-lg transition-shadow",
"Don't": "No hover on clickable cards",
"Code Good": "hover:shadow-xl transition-shadow",
"Code Bad": "Static cards that are clickable",
"Severity": "Medium",
"Docs URL": ""
},
{
"No": "39",
"Category": "Cards",
"Guideline": "Card spacing",
"Description": "Consistent internal card spacing",
"Do": "space-y-4 for card content",
"Don't": "Inconsistent internal spacing",
"Code Good": "space-y-4 or p-6",
"Code Bad": "Mixed mb-2 mb-4 mb-6",
"Severity": "Low",
"Docs URL": ""
},
{
"No": "40",
"Category": "Accessibility",
"Guideline": "Screen reader text",
"Description": "Provide context for screen readers",
"Do": "sr-only for hidden labels",
"Don't": "Missing context for icons",
"Code Good": "<span class='sr-only'>Close menu</span>",
"Code Bad": "No label for icon button",
"Severity": "High",
"Docs URL": "https://tailwindcss.com/docs/screen-readers"
},
{
"No": "41",
"Category": "Accessibility",
"Guideline": "Focus visible",
"Description": "Show focus only for keyboard users",
"Do": "focus-visible:ring-2",
"Don't": "Focus on all interactions",
"Code Good": "focus-visible:ring-2",
"Code Bad": "focus:ring-2 (shows on click too)",
"Severity": "Medium",
"Docs URL": ""
},
{
"No": "42",
"Category": "Accessibility",
"Guideline": "Reduced motion",
"Description": "Respect user motion preferences",
"Do": "motion-reduce:animate-none",
"Don't": "Ignore motion preferences",
"Code Good": "motion-reduce:transition-none",
"Code Bad": "No reduced motion support",
"Severity": "High",
"Docs URL": "https://tailwindcss.com/docs/hover-focus-and-other-states#prefers-reduced-motion"
},
{
"No": "43",
"Category": "Performance",
"Guideline": "Configure content paths",
"Description": "Tailwind needs to know where classes are used",
"Do": "Use 'content' array in config",
"Don't": "Use deprecated 'purge' option (v2)",
"Code Good": "content: ['./src/**/*.{js,ts,jsx,tsx}']",
"Code Bad": "purge: [...]",
"Severity": "High",
"Docs URL": "https://tailwindcss.com/docs/content-configuration"
},
{
"No": "44",
"Category": "Performance",
"Guideline": "JIT mode",
"Description": "Use JIT for faster builds and smaller bundles",
"Do": "JIT enabled (default in v3)",
"Don't": "Full CSS in development",
"Code Good": "Tailwind v3 defaults",
"Code Bad": "Tailwind v2 without JIT",
"Severity": "Medium",
"Docs URL": ""
},
{
"No": "45",
"Category": "Performance",
"Guideline": "Avoid @apply bloat",
"Description": "Use @apply sparingly",
"Do": "Direct utilities in HTML",
"Don't": "Heavy @apply usage",
"Code Good": "class='px-4 py-2 rounded'",
"Code Bad": "@apply px-4 py-2 rounded;",
"Severity": "Low",
"Docs URL": "https://tailwindcss.com/docs/reusing-styles"
},
{
"No": "46",
"Category": "Plugins",
"Guideline": "Official plugins",
"Description": "Use official Tailwind plugins",
"Do": "@tailwindcss/forms typography aspect-ratio",
"Don't": "Custom implementations",
"Code Good": "@tailwindcss/forms",
"Code Bad": "Custom form reset CSS",
"Severity": "Medium",
"Docs URL": "https://tailwindcss.com/docs/plugins"
},
{
"No": "47",
"Category": "Plugins",
"Guideline": "Custom utilities",
"Description": "Create utilities for repeated patterns",
"Do": "Custom utility in config",
"Don't": "Repeated arbitrary values",
"Code Good": "Custom shadow utility",
"Code Bad": "shadow-[0_4px_20px_rgba(0,0,0,0.1)] everywhere",
"Severity": "Medium",
"Docs URL": ""
},
{
"No": "48",
"Category": "Layout",
"Guideline": "Container Queries",
"Description": "Use @container for component-based responsiveness",
"Do": "Use @container and @lg: etc.",
"Don't": "Media queries for component internals",
"Code Good": "@container @lg:grid-cols-2",
"Code Bad": "@media (min-width: ...) inside component",
"Severity": "Medium",
"Docs URL": "https://github.com/tailwindlabs/tailwindcss-container-queries"
},
{
"No": "49",
"Category": "Interactivity",
"Guideline": "Group and Peer",
"Description": "Style based on parent/sibling state",
"Do": "group-hover peer-checked",
"Don't": "JS for simple state interactions",
"Code Good": "group-hover:text-blue-500",
"Code Bad": "onMouseEnter={() => setHover(true)}",
"Severity": "Low",
"Docs URL": "https://tailwindcss.com/docs/hover-focus-and-other-states#styling-based-on-parent-state"
},
{
"No": "50",
"Category": "Customization",
"Guideline": "Arbitrary Values",
"Description": "Use [] for one-off values",
"Do": "w-[350px] for specific needs",
"Don't": "Creating config for single use",
"Code Good": "top-[117px] (if strictly needed)",
"Code Bad": "style={{ top: '117px' }}",
"Severity": "Low",
"Docs URL": "https://tailwindcss.com/docs/adding-custom-styles#using-arbitrary-values"
},
{
"No": "51",
"Category": "Colors",
"Guideline": "Theme color variables",
"Description": "Define colors in Tailwind theme and use directly",
"Do": "bg-primary text-success border-cta",
"Don't": "bg-[var(--color-primary)] text-[var(--color-success)]",
"Code Good": "bg-primary",
"Code Bad": "bg-[var(--color-primary)]",
"Severity": "Medium",
"Docs URL": "https://tailwindcss.com/docs/customizing-colors"
},
{
"No": "52",
"Category": "Colors",
"Guideline": "Use bg-linear-to-* for gradients",
"Description": "Tailwind v4 uses bg-linear-to-* syntax for gradients",
"Do": "bg-linear-to-r bg-linear-to-b",
"Don't": "bg-gradient-to-* (deprecated in v4)",
"Code Good": "bg-linear-to-r from-blue-500 to-purple-500",
"Code Bad": "bg-gradient-to-r from-blue-500 to-purple-500",
"Severity": "Medium",
"Docs URL": "https://tailwindcss.com/docs/background-image"
},
{
"No": "53",
"Category": "Layout",
"Guideline": "Use shrink-0 shorthand",
"Description": "Shorter class name for flex-shrink-0",
"Do": "shrink-0 shrink",
"Don't": "flex-shrink-0 flex-shrink",
"Code Good": "shrink-0",
"Code Bad": "flex-shrink-0",
"Severity": "Low",
"Docs URL": "https://tailwindcss.com/docs/flex-shrink"
},
{
"No": "54",
"Category": "Layout",
"Guideline": "Use size-* for square dimensions",
"Description": "Single utility for equal width and height",
"Do": "size-4 size-8 size-12",
"Don't": "Separate h-* w-* for squares",
"Code Good": "size-6",
"Code Bad": "h-6 w-6",
"Severity": "Low",
"Docs URL": "https://tailwindcss.com/docs/size"
},
{
"No": "55",
"Category": "Images",
"Guideline": "SVG explicit dimensions",
"Description": "Add width/height attributes to SVGs to prevent layout shift before CSS loads",
"Do": "<svg class='size-6' width='24' height='24'>",
"Don't": "SVG without explicit dimensions",
"Code Good": "<svg class='size-6' width='24' height='24'>",
"Code Bad": "<svg class='size-6'>",
"Severity": "High",
"Docs URL": ""
}
]
