| name | design-obs-alert-overlay |
| description | Generate an OBS browser-source alert overlay — single 1920×1080 HTML file with TRANSPARENT background and hash-routed scenes for stream events (#follow, |
Skill: obs-alert-overlay
Produces ONE self-contained obs-alert-overlay.html file at 1920×1080 with transparent background that streams compositors (OBS, Streamlabs, Twitch Studio) load as a browser source. The page contains four hash-routed scenes — #follow, #sub, #donation, #raid — each with its own auto-playing entrance animation. Switching scenes is just changing the URL hash.
This is distinct from the stream-overlay skill (which produces persistent scene chrome — starting / brb / webcam / lower-third / ending). This skill produces TRANSIENT alert cards triggered per event.
When to use
- User streams on Twitch / YouTube Live / Kick and wants branded alert cards
- A
DESIGN.md exists for the brand
Inputs
- Required: brand slug
- Optional: alert position (default: lower-right corner; alternates: lower-left, upper-right, top-bar)
- Optional: brand voice for alert copy (e.g. "ack." vs "thanks for the follow." vs "noted." — Shane's brand prefers terse + sentence-case)
Output
./design/<brand-slug>/artifacts/obs-alert-overlay.html (single file — overwrite OK; canonical alert overlay for the brand)
Scenes (default 4)
| Hash | Trigger | Default copy |
|---|
#follow | new follower | " just followed." |
#sub | new subscriber | " subscribed." |
#donation | tip / donation | " sent $." |
#raid | incoming raid | " raided with ." |
Each scene takes scene parameters via URL: obs-alert-overlay.html#follow?name=Sam (or via OBS alert variable substitution per stream tool).
Steps
1. Verify brand exists
test -f ./design/<brand-slug>/tokens.css
2. Gather the brief
Ask in one message:
1. Default alert position — lower-right (default) | lower-left | upper-right | top-bar
2. Brand voice for alert copy — terse ("noted.") | declarative ("just followed.") | warm ("welcome.")
3. Hold duration (seconds) — default 4
4. Any scenes to skip — default: include all 4
3. Pick variation — applies to ALL scenes (consistency for live broadcasts)
Alert cards must read consistently across scene types — viewers shouldn't have to re-parse the visual language for each event type. Pick ONE set:
- Card style:
bracketed (corner-frame L-marks) | chromeless (no border, type-only) | block (solid color block) | hairline (1px border + cream surface)
- Type pressure:
display-led (Fraunces or brand display dominant) | mono-led (mono labels carry it)
- Color usage:
cream-card (cream surface on transparent overlay) | inverted-card (dark ink card on transparent overlay)
- Position:
lower-right (default) | lower-left | upper-right | top-bar
Differentiation between scenes comes from copy + a small mono label ("FOLLOW" / "SUB" / "TIP" / "RAID"), NOT from changing the visual treatment per scene.
4. Generate the HTML
The file structure mirrors stream-overlay: one .scene per hash, JS reveals the active scene. Each .scene contains an .alert-card with auto-playing CSS keyframe animation.
Template:
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title><Brand> — OBS Alert Overlay</title>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=<families>&display=swap">
<style>
<contents of tokens.css>
html, body { margin: 0; padding: 0; width: 1920px; height: 1080px; overflow: hidden; background: transparent; font-family: var(--type-sans-family); color: var(--color-ink); }
.scene { position: fixed; inset: 0; width: 1920px; height: 1080px; display: none; }
.scene.is-active { display: block; }
.alert-card {
position: absolute;
bottom: 80px; right: 80px;
min-width: 480px; max-width: 720px;
padding: 24px 32px;
background: var(--color-surface);
color: var(--color-ink);
border: 1px solid var(--color-rule);
animation: alert-sequence 4800ms cubic-bezier(0.2, 0.6, 0.2, 1) forwards;
}
@keyframes alert-sequence {
0% { transform: translateX(120%); opacity: 0; }
12% { transform: translateX(0); opacity: 1; }
92% { transform: translateX(0); opacity: 1; }
100% { transform: translateX(0); opacity: 0; }
}
.alert-card .label {
font-family: var(--type-mono-family);
font-size: 11px; letter-spacing: 0.18em;
text-transform: uppercase; color: var(--color-ink-3);
margin: 0 0 8px;
}
.alert-card .copy {
font-family: var(--type-display-family);
font-weight: 500; font-size: 32px; line-height: 1.18;
letter-spacing: -0.012em;
margin: 0;
color: var(--color-ink);
}
.alert-card .copy .name { color: var(--color-accent); }
.alert-card--inverted {
background: var(--color-ink); color: var(--color-surface);
border-color: rgba(251, 250, 249, 0.18);
}
.alert-card--inverted .label { color: rgba(251, 250, 249, 0.55); }
.alert-card--inverted .copy { color: var(--color-surface); }
.alert-card--bracketed { border: 0; }
.alert-card--bracketed::before, .alert-card--bracketed::after {
content: ""; position: absolute; width: 12px; height: 12px;
border: 1px solid var(--color-ink);
}
.alert-card--bracketed::before { top: -1px; left: -1px; border-right: none; border-bottom: none; }
.alert-card--bracketed::after { bottom: -1px; right: -1px; border-left: none; border-top: none; }
</style>
</head>
<body>
<section id="scene-follow" class="scene">
<div class="alert-card">
<p class="label">— follow</p>
<p class="copy"><span class="name">[name]</span> just followed.</p>
</div>
</section>
<section id="scene-sub" class="scene">
<div class="alert-card">
<p class="label">— subscriber</p>
<p class="copy"><span class="name">[name]</span> subscribed.</p>
</div>
</section>
<section id="scene-donation" class="scene">
<div class="alert-card">
<p class="label">— tip</p>
<p class="copy"><span class="name">[name]</span> sent $<span class="amount">[amount]</span>.</p>
</div>
</section>
<section id="scene-raid" class="scene">
<div class="alert-card">
<p class="label">— raid</p>
<p class="copy"><span class="name">[name]</span> raided with <span class="count">[count]</span>.</p>
</div>
</section>
<script>
function activateScene() {
var hash = (window.location.hash || '#follow').split('?')[0].slice(1);
var scenes = document.querySelectorAll('.scene');
scenes.forEach(function(el) { el.classList.toggle('is-active', el.id === 'scene-' + hash); });
var params = new URLSearchParams(window.location.hash.split('?')[1] || '');
['name', 'amount', 'count'].forEach(function(key) {
var val = params.get(key);
if (!val) return;
document.querySelectorAll('.scene.is-active .' + key).forEach(function(el) { el.textContent = val; });
});
}
window.addEventListener('hashchange', activateScene);
activateScene();
</script>
</body>
</html>
5. Document the OBS setup for the user
After writing the file:
OBS alert overlay generated at ./design/<brand-slug>/artifacts/obs-alert-overlay.html.
OBS setup (one alert source per scene):
- Sources → Add → Browser
- Local file → point to
obs-alert-overlay.html
- Width: 1920, Height: 1080
- URL hash:
#follow (or other scene)
- Optional dynamic name via query:
…/obs-alert-overlay.html#follow?name={user}
Connect your alert provider (Streamlabs / StreamElements) to trigger a refresh of the browser source per event so the animation re-plays.
Variation: <card-style> × <type-pressure> × <color> × <position>.
6. Verify
Anti-Slop Rules
Governed by three shared canonical references — read them, do not restate them:
../design-anti-patterns.md — the hard floor. Wins every conflict.../design-principles.md — the craft floor (typographic hierarchy, spatial rhythm, color theory, layout logic, visual tension).../design-variation-sop.md — the named-aesthetic roster + the procedure for varying every invocation.
Forbidden (fast scan — the references hold the full list):
- Indigo/violet/purple as default accent or primary — the
hsl(230–280) family on a near-white surface. The single loudest AI tell.
- Purple→blue / "aurora" / gradient-mesh backgrounds; gradient-fill text.
- Glassmorphism without an explicit AA-contrast scrim; floating gradient "blobs" as atmosphere.
- The three-up icon-card feature grid; the "hero → 3 cards → CTA" median skeleton.
- One global border-radius on every element; timid evenly-weighted low-contrast palette.
- Inter / Roboto / Arial / Open Sans / Lato / Helvetica / system as the primary family (Space Grotesk = yellow flag). Use a category-matched stack from the variation roster.
- Value-free CTAs ("Get Started", "Learn More", "Sign Up"); the two-CTA hero. Name the real action and its value.
Required variation (every invocation):
- Make at least two intentional decisions that differ from the safe defaults (palette, layout structure, typographic voice, or spatial density) AND from the most recent artifact in this brand.
- Never default to "clean / minimal / modern" — that is the absence of a direction (variation-sop Rule 1).
- Sketch three distinct directions, offer them as a one-line menu, generate the best-fit by default, all three only if asked (variation-sop Rule 3).
Authenticity: prefer specific over generic everywhere — real datelines (not "today"), the brand's actual voice (not "build the future" filler), concrete CTAs over placeholders.
Rules
- Single file always. OBS loads one URL; multiple files would defeat the purpose.
- Transparent background — hard requirement.
body { background: transparent } must be present.
- One animation per scene. Slide-in + hold + fade is ONE sequence. Adding a separate spinner or pulse would be two animations — forbidden.
- No sound. This is a visual artifact. Audio belongs to the streaming software's alert config, not the overlay.
- Dynamic substitution via URL query. Name, amount, count are passed in by the streaming tool — the artifact must accept them via
?name=... parsing.
- Token-pure. Same rules as other platform skills.
- Anti-pattern compliance. This skill defers to three shared canonical references:
../design-anti-patterns.md (the hard floor — wins every conflict), ../design-principles.md (the craft floor), and ../design-variation-sop.md (direction roster + offer-3 procedure). The anti-patterns file is the canonical anti-tell list.
