agentleFS
OKHP3OKHP3/skillz/.agents/skills/okhp3-replit-canvas-board/SKILL.md

okhp3-replit-canvas-board

Skill3 starsChanged 2 months agoMITView on GitHub

Plan and build a structured multi-frame Replit canvas presentation board — hero rows, labeled zones, iframe lifecycle (building→live), coordinate layouts, and focusCanvasShapes for audience navigation. Use when organising the canvas for a designathon, showcase, or any multi-frame review. Also activate for "arrange the frames", "set up the board", "label the zones", "focus the viewport", or any canvas layout that needs deliberate spatial planning rather than ad-hoc placement.

The file

We split this skill into the rules it gives an agent

7 rules. About 0 are common, 2 are distinctive, and 5 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 5

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Before issuing any applyCanvasActions calls, write down:

    line 76
  2. Very specific:

    Every zone gets a text shape label placed directly above the zone's frames.

    line 116
  3. Very specific:

    For a presentation board: all frames must be "live" before calling focusCanvasShapes.

    line 142
  4. Very specific:

    Call getCanvasState with a wide focusArea before computing coordinates for a reorganisation:

    line 164
  5. Distinctive:

    When do you NOT need to read first?

    line 177
  6. Very specific:

    Use the full https:// URL in the url field.

    line 214
  7. Distinctive:

    Always call this as the last action of a canvas layout session.

    line 220

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill 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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

okhp3-replit-canvas-board

OverKill Hill P³ · overkillhill.com · github.com/OKHP3

A portable Replit Agent Skill for planning and organising the workspace canvas as a structured presentation board — not just placing shapes, but producing a layout that a judge, reviewer, or collaborator can scan in under 30 seconds.

This skill sits above the raw canvas skill API. It teaches layout strategy; the canvas skill (read .local/skills/canvas/SKILL.md) teaches the callbacks.


Scope

In scopeOut of scope
Zone planning, hero rows, gutter mathCanvas callback schemas — read the canvas skill
iframe building→live lifecycle for audience UXComponent authoring — read the mockup-sandbox skill
Section label shape conventionsExtracting existing components — read mockup-extract
focusCanvasShapes as a presentation closeGraduating mockups to production — read mockup-graduate

Coordinate system

  • Origin (0, 0) is top-left.
  • Positive x goes right, positive y goes down.
  • Artifact frames are pre-placed by Replit and cannot be resized or deleted — they can be moved.
  • Design/mockup iframe sizes are set by you and can be anything.

The two board modes

Building mode — iframes scattered wherever the last task dropped them. The canvas is a work surface, not a presentation. This is fine while building.

Presentation mode — iframes in deliberate zones with section labels, consistent gutters, and a focusCanvasShapes call at the end that pans the audience to the finished layout. Switch to this before a demo, judge review, or designathon submission.

Why this matters. A canvas with 11 frames in random positions looks unfinished even when the work is excellent. A canvas where a judge can scan Hero → Spec → Gameplay → Mobile → Storybook in one sweep communicates craft.


Layout planning — do this before touching the canvas

Before issuing any applyCanvasActions calls, write down:

  1. Zone list — What named regions will exist? (e.g. Hero row, System Spec, Gameplay Direction, Mobile, Storybook)
  2. Frame inventory — Which shape IDs go in which zone? What are their w and h?
  3. Gutter values — Pick two: sibling gutter (between frames in the same zone) and zone gutter (between zones). Consistent values make the layout scannable. Recommended defaults: 80 px sibling, 160 px zone.
  4. Y baseline — Where does the first non-hero row start? Typically hero_h + hero_top_margin + zone_gutter + label_h + label_gap.
  5. Coordinate table — Compute each frame's x before touching the canvas. A spreadsheet or quick arithmetic avoids the multi-round correction cycle.

Why plan first? Canvas moves are reversible, but computing coordinates in flight forces a read→compute→move→check loop that takes multiple turns. A written coordinate table turns this into a single applyCanvasActions batch.


Hero row convention

The hero row is the top strip of the board. Use it for the artifact frames that represent the primary deliverables — the live game, the pitch deck, the showcase video.

y = 100  (leave room for a section label above at y = 20)
x positions = 0, (w1 + sibling_gutter), (w1 + sibling_gutter + w2 + sibling_gutter), ...

Section label for the hero row (create before the frames):

{
  "type": "create",
  "shapeId": "label-hero",
  "shape": {
    "type": "text",
    "x": 0, "y": 20, "w": <total_hero_width>, "h": 60,
    "text": "SYSTEM ARTIFACTS — live game · portfolio deck · cinematic video",
    "color": "grey"
  }
}

Section label convention

Every zone gets a text shape label placed directly above the zone's frames. Consistent sizing across all labels makes the board scannable.

PropertyValue
type"text"
color"grey"
fill"none" (default)
h60 canvas units
Gap between label bottom and frame top40 canvas units
yframes_y_baseline - 40 - 60
wSpan of all frames in the zone (last frame's right edge minus first frame's x)

Label text pattern: "01 — ZONE NAME" — numbered zones in reading order so judges can orient themselves.


iframe lifecycle: building → live

This is the most important audience UX rule. Never leave iframes in "building" state when presenting.

StateWhen to useAudience sees
"building"Frame placeholder created but component/server not readyAnimated building indicator — reassures user work is in progress
"modifying"Frame exists and live, but you are actively editing its componentModifying indicator — prevents flickering
"live"Component is rendered and URL resolvesThe actual component

For a presentation board: all frames must be "live" before calling focusCanvasShapes. A mix of building and live states signals an incomplete build.

To flip a building placeholder to live:

await applyCanvasActions({ actions: [
  {
    type: "update",
    shapeId: "my-frame",
    updates: {
      shapeType: "iframe",
      state: "live",
      url: "https://<domain>/__mockup/preview/folder/Component"
    }
  }
] });

Reading state before placing

Call getCanvasState with a wide focusArea before computing coordinates for a reorganisation:

const state = await getCanvasState({
  focusArea: { x: -5000, y: -5000, w: 20000, h: 20000 }
});
console.log(JSON.stringify(state.focusedShapes.map(s => ({
  id: s.shapeId, type: s.shapeType, x: s.x, y: s.y, w: s.w, h: s.h
})), null, 2));

Cross-reference the returned IDs against your coordinate table. Abort and investigate if an expected shape ID is missing before issuing any move commands.

When do you NOT need to read first?

  • Placing brand-new frames on an empty canvas (create-auto handles placement automatically)
  • Placing new frames in a region you know is empty

Moving frames: artifact vs. design

Frame typeCan move?Can resize?Can delete?
Artifact frame (artifact:v3:artifacts/<slug>)✅ Yes❌ No❌ No
Design/mockup iframe✅ Yes✅ Yes✅ Yes
Text/geo label shape✅ Yes✅ Yes✅ Yes

Move an artifact frame:

{ "type": "move", "shapeId": "artifact:v3:artifacts/chai-chasers", "x": 2000, "y": 100 }

Mockup-sandbox URL pattern

Design/mockup iframes served by the mockup-sandbox use path-based routing — no port number:

https://${REPLIT_DOMAINS}/__mockup/preview/{folder}/{ComponentName}

Get REPLIT_DOMAINS at runtime:

echo $REPLIT_DOMAINS

Use the full https:// URL in the url field.


focusCanvasShapes — the presentation close

Always call this as the last action of a canvas layout session. It pans the user's (or judge's) viewport to show the finished layout.

await focusCanvasShapes({
  shapeIds: [
    "label-hero", "artifact:v3:artifacts/chai-chasers-video",
    "artifact:v3:artifacts/chai-chasers",
    "label-zone-1", "design-system", "progress-feedback",
    // ... all frame and label IDs
  ],
  animateMs: 500
});

Why 500 ms? A short animated pan feels polished. Instant jumps feel like a glitch. 500 ms is the sweet spot.


Complete layout workflow

  1. Inventory frames — getCanvasState with a wide focus area; capture all shape IDs, positions, and sizes.
  2. Plan the layout — write the coordinate table (zone list, gutter values, x/y for every frame and label).
  3. Delete orphaned labels — remove any text shapes that no longer label a frame (find them by ID from the inventory).
  4. Create new labels — one text shape per zone, placed above the Y baseline.
  5. Move frames — one move action per frame, batched in a single applyCanvasActions call.
  6. Verify — getCanvasState again to confirm positions, or focusCanvasShapes to visually inspect.
  7. Flip any building iframes — update each to "live" with its resolved URL.
  8. Focus the viewport — focusCanvasShapes with all frame and label IDs, animateMs: 500.

Common mistakes

MistakeWhy it hurtsFix
Computing coordinates during the move loopMulti-turn correction cyclePlan the full coordinate table first
Forgetting to read state before reorganisingMove commands target wrong IDsgetCanvasState with wide focusArea first
Leaving frames in "building" when presentingSignals incomplete workFlip all to "live" before focusCanvasShapes
Trying to resize or delete an artifact frameSilent failure or errorArtifact frames can only be moved
Using the main app dev URL in a mockup iframeShows entire app, not the componentUse /__mockup/preview/{folder}/{ComponentName}
Calling focusCanvasShapes mid-buildDisrupts the build flowCall it only at the very end

About

Built from retrospective analysis of the Glee-fully Chai Chasers Designathon project at overkillhill.com. By Jamie Hill · OverKill Hill P³ · github.com/OKHP3 MIT License — free to use, fork, and adapt. A nod to the source is appreciated.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.