👋 Hello contributor

🧩 Design-Information-Modeling for Kit-of-Parts 🏘

You want to 🧩 the next 🏘🏛🏢🏭🏫🏨⛪🕌 with 🤖? But 📐🔢🗣👥🖱️️⌨️️ takes all your ⌚? Then try to 🧠 the 🧬 and let semio 💉🖥✒🖨🪄🚀

👋 Hello contributor

Note

Are you a user or new to semio? Then you might want to first check out our docs 📖

Glad to see you!

Let me walk you through 🚶

📑 Overview

🛍 Products
📄 Specs
🦑 Repo
- ⚖️ Principles
- 🔀 Git
🧑‍💻 Development
♻ Ecosystems
📦 Bundles
🏘 Examples
💯 Brand
⚖️ License
🔒Security
✨ Contributors
📊 Stats

🛍 Products ↑

Do you wonder how semio is interopable? The reason are shared specification, ecosystems and bundles 🪢

Work-in-progress artifacts stay bundled with the active ticket workspace so teams can trace temporary data without hunting global temp locations. The engine offers a dev/debug startup mode that waits for a debugger to attach before it runs. The engine can also run as a pure stdio MCP server for tool integrations.

✏ sketchpad ↑

sketchpad is a simple-to-use, accessible and browser-based user interface for semio🖱️️

It is the digital pencil for sketching plans and digital scalpel for building models in semio ✍

Sketchpad uses semantic borders to communicate interactive element edges and window boundaries. Windows are separated from the canvas edge and from each other by a single spacing unit, and each window is outlined by a continuous border.

Each window has a consistent set of icon actions (open in new window, maximize/minimize, close) that stays in the same position across window kinds.

Sketchpad uses background levels to visually distinguish the base canvas from windows, panels, and transient UI surfaces.

Sketchpad is a multi-window workspace: each app defines which window kinds it supports and window layouts persist so users can restore their preferred arrangement.

In a multi-window workspace, exactly one window is active and its surface uses the active background color; table views follow the active window surface background.

Hover and selection cues stay consistent across Home, Kit, Design, Type, Quality, Docs, and Feedback so focus follows your pointer and selection across the workspace.

👥 studio ↑

A studio is a synchronous collaboriation environment for teams to work together in semio 🤝

☁ cloud ↑

Use any file-hosting platform as an asynchronous Common-Data-Environment 📁

🤖 assistant ↑

The assistant helps you on every step in the design process with semio ✍

VS Code Extension ↑

The VS Code extension keeps tickets close to daily work with inline close or reopen actions that act on the selected ticket, commit visibility, and concise hover descriptions for quick scanning. Automation tooling rejects invalid arguments and non-file paths so MCP-driven workflows surface mistakes immediately. Ticket creation MUST require a Goal ID and interaction starts ALWAYS request a description, while file lists can be added later when needed. Ticket interaction and finish actions attach git-derived file lists and line totals scoped to the ticket files so progress and impact are visible from the ticket view. Code hygiene diagnostics ignore comment markers inside string literals so snippets and URLs stay clean of false comment warnings. Code hygiene diagnostics flag orphan definitions outside named sections so the file structure stays consistent. The command browser mirrors the repo command and subcommand hierarchy so discovery follows the same structure as the CLI. Problem list entries open in dedicated editor tabs so edits are immediately saveable. Contributor views merge ticket activity and file header credits into a per-person breakdown with line totals, grouped tickets, commits, bundles, and file navigation for quick context. The built-in Explorer adds a Sections panel that lists the current file structure (including JSON object keys), lets you jump to a section on click, supports F2 rename, and provides inline create-child, rename, delete, and drag-move actions. The semio-repo: Navigate command (semio.navigate) accepts any semiorepo:// URI or plain artifact ID and opens the corresponding resource: files open in the editor, folders and bundles reveal in the Explorer, tickets open their ticket.md, goals open their goal.json, contributors and commits open GitHub in the browser, and sections and definitions jump to the correct line. The semio-repo: Navigate to... command (semio.navigateTo) opens a quick pick listing all tree nodes from the repo. Clicking any tree item in the Monorepo view navigates to its resource, including goals which open their goal.json. A URI handler registered for the semiorepo scheme means clicking semiorepo:// links from terminals, markdown previews, or external applications triggers navigation within VS Code.

🦗 semio.gh ↑

A batteries-included Grasshopper plugin for semio ⚡

🦏 semio.3dm ↑

A Grasshopper-based integration of Rhino and semio 🔀

🐝 semio.wasp ↑

A Grasshopper-based integration of Wasp and semio 🔀

🦌 semio.monoceros ↑

A Grasshopper-based integration of Monoceros and semio 🔀

🐞 semio.ladybug ↑

A Grasshopper-based integration of Ladybug and semio 🔀

📄 Specs ↑

📦 Kit ↑

A kit is a collection of types, designs, authors, qualities, attributes, and concepts 📦

A kit is either static (a special .zip file) or dynamic (bound to a runtime) 📦

A static kit contains a reserved .semio folder that contains a kit.db sqlite file 💾

The SQL-schema of kit.db is found in ./sqlite/schema.sql 📄

For Inter-Process-Communication (IPC) the JSON-schema in ./jsonschema/kit.json is used 📄

🏘 Design ↑

A design is an undirected graph of pieces (nodes) and connections (edges) with organizational layers, groups, stats, attributes, and concepts 📐

A design is proto (a protodesign) when it has no parent.

Children of a parent are _subdesigns.

A flat design has no connections and all pieces are fixed ◳

The pieces are placed hierarchically (breadth-first) for every component 🌿

Additional connections which where not used in the placement can be used to validate the computed planes 🛂

🏠 Type ↑

A type is a reusable component with different models, connectors, attributes, concepts, and authors 🧱

A type is proto (a prototype) when it has no parent.

Children of a parent are _subtypes.

A type can be virtual (intermediate type requiring other virtual types to form a physical type), scalable, and mirrorable with stock quantity, unit, and optional location 📍

🔗 Connection ↑

A connection is a 3D-Link between two pieces with the translation parameters gap (offset in y-direction), shift (offset in x-direction) and rise (offset in z-direction), and the rotation parameters rotation (rotation around y-axis), turn (rotation around z-axis) and tilt (rotation around x-axis) 🪢

The translation is applied first, then the rotation 🥈

The two pieces are called connected and connecting but there is no difference between them 🔄

The direction of a connection goes from the lower hierarchy to the higher hierarchy of the pieces ➡

A connection can have attributes and diagram positioning with x and y offsets 📍

⭕ Piece ↑

A piece is an instance of either a type or a design with id, optional description, optional plane, center position, scale, optional mirror plane, hidden and locked states, color, and attributes 📐

A piece is either fixed (with a plane) or linked (with a connection) 📐

A group of connected pieces is called a component 🌿

The hierarchy of a piece is the length of the shortest path to the next fixed piece 👣

⚓ Connector ↑

A connector is a conceptual connection point with an outwards direction, id, optional description, and t value for diagram ring positioning 🤝

A connector can be marked as mandatory in which case it is required to be connected to a piece 💯

A connector can have a connector port and a list of compatible ports for explicit compatibility control 👨‍👩‍👧‍👦

No port means the default port and no compatible ports means the connector is compatible with all other connectors 🔑

It is enough for one connector to be compatible with another connector to be compatible with each other ↔

A connector can have props that define measurable characteristics and attributes for additional metadata 📏

💾 Model ↑

A model is a tagged url to a resource with an optional description 📄

No tags means the default model 🔑

The similarity of models is determined by the jaccard index of their tags 🔄

🏷️ Attribute ↑

A attribute is metadata with a unique name, an optional value, an optional unit and an optional definition (url or text) 🔤

The name iskebab-cased and with .-separated string similar to toml keys 🔑

No value is equivalent to the boolean true where the name is the category of the attribute 🔑

The unit is a unit identifier 🔢

mm for millimeter, cm for centimeter, dm for decimeter, m for meter, km for kilometer
m² for square meter, m³ for cubic meter, m⁴ for quartic meter
° for degree, rad for radian
N for newton, kN for kilonewton, MN for meganewton
°C for degree Celsius, °F for degree Fahrenheit
W for watt, kW for kilowatt, MW for megawatt, GW for gigawatt
Wh for watt-hour, kWh for kilowatt-hour, MWh for megawatt-hour, GWh for gigawatt-hour
J for joule, kJ for kilojoule, kcal for kilocalorie
kWh/m²a for kilowatt-hour per square meter per year
m/s for meter per second, m²/s for square meter per second, m³/s for cubic meter per second
Pa for pascal, kPa for kilopascal, MPa for megapascal
…

A list of attributes is semantically equivalent to nested dictionaries where the key is the name and the value is the value ↔

🏷️ Tag ↑

A tag is a kebab-cased name 🔤

◳ Plane ↑

A plane is a location (origin) and orientation (x-axis, y-axis and derived z-axis) in 3D space ✈

The coordinate system is left-handed where the thumb points up into the direction of the z-axis, the index-finger forwards into the direction of the y-axis and the middle-finger points to the right into the direction of the x-axis 👈

🔗 Url ↑

A url is either relative (to the root of the .zip file) or remote (http, https, ftp, …) string🌐

A relative url is a /-normalized path to a file in the .zip file and is not prefixed with with ., ./, /, …

🔢 Quality ↑

A quality is a measurement definition with a key, name, description, kind (General, Design, Type, Piece, Connection, Connector), unit information (SI and Imperial), range constraints (min/max with exclusion flags), default value, and optional formula 📏

A quality can be scalable (adjusts with piece scaling) and have multiple benchmarks for performance evaluation 🎯

The kind determines which entities the quality can be applied to using a bitwise enum system 🔢

📊 Benchmark ↑

A benchmark is a performance standard within a quality with a name, optional icon, and range (min/max with exclusion flags) 🏆

Benchmarks provide reference points for evaluating quality measurements against industry or design standards 📈

🏷️ Concept ↑

A concept is a name and order pair that provides semantic grouping for kits, types, or designs 🧠

Concepts enable hierarchical organization and categorization of design elements beyond simple naming 📂

👤 Author ↑

An author has a name and email and can be associated with kits, types, or designs with a rank indicating contribution level 👨‍💻

Authors provide attribution and contact information for design ownership and collaboration 🤝

📋 Layer ↑

A layer is an organizational grouping within a design with a name, optional description, and color for visual organization 🎨

Layers provide a way to group and manage pieces logically within complex designs 📑

👥 Group ↑

A group is a collection of pieces within a design with optional name, description, color, and attributes 👥

Groups enable semantic clustering of pieces that belong together functionally or conceptually 🔗

⚙️️ Prop ↑

A prop is a key-value pair on a connector that references a quality with a specific value and optional unit 🔧

Props define measurable characteristics of connectors using the quality system for standardized measurement 📐

📈 Stat ↑

A stat is a statistical measurement on a design that references a quality with range (min/max) and optional unit 📊

Stats provide computed or measured performance data for entire designs using the quality framework 📈

🦑 Repo ↑

This git repo has everything that exists in the open semio ecosystem 🤯

⚖️ Principles ↑

Let's start with the rules of thumbs that this codebase was built with 🫰

💾 If something can be written in a single file, then it probably should ✅

I know, the urge to tidy up or separate things is big 🗃️️

But try to withstand it 🫥

Out of my experience, it makes development slower, not faster 🐌

A single file is easier for humans and computers to understand 💡

You will be surprised

by the awesome fill-in-the-middle suggestions of your copilot 🤖
by the hassle-free context selection for your ai agent 🖱️️
by the smooth refactor experience by just going top-to-bottom ⬇
by the beautiful diff for your next code review 🔍
by the clean git-history when you try to find a certain change 🔁

🙃 Write and read code upside down ✅

Whenever something is referenced it should be above in the source code ⬆

This means that all the building blocks (functions, classes, components, …) are first defined and then used below ⬇

If you have a cyclic depedency (really?!) then put the object with lower complexity first 🥇

This means that when you start with unknown code, it is probably best to start on the bottom and go upwards 🖱️️

Why? LLMs, reflection, … , work best left-to-write 🤖

But Fill-in-the-Middle training is for free!?

Yeah, if you consider only FiM for code, then yes 🆗

But we want it all!

And is really so hard to start reading a from the bottom?

📑 If a class, function, component, … is only used once, then don't create it ❌

Probably, you learned to group code by classes, functions, components, … even if those definitions are only used once 🥇

It hides the actual complexity and makes it harder to navigate the code 🔍

📺 Inline everything that bearly fits onto the screen ✅

Smaller code, less tokens and easier diffs 🔍

Your ai bill will be lower and the completions will resolve faster 🚀

If you are not sure what the code does, you can ask ai 💬

🗣 Don't use comments or if you must, only tag code at the end of the line ❌

Smaller code, less tokens and easier diffs 🔍

Your ai bill will be lower and the completions will resolve faster 🚀

If you are not sure what the code does, you can ask ai 💬

📑 Use regions to structure your code ✅

Because you are not using classes, functions, components, … and you are inlining everything, your code will become long 📃

To organize your code, you can use nested regions 📂

In general, our files follow this structure:

Header
TODOs
Imports
Constants
CODE

📁 If a folder doesn't make your life dramatically easier, don't create it ❌

We all know this ./src/** folder that has made it into a lot of starters 🚀

Other than feeling cool about using hacky abbreviations, does it really help you to understand the bundle faster and work more efficient on it?

If your bundle contains hundreds of config file and other bundle folders at the root, maybe 🤔

But most likely not ❌

📦 Parts that belong together should be close in the source code ✅

The default code organization is to group kind of structurally similar parts together 📂

All models next to each other, all controllers next to each other, all errors next to each other, …

While this pattern supports structural refactoring, it makes plain extensions harder because you have to search through all the files 🔍

Most changes are plain extensions and not structural refactors 🔄

Further it has the advantage that every LLM-agent only has to predict one big block of code instead of plenty of small ones 🤖

That's why frameworks like React exist or vendoring such as with shadcn is more flexible than dependcenies such as with bootstrap

Cutting components vertically (a bit of logic with a bit of UI) instead of horizontally (all logic, all ui) requires more effort but enhances reusability 🔮

📄 If multiple people work longterm on the same part, then one file for each part should be created ✅

Trust me, it will make collaboration much easier 🔀

🔮 If you don't need an port because something is not likely to be extended soon, don't create it ❌

The main question is the port productive or not?

The pay-off of abstraction happens in the future 🛣

Every extension profits from a clean port 🚀

Most things are not extended 🪨

If you change your architecture, just design proper ports for something concrete not something potential and reactor it ✍

🤏 Repeating code is ok if it the repeated code is close in the source code ✅

We are past the time where we copy code for no reason 📃

Actually repeated code can improve the attribute of your copilots suggestion 🤯

The main question is how can your application grow?

If a change requires exponentially more duplication then you'll probably have to fix it 🛠️

If not, then you are probably good 👌

🏷️ Never use `type` for naming enums, ports, or types. Always use `kind` instead ✅

To avoid confusion with the native type concept in Semio, always use kind for naming enums, ports, or types that represent categories or classifications 🏷️

Examples: ArtifactType → ArtifactKind, WindowType → WindowKind, etc. 🔄

🤨 Wait, no high-level advice and only plain numbers, files, folders or close line of codes?

In our understanding, policy-of-thumbs are most useful when they are concrete 🔨

Besides that we are sure you know about KISS (Keep-It-Simple-Stupid), DRY (Dont-Repeat-Yourself) vs WET (Write-Every-Thing-Twice)/RUG (Repeat-Until-Good), YAGNI (You-Aren't-Gonna-Need-It), SoC (Separation-of-Concerns), Avoid Premature Optimization, Law of Demeter, LCHC (Low-Coupling-High-Cohesion), SOLID (SR (Single Responsibility), OC (Open/Closed), LS (Liskov's Substitution), IS (Port Segregation), DI (Dependency Inversion)), …

But as always, the devil is in the details 😈

Even if 95% of the codebase follows those principles, there are good reasons for the other 5% ⚖️

🚩 Don't worry, you'll figure out the possibilities and make the right choice for the specific problems ✅

🔀 Git ↑

🦑 GitKraken ↑

Note

It is free for open-source bundles like this one ❤

We use GitKraken Desktop as our git client 🖱️️

It is the only nice chronological graphical overview for all branches at the same time that we found 🔍

💬 Discord ↑

Most git events are synchronized with our repo channel 💬

It is perfect to find the latest activities and the history 🔍

📢 Release ↑

Every release contains a set of matching specs, bundles, examples and docs 📦

The release notes follow this format:

SYMBOL TITLE

COMPONENT
- SYMBOL SUMMARY [CONTRIBUTOR]
…

Title symbols:

🏗️️ Foundational work
🛠️ Heavy work
🪛 Minor work
🐛 Major Bug fix

Description symbols:

🌱 Started [not yet ready]
➕ Added [ready]
⬆ Updated
🔄 Renamed
🔁 Refactored
🐛 Bug fix

Before every release the repo is archived 📦

🏷️ Tag ↑

We have two different types of tags:

rYY.MM-V for releases (e.g r21.06-1,r23.07-2,r24.12-1, r25.07-1, …)
COMPONENT-vMAJOR.MINOR.PATCH for bundles which follow the semver versioning scheme (e.g engine-v4.0.2, sketchpad-v1.0.0, grasshopper-v5.4.0-beta, …)

🌿 Branch ↑

The main branch is compressed (squashed history) and acts as the canonical integration branch 🗜

If a release receives updates after main already progressed, create a parallel release/rYY.MM-V branch for that release and keep it compressed as well 🧵

Every contributor has their own FIRSTNAME general-purpose development branch 🛠️

In GitKraken you will quickly find the latest development branch 👀

Other branches are created for bundles, specific features or bug fixes 🐛

Usually one person works on one feature at a time and hence the -NAME suffix 📛

🗃️️ Commit ↑

Commit messages follow this format:

MAIN-TASK-SYMBOL SUMMARY WORK-SYMBOL

The first symbol encodes the main task of the commit and the last symbol encodes the amount of work (🪛 < 🔨 < 🛠️ < 🏗️️) 🧰

📦 Commit as much as you like ✅

Are you worried about committing all those binary application files (.zip, .gh, .blend, .glb, .3dm, …) or the intermediate versions between your ai edits?

Well, normally you should be 💾

But as we archive and squash all commits on every release nothing is lost or polluted 💯

⌛ Push around once an hour ✅

Pushing regularly keeps you extra safe from losing your work 🛟

There are a few services (like Discord) that are automatically updating to what happens in the repo 🔄

To keep our inbox notifications low, we try to push not more than once an hour ⬆

🧑‍💻 Development ↑

Different ecosystems need different tools 🧰

🐳 Devcontainer (Recommended) ↑

The recommended way to develop is using the devcontainer which provides a consistent cross-platform environment.

Prerequisites:

Docker Desktop or compatible container runtime
VS Code with Dev Containers extension

Getting Started:

Clone the repository
Open in VS Code
Click "Reopen in Container" when prompted (or run "Dev Containers: Reopen in Container" from command palette)
Wait for container build and setup to complete

The devcontainer includes:

Node.js 22.x, Go 1.24, Python 3.13, .NET SDK 7.0/8.0, Rust
All required VS Code extensions
Pre-configured development environment
Port forwarding for all dev servers (3000, 4000, 4321, 5678, 6006, 2507)

🪟 Windows Setup (Legacy) ↑

For a complete setup you need:

If you do not have Python installed, I recommend to install it over the Microsoft Store 🏪

Afterwards you can install uv with this command:

irm https://astral.sh/uv/install.ps1 | iex

Then you can run semio-repo/cli/cli preflight build from the root to build all packages, or run tsx ./build.ts in the Grasshopper directory and add your full path LOCAL_PATH\net\Semio.Grasshopper\Debug\net48 to your GrasshopperDeveloperSettings ⚙️️

🎫 Tickets ↑

Contributor workflows use tickets to track each task across interactions. A ticket interaction records a prompt, author, and is bounded by {started, finished} timestamps. Ticket workflows record file touch lists and per-file line diffs so work is auditable and easy to continue. Each ticket workspace keeps a single ticket.md with todos, changes, log, and summary sections so all task context stays in one place, and an important.md file for compulsory actions that must be completed before the ticket can be finished.

🧰 Violations ↑

Contributor workflows include an automated code-quality report that highlights inline and multi-line comments (including JSDoc blocks), missing license headers, malformed region blocks, and empty regions before changes are shared. Comment scanning works uniformly across all supported languages (TypeScript, Go, Python, C#, Shell, Rust) through a single generic implementation in BaseLanguage.ScanComments. Each language declares its own string literal flavors (template literals for JS/TS, raw backtick strings for Go, triple-quoted strings for Python, verbatim @"" strings for C#) so the scanner correctly ignores comment markers inside string contexts. Each language also declares its own skip directives (e.g. eslint-/@ts- for TypeScript, nolint for Go, noqa/type: ignore for Python, pragma for C#) which are excluded from comment violations alongside the built-in TODO and semio-ignore- directives. It also enforces module boundaries and domain-neutral terminology for shared UI building blocks. Each reported problem includes a short reason and solution so contributors can resolve violations quickly.

The fix command applies autofixes for all autofixable violation kinds: it replaces wrong file header artifact IDs with the correct emoji-prefixed path (e.g. 💻 semio/js/src/index.ts), removes empty sections (including one surrounding blank line, preferring the preceding one), resolves missing section end names by walking backward through nested sections to find the matching start, corrects mismatched section end names, removes contiguous inline comment blocks (including intervening blank lines), and removes block and JSDoc comments. After removing lines, a post-processing step collapses consecutive blank lines so the output stays clean. Non-autofixable violations (missing header regions, unnamed region starts, orphan definitions) are reported but left for manual resolution.

🔌 Port Numbers ↑

Overview of all connectors used during development and in final packages:

Service	Port	Command / Package	Notes
Sketchpad	`3000`	`dev js js sketchpad`	Vite dev server for Sketchpad
Play	`4000`	`dev play`	Vite dev server for Play
Docs	`4321`	`dev docs`	Astro dev server (default)
Storybook	`6006`	`dev js js storybook`	Storybook dev server (default)
Playwright	`5173`	`npm test` (js)	Test server for Playwright E2E tests
Engine	`YYMM`	`semio/engine` package	Connector derived from release: `rYY.MM-V` → `YYMM` (e.g., `r25.07-1` → `2507`)

Running Tasks

Press Ctrl+Shift+P (or Cmd+Shift+P on macOS) → "Tasks: Run Task" and select from:

Root-level commands:

build - Build all packages
test - Run all tests
fix - Run auto-fixes/formatters
analyze - Run non-mutating checks
preflight - Run all preflight checks (default build task)
update - Update dependencies
publish:test - Publish to test servers
publish - Publish packages
dev - Start all dev servers
dev js js storybook - Start semio/js Storybook
dev js js sketchpad - Start semio/js Vite Sketchpad (connector 3000)

Workspace-specific commands:

build [workspace] - e.g., build js, build engine, build vscode
test [workspace] - e.g., test js, test engine, test vscode
preflight [workspace] - e.g., preflight js, preflight engine
dev [workspace] - e.g., dev js, dev engine, dev play, dev docs

Launch Configurations

Press F5 or use the Run and Debug panel to launch:

Development:

dev - Start all services with Python debugger attached
dev engine / dev js / dev play / dev docs / dev vscode - Individual services
dev js js storybook / dev js js sketchpad - semio/js specialized dev entrypoints

Testing:

test - Run all tests
test js / test engine / test vscode - Individual test suites

Fix / Analyze:

fix - Run auto-fixes/formatters
analyze - Run non-mutating checks

Preflight:

preflight - Run all preflight checks
preflight js / preflight engine / preflight vscode - Individual checks

Building:

build assets / build icons / build engine / build js / build docs - Individual builds

Publishing:

update / publish:test / publish - Root-level publishing commands

🪄 AI ↑

Most of our codebase is heavily optimized for AI agents 🤖

We pick tools based on billing model (request-based vs token-based), required context size, and whether a workflow needs MCP (e.g. Playwright) 🧰

🛠️ Uses-Cases ↑

Here some strategic advice for different uses-cases 🗺

⚖️ Decision Making ↑

Model will always tell you that your ideas, guesses, analysis, … are great 💯

This makes it really hard to use them for decision making because they tend to just reinforce your own bias 📢

Try to formulate everything as neutral, general and unbiased as possible 🕊

🔁 Refactoring ↑

Most refactors are too big to be done in one go and models are usually steered that if they think the problem is too big then they try to automate it with scripting 🤖

This is usually not possible and then they fail ❌

After all from a provider perspective those tasks are dangerous and hard to scale and we understand why they want the model to avoid doing it 🔥

The next problem is that when they take the wrong approach then, due to large context, they hardely remember how the original state was 🤔

For this reason, we usually create a new file which we name with the suffix*.old and this way in the prompt we can refer to the original state 📄

🐛 Bug Fixes ↑

Try to describe only how to the bug appears and not what you think caused it 😶

Experience what can be causes for bugs is increadibly valuable skill as a developer but the problem is that models are really biased the way you ask questions 🏋

Especially when your guess is wrong then the model might have found the mistake but because of your bias it tries to take a different approach to fix it 🔀

Secondly, if the model can't find the bug then it will often try to remove functionality, add try catch blocks, add logging and other things that fastly turn your codebase into a mess 💣

Therefore, it is often a good idea that after you found the bug, reset your branch and create a new ticket where you define exactly how to fix the bug 🪛

⌨️️ Tools ↑

🌐 Web-Chat ↑

For research, prompt preparation or single file-related operations (sorting, formatting, explaining, …) we use the free , Gemini or Groq, … in the browser to not waste precious tokens 🆓

❄ ChatGPT ↑

The free quota is very quickly reached but resets regularly and hence we just use it for questioning or prompt preparation 💬

🌟 Gemini ↑

AI studio ↑

Good for larger experiments due to more generous free quota 🧪

💻 Editor ↑

✈ Copilot ↑

📚 Resources:

Chat modes

Copilot is our default for most tickets because request-based billing makes fast interaction cheap 💳

🖱️️ Cursor ↑

📚 Resources:

Rules

We have the Pro plan 💳

We use Cursor as our main editor for typing code mostly with Tab ➡

For tasks that require updated large docs that are too large to paste into the prompt, we use the agent 📚

But in general, we don't use the chat because it is way too expensive 💰

🌊 Windsurf ↑

Used for token-heavy test-driven-development workflows with MCP (especially Playwright) 🧪

⌨️️ CLI ↑

⌨️️ Claude Code ↑

We have the Pro plan 💳

Used for small bugs and focused fixes with strong repo context 🧠

🧾 Codex ↑

Used for simple tasks (small edits, small refactors, small doc updates) 🧩

☁ Cloud ↑

🦑 Jules ↑

[!NOTE] Free plan includes 15 tasks per day, 3 concurrent tasks and powered by Gemini 2.5 Pro 🚀

Used on the phone when no IDE is available 📱

🔍 Agents ↑

↕ Reorderer ↑

Used to ensure consistent order of source code, docs, …

🔁 Formatter ↑

Used to ensure consistent formatting of source code, docs, …

🤖 Models ↑

The default model for agent work is Claude Opus 4.5, with GPT-5.2 Codex and GPT-5.3 Codex as alternatives 🧠

Claude Opus 4.5 ↑

GPT-5.2 Codex ↑

GPT-5.3 Codex ↑

🔄 CI/CD ↑

📺 Channels:

TechWorld with Nana - devops

All automation, CI runs, and agent workflows are controlled through the canonical root commands dev, fix, analyze, preflight, test, build, update, publish:test, and publish. Only dev is allowed to stay live for watch mode, while the remaining commands must exit so CI and agents can finish reliably. publish:test and publish always run a full build first. The root package.json uses preflight.ts to orchestrate the command pipeline, and delegates bundle builds/tests/publishing to Nx (npx nx run-many -t <target>).

♻ Ecosystems ↑

Documentation for each ecosystem has been migrated to the respective bundle README.md files:

semio/js/README.md - JavaScript (React, TypeScript, Vite, Tailwind, Three.js)
semio/net/README.md - .NET (C#, NuGet, Grasshopper)
semio/py/README.md - Python (uv, Pydantic, SQLAlchemy)

📦 Bundles ↑

Documentation for each bundle has been migrated to the respective bundle README.md files:

Bundle	README
.devcontainer	.devcontainer/README.md
semio-repo/cli	semio-repo/cli/README.md
semio-repo/vscode	semio-repo/vscode/README.md
semio-repo/server	semio-repo/server/README.md
semio-repo/graphql	semio-repo/graphql/README.md
semio-repo/sqlite	semio-repo/sqlite/README.md
semio	semio/README.md
semio/js	semio/js/README.md
semio/engine	semio/engine/README.md
semio/desktop	semio/desktop/README.md
semio/docs	semio/docs/README.md
semio/play	semio/play/README.md
semio/net	semio/net/README.md
semio/py	semio/py/README.md
semio/go	semio/go/README.md
semio/rs	semio/rs/README.md
semio/assets	semio/assets/README.md
semio/sketchpad	semio/sketchpad/README.md
semio/sqlite	semio/sqlite/README.md

🏘 Examples ↑

🚀 Starter ↑

👋 Hello semio ↑

🌈 Geometry ↑

🫀 Metabolism ↑

💯 Brand ↑

✍ Concept ↑

✅ Do ↑

Visual is better than text 👀
Compact ➡ More information ➡ Faster to understand 🚀

❌ Dont ↑

Rounded corners ⬜
Shadows 🌤
Multiple unicode directly after each other 🥇🥈🥉

🌈 Colors ↑

Name	Hex	RGB	HSL	HSV (or HSB)	CMYK	Color
Primary	#FF344F	255, 52, 79	352, 100, 60.2	352, 79.6, 100	0, 80, 69, 0	Folly
Secondary	#00A69D	0, 166, 157	176.7, 100, 32.5	176.7, 100, 65.1	100, 0, 5, 35	Persian green
Tertiary	#FA9500	250, 149, 0	34.8, 100, 49	35.76, 1, 0.49	0, 40, 100, 2	Princeton orange
Dark (= 0)	#001117
Grey 100 (= 0.1 = 1/10)	#06171C
Dark 8-9 (= 0.1̅ = 1/9)	#07181D
Dark-Dark-Dark-Grey (= 0.125 = 1/8)	#091A1F
Dark 6-7 (= 0.142857 = 1/7)	#0C1C21
Dark-Dark-Grey (= 0.166667 = 1/6)	#112025
Grey 200 (= 0.2 = 1/5)	#18272A
Dark 7-9 (= 0.2̅ = 2/9)	#1D2B2F
Dark Grey (= 0.25 = 1/4)	#243235
Dark 5-7 (= 0.285714 = 2/7)	#2E3C3D
Grey 300 (= 0.3 = 3/10)	#334041
Dark-Dark-Grey (= 0.3̅ = 1/3)	#3E494A
Dark-Grey-Grey-Grey (= 0.375 = 3/8)	#4C5756
Grey 400 (= 0.4 = 2/5)	#555F5D
Dark 4-7 (= 0.428571 = 3/7)	#606966
Dark 5-9 (= 0.4̅ = 4/9)	#666E6B
Grey (= 0.5 = 1/2)	#7B827D
Light 5-9 (= 0.5̅ = 5/9)	#91968F
Light 4-7 (= 0.571429 = 4/7)	#979B94
Grey 600 (= 0.6 = 3/5)	#A2A59D
Light-Grey-Grey-Grey (= 0.625 = 5/8)	#ABADA4
Light-Grey-Grey (= 0.6̅ = 2/3)	#B9BBB0
Grey 700 (= 0.7 = 7/10)	#C4C4B9
Light 5-7 (= 0.714286 = 5/7)	#C9C8BD
Light Grey (= 0.75 = 3/4)	#D3D2C5
Light 7-9 (= 0.7̅ = 7/9)	#DAD9CB
Grey 800 (= 0.8 = 4/5)	#DFDDD0
Light-Light-Grey (= 0.8̅ = 5/6)	#E6E4D5
Light 6-7 (= 0.857143 = 6/7)	#EBE8D9
Light-Light-Light-Grey (= 0.875 = 7/8)	#EEEADB
Light 8-9 (= 0.8̅ = 8/9)	#F0ECDD
Grey 900 (= 0.9 = 9/10)	#F1EDDE
Light (= 1)	#F7F3E3

🥇 Primary ↑

Use the primary color for the most important elements of your design 🏆

We use it e.g. for:

Highlighting interactive elements 🖱️️
Background for important elements 🟥

🥈 Secondary ↑

🥉 Tertiary ↑

⚫ Dark ↑

⚪ Light ↑

🩶 Gray ↑

Are you curious how a 1, 2, 3, 4, 5, 6, 7, 8, 9, 10 and 11 colored gradient can come together for an invertible theme in a semantically meaningfull way? Well, here is how you achieve it with 33 colors 🤯

📄 Typography ↑

Note

Try to place notes either in the beginning or the end of a section ↕ A starting note should contain something important but not crucial to give the brain the right context 🧠 The starting sentence of a note needs no symbol because every note type starts with a symbol 🥇

Be consistent with your language ♻
When things are analogical use the same sentence structure for it 🔄
One symbol after every sentance 💯
One symbol at a time 🥇
A symbol is preferably an emoji or otherwise unicode ⚖️
📝 One symbol to summarize a title
💡 One symbol to summarize a title description and one to think about in the end 🤔
. are forbidden ⛔
All components in semio (sketchpad,studio, …) start with a small letter 🔡
Did you know that … is just one character?

Tip

In the end of a section you can give the curious reader a summarizing question to think about the consequences and a link to more resources 🤔

🔡 Typesetting ↑

Sans serif: Anta 🖨
Serif: Kelly Slab ✍
Monospaced: Shart Tech Mono 🖥
Emoji: Noto Emoji ⚫

👀 Visual elements ↑

Sharp corners 📐
Borders □
Basic geometric shapes ⚪

⚖️ License

The files in this repository are licensed under the GNU Affero General Public License unless otherwise described. Most libraries, modules, extensions, objects or code herein are explicitly licensed. This is indicated in the root of the containing folder under a different license file, or in the configuration files of a bundle or in the respective file's header.

As a reference, different type of components have usually different licenses:

software libraries: LGPLv3 or later - GNU Lesser General Public License Version 3
applications: AGPLv3 or later - GNU Affero General Public License Version 3
examples: MIT - The MIT License
templates: CC0 - No Rights Reserved
assets: CC BY-ND 4.0 - Attribution-NoDerivatives 4.0 International

If you have any questions, please don't hesitate to get in touch with us over email 📧

🔒 Security

If you have any security vulnerabilities or concerns, please contact us over email and don't open an issue, discussion or write into our public discord server 🥷

✨ Contributors ↑

_{Ueli Saluz}
_🟨 _🟪 _🐍 _🦗
_✏ _⚙️️ _🤖 _🎛
_📚 _🛍 _💯
_🦏 _🐝 _🦌 _🐞
_🫀 _👋 _🚀

_KinanSarak
_📚 _👋 _🦗

_{Christian Hödtke}
_🦗

_{AdrianoCelentano}
_🟨

_ellumpine
_🦗 _🐞

_kaatzjo
_⚙️️

_pizzadizza
_🤖

📊 Stats

We use Goatcounter for gaining insights about our docs 📈

Name		Name	Last commit message	Last commit date
Latest commit History 737 Commits
.claude		.claude
.codex		.codex
.cursor		.cursor
.devcontainer		.devcontainer
.github		.github
.husky		.husky
.semio-repo		.semio-repo
.vscode		.vscode
.windsurf		.windsurf
coda		coda
semio-repo		semio-repo
semio		semio
.gitattributes		.gitattributes
.gitignore		.gitignore
.gitmodules		.gitmodules
.mcp.json		.mcp.json
.npmrc		.npmrc
.prettierignore		.prettierignore
.prettierrc.json		.prettierrc.json
.todo.md		.todo.md
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CITATION.cff		CITATION.cff
CLAUDE.md		CLAUDE.md
Cargo.lock		Cargo.lock
Cargo.toml		Cargo.toml
LICENSE.md		LICENSE.md
Monorepo.sln		Monorepo.sln
README.md		README.md
concepts.json		concepts.json
config.json		config.json
conftest.py		conftest.py
dictionary.csv		dictionary.csv
go.work		go.work
go.work.sum		go.work.sum
nx.json		nx.json
package-lock.json		package-lock.json
package.json		package.json
pyproject.toml		pyproject.toml
tsconfig.json		tsconfig.json
uv.lock		uv.lock
vitest.config.ts		vitest.config.ts

License

usalu/semio

Folders and files

Latest commit

History

Repository files navigation

👋 Hello contributor

📑 Overview

🛍 Products ↑

✏ sketchpad ↑

👥 studio ↑

☁ cloud ↑

🤖 assistant ↑

VS Code Extension ↑

🦗 semio.gh ↑

🦏 semio.3dm ↑

🐝 semio.wasp ↑

🦌 semio.monoceros ↑

🐞 semio.ladybug ↑

📄 Specs ↑

📦 Kit ↑

🏘 Design ↑

🏠 Type ↑

🔗 Connection ↑

⭕ Piece ↑

⚓ Connector ↑

💾 Model ↑

🏷️ Attribute ↑

🏷️ Tag ↑

◳ Plane ↑

🔗 Url ↑

🔢 Quality ↑

📊 Benchmark ↑

🏷️ Concept ↑

👤 Author ↑

📋 Layer ↑

👥 Group ↑

⚙️️ Prop ↑

📈 Stat ↑

🦑 Repo ↑

⚖️ Principles ↑

🔀 Git ↑

🦑 GitKraken ↑

💬 Discord ↑

📢 Release ↑

🏷️ Tag ↑

🌿 Branch ↑

🗃️️ Commit ↑

🧑‍💻 Development ↑

🐳 Devcontainer (Recommended) ↑

🪟 Windows Setup (Legacy) ↑

🎫 Tickets ↑

🧰 Violations ↑

🔌 Port Numbers ↑

Running Tasks

Launch Configurations

🪄 AI ↑

🛠️ Uses-Cases ↑

⚖️ Decision Making ↑

🔁 Refactoring ↑

🐛 Bug Fixes ↑

⌨️️ Tools ↑

🌐 Web-Chat ↑

❄ ChatGPT ↑

🌟 Gemini ↑

AI studio ↑

💻 Editor ↑

✈ Copilot ↑

🖱️️ Cursor ↑

🌊 Windsurf ↑

⌨️️ CLI ↑

⌨️️ Claude Code ↑

🧾 Codex ↑

☁ Cloud ↑

🦑 Jules ↑

🔍 Agents ↑

↕ Reorderer ↑

🔁 Formatter ↑

🤖 Models ↑

Claude Opus 4.5 ↑