agentleFS
peterbamuhigirepeterbamuhigire/chwezi-dev-engine/skills/frontend-ux/tailwind-css/SKILL.md

tailwind-css

Skill31 starsChanged 19 days agoMITView on GitHub

Use when implementing or reviewing Tailwind CSS styling, responsive layouts, state variants, theme tokens, layers, grids, or build configuration. Use a design-system skill for visual direction and accessibility-wcag for formal accessibility review.

  • Installs packages

10 other projects use a version of this.

Adopted by

Most recently taken up by

The file

We split this skill into the rules it gives an agent

7 rules. 0 are common, 6 are distinctive, and 1 is very specific to this project.

  • 0

    Common

    Most of the 10 edited versions we read keep these.

  • 6

    Distinctive

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Use the links and companion skills already referenced in this file when deeper context is needed.

    line 31
  2. Distinctive:

    When repeating the same set of utility classes across many elements, extract to a component class.

    line 185
  3. Very specific:

    Rule: Use @apply sparingly — prefer utility classes in JSX components.

    line 214
  4. Distinctive:

    Use it for global base styles (headings, links) and frequently repeated component patterns.

    line 215
  5. Distinctive:

    Add classes that may not appear in scanned files (e.g., dynamically constructed):

    line 291
  6. Distinctive:

    Read and search markup, configuration, and tokens first.

    line 457
  7. Distinctive:

    If the build or rendered interface is unavailable, provide exact changes and mark purge, contrast, responsive, and interaction-state checks …

    line 461

“Common” is measured: kept by at least 6 in 10 of the 10 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Tailwind CSS

Acknowledgement: Shared by Peter Bamuhigire, techguypeter.com, +256 784 464178.

<!-- dual-compat-start -->

Chwezi Product Excellence Standard (mandatory)

Any Chwezi app or system UI work (effective 01 Nov 2026) MUST follow the Chwezi Product Excellence Standard in chwezi-design-engine (resolve via the engine-routing table; never hard-code the path): doctrine/product-excellence-standard.md and skill skills/00-cross-cutting-ops-qa-a11y/chwezi-product-excellence-standard. Engineering gates: product-excellence-engineering-gates.md. Generate the Tailwind theme and CSS custom properties from the single token source (PX-TOKEN-008). Full amounts take the currency's ISO 4217 minor unit (UGX 0 decimals), which overrides the fixed two-decimal full formatter in references/house-style-web.md. Where this skill and the standard differ, the standard wins.

Use When

  • Tailwind CSS v3 utility-first styling — setup, responsive design, dark mode, event/state modifiers, tailwind.config.js customization (colors, spacing, screens, plugins), @apply and @layer directives, flexbox/grid classes, and best practices. Use...

Evidence Produced

CategoryArtifactFormatExample
UX qualityTheme + responsive auditMarkdown doc reviewing tokens, breakpoint coverage, and dark-mode paritydocs/web/tailwind-theme-audit.md

References

  • Use the links and companion skills already referenced in this file when deeper context is needed.
  • references/house-style-web.md: Chwezi business-app house style as CSS tokens, Tailwind theme mapping, tabular amount utilities, components, reduced motion and CI guardrails.
<!-- dual-compat-end -->

Utility-first CSS framework. Style in HTML — no custom CSS required.

Setup

# Next.js (includes Tailwind automatically)
npx create-next-app@latest my-app --typescript --tailwind

# Standalone (any project)
npm install -D tailwindcss postcss autoprefixer
npx tailwindcss init -p

tailwind.config.js (minimum):

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./src/**/*.{html,js,jsx,ts,tsx}'],
  theme: { extend: {} },
  plugins: [],
};

input.css:

@tailwind base;
@tailwind components;
@tailwind utilities;

CDN (prototyping only):

<script src="https://cdn.tailwindcss.com"></script>

Core Philosophy

Tailwind replaces custom CSS with composable utility classes directly on elements.

<!-- Traditional CSS approach -->
<div class="mainBlock">…</div>

<!-- Tailwind utility-first approach -->
<div class="bg-gray-500 p-2 w-72 rounded border border-gray-900 flex">…</div>

Utility classes vs inline styles:

  • Utility classes are part of a design system — reusable, consistent
  • Utility classes support responsive breakpoints and state variants
  • Utility classes handle hover, focus, dark mode — inline styles cannot

Responsive Design

Mobile-first breakpoints. Apply a prefix to target that breakpoint and above.

PrefixMin-widthEquivalent CSS
(none)0pxAlways applies
sm:640px@media (min-width: 640px)
md:768px@media (min-width: 768px)
lg:1024px@media (min-width: 1024px)
xl:1280px@media (min-width: 1280px)
2xl:1536px@media (min-width: 1536px)
<!-- Pink on mobile, red sm+, green md+, gray lg+, blue xl+ -->
<div class="bg-pink-500 sm:bg-red-500 md:bg-green-500 lg:bg-gray-500 xl:bg-blue-500">

Target a range (apply only between breakpoints):

<div class="sm:max-lg:bg-red-500">  <!-- only sm to lg -->
<div class="sm:max-md:flex">        <!-- flex only at sm width -->

Event and State Modifiers

Format: {modifier}:{utility-class}

<!-- hover, active, focus -->
<button class="bg-green-300 hover:bg-blue-400 active:bg-red-500">Click</button>

<!-- Multiple on same event -->
<button class="hover:bg-green-500 hover:text-white">Hover me</button>

<!-- focus -->
<input class="focus:outline-none focus:ring-2 focus:ring-blue-500" />

<!-- disabled -->
<input disabled class="disabled:bg-gray-200 disabled:cursor-not-allowed" />

<!-- required / invalid -->
<input required class="required:bg-red-50 invalid:border-red-500" />

<!-- first-child / last-child -->
<div class="first:font-bold last:italic">…</div>

<!-- odd / even children -->
<div class="odd:bg-green-100 even:bg-blue-100">…</div>

<!-- group — parent hover affects children -->
<div class="group">
  <p class="text-gray-600 group-hover:text-black">Text changes on parent hover</p>
</div>

Dark Mode

System-controlled (default):

<div class="bg-white dark:bg-gray-900 text-black dark:text-white">

Manual toggle (class-based):

// tailwind.config.js
module.exports = { darkMode: 'class', ... }
<!-- Add/remove 'dark' class on root element via JS -->
<html id="root" class="dark">
  <div class="bg-white dark:bg-gray-900">…</div>
</html>
// Toggle dark mode
document.getElementById('root').classList.toggle('dark');

Style Reuse — @apply and @layer

When repeating the same set of utility classes across many elements, extract to a component class.

/* input.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

@layer components {
  .btn-primary {
    @apply px-4 py-2 bg-blue-600 text-white rounded hover:bg-blue-700 transition;
  }
  .card {
    @apply bg-white rounded-xl shadow-md p-6;
  }
}

@layer base {
  h1 { @apply text-2xl font-bold; }
  h2 { @apply text-xl font-semibold; }
  a  { @apply text-blue-600 underline; }
}
<button class="btn-primary">Save</button>
<div class="card">…</div>

Rule: Use @apply sparingly — prefer utility classes in JSX components. Use it for global base styles (headings, links) and frequently repeated component patterns.


tailwind.config.js — Customisation

Custom Colors

module.exports = {
  theme: {
    extend: {
      colors: {
        'brand':  '#1DA1F2',
        'brand-dark': '#0c85d0',
        'silver': '#C0C0C0',
      },
    },
  },
};

Usage: bg-brand, text-silver

Color with shades:

colors: {
  'primary': {
    50:  '#eff6ff',
    100: '#dbeafe',
    500: '#3b82f6',
    900: '#1e3a5f',
  },
}

Usage: bg-primary-500, text-primary-900

Arbitrary color (no config needed): bg-[#1DA1F2]

Custom Screens (Breakpoints)

theme: {
  screens: {
    'sm': '640px', 'md': '768px', 'lg': '1024px',
    'xl': '1280px', '2xl': '1536px',
    '3xl': '1800px',          // custom extra-large
    'mobile': '480px',        // custom named breakpoint
  },
},

Custom Spacing

theme: {
  extend: {
    spacing: {
      '18': '4.5rem',
      '72': '18rem',
      '84': '21rem',
    },
  },
},

Disable Core Plugin

module.exports = { corePlugins: { container: false, preflight: false } }

Class Safelisting

Add classes that may not appear in scanned files (e.g., dynamically constructed):

module.exports = { safelist: ['bg-red-500', 'text-3xl', 'lg:text-4xl'] }

Plugins

npm install @tailwindcss/typography @tailwindcss/forms
plugins: [
  require('@tailwindcss/typography'),   // .prose classes for rich text
  require('@tailwindcss/forms'),        // styled form controls
],

Usage: <article class="prose lg:prose-xl">, <input class="form-input" />


Layout Quick Reference

<!-- Container (centers content at breakpoint) -->
<div class="container mx-auto px-4">

<!-- Flexbox -->
<div class="flex items-center justify-between gap-4">
<div class="flex flex-col gap-2">
<div class="flex flex-wrap">

<!-- Grid -->
<div class="grid grid-cols-3 gap-6">
<div class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-4 gap-4">
<div class="col-span-2">             <!-- span 2 columns -->
<div class="grid grid-cols-[repeat(auto-fit,minmax(min(18rem,100%),1fr))] gap-[clamp(1rem,2vw,2rem)]">

<!-- Position -->
<div class="relative">
  <div class="absolute top-0 right-0">badge</div>
</div>

<!-- Overflow -->
<div class="overflow-hidden">
<div class="overflow-x-auto">

Typography Quick Reference

<!-- Font size: text-xs text-sm text-base text-lg text-xl text-2xl … text-9xl -->
<h1 class="text-4xl font-bold tracking-tight">
<p class="text-base text-gray-600 leading-relaxed">

<!-- Font weight -->
<!-- font-thin font-light font-normal font-medium font-semibold font-bold font-extrabold -->

<!-- Text color: text-{color}-{shade} -->
<p class="text-gray-900 dark:text-gray-100">

<!-- Text align -->
<p class="text-center">  <p class="text-right">

<!-- Truncate long text -->
<p class="truncate">     <!-- single line -->
<p class="line-clamp-3"> <!-- 3 lines then … -->
<h1 class="text-[clamp(2.25rem,6vw,5rem)] leading-[1.05]"> <!-- fluid bounded heading -->

Spacing, Sizing, Effects

<!-- Padding/Margin: p-{n} px-{n} py-{n} pt/pr/pb/pl-{n} -->
<!-- n = 0,1,2,3,4,5,6,8,10,12,16,20,24,32,40,48,64 (0.25rem each) -->
<div class="p-4 mx-auto mt-8">

<!-- Width/Height -->
<div class="w-full max-w-2xl h-screen min-h-0">
<img class="w-16 h-16 object-cover rounded-full">

<!-- Borders -->
<div class="border border-gray-200 rounded-lg">
<div class="border-2 border-blue-500 rounded-xl ring-2 ring-blue-300">

<!-- Shadow -->
<div class="shadow shadow-lg shadow-xl shadow-2xl">

<!-- Opacity -->
<div class="opacity-50 hover:opacity-100 transition">

<!-- Transitions -->
<button class="transition duration-200 ease-in-out hover:scale-105">

Common Component Patterns

<!-- Button variants -->
<button class="px-4 py-2 bg-blue-600 text-white rounded-lg hover:bg-blue-700 
               active:bg-blue-800 transition disabled:opacity-50 disabled:cursor-not-allowed">
  Primary
</button>

<!-- Card -->
<div class="bg-white dark:bg-gray-800 rounded-2xl shadow-md p-6 hover:shadow-lg transition">

<!-- Badge -->
<span class="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs 
             font-medium bg-green-100 text-green-800">
  Active
</span>

<!-- Input -->
<input class="w-full px-3 py-2 border border-gray-300 rounded-lg 
              focus:outline-none focus:ring-2 focus:ring-blue-500 focus:border-transparent
              dark:bg-gray-700 dark:border-gray-600 dark:text-white" />

<!-- Responsive nav (mobile stack → desktop row) -->
<nav class="flex flex-col md:flex-row gap-2 md:gap-6">

Best Practices

RuleReason
Never include CSS files in content configCauses false class detection
Use complete class names (bg-red-500 not bg-${color}-500)Dynamic strings aren't scanned
Prefer @layer components over inline @apply in JSXKeeps HTML clean for one-off reuse
Use extend not override in themePreserve default utilities
Use framework components (React, Vue) instead of HTML loopsClass strings in components = clean repetition
Check Tailwind v3 docs for new classesClasses added/renamed across versions
Use arbitrary values for mathematical relationships, not random decorationclamp(), minmax(), calc(), aspect-ratio, and ch preserve proportion and responsiveness

Source: Bhat — Ultimate Tailwind CSS Handbook (BPB, 2023)

Decision rules

ConditionChoiceFailure avoided
Value is a reusable product tokenAdd a named theme tokenScattered arbitrary values
Value is a one-off mathematical constraintUse an arbitrary valuePolluting the theme
Utility sequence repeats with stable semanticsExtract a componentCopy-paste drift

Anti-Patterns

  • Constructing dynamic fragments such as bg-${color}-500. Fix: map to complete class strings.
  • Replacing the default theme accidentally. Fix: extend it unless the design system owns every token.
  • Using @apply for every component. Fix: extract only stable repetition.
  • Choosing arbitrary spacing without rationale. Fix: use tokens or a documented proportional constraint.
  • Styling only the default state. Fix: cover focus, disabled, error, loading, empty, and dark states.

Capability contract

Read and search markup, configuration, and tokens first. Edit only when authorised; execute the existing build, lint, responsive checks, and accessibility checks when available.

Degraded mode

If the build or rendered interface is unavailable, provide exact changes and mark purge, contrast, responsive, and interaction-state checks as unverified.

Inputs

ArtefactRequired?Purpose
Design tokens, responsive layouts, component states, and Tailwind versionyesMap design to maintainable utilities

Outputs

  • Produce Tailwind implementation with responsive, state, accessibility, and consistency evidence.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.