KODA UI Manual

Introduction

This documentation covers how to create a Graphic User Interface (UI) for your instrument. You'll design the UI inside of Figma, and then export using the KODA Export plugin, which results in a .kdui (KODA UI) file that you can drag directly onto your instrument in the KODA app.

What You'll Need to Get Started

• Figma — A free account is fine.
• KODA Properties plugin
• KODA Export plugin

KODA Structure

Overview

Inside a Figma design project, you'll have a frame layer named Main. This is the main body of the instrument. Any static images contained in it will form the wallpaper background.

Inside the main body, you'll have UI widgets — appearing in Figma's lefthand column as layers with purple lettering and a ❖ or ◇ glyph. Examples: Sliders, Buttons, Menus.

Widget behavior is defined primarily by attached properties. You can view the properties of a selected widget in the upper righthand column. To add or modify them, use the KODA Properties plugin inside Figma.

Other key elements that define widget behavior include layer naming, and the color and text used inside the layers of your widget. Non-purple layers inside Main will be static images.

Optionally, some aspects of widgets can be changed via script during runtime — such as hiding, repositioning, opacity, and rotation. These are handled via GUI Actions inside of cmajor.

Once ready, use the KODA Export plugin in Figma to export as a .kdui file. The UI will appear when you load the attached instrument in the KODA app. If not yet attached, drag the .kdui onto the instrument from disk and save.

Main (Instrument Body and Wallpaper)

An instrument requires you to designate an area for the main body and wallpaper background. Drag in an image or create a rectangle, then name the layer Main in the Layers column. Right-click and choose Frame Selection (⌥⌘G on Mac, Ctrl+Alt+G on Windows). You should see a ⌗ appear next to the Main layer. The dimensions of the Main frame determine the size of your instrument.

A simple example of a Main frame.

You can place any static images or text inside the frame. As long as the layer is not purple in the Layers column (i.e. not a component or instance) and is nested inside the Main frame, it will appear as a static, unchanging element.

UI Widgets

Widget Types

Widgets are the dynamic elements built into the GUI that allow the user to interact with the instrument. They appear in the lefthand Layers column in purple, with a ❖ or ◇ glyph next to them.

Examples of UI widgets.

Properties

Widget behavior is defined primarily by attached properties. At a minimum, widgets must have a Type property (declaring what it is — e.g. slider, button, menu), and typically have a Parameter property declaring a unique name that allows the widget to pass values into the instrument.

You can view properties in the upper righthand column by clicking on the widget's component (❖).

Example of properties for "sli_vol"

To add or modify them, open the KODA Properties plugin, select the widget, enter the values, and press Apply. Properties can also be edited manually in Figma, but the plugin is recommended.

Other Important Elements

In addition to properties, other elements affect widget behavior depending on the specific widget type. Keep the following in mind:

• Fill color — Level Meters and Tables use a fill color from your layer to determine bar color.
• Font sizing, color, and justification (left / center / right) — Affects the text appearance of Labels, Value Edits, and Menus.
• Layer naming — Naming a layer Background results in a static background image, useful for framing widgets like Labels, Value Edits, and Menus. Panel names are used for tab-switching behavior via the Variant Name property.

Components / Variants / Instances

Components

Example of a component.

Components are special layer types displayed in purple in Figma's lefthand column. In KODA, they designate a layer as a UI widget.

To convert a normal layer or group into a component, right-click and select Create Component (⌥⌘K on Mac, Ctrl+Alt+K on Windows). The layer will turn purple and show a ❖ symbol. From here you can add properties, place it in your instrument, and use it as a widget — for example, when building a slider or button using a spritesheet.

Variants

A component set containing two variants: “Default”, “Variant2”.

If you're creating a button with off/on states without a spritesheet, select the component, right-click, and choose Main Component → Add Variant. A second instance of your button will appear below the first. In the Layers column, two ◆ layers will be nested inside the ❖ container (technically a "Component Set"). Use the + button to add more variants, then customize each one's appearance to convey different states.

Instances

An instance of the component is placed in the instrument’s Main body.

Once a component contains multiple variants, keep the stack of layers off to the side rather than placing it directly in Main. Select one of the variant layers, hold ⌥ / Alt while dragging, and a new layer with a ◇ symbol will appear — this is an instance.

The instance looks identical to the variant it was dragged from. By right-clicking and selecting Change Variant, you can swap the instance's appearance to any of the variants. This is the core approach for creating and managing button states.

After placing the ◇ layer inside Main, open the KODA Properties plugin to add the button state properties that allow states to function at runtime.

Animation: Three Methods

The Slider, Animation, and Button widgets support images that move or change. KODA offers three methods:

Quickstart Guide

Make a Slider, Animation, Or Button Using a Spritesheet

1. Be sure your spritesheet is located inside the UI folder for your sample library.
2. Open the KODA Properties plugin. Make sure to set the Type to Slider, Animation, or Button.
3. Drag the spritesheet from disk onto the drop zone marked with a dashed outline in the Spritesheet & Variants section.
4. Set the number of frames and orientation. Press Continue when finished previewing.
5. Buttons only: In the Button States section, enable the button states present in your spritesheets and drag to arrange the order to match. If unedited, a six frame spritesheet defaults to: Off, On, ClickOff, ClickOn, OverOff, OverOn. Two frames defaults to: Off, On.
6. At the plugin bottom, drag out from the dashed drag area into your Figma project. After a brief pause, the component with your properties will appear. Place this in your instrument, and be sure it's contained within the Main frame layer.

Make a Button or Animation Using Variants

1. Start by making a single frame, such as an "Off" button state. Note: this should be off to the side from your instrument's Main body.
2. Turn into a single ❖ component by right-clicking and selecting Create Component (⌥⌘K on Mac, Ctrl+Alt+K on Windows).
3. Add a ◆ variant by selecting the ❖ component, right-clicking, and choosing Main Component → Add Variant.
4. With the ❖ component selected (not a variant inside the component), you'll be able to add additional variants by pressing a "+" icon under the component set frame.
5. Now, with duplicates of your first image in each variant frame, you can make visual changes for each button state or animation frame.
6. When finished, drag out an ◇ instance by first selecting a ◆ variation, then holding ⌥ / Alt while dragging. Place the ◇ instance inside your instrument's Main body.
7. Open the KODA Properties plugin. Make sure to set the Type to Button or Animation. (Slider is also valid, but less common.)
8. Optional: With your ◇ instance (or ❖ component) selected, navigate to the Spritesheet & Variants section. Press the Preview Variants button.
9. Buttons only: In the Button States section, enable the button states present in your variants and drag to arrange the order to match your variants. If unedited and six frames, it defaults to: Off, On, ClickOff, ClickOn, OverOff, OverOn. Two frames defaults to: Off, On.
10. With your ◇ instance (or ❖ component) selected, press Apply at the bottom to apply the component properties for your UI widget.

Make a Menu

1. Create a rectangle. Add example text to the inside. (E.g. "Item 1"). The appearance of your menu when closed will depend on the text size, text color, and text alignment.
2. Select all menu layers and turn into a ❖ component by right-clicking and selecting Create Component (⌥⌘K on Mac, Ctrl+Alt+K on Windows).
3. Select the background rectangle layer and name it Background. Naming a layer "Background" inside a Widget tells it that you want this layer to be included as a static background image for your widget. If you skip this step, your menu will not have any background image.
4. Open the KODA Properties plugin. Set the Type to Menu.
5. In the Item List text field, enter each menu item separated by a line break. (Drag the lower right corner if you need to expand the text field size.)
6. Verify that Max Value is set to the number of items, minus one. (The first item is zero.) It should be updated automatically every time you update the Item List field.
7. Making sure your ❖ component is selected, press Apply at the bottom to apply the component properties for your UI widget.

Exporting From Figma to Your Instrument

1. Open the KODA Export Plugin in Figma (Right-click. Plugins › Development › KODA Export › Export GUI).
2. Press Export Components.
3. Make sure you are saving inside your instrument's UI folder.
4. In the KODA app, close and reopen your instrument to load the new UI changes.

Widget Property Reference

Properties Common to All Widgets

Slider

• Horizontal Slider — Responds to left/right mouse drags
• Vertical Slider — Responds to up/down mouse drags
• Knob — Responds to all directions
• State Display — Does not respond to the mouse

Button

Panel

Menu

Animation

Label

Level Meter

Table

Text Edit

Value Edit

XY Pad