Theme tutorial: colors to CSS

Start with a colors theme, then upgrade to packaged CSS when needed. Index → Workshop SDK.

The AI theme guide produces echo-next.custom-theme JSON for Settings import. Workshop themes are separate packages published through the SDK and Steam. Do not mix formats.

Pick a tier

Tier	What changes	Min ECHO	Start with
colors	Light/dark hex tones	26.8.15	--recipe colors-theme
skin	Declarative chrome / stages	26.8.15	--recipe skin-theme
stylesheet	Packaged CSS	26.8.20	--recipe css-theme
runtime	Sandboxed HTML/CSS/JS UI	26.8.20	--recipe custom-ui

Upgrade without restarting:

node .\bin\echo-workshop-sdk.mjs scaffold .\my-theme --preset stylesheet

Walkthrough A: minimal colors theme

1. Copy the official example:

   node .\bin\echo-workshop-sdk.mjs example minimal-theme .\harbor-colors
   cd .\harbor-colors

2. Edit content/theme.json — change hex values under light / dark.
3. Keep basePreset on a public preset such as classic. Do not use FINAL, nyanCat, or darkSideMoon.
4. Verify:

   npm run check
   npm run dev

5. Replace preview.png (256×256) and update listing copy with npm run set -- --title "Your title".

For colors tier, set compatibility.minEchoVersion to 26.8.15 in the outer manifest.

Walkthrough B: packaged CSS theme

1. Create or upgrade:

   node .\bin\echo-workshop-sdk.mjs init .\harbor-css --recipe css-theme
   cd .\harbor-css

   Or: scaffold . --preset stylesheet on an existing project.
2. Edit content/theme.css. Every rule must sit under your pack id:

   html[data-workshop-theme-pack="echo.harbor-css"] {
     --color-bg: #10131a;
     --color-text: #d8e8f3;
     color-scheme: dark;
   }

3. Set minEchoVersion to 26.8.20 or newer.
4. npm run check → npm run dev for fixture preview and gate summary.

Inline scripts, remote @import, and non-raster url() values are rejected. Stylesheet overrides skin; runtime replaces visible chrome but must keep emergency-exit host chrome.

Walkthrough C: runtime UI (overview)

--recipe custom-ui or scaffold . --preset runtime generates content/ui/. See .echo-sdk/echo-workshop-ui-runtime.d.ts for the postMessage bridge.

node .\bin\echo-workshop-sdk.mjs snippet ui-runtime-init
node .\bin\echo-workshop-sdk.mjs guide theme

Before publish

• Clean npm run check
• Non-placeholder 256×256 preview.png
• minEchoVersion matches the oldest ECHO you tested
• CSS selector pack id matches manifest id
• Use once in ECHO Authoring Studio

User subscribe/use flow → Steam Workshop.