/htmldrop

name: htmldrop
description: >-
  Reach for this skill when an HTML artifact — report, deck, brief, mockup, dashboard, proposal, spec, or landing page, whether the user already has it or you just generated it — needs to reach other people or get tightened before it ships. Three situations: (1) they want a shareable link — public, or password-protected so only a client or specific people can open it; (2) they want reviewers to comment/annotate on it, then pull that feedback back to answer, fold, or synthesize into a revised version; (3) they want to co-edit it with you live and locally first — pointing at sections and commenting while you edit in real time, nothing deployed — to polish before sending. Cues: share, publish, get a link, password-protect, send to the client, collect or incorporate feedback, review it together, iterate in edit mode. Not for deploying apps/frameworks (Vercel, Next.js, npm), CSS/layout debugging, PDF annotation, A/B testing, or emailing screenshots.

htmldrop — Share HTML as Hosted Links

Publish any HTML file and get a shareable URL instantly via the `htmldrop` CLI. Three modes:

• **Simple share** (Surge.sh hosting) — get a public or password-protected link to a static page.
• **Collaborative feedback + converge** — publish with an embedded annotation widget so reviewers can highlight text and comment with no account, then pull the feedback, add evidence-backed comments programmatically, and synthesize an improved version with AI.
• **Edit mode** (local, pre-publish) — serve the file on `127.0.0.1` and iterate on it live *with the user*: they annotate and comment on one surface; you edit the file (it hot-reloads), reply, or ask them a question. No hosting, nothing published. This is the loop to firm a doc up before sharing it — or between rounds of external feedback. See **`references/edit-mode.md`**.

**Design applies to every mode:** before generating or serving any HTML, match the design system of the project the artifact is about, so it looks like the real product rather than a generic page. See **`references/design-and-visuals.md`** — read it whenever you author or edit HTML here.

---

MUST DO BEFORE WRITING ANY HTML (all modes)

This fires **automatically**, whether the user runs simple share, feedback, or edit mode — and whether or not they ever type a `htmldrop playbook`/`htmldrop design` command. It is the default behavior of this skill, not an opt-in. Do both, in order, before you write or edit a single line of HTML:

1. **Match the look first (theme + styling).** Detect and adopt the design system of the project the artifact is *about* (not necessarily your current working dir), in this priority: 1. a look/system the user named → use exactly that; 2. the target project's design system → Tailwind/theme config, `:root` CSS variables/design tokens, an in-use component library, or brand assets (logo, palette, fonts) on an existing styled page; 3. nothing to match → a clean, deliberate neutral default (small palette, system font stack, generous spacing, clear hierarchy). When you deliver, state which source you used in one line ("styled with the project's Tailwind theme" / "no theme found — neutral default"). **Never ship a generic template when a real design system was discoverable.**

2. **Pick the right shape (the MUST-router).** Match the content against these triggers and reach for the right structure before writing. One artifact often combines several:

• **relationships / flows / architecture / sequences** → a real **Mermaid diagram**, never hand-built `<div>` boxes. Re-render on light/dark flip (Mermaid never restyles an already-drawn SVG).
• **comparing options / tools / approaches / tradeoffs** → aligned option cards; make the **cost as visible as the benefit** (don't hide the downside).
• **teaching a concept / how something works** → the **explainer shape**: (a) lead with the one idea that explains everything; (b) a "feel-the-difference" micro-demo with the smallest honest code (a 450ms `setTimeout` *is* network lag; a toggle *is* a mode switch); (c) a looping before/after; (d) a cheat-sheet table last, including the honest trade-off.
• **proposing a change / roadmap / approach** → goal → current → proposed → risks → open questions. Mock the UI, don't describe it.
• **dense structured data / many attributes** → a real `<table>`, aligned columns, no horizontal overflow, highlight the decision-relevant column.
• **a decision/answer needed from the viewer** → an in-artifact form with native controls and one explicit **send answer** per question that delivers the choice to the agent via the feedback channel (not a local-only "queued" state that never arrives).
• **sequential narrative to step through** → slides: one idea each, large type, keyboard nav.

**The full contract lives in `references/design-and-visuals.md`** — ready-to-paste pinned CDN snippets (with integrity hashes), a layout-safety CSS block, a theme-aware Mermaid re-render snippet, and the per-shape guidance. Read it before authoring; it is the single source of truth for both the guardrail above and the optional commands below.

**Optional standalone commands (same content, on demand).** If you (or a non-skill agent, or a curious user) want the guidance without this skill loaded, the CLI exposes it directly — these are a convenience, not a replacement for the guardrail:

• `htmldrop design [--json]` — prints the design contract (priority rule, pinned snippets, layout-safety CSS, theme-aware Mermaid).
• `htmldrop playbook [id] [--json]` — lists the shapes, or prints one (`diagram`, `comparison`, `input`, `plan`, `table`, `slides`, `explainer`).

Prerequisites

• Node.js >= 18
• `npm install -g @yeefeiooi/htmldrop@latest` (the binary is still `htmldrop`)
• For **simple share**: run `htmldrop init` once (sets up Surge account + subdomain)
• For **feedback/converge**: run `htmldrop auth setup` once (generates an author API key in `~/.htmld