Kirby: A Comprehensive Sketch Plugin System for Design Resource Management and Development

Yin Zhengbo, a front‑end engineer at Ctrip Ticket's R&D department, focuses on improving design experience and delivery through systematic tools.

Sketch has become a popular UI design tool, especially after the introduction of Symbols in version 3, and continues to grow its plugin ecosystem.

With the rise of Design Systems, many large companies (e.g., Google, Airbnb) and startups (e.g., Abstract, UXPIN) invest in design plugins; Chinese internet firms also develop their own tools such as Dapllo, Kitchen, Fusion, and Anto.

In 2016, Ctrip's UED team fully switched to Sketch, and the front‑end team recognized the need for automated design system workflows, leading to the creation of the Kirby plugin to codify design language and streamline resource management.

1. Design Resource Management – A design language includes brand assets, colors, typography, icons, animation, and copy, while a Design System provides documentation, resources, component code, and tooling to enforce it.

Sketch’s Symbols and Library features address component sharing, but issues remain in color, typography, and icon management, prompting custom plugin development.

2. Kirby – Sketch Plugin – Kirby originated from a Sketch version upgrade that broke the Sketch Measure plugin’s annotation export. To keep designers on the latest Sketch version and fix the defect, Kirby was built and subsequently expanded to include design tokens, an icon system, components, and templates.

Key features of Kirby include:

2.1 Design Language Constraints

Color Palette

Typography

Shadow

2.2 Static Scan Checks

Provides designers with quick issue detection.

Font and icon system, online template library, and more visual resources are also included.

3. Sketch Plugin Development Technology

The development process involved cross‑domain technical challenges and multiple refactorings.

3.1 Fundamentals

Sketch plugins are folders containing one or more scripts written in JavaScript (ES6) that run in a hybrid SketchAPI environment, not in a browser or Node.js.

Example to run a simple script:

const sketch = require('sketch')
sketch.UI.message('Hello, world!')

This displays a toast message in the Sketch UI.

3.2 API Overview

The plugin system grants full access to Sketch internals, enabling powerful extensions but requiring vigilance for version compatibility.

3.3 Actions API

Used to listen to user actions such as OpenDocument. Example manifest entry:

"commands" : [
  {
    "script" : "my-action-listener.js",
    "name" : "My Action Listener",
    "handlers" : {
      "actions" : {
        "OpenDocument" : "onOpenDocument"
      }
    },
    "identifier" : "my-action-listener-identifier"
  }
]

Handler implementation:

export function onOpenDocument(context) {
  context.actionContext.document.showMessage('Document Opened')
}

Actions can have begin/finished states; wildcards are possible but costly.

defaults write com.bohemiancoding.sketch3 actionWildcardsAllowed -bool YES

Wildcard handler configuration:

{
  "handlers": {
    "actions": {
      "*": "onActionHandler"
    }
  }
}

3.4 Javascript API

Wraps native Sketch APIs; coverage aims for 90%.

https://developer.sketch.com/reference/api/

3.5 Development Environment

skpm, a webpack‑based packaging tool, simplifies plugin creation.

npm install -g skpm
skpm create my-plugin
cd my-plugin
npm run build
# Then run via Plugins → my-plugin → MyCommand

Typical project structure:

├── .gitignore
├── README.md
├── src               // sources
│   ├── manifest.json
│   └── my-command.js
├── node_modules
│   └── skpm
├── my-plugin.sketchplugin // compiled plugin
│   └── Contents
│       ├── Resources
│       └── Sketch
│           ├── manifest.json
│           └── my-command.js
└── package.json

3.6 Crash Protection

Sketch disables all plugins after a crash; this can be turned off:

defaults write com.bohemiancoding.sketch3 disableAutomaticSafeMode true

3.7 Plugin Cache

Cache can be toggled:

defaults write com.bohemiancoding.sketch3 AlwaysReloadScript -bool YES

For long‑running scripts, use coscript.setShouldKeepAround(false) to release.

3.8 WebView Debugging

defaults write com.bohemiancoding.sketch3 WebKitDeveloperExtras -bool true

3.9 Logging

Use macOS Console, Plugin Output.log, or skpm log -f . Console.log works with sketch-dev-tools .

3.10 Code Debugging

Safari’s Web Inspector can debug plugin JavaScript contexts.

3.11 Objective‑C Bridge

All internal Sketch methods are exposed; selectors are converted to underscore syntax.

Example opening a file dialog via AppKit:

var openPanel = NSOpenPanel.openPanel()
openPanel.setCanChooseDirectories(false)
openPanel.setCanChooseFiles(true)
openPanel.setCanCreateDirectories(false)
openPanel.setDirectoryURL(NSURL.fileURLWithPath('~/Documents/'))
openPanel.setTitle('Choose a file')
openPanel.setPrompt('Choose')
openPanel.runModal()
// Keep async operation alive
COScript.currentCOScript().shouldKeepAround = true
// Release after done
COScript.currentCOScript().shouldKeepAround = false

3.12 Native GUI

Finding the right instance and timing is key; Actions API helps with timing, while Sketch headers aid in locating UI elements.

Example retrieving the Create Symbol naming sheet:

const doc = context.actionContext.document;
const docData = doc.documentData();
const window = doc.window();
const sheetWindow = window.attachedSheet();
const createSymbolNameingSheet = sheetWindow.windowController();

3.13 WebView GUI

Bidirectional communication between WebView and plugin uses WKWebView delegates and evaluateJavaScript calls.

export function createPopoverWKHandler() {
  return new MochaJSDelegate({
    'userContentController:didReceiveScriptMessage:' : (function (controller, message) {
      let body = Utils.toJSON(message.body()),
          { key, value } = body;
      switch (key) {
        case 'setTypography':
          Utils.setTextStyle(value);
          break;
      }
    })
  })
}

4. Milestone One

A fully functional Sketch plugin must also consider version management, compatibility, user configuration, cloud sync, and enterprise authentication.

Kirby’s incremental features aim to ensure consistency from design through development to delivery, embodying a complete DesignOps workflow.