1#!/usr/bin/env python3
2"""
3Tailwind CSS Configuration Generator
4 
5Generate tailwind.config.js/ts with custom theme configuration.
6Supports colors, fonts, spacing, breakpoints, and plugin recommendations.
7"""
8 
9import argparse
10import json
11import sys
12from pathlib import Path
13from typing import Any, Dict, List, Optional
14 
15 
16class TailwindConfigGenerator:
17    """Generate Tailwind CSS configuration files."""
18 
19    def __init__(
20        self,
21        typescript: bool = True,
22        framework: str = "react",
23        output_path: Optional[Path] = None,
24    ):
25        """
26        Initialize generator.
27 
28        Args:
29            typescript: If True, generate .ts config, else .js
30            framework: Framework name (react, vue, svelte, nextjs)
31            output_path: Output file path (default: auto-detect)
32        """
33        self.typescript = typescript
34        self.framework = framework
35        self.output_path = output_path or self._default_output_path()
36        self.config: Dict[str, Any] = self._base_config()
37 
38    def _default_output_path(self) -> Path:
39        """Determine default output path."""
40        ext = "ts" if self.typescript else "js"
41        return Path.cwd() / f"tailwind.config.{ext}"
42 
43    def _base_config(self) -> Dict[str, Any]:
44        """Create base configuration structure."""
45        return {
46            "darkMode": ["class"],
47            "content": self._default_content_paths(),
48            "theme": {
49                "extend": {}
50            },
51            "plugins": []
52        }
53 
54    def _default_content_paths(self) -> List[str]:
55        """Get default content paths for framework."""
56        paths = {
57            "react": [
58                "./src/**/*.{js,jsx,ts,tsx}",
59                "./index.html",
60            ],
61            "vue": [
62                "./src/**/*.{vue,js,ts,jsx,tsx}",
63                "./index.html",
64            ],
65            "svelte": [
66                "./src/**/*.{svelte,js,ts}",
67                "./src/app.html",
68            ],
69            "nextjs": [
70                "./app/**/*.{js,ts,jsx,tsx}",
71                "./pages/**/*.{js,ts,jsx,tsx}",
72                "./components/**/*.{js,ts,jsx,tsx}",
73            ],
74        }
75        return paths.get(self.framework, paths["react"])
76 
77    def add_colors(self, colors: Dict[str, str]) -> None:
78        """
79        Add custom colors to theme.
80 
81        Args:
82            colors: Dict of color_name: color_value
83                   Value can be hex (#3b82f6) or variable (hsl(var(--primary)))
84        """
85        if "colors" not in self.config["theme"]["extend"]:
86            self.config["theme"]["extend"]["colors"] = {}
87 
88        self.config["theme"]["extend"]["colors"].update(colors)
89 
90    def add_color_palette(self, name: str, base_color: str) -> None:
91        """
92        Add full color palette (50-950 shades) for a base color.
93 
94        Args:
95            name: Color name (e.g., 'brand', 'primary')
96            base_color: Base color in oklch format or hex
97        """
98        # For simplicity, use CSS variable approach
99        if "colors" not in self.config["theme"]["extend"]:
100            self.config["theme"]["extend"]["colors"] = {}
101 
102        self.config["theme"]["extend"]["colors"][name] = {
103            "50": f"var(--color-{name}-50)",
104            "100": f"var(--color-{name}-100)",
105            "200": f"var(--color-{name}-200)",
106            "300": f"var(--color-{name}-300)",
107            "400": f"var(--color-{name}-400)",
108            "500": f"var(--color-{name}-500)",
109            "600": f"var(--color-{name}-600)",
110            "700": f"var(--color-{name}-700)",
111            "800": f"var(--color-{name}-800)",
112            "900": f"var(--color-{name}-900)",
113            "950": f"var(--color-{name}-950)",
114        }
115 
116    def add_fonts(self, fonts: Dict[str, List[str]]) -> None:
117        """
118        Add custom font families.
119 
120        Args:
121            fonts: Dict of font_type: [font_names]
122                   e.g., {'sans': ['Inter', 'system-ui', 'sans-serif']}
123        """
124        if "fontFamily" not in self.config["theme"]["extend"]:
125            self.config["theme"]["extend"]["fontFamily"] = {}
126 
127        self.config["theme"]["extend"]["fontFamily"].update(fonts)
128 
129    def add_spacing(self, spacing: Dict[str, str]) -> None:
130        """
131        Add custom spacing values.
132 
133        Args:
134            spacing: Dict of name: value
135                     e.g., {'18': '4.5rem', 'navbar': '4rem'}
136        """
137        if "spacing" not in self.config["theme"]["extend"]:
138            self.config["theme"]["extend"]["spacing"] = {}
139 
140        self.config["theme"]["extend"]["spacing"].update(spacing)
141 
142    def add_breakpoints(self, breakpoints: Dict[str, str]) -> None:
143        """
144        Add custom breakpoints.
145 
146        Args:
147            breakpoints: Dict of name: width
148                        e.g., {'3xl': '1920px', 'tablet': '768px'}
149        """
150        if "screens" not in self.config["theme"]["extend"]:
151            self.config["theme"]["extend"]["screens"] = {}
152 
153        self.config["theme"]["extend"]["screens"].update(breakpoints)
154 
155    def add_plugins(self, plugins: List[str]) -> None:
156        """
157        Add plugin requirements.
158 
159        Args:
160            plugins: List of plugin names
161                    e.g., ['@tailwindcss/typography', '@tailwindcss/forms']
162        """
163        for plugin in plugins:
164            if plugin not in self.config["plugins"]:
165                self.config["plugins"].append(plugin)
166 
167    def recommend_plugins(self) -> List[str]:
168        """
169        Get plugin recommendations based on configuration.
170 
171        Returns:
172            List of recommended plugin package names
173        """
174        recommendations = []
175 
176        # Always recommend animation plugin
177        recommendations.append("tailwindcss-animate")
178 
179        # Framework-specific recommendations
180        if self.framework == "nextjs":
181            recommendations.append("@tailwindcss/typography")
182 
183        return recommendations
184 
185    def generate_config_string(self) -> str:
186        """
187        Generate configuration file content.
188 
189        Returns:
190            Configuration file as string
191        """
192        if self.typescript:
193            return self._generate_typescript()
194        return self._generate_javascript()
195 
196    def _generate_typescript(self) -> str:
197        """Generate TypeScript configuration."""
198        plugins_str = self._format_plugins()
199 
200        config_json = json.dumps(self.config, indent=2)
201 
202        # Remove plugin array from JSON (we'll add it with require())
203        config_obj = self.config.copy()
204        config_obj.pop("plugins", None)
205        config_json = json.dumps(config_obj, indent=2)
206 
207        return f"""import type {{ Config }} from 'tailwindcss'
208 
209const config: Config = {{
210{self._indent_json(config_json, 1)}
211  plugins: [{plugins_str}],
212}}
213 
214export default config
215"""
216 
217    def _generate_javascript(self) -> str:
218        """Generate JavaScript configuration."""
219        plugins_str = self._format_plugins()
220 
221        config_obj = self.config.copy()
222        config_obj.pop("plugins", None)
223        config_json = json.dumps(config_obj, indent=2)
224 
225        return f"""/** @type {{import('tailwindcss').Config}} */
226module.exports = {{
227{self._indent_json(config_json, 1)}
228  plugins: [{plugins_str}],
229}}
230"""
231 
232    def _format_plugins(self) -> str:
233        """Format plugins array for config."""
234        if not self.config["plugins"]:
235            return ""
236 
237        plugin_requires = [
238            f"require('{plugin}')" for plugin in self.config["plugins"]
239        ]
240        return ", ".join(plugin_requires)
241 
242    def _indent_json(self, json_str: str, level: int) -> str:
243        """Add indentation to JSON string."""
244        indent = "  " * level
245        lines = json_str.split("\n")
246        # Skip first and last lines (braces)
247        indented = [indent + line for line in lines[1:-1]]
248        return "\n".join(indented)
249 
250    def write_config(self) -> tuple[bool, str]:
251        """
252        Write configuration to file.
253 
254        Returns:
255            Tuple of (success, message)
256        """
257        try:
258            config_content = self.generate_config_string()
259 
260            self.output_path.write_text(config_content)
261 
262            return True, f"Configuration written to {self.output_path}"
263 
264        except OSError as e:
265            return False, f"Failed to write config: {e}"
266 
267    def validate_config(self) -> tuple[bool, str]:
268        """
269        Validate configuration.
270 
271        Returns:
272            Tuple of (valid, message)
273        """
274        # Check content paths exist
275        if not self.config["content"]:
276            return False, "No content paths specified"
277 
278        # Check if extending empty theme
279        if not self.config["theme"]["extend"]:
280            return True, "Warning: No theme extensions defined"
281 
282        return True, "Configuration valid"
283 
284 
285def main():
286    """CLI entry point."""
287    parser = argparse.ArgumentParser(
288        description="Generate Tailwind CSS configuration",
289        formatter_class=argparse.RawDescriptionHelpFormatter,
290        epilog="""
291Examples:
292  # Generate TypeScript config for Next.js
293  python tailwind_config_gen.py --framework nextjs
294 
295  # Generate JavaScript config with custom colors
296  python tailwind_config_gen.py --js --colors brand:#3b82f6 accent:#8b5cf6
297 
298  # Add custom fonts
299  python tailwind_config_gen.py --fonts display:"Playfair Display,serif"
300 
301  # Add custom spacing and breakpoints
302  python tailwind_config_gen.py --spacing navbar:4rem --breakpoints 3xl:1920px
303 
304  # Add recommended plugins
305  python tailwind_config_gen.py --plugins
306        """,
307    )
308 
309    parser.add_argument(
310        "--framework",
311        choices=["react", "vue", "svelte", "nextjs"],
312        default="react",
313        help="Target framework (default: react)",
314    )
315 
316    parser.add_argument(
317        "--js",
318        action="store_true",
319        help="Generate JavaScript config instead of TypeScript",
320    )
321 
322    parser.add_argument(
323        "--output",
324        type=Path,
325        help="Output file path",
326    )
327 
328    parser.add_argument(
329        "--colors",
330        nargs="*",
331        metavar="NAME:VALUE",
332        help="Custom colors (e.g., brand:#3b82f6)",
333    )
334 
335    parser.add_argument(
336        "--fonts",
337        nargs="*",
338        metavar="TYPE:FAMILY",
339        help="Custom fonts (e.g., sans:'Inter,system-ui')",
340    )
341 
342    parser.add_argument(
343        "--spacing",
344        nargs="*",
345        metavar="NAME:VALUE",
346        help="Custom spacing (e.g., navbar:4rem)",
347    )
348 
349    parser.add_argument(
350        "--breakpoints",
351        nargs="*",
352        metavar="NAME:WIDTH",
353        help="Custom breakpoints (e.g., 3xl:1920px)",
354    )
355 
356    parser.add_argument(
357        "--plugins",
358        action="store_true",
359        help="Add recommended plugins",
360    )
361 
362    parser.add_argument(
363        "--validate-only",
364        action="store_true",
365        help="Validate config without writing file",
366    )
367 
368    args = parser.parse_args()
369 
370    # Initialize generator
371    generator = TailwindConfigGenerator(
372        typescript=not args.js,
373        framework=args.framework,
374        output_path=args.output,
375    )
376 
377    # Add custom colors
378    if args.colors:
379        colors = {}
380        for color_spec in args.colors:
381            try:
382                name, value = color_spec.split(":", 1)
383                colors[name] = value
384            except ValueError:
385                print(f"Invalid color spec: {color_spec}", file=sys.stderr)
386                sys.exit(1)
387        generator.add_colors(colors)
388 
389    # Add custom fonts
390    if args.fonts:
391        fonts = {}
392        for font_spec in args.fonts:
393            try:
394                font_type, family = font_spec.split(":", 1)
395                fonts[font_type] = [f.strip().strip("'\"") for f in family.split(",")]
396            except ValueError:
397                print(f"Invalid font spec: {font_spec}", file=sys.stderr)
398                sys.exit(1)
399        generator.add_fonts(fonts)
400 
401    # Add custom spacing
402    if args.spacing:
403        spacing = {}
404        for spacing_spec in args.spacing:
405            try:
406                name, value = spacing_spec.split(":", 1)
407                spacing[name] = value
408            except ValueError:
409                print(f"Invalid spacing spec: {spacing_spec}", file=sys.stderr)
410                sys.exit(1)
411        generator.add_spacing(spacing)
412 
413    # Add custom breakpoints
414    if args.breakpoints:
415        breakpoints = {}
416        for bp_spec in args.breakpoints:
417            try:
418                name, width = bp_spec.split(":", 1)
419                breakpoints[name] = width
420            except ValueError:
421                print(f"Invalid breakpoint spec: {bp_spec}", file=sys.stderr)
422                sys.exit(1)
423        generator.add_breakpoints(breakpoints)
424 
425    # Add recommended plugins
426    if args.plugins:
427        recommended = generator.recommend_plugins()
428        generator.add_plugins(recommended)
429        print(f"Added recommended plugins: {', '.join(recommended)}")
430        print("\nInstall with:")
431        print(f"  npm install -D {' '.join(recommended)}")
432 
433    # Validate
434    valid, message = generator.validate_config()
435    if not valid:
436        print(f"Validation failed: {message}", file=sys.stderr)
437        sys.exit(1)
438 
439    if message.startswith("Warning"):
440        print(message)
441 
442    # Validate only mode
443    if args.validate_only:
444        print("Configuration valid")
445        print("\nGenerated config:")
446        print(generator.generate_config_string())
447        sys.exit(0)
448 
449    # Write config
450    success, message = generator.write_config()
451    print(message)
452    sys.exit(0 if success else 1)
453 
454 
455if __name__ == "__main__":
456    main()
457