Files
skills/public/chat-and-messaging.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
hanzoskills.com/llms.txt now opens with the install line, the API
reference index and the company index, so an agent that lands on any
one of the three can find the rest.

robots.txt claimed 537 documents while llms.txt counts 920. The number
is gone from robots.txt; llms.txt derives it.

public/ is regenerated from scripts/site.py, which it had fallen
behind: the copy-prompt menu and agent bar were in the generator and
not in the committed pages. tests/site.mjs passes against the result.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-11 00:27:59 -07:00

452 lines
21 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>chat-and-messaging</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="alternate" type="text/markdown" href="/chat-and-messaging.md">
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/chat-and-messaging">
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/chat-and-messaging.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>chat-and-messaging</h1><p class="lede">Chat is a conversation, not a document.</p><h1>Chat and Messaging Interfaces</h1>
<p>Chat is a conversation, not a document. Design for flow and readability.</p>
<h2>Message Structure</h2>
<pre><code class="lang-typescript">interface Message {
role: &#x27;user&#x27; | &#x27;assistant&#x27; | &#x27;system&#x27;;
content: string;
timestamp: Date;
status?: &#x27;sending&#x27; | &#x27;sent&#x27; | &#x27;error&#x27;;
attachments?: Attachment[];
}</code></pre>
<h2>Visual Design Guidelines</h2>
<p><strong>Layout:</strong></p>
<ul><li><strong>Alternating alignment</strong>: User messages right, assistant left (or use color/avatar distinction)</li><li><strong>Generous padding</strong>: 16-24px within messages for readability</li><li><strong>Subtle backgrounds</strong>: Use background color to distinguish roles, not heavy borders</li><li><strong>Avatar placement</strong>: Left side with 8-12px spacing</li><li><strong>Time stamps</strong>: Subtle, small (11-12px), gray, right-aligned or on hover</li><li><strong>Max width</strong>: 65-75 characters (600-800px) for message content</li></ul>
<pre><code class="lang-css">.chat-container {
max-width: 800px;
margin: 0 auto;
padding: var(--space-4);
display: flex;
flex-direction: column;
gap: var(--space-4);
}
.message {
display: flex;
gap: var(--space-3);
padding: var(--space-4);
border-radius: 12px;
max-width: 75%;
}
.message-user {
align-self: flex-end;
background: var(--color-primary);
color: var(--color-primary-foreground);
}
.message-assistant {
align-self: flex-start;
background: var(--color-muted);
color: var(--color-foreground);
}
.message-timestamp {
font-size: 11px;
color: var(--color-muted-foreground);
margin-top: var(--space-1);
}</code></pre>
<h2>Message States</h2>
<pre><code class="lang-css">/* Sending state - subtle opacity */
.message-sending {
opacity: 0.6;
transition: opacity 0.2s;
}
/* Error state - clear but not alarming */
.message-error {
border-left: 3px solid var(--color-error);
background: color-mix(in srgb, var(--color-error) 5%, transparent);
}
/* Streaming state - subtle pulse */
@keyframes pulse {
0%, 100% { opacity: 1; }
50% { opacity: 0.5; }
}
.message-streaming::after {
content: &#x27;▊&#x27;;
animation: pulse 1s ease-in-out infinite;
font-family: &#x27;Zen Mono&#x27;, monospace;
}</code></pre>
<h2>Input Area Design</h2>
<p><strong>Features:</strong></p>
<ul><li><strong>Auto-expanding textarea</strong>: Grows with content, max 6-8 lines before scroll</li><li><strong>Clear send button</strong>: Icon + text on desktop, icon only on mobile</li><li><strong>Attachment preview</strong>: Show thumbnails of uploaded files</li><li><strong>Character limit</strong>: Show remaining count only when approaching limit</li><li><strong>Loading state</strong>: Disable input, show spinner in send button</li></ul>
<pre><code class="lang-typescript">const ChatInput = () =&gt; {
const [message, setMessage] = useState(&#x27;&#x27;);
const [isSubmitting, setIsSubmitting] = useState(false);
const textareaRef = useRef&lt;HTMLTextAreaElement&gt;(null);
const adjustHeight = () =&gt; {
const textarea = textareaRef.current;
if (textarea) {
textarea.style.height = &#x27;auto&#x27;;
textarea.style.height = `${Math.min(textarea.scrollHeight, 8 * 24)}px`; // max 8 lines
}
};
return (
&lt;div className=&quot;chat-input&quot;&gt;
&lt;textarea
ref={textareaRef}
value={message}
onChange={(e) =&gt; {
setMessage(e.target.value);
adjustHeight();
}}
onKeyDown={(e) =&gt; {
if (e.key === &#x27;Enter&#x27; &amp;&amp; !e.shiftKey) {
e.preventDefault();
handleSend();
}
}}
placeholder=&quot;Type a message...&quot;
disabled={isSubmitting}
/&gt;
&lt;button onClick={handleSend} disabled={isSubmitting || !message.trim()}&gt;
{isSubmitting ? &lt;Spinner /&gt; : &lt;SendIcon /&gt;}
&lt;/button&gt;
&lt;/div&gt;
);
};</code></pre>
<h2>Scroll Behavior</h2>
<p><strong>CRITICAL:</strong> Respect user scroll position while auto-scrolling for new messages.</p>
<pre><code class="lang-typescript">function ChatMessages({ messages }: { messages: Message[] }) {
const messagesEndRef = useRef&lt;HTMLDivElement&gt;(null);
const scrollContainerRef = useRef&lt;HTMLDivElement&gt;(null);
const [isUserScrolling, setIsUserScrolling] = useState(false);
const scrollToBottom = () =&gt; {
if (!isUserScrolling) {
messagesEndRef.current?.scrollIntoView({
behavior: &#x27;smooth&#x27;,
block: &#x27;end&#x27;
});
}
};
useEffect(() =&gt; {
const container = scrollContainerRef.current;
if (!container) return;
const handleScroll = () =&gt; {
const { scrollHeight, scrollTop, clientHeight } = container;
// User is near bottom if within 100px
const isNearBottom = scrollHeight - scrollTop - clientHeight &lt; 100;
setIsUserScrolling(!isNearBottom);
};
container.addEventListener(&#x27;scroll&#x27;, handleScroll);
return () =&gt; container.removeEventListener(&#x27;scroll&#x27;, handleScroll);
}, []);
useEffect(() =&gt; {
scrollToBottom();
}, [messages]);
return (
&lt;div ref={scrollContainerRef} className=&quot;messages-container&quot;&gt;
{messages.map((msg) =&gt; (
&lt;Message key={msg.id} message={msg} /&gt;
))}
&lt;div ref={messagesEndRef} /&gt;
&lt;/div&gt;
);
}</code></pre>
<h2>Markdown Rendering</h2>
<p><strong>Libraries:</strong></p>
<ul><li><code>react-markdown</code> - Parse and render markdown</li><li><code>remark-gfm</code> - GitHub Flavored Markdown support</li><li><code>rehype-sanitize</code> - Sanitize HTML to prevent XSS</li></ul>
<pre><code class="lang-typescript">import ReactMarkdown from &#x27;react-markdown&#x27;;
import remarkGfm from &#x27;remark-gfm&#x27;;
import rehypeSanitize from &#x27;rehype-sanitize&#x27;;
import { Prism as SyntaxHighlighter } from &#x27;react-syntax-highlighter&#x27;;
import { oneDark } from &#x27;react-syntax-highlighter/dist/esm/styles/prism&#x27;;
function MessageContent({ content }: { content: string }) {
return (
&lt;ReactMarkdown
remarkPlugins={[remarkGfm]}
rehypePlugins={[rehypeSanitize]}
components={{
code({ node, inline, className, children, ...props }) {
const match = /language-(\w+)/.exec(className || &#x27;&#x27;);
return !inline &amp;&amp; match ? (
&lt;SyntaxHighlighter
style={oneDark}
language={match[1]}
PreTag=&quot;div&quot;
{...props}
&gt;
{String(children).replace(/\n$/, &#x27;&#x27;)}
&lt;/SyntaxHighlighter&gt;
) : (
&lt;code className={className} {...props}&gt;
{children}
&lt;/code&gt;
);
}
}}
&gt;
{content}
&lt;/ReactMarkdown&gt;
);
}</code></pre>
<h2>Streaming Messages</h2>
<p>For real-time streaming (like ChatGPT):</p>
<pre><code class="lang-typescript">function StreamingMessage({ stream }: { stream: ReadableStream }) {
const [content, setContent] = useState(&#x27;&#x27;);
const [isComplete, setIsComplete] = useState(false);
useEffect(() =&gt; {
const reader = stream.getReader();
const decoder = new TextDecoder();
async function read() {
try {
while (true) {
const { done, value } = await reader.read();
if (done) {
setIsComplete(true);
break;
}
const text = decoder.decode(value, { stream: true });
setContent(prev =&gt; prev + text);
}
} catch (error) {
console.error(&#x27;Stream error:&#x27;, error);
}
}
read();
}, [stream]);
return (
&lt;div className=&quot;streaming-message&quot;&gt;
&lt;MessageContent content={content} /&gt;
{!isComplete &amp;&amp; &lt;span className=&quot;cursor-blink&quot;&gt;▊&lt;/span&gt;}
&lt;/div&gt;
);
}</code></pre>
<h2>Best Practices</h2>
<h3>Do:</h3>
<ul><li>✅ Preserve user scroll position (don&#x27;t force scroll if reading)</li><li>✅ Show message status (sending, sent, error)</li><li>✅ Support markdown and code highlighting</li><li>✅ Use generous spacing (16-24px padding)</li><li>✅ Limit message width (65-75 characters)</li><li>✅ Show timestamps subtly</li><li>✅ Support keyboard shortcuts (Enter to send, Shift+Enter for newline)</li><li>✅ Sanitize HTML to prevent XSS</li></ul>
<h3>Don&#x27;t:</h3>
<ul><li>❌ Force scroll when user is reading older messages</li><li>❌ Make messages too wide (hard to read)</li><li>❌ Use heavy borders or shadows</li><li>❌ Show timestamps prominently (they&#x27;re noise)</li><li>❌ Forget error recovery (retry failed messages)</li><li>❌ Block input during streaming (allow cancellation)</li><li>❌ Render unsanitized HTML from user input</li></ul>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/chat-and-messaging.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>