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

> Discover how HKUDS/CLI-Anything ensures UTF-8 encoding support for CJK characters in its Sketch file build process, bypassing default serializers for full character compatibility.

- Repository: [✨Data Intelligence Lab@HKU✨/CLI-Anything](https://github.com/HKUDS/CLI-Anything)
- Tags: how-to-guide
- Published: 2026-08-16

---

**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`](https://github.com/HKUDS/CLI-Anything/blob/main/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`](https://github.com/HKUDS/CLI-Anything/blob/main/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:

```javascript
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:

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

```

Then execute the build command:

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

```

The execution chain flows through:
- [`cli.js`](https://github.com/HKUDS/CLI-Anything/blob/main/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:

```javascript
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`](https://github.com/HKUDS/CLI-Anything/blob/main/sketch/agent-harness/src/builder.js) | Core archive builder | Implements `buildSketchFile` with explicit `Buffer.from(..., 'utf8')` calls |
| [`sketch/agent-harness/src/cli.js`](https://github.com/HKUDS/CLI-Anything/blob/main/sketch/agent-harness/src/cli.js) | Command-line entry point | Invokes builder; passes through raw JSON without transformation |
| [`sketch/agent-harness/README.md`](https://github.com/HKUDS/CLI-Anything/blob/main/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`](https://github.com/HKUDS/CLI-Anything/blob/main/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`](https://github.com/HKUDS/CLI-Anything/blob/main/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`](https://github.com/HKUDS/CLI-Anything/blob/main/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.