BetterSEQTA-Plus/.cursor/skills/theme-authoring/SKILL.md

name, description

name	description
theme-authoring	Creates BetterSEQTA+ custom themes as `.theme.json` files for import or publishing to the BetterSEQTA theme store. Use when the user asks to make a new theme, adjust theme colors/CSS, or prepare a theme JSON for upload.

Theme authoring (BetterSEQTA+)

Goal

Produce a valid *.theme.json file that BetterSEQTA+ can install (via theme import or store download).

Output contract

Return:

• The final theme JSON (ready to save as my-theme.theme.json)
• A short list of the main palette values used (accent + background + text)

Theme JSON schema (practical)

Required keys:

• id: string (stable identifier; use kebab-case, e.g. banana-theme)
• name: string (display name)
• description: string
• defaultColour: string CSS color (e.g. rgb(...) or #RRGGBB)
• CanChangeColour: boolean
• CustomCSS: string (CSS applied as a <style> tag)

Common optional keys:

• hideThemeName: boolean
• forceTheme: boolean (when true, the theme forces light/dark)
• forceDark: boolean (when forcing, true = dark, false = light)
• images: array of { id, variableName, data } where data is base64 PNG (no prefix required, but allowed)
• coverImage: base64 image string (optional)
• adaptiveCssVariables: string[] (advanced; see below)

Workflow

1) Pick a theme concept + palette

Decide:

• Accent: set as defaultColour
• Surfaces: --background-primary, --background-secondary
• Text: set --theme-fg-parts to a readable RGB triple

If the theme is intended to be “bright” and friendly, default to forced light:

• forceTheme: true, forceDark: false

If it’s intended to be “night/dark”, default to forced dark:

• forceTheme: true, forceDark: true

2) Write CustomCSS

Use a consistent, minimal set of overrides:

• In :root set:
  • --background-primary, --background-secondary
  • --theme-offset-bg, --theme-offset-bg-more (slightly darker/lighter than secondary)
  • --theme-bg-parts, --theme-sel-bg-parts, --theme-fg-parts (RGB triples)
• Set the page background on:
  • html, body, #container, #content
  • Use 2–3 subtle radial-gradient(...) layers + a linear-gradient(...)
  • Finish with , var(--background) !important; so custom backgrounds still work

Recommended template (edit values and gradient stops):

{
  "id": "my-theme",
  "name": "My Theme",
  "description": "One-line vibe description.",
  "defaultColour": "rgb(123, 100, 200)",
  "CanChangeColour": true,
  "hideThemeName": false,
  "forceTheme": true,
  "forceDark": false,
  "CustomCSS": ":root {\\n  --background-primary: rgb(255, 255, 255) !important;\\n  --background-secondary: rgb(235, 235, 235) !important;\\n  --theme-offset-bg: rgb(245, 245, 245) !important;\\n  --theme-offset-bg-more: rgb(225, 225, 225) !important;\\n  --theme-bg-parts: 255, 255, 255 !important;\\n  --theme-sel-bg-parts: 123, 100, 200 !important;\\n  --theme-fg-parts: 20, 20, 20 !important;\\n}\\n\\nhtml,\\nbody,\\n#container,\\n#content {\\n  background-image:\\n    radial-gradient(circle at 18% 18%, rgb(123 100 200 / 20%) 0%, transparent 40%),\\n    radial-gradient(circle at 82% 78%, rgb(123 100 200 / 14%) 0%, transparent 46%),\\n    linear-gradient(145deg, rgb(255 255 255) 0%, rgb(245 245 245) 55%, rgb(235 235 235) 100%),\\n    var(--background) !important;\\n  background-size: auto, auto, auto, cover !important;\\n  background-position: center, center, center, center !important;\\n  background-repeat: no-repeat !important;\\n  background-attachment: fixed !important;\\n}\\n\"\n+}

3) Validate mentally (fast checks)

• Contrast: --theme-fg-parts must be readable on both primary and secondary backgrounds.
• Forcing: if forceTheme: true, ensure forceDark matches the palette.
• No hard dependency on images unless you include images.

4) Hand off

Name the file as: <id>.theme.json (e.g. banana.theme.json).

Advanced: adaptiveCssVariables (optional)

Use only when you want the theme to react cleanly to Adaptive Theme Colour in BetterSEQTA+.

What it does:

• It requests the app to write values derived from the current --better-main into CSS custom properties you list.
• Supports channel bindings by suffix:
  • --my-var:r (red channel as 0..255)
  • --my-var:g (green channel)
  • --my-var:b (blue channel)
  • --my-var (full colour string)

When to use:

• Your theme does math/mixing in CSS and needs stable numeric channels.

When NOT to use:

• Most themes. If your theme looks good with a fixed palette, omit it.