# Voice & Tone

## Agent Instructions

You are writing KIRUPA content. For a tutorial, be a technically sharp friend at a whiteboard: explain why it matters, use a concrete running example, build intuition before jargon, and show state changes. Keep prose, code, and diagrams consistent; introduce images and supply purposeful alt text. Preserve the author's voice and uncertainty. Never invent expertise, facts, anecdotes, or citations. Use small bursts of playfulness without hype or applause. Short replies answer first and stay proportionate. Reference/API/error/safety text uses neutral precision, not a forced teaching voice.

Follow WCAG 2.2 AA for new or changed content: semantic HTML, keyboard access, visible focus, readable contrast in every theme, text alternatives, labeled controls, and explicit errors. Support zoom/reflow, respect reduced motion, and keep sound optional. Read /design/sections/accessibility.md for acceptance checks. Report unresolved barriers; automated checks alone do not establish conformance.

## Reference

KONVO-based tutorial guidance and examples for explanations, reference text, replies, and errors.

For tutorials, sound like a technically sharp friend at a whiteboard: casual but competent, direct rather than dry, playful in small bursts. Open with a plain-English reason to care. Use one concrete running example, establish its starting state, change one thing, then name the jargon once the reader has felt the idea.

> **Example: Start with a concrete reason**
> Our click counter keeps starting over at 1. We want the next click to continue from the previous value, so let's give that number somewhere to live between clicks.

Show state-by-state diagrams with stable objects, labels, and colors. Introduce each image in the preceding sentence and write purposeful alt text. Prose, code, and figures must agree about names, coordinates, values, and return behavior. A funny aside can release pressure; it should not interrupt a sequence someone is tracking.

> **Example: Show the change before naming it**
> Here is our counter after each click: `0 -> 1 -> 2`. A diagram would keep the same button in every frame and change only the displayed number. Its alt text could be: 'The counter starts at zero, then increases to one and two on successive clicks.'

[Tutorial text example](/design/voice.htm#specimen-voice)

Preserve the author's voice, point of view, and uncertainty. Never invent expertise, measurements, anecdotes, citations, or confidence to make a draft feel finished. Cut hype, generic applause lines, and sentences that only promise the next sentence will be interesting.

> **Example: Keep the uncertainty**
> If the draft says, 'I think recreating the callback is why the counter resets,' keep that uncertainty until the code supports the explanation. Don't rewrite it as a measured performance finding or an experience the author never described.

Short replies answer first and match the scale of the question. One specific follow-up is better than a speculative essay when the code or error is missing. Tutorial voice is not an API, reference, error, or safety-text template: those surfaces favor neutral precision and direct action names.

> **Example: Match the job**
> A reply with missing context can be just, 'Can you share the click handler?' An error can say, 'Could not load the image. Check your connection and try again.' Neither needs a story about a counter.

These are highlights adapted from the installed KONVO skill, not a requirement to apply an article outline to every page. The local skill is not bundled or required to read this reference. [Building Your First Interactive Web Page](https://www.kirupa.com/html5/building_your_first_web_page.htm) is a real example of the site's teaching voice.

> **Example: Keep reference text literal**
> For a button reference, 'Play starts the selected sample. Stop ends playback.' is enough. Save the running example and diagrams for a reader who is learning how the player works.

- Prefer: 'The button reads the old value because this callback kept the earlier state.'
- Avoid: 'Unlock a powerful new paradigm for seamless state management.'
- An error should say what failed and what to do next, not try to be charming.

## Sources

- [llms.txt](https://github.com/kirupa/kirupaWWW/blob/main/llms.txt)
- [https://www.kirupa.com/konvo.htm](https://www.kirupa.com/konvo.htm)

[Section page and specimens](/design/voice.htm) | [Instruction index](/design/index.md) | [Plain prompt](/design/agent/voice.txt)