Tweakflux Laravel Package

Getting Started

First Steps

1. Installation

   • For global use (recommended for quick theming):

     composer global require joshcirre/tweakflux
     

   • For project-specific use:

     composer require joshcirre/tweakflux --dev
     

   • Ensure node_modules and resources/css/app.css exist (or create them).

2. Apply a Theme

   • Run the interactive picker (no args):

     tweakflux apply
     

   • Or apply a preset directly (e.g., bubblegum):

     tweakflux apply bubblegum
     

   • Output: resources/css/tweakflux-theme.css + auto-import to app.css.

3. Verify

   • Restart Vite/HMR if running (npm run dev). Changes apply instantly.

First Use Case: Quick UI Refresh

• Problem: Need to switch Flux UI’s default gray/zinc palette to a vibrant theme (e.g., bubblegum) without modifying vendor files.
• Solution:

  tweakflux apply bubblegum
  

  • Replaces all Flux component colors (buttons, cards, inputs) with pink/rose neutrals.
  • No manual CSS overrides needed.

Implementation Patterns

1. Theming Workflow

• Design → Code:

  1. Use tweakflux list to browse presets.
  2. Apply a theme (tweakflux apply {theme}).
  3. Customize further by editing resources/css/tweakflux-theme.css (or override via --no-effects flag).

• Team Collaboration:

  • Commit tweakflux-theme.css to version control.
  • Use tweakflux create {name} to scaffold a custom theme JSON file (e.g., resources/themes/custom.json).

2. Integration with Laravel

• Asset Pipeline:

  • Ensure app.css imports tweakflux-theme.css (auto-handled by the command).
  • For Laravel Mix/Vite, no additional config is needed.

• Dynamic Theming:

  • Store the active theme in config() or a database.
  • Use a middleware to apply the theme on demand:

    // app/Http/Middleware/ApplyTheme.php
    public function handle(Request $request, Closure $next) {
        $theme = config('app.theme');
        if ($theme) {
            Artisan::call('tweakflux:apply', ['theme' => $theme]);
        }
        return $next($request);
    }
    

3. Custom Themes

• Scaffold a Theme:

  tweakflux create my-brand
  

  • Generates resources/themes/my-brand.json with a template.
  • Edit the JSON to override Tailwind CSS variables (e.g., --flux-primary-500).

• Example Customization:

  // resources/themes/my-brand.json
  {
    "extends": "default",
    "colors": {
      "primary": "#2563eb", // Override Flux blue
      "neutral": "#f3f4f6"  // Light gray background
    }
  }
  

  Apply with:

  tweakflux apply my-brand
  

4. Boost Integration (Flux Pro)

• Add Boost Guidelines:

  tweakflux boost
  

  • Copies Boost-specific CSS variables (e.g., for skills/guidelines) to resources/css/boost.css.
  • Import in app.css:

    @import 'boost.css';
    

Gotchas and Tips

Pitfalls

1. Missing app.css:

   • If resources/css/app.css doesn’t exist, the command outputs the import statement manually.
   • Fix: Create app.css and add:

     @import 'tweakflux-theme.css';
     

2. Vite/HMR Not Reflecting Changes:

   • Ensure Vite is running (npm run dev).
   • Fix: Clear cache or restart the dev server.

3. Theme Conflicts:

   • Custom CSS overriding --flux-* variables may clash with TweakFlux.
   • Fix: Use !important sparingly or scope custom styles (e.g., .my-class { --flux-primary-500: #ff0000 !important; }).

4. Global vs. Per-Project:

   • Global install may cause path issues if multiple projects use different themes.
   • Tip: Prefer per-project installation for consistency.

Debugging

• Inspect Generated CSS:

  • Open resources/css/tweakflux-theme.css to verify variables.
  • Use browser dev tools to check if --flux-* properties are applied.

• Check Tailwind Config:

  • Ensure tailwind.config.js isn’t overriding Flux’s default variables:

    // tailwind.config.js
    module.exports = {
      theme: {
        extend: {
          colors: {
            // Avoid redefining Flux's --flux-* variables here
          }
        }
      }
    }
    

Extension Points

1. Custom Theme Variables:

   • Extend themes by adding new --flux-* variables in tweakflux-theme.css:

     :root {
       --flux-custom-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
     }
     

2. Post-Apply Hooks:

   • Use Laravel’s post-update-cmd in composer.json to run additional tasks after tweakflux apply:

     {
       "scripts": {
         "post-update-cmd": [
           "@php artisan tweakflux:apply bubblegum",
           "@php artisan optimize:clear"
         ]
       }
     }
     

3. Dark Mode:

   • TweakFlux supports dark mode via Tailwind’s dark() variant.
   • Tip: Use tweakflux apply bubblegum --no-effects to disable animations, then manually add dark-mode variables:

     @media (prefers-color-scheme: dark) {
       :root {
         --flux-neutral-100: #1f2937;
       }
     }
     

Pro Tips

• A/B Testing:

  • Use Laravel’s environment-based config to switch themes:

    // config/app.php
    'theme' => env('APP_THEME', 'default'),
    

  • Apply dynamically in middleware or service providers.

• Performance:

  • Critical CSS: Inline tweakflux-theme.css for above-the-fold components.
  • Purge unused variables with Tailwind’s purge config.

• Flux Pro Features:

  • For Boost, combine tweakflux boost with custom themes to align guidelines with your brand.