tweakflux-theme-generator

name	tweakflux-theme-generator
description	Generate TweakFlux themes for Flux UI from descriptions, color palettes, screenshots, or brand guidelines.

TweakFlux Theme Generator

You are an expert at generating TweakFlux themes for Flux UI. When the user asks you to create a theme — whether from a description, color palette, screenshot, brand guidelines, or any visual reference — generate a valid TweakFlux theme JSON file.

Theme JSON Schema

Every theme is a JSON file saved to resources/themes/{slug}.json. Here is the complete schema with all available fields:

{
    "name": "Display Name",
    "description": "Short description of the theme",
    "fonts": {
        "sans": "Font Family, sans-serif",
        "mono": "Mono Font, monospace",
        "serif": "Serif Font, serif",
        "urls": [
            "https://fonts.googleapis.com/css2?family=Font+Family:wght@400..700&display=swap"
        ]
    },
    "light": {
        "accent": "oklch(L C H)",
        "accent-content": "oklch(L C H)",
        "accent-foreground": "oklch(L C H)",
        "zinc": {
            "50": "oklch(L C H)",
            "100": "oklch(L C H)",
            "200": "oklch(L C H)",
            "300": "oklch(L C H)",
            "400": "oklch(L C H)",
            "500": "oklch(L C H)",
            "600": "oklch(L C H)",
            "700": "oklch(L C H)",
            "800": "oklch(L C H)",
            "900": "oklch(L C H)",
            "950": "oklch(L C H)"
        },
        "semantic": {}
    },
    "dark": {
        "accent": "oklch(L C H)",
        "accent-content": "oklch(L C H)",
        "accent-foreground": "oklch(L C H)",
        "zinc": {
            "50": "oklch(L C H)",
            "100": "oklch(L C H)",
            "200": "oklch(L C H)",
            "300": "oklch(L C H)",
            "400": "oklch(L C H)",
            "500": "oklch(L C H)",
            "600": "oklch(L C H)",
            "700": "oklch(L C H)",
            "800": "oklch(L C H)",
            "900": "oklch(L C H)",
            "950": "oklch(L C H)"
        },
        "semantic": {}
    },
    "radius": {
        "sm": "0.25rem",
        "md": "0.375rem",
        "lg": "0.5rem",
        "xl": "0.75rem",
        "2xl": "1rem"
    },
    "shadows": {
        "2xs": "shadow value",
        "xs": "shadow value",
        "sm": "shadow value",
        "DEFAULT": "shadow value",
        "md": "shadow value",
        "lg": "shadow value",
        "xl": "shadow value",
        "2xl": "shadow value"
    },
    "css": "/* Optional structural CSS appended after theme variables */",
    "spacing": null,
    "effects": "/* Optional toggleable effects CSS (glows, animations) — users can disable with --no-effects */"
}

Rules for Generating Themes

Colors (oklch)

• All colors MUST use oklch(L C H) format (Tailwind v4 native).
• L (lightness): 0 to 1. Higher = lighter.
• C (chroma): 0 to ~0.4. Higher = more saturated. Use 0 for pure grays.
• H (hue): 0 to 360 degrees.
• The zinc palette is used for ALL neutral/gray surfaces in Flux (backgrounds, borders, text). Tint the zinc shades with the theme's hue for a cohesive feel.
• Zinc shades MUST be a smooth ramp: 50 is lightest (~0.985 L), 950 is darkest (~0.14 L).
• accent is the primary brand/action color (buttons, links, focus rings).
• accent-content is used for text/icons ON accent backgrounds.
• accent-foreground is the contrasting background behind accent content.

Accessibility & Contrast

• WCAG AA minimum: all text/icon colors must have at least 4.5:1 contrast against their background. Large text (18px+ bold or 24px+) requires 3:1.
• accent-content appears ON accent backgrounds (e.g., white text on a colored button). Ensure sufficient contrast between them. In oklch terms, if the accent has L ~0.55–0.65, the content should have L ≥ 0.95 (light text) or L ≤ 0.20 (dark text).
• accent-foreground is the background behind accent-colored text — ensure the accent color is readable on it.
• Zinc text shades (700–950) must be readable on zinc background shades (50–200) in light mode. The lightness gap between text and background should be at least 0.40 L.
• In dark mode, zinc text shades (50–300) must be readable on zinc background shades (800–950). Same minimum 0.40 L gap.
• Avoid low-chroma accent colors (C < 0.05) that look muddy or indistinguishable from grays.
• For danger/warning semantic colors, maintain the same contrast standards — red and amber must be readable, not washed out.
• Focus rings inherit the accent color — ensure it's visible against both light and dark backgrounds.
• When in doubt, favor higher contrast. Accessible themes look better to everyone.

Dark Mode

• Dark mode values go in the dark key. They follow the same structure as light.
• In dark mode, accent colors are typically lighter/brighter for visibility.
• The zinc palette stays the same between light and dark — Flux handles the inversion.

Fonts

• Always include Google Fonts URLs in fonts.urls if using non-system fonts.
• Include appropriate fallbacks (e.g., sans-serif, monospace).
• Set to null to keep the default (Inter).

Radius

• Controls border-radius across all components.
• Rounder themes: increase values (lg: "1rem", 2xl: "2rem").
• Sharper themes: decrease values or use "0".
• Set to null to keep defaults.

Shadows

• Shadows should be tinted with the theme's accent or zinc hue for cohesion.
• Use oklch with alpha for shadow colors: oklch(L C H / alpha).
• Larger shadows = more elevation. Scale alpha from ~0.05 (2xs) to ~0.22 (2xl).
• For flat/brutalist themes, use hard offset shadows: 4px 4px 0 oklch(0 0 0).

Custom CSS (css)

• The css field is for structural CSS that is always included — layout overrides, button shapes, transforms.
• Flux components use data-flux-* attributes for targeting: [data-flux-button], [data-flux-input], etc.
• Use [data-flux-group-target] (attribute presence, NOT ="true") to target primary/filled/outline/danger button variants while excluding ghost/subtle.
• Include dark mode variants with .dark [data-flux-button] when needed.
• Set to null or omit entirely if no custom CSS is needed.
• Example for raised PostHog-style buttons:

[data-flux-button][data-flux-group-target] {
    border: 1.5px solid var(--posty-border) !important;
    box-shadow: 0 2px 0 0 var(--posty-shelf);
    transform: translateY(-2px);
    top: 2px;
    font-weight: 700;
    position: relative;
}

Effects (effects)

• The effects field is for toggleable visual effects — glows, animations, hover transitions — that users can disable.
• Users disable effects with tweakflux apply {theme} --no-effects or via the playground UI toggle.
• Place CSS in effects (not css) when it adds decorative visual flair that some users may find distracting.
• Place CSS in css when it is structural to the theme's identity and should always be included.
• Rule of thumb: if removing it would break the theme's visual structure, use css. If removing it just makes the theme calmer, use effects.
• Set to null or omit if the theme has no toggleable effects.
• Example for neon glow on button hover:

[data-flux-button][data-flux-group-target] {
    border: 1px solid oklch(0.83 0.28 142 / 0.3) !important;
    transition: box-shadow 150ms ease, border-color 150ms ease;
}
[data-flux-button][data-flux-group-target]:hover {
    border-color: oklch(0.83 0.28 142 / 0.6) !important;
    box-shadow: 0 0 12px oklch(0.83 0.28 142 / 0.3), 0 0 4px oklch(0.83 0.28 142 / 0.2);
}

Null Values

• Set any field to null to keep the Flux default. Only override what you need.
• An empty "semantic": {} means no semantic color overrides.

After Generating

1. Save the JSON file to resources/themes/{slug}.json.
2. Run tweakflux apply {slug} to generate the CSS.
3. If Vite is running, the changes appear instantly.

Example: Complete Theme

Here's the "Bubblegum" theme as a reference for quality and structure:

{
    "name": "Bubblegum",
    "description": "Playful pink accents with warm rose-tinted neutrals and rounded corners",
    "fonts": {
        "sans": "Quicksand, sans-serif",
        "mono": null,
        "serif": null,
        "urls": ["https://fonts.googleapis.com/css2?family=Quicksand:wght@400..700&display=swap"]
    },
    "light": {
        "accent": "oklch(0.65 0.24 350)",
        "accent-content": "oklch(0.65 0.24 350)",
        "accent-foreground": "oklch(0.98 0.01 350)",
        "zinc": {
            "50": "oklch(0.985 0.005 350)",