Skip to content
Sketch Import Loop
AutoXXS (320px)XS (375px)SM (640px)MD (768px)LG (1024px)XL (1280px)XXL (1536px)
SketchMaterialiOSTamagui
DataInjectionKeyPatternsServiceTransactionProcessResearchProductQualityPerformanceSpecDomainFunctionTechnologyArchitectureConfigMiddlewareDataDatabaseDrizzleMigrationModelop-sqliteSchemaSQLState ManagementDraftKeystoneMergePatchPatchesPersistenceReactiveRedoStoreUndoTestingDeviceFactoryIsolationTypeScriptZodTopicsCommunicationBidsNVCDesignDesign ImplicationsEducationPedagogyFoundationsPsychologyAttachmentFloodingRelatingAuthentic RelatingUIEditorReact Native

Sketch Import Loop

Workflow Sketch Import Loop
agent stardesign
tags
workflowuidslsketch
context
agents/conventions/naming-standards

Converts hand-drawn or schematic sketches into DSL surface documents using multimodal vision. One image → one surface draft → user confirmation → write.

Trigger

import sketches <folder>

Steps

  1. Discover images. Glob <folder> for *.png, *.jpg, *.jpeg, *.webp, *.gif. Sort alphabetically. Report the list to the user before processing.

  2. For each image, run the Sketch → Draft cycle:

    a. Read the image using your file-reading tool (multimodal vision).

    b. Analyse the sketch. Identify:

    • The overall screen purpose (what task does this surface support?).
    • Structural regions: navigation bars, headers, content areas, footers, sidebars.
    • UI elements within each region: buttons, inputs, selects, labels, lists, tables, cards, icons, badges, modals, tabs, accordions, steppers.
    • All visible text content — headings, body copy, button labels, placeholder text, captions. Treat every legible string as authoritative copy; transcribe it exactly.
    • Any annotations or labels written on the sketch — treat these as authoritative names for elements and surfaces.
    • The reading order / visual hierarchy (top-to-bottom, left-to-right unless the sketch indicates otherwise).
    • Relative sizing and spacing — note which elements are large vs. small, which gaps appear wider or narrower, and any visible padding within containers.

    c. Map elements to DSL components using the vocabulary in the DSL Quick Reference. Prefer the most semantically precise component. If an element is ambiguous, use placeholder(type="..." label="...") and note the ambiguity.

    d. Infer a surface id and title from the filename (strip extension, kebab-case) or from labels on the sketch. If no clear name is derivable, prompt the user for one before continuing.

    e. Draft the Pug DSL block. Apply all UI Design Principles: label every interactive element, respect layout hierarchy, use id attributes on elements that will be clickable. Reflect layout fidelity using DSL size/spacing attributes (gap, size, width, height, padding) to match the proportions observed in the sketch — prefer named scale tokens (sm, md, lg, xl) over raw values.

    f. Ask about colours before showing the draft. If the sketch uses colour (backgrounds, text colour, border colour, badges), ask the user which colour tokens or theme values to apply. If the sketch is monochrome (pencil/ink), note this and skip the colour question.

    g. Show the draft to the user:

    • Display the inferred surface id, title, and the complete Pug DSL block.
    • List any ambiguities or assumptions made during analysis.
    • Ask: “Does this match the sketch? Any corrections before I move to the next image?”

    h. Incorporate feedback. Apply corrections inline. If the user says “skip”, mark the surface TODO and move on. If the user says “write”, write the file immediately and continue to the next image. Otherwise wait for explicit approval or write.

  3. After all images are processed, report a summary: how many surfaces were drafted, how many written, how many skipped.

Naming the output file

  • File: content/surfaces/<surface-id>.ui.mdoc
  • The surface id must be kebab-case with no prefix (e.g. login-screen).
  • The qualified id is surface/<surface-id>.
  • Set status: draft in frontmatter.
  • Leave for as TODO if no linked feature is known — flag it clearly in the summary.

Do’s and Don’ts

Do:

  • Wait for user approval before writing each drafted surface to disk
  • Confirm each surface separately — process one at a time
  • Treat multiple clearly separate screens in a single sketch as individual surfaces
  • Apply the .not-content and align-items: flex-end rules to any chrome elements identified in the sketch
  • Ask about colours before showing the draft when the sketch uses colour

Don’t:

  • Write any file until the user approves the draft for that image
  • Batch-write all surfaces at once
  • Skip the colour question for sketches that use colour (backgrounds, text colour, border colour, badges)
  • Invent a surface id without checking the filename or sketch labels first

Definition of Done

  • All images in folder processed or explicitly skipped
  • Each drafted surface confirmed by user before writing
  • Summary report output with counts of drafted, written, and skipped surfaces