npm install

AI-ready resources

Copy-paste prompt templates for Claude, Cursor, ChatGPT, GitHub Copilot, and v0.dev. Each prompt gives your AI assistant the exact context it needs to wire up salt-theme-gen correctly — no back-and-forth, no hallucinated API.

/llms.txt · Machine-readable API spec for AI assistants

Token name cheatsheet

These are the CSS variable names your AI assistant should use. Paste the table below as context when working in any file.

Category CSS variable pattern Examples
Colors var(--salt-color-{name}) --salt-color-primary, --salt-color-background, --salt-color-text, --salt-color-muted, --salt-color-border, --salt-color-danger, --salt-color-success, --salt-color-on-primary
Tonal palettes var(--salt-palette-{intent}-{step}) --salt-palette-primary-50, --salt-palette-primary-500, --salt-palette-danger-50, --salt-palette-danger-700 (steps: 50–950)
Surfaces var(--salt-surface-{name}) --salt-surface-card, --salt-surface-elevated, --salt-surface-modal, --salt-surface-popover
States var(--salt-state-{intent}-{state}) --salt-state-primary-hover, --salt-state-primary-pressed, --salt-state-primary-focused, --salt-state-primary-disabled, --salt-state-danger-hover
Spacing var(--salt-spacing-{size}) --salt-spacing-xs (4px), --salt-spacing-sm (8px), --salt-spacing-md (12px), --salt-spacing-lg (16px), --salt-spacing-xl (24px), --salt-spacing-xxl (32px)
Radius var(--salt-radius-{size}) --salt-radius-sm (6px), --salt-radius-md (10px), --salt-radius-lg (14px), --salt-radius-xl (20px), --salt-radius-pill (9999px)
Font sizes var(--salt-font-size-{size}) --salt-font-size-xs (12px), --salt-font-size-sm (14px), --salt-font-size-md (16px), --salt-font-size-lg (18px), --salt-font-size-xl (20px), --salt-font-size-xxl (24px), --salt-font-size-3xl (32px)

Generic setup prompt

Works with any framework. Paste this into Claude, Cursor, or ChatGPT when starting a new project or adding tokens to an existing one. 

Add salt-theme-gen design tokens to this project.

INSTALL
npm install salt-theme-gen

GENERATE THEME + CSS VARIABLES
Create src/theme.ts (or src/theme.js):
  import { generateTheme, generateCssVariables } from 'salt-theme-gen';

  export const theme = generateTheme({
    preset: 'ocean',      // one of 20 built-in presets, or primary: '#6366f1' for a hex color
    spacing:  'default',  // 'compact' | 'default' | 'relaxed' | 'spacious'
    radius:   'default',  // 'sharp' | 'default' | 'rounded' | 'pill'
    fontSize: 'default',  // 'small' | 'default' | 'large' | 'editorial'
  });

  export const { css: themeCSS } = generateCssVariables(theme, { format: 'both' });
  // themeCSS is a ready-to-inject stylesheet string with 150+ --salt-* CSS variables
  // format: 'both' = hex fallback + @supports oklch() for modern browsers

INJECT CSS VARIABLES INTO <head>
  const style = document.createElement('style');
  style.textContent = themeCSS;
  document.head.prepend(style);

  // Or at build time — write to a static file:
  // import { writeFileSync } from 'node:fs';
  // writeFileSync('public/theme.css', themeCSS, 'utf8');

DARK MODE
- Toggle dark mode by setting data-theme="dark" on <html>
- Persist with localStorage.setItem('theme', 'dark')
- Read preference on page load with a synchronous inline script (before CSS loads):
  <script>(function(){var t=localStorage.getItem('theme');if(t)document.documentElement.setAttribute('data-theme',t);})();</script>

REPLACE ALL HARDCODED VALUES
Replace every hex/rgb/hsl color with the appropriate --salt-* CSS variable:
  - Brand/action colors → var(--salt-color-primary), var(--salt-color-secondary)
  - Page background → var(--salt-color-background)
  - Card/panel background → var(--salt-color-surface) or var(--salt-surface-card)
  - Body text → var(--salt-color-text)
  - Secondary text → var(--salt-color-muted)
  - Dividers/borders → var(--salt-color-border)
  - Error states → var(--salt-color-danger)
  - Success states → var(--salt-color-success)
  - Padding/gap/margin → var(--salt-spacing-sm), var(--salt-spacing-md), etc.
  - Border radius → var(--salt-radius-md), var(--salt-radius-lg)
  - Font size → var(--salt-font-size-sm), var(--salt-font-size-md), etc.
  - Hover state → var(--salt-state-primary-hover)
  - Focus ring → var(--salt-state-primary-focused)
  - Disabled → var(--salt-state-primary-disabled)
  - Badge tint backgrounds → var(--salt-palette-danger-50), var(--salt-palette-danger-700)

DO NOT hardcode any color, spacing, or font size value anywhere.
DO NOT write a custom loop to serialize theme tokens — always use generateCssVariables().

Framework-specific prompts

Each prompt is self-contained — it assumes salt-theme-gen is already installed and provides the full implementation pattern for that framework.

React ThemeContext + CSS injection 
Wire up salt-theme-gen in this React project:

1. Create src/theme/index.ts:
   import { generateTheme, generateCssVariables } from 'salt-theme-gen';
   export const theme = generateTheme({ preset: 'ocean' });
   export const { css: themeCSS } = generateCssVariables(theme, { format: 'both' });

2. In src/main.tsx, before ReactDOM.createRoot, inject CSS vars:
   import { themeCSS } from './theme';
   const style = document.createElement('style');
   style.textContent = themeCSS;
   document.head.prepend(style);

3. Add an inline <script> in index.html <head> (synchronous, no defer/async):
   (function(){var t=localStorage.getItem('theme');if(t)document.documentElement.setAttribute('data-theme',t);})();

4. Create src/theme/ThemeContext.tsx:
   - Context with { isDark, toggle }
   - Reads localStorage on init, matches OS with matchMedia('(prefers-color-scheme: dark)')
   - On toggle: sets data-theme on document.documentElement + saves to localStorage
   - Export useTheme() hook

5. Wrap <App /> in ThemeProvider in main.tsx

6. Replace all hardcoded colors/spacing with --salt-* CSS variables:
   background: var(--salt-color-primary), padding: var(--salt-spacing-md), etc.
Next.js App Router, no FOUC 
Add salt-theme-gen to this Next.js App Router project:

1. Create src/lib/theme.ts:
   import { generateTheme, generateCssVariables } from 'salt-theme-gen';
   export const theme = generateTheme({ preset: 'ocean' });
   export const { css: themeCSS } = generateCssVariables(theme, { format: 'both' });

2. In app/layout.tsx (root layout):
   - Inject via <style dangerouslySetInnerHTML={{ __html: themeCSS }} />
   - Add suppressHydrationWarning to <html>
   - Add inline <script> in <head> that reads localStorage and sets data-theme synchronously:
     (function(){var t=localStorage.getItem('theme');if(t)document.documentElement.setAttribute('data-theme',t);})();

3. Create src/components/ThemeProvider.tsx as a Client Component ('use client'):
   - Manages isDark state, syncs to data-theme attribute
   - Exports useTheme() hook via context

4. Wrap children in RootLayout with ThemeProvider

5. Replace all hardcoded colors with --salt-* CSS variables:
   background: var(--salt-color-primary), border-radius: var(--salt-radius-md), etc.
Vue 3 Composable + provide/inject 
Add salt-theme-gen to this Vue 3 project:

1. Create src/theme/index.ts:
   import { generateTheme, generateCssVariables } from 'salt-theme-gen';
   export const theme = generateTheme({ preset: 'ocean' });
   export const { css: themeCSS } = generateCssVariables(theme, { format: 'both' });

2. In src/main.ts, before app.mount():
   import { themeCSS } from './theme';
   const style = document.createElement('style');
   style.textContent = themeCSS;
   document.head.prepend(style);

3. Create src/composables/useThemeMode.ts:
   - module-level ref isDark (shared state, not per-component)
   - toggle() function: flips isDark, sets data-theme on documentElement, saves localStorage
   - Returns { isDark, toggle }

4. In App.vue, provide('theme', { isDark, toggle }) for deep component access

5. Inject in child components with useTheme() composable that wraps inject('theme')

6. Replace hardcoded values with --salt-* CSS variables
SvelteKit Writable store + svelte:head 
Add salt-theme-gen to this SvelteKit project:

1. Create src/lib/theme.ts — generateTheme({ preset: 'ocean' })

2. Create src/lib/stores/theme.ts:
   - writable<'light'|'dark'>('light') store
   - init() reads localStorage and matchMedia on client
   - subscribe to update data-theme attribute on document.documentElement

3. In src/routes/+layout.svelte:
   - Call init() in onMount
   - Use {@html themeCSS} inside <svelte:head> for CSS injection
   - Or: generate static/theme.css via a script and <link> it in app.html

4. Add synchronous inline script to src/app.html <head>:
   <script>
     var t = localStorage.getItem('theme');
     if (t) document.documentElement.setAttribute('data-theme', t);
   </script>

5. In components, import { theme } from '$lib/stores/theme' and use $theme for reactivity
Angular Injectable service + signals 
Add salt-theme-gen to this Angular project:

1. Create src/app/theme/theme.service.ts:
   - @Injectable({ providedIn: 'root' })
   - Inject DOCUMENT
   - isDark = signal(false)
   - In constructor: read localStorage, call applyMode()
   - applyMode(dark: boolean): sets data-theme attribute, calls injectCSS()
   - injectCSS(): creates <style id="salt-theme"> with CSS vars from theme.light/.dark
   - toggle(): isDark.set(!isDark()), calls applyMode, saves localStorage

2. In src/main.ts, after bootstrapApplication:
   appRef.injector.get(ThemeService); // eager instantiation

3. CSS variables work through ViewEncapsulation.Emulated — add ::ng-deep or
   use :host-context([data-theme="dark"]) for dark-mode overrides in component styles

4. Inject ThemeService in components that need the toggle button
Tailwind CSS Extend config with CSS vars 
Wire salt-theme-gen tokens into this Tailwind CSS project:

1. Create src/theme.ts and generate CSS variables:
   import { generateTheme, generateCssVariables, generateTailwindConfig } from 'salt-theme-gen';
   export const theme = generateTheme({ preset: 'ocean' });
   export const { css: themeCSS } = generateCssVariables(theme, { format: 'both' });
   export const { extend } = generateTailwindConfig(theme);

2. Inject themeCSS into <head> (or write to public/theme.css)

3. Update tailwind.config.ts:
   import { extend } from './src/theme';
   export default {
     darkMode: ['selector', '[data-theme="dark"]'],
     theme: { extend },
   };
   // All --salt-* tokens are now available as Tailwind utilities:
   // bg-salt-primary, text-salt-on-primary, p-salt-md, rounded-salt-md
   // bg-salt-palette-danger-50, text-salt-palette-danger-700

4. Replace arbitrary Tailwind values (bg-[#2563eb]) with salt token classes (bg-salt-primary)
5. Dark mode: data-theme="dark" toggles automatically — no dark: variants needed
React Native No CSS variables — JS objects 
Add salt-theme-gen to this React Native project:

IMPORTANT: React Native does not support CSS custom properties.
Use the GeneratedThemeMode JS object directly.

1. Create src/theme/index.ts:
   import { generateTheme } from 'salt-theme-gen';
   export const theme = generateTheme({ preset: 'ocean' });

2. Create src/theme/ThemeContext.tsx:
   - Context with mode: GeneratedThemeMode, isDark: boolean, toggle()
   - useColorScheme() from react-native for OS preference
   - AsyncStorage for persistence (@react-native-async-storage/async-storage)
   - Preference: 'light' | 'dark' | 'system'

3. Wrap app root with ThemeProvider

4. In screens/components:
   const { mode } = useTheme();
   const styles = useMemo(() => StyleSheet.create({
     container: { backgroundColor: mode.colors.background },
     text:       { color: mode.colors.text, fontSize: mode.fontSizes.md },
     card:       { backgroundColor: mode.surfaceElevation.card,
                   borderRadius: mode.radius.lg, padding: mode.spacing.xl },
   }), [mode]);

5. Always use useMemo([mode]) — avoids recreating StyleSheet on every render
Astro Fragment set:html + is:inline script 
Add salt-theme-gen to this Astro project:

1. Create src/lib/theme.ts:
   import { generateTheme, generateCssVariables } from 'salt-theme-gen';
   export const theme = generateTheme({ preset: 'ocean' });
   export const { css: themeCSS } = generateCssVariables(theme, { format: 'both' });

2. In src/layouts/BaseLayout.astro <head>:
   <Fragment set:html={`<style>${themeCSS}</style>`} />

   IMPORTANT: Use Fragment set:html, NOT a regular <style> tag.
   A regular <style> gets scoped by Astro and loses [data-theme='dark'] selectors.

3. Add a synchronous inline script for FOUC prevention:
   <script is:inline>
     var t = localStorage.getItem('theme');
     if (t) document.documentElement.setAttribute('data-theme', t);
   </script>

4. For typed token access in React/Vue islands, generate theme server-side and
   pass as props: <ReactIsland lightColors={theme.light.colors} />

5. Use --salt-* CSS variables in all .astro component <style> blocks:
   background: var(--salt-color-primary); padding: var(--salt-spacing-md);

Using with Claude Code

Claude Code has full access to your file system and can run npm install. These prompts work in both interactive chat and /loop mode.

Add tokens to an existing project
Install salt-theme-gen and add its design tokens to this project.
Run: npm install salt-theme-gen
Then:
1. Call generateTheme({ preset: 'ocean' }) to generate the theme
2. Call generateCssVariables(theme, { format: 'both' }) to get the CSS stylesheet string
3. Inject the CSS into the <head> (or write to a static file)
4. Replace all hardcoded color/spacing values with --salt-* CSS variables
All token names use the --salt- prefix: --salt-color-primary, --salt-spacing-md, etc.
Do not touch any existing business logic — only replace style values.
Change preset
Change the salt-theme-gen preset from ocean to rose.
Find the generateTheme() call and update the preset argument only.
No other changes needed — token names stay the same, values update automatically.
Audit hardcoded values
Audit this project for hardcoded color values.
Search for: hex colors (#xxx, #xxxxxx), rgb(), rgba(), hsl(), hsla()
List every file and line where they appear.
Then replace each one with the appropriate salt-theme-gen CSS variable.
Map: brand/primary colors → var(--salt-color-primary), backgrounds → var(--salt-color-background),
text → var(--salt-color-text), danger → var(--salt-color-danger), etc.
All variables use the --salt- prefix. Do not use --color-* or --space-* (those are wrong).
Add dark mode toggle component
Add a dark mode toggle button to this project that uses salt-theme-gen.
The button should:
- Toggle data-theme="dark" on document.documentElement
- Persist preference in localStorage under key 'theme'
- Show sun/moon icons for current state
- Apply the toggle without a full page reload
Assume CSS variables for light/dark are already injected via salt-theme-gen.

Cursor rules / Copilot instructions

Add these rules to .cursorrules, .cursor/rules/*.mdc, or .github/copilot-instructions.md to enforce token usage project-wide. 

# Design token rules — salt-theme-gen

This project uses salt-theme-gen CSS custom properties for all design values.
All variables use the --salt- prefix. DO NOT use any other variable naming convention.

## REQUIRED in all files — use these exact CSS variable names:

Colors (23 semantic):
  var(--salt-color-primary)     var(--salt-color-secondary)    var(--salt-color-tertiary)
  var(--salt-color-background)  var(--salt-color-surface)      var(--salt-color-text)
  var(--salt-color-muted)       var(--salt-color-border)
  var(--salt-color-danger)      var(--salt-color-success)      var(--salt-color-warning)  var(--salt-color-info)
  var(--salt-color-on-primary)  var(--salt-color-on-danger)    var(--salt-color-on-success)

Tonal palette steps (for badges, charts, tinted backgrounds):
  var(--salt-palette-primary-50)   var(--salt-palette-primary-500)   var(--salt-palette-primary-900)
  var(--salt-palette-danger-50)    var(--salt-palette-danger-700)
  (pattern: --salt-palette-{intent}-{step}, steps: 50 100 200 300 400 500 600 700 800 900 950)

Surface elevation:
  var(--salt-surface-card)  var(--salt-surface-elevated)  var(--salt-surface-modal)  var(--salt-surface-popover)

Interaction states:
  var(--salt-state-primary-hover)    var(--salt-state-primary-pressed)
  var(--salt-state-primary-focused)  var(--salt-state-primary-disabled)
  (also: -secondary-, -danger-, -success-, -warning-, -info- variants)

Spacing: var(--salt-spacing-xs) var(--salt-spacing-sm) var(--salt-spacing-md) var(--salt-spacing-lg) var(--salt-spacing-xl) var(--salt-spacing-xxl)
Radius:  var(--salt-radius-sm) var(--salt-radius-md) var(--salt-radius-lg) var(--salt-radius-xl) var(--salt-radius-pill)
Font:    var(--salt-font-size-xs) var(--salt-font-size-sm) var(--salt-font-size-md) var(--salt-font-size-lg) var(--salt-font-size-xl) var(--salt-font-size-xxl) var(--salt-font-size-3xl)

## NEVER
- Do not write hex values, rgb(), rgba(), hsl(), hsla() in any stylesheet or inline style
- Do not write hardcoded pixel sizes for colors, spacing, or font sizes
- Do not add new design values — use the existing token set
- Do not use --color-*, --space-*, --radius-*, --text-* (these are the OLD names — wrong)
- Do not write a modeToVars/modeToCSS function — use generateCssVariables() from the library

## Dark mode
- Toggle by setting data-theme="dark" on <html>
- Never duplicate CSS rules for dark mode — use the CSS variable system
- Token values automatically update between light/dark modes

For Cursor, save as .cursor/rules/design-tokens.mdc with alwaysApply: true to enforce tokens in every file the AI touches.

/llms.txt

A machine-readable spec at /llms.txt documents the full salt-theme-gen API for AI assistants. Load it into your context when working on complex integrations.

Load in Claude
Read the file at https://learn.esalt.net/llms.txt for the complete salt-theme-gen API reference, then help me [task].
Load in Cursor
@https://learn.esalt.net/llms.txt Help me wire up salt-theme-gen in this project.
Load in ChatGPT
Here is the salt-theme-gen API reference: [paste contents of /llms.txt]
Now help me [task].