JSN UI Theming
OKLCH design tokens, dark mode, and the live theme builder widget.
.skills/jsn-ui-theming.md1480 charsthemingdesign-tokens
.skills/jsn-ui-theming.md
# JSN UI — Theming
JSN UI uses **OKLCH color tokens** declared in `globals.css`. The
design system ships 6 hand-tuned presets; users can override any
token at the CSS variable level.
## Files
- `src/app/globals.css` — the design tokens (light + dark via `.dark`)
- `src/lib/themes.ts` — 6 presets: `default`, `blue`, `purple`, `green`, `orange`, `rose`
- `src/lib/theme-provider.tsx` — `ThemeProvider` + `useTheme()` hook
- `src/components/theme-toggle.tsx` — light / dark / system switcher
## Available tokens
```css
--background /* page bg */
--foreground /* default text */
--card /* card bg */
--card-foreground /* card text */
--primary /* primary actions */
--primary-foreground
--secondary
--secondary-foreground
--muted
--muted-foreground
--accent
--accent-foreground
--destructive
--destructive-foreground
--border
--input
--ring /* focus ring */
--radius /* border-radius scale */
```
All tokens are bound to Tailwind v4 via `@theme inline` in `globals.css`,
so you use them as `bg-background`, `text-foreground`, `border-border`, etc.
## How to apply a preset
```tsx
import { themes } from "@/lib/themes";
useEffect(() => {
const root = document.documentElement;
for (const [k, v] of Object.entries(themes.blue.light)) {
root.style.setProperty(k, v);
}
}, []);
```
## How to add a new theme
1. Open `src/lib/themes.ts`
2. Add a new entry to the `themes` object:
```ts
myTheme: {
light: { "--background": "oklch(0.99 0.005 100)", ... },
dark: { "--background": "oklch(0.16 0.02 100)", ... },
},
```
3. Add the name to the `themeNames` array (auto-derived from keys).
## The Theme Builder
Lives at `/theme`. Lets the user:
- Pick a preset
- Toggle light / dark
- Override any token by hand
- See a live preview (cards + buttons)
- Copy a ready-to-paste CSS snippet
When the user wants to ship their own theme, the recommended flow is:
1. Visit `/theme`
2. Tweak tokens
3. Click "Copy CSS"
4. Paste into their `globals.css` over the existing `:root` block
How to use this skill
These files live in the .skills/ directory of the JSN UI repo. Open Design–compatible agents (Claude Code, Cursor, Cline, etc.) auto-detect them. You can also reference them directly:
# in your agent's config - name: jsn-ui source: https://github.com/javashn/jsn-ui/tree/main/.skills