@kolisachint/hoocode-agent 0.5.41 → 0.5.42

package/templates/skills/artifact-design/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: artifact-design
+description: Build a self-contained HTML visual written to disk — page, report, dashboard, mockup, diagram, or poster. Load before the first line of markup or CSS whenever something has to look right, or a redesign is asked for. Not for app code the project's own design system already governs.
+allowed-tools: read, write, edit, grep, find, ls
+---
+
+# Designing a visual
+
+hoocode writes visuals as one self-contained `.html` file on disk. There is no
+host, no CSP, and no gallery: fonts and libraries may come from a CDN or from
+local files, and the page is yours to lay out however the subject demands. The
+constraint that remains is the only one that ever mattered — it has to be good.
+
+Not for a canvas extension. A canvas serves a live page from its own loopback
+server, under constraints that contradict half of this file, and `/new-canvas`
+points at `../canvas-design/SKILL.md` for it.
+
+## First, read the request
+
+Decide the treatment, not whether to design. Every visual gets real typographic
+hierarchy, considered spacing, and a deliberate palette. What varies is how far
+past that you go.
+
+- **Utilitarian** — a report, a plan, a status page, a diagram. Most requests.
+  Make it clean and well-composed. Skip the oversized hero. Keep flourishes few.
+- **Editorial** — a landing page, a poster, something the user will show other
+  people. Take a real point of view and one deliberate risk.
+
+When unsure, build the well-composed version. A restrained page is never wrong;
+an over-designed one sometimes is.
+
+## Honor what already exists
+
+Look before you invent. If the repo has a design system — a tokens file, a
+theme, CSS variables, an existing stylesheet, a brand section in a project
+context file — use it. Precedence is always:
+
+1. What the user asked for, in their words
+2. The project's existing system
+3. Your own choices
+
+Your choices fill gaps. They never override the first two.
+
+## Write the plan before the markup
+
+This is the part that does the work. Before any code, write down:
+
+- **Color** — 4 to 6 named hex values. Name them by role (`ink`, `ground`,
+  `accent`, `muted`), not by hue.
+- **Type** — at least two faces with distinct jobs: one with character for
+  display, one comfortable for body text, and a third for data or captions if
+  the content needs it. Name the fallback stack for each.
+- **Layout** — the structural idea in one or two sentences.
+
+Then build from the plan and derive every color and type decision from it. A
+page assembled without a plan reads as assembled without a plan.
+
+## Fundamentals
+
+**Ground it in the subject.** One concrete subject, one audience, one job for
+the page. Distinctive choices come from the subject's own world — its materials,
+its vocabulary, how people in it actually talk. Use real content throughout.
+Never lorem, never placeholder rows.
+
+**Type carries the page,** including when the page is not about type. Keep
+running text near 65 characters wide. Set a scale and stay on it. Give headings
+`text-wrap: balance`, give body text line-height room, give uppercase labels a
+little letter-spacing. Always declare a real fallback stack — a silent fallback
+is the most common way a good design ships looking wrong.
+
+**Pick the neutrals.** A pure mid-grey reads as unconsidered. Bias the greys
+slightly toward the accent hue and they read as chosen. Pure white and near-black
+are fine grounds when the subject wants them; the point is that you decided.
+
+**Let layout do the spacing.** Flex or grid with `gap`, not per-element margins
+that collapse or double unpredictably. Wide content — tables, code blocks,
+diagrams — gets its own `overflow-x: auto` container so the page body never
+scrolls sideways. Use `font-variant-numeric: tabular-nums` wherever digits line
+up in a column.
+
+**Design both themes.** A local page sees only `prefers-color-scheme`, so this
+is simpler here than on a hosted target: define the complete palette as custom
+properties on `:root`, redefine only those properties inside
+`@media (prefers-color-scheme: dark)`, and style every component through the
+properties. Never give a color its only definition inside the media block — that
+is how a page ends up rendering one theme's text on the other theme's ground.
+Set an explicit `background` on `body`. Give the second theme the same attention
+as the first rather than inverting it mechanically; check that the accent still
+works on both grounds. A page that deliberately commits to one visual world may
+stay single-theme, but then paint every color explicitly so it holds either way.
+
+**Structure should encode something true.** Numbered markers, eyebrows,
+dividers, and section labels are information, not decoration. Number things only
+when the order actually matters to the reader.
+
+**When it is a UI, not a document,** the craft shifts from typography to
+information design. A dashboard is scanned, not read. Put the summary above the
+detail. Encode state in form as well as in number — a pill, a chip, a severity
+stripe — so what needs attention is visible at a glance. Semantic color (good,
+warning, critical) is a separate system from your accent and does not count as
+using it. Anything interactive should look interactive.
+
+## Avoid the generated look
+
+Machine-generated design keeps landing on the same handful of looks. When the
+user has specified a direction, follow it exactly, including if it is one of
+these. When nothing is specified, do not spend the freedom here:
+
+- Warm cream ground, serif display face, terracotta accent
+- Near-black ground with a single acid-green or vermilion pop
+- Hairline rules and dense columns imitating a broadsheet
+- Purple-to-blue gradient hero on white
+- Inter or Space Grotesk chosen as the safe default
+- Emoji as section markers
+- Everything centered
+- Uniform large corner radii on every surface
+- A colored accent rail down the side of every card
+
+## Words are design material
+
+Write from the reader's side of the screen. Name things the way they would name
+them, not the way the system is built. Active voice. A control says exactly what
+it does, and the confirmation matches it. Errors say what went wrong and what to
+do about it. Specific beats clever.
+
+Give the page a real `<title>` — a short, specific noun phrase, not a category
+label and not a name with an explainer bolted on after a dash.
+
+## Libraries, and why the answer is usually none
+
+A hosted page and a file on disk fail differently, and that decides this. A
+hosted page is always viewed online, so a CDN dependency is free. A file gets
+moved, attached to mail, and opened on a laptop in a tunnel — and there a
+runtime dependency does not degrade, it collapses. Tailwind from a CDN with no
+network is an unstyled document. React from a CDN with no network is a blank
+one.
+
+So the default is no runtime dependency at all. Write plain CSS; modern CSS has
+custom properties, grid, `clamp()`, and container queries, and a page that needs
+a utility framework to be laid out usually needs a clearer layout instead.
+
+There is no build step here and nothing bundles this file, so a framework that
+expects one — Vite, a JSX pipeline, anything importing bare module specifiers —
+is not an option regardless.
+
+When a library genuinely earns its place, and that is mostly charting or syntax
+highlighting rather than layout:
+
+- Inline it into the file if its licence permits, and the page stays whole.
+- Otherwise pin an exact version, give the feature a readable fallback for when
+  the script does not load, and tell the user the page needs network.
+
+Webfonts are the one dependency that degrades gracefully, because a real
+fallback stack keeps the page readable when the link fails. Use one, and always
+declare the stack.
+
+## Build cleanly
+
+- Watch selector specificity. Type-level and element-level selectors fighting
+  over the same padding is how spacing silently comes undone.
+- Close every non-void element and double-quote every attribute.
+- Give keyboard focus a visible state.
+- Respect `prefers-reduced-motion`.
+- For generative or decorative graphics, reach for Canvas or WebGL rather than
+  hand-authoring long SVG path data.
+- Before finishing, scan the stylesheet for any color declared only inside a
+  media query.
+
+## Delivering it
+
+Write one self-contained `.html` file. Inline the page's own CSS and JS; embed
+small assets as data URIs so the file survives being moved or sent to someone.
+
+Put it where the user would expect it — alongside the data it visualizes, or in
+the directory they named. Then give them the path as a markdown link with a
+`file://` URL:
+
+```
+[tokens.html](file:///abs/path/to/tokens.html)
+```
+
+hoocode's markdown renderer turns that into an OSC 8 hyperlink wherever the
+terminal supports one, so it is clickable in kitty, iTerm2, WezTerm and others,
+and still readable as plain text everywhere else. Offer to open it rather than
+opening it unasked.
+
+Canvas is not a viewer for this. `/canvas` hosts canvas extensions — a directory
+with an `extension.mjs` speaking the canvas JSON-RPC protocol — and `/canvas
+open` takes an extension id, not a file path. A page you can hand someone is a
+file; reach for `/new-canvas` only when the user wants a live surface the agent
+can call typed actions on, which is a different and larger job than a visual.

package/templates/skills/canvas-design/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: canvas-design
+description: How to make a canvas extension's page good — layout, styling, live state, and the dependency and token constraints the surface imposes. Read when building or editing a canvas; the /new-canvas brief points here.
+disable-model-invocation: true
+allowed-tools: read, write, edit, grep, find, ls
+---
+
+# Designing a canvas
+
+A canvas is not a document. It is a small application: a page served over
+loopback that a person operates while you drive the same state through typed
+actions. Both of you are live on it at once, and that is the whole design
+problem.
+
+Read `../artifact-design/SKILL.md` for the fundamentals — treatment, the
+color/type/layout plan you write before any markup, neutrals, spacing, the
+generated-look list. All of it applies. This file covers only what is different
+because the surface is a canvas, and where the two disagree, this file wins.
+
+## What the catalog already tells you
+
+Of the 23 extensions in GitHub's canvas catalog, 22 import nothing but
+`@github/copilot-sdk` and `node:` builtins. The single exception ships a README
+telling the user to `npm install` by hand. Zero dependencies is not a
+restriction someone imposed on you; it is what working canvases actually do.
+
+The flagship, `pr-artifact-explorer`, is a rich **read** surface the agent
+navigates — its shared state is a cache and a route, and neither party co-edits
+content. It sidesteps concurrent editing entirely. Treat that as evidence about
+what is easy and what is not: a canvas that shows state well is worth far more
+than one that lets both parties type into the same field.
+
+## The page lives inside a template string
+
+The HTML is a JavaScript template literal in `extension.mjs`, not a file. Two
+consequences worth planning around rather than discovering:
+
+- Every backtick and `${` in your CSS or markup needs escaping. A `grid-template`
+  value or a JS snippet with a template literal inside it will break the outer
+  string. Prefer plain quotes and avoid nesting template literals.
+- There is no stylesheet to open in an editor. Keep the CSS in one clearly
+  delimited chunk near the top of the served string so it stays findable, rather
+  than scattering inline `style=` attributes.
+
+If the page grows past a screenful of markup, serve it from a separate file in
+the extension directory and read it at request time. The extension is already an
+HTTP server; it can serve its own assets. That is the escape hatch from string
+escaping, and it does not violate the no-dependency rule.
+
+## No dependencies, and no build
+
+`package.json` and `node_modules` are forbidden in the extension directory, so
+there is nothing to install and nothing to bundle. Write plain CSS and plain
+DOM. Modern CSS has custom properties, grid, and `clamp()`; a canvas that needs
+a utility framework needs a clearer layout instead.
+
+Do not reach for a CDN either. The page is served from `127.0.0.1`, so it works
+with no network — a CDN script throws that away and turns an offline-capable
+local tool into a broken one.
+
+## You own the theme completely
+
+The canvas protocol carries no theme, no palette, and no styling hook. Nothing
+is inherited. A page that sets no colors gets browser defaults, which is why the
+scaffold's placeholder looks like nothing.
+
+So define the full palette as custom properties on `:root`, redefine them under
+`@media (prefers-color-scheme: dark)`, and style everything through them. Set an
+explicit `background` on `body`. This is the same discipline as any page, with
+one simplification: there is no host stamping `data-theme`, so two states is the
+whole problem.
+
+## Design for two operators
+
+The person changes state through the page. You change the same state through
+`invoke_canvas_action`. The page has to be honest about that:
+
+- **Render from server state, not from what the user just clicked.** After an
+  action mutates state, the page must be able to show the new truth. Poll on a
+  short interval, or push with SSE — both are a few lines with no dependency.
+- **Make agent-reachable state visible.** If an action can add a note, the notes
+  should be on screen. State only you can see is state the person cannot trust.
+- **Do not build co-editing.** Concurrent edits to one field is the hard problem
+  the reference canvas declined to solve. Prefer append, toggle, and select over
+  a shared text buffer.
+- **Show that something changed.** When state moves underneath the person, a
+  brief highlight on the changed row beats a silent re-render.
+
+## Actions are tool schemas, so they cost
+
+Every action becomes an agent-callable tool while the instance is open, and its
+name, description, and `inputSchema` are re-sent on every request for as long as
+it stays open. Declare the actions the canvas actually needs and give each a
+tight schema — not one per button.
+
+Action results land in the model's context too. Return a summary and a count,
+not the whole collection; where a list is genuinely useful, slice it and set a
+flag saying you did. Measure with `hoocode --print-token-surface` while a canvas
+is open.
+
+## Reload replaces the URL
+
+Reloading forks a new process and hands back a **new** URL; the tab the person
+had open dies with the old one. Two design consequences:
+
+- Keep meaningful state on the server side of the canvas, not in the page. A
+  scroll position is fine to lose; a half-filled form is not.
+- Give the person the new URL every time you reload, and say the old tab is
+  dead. A page that silently stopped updating looks like a bug you caused.
+
+## Before you call it done
+
+- Open it and look, rather than reasoning about the markup.
+- Check both color schemes.
+- Resize narrow — a canvas is often a side window, not a full screen.
+- Invoke each action and confirm the page reflects it without a manual refresh.
+- Confirm the page still renders with the network off.