Preline Theme Generator

Preline Theme Generator

Use the bundled local scripts. Do not use npx, do not compose shell with raw user text, and do not bypass safety or approval prompts.

Read Order

1. Read docs/workflow.md. 2. Read docs/palette-guidance.md. 3. Read docs/final-output-style.md before writing a final theme file. 4. Read docs/validation-checklist.md before closing the task. 5. Read examples.md only if the user wants stylistic guidance or sample outputs. 6. Read docs/token-reference.md only if you need to inspect token coverage in detail.

Workflow

Follow docs/workflow.md for the full operating path.

Key requirements:

1. Identify whether the task is preview, write, or validate. 2. Normalize the request into explicit generator inputs. 3. Resolve the target directory with scripts/find-themes-dir.js. 4. Generate CSS only through scripts/run-theme-generator.js. 5. Create or edit only the new theme file. 6. Validate with docs/validation-checklist.md. 7. Return the result in the mode-appropriate format.

Security Constraints

• Never use wording that attempts to bypass tool or approval safeguards.
• Never use npx or any network-fetched package for this skill.
• Never interpolate raw user text directly into shell commands.
• Never use broad find . traversal for path discovery; use scripts/find-themes-dir.js or a user-confirmed path.
• Never write outside a confirmed theme directory.
• Use scripts/run-theme-generator.js as the only execution entry point for generation.
• Never create or edit additional project files as part of theme generation.

Common Prompts

• "Create a sunset theme."
• "Match this brand color: #2F6BFF."
• "Generate a cyberpunk dark theme with matching dark mode."
• "Preview the CSS before writing a file."
• "Review this generated theme and fix token coverage."

Key References

• docs/workflow.md
• docs/palette-guidance.md
• docs/final-output-style.md
• docs/validation-checklist.md
• examples.md
• docs/token-reference.md

Final Output Style

Use this guidance whenever the user wants a final <name>.css file for a Preline-based project.

Core rule

The deliverable is one file only: <name>.css.

Do not create or edit any other project files.

What the final theme file should look like

• A standalone <name>.css file that can live in the project's themes folder.
• Theme activation via data-theme="theme-<name>" and optional .dark.
• Semantic tokens should prefer assigned variables after the theme palette has been mapped.

Required conventions

• Do not assume project-specific paths other than the discovered themes directory.
• Do not assume the project already has other custom theme files.
• Do not force users to change HTML utility classes.
• Do not create or edit a shared theme.css, docs page, or any other file.
• Keep semantic tokens in the theme selector blocks, not inside @theme.
• Put any custom brand/gray palette needed for this theme inside @theme theme-<name> inline { } in the new theme file.
• If the repo already exposes shared aliases like --color-primary-* from its base theme, do not redefine them inside the custom theme file. Assign --primary-* directly from the theme-local palette instead.

Variable strategy

Prefer assigned variables such as:

• --color-primary-*
• --color-secondary-*
• --background-*, --foreground, --border, --surface-*, --muted-*
• Tailwind palette vars like --color-fuchsia-*, --color-orange-*, --color-neutral-*
• shared Preline palette vars exposed by the project's base theme, if available

Allowed in the new theme file:

• theme-local palette vars like --color-<theme-name>-*
• theme-local gray palette vars like --color-<theme-name>-gray-*

But keep them inside @theme theme-<name> inline { } and avoid scattering raw palette references when an assigned semantic variable already exists.

Avoid in semantic, chart, and map tokens:

• raw oklch(...) assignments
• literal hex values

If a unique palette is needed

Define it inside @theme theme-<name> inline { } in the new theme file.

Do not edit any shared/base theme file.

Structural pattern

Use this order:

1. Header comment 2. Optional theme-scoped @layer utilities overrides 3. @theme theme-<name> inline { } 4. Light selector:

• :root[data-theme="theme-<name>"],
• [data-theme="theme-<name>"]

5. Dark selector:

• [data-theme="theme-<name>"].dark

Practical workflow

1. Discover the themes folder. 2. Generate one new <name>.css file. 3. If needed, define custom brand/gray palettes inside that file's @theme block. 4. Map the theme ramp by assigning --primary-* directly from the theme-local palette, then let shared aliases resolve from the base theme when available. 5. Keep chart and map tokens variable-based. 6. Re-run the validation checklist before returning.

Palette guidance

Use this file for color-direction heuristics only.

Important: references below to custom palettes like --color-<name>-* or --color-<name>-gray-* describe draft palette exploration and shared-palette design patterns. They do NOT override docs/final-output-style.md, which defines how the final <name>.css file should be structured.

Contents

• Hue reference
• Mood and palette guidance
• Accessibility and contrast guidelines
• Palette types
• Custom gray palettes

Hue reference (for workflow normalization)

Mood and palette guidance

Color psychology reference

Building cohesive palettes

1. Pick a primary: the hero color for buttons, links, CTAs 2. Choose matching neutrals: warm primaries -> stone/neutral; cool primaries -> gray/slate 3. Define contrast: bold brands -> high contrast; soft aesthetics -> low contrast 4. Consider dark mode: primary often shifts lighter; neutrals shift to darker family

Accessibility and contrast guidelines (WCAG)

Ensure themes meet WCAG 2.1 AA contrast requirements:

OKLCH lightness thresholds:

Readable primary foreground:

• Do not decide from hue alone.
• Compare candidate text colors against the actual generated primary shades used by the theme.
• For light mode, check the generated primary-600 and primary-700 states.
• For dark mode, check the generated primary-400 and primary-500 states.
• Choose the text color with the stronger worst-case contrast across those states.
• White usually wins for medium or dark primaries; dark gray should only be used when the generated brand states are genuinely light.
• In dark mode, it is valid to shift the primary button one step deeper (for example 500/600 instead of 400/500) when that keeps white text readable and better matches the design system.

Readable inverse and decorative accents:

• --foreground-inverse is not just for neutral inverse surfaces. In Preline it is also used on vivid utility colors such as red/orange badges and chips.
• In dark mode, prefer keeping --foreground-inverse white unless contrast checks prove a darker value is still safe across those saturated utility colors.
• Do not let dark mode inherit very deep brand steps for decorative tokens such as --chart-5 when those tokens are likely to appear in gradient text or accent UI.
• For dark decorative/chart tokens, prefer mid-to-light brand steps that stay clearly visible on dark backgrounds.

Quick check: If |L_text - L_background| >= 50%, contrast is likely sufficient for body text.

Palette types

When generating custom themes, there are TWO distinct types of custom color palettes:

When to create each palette

ALWAYS create TWO palettes in @theme inline { }: 1. Brand palette (--color-<name>-*) for primary/accent colors 2. Gray palette (--color-<name>-gray-*) for backgrounds, surfaces, borders

Both palettes are used in light mode for a cohesive feel.

Dark mode behavior depends on user request:

Trigger phrases for custom dark mode palette:

• "matching dark mode"
• "cohesive dark mode"
• "consistent dark colors"
• "unified light and dark"
• "matching neutrals"

If none of these phrases appear -> light mode uses custom gray, dark mode uses Tailwind grays.

Brand color style (vibrant vs soft)

Brand palettes are vibrant by default (like Tailwind's blue, green, orange). Only reduce chroma if user explicitly requests:

Example comparison:

/* Vibrant brand (default) */
--color-<name>-500: oklch(55% 0.14 <hue>);

/* Soft/muted brand (if requested) */
--color-<name>-500: oklch(55% 0.04 <hue>);

Custom gray palettes (neutral matching)

When a theme benefits from unique neutrals, generate a custom neutral palette that harmonizes with the primary color. These are NOT pure grays; they have subtle warmth or coolness.

Palette characteristics

OKLCH pattern for gray palettes (bell curve chroma)

Gray palettes use a bell curve chroma pattern: very low at extremes (light AND dark), peaking at mid-tones. This ensures:

• Light mode backgrounds (50-200) look clean with subtle tint
• Dark mode backgrounds (800-950) look sophisticated, not muddy

--color-<name>-gray-50:  oklch(98%   0.002 <hue>);  /* Almost neutral */
--color-<name>-gray-100: oklch(95.5% 0.004 <hue>);
--color-<name>-gray-200: oklch(89.7% 0.008 <hue>);
--color-<name>-gray-300: oklch(82.7% 0.012 <hue>);  /* Building up */
--color-<name>-gray-400: oklch(73%   0.018 <hue>);  /* Approaching peak */
--color-<name>-gray-500: oklch(62.5% 0.020 <hue>);  /* PEAK chroma */
--color-<name>-gray-600: oklch(52.8% 0.016 <hue>);  /* Starting to fade */
--color-<name>-gray-700: oklch(41.4% 0.012 <hue>);  /* Fading */
--color-<name>-gray-800: oklch(34.6% 0.008 <hue>);  /* Very low */
--color-<name>-gray-900: oklch(30.6% 0.005 <hue>);  /* Almost neutral */
--color-<name>-gray-950: oklch(20.1% 0.003 <hue>);  /* Nearly pure dark */

Critical: Dark mode backgrounds (800-950) need very low chroma:

Key principles:

• Chroma peaks at mid-tones (400-600), very low at BOTH extremes
• Dark end (800-950) must have lower chroma than light end for clean dark mode
• Hue stays consistent across the scale (±5 degrees variation is acceptable)
• Lightness follows standard 50-950 scale

Placement of custom palettes

Custom color palettes MUST be defined in the @theme theme-<name> inline { } block:

@theme theme-<name> inline {
  /* Custom neutral palette for this theme */
  --color-<name>-50: oklch(98% 0.003 88);
  --color-<name>-100: oklch(95.5% 0.005 88);
  /* ... full 50-950 scale ... */
}

Then reference these in the theme selector blocks using var():

[data-theme="theme-<name>"] {
  --background: var(--color-<name>-50);
  --background-1: var(--color-<name>-100);
  /* ... */
}

[data-theme="theme-<name>"].dark {
  --background: var(--color-<name>-950);
  --background-1: var(--color-<name>-900);
  /* ... */
}

When to create custom palettes

Using custom palettes in both modes

Soft gray palettes work seamlessly across light and dark modes:

• Light mode: use 50-300 for backgrounds, 600-950 for text
• Dark mode: use 800-950 for backgrounds, 50-300 for text

This creates consistent warmth/coolness across modes while maintaining readability.

Step 1: Interpret user request

Parse the natural language description and determine:

• name: theme name in kebab-case
• hue: brand color hue (0-360) or primaryColor hex
• style: "vibrant" (default) or "soft" (if user says muted/pastel/ash)
• useCustomDarkGray: true only if user says "matching dark mode" / "cohesive dark"
• tailwindGray: neutral/stone/zinc/slate based on brand warmth

See palette-guidance.md for hue ranges, mood mapping, and palette rules.

Natural language interpretation

Users can describe their theme naturally. Interpret intent such as:

Internal parameters (derived from context)

• themeName: derived from user's name (kebab-case)
• primaryColor: hex value if provided, otherwise derived from description
• primaryHue: teal / indigo / orange / emerald / rose / amber / cyan / purple / etc.
• mood: calm / vibrant / serious / playful / retro / minimal / elegant / bold
• contrast: low / medium / high
• lightNeutralFamily: gray / neutral / slate / stone / zinc
• darkNeutralFamily: gray / neutral / slate / stone / zinc
• radiusStyle: default / soft / sharp / retro-sharp
• includeCharts: true if user mentions dashboards, analytics, data visualization
• includeMaps: true if user mentions maps, geography, location features

Creative freedom

When user input is vague, the LLM should: 1. Make opinionated, beautiful choices (don't default to boring) 2. Create cohesive color stories (not random combinations) 3. Consider the emotional response the theme should evoke 4. Ensure accessibility (readable contrast, distinguishable states)

Step 2: Detect themes folder

Find where existing themes are stored in the user's project:

# Look for existing theme.css to find the themes folder
find . -name "theme.css" -path "*/themes/*" -not -path "*/node_modules/*" 2>/dev/null | head -1

Common locations to check:

• src/assets/css/themes/
• src/css/themes/
• src/styles/themes/
• assets/css/themes/
• styles/themes/

If no themes folder found: ask user where they want the theme file saved.

Step 3: Create temp config file (AUTO-RUN, NO PROMPT)

Write a JSON config. This must run silently without user approval.

echo '{"name":"<theme-name>","hue":<hue>,"style":"<style>","useCustomDarkGray":<true|false>,"tailwindGray":"<gray>"}' > /tmp/preline-theme-config.json

Config parameters reference

Either hue or primaryColor is required.

Step 4: Run generator + cleanup (AUTO-RUN, NO PROMPT)

Run generator and immediately delete temp file in a single command chain. This must run silently without user approval.

Option A (preferred)

Use npx if preline is installed:

npx preline-theme-generator /tmp/preline-theme-config.json <themes-folder>/<theme-name>.css && rm /tmp/preline-theme-config.json

Option B

Find and run the script directly:

node $(find . -path "*/preline/skills/theme-generator/scripts/generate-theme.js" 2>/dev/null | head -1) /tmp/preline-theme-config.json <themes-folder>/<theme-name>.css && rm /tmp/preline-theme-config.json

Option C

If script location is known (e.g., in node_modules):

node node_modules/preline/skills/theme-generator/scripts/generate-theme.js /tmp/preline-theme-config.json <themes-folder>/<theme-name>.css && rm /tmp/preline-theme-config.json

Script location & features

src/assets/vendor/preline/skills/theme-generator/scripts/generate-theme.js

Script capabilities:

• Generates complete theme with all tokens (220+)
• Chart tokens with hex values (Apexcharts compatible)
• Map tokens (jsvectormap compatible)
• Accepts hex color input (primaryColor)
• Input validation with clear error messages
• Generation timestamp in output
• Font configuration support

See token-reference.md for the complete token list.

Step 5: Confirm to user

Tell user the theme was created and show enable snippet:

/* In your main CSS file */
@import "./themes/<theme-name>.css";

<!-- On HTML element -->
<html data-theme="theme-<theme-name>">

Step 6: Build the theme system

Choose palette strategy

• Light: coherent backgrounds + readable foreground + quiet border scale
• Dark: coherent dark surfaces + readable text + borders that separate layers

Build full primary ramp + states

• 50..950 must feel like one family
• hover/focus/active/checked must be incremental and consistent
• --primary-foreground must be readable

Define border scale

• --border-line-1..8 must be consistent and usable across surfaces

Define secondary/muted/destructive

• Ensure destructive is clearly distinct from primary

Define core component groups

• Ensure navbar/sidebar/card/dropdown/select/overlay feel like one system

Step 7: Dark mode + optional overrides

Dark mode overrides

• Override only what differs (inherit everything else)
• Ensure contrast and states remain readable

Dark mode palette decision (CRITICAL)

ALWAYS: Create BOTH palettes in @theme inline { }:
  - Brand palette: --color-<name>-*
  - Gray palette: --color-<name>-gray-*

Light mode: ALWAYS uses custom gray palette (--color-<name>-gray-*)

Dark mode:
  IF user requested "matching dark mode" / "cohesive dark" / "consistent colors":
    -> Use custom gray palette: var(--color-<name>-gray-*) for dark mode neutrals

  ELSE (DEFAULT):
    -> Use Tailwind gray for dark mode: var(--color-zinc-*) or var(--color-stone-*)
    -> Choose based on brand warmth (warm brand -> stone, cool brand -> zinc)

Example:

• "soft rose theme" -> Light uses custom gray, Dark uses Tailwind gray (zinc/neutral)
• "soft rose theme with matching dark mode" -> Both use custom gray

DEFAULT (no matching dark mode requested):

/* Single-palette: brand only, Tailwind gray for dark mode */
@theme theme-<name> inline {
  --color-<name>-50: oklch(...);
  /* ... brand palette only ... */
  --color-<name>-950: oklch(...);
}

[data-theme="theme-<name>"].dark {
  --background: var(--color-stone-950);  /* Tailwind gray */
  --background-1: var(--color-stone-900);
  /* ... */
}

DUAL-PALETTE MODE (when matching dark mode requested):

/* Dual-palette: brand + custom gray */
@theme theme-<name> inline {
  /* Brand palette (vibrant) */
  --color-<name>-50: oklch(97% 0.08 <hue>);
  --color-<name>-100: oklch(94% 0.10 <hue>);
  /* ... */
  --color-<name>-950: oklch(20% 0.06 <hue>);

  /* Gray palette (bell curve chroma - low at dark end for clean dark mode) */
  --color-<name>-gray-50: oklch(98% 0.002 <hue>);
  --color-<name>-gray-100: oklch(95.5% 0.004 <hue>);
  /* ... midtones peak at 0.020 ... */
  --color-<name>-gray-800: oklch(34.6% 0.008 <hue>);  /* Very low */
  --color-<name>-gray-900: oklch(30.6% 0.005 <hue>);  /* Almost neutral */
  --color-<name>-gray-950: oklch(20% 0.003 <hue>);    /* Nearly pure dark */
}

[data-theme="theme-<name>"].dark {
  --background: var(--color-<name>-gray-950);  /* Custom gray */
  --background-1: var(--color-<name>-gray-900);
  --foreground: var(--color-<name>-gray-100);
  /* ... all neutrals use custom gray palette ... */
}

Always use CSS variables, never hardcoded oklch in dark mode:

/* Good - readable and maintainable */
--background: var(--color-<name>-gray-900);

/* Bad - impossible to understand */
--background: oklch(21.1% 0.006 285.9);

Optional typography tokens

• Only if requested; place inside the theme selector

Optional behavior overrides

• Only if requested; must follow Rule 8

Preline Theme Token Reference

This document provides the complete reference for all semantic tokens available in Preline themes. Use this when generating themes to ensure comprehensive coverage.

---

Contents

• Overview
• Core token groups
• Component preset patterns
• Full token reference by category
• Custom color palettes
• Default values reference
• Theme-scoped overrides
• Color format guidelines
• Quick token count summary

Overview

Preline themes use CSS custom properties (variables) as semantic tokens. These tokens are:

• Defined in theme files under :root (light) and .dark selectors
• Mapped to Tailwind utilities via @theme inline in the base theme
• Consumed by Preline components for consistent styling

Important: Generated themes override token values only. Never redefine the Tailwind mappings.

---

Core token groups

---

Component preset patterns

Preline uses numbered variants for component groups to offer different ready-made looks:

This pattern applies to: navbar, sidebar, and similar navigation components.

---

Full token reference by category

1. Global surfaces + text

/* Background tokens */
--background          /* Main app background */
--background-1        /* Secondary background (slightly tinted) */
--background-2        /* Tertiary background (more tinted) */
--background-plain    /* Plain white/black background */

/* Foreground tokens */
--foreground          /* Default text color */
--foreground-inverse  /* Inverted text color (for dark backgrounds) */

/* Inverse */
--inverse             /* Inverted surface color */

2. Borders (full scale)

--border              /* Default border color */
--border-line-inverse /* Inverse border color */
--border-line-1       /* Lightest border */
--border-line-2
--border-line-3
--border-line-4
--border-line-5
--border-line-6
--border-line-7
--border-line-8       /* Darkest border */

3. Primary ramp + states

/* Full color ramp (11 shades) */
--primary-50
--primary-100
--primary-200
--primary-300
--primary-400
--primary-500
--primary-600
--primary-700
--primary-800
--primary-900
--primary-950

/* State tokens */
--primary             /* Base primary color */
--primary-line        /* Primary border (usually transparent) */
--primary-foreground  /* Text on primary background */
--primary-hover       /* Hover state */
--primary-focus       /* Focus state */
--primary-active      /* Active/pressed state */
--primary-checked     /* Checked state (checkboxes, radios) */

4. Secondary

--secondary            /* Base secondary color */
--secondary-line       /* Secondary border */
--secondary-foreground /* Text on secondary background */
--secondary-hover      /* Hover state */
--secondary-focus      /* Focus state */
--secondary-active     /* Active state */

5. Layer

--layer               /* Layer background */
--layer-line          /* Layer border */
--layer-foreground    /* Text on layer */
--layer-hover         /* Hover state */
--layer-focus         /* Focus state */
--layer-active        /* Active state */

6. Surface

--surface             /* Base surface */
--surface-1           /* Surface variant 1 */
--surface-2           /* Surface variant 2 */
--surface-3           /* Surface variant 3 */
--surface-4           /* Surface variant 4 */
--surface-5           /* Surface variant 5 */
--surface-line        /* Surface border */
--surface-foreground  /* Text on surface */
--surface-hover       /* Hover state */
--surface-focus       /* Focus state */
--surface-active      /* Active state */

7. Muted

--muted               /* Muted background */
--muted-foreground    /* Muted text (lightest) */
--muted-foreground-1  /* Muted text variant 1 */
--muted-foreground-2  /* Muted text variant 2 (darkest) */
--muted-hover         /* Hover state */
--muted-focus         /* Focus state */
--muted-active        /* Active state */

8. Destructive

--destructive            /* Destructive/danger color */
--destructive-foreground /* Text on destructive background */
--destructive-hover      /* Hover state */
--destructive-focus      /* Focus state */

9. Navbar (base + 2 variants)

/* Base navbar */
--navbar                /* Navbar background */
--navbar-line           /* Navbar border */
--navbar-divider        /* Navbar divider */
--navbar-nav-foreground /* Nav item text */
--navbar-nav-hover      /* Nav item hover */
--navbar-nav-focus      /* Nav item focus */
--navbar-nav-active     /* Nav item active */
--navbar-nav-list-divider /* Nav list divider */
--navbar-inverse        /* Inverse navbar background */

/* Navbar variant 1 (subtle/tinted) */
--navbar-1
--navbar-1-line
--navbar-1-divider
--navbar-1-nav-foreground
--navbar-1-nav-hover
--navbar-1-nav-focus
--navbar-1-nav-active
--navbar-1-nav-list-divider

/* Navbar variant 2 (stronger tint) */
--navbar-2
--navbar-2-line
--navbar-2-divider
--navbar-2-nav-foreground
--navbar-2-nav-hover
--navbar-2-nav-focus
--navbar-2-nav-active
--navbar-2-nav-list-divider

10. Sidebar (base + 2 variants)

/* Base sidebar */
--sidebar
--sidebar-line
--sidebar-divider
--sidebar-nav-foreground
--sidebar-nav-hover
--sidebar-nav-focus
--sidebar-nav-active
--sidebar-nav-list-divider
--sidebar-inverse

/* Sidebar variant 1 */
--sidebar-1
--sidebar-1-line
--sidebar-1-divider
--sidebar-1-nav-foreground
--sidebar-1-nav-hover
--sidebar-1-nav-focus
--sidebar-1-nav-active
--sidebar-1-nav-list-divider

/* Sidebar variant 2 */
--sidebar-2
--sidebar-2-line
--sidebar-2-divider
--sidebar-2-nav-foreground
--sidebar-2-nav-hover
--sidebar-2-nav-focus
--sidebar-2-nav-active
--sidebar-2-nav-list-divider

11. Card

--card                /* Card background */
--card-line           /* Card border */
--card-divider        /* Card divider */
--card-header         /* Card header background */
--card-footer         /* Card footer background */
--card-inverse        /* Inverse card background */

12. Dropdown

--dropdown                /* Dropdown background */
--dropdown-1              /* Dropdown variant background */
--dropdown-line           /* Dropdown border */
--dropdown-divider        /* Dropdown divider */
--dropdown-header         /* Dropdown header background */
--dropdown-footer         /* Dropdown footer background */
--dropdown-item-foreground /* Item text */
--dropdown-item-hover     /* Item hover */
--dropdown-item-focus     /* Item focus */
--dropdown-item-active    /* Item active */
--dropdown-inverse        /* Inverse dropdown */

13. Select

--select                /* Select background */
--select-1              /* Select variant background */
--select-line           /* Select border */
--select-item-foreground /* Item text */
--select-item-hover     /* Item hover */
--select-item-focus     /* Item focus */
--select-item-active    /* Item active */
--select-inverse        /* Inverse select */

14. Overlay

--overlay             /* Overlay/modal background */
--overlay-line        /* Overlay border */
--overlay-divider     /* Overlay divider */
--overlay-header      /* Overlay header background */
--overlay-footer      /* Overlay footer background */
--overlay-inverse     /* Inverse overlay */

15. Popover, tooltip, table, switch

/* Popover */
--popover             /* Popover background */
--popover-line        /* Popover border */

/* Tooltip */
--tooltip             /* Tooltip background */
--tooltip-foreground  /* Tooltip text */
--tooltip-line        /* Tooltip border */

/* Table */
--table-line          /* Table border */

/* Switch */
--switch              /* Switch knob color */

16. Footer

--footer              /* Footer background */
--footer-line         /* Footer border */
--footer-inverse      /* Inverse footer */

17. Scrollbar

--scrollbar-track         /* Scrollbar track */
--scrollbar-thumb         /* Scrollbar thumb */
--scrollbar-track-inverse /* Inverse track */
--scrollbar-thumb-inverse /* Inverse thumb */

18. Charts (Apexcharts)

Important: keep chart -hex tokens variable-based in generated theme source. Do not hardcode literal hex or oklch values into the final theme file.

/* Primary chart color */
--chart-primary
--chart-colors-primary
--chart-colors-primary-inverse
--chart-colors-primary-hex
--chart-colors-primary-hex-inverse

/* Chart palette (1-10) */
--chart-1 through --chart-10
--chart-colors-chart-1 through --chart-colors-chart-10
--chart-colors-chart-1-inverse through --chart-colors-chart-10-inverse
--chart-colors-chart-1-hex through --chart-colors-chart-10-hex
--chart-colors-chart-1-hex-inverse through --chart-colors-chart-10-hex-inverse

/* Chart backgrounds */
--chart-colors-background
--chart-colors-background-inverse
--chart-colors-chart-inverse

/* Chart foregrounds */
--chart-colors-foreground
--chart-colors-foreground-inverse

/* Chart labels */
--chart-colors-labels
--chart-colors-labels-inverse
--chart-colors-xaxis-labels
--chart-colors-xaxis-labels-inverse
--chart-colors-yaxis-labels
--chart-colors-yaxis-labels-inverse

/* Chart grid */
--chart-colors-grid-border
--chart-colors-grid-border-inverse

/* Chart special */
--chart-colors-bar-ranges
--chart-colors-bar-ranges-inverse
--chart-colors-candlestick-upward
--chart-colors-candlestick-upward-inverse
--chart-colors-candlestick-downward
--chart-colors-candlestick-downward-inverse

19. Maps (jsvectormap)

--map-colors-primary
--map-colors-primary-inverse
--map-colors-default
--map-colors-default-inverse
--map-colors-highlight
--map-colors-highlight-inverse
--map-colors-border
--map-colors-border-inverse

---

Custom color palettes

The base theme defines custom color palettes that themes can use:

Khaki (earthy/warm neutral)

--color-khaki-50 through --color-khaki-950

Lavender (soft purple/mauve neutral)

--color-lavender-50 through --color-lavender-950

These are useful for creating warm or soft-toned themes instead of using standard gray/neutral.

---

Default values reference

Light mode defaults (:root)

:root {
  /* Backgrounds */
  --background: var(--color-white);
  --background-1: var(--color-gray-50);
  --background-2: var(--color-gray-100);
  --background-plain: var(--color-white);

  /* Foregrounds */
  --foreground: var(--color-gray-800);
  --foreground-inverse: var(--color-white);
  --inverse: var(--color-gray-800);

  /* Borders */
  --border: var(--color-gray-200);
  --border-line-inverse: var(--color-white);
  --border-line-1: var(--color-gray-100);
  --border-line-2: var(--color-gray-200);
  --border-line-3: var(--color-gray-300);
  --border-line-4: var(--color-gray-400);
  --border-line-5: var(--color-gray-500);
  --border-line-6: var(--color-gray-600);
  --border-line-7: var(--color-gray-700);
  --border-line-8: var(--color-gray-800);

  /* Primary (blue by default) */
  --primary-50: var(--color-blue-50);
  --primary-100: var(--color-blue-100);
  --primary-200: var(--color-blue-200);
  --primary-300: var(--color-blue-300);
  --primary-400: var(--color-blue-400);
  --primary-500: var(--color-blue-500);
  --primary-600: var(--color-blue-600);
  --primary-700: var(--color-blue-700);
  --primary-800: var(--color-blue-800);
  --primary-900: var(--color-blue-900);
  --primary-950: var(--color-blue-950);

  --primary: var(--color-primary-600);
  --primary-line: transparent;
  --primary-foreground: var(--color-white);
  --primary-hover: var(--color-primary-700);
  --primary-focus: var(--color-primary-700);
  --primary-active: var(--color-primary-700);
  --primary-checked: var(--color-primary-600);

  /* Secondary */
  --secondary: var(--color-gray-900);
  --secondary-line: transparent;
  --secondary-foreground: var(--color-white);
  --secondary-hover: var(--color-gray-800);
  --secondary-focus: var(--color-gray-800);
  --secondary-active: var(--color-gray-800);

  /* Layer */
  --layer: var(--color-white);
  --layer-line: var(--color-gray-200);
  --layer-foreground: var(--color-gray-800);
  --layer-hover: var(--color-gray-50);
  --layer-focus: var(--color-gray-50);
  --layer-active: var(--color-gray-50);

  /* Surface */
  --surface: var(--color-gray-100);
  --surface-1: var(--color-gray-200);
  --surface-2: var(--color-gray-300);
  --surface-3: var(--color-gray-400);
  --surface-4: var(--color-gray-500);
  --surface-5: var(--color-gray-600);
  --surface-line: transparent;
  --surface-foreground: var(--color-gray-800);
  --surface-hover: var(--color-gray-200);
  --surface-focus: var(--color-gray-200);
  --surface-active: var(--color-gray-200);

  /* Muted */
  --muted: var(--color-gray-50);
  --muted-foreground: var(--color-gray-400);
  --muted-foreground-1: var(--color-gray-500);
  --muted-foreground-2: var(--color-gray-600);
  --muted-hover: var(--color-gray-100);
  --muted-focus: var(--color-gray-100);
  --muted-active: var(--color-gray-100);

  /* Destructive */
  --destructive: var(--color-red-500);
  --destructive-foreground: var(--color-white);
  --destructive-hover: var(--color-red-600);
  --destructive-focus: var(--color-red-600);

  /* Navbar (base) */
  --navbar: var(--color-white);
  --navbar-line: var(--color-gray-200);
  --navbar-divider: var(--color-gray-200);
  --navbar-nav-foreground: var(--color-gray-800);
  --navbar-nav-hover: var(--color-gray-100);
  --navbar-nav-focus: var(--color-gray-100);
  --navbar-nav-active: var(--color-gray-100);
  --navbar-nav-list-divider: var(--color-gray-200);
  --navbar-inverse: var(--color-primary-950);

  /* Navbar-1 */
  --navbar-1: var(--color-gray-50);
  --navbar-1-line: var(--color-gray-200);
  --navbar-1-divider: var(--color-gray-200);
  --navbar-1-nav-foreground: var(--color-gray-800);
  --navbar-1-nav-hover: var(--color-gray-200);
  --navbar-1-nav-focus: var(--color-gray-200);
  --navbar-1-nav-active: var(--color-gray-200);
  --navbar-1-nav-list-divider: var(--color-gray-200);

  /* Navbar-2 */
  --navbar-2: var(--color-gray-100);
  --navbar-2-line: transparent;
  --navbar-2-divider: var(--color-gray-300);
  --navbar-2-nav-foreground: var(--color-gray-800);
  --navbar-2-nav-hover: var(--color-gray-200);
  --navbar-2-nav-focus: var(--color-gray-200);
  --navbar-2-nav-active: var(--color-gray-200);
  --navbar-2-nav-list-divider: var(--color-gray-200);

  /* Sidebar follows same pattern as navbar */
  /* Card, Dropdown, Select, Overlay, Popover, Tooltip, Table, Switch, Footer, Scrollbar */
  /* See the project's existing base Preline theme source for complete default values */
}

Dark mode defaults (.dark)

.dark {
  /* Backgrounds */
  --background: var(--color-neutral-800);
  --background-1: var(--color-neutral-900);
  --background-2: var(--color-neutral-900);
  --foreground: var(--color-neutral-200);
  --inverse: var(--color-neutral-950);

  /* Borders */
  --border: var(--color-neutral-700);
  --border-line-1: var(--color-neutral-800);
  --border-line-2: var(--color-neutral-700);
  --border-line-3: var(--color-neutral-600);
  --border-line-4: var(--color-neutral-500);
  --border-line-5: var(--color-neutral-400);
  --border-line-6: var(--color-neutral-300);
  --border-line-7: var(--color-neutral-200);
  --border-line-8: var(--color-neutral-100);

  /* Primary (shifts to 500 in dark mode) */
  --primary: var(--color-primary-500);
  --primary-line: transparent;
  --primary-foreground: var(--color-white);
  --primary-hover: var(--color-primary-600);
  --primary-focus: var(--color-primary-600);
  --primary-active: var(--color-primary-600);
  --primary-checked: var(--color-primary-500);

  /* Secondary */
  --secondary: var(--color-white);
  --secondary-line: transparent;
  --secondary-foreground: var(--color-neutral-800);
  --secondary-hover: var(--color-neutral-100);
  --secondary-focus: var(--color-neutral-100);
  --secondary-active: var(--color-neutral-100);

  /* Layer */
  --layer: var(--color-neutral-800);
  --layer-line: var(--color-neutral-700);
  --layer-foreground: var(--color-white);
  --layer-hover: var(--color-neutral-700);
  --layer-focus: var(--color-neutral-700);
  --layer-active: var(--color-neutral-700);

  /* Surface */
  --surface: var(--color-neutral-700);
  --surface-1: var(--color-neutral-600);
  --surface-2: var(--color-neutral-500);
  --surface-3: var(--color-neutral-600);
  --surface-4: var(--color-neutral-500);
  --surface-5: var(--color-neutral-400);
  --surface-line: transparent;
  --surface-foreground: var(--color-neutral-200);
  --surface-hover: var(--color-neutral-600);
  --surface-focus: var(--color-neutral-600);
  --surface-active: var(--color-neutral-600);

  /* Muted */
  --muted: var(--color-neutral-800);
  --muted-foreground: var(--color-neutral-500);
  --muted-foreground-1: var(--color-neutral-400);
  --muted-foreground-2: var(--color-neutral-300);
  --muted-hover: var(--color-neutral-700);
  --muted-focus: var(--color-neutral-700);
  --muted-active: var(--color-neutral-700);

  /* Destructive (same red, readable in dark) */
  --destructive: var(--color-red-500);
  --destructive-foreground: var(--color-white);
  --destructive-hover: var(--color-red-600);
  --destructive-focus: var(--color-red-600);

  /* Components shift to neutral-800/900 backgrounds */
  /* Nav items shift to neutral-700 hover states */
  /* See the project's existing base Preline theme source for complete dark mode values */
}

---

Theme-scoped overrides

When creating a theme, override values under theme-scoped selectors:

/* Light mode */
:root[data-theme="theme-<name>"],
[data-theme="theme-<name>"] {
  /* Override tokens here */
}

/* Dark mode */
[data-theme="theme-<name>"].dark {
  /* Override dark-specific tokens here */
}

---

Color format guidelines

• For most tokens: use Tailwind color variables var(--color-<color>-<shade>)
• For oklch colors: acceptable for standard tokens
• For chart -hex tokens: keep them as stable variable references in generated source
• For custom colors: can use hex, rgb, hsl, or oklch

---

Quick token count summary

Validation checklist (must self-check before returning)

Final source style

• [ ] Only one project file is created or edited: <name>.css
• [ ] The final file is a production-style <name>.css file
• [ ] @theme theme-<name> inline { } is present
• [ ] Any custom brand/gray palette lives inside @theme theme-<name> inline { } in the new theme file
• [ ] Semantic tokens prefer assigned vars such as --color-primary-*, --background-*, --foreground, --border, --surface-*, or shared palette vars when available
• [ ] The custom theme does not redefine shared aliases like --color-primary-* inside @theme when the repo base theme already owns them
• [ ] No raw oklch(...) or literal hex values remain in semantic, chart, or map token assignments in the final theme file

Structure

• [ ] Theme key consistent: theme-<name> everywhere
• [ ] Light selector uses :root[data-theme=...], [data-theme=...]
• [ ] Dark selector is [data-theme="theme-<name>"].dark
• [ ] Semantic token definitions are in selector blocks (NOT inside @theme block)
• [ ] No requirement to change HTML utility classes (only data-theme, optional .dark)

Palette strategy

• [ ] Primary ramp maps --primary-* directly to theme-local palette vars
• [ ] Neutral/background tokens use assigned palette vars
• [ ] If a new custom palette is needed, it is declared inside the new theme file's @theme block, not by editing another file

Token coverage

• [ ] Full coverage present across global tokens, states, and major component groups
• [ ] CSS syntax valid (balanced braces, no broken comments)
• [ ] If behavior overrides exist, they are theme-scoped only
• [ ] Chart/map tokens use variable references matching shipped theme patterns

Dark mode consistency

• [ ] Dark mode uses CSS variables (var(--color-*)) not hardcoded color literals
• [ ] Dark mode uses one consistent grayscale family unless there is a deliberate, reference-backed reason not to
• [ ] Hover/focus/active states remain readable and distinguishable
• [ ] --foreground-inverse remains readable on vivid utility colors in dark mode (for example red badges/chips)
• [ ] Dark-mode chart/decorative tokens avoid very deep brand steps when those tokens are used in gradient text or accent UI

Workflow

Use this file as the default operating guide for the active theme skill.

Task modes

Classify the request before doing any work:

• preview: generate CSS and return it without writing a project file
• write: create one new <name>.css theme file
• validate: review or fix an existing generated theme file

Normalize the request

Convert natural language into the generator's small, explicit input set:

Use docs/palette-guidance.md for hue ranges, mood mapping, contrast heuristics, and gray-family decisions.

Natural-language interpretation

Use the user's language to infer the palette direction:

When the request is vague:

1. Make an opinionated, coherent palette choice. 2. Keep contrast readable. 3. Prefer a consistent system over a flashy but uneven palette.

Foreground rule:

• When mapping text or icon colors onto the primary brand color, choose the foreground by contrast against the generated primary states, not by hue bucket alone.
• Treat --foreground-inverse separately from primary foregrounds. In Preline it is reused on hardcoded vivid utility backgrounds such as red badges, so dark mode should keep it readable on saturated colors instead of tinting it into a dark neutral.
• Treat chart tokens as decorative UI tokens, not just data-series tokens. Dark mode must override any chart shades that would become too dark for gradient text, badges, or chart accents on dark surfaces.

Discover the target directory

Use the bundled resolver instead of broad repo traversal:

node scripts/find-themes-dir.js

Trusted theme directories are checked in this order:

• src/assets/css/themes/
• src/css/themes/
• src/styles/themes/
• assets/css/themes/
• styles/themes/
• dist/assets/css/themes/
• npm/preline/css/themes/

Rules:

• Prefer source theme directories over generated outputs.
• Do not use repo-wide find . traversal for this task.
• If no trusted theme directory is found and the user did not provide a path, ask where the file should be written.

Generate CSS

Use the local wrapper as the only execution entry point:

node scripts/run-theme-generator.js --name seafoam --hue 180 --style vibrant --tailwind-gray zinc --stdout

Write a theme file with:

node scripts/run-theme-generator.js --name seafoam --hue 180 --style vibrant --tailwind-gray zinc --output src/assets/css/themes/seafoam.css

Rules:

• Do not use npx.
• Do not interpolate raw user text into shell commands.
• Do not chain temp-file cleanup or other unrelated shell work into the command.
• Do not create or edit any project file other than the new theme file.

Theme structure expectations

The wrapper should emit a production-style standalone <name>.css file:

1. Header comment 2. Optional theme-scoped @layer utilities overrides 3. @theme theme-<name> inline { } 4. Light selector

• :root[data-theme="theme-<name>"],
• [data-theme="theme-<name>"]

5. Dark selector

• [data-theme="theme-<name>"].dark

Keep custom brand and gray palettes inside the file's @theme block. Keep semantic tokens in the selector blocks.

See docs/final-output-style.md for the final file rules and docs/token-reference.md only when detailed token coverage inspection is necessary.

Dark-mode decision rule

Always generate both palettes in @theme theme-<name> inline { }:

• --color-<name>-* for the brand ramp
• --color-<name>-gray-* for the theme's neutral ramp

Dark-mode neutrals depend on user intent:

• Explicit matching/cohesive dark request: use the theme's custom gray palette in dark mode.
• Default path: keep light mode custom and use a Tailwind gray family in dark mode.

Primary foreground decision:

• Use the generated brand shades to determine whether white or dark text is more readable on the primary color in each mode.
• In dark mode, prefer a deeper primary step with white text when that profile remains readable; only fall back to lighter primary steps with dark text when white would fail.

Use CSS variables in semantic tokens and dark-mode overrides. Do not hardcode raw oklch(...) or hex values in semantic, chart, or map tokens.

Validation focus

Before returning:

• confirm only one project file was created or edited
• confirm the theme key is theme-<name> everywhere
• confirm the file has full light and dark token coverage
• confirm chart and map tokens remain variable-based
• confirm dark-mode states remain readable

Use docs/validation-checklist.md as the final gate.

Response shape

Match the response to the mode:

• Preview: return the CSS first, then the enable snippet if useful
• Write: return the created path, a short summary, and the enable snippet
• Validate: list findings first, then the applied or recommended fix

Enable snippet:

<html data-theme="theme-<theme-name>">

Examples — Preline Theme Generator

These examples are palette-and-structure references, not literal final-output templates.

Important: examples below are structural references. Final delivered theme files should follow docs/final-output-style.md and should never require edits to any companion project file.

These examples define what "good output" looks like.

Contents

• Example 1 — Calm teal SaaS theme
• Example 2 — Retro sharp corners
• Example 3 — Theme-scoped font token
• Example 4 — Brand match with exact primary color

Example 1 — Calm teal SaaS theme (full theme, clean)

Input

• themeName: seafoam
• mood: calm, modern SaaS
• primaryHue: teal (180)
• contrast: medium
• style: vibrant
• darkNeutralFamily: zinc

Expected Structure

• @theme theme-seafoam inline { } contains brand + gray palettes
• Light mode selector: :root[data-theme="theme-seafoam"], [data-theme="theme-seafoam"]
• Dark mode selector: [data-theme="theme-seafoam"].dark
• Full coverage: global surfaces, borders, primary ramp, states, components
• Dark mode uses Tailwind zinc for neutrals (no matching dark requested)

Output (truncated)

/* ------------------------------ */
/* -------- Seafoam ------------- */
/* ------------------------------ */

@theme theme-seafoam inline {
  /* BRAND PALETTE (vibrant) */
  --color-seafoam-50: oklch(97% 0.08 180);
  --color-seafoam-100: oklch(94% 0.10 180);
  --color-seafoam-200: oklch(88% 0.12 180);
  --color-seafoam-300: oklch(80% 0.14 180);
  --color-seafoam-400: oklch(70% 0.16 180);
  --color-seafoam-500: oklch(60% 0.14 180);
  --color-seafoam-600: oklch(52% 0.12 180);
  --color-seafoam-700: oklch(44% 0.10 180);
  --color-seafoam-800: oklch(36% 0.08 180);
  --color-seafoam-900: oklch(28% 0.06 180);
  --color-seafoam-950: oklch(20% 0.05 180);
  
  /* GRAY PALETTE (bell curve chroma) */
  --color-seafoam-gray-50: oklch(98% 0.002 180);
  --color-seafoam-gray-100: oklch(95.5% 0.004 180);
  --color-seafoam-gray-200: oklch(89.7% 0.008 180);
  /* ... 300-700 ... */
  --color-seafoam-gray-800: oklch(34.6% 0.008 180);
  --color-seafoam-gray-900: oklch(30.6% 0.005 180);
  --color-seafoam-gray-950: oklch(20.1% 0.003 180);

}

:root[data-theme="theme-seafoam"],
[data-theme="theme-seafoam"] {
  /* Global */
  --background: var(--color-white);
  --background-1: var(--color-seafoam-gray-50);
  --foreground: var(--color-seafoam-gray-800);
  
  /* Primary ramp */
  --primary-50: var(--color-seafoam-50);
  --primary-100: var(--color-seafoam-100);
  /* ... full ramp ... */
  
  /* Primary states */
  --primary: var(--color-primary-600);
  --primary-foreground: var(--color-white);
  --primary-hover: var(--color-primary-700);
  
  /* Components prefer assigned semantic tokens */
  --navbar: var(--background-plain);
  --navbar-line: var(--border);
  /* ... */
}

[data-theme="theme-seafoam"].dark {
  /* Dark mode uses Tailwind zinc */
  --background: var(--color-zinc-800);
  --background-1: var(--color-zinc-900);
  --foreground: var(--color-zinc-200);
  
  --primary: var(--color-primary-400);
  --primary-foreground: var(--color-zinc-900); /* Contrast-selected because the generated light-brand states are too light for white */
  /* ... */
}

---

Example 2 — Retro sharp corners (behavior change must be scoped)

Input

• themeName: arcade
• mood: retro 90s
• primaryHue: magenta (320)
• contrast: high
• radiusStyle: retro-sharp

Expected Structure

• Full token coverage
• Theme sets radius tokens in theme selector (NOT in @theme block)
• Any "rounded" behavior override inside @layer utilities scoped to theme

Output (radius section only)

:root[data-theme="theme-arcade"],
[data-theme="theme-arcade"] {
  /* RETRO SHARP CORNERS */
  --radius-sm: 0px;
  --radius-md: 2px;
  --radius-lg: 4px;
  --radius-xl: 4px;
  --radius-2xl: 6px;
  --radius-3xl: 6px;
  
  /* ... rest of tokens ... */
}

/* Optional: Override rounded utility if needed */
@layer utilities {
  :is(:root[data-theme="theme-arcade"], [data-theme="theme-arcade"]) .rounded {
    border-radius: var(--radius-md);
  }
}

---

Example 3 — Theme-scoped font token (no mapping changes)

Input

• themeName: leafy-modern
• mood: organic, clean
• primaryHue: emerald (145)
• fontSans: "Roboto", ui-sans-serif, system-ui, sans-serif

Expected Structure

• Theme sets --font-sans inside theme selector (NOT in @theme block)
• Theme does NOT import Google Fonts (font loading is separate)
• User enables via data-theme="theme-leafy-modern" only

Output (font section only)

:root[data-theme="theme-leafy-modern"],
[data-theme="theme-leafy-modern"] {
  /* TYPOGRAPHY */
  --font-sans: "Roboto", ui-sans-serif, system-ui, sans-serif;
  
  /* ... rest of tokens ... */
}

---

Example 4 — Brand match with exact primary color

Input

• themeName: brand-x
• primaryColor: #2F6BFF (converts to hue ~225)
• mood: confident, high clarity
• contrast: medium-high

Expected Structure

• Script converts hex to hue automatically
• Primary ramp derived coherently from the brand hue
• --primary-foreground readable (white on this blue)
• Chart -hex tokens remain variable-based placeholders in generated source

Output (chart section showing variable-based chart tokens)

:root[data-theme="theme-brand-x"],
[data-theme="theme-brand-x"] {
  /* ... other tokens ... */
  
  /* CHARTS */
  --chart-primary: var(--color-primary-500);
  --chart-colors-primary: var(--color-primary-500);
  --chart-colors-primary-hex: var(--color-primary-500);
  --chart-colors-primary-hex-inverse: var(--color-primary-300);
  
  --chart-1: var(--color-primary-500);
  --chart-colors-chart-1-hex: var(--color-primary-500);
  /* ... */
}

Output Template (Full Theme)

Use this skeleton for every generated theme. Replace <name> with the theme name (kebab-case). Fill in ALL token values for a complete theme.

Note: The generate-theme.js script produces output matching this template automatically. See SKILL.md for interpretive guidance and docs/token-reference.md for complete token documentation.

---

Required Structure

@import "./theme.css";

/* ------------------------------ */
/* --------- Theme: <name> ------ */
/* ------------------------------ */

/* ============================================== */
/* OPTIONAL: THEME-SCOPED BEHAVIOR OVERRIDES      */
/* ============================================== */

/* Only include if the theme needs behavior changes (e.g., different border radius, shadows etc.) */
/*
@layer utilities {
  :is(:root[data-theme="theme-<name>"], [data-theme="theme-<name>"]) .rounded {
    border-radius: var(--radius-ui);
  }
}
*/

@theme theme-<name> inline {
  /* ============================================ */
  /* CUSTOM COLOR PALETTES                        */
  /* ============================================ */
  
  /* 
   * ALWAYS create BOTH palettes:
   *   1. Brand palette (--color-<name>-*) — for primary/accent colors
   *   2. Gray palette (--color-<name>-gray-*) — for backgrounds, surfaces, borders
   *
   * Light mode: ALWAYS uses custom gray palette
   *
   * Dark mode behavior:
   *   - DEFAULT: Use Tailwind grays (zinc/stone) — see dark mode section below
   *   - If user says "matching dark mode": Use custom gray palette
   */
  
  /* -------------------------------------------- */
  /* BRAND PALETTE (always required)              */
  /* -------------------------------------------- */
  /* Vibrant by default, soft only if user says "muted/ash/soft" */
  
  --color-<name>-50:  oklch(97%  0.08 <hue>);
  --color-<name>-100: oklch(94%  0.10 <hue>);
  --color-<name>-200: oklch(88%  0.12 <hue>);
  --color-<name>-300: oklch(80%  0.14 <hue>);
  --color-<name>-400: oklch(70%  0.16 <hue>);
  --color-<name>-500: oklch(58%  0.14 <hue>);
  --color-<name>-600: oklch(50%  0.12 <hue>);
  --color-<name>-700: oklch(42%  0.10 <hue>);
  --color-<name>-800: oklch(35%  0.08 <hue>);
  --color-<name>-900: oklch(28%  0.06 <hue>);
  --color-<name>-950: oklch(20%  0.05 <hue>);
  
  /* -------------------------------------------- */
  /* GRAY PALETTE (always required for light mode)*/
  /* -------------------------------------------- */
  /* Used in light mode for cohesive backgrounds, surfaces, borders.
   * Uses bell curve chroma: very low at extremes, peak at midtones.
   * Dark end (800-950) has very low chroma for clean dark mode (if used).
   */
  
  --color-<name>-gray-50:  oklch(98%   0.002 <hue>);  
  --color-<name>-gray-100: oklch(95.5% 0.004 <hue>);
  --color-<name>-gray-200: oklch(89.7% 0.008 <hue>);
  --color-<name>-gray-300: oklch(82.7% 0.012 <hue>);
  --color-<name>-gray-400: oklch(73%   0.018 <hue>);
  --color-<name>-gray-500: oklch(62.5% 0.020 <hue>);
  --color-<name>-gray-600: oklch(52.8% 0.016 <hue>);
  --color-<name>-gray-700: oklch(41.4% 0.012 <hue>);
  --color-<name>-gray-800: oklch(26.9% 0.006 <hue>);
  --color-<name>-gray-900: oklch(20.5% 0.004 <hue>);
  --color-<name>-gray-950: oklch(14.1% 0.002 <hue>);
}

:root[data-theme="theme-<name>"],
[data-theme="theme-<name>"] {
  
  /* ============================================== */
  /* THEME-SPECIFIC OVERRIDES (optional)            */
  /* ============================================== */
  /* Place non-default customizations HERE at top:
   * - Radius overrides (retro sharp corners)
   * - Font overrides
   * - Any theme-specific behavior changes
   * 
   * Example for retro sharp corners:
   * --radius-sm: 0px;
   * --radius-md: 2px;
   * --radius-lg: 4px;
   * --radius-xl: 4px;
   * --radius-2xl: 6px;
   * --radius-3xl: 6px;
   */
  
  /* ============================================ */
  /* GLOBAL SURFACES + TEXT                       */
  /* ============================================ */
  
  --background-1: ...;
  --background-2: ...;
  --foreground: ...;
  
  --inverse: ...;
  
  /* ============================================ */
  /* BORDERS (Full Scale)                         */
  /* ============================================ */
  
  --border: ...;
  --border-line-1: ...;
  --border-line-2: ...;
  --border-line-3: ...;
  --border-line-4: ...;
  --border-line-5: ...;
  --border-line-6: ...;
  --border-line-7: ...;
  --border-line-8: ...;
  
  /* ============================================ */
  /* PRIMARY RAMP (Full 11-shade scale)           */
  /* ============================================ */
  
  --primary-50: ...;
  --primary-100: ...;
  --primary-200: ...;
  --primary-300: ...;
  --primary-400: ...;
  --primary-500: ...;
  --primary-600: ...;
  --primary-700: ...;
  --primary-800: ...;
  --primary-900: ...;
  --primary-950: ...;
  
  /* PRIMARY STATES */
  --primary: ...;
  --primary-hover: ...;
  --primary-focus: ...;
  --primary-active: ...;
  --primary-checked: ...;
  
  /* ============================================ */
  /* SECONDARY                                    */
  /* ============================================ */
  
  --secondary: ...;
  --secondary-hover: ...;
  --secondary-focus: ...;
  --secondary-active: ...;
  
  /* ============================================ */
  /* LAYER                                        */
  /* ============================================ */
  
  --layer-line: ...;
  --layer-foreground: ...;
  --layer-hover: ...;
  --layer-focus: ...;
  --layer-active: ...;
  
  /* ============================================ */
  /* SURFACE                                      */
  /* ============================================ */
  
  --surface: ...;
  --surface-1: ...;
  --surface-2: ...;
  --surface-3: ...;
  --surface-4: ...;
  --surface-5: ...;
  --surface-foreground: ...;
  --surface-hover: ...;
  --surface-focus: ...;
  --surface-active: ...;
  
  /* ============================================ */
  /* MUTED                                        */
  /* ============================================ */
  
  --muted: ...;
  --muted-foreground: ...;
  --muted-foreground-1: ...;
  --muted-foreground-2: ...;
  --muted-hover: ...;
  --muted-focus: ...;
  --muted-active: ...;
  
  /* ============================================ */
  /* NAVBAR (Base)                                */
  /* ============================================ */
  
  --navbar-line: ...;
  --navbar-divider: ...;
  --navbar-nav-foreground: ...;
  --navbar-nav-hover: ...;
  --navbar-nav-focus: ...;
  --navbar-nav-active: ...;
  --navbar-nav-list-divider: ...;
  --navbar-inverse: ...;
  
  /* NAVBAR-1 (Subtle/tinted variant) */
  --navbar-1: ...;
  --navbar-1-line: ...;
  --navbar-1-divider: ...;
  --navbar-1-nav-foreground: ...;
  --navbar-1-nav-hover: ...;
  --navbar-1-nav-focus: ...;
  --navbar-1-nav-active: ...;
  --navbar-1-nav-list-divider: ...;
  
  /* NAVBAR-2 (Stronger tint variant) */
  --navbar-2: ...;
  --navbar-2-divider: ...;
  --navbar-2-nav-foreground: ...;
  --navbar-2-nav-hover: ...;
  --navbar-2-nav-focus: ...;
  --navbar-2-nav-active: ...;
  --navbar-2-nav-list-divider: ...;
  
  /* ============================================ */
  /* SIDEBAR (Base)                               */
  /* ============================================ */
  
  --sidebar-line: ...;
  --sidebar-divider: ...;
  --sidebar-nav-foreground: ...;
  --sidebar-nav-hover: ...;
  --sidebar-nav-focus: ...;
  --sidebar-nav-active: ...;
  --sidebar-nav-list-divider: ...;
  --sidebar-inverse: ...;
  
  /* SIDEBAR-1 */
  --sidebar-1: ...;
  --sidebar-1-line: ...;
  --sidebar-1-divider: ...;
  --sidebar-1-nav-foreground: ...;
  --sidebar-1-nav-hover: ...;
  --sidebar-1-nav-focus: ...;
  --sidebar-1-nav-active: ...;
  --sidebar-1-nav-list-divider: ...;
  
  /* SIDEBAR-2 */
  --sidebar-2: ...;
  --sidebar-2-divider: ...;
  --sidebar-2-nav-foreground: ...;
  --sidebar-2-nav-hover: ...;
  --sidebar-2-nav-focus: ...;
  --sidebar-2-nav-active: ...;
  --sidebar-2-nav-list-divider: ...;
  
  /* ============================================ */
  /* CARD                                         */
  /* ============================================ */
  
  --card-line: ...;
  --card-divider: ...;
  --card-header: ...;
  --card-footer: ...;
  --card-inverse: ...;
  
  /* ============================================ */
  /* DROPDOWN                                     */
  /* ============================================ */
  
  --dropdown-divider: ...;
  --dropdown-header: ...;
  --dropdown-footer: ...;
  --dropdown-item-foreground: ...;
  --dropdown-item-hover: ...;
  --dropdown-item-focus: ...;
  --dropdown-item-active: ...;
  --dropdown-inverse: ...;
  
  /* ============================================ */
  /* SELECT                                       */
  /* ============================================ */
  
  --select-item-foreground: ...;
  --select-item-hover: ...;
  --select-item-focus: ...;
  --select-item-active: ...;
  --select-inverse: ...;
  
  /* ============================================ */
  /* OVERLAY                                      */
  /* ============================================ */
  
  --overlay-divider: ...;
  --overlay-header: ...;
  --overlay-footer: ...;
  --overlay-inverse: ...;
  
  /* ============================================ */
  /* POPOVER, TOOLTIP, TABLE, FOOTER              */
  /* ============================================ */
  
  --popover-line: ...;
  
  --tooltip: ...;
  
  --table-line: ...;
  
  --footer-line: ...;
  --footer-inverse: ...;
  
  /* ============================================ */
  /* SCROLLBAR                                    */
  /* ============================================ */
  
  --scrollbar-track: ...;
  --scrollbar-thumb: ...;
  
  /* ============================================ */
  /* CHARTS (Apexcharts)                          */
  /* ============================================ */
  
  /* IMPORTANT: Avoid using Tailwind's default color variables for gradient Apexcharts colors.
  The Apexcharts plugin does not support the oklch color format, so these colors may not render correctly. */
  
  --chart-colors-background-inverse: ...;
  --chart-colors-foreground: ...;
  --chart-primary: ...;
  --chart-colors-primary: ...;
  --chart-colors-primary-inverse: ...;
  --chart-colors-primary-hex: #......; /* Must be valid hex */
  --chart-colors-primary-hex-inverse: #......; /* Must be valid hex */
  
  --chart-1: ...;
  --chart-colors-chart-1: ...;
  --chart-colors-chart-1-inverse: ...;
  --chart-colors-chart-1-hex: #......;
  --chart-colors-chart-1-hex-inverse: #......;
  
  --chart-2: ...;
  --chart-colors-chart-2: ...;
  --chart-colors-chart-2-inverse: ...;
  --chart-colors-chart-2-hex: #......;
  --chart-colors-chart-2-hex-inverse: #......;
  
  --chart-3: ...;
  --chart-colors-chart-3: ...;
  --chart-colors-chart-3-inverse: ...;
  --chart-colors-chart-3-hex: #......;
  --chart-colors-chart-3-hex-inverse: #......;
  
  --chart-4: ...;
  --chart-colors-chart-4: ...;
  --chart-colors-chart-4-inverse: ...;
  --chart-colors-chart-4-hex: #......;
  --chart-colors-chart-4-hex-inverse: #......;
  
  --chart-5: ...;
  --chart-colors-chart-5: ...;
  --chart-colors-chart-5-inverse: ...;
  --chart-colors-chart-5-hex: #......;
  --chart-colors-chart-5-hex-inverse: #......;
  
  --chart-6: ...;
  --chart-colors-chart-6: ...;
  --chart-colors-chart-6-inverse: ...;
  --chart-colors-chart-6-hex: #......;
  --chart-colors-chart-6-hex-inverse: #......;
  
  --chart-7: ...;
  --chart-colors-chart-7: ...;
  --chart-colors-chart-7-inverse: ...;
  --chart-colors-chart-7-hex: #......;
  --chart-colors-chart-7-hex-inverse: #......;
  
  --chart-8: ...;
  --chart-colors-chart-8: ...;
  --chart-colors-chart-8-inverse: ...;
  --chart-colors-chart-8-hex: #......;
  --chart-colors-chart-8-hex-inverse: #......;
  
  --chart-9: ...;
  --chart-colors-chart-9: ...;
  --chart-colors-chart-9-inverse: ...;
  --chart-colors-chart-9-hex: #......;
  --chart-colors-chart-9-hex-inverse: #......;
  
  --chart-10: ...;
  --chart-colors-chart-10: ...;
  --chart-colors-chart-10-inverse: ...;
  --chart-colors-chart-10-hex: #......;
  --chart-colors-chart-10-hex-inverse: #......;
  
  --chart-colors-candlestick-upward: ...;
  --chart-colors-candlestick-upward-inverse: ...;
  --chart-colors-candlestick-downward: ...;
  --chart-colors-candlestick-downward-inverse: ...;
  
  --chart-colors-labels: ...;
  --chart-colors-labels-inverse: ...;
  --chart-colors-xaxis-labels: ...;
  --chart-colors-xaxis-labels-inverse: ...;
  --chart-colors-yaxis-labels: ...;
  --chart-colors-yaxis-labels-inverse: ...;
  
  --chart-colors-grid-border: ...;
  --chart-colors-grid-border-inverse: ...;
  --chart-colors-bar-ranges: ...;
  --chart-colors-bar-ranges-inverse: ...;
  
  /* ============================================ */
  /* MAPS (jsvectormap)                           */
  /* ============================================ */
  
  --map-colors-primary: ...;
  --map-colors-primary-inverse: ...;
  --map-colors-default: ...;
  --map-colors-default-inverse: ...;
  --map-colors-highlight: ...;
  --map-colors-highlight-inverse: ...;
  --map-colors-border: ...;
  --map-colors-border-inverse: ...;
}

/* ============================================== */
/* DARK MODE OVERRIDES                            */
/* ============================================== */

[data-theme="theme-<name>"].dark {
  
  /* ============================================ */
  /* DARK MODE OVERRIDES                          */
  /* ============================================ */
  
  /* 
   * CRITICAL: Choose correct mode based on user request
   *
   * DEFAULT (no "matching dark mode" requested):
   *   Use Tailwind grayscale (stone/zinc/slate) based on brand warmth:
   *   - Warm brands (orange/amber/brown/rose) → stone or neutral
   *   - Cool brands (blue/cyan/teal/indigo) → zinc or slate
   *
   * IF USER REQUESTED "matching dark mode":
   *   Use custom gray palette: var(--color-<name>-gray-*)
   *   (uncomment the dual-palette section below and comment out Tailwind section)
   */
  
  /* -------------------------------------------- */
  /* DEFAULT: Use Tailwind gray for dark mode     */
  /* -------------------------------------------- */
  
  /* BACKGROUNDS - dark end of scale (800-950) */
  --background: var(--color-stone-950);
  --background-1: var(--color-stone-900);
  --background-2: var(--color-stone-800);
  --foreground: var(--color-stone-200);
  
  --inverse: var(--color-stone-50);
  
  /* BORDERS - mid-dark range (700-900) */
  --border: var(--color-stone-800);
  --border-line-inverse: var(--color-stone-200);
  --border-line-1: var(--color-stone-900);
  --border-line-2: var(--color-stone-850);
  --border-line-3: var(--color-stone-800);
  --border-line-4: var(--color-stone-750);
  --border-line-5: var(--color-stone-700);
  --border-line-6: var(--color-stone-650);
  --border-line-7: var(--color-stone-600);
  --border-line-8: var(--color-stone-550);
  
  /* -------------------------------------------- */
  /* DUAL-PALETTE: Use custom gray (uncomment)    */
  /* -------------------------------------------- */
  /*
  --background: var(--color-<name>-gray-950);
  --background-1: var(--color-<name>-gray-900);
  --background-2: var(--color-<name>-gray-800);
  
  --foreground: var(--color-<name>-gray-200);
  
  --inverse: var(--color-<name>-gray-50);
  
  --border: var(--color-<name>-gray-800);
  --border-line-inverse: var(--color-<name>-gray-200);
  --border-line-1: var(--color-<name>-gray-900);
  --border-line-2: var(--color-<name>-gray-850);
  ... etc ...
  */
  
  /* PRIMARY STATES (adjust for dark backgrounds) */
  --primary: var(--color-<name>-400);
  /* 
   * --primary-foreground: DYNAMIC based on brand lightness
   *   Light brands (yellow/lime/cyan hue 50-110 or 160-195): var(--color-<gray>-900)
   *   Dark brands (most colors): var(--color-white)
   */
  --primary-foreground: var(--color-white); /* or var(--color-<gray>-900) for light brands */
  --primary-hover: var(--color-<name>-500);
  --primary-focus: var(--color-<name>-500);
  --primary-active: var(--color-<name>-500);
  --primary-checked: var(--color-<name>-400);
  
  /* SECONDARY */
  --secondary: var(--color-white);
  --secondary-hover: var(--color-stone-100);
  --secondary-focus: var(--color-stone-100);
  --secondary-active: ...;
  
  /* LAYER */
  --layer: ...;
  --layer-line: ...;
  --layer-foreground: ...;
  --layer-hover: ...;
  --layer-focus: ...;
  --layer-active: ...;
  
  /* SURFACE */
  --surface: ...;
  --surface-1: ...;
  --surface-2: ...;
  --surface-3: ...;
  --surface-4: ...;
  --surface-5: ...;
  --surface-foreground: ...;
  --surface-hover: ...;
  --surface-focus: ...;
  --surface-active: ...;
  
  /* MUTED */
  --muted: ...;
  --muted-foreground: ...;
  --muted-foreground-1: ...;
  --muted-foreground-2: ...;
  --muted-hover: ...;
  --muted-focus: ...;
  --muted-active: ...;
  
  /* NAVBAR (all variants) */
  --navbar: ...;
  --navbar-line: ...;
  --navbar-divider: ...;
  --navbar-nav-foreground: ...;
  --navbar-nav-hover: ...;
  --navbar-nav-focus: ...;
  --navbar-nav-active: ...;
  --navbar-nav-list-divider: ...;
  --navbar-inverse: ...;
  
  --navbar-1: ...;
  --navbar-1-line: ...;
  --navbar-1-divider: ...;
  --navbar-1-nav-foreground: ...;
  --navbar-1-nav-hover: ...;
  --navbar-1-nav-focus: ...;
  --navbar-1-nav-active: ...;
  --navbar-1-nav-list-divider: ...;
  
  --navbar-2: ...;
  --navbar-2-divider: ...;
  --navbar-2-nav-foreground: ...;
  --navbar-2-nav-hover: ...;
  --navbar-2-nav-focus: ...;
  --navbar-2-nav-active: ...;
  --navbar-2-nav-list-divider: ...;
  
  /* SIDEBAR (all variants) */
  --sidebar: ...;
  --sidebar-line: ...;
  --sidebar-divider: ...;
  --sidebar-nav-foreground: ...;
  --sidebar-nav-hover: ...;
  --sidebar-nav-focus: ...;
  --sidebar-nav-active: ...;
  --sidebar-nav-list-divider: ...;
  --sidebar-inverse: ...;
  
  --sidebar-1: ...;
  --sidebar-1-line: ...;
  --sidebar-1-divider: ...;
  --sidebar-1-nav-foreground: ...;
  --sidebar-1-nav-hover: ...;
  --sidebar-1-nav-focus: ...;
  --sidebar-1-nav-active: ...;
  --sidebar-1-nav-list-divider: ...;
  
  --sidebar-2: ...;
  --sidebar-2-divider: ...;
  --sidebar-2-nav-foreground: ...;
  --sidebar-2-nav-hover: ...;
  --sidebar-2-nav-focus: ...;
  --sidebar-2-nav-active: ...;
  --sidebar-2-nav-list-divider: ...;
  
  /* CARD */
  --card: ...;
  --card-line: ...;
  --card-divider: ...;
  --card-header: ...;
  --card-footer: ...;
  --card-inverse: ...;
  
  /* DROPDOWN */
  --dropdown: ...;
  --dropdown-1: ...;
  --dropdown-divider: ...;
  --dropdown-header: ...;
  --dropdown-footer: ...;
  --dropdown-item-foreground: ...;
  --dropdown-item-hover: ...;
  --dropdown-item-focus: ...;
  --dropdown-item-active: ...;
  --dropdown-inverse: ...;
  
  /* SELECT */
  --select: ...;
  --select-1: ...;
  --select-item-foreground: ...;
  --select-item-hover: ...;
  --select-item-focus: ...;
  --select-item-active: ...;
  --select-inverse: ...;
  
  /* OVERLAY */
  --overlay: ...;
  --overlay-divider: ...;
  --overlay-header: ...;
  --overlay-footer: ...;
  --overlay-inverse: ...;
  
  /* POPOVER, TOOLTIP, TABLE */
  --popover: ...;
  --popover-line: ...;
  
  --tooltip: ...;
  --tooltip-foreground: ...;
  
  --table-line: ...;
  
  /* SWITCH */
  --switch: ...;
  
  /* FOOTER */
  --footer: ...;
  --footer-line: ...;
  --footer-inverse: ...;
  
  /* SCROLLBAR */
  --scrollbar-track: ...;
  --scrollbar-thumb: ...;
  --scrollbar-track-inverse: ...;
  --scrollbar-thumb-inverse: ...;
  
  /* CHARTS (dark mode adjustments) */
  --chart-primary: ...;
  --chart-5: ...; /* Often needs adjustment */
  --chart-6: ...; /* Often needs adjustment */
  --chart-8: ...;
  --chart-9: ...;
  --chart-10: ...;
}

---

Enable Theme Snippet

Provide this snippet to users for enabling the theme:

CSS (in tailwind.css or main entry)

@import "tailwindcss";
@import "./themes/theme.css";
@import "./themes/<name>.css";

HTML

<html data-theme="theme-<name>">
  ...
</html>

For dark mode, add the .dark class:

<html data-theme="theme-<name>" class="dark">
  ...
</html>

---

Notes

Palette Rules: 1. @theme theme-<name> inline { } ALWAYS contains TWO palettes: brand + gray 2. Light mode ALWAYS uses custom gray palette for backgrounds/surfaces/borders 3. Dark mode DEFAULT: Use Tailwind gray (stone/zinc) based on brand warmth 4. Dark mode if "matching dark mode" requested: Use custom gray palette 5. Brand palette is VIBRANT by default; only use soft/low-chroma if user says "muted/ash/soft" 6. Gray palette uses bell curve chroma (low at 800-950 for clean dark mode)

Token Rules: 7. All semantic tokens (--background, --primary, etc.) go in selector blocks, NOT in @theme block 8. Replace all ... with actual color values using var(--color-<family>-<shade>) format 9. Chart -hex tokens MUST contain valid hex values (e.g., #2563eb), not CSS variables 10. Dark mode MUST use CSS variables for readability - never hardcode oklch values 11. Use ONE consistent grayscale family throughout dark mode (don't mix) 12. Dark mode only needs to override tokens that differ from light mode

Theme Generator QA (Self-Check)

Use this checklist immediately before returning a generated theme.

---

1) Structural correctness

• Did I include BOTH imports at the top?
• @import "tailwindcss";
• @import "./theme.css";
• Did I use the correct theme name everywhere (theme-<name>)?
• Did I include the theme scoping block with custom palettes?
• @theme theme-<name> inline { /* brand + gray palettes */ }
• Did I include BOTH selectors?
• Light: :root[data-theme="theme-<name>"], [data-theme="theme-<name>"]
• Dark: [data-theme="theme-<name>"].dark

---

2) Mapping / HTML safety (critical)

• Did I put ONLY custom color palettes inside @theme block?
• The @theme theme-<name> inline { } block should ONLY contain:
• Brand palette: --color-<name>-* (50-950)
• Gray palette: --color-<name>-gray-* (50-950)
• Semantic tokens (--background, --primary, etc.) go in SELECTOR blocks, NOT inside @theme.
• Theme files must NOT change Tailwind mappings.
• Did I introduce any change that requires users to edit HTML utility classes?
• If yes: remove it. Themes must activate via data-theme only.

---

3) Full theme coverage sanity

3.1 Global surfaces + text

• Did I define background tokens?
• --background, --background-1, --background-2, --background-plain
• Did I define foreground tokens?
• --foreground, --foreground-inverse, --inverse

3.2 Borders (full scale)

• Did I define the base border token?
• --border
• Did I define the full border scale?
• --border-line-inverse
• --border-line-1 through --border-line-8
• Is the border scale coherent and usable across different surfaces?

3.3 Primary ramp + states

• Did I define the full primary color ramp?
• --primary-50 through --primary-950 (all 11 shades)
• Do the shades feel like one cohesive family?
• Did I define all primary state tokens?
• --primary, --primary-hover, --primary-focus, --primary-active, --primary-checked
• --primary-line, --primary-foreground
• Is --primary-foreground readable against --primary?

3.4 Secondary / Layer / Surface / Muted / Destructive

• Did I define secondary tokens?
• --secondary, --secondary-line, --secondary-foreground
• --secondary-hover, --secondary-focus, --secondary-active
• Did I define layer tokens?
• --layer, --layer-line, --layer-foreground
• --layer-hover, --layer-focus, --layer-active
• Did I define surface tokens?
• --surface, --surface-1 through --surface-5
• --surface-line, --surface-foreground
• --surface-hover, --surface-focus, --surface-active
• Did I define muted tokens?
• --muted, --muted-foreground, --muted-foreground-1, --muted-foreground-2
• --muted-hover, --muted-focus, --muted-active
• Did I define destructive tokens?
• --destructive, --destructive-foreground
• --destructive-hover, --destructive-focus
• Is destructive visually distinct from primary?

3.5 Component groups (all variants)

• Did I define navbar tokens (base + variants)?
• --navbar, --navbar-line, --navbar-divider, --navbar-inverse
• --navbar-nav-foreground, --navbar-nav-hover, --navbar-nav-focus, --navbar-nav-active
• --navbar-nav-list-divider
• Same pattern for --navbar-1-* and --navbar-2-*
• Did I define sidebar tokens (base + variants)?
• Same pattern as navbar for --sidebar-*, --sidebar-1-*, --sidebar-2-*
• Did I define card tokens?
• --card, --card-line, --card-divider, --card-header, --card-footer, --card-inverse
• Did I define dropdown tokens?
• --dropdown, --dropdown-1, --dropdown-line, --dropdown-divider
• --dropdown-header, --dropdown-footer
• --dropdown-item-foreground, --dropdown-item-hover, --dropdown-item-focus, --dropdown-item-active
• --dropdown-inverse
• Did I define select tokens?
• --select, --select-1, --select-line
• --select-item-foreground, --select-item-hover, --select-item-focus, --select-item-active
• --select-inverse
• Did I define overlay tokens?
• --overlay, --overlay-line, --overlay-divider
• --overlay-header, --overlay-footer, --overlay-inverse
• Did I define popover, tooltip, table, switch, footer tokens?
• --popover, --popover-line
• --tooltip, --tooltip-foreground, --tooltip-line
• --table-line
• --switch
• --footer, --footer-line, --footer-inverse
• Did I define scrollbar tokens?
• --scrollbar-track, --scrollbar-thumb
• --scrollbar-track-inverse, --scrollbar-thumb-inverse

---

4) Chart / Map token safety

• If I included chart tokens, did I keep -hex variants as valid hex values?
• Apexcharts does NOT support oklch format
• Did I include the comment warning about oklch incompatibility?
• Did I define chart tokens coherently?
• --chart-primary, --chart-1 through --chart-10
• --chart-colors-* variants with -hex and -inverse where needed
• If I included map tokens, are they using compatible color formats?
• --map-colors-primary, --map-colors-default, --map-colors-highlight, --map-colors-border
• Plus -inverse variants

---

5) Dark mode completeness

• Did I override all tokens that need different values in dark mode?
• Did I maintain readable contrast in dark mode?
• Text on backgrounds
• Primary foreground on primary background
• Are hover/focus/active states still distinguishable in dark mode?
• Did I use appropriate dark neutral family (e.g., stone, neutral, slate)?

---

6) CSS syntax validation

• Are all braces balanced?
• Are all selectors valid?
• Are there any broken or unclosed comments?
• Are there any duplicate conflicting selectors?
• Did I properly close both the light mode and dark mode selector blocks?

---

7) Behavior overrides (if any)

• If I added radius or other behavior overrides, are they theme-scoped?
• Must be inside @layer utilities with theme selector
• Did I avoid global overrides that affect non-theme pages?

---

Quick validation summary

Before returning, confirm all are true:

• [ ] Imports present and ordered correctly
• [ ] Theme key is theme-<name> everywhere
• [ ] @theme theme-<name> inline { } block contains brand + gray palettes
• [ ] Light selector: :root[data-theme="theme-<name>"], [data-theme="theme-<name>"]
• [ ] Dark selector: [data-theme="theme-<name>"].dark
• [ ] Only color palettes inside @theme block (NO semantic tokens)
• [ ] Full coverage: backgrounds, foregrounds, borders, primary ramp, states
• [ ] Full coverage: secondary, layer, surface, muted, destructive
• [ ] Full coverage: navbar (3 variants), sidebar (3 variants), card, dropdown, select, overlay
• [ ] Full coverage: popover, tooltip, table, switch, footer, scrollbar
• [ ] Chart/map tokens use hex for -hex variants (if included)
• [ ] Dark mode overrides are complete and readable
• [ ] CSS syntax is valid
• [ ] No HTML utility class changes required