Add HTML wireframe and prototype skills

.claude-plugin/marketplace.json

@@ -3,19 +3,19 @@
   "owner": {
     "name": "plannotator"
   },
-  "description": "Agent skills for elegant, self-contained HTML plans, diagrams, and artifacts.",
+  "description": "Focused skills for self-contained HTML artifacts, wireframes, interactive prototypes, plans, and diagrams.",
   "plugins": [
     {
       "name": "plannotator-effective-html",
       "source": {
         "source": "github",
         "repo": "plannotator/effective-html"
       },
-      "description": "HTML skills for pragmatic visual artifacts — html, html-diagram, and html-plan.",
+      "description": "Create HTML wireframes, styled mockups, interactive prototypes, plans, diagrams, and general standalone artifacts.",
       "homepage": "https://github.com/plannotator/effective-html",
       "repository": "https://github.com/plannotator/effective-html",
       "license": "MIT",
-      "keywords": ["html", "diagram", "plan", "svg", "artifacts", "skills"],
+      "keywords": ["html", "wireframe", "prototype", "prototyping", "diagram", "plan", "html-artifacts", "agent-skills", "claude-code", "codex"],
       "category": "productivity"
     }
   ]

.claude-plugin/plugin.json

@@ -2,7 +2,9 @@
   "name": "plannotator-effective-html",
   "skills": [
     "./skills/html",
+    "./skills/html-wireframe",
+    "./skills/html-prototype",
     "./skills/html-diagram",
     "./skills/html-plan"
   ]
-}
+}

.codex-plugin/plugin.json

@@ -1,27 +1,25 @@
 {
   "name": "plannotator-effective-html",
-  "version": "0.1.0",
-  "description": "HTML skills for pragmatic visual artifacts — html, html-diagram, and html-plan.",
+  "version": "0.3.0",
+  "description": "Focused skills for self-contained HTML artifacts, wireframes, interactive prototypes, plans, and diagrams.",
   "author": {
     "name": "plannotator",
     "url": "https://github.com/plannotator"
   },
   "homepage": "https://github.com/plannotator/effective-html",
   "repository": "https://github.com/plannotator/effective-html",
   "license": "MIT",
-  "keywords": ["html", "diagram", "plan", "svg", "artifacts", "skills"],
+  "keywords": ["html", "wireframe", "prototype", "prototyping", "diagram", "plan", "html-artifacts", "agent-skills", "claude-code", "codex"],
   "skills": "./skills/",
   "interface": {
     "displayName": "Effective HTML",
-    "shortDescription": "Elegant, self-contained HTML plans, diagrams, and artifacts",
-    "longDescription": "Create polished, self-contained HTML artifacts, full-screen architecture diagrams, and pragmatic plan pages from local reference examples.",
+    "shortDescription": "HTML wireframes, prototypes, and artifacts",
+    "longDescription": "Create self-contained HTML artifacts whose direction follows the user's brief, project, and subject, with focused skills for low-fidelity wireframes, styled mockups, interactive prototypes, plans, diagrams, and general HTML work.",
     "developerName": "plannotator",
     "category": "Productivity",
     "capabilities": ["Write"],
     "defaultPrompt": [
-      "Create an effective HTML plan.",
-      "Create an effective HTML diagram.",
-      "Create an effective HTML artifact."
+      "Use $html to choose the right Effective HTML workflow and create a self-contained artifact from this brief."
     ]
   }
 }

README.md

@@ -1,83 +1,127 @@
-## HTML skills for pragmatic visual artifacts
+# Effective HTML
 
+Five focused skills for creating useful, self-contained HTML artifacts, from low-fidelity wireframes to working interactive prototypes.
 
+The collection is opinionated about clarity, accessibility, and verification. It is not tied to one palette, typography stack, component system, or diagram style. Each artifact follows the user's direction first, then the project's established language, then the subject itself.
 
-https://github.com/user-attachments/assets/24306977-7f30-44c9-9bff-55f901d557b0
+## Choose a skill
 
-_**Note:** The diagram was made by `Fable 5`, I will create more fable 5 artifacts and add them to the skill folder for smaller models to distill._
-[example demo](https://x.com/backnotprop/status/2065479594023829619?s=20)
+| Skill | Use it for |
+| --- | --- |
+| [`html`](skills/html/SKILL.md) | Broad HTML requests, mixed artifacts, reports, explainers, presentations, landing pages, tools, and routing to a specialist |
+| [`html-wireframe`](skills/html-wireframe/SKILL.md) | Low-fidelity layout directions that test content, hierarchy, navigation, flows, and responsive structure |
+| [`html-prototype`](skills/html-prototype/SKILL.md) | Styled mockups and working prototypes with realistic states, interaction, keyboard support, and responsive behavior |
+| [`html-plan`](skills/html-plan/SKILL.md) | Plans, roadmaps, rollouts, and implementation sequences that preserve source commitments |
+| [`html-diagram`](skills/html-diagram/SKILL.md) | Architecture, sequence, process, state, hierarchy, timeline, and system diagrams |
 
+A mockup is a noninteractive fidelity mode inside `html-prototype`. There is no separate `html-mockup` skill.
 
-Focused skills for generating self-contained HTML deliverables with a strong visual bias:
+## One brief, three stages
 
-- `html`: an HTML file for whatever you're describing, in the effective HTML style
-- `html-diagram`: architecture, stack, and systems understanding rendered as full-screen HTML diagrams with high-quality SVG
-- `html-plan`: HTML plan pages in the effective HTML style
+The [release-readiness example](examples/release-readiness/README.md) carries the same product brief through structure, visual fidelity, and interaction. Every stage is preserved as a standalone HTML file that opens without build tooling.
 
-<p align="center">
-  <a href="https://github.com/backnotprop/plannotator">
-    <img src="./star-plannotator.svg" width="340" alt="like this? star Plannotator">
-  </a>
-</p>
-<p align="center">
-Render and annotate your HTML with Plannotator (optional): https://github.com/backnotprop/plannotator
-</p>
+| Wireframe | Mockup | Prototype |
+| --- | --- | --- |
+| [![Low-fidelity release wireframe](examples/release-readiness/screenshots/wireframe-desktop.png)](examples/release-readiness/wireframe.html) | [![Styled release mockup](examples/release-readiness/screenshots/mockup-desktop.png)](examples/release-readiness/mockup.html) | [![Interactive release prototype](examples/release-readiness/screenshots/prototype-desktop.png)](examples/release-readiness/prototype.html) |
+| Decide what belongs on the screen and compare structural directions. | Judge hierarchy, visual language, and responsive composition. | Test the blocked-to-ready flow, feedback, recovery, and product boundary. |
 
+Read the canonical Plannotator guide, [HTML wireframes and prototypes for coding agents](https://docs.plannotator.ai/learn/code-context/html-wireframes-and-prototypes-for-coding-agents), for the review questions that belong at each stage.
 
 ## Install
 
+Install the collection:
+
 ```bash
 npx skills add plannotator/effective-html
 ```
 
-List available skills first:
+List or install individual skills:
 
 ```bash
 npx skills add plannotator/effective-html --list
+npx skills add plannotator/effective-html --skill html-wireframe
+npx skills add plannotator/effective-html --skill html-prototype
 ```
 
-Install a specific skill:
+Invoke a skill directly:
 
-```bash
-npx skills add plannotator/effective-html --skill html-diagram
-npx skills add plannotator/effective-html --skill html-plan
+```text
+Use $html-wireframe to explore three responsive layouts for this checkout brief.
+
+Use $html-prototype in mockup mode to apply our existing design system to the approved wireframe.
+
+Use $html-prototype to make the checkout flow work, including validation, loading, failure, success, keyboard, and mobile states.
 ```
 
-### As a Claude Code plugin
+Only `$html` is eligible for implicit invocation. Call a specialist directly when you know the artifact type, or use `$html` to route a broad request. Each specialist remains independently usable when invoked directly.
 
-This repo is also a [plugin marketplace](https://code.claude.com/docs/en/plugin-marketplaces). Add it and install:
+### Claude Code plugin
 
-```
+```text
 /plugin marketplace add plannotator/effective-html
 /plugin install plannotator-effective-html@effective-html
 ```
 
-### As a Codex plugin
+### Codex plugin
 
 ```bash
 codex plugin marketplace add plannotator/effective-html
 codex plugin add plannotator-effective-html@effective-html
 ```
 
-<br/>
+## How the skills work
+
+The skills separate creative freedom from reliability:
+
+- Visual direction comes from the conversation, project, audience, and subject.
+- Wireframes stay intentionally unfinished so reviewers focus on structure.
+- Mockups add a visual system without pretending to test behavior.
+- Prototypes implement one credible flow and its relevant states.
+- Plans preserve source commitments.
+- Diagrams choose a visual model and rendering method that fit the relationship being explained.
+- Every artifact is responsive, accessible, self-contained, and verified in a browser.
+
+Detailed guidance lives only where it is needed. The broad `html` skill keeps shared references for creative direction, documents, interfaces, diagrams, charts, and data. The specialist skills remain concise and independently usable.
+
+## Repository shape
+
+```text
+skills/
+├── html/
+│   ├── SKILL.md
+│   ├── agents/openai.yaml
+│   └── references/
+├── html-wireframe/
+├── html-prototype/
+├── html-plan/
+└── html-diagram/
+
+examples/
+└── release-readiness/
+    ├── brief.md
+    ├── states.md
+    ├── wireframe.html
+    ├── mockup.html
+    ├── prototype.html
+    └── screenshots/
+```
+
+This project was inspired by Thariq Shihipar's [The unreasonable effectiveness of HTML](https://thariqs.github.io/html-effectiveness).
+
 <p align="center">
-  <a href="https://github.com/plannotator/tot">
-    <img src="./use-tot.svg" width="300" alt="share your HTML? use tot">
+  <a href="https://github.com/backnotprop/plannotator">
+    <img src="./star-plannotator.svg" width="340" alt="Star Plannotator on GitHub">
   </a>
 </p>
-
 <p align="center">
-Create instant share links for your HTML files (optional): https://github.com/plannotator/tot<br/> HTML from video: https://tot.page/0CW7xV96XMxnalrzwRl4eQ
+Render and annotate local HTML with <a href="https://github.com/backnotprop/plannotator">Plannotator</a>.
 </p>
 
-## Skills
-
-- `html` - Create an HTML file for whatever the user is describing, matching the effective HTML references.
-- `html-diagram` - Build full-screen HTML architecture and stack diagrams with SVG-first presentation and minimal prose.
-- `html-plan` - HTML plan pages in the effective HTML style.
-
-## Repository Shape
-
-Skills live under `skills/<skill-name>/SKILL.md`. Each skill also bundles a copy of the `html-effectiveness` example corpus under `references/html-effectiveness/` so the examples stay local to the skill.
-
-Credit: this repo bundles and uses the `html-effectiveness` examples by Thariq Shihipar: https://thariqs.github.io/html-effectiveness
+<p align="center">
+  <a href="https://github.com/plannotator/tot">
+    <img src="./use-tot.svg" width="300" alt="Share HTML with tot">
+  </a>
+</p>
+<p align="center">
+Create a shareable link for an HTML file with <a href="https://github.com/plannotator/tot">tot</a>.
+</p>

examples/release-readiness/README.md

@@ -0,0 +1,58 @@
+# Release readiness example
+
+This example takes one product brief through three review stages. Each stage is a separate, self-contained HTML file so it can be opened directly, copied, and changed without build tooling.
+
+## 1. Wireframe
+
+[Open the wireframe](wireframe.html)
+
+The wireframe keeps the visual treatment deliberately plain and compares three structural directions:
+
+- **Decision first** keeps the release verdict visible beside the checks.
+- **Evidence ledger** favors dense comparison and auditability.
+- **Guided gate** turns the decision into a step-by-step review.
+
+Decisions at this stage include content, grouping, navigation, task order, and mobile reflow. Color, typography, component styling, and animation remain open.
+
+| Decision first | Evidence ledger | Guided gate |
+| --- | --- | --- |
+| ![Decision-first wireframe](screenshots/wireframe-desktop.png) | ![Evidence-ledger wireframe](screenshots/wireframe-evidence-ledger-desktop.png) | ![Guided-gate wireframe](screenshots/wireframe-guided-gate-desktop.png) |
+
+## 2. Mockup
+
+[Open the mockup](mockup.html)
+
+The mockup develops the decision-first direction into a release-control workspace. It adds a product-specific visual hierarchy, responsive composition, readable state styling, and realistic evidence without adding product behavior.
+
+Decisions at this stage include type, spacing, color, contrast, visual density, and how the desktop composition collapses on mobile. Data flow, permissions, persistence, and transitions remain open.
+
+![Styled release-readiness mockup](screenshots/mockup-desktop.png)
+
+## 3. Prototype
+
+[Open the prototype](prototype.html)
+
+The prototype adds the smallest complete flow needed to test the decision:
+
+1. Review the failed iOS smoke test.
+2. Record a passing rerun in a keyboard-accessible dialog.
+3. See the release change from blocked to ready.
+4. Request a production release and reach the explicit prototype boundary.
+
+The artifact includes loading, error, success, disabled, empty-notes, mobile, and reduced-motion states. It does not authenticate a user, save data, or start a real release.
+
+![Interactive release-readiness prototype](screenshots/prototype-desktop.png)
+
+See the [validation record](validation.md) for browser, interaction, accessibility, clean-invocation, and packaging checks.
+
+## Clone and adapt
+
+Copy the stage closest to the question you need to answer:
+
+```bash
+cp examples/release-readiness/wireframe.html my-flow.html
+cp examples/release-readiness/mockup.html my-mockup.html
+cp examples/release-readiness/prototype.html my-prototype.html
+```
+
+Replace the brief, labels, data, and state model before changing the visual direction. A useful adaptation keeps the review question clear and removes controls that do not support it.

examples/release-readiness/brief.md

@@ -0,0 +1,26 @@
+# Atlas Mobile 4.8 release-readiness brief
+
+## User and task
+
+A release manager must decide whether Atlas Mobile 4.8 can go to production.
+
+## Required information
+
+- Release candidate and commit
+- Release owner
+- Four required checks and their current state
+- Evidence behind each check
+- Open risks and reviewer notes
+- Current release decision
+
+## Required behavior
+
+The page starts blocked because the iOS smoke test failed. A reviewer can record a passing rerun. The release state then changes from blocked to ready, and the production-release action becomes available.
+
+## Non-goals
+
+- Starting a real deployment
+- Authentication or authorization
+- Loading live build data
+- Defining the production application's component architecture
+- Final product copy for every failure and recovery state