User Guide

Getting Started

What is JustDraw

A browser-based icon design tool with a built-in publishing pipeline. Draw icons with precision vector tools, press Cmd+S, and they publish to CDN as optimized SVGs and Android VectorDrawables. No export dialogs. No manual deploy.

Signing in

Click Sign in with GitHub on the landing page. JustDraw uses GitHub OAuth — your icons save to a GitHub repository you choose. No account to create beyond GitHub.

Creating an icon set

After signing in, you land on the Home view showing your GitHub repos. Click a repo to open it, or create a new one. Each repo is one icon set.

Editor overview

The editor has three views:

• Home: your icon sets (GitHub repos)
• Grid: browse all icons in the current set — search, filter, reorder
• Edit: the drawing canvas for a single icon

In Edit mode, the screen layout is:

• Canvas in the center — your drawing surface
• Toolbar on the left — tool selection
• Sidebar on the right — properties, layers, tags, diagnostics
• Status bar at the bottom — zoom, icon name, quality indicator

Drawing

Pen tool

Press P to activate the pen tool.

Drawing straight lines: Click to place points. Each click adds a corner. Click the starting point to close the shape.

Drawing curves: Click and drag to create a bezier curve. The drag direction and distance control the curve shape. Release the mouse to set the curve, then click the next point.

Ending an open path: Press Escape or double-click to finish without closing.

Repositioning the last point: Hold Spacebar while placing a point to reposition it before committing.

Tip: Hold Shift to constrain angles to 45-degree increments.

Shape tools

• Rectangle (R): click and drag to draw. Corner radius adjustable in the sidebar after drawing.
• Ellipse (O): click and drag. Hold Shift to constrain to a circle.
• Polygon (Y): click and drag. Set the number of sides in the sidebar.
• Star (U): click and drag. Set sides and inner radius in the sidebar.

Line tool

Press L. Click to place the start point, click again for the end point. Creates an open path with two nodes.

Selection

Select tool (V): click a shape to select it. Click empty canvas to deselect.

• Shift+click: add/remove from selection
• Marquee: click and drag on empty canvas to select shapes within the rectangle
• Lasso: the marquee also supports crossing-segment selection — shapes partially inside are included
• Cmd+A: select all shapes
• Escape: deselect all

Transform

With shapes selected:

• Drag to move. Hold Shift to constrain to horizontal/vertical.
• Scale handles appear at corners and edges of the selection box. Drag to resize. Hold Shift for proportional scaling. Hold Alt to scale from center.
• Rotate with the rotate tool (E) or by hovering outside a corner handle.
• Flip: Shift+H (horizontal), Shift+V (vertical). Add Alt to flip around artboard center instead of selection center.
• Nudge: arrow keys move by one grid step. Shift+Arrow moves by 4x. Alt+Arrow moves by 1/4x.

Groups

Select multiple shapes and press Cmd+G to group them. Groups move and transform as a unit.

Press Cmd+Shift+G to ungroup.

Press Enter on a selected group to enter group isolation — edit children directly. Press Escape to exit.

Snap and guides

• Grid snap is on by default. Press G to toggle. Hold Alt during a drag to temporarily disable.
• Alignment guides appear automatically — cyan lines snap to edges and centers of other shapes.
• Custom guides: drag from the ruler edges to create guides. Cmd+; toggles guide visibility. Right-click a guide to lock, delete, or clear all.

Editing Paths

Entering isolation mode

Double-click a shape to edit its individual nodes. The rest of the canvas dims. Press Escape to exit isolation.

Alternatively, press A to switch to the Point Select tool and edit nodes across multiple selected shapes without full isolation.

Nodes and handles

• Square nodes: corners — handles move independently
• Round nodes: smooth — handles are co-linear (moving one adjusts the other)
• Hollow circles: off-curve control points (bezier handles)

Select a node and press Enter to toggle between smooth and corner.

Drag a handle to adjust the curve. Hold Alt while dragging to break handle symmetry on a smooth node.

Scissors

Press K to activate the scissors tool. Click on any path segment to split it at that point. A closed path becomes open. An open path splits into two separate paths.

Adding and removing nodes

Adding a node: in point select mode, hold Alt and click on a path segment to insert a point.

Deleting a node: select it and press Backspace/Delete. The curve re-fits automatically.

Deleting a segment: select two adjacent nodes and press Shift+X.

Boolean operations

Select two or more shapes. Right-click and choose from the context menu, or use the toolbar:

• Union: combine into one shape
• Subtract: cut the front shape from the back
• Intersect: keep only the overlap
• Exclude: keep everything except the overlap

Curve assist

Select nodes and use these shortcuts for curve quality:

Curvature comb

Toggle in Settings. Shows a Speed Punk-style overlay — green for low curvature, red for high. Helps spot kinks and inconsistencies.

Measurement

Press M to toggle stem measurement. Hover over any path to see the perpendicular thickness readout — a dashed gold line shows the measurement with a label.

Visual Properties

Fill

Select a shape. The fill color shows in the sidebar. Click the color swatch to change it. Press F to toggle fill on/off.

On export, fills become currentColor for monochrome icons, or preserve per-path colors for multi-color icons.

Stroke

Select a shape. Toggle stroke with S. Adjust weight, cap (butt/round/square), and join (miter/round/bevel) in the sidebar.

Opacity

Set per-path opacity in the sidebar (or press 1–9 for 10–90%, 0 for 100%).

Groups with opacity less than 100% composite as a unit — children blend with each other first, then the group blends with the canvas.

Semantic tokens

Named aliases that map abstract roles to specific icons (e.g., action.delete → trash). Manage in the sidebar's Tokens section. Tokens export through the pipeline — they appear in npm metadata, design system docs, and are resolvable via MCP.

Organizing Icons

Grid view

Press Cmd+W from the editor to return to grid view (or click the back chevron in the toolbar).

Grid view shows all icons in the current set as thumbnails. Features:

• Search: type to filter by name or tag
• Category chips: click to filter by category
• Drag reorder: drag icons to rearrange their order
• Bulk select: click one, Shift+click another to select a range
• Status filter: filter by draft/review/production

Naming

Click an icon's name in the sidebar to edit it. A green check means the name matches a known concept in the taxonomy. An amber question mark means it's unknown — suggestions appear below.

Tags and categories

Tags and categories appear in the sidebar when an icon is selected.

Tags: click the + button to add. Ghost chips suggest tags from the taxonomy with cross-set frequency badges (e.g., "×6" means 6 of 7 reference sets use this tag).

Categories: auto-derived from the taxonomy. Shows frequency (e.g., "Communication (6/7)").

Icon status

Each icon has a status: draft, review, production, or deprecated. Click the status button in the sidebar or grid to change it. Status affects export — the pipeline can filter by status.

Diagnostics

A colored dot on each icon thumbnail indicates quality:

• Green: no issues
• Yellow: warnings (near-vertical/horizontal segments, fractional coordinates)
• Red: errors (kinks, zero-area paths, duplicate nodes)

Click the dot or open the diagnostics section in the sidebar to see details. Click any issue to select the relevant node or path.

Coverage dashboard

The sidebar shows a coverage panel with per-category progress bars. This tells you how complete your set is relative to the taxonomy — how many of the expected icons in each category you've drawn.

Saving and Publishing

Save to GitHub

Press Cmd+S. Your icons save to the GitHub repository you selected on sign-in.

What happens on save:

1. Each icon serializes to an SVG file + a .meta.json file (tags, status, category)
2. Files commit to the repo's icons/ directory via GitHub's GraphQL API
3. On first save, JustDraw auto-installs a GitHub Actions workflow into the repo

Tip: Cmd+Shift+S creates a named checkpoint you can reference later.

Save to file

If you're not signed in to GitHub, Cmd+S downloads a .justdraw file — a JSON bundle of the entire set.

The export pipeline

After you save to GitHub, the automated pipeline runs:

1. Validate — checks naming, paths, metadata, complexity
2. Export — optimizes SVGs, generates Android VectorDrawable XML
3. Build pages — generates a searchable browse page and changelog
4. Deploy — publishes to GitHub Pages CDN

Your icons are live at {username}.github.io/{repo}/svg/{icon-name}.svg.

The pipeline also generates npm packages, framework components, Iconify JSON, and documentation files. See Packages for details.

Conflicts

If someone else pushes to the same repo while you have unsaved changes, JustDraw detects the conflict on your next save. A conflict modal appears showing which icons diverged. You can resolve per icon — keep yours, keep theirs, or merge.

Multiple tabs

Open the same set in two browser tabs — edits sync via BroadcastChannel. JustDraw also polls the GitHub HEAD to detect remote changes from other devices.

Reverting

Right-click an icon with unsaved changes in grid view → Revert to Last Saved. Or use Discard All Changes in the set menu to reload everything from GitHub.

Import

SVG files

Drag SVG files onto the grid view, or use the Import button. JustDraw handles:

• Single SVGs or batch folders
• SVG sprites with <symbol> elements
• Full CSS cascade and attribute inheritance
• Group hierarchy and clip-path
• Coordinate transform and viewBox normalization

GlyphsApp files

Drag a .glyphs file onto the grid. Y-axis flips automatically (font tools use Y-up, JustDraw uses Y-down).

Font files

Drag .otf, .ttf, or .woff files. Glyphs convert from quadratic/cubic bezier format to JustDraw's node format.

Smart import features

• Corner detection: arc patterns auto-unbake into corner-radius nodes
• Naming enrichment: imported icons get alias-aware semantic linting
• Single-color pattern resolution: multi-path SVGs that are effectively one color simplify to solid fill

Reference Ghost

Press Shift+G to toggle. Overlays an icon from a reference set (Lucide, Phosphor, Tabler, Bootstrap, Feather, or Material) as a blue-tinted ghost behind your drawing. Useful for comparing proportions and weight.

Change the reference set in the sidebar dropdown. The ghost auto-loads the matching icon name from the selected set.

Keyboard Shortcuts

Tools

File

Selection

Edit

Transform

Path

Curve Assist

Visual

View

Navigation

Settings

Press Cmd+, in grid view to open Settings.

Grid: artboard size, overshoot, grid unit, snap increment, nudge step.

Drawing: default stroke weight, paste offset, inactive path opacity.

Canvas: zoom min/max, node hit radius.

Behavior: undo depth.

Export: coordinate precision.

Each section has a Reset to defaults button.