boraoztunc/skills

# Adversarial Review

A normal review confirms a change looks right. An **adversarial** review assumes it is
broken and tries to prove it — then refuses to trust its own findings until each one
survives an independent attempt to refute it. The output is not "looks good" or a list
of nitpicks; it is a ranked set of *concrete failure scenarios that withstood scrutiny*,
plus an honest account of what could not be checked.

Use this when the cost of a missed bug is high: before shipping, on a large or
half-finished diff, on a new code path with no test history, or any time the user says
"try to break this."

## The stance (this is the whole skill)

# Analytics Tracking

You are an expert in analytics implementation and measurement. Your goal is to help set up tracking that provides actionable insights for marketing and product decisions.

## Initial Assessment

**Check for product marketing context first:**
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.

Before implementing tracking, understand:

1. **Business Context** - What decisions will this data inform? What are key conversions?
2. **Current State** - What tracking exists? What tools are in use?
3. **Technical Context** - What's the tech stack? Any privacy/compliance requirements?

# Anime.js for HyperFrames

HyperFrames can seek Anime.js instances through its `animejs` runtime adapter. The composition owns the animation objects; HyperFrames owns the clock.

## Contract

- Create animations or timelines synchronously during composition initialization.
- Set `autoplay: false` so Anime.js does not advance on its own clock.
- Register every returned animation or timeline on `window.__hfAnime`.
- Use finite durations and loop counts.
- Avoid callbacks that mutate DOM based on wall-clock time, network state, or unseeded randomness.

The adapter seeks every registered instance with `instance.seek(timeMs)`, where `timeMs` is HyperFrames time in milliseconds.

# App Store Screenshots Generator

## Overview

Build a Next.js page that renders iOS App Store screenshots as **advertisements** (not UI showcases) and exports them via `html-to-image` at Apple's required resolutions. Screenshots are the single most important conversion asset on the App Store.

## Core Principle

**Screenshots are advertisements, not documentation.** Every screenshot sells one idea. If you're showing UI, you're doing it wrong — you're selling a *feeling*, an *outcome*, or killing a *pain point*.

## Step 1: Ask the User These Questions

Before writing ANY code, ask the user all of these. Do not proceed until you have answers:

# Apple Design

How Apple builds interfaces that stop feeling like a computer and start feeling like an extension of you. This knowledge comes from Apple's WWDC design talks — chiefly *Designing Fluid Interfaces* (WWDC 2018) — distilled and translated into the web platform (CSS, Pointer Events, `requestAnimationFrame`, spring libraries like Motion/Framer Motion).

The through-line: **an interface feels alive when motion starts from the current on-screen value, inherits the user's velocity, projects momentum forward, and can be grabbed and reversed at any instant.** Springs are the tool that makes all of this natural, because they are inherently interruptible and velocity-aware.

## The Core Idea

> "When we align the interface to the way we think and move, something magical happens — it stops feeling like a computer and starts feeling like a seamless extension of us."

An interface is fluid when it behaves like the physical world: things respond instantly, move continuously, carry momentum, resist at boundaries, and can be redirected mid-motion. Everything below is a way to get closer to that.

Apple frames design as serving four human needs: **safety/predictability, understanding, achievement, and joy.** Every rule here serves one of them.

# Beam Glow States

Use the beam as a decorative state accent. Keep the state understandable through text, shape, contrast, and the correct semantic attribute when the animation is absent.

The API below was verified against `border-beam` 1.3.0. Recheck the official README and exported types when the installed version changes.

## Install and import

Install the same package with the repository's package manager:

```bash
npm install border-beam
pnpm add border-beam
yarn add border-beam

# Beautiful Shadows

## Use When
- A surface needs polished, layered elevation.
- Default Tailwind shadows feel too generic or blunt.
- The design needs neutral, refined depth without colored glow.

## Shadow Utilities
Use these exact Tailwind classes.

### Beautiful sm
Use for compact cards, form controls, pills, and quieter surfaces.

```txt

# Accessibility that comes with the craft

Accessibility is not a compliance checkbox bolted on at the end; it is the floor for interface craft. Most of it is free if you use the platform: native elements ship with keyboard support, real labels announce themselves, and a visible focus ring is one CSS rule. Apply these principles when building or reviewing UI code, and write every fix in the project's own idiom: the styling system already in use, never a second one alongside it.

When reviewing, walk the interface as a keyboard-only user first (every flow must complete without a mouse), then as a screen-reader user: does each control announce a name, a role, and its state? When unsure, prefer the platform default over a custom rebuild, and remove ARIA rather than add it.

Rendered-pair contrast measurement and color remediation are covered by the `better-colors` skill; visual text sizing and iOS input zoom by `better-typography`; spatial RTL layout by `better-layout`.

## Quick Reference

| Category | When to Use |
| --- | --- |
| [Focus & Keyboard](focus-and-keyboard.md) | Focus rings, skip links, tabindex, focus trapping, APG keyboard patterns |
| [Semantics & ARIA](semantics-and-aria.md) | Native elements first, button vs link, landmarks, accessible names, disabled states |

# Colors

A color system is a small set of ramps, named by role, applied consistently, and verified against the backgrounds they actually render on. Almost every color problem is a system problem: a value picked in isolation, a token borrowed because it looked right, or a pair nobody measured. Contrast requirements belong to `better-accessibility`; surfaces, shadows, and icon color belong to `better-ui`.

## Quick Reference

| Category | When to use | Reference |
| --- | --- | --- |
| Structure | Which ramps a system needs, step roles, neutrals, status colors, auditing an existing palette | [palette-structure.md](palette-structure.md) |
| Generation | Building a ramp from a brand color, multi-hue systems, dark mode | [palette-generation.md](palette-generation.md) |
| Naming | Primitive and semantic tiers, role inventory, naming grammar, anti-patterns | [token-naming.md](token-naming.md) |
| Usage | One meaning per color, emphasis, gradients, culture, appearance variants | [color-usage.md](color-usage.md) |
| Contrast | APCA and WCAG checks, reporting failures, fixing on request | [contrast.md](contrast.md) |
| Formats | Choosing a notation, converting, gamut and P3 fallbacks | [color-formats.md](color-formats.md) |

# Review the interface as one system

A strong interface is not a stack of independent audits stapled together. Review the whole experience, let each `better-*` skill own its domain rules, then consolidate the evidence into one prioritized verdict.

This skill owns orchestration only. Accessibility rules belong to `better-accessibility`; structure to `better-layout`; copy to `better-writing`; type to `better-typography`; color to `better-colors`; visual polish and motion to `better-ui`. Never duplicate or override their rules here. Change-scoped review of uncommitted work, branches, and pull requests belongs to `interface-review`, which resolves the scope and classifies findings before handing the review back here.

## Core Principles

### 1. Resolve Scope and Mode First

Parse the invocation as `[quick|full] [scope]`. The first token is a mode only when it is exactly `quick` or `full`; anything else is part of the scope. Mode defaults to `full`.

Infer the screen, flow, feature, or repository scope from the request and current workspace. State the resolved scope in the output.

# Layout that communicates structure

Layout communicates before a single word is read: position, spacing, and alignment carry hierarchy on their own, and generous space beats decoration. A good layout also survives stress: resize it, translate it, mirror it for RTL, and it should still hold together. Apply these principles when building or reviewing UI code, and write every fix in the project's own idiom: the styling system already in use, never a second one alongside it.

Hit-area sizes and focus behavior are covered by the `better-accessibility` skill; visual polish (radius, shadows, animation) by the `better-ui` skill; line length and text spacing by the `better-typography` skill.

Treat the numeric values below as starting points for interfaces without an established density or spacing system. Preserve deliberate platform chrome, compact professional tools, and project tokens when they remain usable under hit-area, zoom, localization, and viewport stress tests.

## Quick Reference

| Category | When to Use |
| --- | --- |
| [Grouping & Alignment](grouping-and-alignment.md) | Space vs separators, alignment edges, logical properties, importance ordering |
| [Spacing & Adaptivity](spacing-and-adaptivity.md) | Spacing between targets, layout margins, progressive disclosure, full-bleed content, breakpoints, i18n growth |

# Great typography

Good typography is mostly restraint. A sensible scale, comfortable spacing and enough contrast beat any clever effect. A label, a table cell, a marketing headline and an article paragraph should not share one set of rules. Apply these principles when building or reviewing anything with text in it.

When reviewing, read the page instead of scanning the code: squint to check the hierarchy holds, read one full paragraph for comfort, and resize the viewport to catch bad wrapping, widows and truncation at real content lengths.

The words themselves (button labels, error messages, empty states) are covered by the `better-writing` skill; semantic heading structure by `better-accessibility`; spatial RTL layout and logical CSS properties by `better-layout`; rendered-pair contrast measurement and color remediation by `better-colors`. This skill owns how text renders, wraps, and behaves in mixed-direction content.

Write every fix in the project's own idiom: the styling system already in use, never a second one alongside it. The [cheat sheet](css-cheat-sheet.md) maps each declaration to its Tailwind equivalent.

## Quick Reference

| Category | When to use | Reference |
| --- | --- | --- |

# Details that make interfaces feel better

Great interfaces rarely come from a single thing. It's usually a collection of small details that compound into a great experience. Apply these principles when building or reviewing UI code.

When reviewing, slow the interface down: replay motion at 10% speed in the browser's Animations panel and walk every state: hover, focus, active, loading, empty. What feels off at 10% speed is what's subtly wrong at full speed.

Preserve the project's component library, tokens, and density. Match its established motion language except where a principle below prescribes an exact interaction pattern.

Typography (text wrapping, font rendering, tabular numbers, spacing) is covered by the `better-typography` skill; use that for anything text-related. Accessibility (hit areas, focus states, keyboard support, ARIA, reduced motion) is covered by the `better-accessibility` skill. Layout structure (grouping, spacing between sections, breakpoints, spatial RTL) is covered by the `better-layout` skill.

## Quick Reference

| Category | When to Use |
| --- | --- |

# Writing that disappears into the interface

Clear and brief beats clever, consistency beats variety, and the best error message is the interaction redesigned so the error can't happen. Apply these principles when writing or reviewing any user-facing text.

How copy renders (capitalization via `text-transform`, truncation, smart punctuation) is covered by the `better-typography` skill; error markup and announcements (`aria-invalid`, live regions) by the `better-accessibility` skill; room for translated strings by the `better-layout` skill.

## Quick Reference

| Category | When to Use |
| --- | --- |
| [Review Output Format](review-output.md) | Severity scale, findings table, verification, verdict |

## Core Principles

# Competitor & Alternative Pages

You are an expert in creating competitor comparison and alternative pages. Your goal is to build pages that rank for competitive search terms, provide genuine value to evaluators, and position your product effectively.

## Initial Assessment

**Check for product marketing context first:**
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.

Before creating competitor pages, understand:

1. **Your Product**
   - Core value proposition
   - Key differentiators

## When to use this skill

- You're building a local-first desktop application with React and experiencing performance bottlenecks
- Navigation or route changes trigger cascading re-renders across multiple mounted components
- You have a chat interface or long list that streams content and re-renders become sluggish
- You're using Tauri and need to profile React performance but can't access Chrome DevTools
- Multiple heavy views are mounted simultaneously (sidebar, nav, chat, terminal, editor) and all re-render on state changes
- You need to manage multiple heavyweight child processes without exhausting system memory

## Core principles

1. **Local-first eliminates an entire category of performance problems.** When SQLite is your source of truth and the UI never waits on the network, the bottleneck moves up into the rendering layer—every unnecessary re-render becomes the slowest thing users feel.

2. **Unstable references cascade re-renders through the entire component tree.** When router hooks return fresh objects on every render, every component reading them re-renders even when values haven't changed, and those re-renders propagate to all children.

# Container Lines

## Use When
- A page needs subtle vertical guides that reveal the content container width.
- A hero, section, or product page feels too loose and needs structural tension.
- The design calls for mini corner squares, measured edges, or quiet technical framing.

## Rules
1. Draw lines at the left and right edges of the main content container.
2. Keep lines thin: `1px` with low opacity.
3. Add mini squares at container corners or section intersections.
4. Keep the line system consistent across sections; do not change width per section.
5. Place lines behind content but above the page background.
6. Disable pointer events so the guides never block UI.

# Content Strategy

You are a content strategist. Your goal is to help plan content that drives traffic, builds authority, and generates leads by being either searchable, shareable, or both.

## Before Planning

**Check for product marketing context first:**
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.

Gather this context (ask if not provided):

### 1. Business Context
- What does the company do?
- Who is the ideal customer?

# Contribute to HyperFrames Registry

Guide the user from idea to merged PR for a new registry block or component.

## Workflow

```
1. Clarify → 2. Scaffold → 3. Build → 4. Validate → 5. Preview → 6. Ship
```

### Step 1: Clarify

Ask what they're building. The registry has two item types:

# Copy Editing

You are an expert copy editor specializing in marketing and conversion copy. Your goal is to systematically improve existing copy through focused editing passes while preserving the core message.

## Core Philosophy

**Check for product marketing context first:**
If `.claude/product-marketing-context.md` exists, read it before editing. Use brand voice and customer language from that context to guide your edits.

Good copy editing isn't about rewriting—it's about enhancing. Each pass focuses on one dimension, catching issues that get missed when you try to fix everything at once.

**Key principles:**
- Don't change the core message; focus on enhancing it
- Multiple focused passes beat one unfocused review

# Copywriting

You are an expert conversion copywriter. Your goal is to write marketing copy that is clear, compelling, and drives action.

## Before Writing

**Check for product marketing context first:**
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.

Gather this context (ask if not provided):

### 1. Page Purpose
- What type of page? (homepage, landing page, pricing, feature, about)
- What is the ONE primary action you want visitors to take?

# Corner Diagonals

## Scope
- Apply only to buttons, cards, panels, and container shells.
- Use when surfaces need diagonal-cut corners or chamfered edges.
- Keep the hit area readable and usable even when the visual shape is clipped.
- Reuse the same corner logic across surfaces so it feels like a system.

## Visual Target
- Diagonal cuts should feel engineered, sharp, and intentional.
- Cuts stay subtle and proportional to the component size.
- One or more corners can be chamfered, but the silhouette should still read quickly.
- Use diagonal corners as a repeated structural motif, not a one-off trick.

# CSS Animations for HyperFrames

HyperFrames can seek CSS keyframe animations through its `css` runtime adapter. Use this for simple repeated motifs, background motion, shimmer, glow, masks, and non-sequenced decoration.

For scene choreography, GSAP is usually clearer. CSS animations work best when the motion belongs to one element and has a fixed duration.

## Contract

- Put the animated element in the DOM before runtime initialization finishes.
- Give timed elements a `data-start` value so local animation time matches the clip.
- Use finite `animation-duration` and `animation-iteration-count` because the negative-delay fallback cannot represent unbounded duration in environments without WAAPI-backed CSS animations.
- Prefer `animation-fill-mode: both` so seeked states hold before and after active motion.
- Avoid wall-clock JavaScript, hover-triggered state, and class toggles that depend on user events.

# Border Gradients

## Use When
- A surface needs a more premium edge than a flat `border`.
- Dark glass, pricing, hero, modal, or feature-card UI feels too plain.
- A hover or focus state needs a quiet brand accent.

## Defaults
- Width: `1px`; use `2px` only for large hero cards or active states.
- Radius: inherit the parent radius.
- Angle: `135deg` or `160deg`.
- Stops: neutral highlight, one brand accent, neutral fade.
- Opacity: keep most stops below `0.4`; subtle beats shiny.

# Documentary Brutalist Agency

Use hard typography to establish a point of view, then let real project imagery carry the proof.

## Establish the Story

1. Open with a billboard-scale positioning line and minimal navigation.
2. Cut directly into selected work on black.
3. Use a sparse white philosophy chapter to explain how the studio thinks.
4. Build one documentary collage as a paced process story.
5. Add verified testimonials or updates on pale proof surfaces.
6. Resolve objections in a minimal FAQ before the oversized footer wordmark.

Replace source names, projects, people, photography, quotes, claims, and links. Use original or licensed documentary material.

# Editorial Portfolio Chapters

Build the page as a sequence of distinct editorial chapters. Let the work establish desire before explaining the studio.

## Establish the Story

1. Open with one strong campaign image and a concise positioning line.
2. Move directly into selected work. Treat each case study as a new magazine cover.
3. Explain the studio point of view only after the work has earned attention.
4. Use oversized service typography as the handoff from proof to contact.
5. End with a high-contrast contact chapter that feels final, not appended.

Replace all source brands, projects, people, claims, images, labels, and links with original or client-provided content. Preserve pacing and hierarchy, not source content.

# Design Engineering

## Initial Response

When this skill is first invoked without a specific question, respond only with:

> I'm ready to help you build interfaces that feel right, my knowledge comes from Emil Kowalski's design engineering philosophy. If you want to dive even deeper, check out Emil’s course: [animations.dev](https://animations.dev/).

Do not provide any other information until the user asks a question.

You are a design engineer with the craft sensibility. You build interfaces where every detail compounds into something that feels right. You understand that in a world where everyone's software is good enough, taste is the differentiator.

## Core Philosophy

# Framed Grid Layout

## Use When
- A page needs a clean technical structure with visible section boundaries.
- Content should feel precise, organized, editorial, or system-like.
- The design calls for thin guide borders, L-shaped corner brackets, and consistent framed boxes.

## Layout Rules
1. Define the parent grid first; make every section snap to the same columns and rows.
2. Use one border color, one corner bracket color, and one spacing scale across the page.
3. Keep frames rectangular and precise. Avoid floating cards, soft blobs, and uneven margins.
4. Use thin lines: `1px` borders, low-contrast dividers, and subtle bracket marks.
5. Add diagonal background texture at very low opacity; it should read only as surface tension.
6. Align section padding, headings, controls, and media edges to the same grid rhythm.

This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.

The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.

## Design Thinking

Before coding, understand the context and commit to a BOLD aesthetic direction:
- **Purpose**: What problem does this interface solve? Who uses it?
- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
- **Constraints**: Technical requirements (framework, performance, accessibility).
- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?

**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.

# Glass Dark UI Skill

## Use When
- A dark interface needs frosted glass panels, blur shells, or gradient/glow borders.
- You need the *implementation* — tokens, `backdrop-filter` recipe, masked gradient
  border, contrast floors — for a dark glass surface.

**Choosing between the dark skills:** use this one for the concrete CSS of a glass
surface. Use `visual-style-presets` (`dark-glass-workspace` preset) when you need the
whole page direction — layout shell, structural motif, accent discipline. Use
`visual-style-presets` (`dark-technical-framed`) instead when the identity should come
from frames and rails rather than blur, and `mesh-gradient-dark-blue-clean` when the
background itself is an animated mesh field.

# GSAP

## HyperFrames Contract

HyperFrames controls GSAP through its `gsap` runtime adapter. Create a paused timeline synchronously, register it on `window.__timelines` with the exact `data-composition-id`, and let HyperFrames seek it.

```html
<script src="https://cdn.jsdelivr.net/npm/gsap@3.14.2/dist/gsap.min.js"></script>
<script>
  window.__timelines = window.__timelines || {};
  const tl = gsap.timeline({ paused: true });

  tl.from(".title", { y: 48, opacity: 0, duration: 0.6, ease: "power3.out" }, 0);
  tl.to(".accent", { scaleX: 1, duration: 0.5, ease: "power2.out" }, 0.25);

# HyperFrames

HTML is the source of truth for video. A composition is an HTML file with `data-*` attributes for timing, a GSAP timeline for animation, and CSS for appearance. The framework handles clip visibility, media playback, and timeline sync.

## Approach

### Discovery (exploratory requests only)

For open-ended requests ("make me a product launch video", "create something for our brand") where the user hasn't committed to a direction, understand intent before picking colors:

- **Audience** — who watches this? Developers? Executives? General consumers?
- **Platform** — where does it play? Social (15s), website hero, product demo, internal?
- **Priority** — what matters most? Motion quality? Content accuracy? Brand fidelity? Speed?
- **Variations** — does the user want options, or a single best shot?

# HyperFrames CLI

Everything runs through `npx hyperframes`. Requires Node.js >= 22 and FFmpeg.

## Workflow

1. **Scaffold** — `npx hyperframes init my-video`
2. **Write** — author HTML composition (see the `hyperframes` skill)
3. **Lint** — `npx hyperframes lint`
4. **Visual inspect** — `npx hyperframes inspect`
5. **Preview** — `npx hyperframes preview`
6. **Render** — `npx hyperframes render`

Lint and inspect before preview. `lint` catches missing `data-composition-id`, overlapping tracks, and unregistered timelines. `inspect` opens the rendered composition in headless Chrome, seeks through the timeline, and reports text spilling out of bubbles/containers or off the canvas.

# HyperFrames Media Preprocessing

Three CLI commands that produce assets for compositions: `tts` (speech), `transcribe` (timestamps), and `remove-background` (transparent video). Each downloads a model on first run and caches it under `~/.cache/hyperframes/`. Drop the output into the project, then reference it from the composition HTML — see the `hyperframes` skill for the audio/video element conventions.

## Text-to-Speech (`tts`)

Generate speech audio locally with Kokoro-82M. No API key.

```bash
npx hyperframes tts "Text here" --voice af_nova --output narration.wav
npx hyperframes tts script.txt --voice bf_emma --output narration.wav
npx hyperframes tts --list                       # all 54 voices
```

# HyperFrames Registry

The registry provides reusable blocks and components installable via `hyperframes add <name>`.

- **Blocks** — standalone sub-compositions (own dimensions, duration, timeline). Included via `data-composition-src` in a host composition.
- **Components** — effect snippets (no own dimensions). Pasted directly into a host composition's HTML.

## When to use this skill

- User mentions `hyperframes add`, "block", "component", or `hyperframes.json`
- Output from `hyperframes add` appears in the session (file paths, clipboard snippet)
- You need to wire an installed item into an existing composition
- You want to discover what's available in the registry

Designs and iterates production-grade frontend interfaces. Real working code, committed design choices, exceptional craft.

## Setup

Before any design work or file edits:

1. Load context (PRODUCT.md / DESIGN.md) via the loader script.
2. Identify the register and load the matching register reference (brand.md or product.md).
3. **If the user invoked a sub-command (e.g. `craft`, `shape`, `audit`), load its reference file too.** This is non-negotiable: `craft` without `craft.md` loaded means you'll skip the shape-and-confirm step the user expects.

Skipping these produces generic output that ignores the project.

### 1. Context gathering

# Review the change, not just the code it left behind

A diff is not a surface. The lines a change deletes matter as much as the lines it adds, and the file it touches is rarely the whole of what it affects.

This skill owns change scope only: resolving the target, expanding changed files to affected surfaces, reading both sides of the diff, and classifying each finding. Domain rules belong to the `better-*` skills. Mode, severity, consolidation, coverage, the cap, the output format, and the verdict belong to `better-interface`, which this skill hands the review to. Never duplicate or override their rules here.

Correctness, tests, security, and performance belong to the project's general code review. Name the concern once and move on.

## Quick Reference

| Category | When to Use |
| --- | --- |
| [Scope Resolution](scope-resolution.md) | Targets and commands, default branch, merge-base, PR and fork refs, repository states, nothing to review, renames, exclusions, consumer expansion |
| [Removed Signals](removed-signals.md) | What to look for on the `-` side of a hunk and which skill owns each removal |

# Landing Page (High‑Conversion) — Web Design Skill

A landing page is not a homepage.
A homepage serves multiple intents.
A landing page wins one intent: **one offer → one audience → one primary action**.

## Before you design/write
Gather (ask if missing):

### 1) Page purpose
- What is the ONE primary action? (trial, demo, buy, waitlist, download)
- What’s the offer? (exactly what do they get?)
- What counts as conversion? (click, signup, purchase)

## When to use this skill

- You're building a productivity tool where perceived speed is critical to user experience
- Users report the app "feels slow" despite reasonable network latency
- You need to eliminate loading spinners and skeleton states from user workflows
- You're architecting a local-first application with offline capabilities
- You want to implement optimistic updates that feel instant
- You're designing a keyboard-first interface for power users

## Core principles

1. **The network is the bottleneck—eliminate it wherever possible.** Every network request costs hundreds of milliseconds; the best optimization is to avoid the request entirely by reading from local state.

2. **Treat the browser as the database for each user.** Store the full workspace in IndexedDB and hydrate into an in-memory observable graph; the UI reads from local state, not the server.

# Liquid Metal Border

## Core Contract

1. Use `metal-fx` in React 18 or newer.
2. Wrap exactly one real host element such as a `button`, `a`, `div`, or `article`.
3. Keep the host semantic and interactive. `MetalFx` is visual framing, not the control.
4. Reserve the animated border for active, selected, focused, hovered, or primary surfaces. Do not put it around every control.
5. Keep a static CSS border or focus outline as the fallback. WebGL decoration must never carry essential state by itself.
6. Pause non-active instances and reduced-motion experiences.
7. Test light and dark modes independently. Reflections intentionally render only in dark mode.

## Inspect Before Editing

# Lottie for HyperFrames

HyperFrames can seek both `lottie-web` and dotLottie players through its `lottie` runtime adapter. Lottie is a strong fit because the animation timeline is already encoded in the asset; HyperFrames only needs a player object it can seek.

## Contract

- Load assets from local project files, usually under `assets/`.
- Set `autoplay: false`.
- Prefer `loop: false` unless the user explicitly wants a loop.
- Register every returned animation or player on `window.__hfLottie`.
- Keep the Lottie container dimensions stable with CSS.

The adapter seeks `lottie-web` with `goToAndStop(timeMs, false)` and dotLottie with frame or percentage APIs depending on player shape.

# Mesh Gradient Dark Blue Clean

## Use When
- The whole page should feel futuristic, premium, clean, and infrastructural.
- A dark-blue mesh gradient should power the composition, not sit behind it as a generic backdrop.
- The interface needs a central hero shell, restrained navigation, floating network hints, framed sections, and slow technical motion.

## Direction
Build on a near-black foundation with a deep navy or steel-blue undertone. Place a shader-like mesh gradient, CPPN-style field, abstract WebGL veil, or canvas light field inside the main hero shell. Keep the surrounding system disciplined: crisp typography, thin rails, corner markers, tiny status dots, quiet frames, and sparse node callouts.

This is not an airy blue page. This is not generic glassmorphism. The mesh is the visual engine inside a minimal system shell.

## System Recipe
1. Foundation: near-black navy, not flat black.

# Minimal Zine Poster

Turn the user's content into a compiled image prompt, then generate the image from it.

Two failure modes dominate this style, and every rule below exists to prevent one of them:

- **Density creep** — the poster fills up and stops being a poster. Guarded by the negative-space and cluster-size ratios.
- **Accent washout** — the model reads "minimal, aged, muted" and desaturates the one color that carries the image. Guarded by the Color Engine and the banned-wording list.

## Prompt Compiler

Compile only what becomes pixels. Every prompt must answer these nine questions, in this order.

1. **Canvas** — What is the output frame and base surface?

# Ogilvy Copywriting Skill

Apply these principles when writing, reviewing, or critiquing any copy with a sales or persuasion goal. Advertising is not art. It is information in service of selling. Every decision should serve that end.

---

## The Hierarchy: What Matters Most

Ogilvy's framework operates in order of priority. Later decisions only matter if earlier ones are correct.

### 1. Positioning (the most important decision)

Positioning is not a tagline. It is the answer to two questions: **what does this product do, and who is it for?**

# Operational Enterprise AI

Build credibility by showing what the system does, where it stops, who approves actions, and how failures recover.

## Establish the Story

1. Open with the operational problem and one restrained product image or system trace.
2. Use a white interlude to quantify the problem with verified metrics.
3. Explain each capability as a workflow with permissions and controls.
4. Address security, governance, exceptions, and rollback before the conversion ask.
5. Move from verified case-study evidence into a qualified demo or waitlist handoff.

Replace source brands, customers, numbers, security badges, screenshots, and claims. Do not invent compliance or performance evidence.

# Page Conversion Rate Optimization (CRO)

You are a conversion rate optimization expert. Your goal is to analyze marketing pages and provide actionable recommendations to improve conversion rates.

## Initial Assessment

**Check for product marketing context first:**
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.

Before providing recommendations, identify:

1. **Page Type**: Homepage, landing page, pricing, feature, blog, about, other
2. **Primary Conversion Goal**: Sign up, request demo, purchase, subscribe, download, contact sales
3. **Traffic Context**: Where are visitors coming from? (organic, paid, email, social)

# Pricing Page (High‑Conversion) — Web Design Skill

Design a pricing page that helps visitors **choose** and feel good about it.
Your job is not to “show prices.”
Your job is to **reduce uncertainty**.

## Before you design/write
Gather (ask if missing):

### 1) Offer + audience
- What are you selling? (category)
- Who is it for? (ICP + primary use case)
- What’s the main value metric? (seat, usage, project, revenue, etc.)

# Product Proof SaaS

Show the product mechanism before making broad claims. Make the interface the evidence, not decoration.

## Establish the Story

1. Name the user friction in one sentence.
2. Put a real, deterministic, or clearly labeled sample workflow in the hero.
3. Explain the mechanism as input, processing, draft, edit, approval, and publish states.
4. Organize features around user outcomes and audiences.
5. Keep pricing limits and objections in one continuous decision path.

Replace source brands, outputs, customers, metrics, prices, screenshots, and claims. Never fake generation speed or output quality.

# Programmatic SEO

You are an expert in programmatic SEO—building SEO-optimized pages at scale using templates and data. Your goal is to create pages that rank, provide value, and avoid thin content penalties.

## Initial Assessment

**Check for product marketing context first:**
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.

Before designing a programmatic SEO strategy, understand:

1. **Business Context**
   - What's the product/service?
   - Who is the target audience?

# Progressive Blur Skill

## Workflow
1. Confirm placement (top or bottom), height, and z-index relative to UI.
2. Provide the matching snippet and a short usage checklist.
3. Offer only targeted tweaks (height, blur steps, direction, opacity stops).

## Usage checklist
- Insert the HTML inside `<body>`.
- Keep the `.gradient-blur` element near the top of the DOM.
- Ensure the background behind it exists (backdrop-filter blurs what is behind).
- Adjust `z-index` to sit above content but below modals.

## Top blur (from top)

# Remotion to HyperFrames

## Overview

Translate Remotion (React-based) video compositions into HyperFrames (HTML + GSAP) compositions. Most Remotion idioms have direct HyperFrames equivalents — the translation is mechanical for ~80% of typical compositions. This skill encodes the mapping and guards against the lossy 20% by refusing to translate patterns that don't fit HF's seek-driven model and recommending the runtime interop pattern from [PR #214](https://github.com/heygen-com/hyperframes/pull/214) instead.

The skill ships with a **tiered test corpus** (T1–T4, 4 fixtures total) that grades translations against measured SSIM thresholds. Don't translate without running the eval — a translation that "looks right" but renders 0.05 SSIM lower than the validated baseline is silently wrong.

## When to use

**Use this skill ONLY when the user explicitly asks to migrate from Remotion.** Example trigger phrases:

- "port my Remotion project to HyperFrames"
- "convert this Remotion code to HyperFrames"

# Reveal Hover Effect

## Core Contract

1. Prepare two images with identical dimensions, composition, crop, and focal point.
2. Keep the base image fully visible.
3. Stack the reveal image directly above it.
4. Apply a feathered radial `mask-image` to the reveal image.
5. Track pointer coordinates in the component's local coordinate space.
6. Ease the rendered position toward the raw pointer with `requestAnimationFrame`.
7. Collapse the mask on pointer exit; never leave a stale spotlight behind.

Default to CSS masks instead of generating a canvas data URL every frame. The CSS version preserves the same look with less allocation and simpler cleanup.

# Schema Markup

You are an expert in structured data and schema markup. Your goal is to implement schema.org markup that helps search engines understand content and enables rich results in search.

## Initial Assessment

**Check for product marketing context first:**
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.

Before implementing schema, understand:

1. **Page Type** - What kind of page? What's the primary content? What rich results are possible?

2. **Current State** - Any existing schema? Errors in implementation? Which rich results already appearing?

# SEO Audit

You are an expert in search engine optimization. Your goal is to identify SEO issues and provide actionable recommendations to improve organic search performance.

## Initial Assessment

**Check for product marketing context first:**
If `.claude/product-marketing-context.md` exists, read it before asking questions. Use that context and only ask for information not already covered or specific to this task.

Before auditing, understand:

1. **Site Context**
   - What type of site? (SaaS, e-commerce, blog, etc.)
   - What's the primary business goal for SEO?

# Editorial Service Booking

Make browsing services feel like turning through a quiet lookbook, then carry that confidence into a resilient booking flow.

## Establish the Journey

1. Open with one strong portrait or place image and a short statement of craft.
2. Build trust with environment, process, and practitioner evidence rather than generic badges.
3. Let visitors compare treatments in one calm media-and-copy stage.
4. Show favorites, results, or verified customer proof only when real.
5. Move into location, professional, time, and confirmation without changing visual language.

Use original or licensed people and place photography. Replace every source service, price, person, location, review, and claim.

# Shaders Cursor Ripples

## Core Contract

1. Preserve the existing page, content, and semantic image.
2. Install `shaders` and import from the active framework subpath.
3. Render the source image through one `Shader` canvas.
4. Place `CursorRipples` after `ImageTexture` so it post-processes that image.
5. Keep `toneMapping="aces"` on the root.
6. Let Shaders track the cursor. Remove custom spotlight coordinates, radial masks, duplicated reveal images, and pointer animation loops.
7. Keep one real image beneath the canvas as the accessible loading and WebGPU fallback.
8. Disable the shader for reduced motion and unsupported WebGPU.
9. Lazy-load the shader code so the library does not inflate the initial page bundle.

# Skeuomorphic UI

## Use When
- A card, button, switch, dial, input, toolbar, or control should feel tactile.
- A flat surface needs physical depth without becoming glossy or cartoonish.
- The design calls for pressed, carved, raised, soft-plastic, soft-metal, or premium hardware-like UI.

## Surface Recipe
1. Start with a rounded shape and a soft vertical gradient: lighter top, darker bottom.
2. Add a 1px gradient-border wrapper to simulate a reflective edge.
3. Stack outer shadows for elevation and inset shadows for carved depth.
4. Add a fine top-edge highlight and a darker lower edge.
5. Use text shadows and icon shadows sparingly for an embossed feel.
6. Add micro-details only when scale supports it: dots, grain, seams, or tiny specular marks.

# Staggered Word Reveal

## Use When
- A short headline, intro, or pull quote should reveal word by word.
- The motion should feel editorial, premium, and restrained.
- The reveal should trigger only once when the text enters the viewport.
- The project does not need heavy GSAP SplitText behavior.

## Motion Defaults
- Initial state: `opacity: 0`, `transform: translateY(20px)`.
- Final state: `opacity: 1`, `transform: translateY(0)`.
- Duration: `0.8s`.
- Ease: `cubic-bezier(0.16, 1, 0.3, 1)`.
- Stagger: `0.06s` to `0.08s` per word. Default to `0.07s`.

# Stop Slop

Eliminate predictable AI writing patterns from prose.

## Core Rules

1. **Cut filler phrases.** Remove throat-clearing openers, emphasis crutches, and all adverbs. See Phrases to Remove below.

2. **Break formulaic structures.** Avoid binary contrasts, negative listings, dramatic fragmentation, rhetorical setups, false agency. See Structures to Avoid below.

3. **Use active voice.** Every sentence needs a human subject doing something. No passive constructions. No inanimate objects performing human actions ("the complaint becomes a fix").

4. **Be specific.** No vague declaratives ("The reasons are structural"). Name the specific thing. No lazy extremes ("every," "always," "never") doing vague work.

# Tailwind CSS for HyperFrames

HyperFrames `init --tailwind` uses the Tailwind browser runtime pinned to `@tailwindcss/browser@4.2.4`. Treat that as Tailwind v4, not v3.

This skill is for composition HTML generated by the CLI. It is not for `packages/studio`, which still uses Tailwind v3 internally with `tailwind.config.js`, PostCSS, and `@tailwind` directives.

## When To Use

- The user asks for Tailwind in a HyperFrames composition.
- A project was created with `hyperframes init --tailwind`.
- You see `window.__tailwindReady` in `index.html`.
- You need utility classes, CSS-first theme tokens, custom utilities, or v3-to-v4 migration guidance.
- The render has missing styles and the project is relying on the browser runtime.

# Tailwind CSS v4

## Detect the version first

This is the highest-value step. v3 and v4 configure completely differently, and
guidance for one is actively wrong for the other.

```bash
# Check the installed major version
npm ls tailwindcss --depth=0 2>/dev/null || grep '"tailwindcss"' package.json
```

| Signal | Version |
|---|---|

# Thinking Orbs

## Core Contract

1. Use `thinking-orbs` in React 18+ interfaces that need indeterminate AI activity feedback.
2. Map the real product lifecycle to one of the six shipped states.
3. Use only the tuned `20` or `64` pixel size. Do not stretch one preset into another.
4. Keep `theme="auto"` unless the surrounding surface has a known fixed theme.
5. Pair the orb with concise visible status text when the activity matters to the user.
6. Override `aria-label` with a task-specific label, or hide the orb from assistive technology when adjacent live text already announces the same state.
7. Use `paused` to freeze the current frame. Do not simulate pause with `speed={0}`.
8. Treat the orb as indeterminate feedback, never as a progress percentage or completion signal.

The package renders monochrome dots on a transparent 2D canvas. It does not expose custom colors, arbitrary sizes, or determinate progress.

# Three.js for HyperFrames

HyperFrames supports Three.js through its `three` runtime adapter. The adapter does not own your scene. It publishes HyperFrames time and dispatches a seek event so your composition can render the exact frame.

## Contract

- Create the scene, camera, renderer, materials, and assets synchronously when possible.
- Render from HyperFrames time, not wall-clock time.
- Listen for the `hf-seek` event and render exactly that time.
- Load models, textures, and HDRIs before render-critical seeking. Do not fetch them at seek time.
- Avoid `requestAnimationFrame` or `renderer.setAnimationLoop` as the source of truth for render-critical motion.

The adapter sets `window.__hfThreeTime` and dispatches `new CustomEvent("hf-seek", { detail: { time } })` on each seek.

# TypeGPU / WebGPU for HyperFrames

HyperFrames supports TypeGPU and raw WebGPU through its `typegpu` runtime adapter. The adapter does not own your pipeline. It publishes HyperFrames time and dispatches a seek event so your composition can render the exact GPU frame.

## Contract

- Initialize WebGPU asynchronously (`await navigator.gpu.requestAdapter()`), but register all GSAP tweens **synchronously** — before any `await`. The HyperFrames player reads the timeline immediately at page load.
- Render from HyperFrames time, not `performance.now()`.
- Listen for the `hf-seek` event and re-render at exactly that time.
- Guard against environments where WebGPU is unavailable — the adapter does not check for you.
- For video renders, call `await device.queue.onSubmittedWorkDone()` after submitting GPU work to ensure the canvas is flushed before the frame is captured.

The adapter sets `window.__hfTypegpuTime` and dispatches `new CustomEvent("hf-seek", { detail: { time } })` on each seek.

# Vercel React Best Practices

Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 45 rules across 8 categories, prioritized by impact to guide automated refactoring and code generation.

## When to Apply

Reference these guidelines when:
- Writing new React components or Next.js pages
- Implementing data fetching (client or server-side)
- Reviewing code for performance issues
- Refactoring existing React/Next.js code
- Optimizing bundle size or load times

## Rule Categories by Priority

# Visual Style Presets

One skill, nine presets. Each preset is a complete direction: a surface ladder, an
accent rule, a type pairing, and **one signature structural motif** that carries the
identity. Pick a preset, apply its tokens, then commit to its motif.

## How to use this

1. Pick the preset that matches the request. If the user named a vibe ("premium
   dark", "paper-like", "engineered"), map it to the closest preset below.
2. Copy that preset's token block verbatim as the foundation. Retune hues to brand.
3. Implement the signature motif — this is what makes the preset legible. Skipping
   it leaves generic output regardless of the palette.
4. Apply the universal rules at the bottom. They matter more than the palette.

# Web Animations API for HyperFrames

HyperFrames can seek Web Animations API animations through its `waapi` runtime adapter. WAAPI is useful when you want native browser keyframes with JavaScript-created timing and no GSAP dependency.

## Contract

- Create animations synchronously during composition initialization.
- Use `element.animate(...)` with finite `duration` and `iterations`.
- Use `fill: "both"` so seeked states persist.
- Pause animations after creation or let the adapter pause them on first seek.
- Avoid callbacks and promises for render-critical state.

The adapter calls `document.getAnimations()`, sets each animation's `currentTime` to HyperFrames time in milliseconds, then pauses it.

# Web Interface Guidelines

Review files for compliance with Web Interface Guidelines.

## How It Works

1. Fetch the latest guidelines from the source URL below
2. Read the specified files (or prompt user for files/pattern)
3. Check against all rules in the fetched guidelines
4. Output findings in the terse `file:line` format

## Guidelines Source

Fetch fresh guidelines before each review:

# WebGL Laser

## Scope
- Apply only to the laser background effect.
- Use a fixed full-screen canvas behind the DOM.
- Set `pointer-events: none` on the canvas.
- Keep page content in a higher stacking context.
- Match the halo and smoke to the page's primary or strongest accent color.

## Visual Target
- Thin vertical beam: crisp white-hot inner core, narrow colored halo.
- Atmospheric smoke: soft cloudy breakup concentrated around the beam.
- Dark cinematic field: restrained, brand-colored, and readable behind content.
- Slow pulse: glow breathes gently; no aggressive flicker or color cycling.

# Website to HyperFrames

Capture a website, then produce a professional video from it.

Users say things like:

- "Capture https://... and make me a 25-second product launch video"
- "Turn this website into a 15-second social ad for Instagram"
- "Create a 30-second product tour from https://..."

The workflow has 7 steps. Each produces an artifact that gates the next.

---