HKUDS/CLI-Anything Sketch File Build Process: UTF-8 Encoding Support for CJK Characters

Yes, the CLI-Anything custom Sketch file build process fully supports UTF-8 encoding for Chinese, Japanese, and Korean (CJK) characters by bypassing the default serializer and explicitly writing JSON components as UTF-8 buffers.

The HKUDS/CLI-Anything repository provides a specialized Sketch harness that solves a critical encoding problem in the standard sketch-constructor library. When generating .sketch files programmatically, the build process deliberately avoids the default JsonStreamStringify serializer—which corrupts multi-byte characters—and instead implements a custom UTF-8 buffer approach that preserves CJK text integrity.

How UTF-8 Encoding Is Implemented in buildSketchFile

The core encoding logic resides in sketch/agent-harness/src/builder.js. The function buildSketchFile contains an explicit comment documenting the problem and the custom solution:

"bypass sketch-constructor's JsonStreamStringify (corrupts CJK)"

This comment appears at lines 20-27 of builder.js, where the function prepares to serialize each JSON component of the Sketch archive.

The actual implementation at lines 32-35 writes every JSON file using:

Buffer.from(JSON.stringify(component), 'utf8')

This guarantees that characters from Chinese, Japanese, and Korean writing systems—along with emoji and other Unicode symbols—are preserved exactly as specified in the input spec.

Building Sketch Files with CJK Characters: CLI Usage

You can create a Sketch file containing CJK text using the command-line interface. The sketch-cli build command processes your JSON specification and produces a properly encoded .sketch archive.

First, create a specification file with CJK content:

{
  "pages": [
    {
      "name": "首页",
      "artboards": [
        {
          "name": "主页",
          "width": 375,
          "height": 812,
          "layers": [
            {
              "type": "text",
              "value": "欢迎使用 Sketch CLI 🚀",
              "fontSize": 24,
              "style": "$title"
            }
          ]
        }
      ]
    }
  ]
}

Then execute the build command:

npx sketch-cli build -i spec.json -o output.sketch

The execution chain flows through:

• cli.js — parses arguments and validates input
• builder.build() — orchestrates the build process
• buildSketchFile() — writes UTF-8 encoded buffers to the final archive

Programmatic Usage for UTF-8 Sketch Generation

For Node.js applications requiring direct Sketch file generation, import the builder module and call build with your specification path:

const { build } = require('./sketch/agent-harness/src/builder');

(async () => {
  const input = 'spec.json';
  const output = 'my-design.sketch';
  await build(input, output);
  console.log('Done – CJK characters are preserved');
})();

This approach is essential for automated design pipelines, AI-generated interfaces, or any workflow where layer names, text content, or metadata may contain non-ASCII characters.

File Structure and Encoding Responsibility

File	Purpose	UTF-8 Encoding Role
sketch/agent-harness/src/builder.js	Core archive builder	Implements buildSketchFile with explicit Buffer.from(..., 'utf8') calls
sketch/agent-harness/src/cli.js	Command-line entry point	Invokes builder; passes through raw JSON without transformation
sketch/agent-harness/README.md	Usage documentation	Describes the Sketch CLI capabilities

The separation of concerns ensures that encoding happens at exactly one point—the buffer serialization in builder.js—making the behavior predictable and testable.

Verification and Compatibility

Sketch files generated through this process:

• Open correctly in Sketch (macOS)
• Display properly in Lunacy (Windows, Linux, macOS)
• Pass validation by sketchtool and other automation utilities

The UTF-8 encoding applies to all JSON components within the .sketch archive, including:

• Page and artboard names
• Text layer values
• Style definitions and shared style names
• Symbol and instance identifiers
• Metadata and user data fields

Summary

• The HKUDS/CLI-Anything Sketch build process explicitly supports UTF-8 encoding for CJK characters by replacing the default JsonStreamStringify serializer.
• The buildSketchFile function in builder.js uses Buffer.from(JSON.stringify(...), 'utf8') to preserve multi-byte characters.
• Both CLI and programmatic interfaces pass CJK text through unchanged to the final .sketch archive.
• This solution targets a known limitation in the upstream sketch-constructor library.

Frequently Asked Questions

What causes CJK character corruption in standard Sketch file builders?

The sketch-constructor library's default JsonStreamStringify serializer processes JSON as a stream without proper multi-byte character handling. When encountering characters outside the Basic Multilingual Plane—or even common CJK characters requiring two bytes in UTF-8—the stream can split code points incorrectly, producing mojibake or invalid JSON that Sketch applications reject. The CLI-Anything implementation avoids this entirely by using JSON.stringify followed by an explicit UTF-8 buffer conversion.

Can I use emoji and other Unicode symbols alongside CJK text?

Yes. The Buffer.from(..., 'utf8') approach supports the full Unicode range including emoji, mathematical symbols, and right-to-left scripts. The Sketch file format itself stores JSON in UTF-8, so any valid Unicode string passed through the CLI-Anything builder will encode correctly.

Where is the encoding configuration documented in the source code?

The encoding intent is documented in a code comment at lines 20-27 of sketch/agent-harness/src/builder.js, adjacent to the buildSketchFile function definition. The actual implementation appears at lines 32-35. No external configuration is required—UTF-8 encoding is enforced behavior, not an optional setting.

Is the CLI-Anything Sketch builder suitable for production design systems?

Yes. The repository is maintained by HKUDS (The University of Hong Kong's Department of Computer Science) and implements defensive encoding practices that prevent data loss. The explicit buffer approach is more reliable than stream-based alternatives for internationalized content, making it appropriate for design systems serving global user bases.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}