Skip to content

Agent skills for useful HTML artifacts, wireframes, interactive prototypes, plans, and diagrams.

Simplify the Effective HTML guide

Michael Ramosacb4d2a863f1
diff --git a/site/content/docs/choosing-fidelity.mdx b/site/content/docs/choosing-fidelity.mdx
index 1ed9517..dbf6cbf 100644
--- a/site/content/docs/choosing-fidelity.mdx
+++ b/site/content/docs/choosing-fidelity.mdx
@@ -1,66 +1,39 @@
---
title: Choosing fidelity
-description: Match the artifact's finish to the decision being made now.
+description: Understand the difference between a wireframe, mockup, prototype, diagram, and plan.
---
-Fidelity changes the question people answer. A rough artifact invites
-structural critique. A polished artifact invites visual critique. A working
-artifact invites behavioral critique.
-
-Choose the lowest fidelity that makes the next human decision visible.
+A wireframe, mockup, and prototype may show the same product at different
+levels of detail. Choose the one that shows what you need to discuss or try.
<FidelityWorkbench />
-## Read the decision, not the finish
-
-Choose the artifact that exposes the evidence the review needs. A wireframe
-should not be criticized for lacking polish. A mockup should not imply that
-every control works. A prototype should not grow into a product simply because
-the happy path is convincing.
-
-Increase fidelity only when the review depends on new evidence.
-
## Wireframe
-Use a wireframe when the open questions concern content, hierarchy, navigation,
-flow, or responsive structure. Keep visual styling deliberately restrained so
-reviewers do not spend attention on color and polish.
+A wireframe shows rough layout, hierarchy, navigation, and responsive
+structure. It is useful when the organization matters more than the visual
+finish.
## Mockup
-Use a mockup when the structure is stable enough to evaluate visual hierarchy,
-brand expression, density, typography, and composition. A mockup can be
-high-fidelity without pretending every control works.
+A mockup shows how the product could look. It can use the real design system,
+content, typography, color, and spacing without making every control work.
## Prototype
-Use a prototype when the decision depends on behavior: state changes, feedback,
-validation, recovery, keyboard interaction, or a multi-step flow. Implement one
-credible path and the states that could change the decision.
+A prototype lets people try a flow. It can show state changes, validation,
+loading, errors, success, keyboard behavior, and responsive interaction.
## Diagram
-Use a diagram when the hard part is a relationship: architecture, sequence,
-state, hierarchy, ownership, or flow. Pick the visual model from the
-relationship rather than forcing everything into boxes and arrows.
+A diagram shows how parts relate. Use one for architecture, sequence, state,
+hierarchy, ownership, or flow.
## Plan
-Use a plan when the work is primarily sequential and source commitments must be
-preserved. Markdown often remains the better medium. Use HTML only when spatial,
-comparative, or interactive presentation makes the plan materially easier to
-understand.
-
-## Before increasing fidelity
-
-Before raising fidelity, ask:
-
-1. What changed about the decision?
-2. What new evidence will the added fidelity provide?
-3. What kinds of feedback might the extra polish accidentally attract?
-
-Advance when the next question requires it, not because the artifact looks
-unfinished.
+A plan lays out the work in order. Markdown is usually enough. HTML helps when
+the plan needs visual comparison, timelines, dependencies, or embedded
+examples.
<GuideHandoff
artifactHref="/catalog?view=compact#catalog-collection"
@@ -70,6 +43,6 @@ unfinished.
<GuideNext
href="/docs/wireframes"
- title="Start with structure"
- description="Use a wireframe when the open questions are about what belongs, where it goes, and how it reflows."
+ title="Wireframes"
+ description="See how HTML wireframes can compare layouts and responsive structure."
/>
diff --git a/site/content/docs/decks.mdx b/site/content/docs/decks.mdx
index 03c10bb..42ab0d0 100644
--- a/site/content/docs/decks.mdx
+++ b/site/content/docs/decks.mdx
@@ -1,45 +1,29 @@
---
title: Decks
-description: Build a browser-native presentation whose sequence carries the story.
+description: Build browser-native slide decks with interaction, animation, keyboard navigation, and easy sharing.
---
-A deck is useful when the order and pace of the explanation matter. HTML makes
-the presentation directly inspectable, interactive, and shareable without
-turning it into a long scrolling page.
+A browser-native deck is a slide presentation made with HTML. It can include
+interaction, animation, live examples, and links while remaining easy to open
+and share.
-## Give each slide one job
+## What HTML adds
-Write the sequence before styling it. Each slide should introduce one idea,
-comparison, transition, or piece of evidence. Remove slides that merely repeat
-the speaker, and split slides that ask the audience to parse several arguments
-at once.
+HTML decks can respond to input, reveal a sequence, run a small demo, or show
+live data. They can also be inspected and changed with the same tools used for
+other web artifacts.
-## Use a fixed stage
+## Keep it usable as a presentation
-Choose one presentation canvas, usually 16:9, and scale that stage to the
-available viewport. Test the smallest display on which the deck must remain
-readable. Treat the slide as a composition rather than a responsive webpage
-whose elements continuously reflow.
+A deck still needs readable slides, dependable arrow-key navigation, visible
+progress, and a layout that fits the screen. A fixed 16:9 stage is usually
+simpler than treating every slide like a responsive webpage.
-## Keep navigation dependable
+## Use motion when it helps
-Support visible controls and familiar keys. Arrow keys should move through the
-sequence; progress and the current position should remain clear. Preserve
-focus, provide a reduced-motion path, and make full-screen mode optional rather
-than required.
-
-## Use motion to reveal structure
-
-Animation should clarify sequence, comparison, or change. Prefer a few staged
-reveals over constant movement. The deck must still communicate when motion is
-disabled or when it is exported as static pages.
-
-## Package the presentation as an artifact
-
-Keep the deck easy to open and share. A self-contained HTML file is often the
-simplest boundary. If it depends on local media, keep the folder portable and
-make the entry point obvious. Verify keyboard navigation, overflow, external
-links, and static export before presenting.
+Animation is useful for sequence, comparison, and change. It should not be
+required to understand the slide, and the deck should respect reduced-motion
+settings.
<GuideHandoff
artifactHref="https://thariqs.github.io/html-effectiveness/09-slide-deck.html"
@@ -47,14 +31,14 @@ links, and static export before presenting.
artifactDescription="Inspect a concise browser-native presentation from The unreasonable effectiveness of HTML."
sourceHref="https://github.com/zarazhangrui/frontend-slides"
sourceLabel="Study Frontend Slides"
- sourceDescription="See a complete agent workflow for style discovery, navigation, animation, and export."
+ sourceDescription="See how Frontend Slides handles design, navigation, animation, and export."
skillHref="https://github.com/zarazhangrui/frontend-slides/blob/main/SKILL.md"
skillLabel="Read the deck skill"
- skillDescription="Use its implementation rules when a presentation needs more than a one-off example."
+ skillDescription="Read Frontend Slides' guidance for building HTML presentations."
/>
<GuideNext
href="/docs/plans"
- title="Keep implementation work source-grounded"
- description="Use HTML for a plan only when spatial or interactive structure adds leverage."
+ title="Plans"
+ description="See when a plan benefits from visual or interactive structure."
/>
diff --git a/site/content/docs/designing-artifacts.mdx b/site/content/docs/designing-artifacts.mdx
index 138034d..d200001 100644
--- a/site/content/docs/designing-artifacts.mdx
+++ b/site/content/docs/designing-artifacts.mdx
@@ -1,104 +1,40 @@
---
title: Designing artifacts
-description: Give any HTML artifact a visual direction rooted in its subject rather than a static template.
+description: Use the design-artifact skill to give HTML wireframes, mockups, prototypes, diagrams, and other artifacts a clear visual direction.
---
-You can make an effective HTML artifact without installing a skill. When you do
-want reusable creative-direction guidance, use
+You do not need a skill to design an HTML artifact. If you want reusable design
+guidance, use
[`design-artifact`](https://github.com/plannotator/effective-html/blob/main/skills/design-artifact/SKILL.md)
-alongside the artifact workflow.
+on its own or alongside one of the more specific Effective HTML skills.
Effective HTML's `design-artifact` skill was derived from Anthropic's official
[`web-artifacts-builder`](https://github.com/anthropics/skills/blob/main/skills/web-artifacts-builder/SKILL.md)
-skill for Claude Code. Anthropic's skill combines design guidance with a React
-artifact toolchain. This adaptation keeps the creative-direction guidance and
-makes it usable with any Effective HTML artifact.
+skill for Claude Code. Anthropic's version includes a React artifact toolchain.
+This version keeps the design guidance and makes it usable with any Effective
+HTML artifact. It is maintained by Plannotator and is not an Anthropic skill.
-The skill does not decide whether the work should be a wireframe, prototype,
-plan, diagram, deck, report, or tool. It decides how the chosen form should feel:
-its visual register, palette, type, composition, theming, and amount of
-expressive treatment.
+## What the skill does
-## Compose skills instead of stacking rules
+The skill looks at the brief, product, design system, and supplied references
+before choosing typography, color, layout, and visual treatment. It can shape a
+wireframe, mockup, prototype, diagram, deck, report, or small tool without
+forcing every artifact into the same style.
-Let one skill own the artifact's form and let `design-artifact` supply creative
-direction:
-
-- `html` routes a broad request and provides the shared build contract.
-- `html-wireframe` keeps structural exploration visibly low fidelity.
-- `html-prototype` owns mockup fidelity, working states, and interaction.
-- `html-plan` protects source commitments and traceability.
-- `html-diagram` chooses the visual model and rendering method.
-- `design-artifact` shapes the visual identity without overriding those
- boundaries.
-
-This keeps the instructions thin. The brief, project context, and artifact
-itself still carry the substance.
-
-## Start with authority, not inspiration
-
-Read the user's instructions and accepted decisions first. Then inspect the
-project's design system, tokens, components, screenshots, and nearby artifacts.
-Only after those sources should the agent use its own design judgment.
-
-References are evidence about intent, constraints, and technique. They are not a
-palette, card system, or layout to copy into every new artifact.
-
-## Choose the register
-
-Match the amount of treatment to the work:
-
-- **Workmanlike** for plans, operational reports, briefs, and many tools.
-- **Editorial** for explainers, research stories, launches, and decks that need
- a stronger point of view.
-- **Expressive** when the visual or interactive premise is part of the subject
- itself.
-
-Every register deserves careful hierarchy and spacing. Not every artifact needs
-a hero, custom type, animation, or a dense interface.
-
-## Write a short design plan
-
-Before coding, decide:
-
-1. The visual premise and why it belongs to this subject.
-2. The color roles, including neutrals and semantic status colors.
-3. The type roles the content actually needs.
-4. The organizing layout and reading path.
-5. The one place, if any, where interaction or motion carries meaning.
-
-The number of colors, typefaces, columns, and components follows the idea. The
-skill deliberately avoids a fixed theme or component recipe.
-
-## Build, inspect, and revise
-
-Use realistic content from the first draft. Open the result at wide and narrow
-sizes, operate the important controls, and check focus, reduced motion, contrast,
-overflow, and failure states.
-
-Before handoff, ask whether the same visual idea would fit a neighboring topic
-just as well. If it would, the direction is still generic. Revise the
-composition, type, color, imagery, or interaction until it belongs to the brief.
-
-## What changed from Claude Code's artifact skill
-
-Anthropic's skill provides a toolchain for elaborate React artifacts. Effective
-HTML keeps the parts that help an agent choose a visual premise, palette, type,
-composition, and level of treatment. It removes the requirement to use that
-toolchain, so the guidance can also shape quiet plans, wireframes, diagrams,
-mockups, and standalone documents. This adaptation is maintained by Plannotator
-and is not an Anthropic skill.
+Use it when an artifact should match an existing product or needs a more
+specific visual direction. The more focused skills can still handle the format:
+`html-wireframe`, `html-prototype`, `html-diagram`, and `html-plan`.
<GuideHandoff
artifactHref="/catalog?collection=skills#catalog-collection"
artifactLabel="Browse the skill collection"
- artifactDescription="Compare the generic design layer with the artifact specialists."
+ artifactDescription="See all of the Effective HTML skills."
sourceHref="https://github.com/anthropics/skills/blob/main/skills/web-artifacts-builder/SKILL.md"
sourceLabel="Read Anthropic's artifact skill"
- sourceDescription="See the Claude artifact workflow that inspired this portable adaptation."
+ sourceDescription="Read the Claude Code skill this version was based on."
skillHref="https://github.com/plannotator/effective-html/blob/main/skills/design-artifact/SKILL.md"
skillLabel="Use design-artifact"
- skillDescription="Apply subject-specific creative direction to any HTML artifact."
+ skillDescription="Give an HTML artifact a visual direction that fits the project."
/>
## Copy the skill
@@ -269,6 +205,6 @@ and interaction choices.
<GuideNext
href="/docs/choosing-fidelity"
- title="Choose the lowest useful fidelity"
- description="Let the decision determine how resolved the artifact should become."
+ title="Choosing fidelity"
+ description="Compare wireframes, mockups, prototypes, diagrams, and plans."
/>
diff --git a/site/content/docs/diagrams.mdx b/site/content/docs/diagrams.mdx
index 0b4e5b3..e9652f8 100644
--- a/site/content/docs/diagrams.mdx
+++ b/site/content/docs/diagrams.mdx
@@ -1,13 +1,14 @@
---
title: Diagrams
-description: Choose a visual model that matches the relationship being explained.
+description: Use HTML diagrams to explain architecture, sequences, state, hierarchy, and flow.
---
-Diagrams are strongest when their geometry carries an exact relationship.
+Diagrams make relationships easier to see. HTML diagrams can also animate a
+sequence, reveal detail, or let someone select a path through a larger system.
<GuideChapterEvidence chapter="diagrams" />
-## Begin with the relationship
+## Common diagram types
- Use a **sequence** when order and handoff matter.
- Use a **state model** when transitions and conditions matter.
@@ -18,35 +19,24 @@ Diagrams are strongest when their geometry carries an exact relationship.
Do not force every subject into a generic left-to-right process.
-## Keep the visual grammar small
+## Keep it readable
-Define what shapes, lines, color, and annotations mean, then reuse that grammar
-consistently. If a visual distinction does not encode information, remove it.
-
-## Make labels do real work
-
-Use short, concrete labels. Keep explanatory prose outside the dense part of
-the diagram. A reader should be able to identify the system boundary, the
-important relationship, and the exceptional path without decoding a legend of
-decorations.
-
-## Verify the rendered result
-
-Inspect the diagram at its intended size. Check line crossings, label
-collisions, small text, contrast, and the reading order at narrow widths.
+Use a small set of shapes, lines, colors, and labels consistently. Keep dense
+explanation outside the diagram, and check that labels and paths remain legible
+at the size people will actually view it.
<GuideHandoff
artifactHref="/catalog/featured/workspaces-architecture.html"
artifactLabel="Open the request-path explorer"
- artifactDescription="Select flows and inspect how the full architecture responds."
+ artifactDescription="Choose a request and watch its path through the architecture."
sourceHref="https://github.com/plannotator/effective-html/blob/main/public/catalog/featured/workspaces-architecture.html"
skillHref="https://github.com/plannotator/effective-html/blob/main/skills/html-diagram/SKILL.md"
skillLabel="Use the diagram skill"
- skillDescription="Match the visual model to the relationship being explained."
+ skillDescription="Create an HTML diagram that fits the subject."
/>
<GuideNext
href="/docs/decks"
- title="Tell the story as a sequence"
- description="Use a browser-native deck when pacing and progression carry the explanation."
+ title="Decks"
+ description="See how a browser-native presentation can combine slides, interaction, and motion."
/>
diff --git a/site/content/docs/index.mdx b/site/content/docs/index.mdx
index c120721..d3efcdb 100644
--- a/site/content/docs/index.mdx
+++ b/site/content/docs/index.mdx
@@ -1,13 +1,17 @@
---
title: Effective HTML guide
-description: Use context-rich HTML artifacts to understand, review, and direct agent work.
+description: A short guide to wireframes, mockups, prototypes, diagrams, decks, and other HTML artifacts made with agents.
---
-Effective HTML is a field guide to making visual, interactive artifacts with
-agents. It is for developers and for anyone who needs to understand, review, or
-direct agent work.
+Agents can build wireframes, mockups, prototypes, diagrams, decks, and small
+interfaces. These can be easier to understand than a long prompt or Markdown
+file.
-This guide collects ideas from:
+This is a short guide to those uses. You do not need to install a skill or
+follow a fixed process. Use the examples as references and ask your agent for
+the artifact you need.
+
+The guide draws from:
<GuideSources>
<a
@@ -62,57 +66,9 @@ This guide collects ideas from:
</a>
</GuideSources>
-## Start without a skill
-
-You do not need to install a skill to use these patterns. Ask an agent to make
-an HTML artifact, provide the source context and the decision it needs to
-support, then review the result.
-
-The working bias is **fat artifacts + fat context**. Give the agent the real
-brief, source material, constraints, examples, and accepted decisions. Let the
-artifact carry the working detail through realistic content, annotations,
-states, and interactions. The prompt and skills can stay thin. Use a skill when
-a pattern recurs or a team needs shared defaults; once the pattern is familiar,
-the skill may stop adding value.
-
-HTML is useful with agents because it can combine structure, visual form, and
-interaction in one inspectable thing.
-
-The point is not to replace Markdown. The point is to recognize the decisions
-that become easier when the artifact can show layout, compare alternatives,
-respond to input, or expose relationships directly.
-
-## Start with the decision
-
-Ask what the next human judgment actually is:
-
-- **What belongs, and where?** Start with a wireframe.
-- **How should this feel and look?** Make a more resolved mockup.
-- **Does this flow behave correctly?** Build a prototype.
-- **How do these parts relate?** Draw a diagram.
-- **What story needs deliberate sequence and pacing?** Build a browser-native deck.
-- **What sequence preserves the source commitments?** Write a plan.
-
-Higher fidelity is not automatically better. The right artifact is the lowest
-fidelity that answers the current question without creating a new distraction.
-
-## The working loop
-
-1. Name the decision the artifact needs to support.
-2. Choose the form and fidelity that make that decision visible.
-3. Make one self-contained artifact with realistic content.
-4. Inspect it at real desktop and mobile sizes.
-5. Review the structure, behavior, and boundaries that matter at this stage.
-6. Revise or advance the fidelity only when the next decision requires it.
-
-## What this guide covers
-
-The guide covers wireframes, prototypes, diagrams, browser-native decks, and
-plans. It also includes a generic [artifact design
-approach](/docs/designing-artifacts) that can sit above any of those forms. The
-examples stay inspectable and source-grounded. They demonstrate the patterns;
-they are not prerequisites for using them.
+## Browse examples
-Continue with [why HTML](/docs/why-html), learn the generic approach to
-[designing artifacts](/docs/designing-artifacts), or go directly to [choosing
-fidelity](/docs/choosing-fidelity).
+Browse the [catalog](/catalog) for live HTML artifacts, SVGs, examples, and
+skills. The rest of this guide gives short overviews of [why HTML can help](/docs/why-html), [wireframes](/docs/wireframes),
+[prototypes](/docs/prototypes), [diagrams](/docs/diagrams),
+[decks](/docs/decks), and [plans](/docs/plans).
diff --git a/site/content/docs/plans.mdx b/site/content/docs/plans.mdx
index bbe7f2c..067a8a7 100644
--- a/site/content/docs/plans.mdx
+++ b/site/content/docs/plans.mdx
@@ -1,49 +1,44 @@
---
title: Plans
-description: Preserve commitments and implementation sequence without adding visual ceremony.
+description: Use HTML plans when timelines, comparisons, dependencies, or embedded examples help explain the work.
---
-Plans are often better as Markdown. The information is usually linear, the
-source commitments matter, and the reader needs a durable sequence more than a
-visual interface.
+Plans are usually easiest to read and edit as Markdown. HTML can help when the
+plan includes visual information that does not fit naturally in a linear
+document.
<GuideChapterEvidence chapter="plans" />
-## Use HTML selectively
+## When HTML helps
-HTML can help when the plan needs:
+An HTML plan can include:
-- side-by-side comparison of alternatives;
-- a timeline with meaningful overlap;
-- an interactive dependency view;
-- expandable evidence attached to milestones;
-- a review surface that combines a plan with diagrams or working examples.
+- side-by-side alternatives;
+- timelines with overlapping work;
+- dependencies;
+- diagrams or working examples;
+- expandable detail attached to a step.
-If none of those improve the decision, keep the plan simple.
+If the plan is just a sequence of tasks, keep it simple and use Markdown.
-## Preserve the source
+## Keep it tied to the source
-A plan should distinguish supplied requirements from interpretation. Keep
-scope, dependencies, validation, and unresolved questions visible. Do not
-invent product claims or infrastructure to make the plan appear complete.
-
-## Make verification part of the sequence
-
-Name the checks that establish completion. Connect them to the work they
-validate instead of collecting every test in a vague final phase.
+A plan should preserve the supplied requirements, scope, dependencies, checks,
+and unresolved questions. It should not invent missing product or technical
+details to make the plan look complete.
<GuideHandoff
artifactHref="https://thariqs.github.io/html-effectiveness/16-implementation-plan.html"
artifactLabel="Inspect the HTML plan reference"
- artifactDescription="See the case where visual grouping earns the extra medium."
+ artifactDescription="See how an implementation plan can use visual grouping."
sourceHref="https://github.com/plannotator/effective-svg"
skillHref="https://github.com/plannotator/effective-html/blob/main/skills/html-plan/SKILL.md"
skillLabel="Use the plan skill"
- skillDescription="Preserve supplied commitments and choose Markdown first."
+ skillDescription="Create a plan without inventing missing requirements."
/>
<GuideNext
href="/catalog?view=compact#catalog-collection"
- title="Browse the complete artifact field"
- description="Compare the guide's decisions against real HTML, SVG, and interactive work."
+ title="Browse the catalog"
+ description="Open the HTML, SVG, and interactive examples."
/>
diff --git a/site/content/docs/prototypes.mdx b/site/content/docs/prototypes.mdx
index bf82295..b56234b 100644
--- a/site/content/docs/prototypes.mdx
+++ b/site/content/docs/prototypes.mdx
@@ -1,57 +1,40 @@
---
title: Prototypes
-description: Test a credible flow and the states that could change the decision.
+description: Use interactive HTML prototypes to try product flows, behavior, and states.
---
-A prototype is useful when static appearance cannot answer the question.
+A prototype lets you try part of an app before building or changing the real
+product. An agent can make a self-contained HTML prototype with realistic
+content and enough behavior to show how the flow works.
<GuideChapterEvidence chapter="prototypes" />
-## Build the narrowest credible flow
+## What a prototype can show
-Choose one path that represents the product decision. Give it realistic inputs,
-feedback, and transitions. Avoid building unrelated screens simply to make the
-artifact feel complete.
+- a multi-step flow;
+- loading, empty, error, and success states;
+- validation and feedback;
+- keyboard and mobile behavior;
+- transitions between views or modes.
-## Include the relevant states
+## It does not need to be the whole product
-The important states depend on the flow, but commonly include:
-
-- loading or pending work;
-- empty content;
-- validation failure;
-- recoverable error;
-- disabled controls;
-- successful completion;
-- keyboard focus and navigation.
-
-Implement states because they affect the judgment, not to satisfy a checklist
-detached from the product.
-
-## Preserve the product boundary
-
-A prototype should make clear what it is demonstrating and what remains
-illustrative. It should not imply a backend, permission model, or capability
-that has not been established.
-
-## Verify it as an interface
-
-Test the prototype at desktop and mobile sizes. Use the keyboard. Confirm
-labels, focus, contrast, and recovery. A broken demonstration creates false
-confidence.
+A useful prototype can cover one important path and the states around it. It
+does not need a backend, every screen, or every edge case. It should be clear
+which parts work and which parts are only visual.
<GuideHandoff
artifactHref="/examples/release-readiness/prototype.html"
artifactLabel="Open the live prototype"
- artifactDescription="Exercise the complete flow outside the embedded evidence frame."
+ artifactDescription="Try the release-readiness flow."
sourceHref="https://github.com/plannotator/effective-html/tree/main/examples/release-readiness"
skillHref="https://github.com/plannotator/effective-html/blob/main/skills/html-prototype/SKILL.md"
skillLabel="Use the prototype skill"
- skillDescription="Build one credible path and the states that can change the decision."
+ skillDescription="Create a working HTML prototype from a brief."
/>
<GuideNext
href="/docs/diagrams"
- title="Make relationships visible"
- description="Choose a diagram when geometry carries the hard part of the explanation."
+ title="Diagrams"
+ description="See how HTML can explain architecture, sequence, state, and flow."
/>
diff --git a/site/content/docs/why-html.mdx b/site/content/docs/why-html.mdx
index 561949f..4ccb6d3 100644
--- a/site/content/docs/why-html.mdx
+++ b/site/content/docs/why-html.mdx
@@ -1,77 +1,27 @@
---
title: Why HTML?
-description: Use visible structure when dense prose makes agent work harder to understand.
+description: Use HTML artifacts when seeing or trying an idea is clearer than reading about it.
---
-Effective HTML helps people understand and participate in agent work. That
-includes developers reviewing code and non-technical collaborators responding
-to a plan, prototype, report, diagram, or explainer.
-
-Markdown remains useful for linear explanation, short plans, and source-grounded
-lists. The problem is not Markdown. The problem is asking dense prose to carry
-information that would be clearer through space, comparison, state, or
-interaction.
+Agents often answer with prose, and sometimes that is the right format. HTML
+can be easier to understand when you need to compare designs, try a flow,
+inspect a system, or show how something works.
<GuideChapterEvidence chapter="why-html" />
-## Put the detail in the artifact
-
-Give the agent the relevant source context and name the decision a person needs
-to make. Keep the prompt direct. Let the artifact carry the working detail
-through realistic content, visible relationships, annotations, controls, and
-states.
-
-The skills in this repository teach recurring patterns and provide useful
-defaults. They are optional. Once you recognize what a useful artifact looks
-like, a direct request may be enough. Add a skill when repetition or consistency
-justifies one.
-
-## Use less prose when structure can explain
-
-Agents can produce more written material than people will read. A well-structured
-visual can communicate hierarchy, alternatives, state, and relationships
-without requiring someone to parse a long document first.
-
-This is often useful when technical teams share work with non-technical
-collaborators. A wireframe, diagram, or working prototype gives everyone the
-same thing to point at, question, and revise.
-
-## HTML can show the thing
-
-A layout discussion changes when reviewers can see the hierarchy at the target
-width. A behavior discussion changes when they can operate the control. A
-system discussion changes when relationships occupy a shared visual field.
-
-The artifact reduces translation work between an agent's description and a
-human's judgment.
-
-## HTML can hold multiple forms of evidence
-
-A single page can combine:
-
-- prose that explains the constraint;
-- a wireframe that exposes the hierarchy;
-- a diagram that clarifies the relationship;
-- a control that demonstrates the state change;
-- an annotation that names the unresolved decision.
-
-That combination is valuable when each form contributes something different.
-It becomes noise when HTML is used only to decorate information that would be
-clearer as a short document.
+## What HTML adds
-## HTML can be reviewed as a real boundary
+HTML can put explanation, layout, state, and interaction in one file. You can
+open it in a browser, test it at real sizes, click through it, annotate it, and
+share it with technical or non-technical collaborators.
-A self-contained artifact can be opened at real viewport sizes, navigated with
-a keyboard, inspected for contrast, and tested in loading, empty, failure, and
-success states. Those checks turn a proposal into something concrete enough to
-redirect.
+That makes HTML useful for wireframes, mockups, prototypes, diagrams, visual
+explainers, reports, presentations, and small purpose-built tools.
## Keep Markdown when it is enough
-Prefer Markdown for a linear plan, short explanation, or source-grounded list
-of commitments unless visual or interactive structure makes the work easier to
-understand. Choose HTML for the decisions it can expose, not because every
-agent output needs a webpage.
+Markdown is usually simpler for notes, short plans, and linear explanations.
+Use HTML when seeing or trying the idea adds something useful.
<GuideHandoff
artifactHref="/examples"
@@ -79,12 +29,12 @@ agent output needs a webpage.
artifactDescription="Inspect the release-readiness wireframe and prototype."
sourceHref="https://github.com/plannotator/effective-html"
skillHref="https://github.com/plannotator/effective-html/blob/main/skills/html/SKILL.md"
- skillLabel="Use the HTML router"
- skillDescription="Decide whether HTML adds useful evidence before building."
+ skillLabel="Read the HTML skill"
+ skillDescription="See the general guidance for making HTML artifacts."
/>
<GuideNext
href="/docs/choosing-fidelity"
- title="Choose the lowest useful fidelity"
- description="Match the artifact's finish to the decision being made now."
+ title="Wireframe, mockup, or prototype?"
+ description="See the practical difference between the common levels of fidelity."
/>
diff --git a/site/content/docs/wireframes.mdx b/site/content/docs/wireframes.mdx
index 6f913e9..30beece 100644
--- a/site/content/docs/wireframes.mdx
+++ b/site/content/docs/wireframes.mdx
@@ -1,56 +1,39 @@
---
title: Wireframes
-description: Explore structure without letting polish dominate the review.
+description: Use HTML wireframes to compare layouts, hierarchy, navigation, and responsive structure.
---
-Wireframes test the organization of an interface before visual finish makes
-changes feel expensive.
+Wireframes show how a page or flow is organized without presenting a finished
+design. An agent can turn the same brief into several HTML wireframes that you
+can open at desktop and mobile sizes.
<GuideChapterEvidence chapter="wireframes" />
-## Use them for
+## What a wireframe can show
-- content hierarchy and information density;
+- content hierarchy and density;
- navigation and page structure;
-- responsive reflow;
-- alternative layouts;
-- the order and grouping of controls;
-- the boundary between primary and supporting actions.
+- responsive layout;
+- different ways to organize the same content;
+- the order and grouping of controls.
-## Keep them intentionally unfinished
+## Keep the focus on structure
-A useful wireframe looks deliberate without looking final. Use a restrained
-palette, clear type hierarchy, visible boundaries, and realistic content.
-Avoid branded polish that causes reviewers to debate the surface instead of
-the structure.
-
-## Make alternatives genuinely different
-
-Changing only padding or card order does not produce a meaningful alternative.
-Explore different organizing ideas: an index versus a guided path, a split view
-versus a focused canvas, or a persistent control rail versus contextual
-actions.
-
-## Review questions
-
-- Can a person tell what the page is for within seconds?
-- Is the primary action obvious without being isolated from its context?
-- Does the hierarchy survive at narrow widths?
-- What can be removed before more detail is added?
-- Are the alternatives testing different structural hypotheses?
+Use realistic content, clear boundaries, and a restrained palette so people can
+compare layout and structure before discussing color, typography, and branding.
<GuideHandoff
artifactHref="/examples/release-readiness/wireframe.html"
artifactLabel="Open the wireframe"
- artifactDescription="Inspect the standalone artifact at real viewport widths."
+ artifactDescription="Open it at desktop and mobile widths."
sourceHref="https://github.com/plannotator/effective-html/tree/main/examples/release-readiness"
skillHref="https://github.com/plannotator/effective-html/blob/main/skills/html-wireframe/SKILL.md"
skillLabel="Use the wireframe skill"
- skillDescription="Turn a structural question into a bounded HTML wireframe."
+ skillDescription="Create a simple HTML wireframe from a brief."
/>
<GuideNext
href="/docs/prototypes"
- title="Test behavior next"
- description="Build a prototype when static structure cannot answer the question."
+ title="Prototypes"
+ description="See how a working HTML flow can show behavior and state."
/>