agentleFS
yhassyyhassy/wireframe-skill/SKILL.md

wireframe

Skill17 starsChanged 41 days agoMITView on GitHub

Generate JSON wireframe with HTML preview

15 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use make-tweakable.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • bluzirSkill

    make-tweakable

    Add an in-artifact floating Tweaks panel that lets the user adjust colors, fonts, spacing, layout variants live in the preview. Persists via claude-pipe pattern (pending.yaml + apply-tweaks skill).

    Also in 3 projects that use this

The file

We split this skill into the rules it gives an agent

11 rules. 0 are common, 7 are distinctive, and 4 are very specific to this project.

  • 0

    Common

    Most of the 12 edited versions we read keep these.

  • 7

    Distinctive

    This author's own choices. Worth a look.

  • 4

    Very specific

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

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

    If a design-id argument is provided:

    line 39
  2. Distinctive:

    Use the conversation context to understand the desired layout

    line 45
  3. Distinctive:

    Ask clarifying questions if the layout description is ambiguous

    line 46
  4. Distinctive:

    Follow the perception sequence (Phases 1–7) to reason about the layout before producing JSON

    line 51
  5. Very specific:

    Every node MUST have a name

    line 56
  6. Distinctive:

    Ask the user where to save the JSON: "Where should I save the wireframe JSON?

    line 70
  7. Very specific:

    Use AskUserQuestion with a simple text prompt

    line 71
  8. Distinctive:

    Create the directory if it doesn't exist

    line 72
  9. Very specific:

    Write the JSON to {output_dir}/{name}.wireframe.json with the Write tool.

    line 76
  10. Distinctive:

    Use a Bash command to splice the JSON into the template.

    line 80
  11. Distinctive:

    Do NOT: read the template with the Read tool or write the HTML with the Write tool.

    line 92

“Common” is measured: kept by at least 6 in 10 of the 12 edited versions of this file we could read. “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

/wireframe

Generate a JSON wireframe definition and render it as a self-contained HTML preview.

Input

Two modes:

  1. Conversation: Describe the layout you want to wireframe. Claude generates JSON from the description.
  2. design-id argument: /wireframe {design-id} — reads designs/{design-id}/output/design-spec.md and extracts layout structure from the Information Architecture section.

Output

Two files per screen:

  • {name}.wireframe.json — Machine-readable wireframe definition
  • {name}.wireframe.html — self-contained HTML preview (open in browser)

HTML preview features:

  • Collapsible right panel showing live JSON (syncs on every edit)
  • Drag-and-drop reordering within the same parent
  • Save button (Chrome / Edge — uses File System Access API, first save opens picker, subsequent saves write directly)
  • Copy and Download buttons (all browsers)
  • Panel collapse state persists across sessions via localStorage

Output path:

  • With design-id: designs/{design-id}/output/wireframe/ (automatic)
  • Without design-id: prompted — ask user for directory path

Execution Steps

Step 1: Determine input

If a design-id argument is provided:

  1. Read designs/{design-id}/output/design-spec.md
  2. Extract layout structure from the Information Architecture section
  3. Identify all views/screens described

If no argument:

  1. Use the conversation context to understand the desired layout
  2. Ask clarifying questions if the layout description is ambiguous

Step 2: Load cognitive model and generate wireframe JSON

  1. Load the wireframe designer cognitive model from wireframe-designer.md in this skill's directory
  2. Follow the perception sequence (Phases 1–7) to reason about the layout before producing JSON
  3. Produce a JSON object following the schema below

Schema rules (mechanical — these constrain the JSON format, not design judgment):

  • Every node MUST have a name
  • Layout containers MUST have direction and children
  • Leaf elements SHOULD have a type
  • The JSON maps 1:1 to CSS flexbox — think in flex terms
  • Apply the sizing constraints from the Element types table. In particular: button, link, and text elements must never have fixed width — use height only and let content determine width. input elements use height plus grow or maxWidth, never a fixed width alone

Step 3: Determine output location

Derive {name} (the filename stem) from the JSON name field: English words, lowercase, joined by hyphens. Translate a non-English name into English first.

If design-id was provided:

  • Output directory is designs/{design-id}/output/wireframe/ (no prompt needed)

If no design-id:

  • Ask the user where to save the JSON: "Where should I save the wireframe JSON? Provide a directory path."
  • Use AskUserQuestion with a simple text prompt
  • Create the directory if it doesn't exist

Both .wireframe.json and .wireframe.html go in the same output directory, referred to below as {output_dir}.

Write the JSON to {output_dir}/{name}.wireframe.json with the Write tool.

Step 4: Generate HTML preview

Use a Bash command to splice the JSON into the template. This avoids outputting the ~1300-line template through the Write tool (which is slow because every line becomes output tokens):

python3 -c "
t = open('{skill_dir}/wireframe-template.html').read()
d = open('{output_dir}/{name}.wireframe.json').read()
open('{output_dir}/{name}.wireframe.html', 'w').write(t.replace('const WIREFRAME_DATA = null;', 'const WIREFRAME_DATA = ' + d + ';'))
"

Replace {skill_dir} with the absolute path of the directory that contains this SKILL.md, and {output_dir} and {name} with the values from Step 3. Use absolute paths.

Do NOT read the template with the Read tool or write the HTML with the Write tool. The Python script handles both file operations directly on disk.

Step 5: Output

  1. Open the HTML preview in the browser: open {output_dir}/{name}.wireframe.html
  2. Confirm to the user:
    Wireframe generated:
    - JSON: {output_dir}/{name}.wireframe.json
    - Preview: {output_dir}/{name}.wireframe.html (opened in browser)

JSON Wireframe Schema

{
  "name": "Screen Name",
  "viewport": { "width": 1280, "height": 800 },
  "root": {
    "name": "Root",
    "direction": "vertical",
    "children": []
  }
}

Top-level fields

FieldTypeRequiredDescription
namestringYesScreen/wireframe name
viewport{ width, height }YesCanvas dimensions in px
rootnodeYesRoot layout node

Node fields

Identity:

FieldTypeRequiredDescription
namestringYesNode label (shown in wireframe)
typestringNoElement type for placeholder rendering
variantstringNoText hierarchy: "display" (32px), "heading" (24px), "caption" (12px). Default body (16px). Only for type: "text".

Layout (for containers with children):

FieldTypeDefaultCSS equivalent
direction"vertical" / "horizontal""vertical"flex-direction
childrennode[]—child elements
gapnumber0gap (px)
paddingnumber or [v, h]0padding (px)
justifystring"flex-start"justify-content
alignstring"stretch"align-items
wrapbooleanfalseflex-wrap: wrap

Sizing:

FieldTypeDefaultCSS equivalent
widthnumber—width (px)
heightnumber—height (px)
growbooleanfalseflex: 1
maxWidthnumber—max-width (px)

Element types

TypeRendered asUse forSizing
"text"Gray text labelLabels, headings, body textheight only. No width — text reflows naturally
"image"Gray box with image iconPhotos, thumbnails, hero imageswidth + height, or height + grow
"icon"Small gray circleAction icons, status indicatorsFixed width + height always
"button"Rounded rectangleCTAs, primary actionsheight only. Never width — label length varies
"link"Underlined textNavigation items, secondary actions, text linksheight only. Never width — label length varies
"input"Bordered rectangleSearch fields, form inputs, dropdownsheight + grow or maxWidth. Never fixed width alone
"card"Bordered box with light gray fillContent cards, list itemsheight + grow, or height alone in vertical lists
"table"Header row + placeholder data rowsData tables, lists with columnsgrow or omit. Column widths via columns[].width / columns[].grow
"divider"Thin horizontal lineSection separatorsNo sizing needed
(none)Transparent containerStructural grouping onlygrow for flexible, width for fixed (e.g., sidebar)

Table properties

Tables use columns and rows instead of children:

FieldTypeDefaultDescription
columnsarray—Column definitions (required for table)
columns[].namestring—Column header text
columns[].growbooleantrue if width is unsetFlexible width (flex: 1). A column without width grows even when grow is omitted
columns[].widthnumber—Fixed width in px
rowsnumber3Number of placeholder data rows
{
  "name": "Users Table",
  "type": "table",
  "columns": [
    { "name": "Name", "grow": true },
    { "name": "Email", "grow": true },
    { "name": "Role", "width": 120 },
    { "name": "Status", "width": 100 }
  ],
  "rows": 5
}

Style properties (optional)

Visual properties for downstream consumers. These are purely additive — a wireframe JSON with zero style properties is 100% valid and renders as a monochrome wireframe (current behavior, unchanged). The wireframe HTML renderer ignores style properties.

The /wireframe skill itself produces plain wireframes. Style properties are added by /ui-prompts when a design system is specified, creating a "styled wireframe" that downstream consumers (/pencil-generate, /stitch-generate, Figma Make) use directly.

FieldTypeDescriptionApplies to
fillstring (hex)Background fill colorContainers, cards, buttons
colorstring (hex)Text/icon foreground colorText, icons, links
fontSizenumberFont size in pxText
fontWeightnumberFont weight (400, 600)Text
borderRadiusnumberCorner radius in pxContainers, cards, buttons, inputs
stroke{ color, width }Border definitionContainers, cards, inputs
shadow{ x, y, blur, color }Drop shadowContainers, cards
opacitynumber (0–1)Element opacityAny node

Rules:

  • Values MUST be resolved (hex colors, px numbers) — never token names
  • Absence means "use consumer defaults" — omit properties you don't need to specify
  • fill on a container = background; color on text = foreground (avoid ambiguity)
  • stroke and shadow use object notation for clean parsing

Annotation fields:

FieldTypeDescription
_solvesstringTraces this element to a PRD problem or user need. Metadata only — ignored by all renderers.

Canonical schema: This JSON schema is the canonical layout format used across the pipeline. The ## Layout section in UI prompt files (prompts/*.md) uses this same schema inline, optionally with style properties. Skills that generate prompts (/ui-prompts, /style-exploration, /figma-variation) produce wireframe JSON. Skills that consume prompts (/pencil-generate, /stitch-generate) parse it directly.


Example

A dashboard with proper typographic hierarchy, spacing rhythm, and proportional heights:

{
  "name": "Dashboard",
  "viewport": { "width": 1280, "height": 800 },
  "root": {
    "name": "Page",
    "direction": "vertical",
    "children": [
      {
        "name": "Header",
        "direction": "horizontal",
        "height": 56,
        "padding": [0, 24],
        "justify": "space-between",
        "align": "center",
        "children": [
          { "name": "Logo", "type": "image", "width": 100, "height": 28 },
          { "name": "Search", "type": "input", "grow": true, "maxWidth": 400, "height": 40 },
          { "name": "Avatar", "type": "icon", "width": 32, "height": 32 }
        ]
      },
      {
        "name": "Body",
        "direction": "horizontal",
        "grow": true,
        "children": [
          {
            "name": "Sidebar",
            "width": 240,
            "direction": "vertical",
            "padding": 16,
            "gap": 4,
            "children": [
              { "name": "Overview", "type": "link", "height": 40 },
              { "name": "Projects", "type": "link", "height": 40 },
              { "name": "Settings", "type": "link", "height": 40 }
            ]
          },
          {
            "name": "Main",
            "grow": true,
            "direction": "vertical",
            "padding": 32,
            "gap": 24,
            "children": [
              { "name": "Dashboard", "type": "text", "variant": "display", "height": 48 },
              {
                "name": "Stats Row",
                "direction": "horizontal",
                "gap": 16,
                "children": [
                  { "name": "Total Users", "type": "card", "grow": true, "height": 100 },
                  { "name": "Revenue", "type": "card", "grow": true, "height": 100 },
                  { "name": "Active Today", "type": "card", "grow": true, "height": 100 }
                ]
              },
              {
                "name": "Recent Activity",
                "direction": "vertical",
                "gap": 12,
                "children": [
                  { "name": "Recent Activity", "type": "text", "variant": "heading", "height": 36 },
                  {
                    "name": "Activity Table",
                    "type": "table",
                    "columns": [
                      { "name": "User", "grow": true },
                      { "name": "Action", "grow": true },
                      { "name": "Status", "width": 120 },
                      { "name": "Time", "width": 140 }
                    ],
                    "rows": 6
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  }
}

Cognitive reasoning behind this wireframe:

  • Phase 3 (Task & Scanning Pattern): Dashboard = monitoring intent → F-pattern → top-to-bottom primary content flow, important information along left edge and top
  • Phase 4 (Grid Establishment): Two major zones — sidebar (240px, fixed, persistent navigation) + content area (grow: true). Sidebar exists because content inventory includes navigation that aids the monitoring task.
  • Phase 5 (Hierarchy Assignment): Three levels — display for page identity ("Dashboard"), heading for section identity ("Recent Activity"), body (default) for data content. Caption reserved for table column headers (chrome, not content). Sidebar nav uses link (navigation aids the task but isn't the task itself). Primary CTAs in the content area would use button.
  • Phase 6 (Spacing Logic): Proximity tightens inward — Main padding 32 > section gap 24 > card gap 16 > internal gap 12. Each step inward signals increasing relatedness. Padded containers keep padding ≥ child gap (Main 32 ≥ 24, Sidebar 16 ≥ 4). Unpadded groups (Stats Row, Recent Activity) use a gap smaller than Main's gap of 24, so their children stay aligned with the page title.
  • Phase 7 (Rhythm Verification): Progressive density — spacious at top (title, 48px display text), medium in middle (stat cards, 100px), dense at bottom (table with 6 data rows). Heights accommodate content proportionally.

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.