HeroCanvas
AGENTS.md5 starsChanged 13 days agoApache-2.0View on GitHub
Guidance for anyone building here with an AI agent (Claude Code reads it through CLAUDE.md; other agents read this file). The README says what HeroCanvas is; this file is how to change it. Two sides, as in Laravel's skeleton and framework: - The team's code, at the root: app/ (the connected app; none yet, so HeroCanvas shows its own tour), proposals/, herocanvas.config.ts, brand/. It imports the tool only as from 'herocanvas' (src/index.ts, the public API); a test fails on any…
- Reads credentials
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 33,315 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository6 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- connect-appSkill
- mirror-screenSkill
- new-personaSkill
- new-proposalSkill
- update-herocanvasSkill
The file
We split this AGENTS.md into the rules it gives an agent
1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 76
The interface in two languages: every text HeroCanvas's own interface shows goes through t('English text') (src/i18n/ui.ts), its Spanish in …
≈ “Common” is an estimate: at least 1 in 5 of the 42,283 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Working on HeroCanvas
Guidance for anyone building here with an AI agent (Claude Code reads it through CLAUDE.md; other agents read this
file). The README says what HeroCanvas is; this file is how to change it.
Where a change goes
Two sides, as in Laravel's skeleton and framework:
- The team's code, at the root:
app/(the connected app; none yet, so HeroCanvas shows its own tour),proposals/,herocanvas.config.ts,brand/. It imports the tool only asfrom 'herocanvas'(src/index.ts, the public API); a test fails on any import reaching intosrc/. - The tool, in
src/: never knows the app. It reads it as@app: its settings (config.ts), pages (pages.tsx), navigation (index.ts), stories, connectors (connectors/*.json), screen config and the--app-*tokens. A tool that needs to know a page by name is in the wrong place: declare it in the manifest instead. - The iOS kit (
src/ios,herocanvas/ios): SwiftUI's own views (a NavigationStack's screen, List's Sections and rows, Picker, Toggle…), named as SwiftUI names them, on the--app-*tokens: a SwiftUI app's mirror uses them instead of rebuilding the platform. - The kit (
src/kit, part of the tool): the overlays the simulator presents with, and their buttons. Styled only with--app-*tokens, so any app's look reaches them.
The contract is what crosses between them: src/index.ts and what the tool reads from app/. While in 0.x it may
change; each change goes in src/CHANGELOG.md under Contract, saying what to adapt, so a team's agent can do it on
update (update-herocanvas). At 1.0 it holds still. A new folder or file of the tool's goes in
scripts/update/tool-files.json, or updates won't bring it.
Procedures (skills)
Step by step, in .claude/skills/<name>/SKILL.md (Claude Code loads them on its own; any other agent reads the file
when the task is one of these):
connect-app: the person's app connected for the first time: its code read (any stack), or a Figma file;app/filled with its mirror (settings, tokens, navigation, one page per screen).mirror-screen: one screen or component of the app, built or fixed to match its code.new-proposal: a change to the app as a proposal (proposals/<slug>), with versions and a handoff.new-persona: one or several personas, from what about a user changes the app's screens and the person's answers: each with its mock data and an optional photo (npm run persona:avatar).update-herocanvas: a newer HeroCanvas into this copy (npm run update), its clashes resolved and the team's code adapted to the contract's changes.
The person's app's own repository is read, never edited: everything goes in HeroCanvas.
Rules
- Fast: animations on the compositor (
transform,opacity), no heavy work in render, no new runtime dependency without a strong reason (today: React, React Router). - Declare, don't special-case: pages, their state, flows, scenario controls and list–detail live in the manifest.
- One source of truth for data: an app's mock data lives in one module its screens derive from.
- Components are instrumented: a component marks its root with
useComponent(name, props)(fromherocanvas) so Inspect and Layers find it, and has stories (<Name>.stories.tsx) for the gallery. - One surface for what floats: a menu, dropdown or popover of the designer composes
surfacefromsrc/theme/surface.module.css(its background, radius and the theme's--ui-pop-shadow, which sets it apart in light and dark), and an empty list shows itsemptystate, never bare headers. - Pages, one icon: wherever the designer lists pages, a page's icon is a phone (
ROLE_ICONS,src/nav/stack.ts), its role (tab, push, cover, boot) in its tooltip, badge and indent; the same for every app, never the app's own icons, which may be missing or not drawable. - The tour stands in for an app: with none connected (
NO_APP,src/nav/noApp.ts), HeroCanvas shows its own (src/tour): its pages, navigation, components with their stories, and its theme as--app-*tokens (src/tour/theme.css), so every mode has something real. A new part of the designer gets a step insrc/tour/steps.ts, itsspotsnaming the controls it points at (data-touron them): a beacon pulses on each while the step is open. - Launch in four phases: an app's launch screen is
appConfig.launch(screen, enter, hold, exit: the names iOS and Android share), played by the simulator; a screen waits for it withuseLaunchPhase(). Never a splash of a screen's own. - A component against the code, in three words: Matches code, Differs from code, or Local (only in HeroCanvas, not in the app's code). Where it came from (a Figma file, another design tool, a proposal) is a note, never a state of its own; tiers (Atoms…) show only when Figma or the code gives them. Tokens the same: no code connector, no "not in the code".
- Icons as the app draws them: Material Symbols by name (
<Icon name="search" />), or the app's SF Symbols and its own symbols assf:<name>(<Icon name="sf:magnifyingglass" />), made on a Mac withnpm run symbolsintopublic/symbols/andapp/symbols.json(the team's); with no names it makes HeroCanvas's own, the system keyboards' and the iOS kit's glyphs (scripts/symbols/system.json), which they draw in Material's closest without. HeroCanvas ships no SF Symbols: Apple's license allows them to design apps for its platforms, made from the Mac's own copy. - Public files by
import.meta.env.BASE_URL, never from/: the built site is relative (base: './'), so it works at a domain's root or under a path (GitHub Pages). - The interface in two languages: every text HeroCanvas's own interface shows goes through
t('English text')(src/i18n/ui.ts), its Spanish insrc/i18n/es/<area>.jsonby the glossary (src/i18n/GLOSSARY.md); a test fails on a missing or unused one. Never translate what the app's screens show (they keep the app's languages), nor what's written for developers and agents (handoffs, prompts, exported files). A team picks it inherocanvas.config.ts(language: 'es'). - Guest views: a guest link (src/share) shows a profile of the designer (
src/share/profiles.ts): its modes, its panels by id, its controls. A new panel is left out of them unless a profile names it; a new control a guest shouldn't have askscan('…')(src/share/view.ts), with a newViewControlif none fits. - Comments say why, in short sentences, matching the code around them.
Before you call it done
npm run typecheck, npm run lint, npm test, npx vite build; then look at it (npm run shot -- "/today", or the
dev server) on a phone and a tablet, light and dark.
Versioning: two versions, two changelogs.
- This copy's (
package.json'sversion,CHANGELOG.mdat the root): the team's mirror and proposals. A change toapp/orproposals/bumps it and adds an entry. Shown at the top left of the toolbar. - HeroCanvas's (
src/version.json,src/CHANGELOG.md): only when developing HeroCanvas itself. Every commit to the tool bumps it (0.Y.0 features, 0.Y.Z fixes), adds an entry (a Contract item for what a team must adapt), updates the README's badge, and is taggedvX.Y.Z: the tags are whatnpm run updateinstalls. Shown on its page (#/about), from the ⓘ at the bottom of the left rail. A pull request from a fork leaves both alone: they're bumped and tagged when it's merged intomain(one squashed commit), so two open at once don't clash.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

