html-artifacts

HTML artifacts

The user describes a problem: a PR to understand, options to weigh, a workflow to try. HTML pages are how the user explores and thinks through a topic, so the page is often the main result and the chat reply stays short. Your job is to find the visual form that makes the problem clear or lets the user try it, and build it as one HTML page. You choose the form, the structure, and the interaction. The user iterates with annotations.

What the user values

• Visual over prose. The user learns by seeing and trying, so show it when it can be shown.
• Little prose. Short text at the point of use (on a control, beside a figure, in a status) helps; long paragraphs do not. A page that answers a question leads with the answer. A page to operate opens in a working state. Keep evidence, method, and caveats available but out of the way.
• Plain language, per the global Writing Style rule, in the user's language.
• A page that works well on a phone and on a desktop.
• The user's explicit requests win over anything here. When they ask for a format, a library, a layout, or Mermaid, use it.

Stay true to the sources

• Read the sources the task names (threads, files, diffs, notes) instead of working from a summary. Read the thread the task came from when context is missing.
• Show what the sources support. Keep what is measured, inferred, and assumed distinguishable, and do not drop important facts to make the page shorter.
• Use the user's own text verbatim when you show it.

Judgment that tends to work

These are observations, not rules. Choose what fits the problem.

• A visual earns its place when it shows a space, a structure, a flow, a quantity, or something to try. When a sentence is faster, write the sentence.
• Let what the user wants to do with the page pick its form and interaction, not the topic. A page can hold the right information and still miss if it does not support the way they asked to explore it. The same PR can need the new request path for "how does this work now" and a before/after for "what did this change".
• Draw the mechanism, not its name. For options, draw what differs between them.
• An answer that does not depend on the reader's input is often a diagram. A question about amounts is often a chart, a single number, or a table. "What happens if I do X" or "how does this feel" is often a working prototype.
• When the real system has a control, the figure can have it too. Interaction is for exploring the content. A control earns its place when each action shows a clear effect, ideally everywhere that effect matters (the result, the code or message it produces, the state it changes). An empty state says what to try next.
• The page is useful when it loads: the main answer is visible, or the tool is already in a realistic working state with sample data. Nothing important appears only on hover or after an animation.
• A prototype proves the core interaction. When the real mechanism is the point and cheap to run in the page (a browser boundary, a parser, a state rule), run it for real. Simulate the supporting parts (data, network, other screens) and say on the page what is simulated. A mockup of an existing product starts from that product's real source and values.
• SVG is the default for diagrams. Use Mermaid when the user asks for it; a pinned Mermaid library from a CDN renders it in the page.