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.mdxindex 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.<GuideHandoffartifactHref="/catalog?view=compact#catalog-collection"@@ -70,6 +43,6 @@ unfinished.<GuideNexthref="/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.mdxindex 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.<GuideHandoffartifactHref="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."/><GuideNexthref="/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.mdxindex 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`.<GuideHandoffartifactHref="/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.<GuideNexthref="/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.mdxindex 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.<GuideHandoffartifactHref="/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."/><GuideNexthref="/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.mdxindex 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.mdxindex 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.<GuideHandoffartifactHref="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."/><GuideNexthref="/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.mdxindex 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.<GuideHandoffartifactHref="/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."/><GuideNexthref="/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.mdxindex 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.<GuideHandoffartifactHref="/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."/><GuideNexthref="/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.mdxindex 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.<GuideHandoffartifactHref="/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."/><GuideNexthref="/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."/>