agentleFS
OKHP3OKHP3/skillz/.agents/skills/okhp3-replit-design-pipeline/SKILL.md

okhp3-replit-design-pipeline

Skill3 starsChanged 2 months agoMITView on GitHub

The complete Replit design iteration loop as a single coherent workflow — extract → sandbox → variant → graduate. Use when redesigning, improving, or creating variants of any UI component or page. Covers the "extract first, never approximate" rule, DESIGN subagent brief anatomy, variant labelling conventions on canvas, and the graduation decision gate. Activate for "redesign", "improve this component", "show me options", "create variants", "put on canvas", "graduate this mockup", "design alternatives", or any request that implies iterating on UI — whether the component exists already or is being built from scratch.

The file

Show its rules and text

We split this skill into the rules it gives an agent

13 rules. About 0 are common, 7 are distinctive, and 6 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈7

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 6

    Very specific

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

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

    Create artifacts/mockup-sandbox/src/components/mockups/{group}/_group.css with the app's :root CSS variables and font imports — this is …

    line 88
  2. Very specific:

    Create Current.tsx in the same group folder, importing _group.css.

    line 89
  3. Very specific:

    Start the mockup-sandbox workflow: restartWorkflow({ workflowName: "artifacts/mockup-sandbox: Component Preview Server" }).

    line 100
  4. Very specific:

    Create the component in artifacts/mockup-sandbox/src/components/mockups/{group}/.

    line 101
  5. Very specific:

    Place a "building" iframe on the canvas immediately — before the component is written — so the user sees instant feedback.

    line 102
  6. Distinctive:

    Use a DESIGN subagent for variant exploration when there are 2+ variants to generate.

    line 117
  7. Very specific:

    Place a text shape label above each variant iframe — not below, not beside.

    line 139
  8. Distinctive:

    Why named variants matter: When the user says "I prefer B," they mean the design hypothesis, not the letter.

    line 145
  9. Distinctive:

    Default to ≥2 of 3 variants being net-new big swings, not incremental refinements.

    line 159
  10. Distinctive:

    Which variant exactly?: If multiple are live, confirm with the user.

    line 173
  11. Distinctive:

    Does the mockup have real data or mock data?: All mock data → real API calls during graduation.

    line 175
  12. Distinctive:

    After graduation, if the user wants further changes:

    line 194
  13. Distinctive:

    When activating this pipeline, read skills in this order — only what you need for the current phase:

    line 219

≈ “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-design-pipeline

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

Replit's design canvas exposes five interlocking skills: mockup-sandbox, mockup-extract, mockup-graduate, design-exploration, and the design (DESIGN subagent) skill. None of them explains the full loop as a decision tree. This skill does.


Scope

In scopeOut of scope
Decision tree: extract vs. build from scratchCanvas callback schemas — read the canvas skill
Full pipeline narration: extract → sandbox → variant → graduateSandbox setup and URL patterns — read mockup-sandbox
DESIGN subagent brief anatomyImport tracing during extraction — read mockup-extract
Variant labelling on canvasProduction wiring — read mockup-graduate
Graduation decision gateLaunching subagents — read the design skill

The decision tree: start here

User asks to improve / redesign / create variants / show options

          ↓
Does the component already exist in the main app codebase?
          │
   YES ───┤                         NO
          ↓                          ↓
    EXTRACT first               BUILD from scratch
    (mockup-extract)            (mockup-sandbox + DESIGN subagent)
    then iterate                    ↓
          │                  Is this a net-new component
          ↓                  the user described, or one
    Proceed to               the agent is inventing?
    VARIANT phase                   │
                              Both → Build from scratch,
                              then proceed to VARIANT phase

The golden rule: if the component exists in the codebase, extract it. Never rebuild from memory. You will get dimensions, colours, spacing, opacity values, and font sizes wrong. The real source code has the correct values.


Phase 1 — Extract (when component already exists)

Read the mockup-extract skill (read .local/skills/mockup-extract/SKILL.md) for the full process. The high-level steps are:

  1. Locate the target component file in the main app.
  2. Trace its full import chain (component → hook → context → client). Classify each dependency as inline, copy, or stub.
  3. Create artifacts/mockup-sandbox/src/components/mockups/{group}/_group.css with the app's :root CSS variables and font imports — this is what makes the extracted component look identical to the original.
  4. Create Current.tsx in the same group folder, importing _group.css.
  5. Embed it on the canvas labelled "Current" — this is your baseline.

Do not call getCanvasState and then place the baseline blind. Read state first, find empty space, then place.


Phase 2 — Sandbox (when component does not yet exist)

Read the mockup-sandbox skill (read .local/skills/mockup-sandbox/SKILL.md) for setup. The key steps:

  1. Start the mockup-sandbox workflow: restartWorkflow({ workflowName: "artifacts/mockup-sandbox: Component Preview Server" }).
  2. Create the component in artifacts/mockup-sandbox/src/components/mockups/{group}/.
  3. Place a "building" iframe on the canvas immediately — before the component is written — so the user sees instant feedback.
  4. Flip to "live" once the URL resolves.

Preview URL pattern (no port number):

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

Phase 3 — Variant exploration

When to use a DESIGN subagent

Use a DESIGN subagent for variant exploration when there are 2+ variants to generate. They run in parallel and each produces genuinely distinct output.

DESIGN subagent brief anatomy for mockup sandbox variants:

Product/brand identity: 1-2 vivid sentences — who it's for, what it feels like.
Goal: what component or page to build.
Vibe: one natural-language feeling (NOT a design style name).
Target location: the file path, shape ID, and dev server URL.
Variant hypothesis: what makes THIS variant distinct from the others (give each subagent a different brief).

What NOT to include in the brief:

  • Specific CSS values, colours, font names, pixel spacing
  • Layout prescriptions ("put the CTA on the right")
  • Section names or content order
  • Design style names ("minimalist", "material design")

Why? The DESIGN subagent is the creative director. Your job is to describe the feeling and the goal. Over-specification produces constrained, predictable output. Under-specification produces generic output. The sweet spot is vivid product identity + distinct vibe.

Variant labelling on canvas

Place a text shape label above each variant iframe — not below, not beside. Use the same label height (60 canvas units) and gap (40 canvas units) as the zone labels in the board layout.

Label naming convention:

  • "Current" — the extracted or pre-existing component
  • "A — Minimal" / "B — Editorial" / "C — Bold" — name by design hypothesis, not by letter alone

Why named variants matter. When the user says "I prefer B," they mean the design hypothesis, not the letter. A label like "B — Editorial" makes the conversation precise.

Distinct variation axes

Each variant should represent a meaningfully different answer to "how should this component work?" Choose from:

AxisExamples
StructuralList vs. grid vs. timeline; sidebar vs. top nav
Content/semanticFeature-led vs. social-proof-led vs. price-led
ConceptualDashboard-as-cockpit vs. dashboard-as-feed
BehaviouralValidate on blur vs. on submit vs. inline
AestheticMinimal vs. bold editorial vs. warm textured

Default to ≥2 of 3 variants being net-new big swings, not incremental refinements.


Phase 4 — Graduate

Trigger: the user says "use this one", "ship it", "I like B, integrate it", "graduate this", or any approval of a specific variant.

Read the mockup-graduate skill (read .local/skills/mockup-graduate/SKILL.md) for the full process.

The graduation decision gate

Before graduating, answer:

  1. Which variant exactly? If multiple are live, confirm with the user.
  2. Is the main app's component library different from shadcn/ui? If yes, every @/components/ui/* import needs translation.
  3. Does the mockup have real data or mock data? All mock data → real API calls during graduation.

GENERAL vs DESIGN subagent for graduation

  • GENERAL subagent — for graduation. Graduation is engineering: import graph, routing, state wiring, API integration. GENERAL subagents navigate codebases.
  • DESIGN subagent — never for graduation. They don't wire APIs or understand routing.

What to preserve exactly

Colours, gradients, shadows, border radius, spacing, typography (family/weight/size/line-height), layout structure, animations, hover states, and icons.

What to transform

Mock data → real API calls; no-op navigation handlers → real router links; local constants → app state; stubbed auth → real auth context.


Phase 5 — Iterate

After graduation, if the user wants further changes:

  • Small visual edits → edit the main app component directly.
  • Major redesign → extract the newly graduated component back into the sandbox, create new variants, graduate again.

This loop is the full pipeline. Each cycle produces tighter, more informed output than the last.


Common mistakes

MistakeWhy it hurtsFix
Rebuilding an existing component from scratchWrong colours, spacing, opacity — visual fidelity lostAlways extract first
Giving all DESIGN subagents the same vibeThree nearly identical variantsEach subagent gets a distinct brief
Naming variants A/B/C with no hypothesisUser confusion when approvingName by design hypothesis ("Editorial", "Minimal")
Using a DESIGN subagent for graduationThey don't wire APIs or understand routingUse a GENERAL subagent
Editing index.css instead of _group.cssTokens leak into every other mockupUse group-level CSS
Forgetting import './_group.css'Component renders with wrong tokens — no error, just wrongAlways import it
Improving the design during graduationShips something the user did not approveGraduate exactly what was approved

Skill reading order

When activating this pipeline, read skills in this order — only what you need for the current phase:

  1. This skill — pipeline decision tree and brief anatomy (always read first)
  2. .local/skills/mockup-sandbox/SKILL.md — if setting up the sandbox or creating new components
  3. .local/skills/mockup-extract/SKILL.md — if extracting an existing component
  4. .local/skills/design/SKILL.md — if launching a DESIGN subagent
  5. .local/skills/design-exploration/SKILL.md — if the user asks for divergent exploration ("what else could this be?")
  6. .local/skills/mockup-graduate/SKILL.md — when the user approves a variant
  7. .local/skills/canvas/SKILL.md — for canvas callback mechanics at any stage

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.