Skinning Guide v2.0

Quick Start

cp -r ~/Moltamp/skins/_template ~/Moltamp/skins/my-skin

1. Edit skin.json with your info
2. Edit theme.css — set your palette in :root, style elements with var()
3. Drop art in assets/, reference as url('./assets/file.ext')
4. Open MOLTamp Settings → Skins, select your skin

The Rules

Non-negotiable. The validator enforces them.

1. All colors live in :root

Every color value must be a CSS variable in :root. Never hardcode a color in a selector.

/* WRONG */
.moltamp-panel-left { background: #070b07; }

/* RIGHT */
:root { --skin-panel-bg: #070b07; }
.moltamp-panel-left { background: var(--skin-panel-bg); }

Why: Color overrides inject a :root block on top of your skin. Hardcoded colors can't be reached.

2. Contract variables come first

The 6 chrome and 21 terminal variables are the contract. Override them in :root. Extend with --skin-* prefixed variables.

3. Never hide panels

No display: none on panels. Users toggle visibility in Settings. Style them freely — visibility is the user's choice.

4. No executable content

• No external URLs (https:, http:)
• No @import
• No expression(), javascript:
• CSS only. Zero JS.

5. Don't hide the permission dialog

These trigger validator warnings: visibility: hidden, opacity: 0, pointer-events: none

6. No backgrounds on .moltamp-vibes

The vibes panel is always transparent. Visual content must come from GIF widget slots in skin.json, not CSS background. MOLTamp strips vibes backgrounds at load time.

7. Pseudo-elements need pointer-events: none

Every ::before and ::after must include pointer-events: none. Without it, they block right-click menus, drag handles, and widget interaction. Auto-fixed at load time, but declare it explicitly.

.moltamp-panel-right::before {
  content: '';
  position: absolute;
  inset: 0;
  background: var(--skin-overlay);
  pointer-events: none;  /* always include this */
}

8. Assets stay in assets/

• Reference with url('./assets/filename.ext')
• Supported: PNG, JPG, WebP, GIF, SVG, AVIF
• Max 5MB per file, 20MB per skin
• No nested directories, no path traversal

Skin Format

skins/my-skin/
  skin.json          ← Required: manifest
  theme.css          ← Required: all styles
  assets/            ← Optional: images, GIFs, SVGs

skin.json

{
  "id": "my-skin",
  "name": "My Skin",
  "version": "1.0.0",
  "author": "Your Name",
  "description": "A short description.",
  "engine": "1.0"
}

All fields required. id must match ^[a-zA-Z0-9_-]+$.

Variable Contract

Override these in :root. This is the API between MOLTamp and your skin.

Terminal Colors (21 vars)

Chrome Colors (6 vars)

Effects (6 vars)

Typography & Layout

Targetable Elements

Layout

Terminal

The Vibes Panel

The .moltamp-vibes div is your hero canvas.

Backgrounds are not allowed on .moltamp-vibes. The vibes panel is always transparent — all visual content (GIFs, images) must come from GIF widget slots defined in skin.json, not from CSS background or background-image. MOLTamp enforces this with an !important override at load time.

// skin.json
{
  "vibes": {
    "slots": [
      { "widgetId": "gif", "gifSrc": "assets/vibes.gif", "gifFit": "cover" }
    ]
  }
}

Use ::before and ::after for overlay effects — these are still allowed:

.moltamp-vibes::before {
  content: '';
  position: absolute;
  inset: 0;
  background: var(--skin-overlay);
  mix-blend-mode: multiply;
  pointer-events: none;
}

Reactive Data Attributes

Set on .moltamp-shell — changes with Claude's state.

Activity Level

Shell State

Live CSS Properties

Set on .moltamp-shell for data-driven visuals:

Example: Context gauge as pie chart:

.moltamp-context-gauge {
  width: 80px; height: 80px;
  border-radius: 50%;
  background: conic-gradient(
    var(--c-chrome-accent) calc(var(--data-context-pct) * 1%),
    var(--c-chrome-border) 0
  );
}

Reactive Animations

Bind animations to data attributes:

[data-activity="high"] .moltamp-vibes {
  filter: brightness(1.2) saturate(1.1);
  animation: skin-glow 2s ease-in-out infinite;
}

[data-shell-state="thinking"] .moltamp-vibes {
  animation: skin-pulse 1.5s ease-in-out infinite;
}

[data-shell-state="error"] .moltamp-vibes {
  box-shadow: inset 0 0 20px var(--skin-error-color);
}

Prefer transform and opacity for performance. Keep durations under 5s.

Sharing

Export: Settings → Skins → Export — saves as .zip

Import: Settings → Skins → Import — select .zip

Preflight (Auto-Fixes)

MOLTamp applies these overrides after your skin CSS loads. They protect users from common mistakes — especially in AI-generated skins.

For AI-generated skins

If using ChatGPT, Claude, or another AI to generate a skin, paste this with your prompt:

Rules: All colors must be CSS variables in :root.
Use --skin-* prefix for custom vars.
Never set background on .moltamp-vibes — use skin.json vibes slots for images.
Every ::before/::after MUST have pointer-events: none.
No external URLs, no @import, no JS.

Pre-Share Checklist

• All colors defined as variables in :root
• Zero hardcoded hex/rgb outside :root
• Contract variables (--c-*, --t-*) overridden
• Custom variables use --skin-* prefix
• No background or background-image on .moltamp-vibes (use GIF widget slots)
• Every ::before/::after has pointer-events: none
• No external URLs or @import
• Assets under 5MB each, 20MB total
• Tested at different panel sizes
• Right-click context menus work on all panels
• Permission dialog still visible