Silk — Cross-Platform Go UI Framework & Visual Designer

A Go-native GUI framework with a visual form designer and integrated Go IDE. Drag widgets onto a canvas, arrange nested layouts, generate Go code, then build and run from the same workbench. The project is working toward a Qt Creator-style workflow; it does not claim full feature parity.

The SilkIDE mark is a cyan-to-blue folded silk S. Transparent PNGs and Windows/macOS application icons live in assets/branding.

---

Table of Contents

• Integrated Go Designer / IDE — screenshot and workflow
• Validation Status — tested platforms and remaining gaps
• Quick Start — build and launch
• Development Setup — prerequisites by OS
• Project Structure — what lives where
• Your First App — hello world with the SDK
• Using the Designer — visual form design
• Building & Running — all the common commands
• Features — what's included
• Troubleshooting — common issues

---

Integrated Go Designer / IDE

Actual macOS arm64 window captured on 2026-09-11, using the dark theme and an isolated demo project. This is a running application, not a mockup.

make run-ide     # Qt Creator-style Go editing + visual design workbench
make test-ide    # IDE, designer, widgets and tool-engine regression tests

• Welcome / Edit / Design modes: Cmd+1/2/3 on macOS, Ctrl+1/2/3 elsewhere.
• Save and undo/redo always target the visible document, from the toolbar, command palette or keyboard. Cmd/Ctrl+Shift+S saves all changed documents.
• Real file tabs only: edits show *; undoing back to the saved text clears it.
• Restart restores tab order, active file, cursor, vertical scroll and mode. Missing files are skipped; older path-only sessions still load. Unsaved code buffers are not crash backups: save/discard/cancel remains the quit guard.
• Saving .silkui regenerates a companion .silk.go: nested widgets, logical geometry, empty captions, scalar properties and exact RGBA colors are preserved. Declarative output describes structure; wire event handlers with BuildWithIndex in host code, or use the imperative exporter for handler bodies.
• Live preview: Cmd/Ctrl+Shift+R, or the eye button; export is a separate action.
• Built-in vector icons require no external directory. They use exact sRGB theme/semantic palettes and rasterize at the device transform for Retina and fractional scaling; disabled icons have their own neutral palette.
• Build / Run infer the nearest go.mod for forms stored in subdirectories; explicit project and run-directory settings take precedence.
• Drag-and-drop respects nested container ownership and form bounds. HBox, VBox, Grid and Form layouts share selection/locking rules with the context menu.
• Menus support keyboard navigation, disabled actions and nested popup dismissal. Properties and View Code activate the corresponding dock instead of silently doing nothing; export reports the actual output path or an error.
• Stop terminates the active Run command and its child processes as well as the debugger; independently opened terminal sessions are left alone.
• Project settings use the selected project root and persist Kit changes. About separates IDE and SDK versions, shows runtime/build details, and wraps or scrolls long content without overlapping its right-aligned Close button.
• Fit canvas: Cmd/Ctrl+Shift+0 (plain F remains available for code input).

For desktop verification, use a disposable project and an isolated settings home. gopls and dlv are optional external tools; installing or building the IDE alone does not establish language-server or debugger availability.

Validation Status

Environment	Latest local evidence	Not established by this check
macOS arm64 / Go 1.26.5	Real desktop interaction with all 9 main-menu entries, native Open/Save sheets, About/Settings, canvas context actions and Run/Stop; 11-package regression plus saved-design runtime tests	Every secondary panel action, real gopls/dlv end-to-end workflows, mixed-DPI multi-monitor behavior
Linux arm64 / Go 1.26.0	Debian 12 build, four-package tests, vet and non-root Xvfb window-startup smoke	Interactive desktop/IME/font coverage; a portable dependency-free binary
Windows amd64	silk_pure_go test-binary type compilation for ged and cmd/silkide	Native Windows GUI/Cairo execution

Run/Build currently use saved files on disk; save edits before running. IDE symbol actions require gopls and report when it is unavailable. Some panels still have incomplete localization/font fallback. Passing tests or installing external tools alone is not a full desktop compatibility claim.

Detailed, dated verification records: workbench · menus and About · SDK/platform compatibility · popup ownership · designer gaps. Local bin/qa-artifacts/ evidence mentioned in those records is not shipped in Git.

Rendering performance

Static UI no longer requests frames just to maintain a refresh rate. Ongoing quiet animation is capped at 25 FPS; input briefly raises the ceiling to 60 FPS, with extra recovery time after expensive frames. Windows rendering uses a coalesced deadline timer rather than a paint-to-animation feedback loop; custom modal dialogs block waiting for messages instead of polling every 1 ms. Hidden busy widgets stop their animation. Text/modified-state/outline caches avoid repeated full-document work while idle. These are code-level fixes; Windows native CPU/latency improvement still requires measurement.

See bounded CPU capture and Windows verification. Profiling is opt-in, local-only, and stops automatically after 30 seconds.

Quick Start

# 1. Clone
git clone https://github.com/uk0/silk.git
cd silk

# 2. Install system dependencies (macOS)
brew install cairo pkg-config

# 3. Build and run the integrated Go designer / IDE
make run-ide

# 4. Or run the widget gallery demo
CGO_CFLAGS="-I/opt/homebrew/include" go run demo.go

Drag widgets from the left panel onto the canvas, press F5 to compile & run.

---

Development Setup

Prerequisites

Dependency	Minimum Version	Purpose
Go	1.26+	Compiler
CGO	enabled	Required for Cairo
Cairo	1.16+	2D rendering backend
pkg-config	any	Find Cairo headers
GLFW 3.3	auto-downloaded	Window management (macOS/Linux)

macOS

# Install Homebrew (if not installed)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Cairo and pkg-config
brew install cairo pkg-config

# Verify
pkg-config --cflags --libs cairo
# Should output: -I/opt/homebrew/Cellar/cairo/.../include -L/opt/homebrew/Cellar/cairo/.../lib -lcairo

If go build can't find cairo/cairo.h, export the include path:

export C_INCLUDE_PATH=/opt/homebrew/include
export CGO_CFLAGS="-I/opt/homebrew/include"
export CGO_LDFLAGS="-L/opt/homebrew/lib -lcairo"

Add these to your ~/.zshrc or ~/.bashrc for persistent use.

Windows

silk's Cairo bindings need gcc + pkg-config + cairo from MSYS2's UCRT64 toolchain. Once those are on PATH, go build / go run / go test work from any of the three common Windows shells. Pick the one you prefer; the build flow is identical, only the env-var syntax differs.

One-time setup

1. Install MSYS2 from https://www.msys2.org/.
2. Open the MSYS2 UCRT64 shell (Start → "MSYS2 UCRT64").
3. Install the toolchain:

   pacman -S mingw-w64-ucrt-x86_64-gcc \
             mingw-w64-ucrt-x86_64-pkgconf \
             mingw-w64-ucrt-x86_64-cairo

Build & run from each shell

MSYS2 UCRT64 (recommended — PATH is already set):

cd /c/path/to/silk
go build -o silkide.exe ./cmd/silkide/
./silkide.exe
go test ./gui/ ./ged/ ./paint/ ./graph/ ./geom/

PowerShell:

$env:PATH = "C:\msys64\ucrt64\bin;$env:PATH"
cd C:\path\to\silk
go build -o silkide.exe .\cmd\silkide\
.\silkide.exe
go test .\gui\ .\ged\ .\paint\ .\graph\ .\geom\

Command Prompt (cmd.exe):

set PATH=C:\msys64\ucrt64\bin;%PATH%
cd C:\path\to\silk
go build -o silkide.exe .\cmd\silkide\
silkide.exe
go test .\gui\ .\ged\ .\paint\ .\graph\ .\geom\

Verify

go env CGO_ENABLED   # 1
gcc --version        # ucrt64 gcc, 13.x or newer
pkg-config --modversion cairo  # 1.18.x

If go build errors with 'cairo.h' file not found, the UCRT64 bin/ isn't on PATH — re-run the env-var line for your shell. The win32 package is compile-tagged Windows-only so it only enters the build on this platform; on macOS/Linux it's a no-op.

Linux (Ubuntu/Debian)

sudo apt update
sudo apt install -y \
    build-essential \
    pkg-config \
    libcairo2-dev \
    libx11-dev \
    libxcursor-dev \
    libxi-dev \
    libxinerama-dev \
    libxrandr-dev \
    libxxf86vm-dev \
    libgl1-mesa-dev

# Verify
pkg-config --libs cairo

Linux (Fedora/RHEL)

sudo dnf install -y \
    gcc pkgconfig \
    cairo-devel \
    libX11-devel libXcursor-devel libXi-devel \
    libXinerama-devel libXrandr-devel libXxf86vm-devel \
    mesa-libGL-devel

---

Project Structure

silk/
├── core/             Foundation layer
│   ├── factory.go        Object creation from registered types
│   ├── signal-slot.go    Event binding mechanism
│   ├── tdoc.go           Tree-structured persistence
│   └── shell.go          Platform file paths
│
├── gui/              Widgets + theming + layout engine
│   ├── widget.go         Base widget class
│   ├── button.go, label.go, edit.go, ...
│   ├── hbox.go, vbox.go, gridlayout.go   Layout containers
│   ├── theme.go          Color schemes
│   ├── animation.go      12 easing functions
│   ├── codeeditor.go     Full-featured code editor (~3,300 lines)
│   ├── formloader.go     SDK-level .silkui loader
│   ├── window_glfw.go    macOS/Linux window backend
│   └── window_windows.go Windows window backend
│
├── graph/            Scene graph for design canvas
│   ├── view.go           Graph view with zoom/pan
│   ├── tool.go           Interaction tools
│   └── resize-decor.go   Resize handles
│
├── ged/              Visual designer (GUI Editor)
│   ├── ged-view.go       Design canvas
│   ├── codegen.go        Go code generation
│   ├── code-panel.go     Event handler editor
│   ├── file-explorer.go  Project file tree
│   ├── editor-tabs.go    Multi-tab editor
│   ├── build-output.go   Compile error navigation
│   └── ... (25+ designer panels)
│
├── paint/            Cairo rendering abstraction
├── cairo/            Cairo C bindings (CGO)
├── geom/             2D vectors, matrices, rectangles
├── prop/             Property system
│
├── examples/         Runnable examples
│   ├── calculator/       Calculator app
│   ├── dashboard/        Charts & data binding
│   ├── todoapp/          Todo list
│   ├── texteditor/       Basic text editor
│   ├── showcase/         Widget gallery demo
│   └── load_silkui/      SDK loader example
│
├── icon/             PNG icons (4 sizes × 64 icons)
│
├── design.go         Visual designer entry point
├── demo.go           Widget gallery demo
└── sandbox.go        Test sandbox

Module Layout

// go.mod
module github.com/uk0/silk

Internal imports use: github.com/uk0/silk/core, github.com/uk0/silk/gui, github.com/uk0/silk/ged, etc.

---

组态 / SCADA & Industrial Platform

Beyond the widget toolkit, Silk ships a full industrial-automation (组态) stack built on a real-time tag database:

• Field-bus drivers — Modbus TCP, Siemens S7, OPC-UA and MQTT, covering every PLC data type and all four register/byte orders (ABCD/DCBA/BADC/CDAB), read-only or read-write. Wrap two in a redundant driver for primary/backup failover, or bridge protocols with the gateway. A simulator driver runs screens without hardware.
• Tags & bindings — core.TagDB streams device values into widgets via value-driven bindings, animation, alarms and rolling trends. Configure a device and its tag points visually with DeviceComponent, or stamp many devices from a structured template.
• Data & logic — historian (SQLite history), reports (interval aggregation → CSV/HTML), trend playback, recipes, calc/formula tags, event log, live statistics, runtime Go scripting, and user auth with login sessions.

tags := core.NewTagDB()
dev := device.NewDeviceComponent()          // Modbus / S7 / OPC-UA / MQTT
dev.SetProtocol("modbus")
dev.SetHost("192.168.0.10")
dev.SetPoints("level, hr:0, Float32, ABCD, RO\npump, coil:0, Bool, ABCD, RW")
dev.Start(tags)                             // poll device -> tags -> screen

The silkide designer/IDE adds LSP (gopls) code intelligence, a Delve debugger, and Qt Creator-style locator, find-in-files, snippets and build-issue navigation.

---

Your First App

Option 1: Pure SDK (No Designer)

package main

import (
    "github.com/uk0/silk/core"
    "github.com/uk0/silk/gui"
)

func main() {
    // Create main frame
    f := gui.NewFrameWindow()
    f.SetTitle("My First Silk App")
    gui.SetDefaultFrame(f)

    // Create a form with widgets
    form := gui.NewForm()
    form.SetTitle("Hello")

    btn := gui.NewButton1("Click Me", nil)
    btn.SetParent(form)
    btn.SetBounds(20, 20, 100, 30)
    btn.Action().BindFunc0(func() {
        gui.ShowMessageDialog(f, "Hi", "Hello, World!")
    })

    // Attach and show
    f.SuggestDocDock().AddView(form)
    f.SetClosedCallback(func(*gui.Frame) { core.Quit() })
    if w := f.Window(); w != nil {
        w.SetSize(400, 300)
        w.MoveToCenter()
    }
    f.Show()
    core.EventLoop()
}

Save as hello.go and run:

CGO_CFLAGS="-I/opt/homebrew/include" go run hello.go

Option 2: Load from Designer File

Design your form visually in the designer, save as main.silkui, then:

package main

import (
    "github.com/uk0/silk/core"
    "github.com/uk0/silk/gui"
    "log"
)

func main() {
    // Load design file — produced by the visual designer
    form, err := gui.LoadForm("main.silkui")
    if err != nil {
        log.Fatal(err)
    }

    f := gui.NewFrameWindow()
    gui.SetDefaultFrame(f)
    f.SuggestDocDock().AddView(form)
    f.SetClosedCallback(func(*gui.Frame) { core.Quit() })
    f.Show()
    core.EventLoop()
}

No designer code needed at runtime — just github.com/uk0/silk/core + github.com/uk0/silk/gui.

---

Using the Designer

Launch

CGO_CFLAGS="-I/opt/homebrew/include" go run design.go

Two Modes

Mode	Shortcut	Purpose
Design Mode	Ctrl+1	Drag widgets, edit properties, visual layout
Code Mode	Ctrl+2	File explorer, multi-tab code editor

Design Workflow

1. Drag a widget from the left palette onto the canvas
2. Click the widget to see/edit properties on the right
3. Double-click to open the event handler code editor
4. Press F5 to compile and run your app
5. Press Ctrl+R for quick preview (no compile)

Code Workflow

1. Ctrl+2 to enter Code Mode
2. Ctrl+P to quick-open any file
3. Cmd/Ctrl+Click on a function → go to definition
4. Ctrl+Shift+O → symbol navigation
5. Ctrl+Shift+F → format code (gofmt)
6. F5 → compile, errors shown with clickable navigation

Full Shortcut Reference

See Help → Keyboard Shortcuts in the designer for all 40+ shortcuts.

---

Building & Running

Running Examples

# Set CGO flags once per shell session
export CGO_CFLAGS="-I/opt/homebrew/include"
export CGO_LDFLAGS="-L/opt/homebrew/lib -lcairo"

# Then run any example
go run examples/calculator/main.go
go run examples/dashboard/main.go
go run examples/showcase/main.go

Note: Most examples use //go:build ignore — they're standalone programs, not part of the package build.

Building a Release Binary

go build -v -o myapp hello.go

# Smaller binary (strip debug info)
go build -ldflags="-s -w" -o myapp hello.go

# Cross-compile (static linking may require extra setup)
GOOS=linux GOARCH=amd64 go build -o myapp hello.go

Running Tests

# All tests
go test -short ./...

# Specific package with verbose output
go test -v ./gui/

# Benchmarks
go test -bench=. -benchmem ./gui/

Current test suite: 398+ tests, 100% pass rate.

Development Cycle

# 1. Edit source files
vim gui/button.go

# 2. Build to check
go build ./gui/

# 3. Run relevant tests
go test ./gui/

# 4. Launch designer to verify visually
go run design.go

---

Features

Built-in Widget Families

• Input (15): Button, Edit, CheckBox, RadioButton, ComboBox, SpinBox, Slider, ToggleSwitch, SearchBox, NumberInput, DatePicker, ColorPicker, Rating, DropdownButton, SwitchGroup
• Display (12): Label, ProgressBar, GroupBox, ImageView, Tag, Badge, Avatar, Breadcrumb, Link, LabelSeparator, Placeholder, Timeline
• Layout (10): VBox, HBox, GridLayout, FormLayout, Splitter, StackedWidget, TabWidget, Card, Accordion, ScrollArea
• Data (4): ListWidget, TreeView, Table, NotificationPanel
• Charts (5): LineChart, BarChart, PieChart, Gauge, ScatterPlot
• Window (6): Form, Dialog, Menu, ToolBar, StatusBar, CodeEditor

Designer Features

• Smart alignment guides (blue snap lines)
• Ctrl+Scroll zoom, Space+drag pan
• Object inspector, property editor with categories
• Undo/redo with visual history panel
• Code generation for 23+ event types
• Tab order editor, widget locking
• Form size presets (Desktop/Tablet/Phone)
• Theme preview, custom template saving

Code Editor Features

• Multi-cursor editing (Cmd+Alt+Up/Down)
• Cmd/Ctrl+Click cross-file go-to-definition
• Auto-completion (keywords, types, gui.* API)
• Find/Replace (Ctrl+F), Go to line (Ctrl+G)
• Symbol navigation (Ctrl+Shift+O)
• 14 Go code snippets, bracket matching
• Minimap, bookmarks (Ctrl+B)
• Rename refactoring (F2 in Silk IDE; requires gopls)
• Code formatting via gofmt (Ctrl+Shift+F)
• Error markers with squiggly underlines
• Split editor view (Ctrl+\)
• Git gutter markers

IDE Features (silkide)

• Language server (gopls) — completion, hover, go-to-definition, find-references, rename, format, code actions, signature help, diagnostics, plus call hierarchy, type hierarchy, implementations, inlay hints, semantic tokens and code lens
• Debugger (Delve) — breakpoints with conditions/hit counts/logpoints, goroutine- and frame-scoped locals, arguments and watches, lazily expanded variables, and a debug console
• Build & run — kits (toolchain, GOOS/GOARCH, tags, race/coverage, deploy profile), multiple named run/debug configurations, and a cancellable task runner with streaming output
• Testing — go test -json driven results in a package → test → subtest explorer with run/debug/rerun-failed and gutter actions
• Analyzers — vet, race, coverage, pprof, trace, govulncheck, staticcheck
• Version control — branches, remotes, fetch/pull/push, stash, rebase, cherry-pick, staged/unstaged/conflict grouping, hunk-level diff staging and a three-way merge editor
• Navigation & search — fuzzy quick-open, project-wide find/replace with regex and transactional preview, grouped references, outline, bookmarks and a live TODO index
• Terminal — PTY-backed shell session with a full ANSI screen (Unix; ConPTY pending on Windows)

---

Troubleshooting

cairo/cairo.h not found

Set the include path:

# macOS
export CGO_CFLAGS="-I/opt/homebrew/include"
export CGO_LDFLAGS="-L/opt/homebrew/lib -lcairo"

# Linux
export CGO_CFLAGS="-I/usr/include/cairo"

Icons show as red X

The designer loads icons from the ./icon/ directory. Run from the project root:

cd /path/to/silk
go run design.go   # from the directory containing icon/

"Duplicate libraries -lcairo" warning

Safe to ignore — it's a linker hint, not an error.

Windows: "The application was unable to start correctly (0xc000007b)"

Ensure you're using the MSYS2 UCRT64 shell or have C:\msys64\ucrt64\bin in PATH so Cairo DLLs are found at runtime.

F5 compile fails with "gofmt not found"

Install Go's standard tools (usually included with Go, but verify):

which gofmt
# Should print the gofmt path

---

Cross-Platform Support

Platform	Window Backend	Rendering	Status
macOS	GLFW + OpenGL	Cairo	✅ Primary
Windows	Win32 native	Cairo	✅ Supported
Linux	GLFW + OpenGL	Cairo	✅ Supported

---

Tech Stack

• Go 1.21+ — compiler
• Cairo 2D — 2D rendering
• GLFW 3.3 — macOS/Linux window management
• Win32 API — Windows window management
• OpenGL 2.1 — texture upload for back-buffer composition
• Zero external Go GUI dependencies — everything built from scratch

---

Contributing

# 1. Fork on GitHub
# 2. Clone your fork
git clone https://github.com/YOUR_USERNAME/silk.git
cd silk

# 3. Create a branch
git checkout -b feature/my-feature

# 4. Make changes and test
go test -short ./...

# 5. Commit (no signatures in messages)
git commit -m "Add feature X"

# 6. Push and open a Pull Request
git push origin feature/my-feature

---

File Format

Design files use the .silkui extension (TDoc-based tree format). Legacy .cml, .silk, .form files are still accepted on load for backwards compatibility.

Gantt chart regression commands, a reproducible .silkui fixture and desktop verification steps are documented in GANTT-TESTING.md.

---

License

AGPL-3.0

---

Silk — making Go desktop development silky smooth.