The UX of grid-based applications

Yes, now you have to :smiley:

This said, the way things have developed on the Teletype are certainly a good “best practice” example in my opinion.

1 Like

Please do. I spent some time a few months ago trying to think through some arc functionality and wound up recreating the arc documentation visuals in keynote so I could play around with them, but it would be great to have a set of images anyone could just start with.

1 Like

OK. Fair warning: my drawing tool is Sketch, and that’s how I plan to do this.

Many many reasons why this tool has become so popular for interaction design.


Sketch seems good. If people wanted to take the assets you produce to make their own documentation, is there a free app that you would recommend that would suffice?

Inkscape is free.

I’ll make SVG exports from my Sketch files that will be usable in Inkscape. You’ll miss quite a few niceties that make things more convenient, but it’ll work.

1 Like

i think defining grid (and arc) interface conventions is a useful exercise, with some exceptions, depending on the goals.

i doubt that it’s feasible to try and follow these conventions for all apps. simply because the restrictions imposed by grid itself tend to make UI much more app specific. a lot of times unique controls are needed both to fit it into 128 LEDs/buttons and to make it intuitive (as a side note, designing a friendly user interface can take more time and planning than writing the actual code).

so, designing with some preselected set of controls is doable but will be probably limiting in practical terms. it might sound contradictory considering the many very different things that were already created with a limited set of grid ops, but grid ops were built with a very specific goal in mind, to allow creating flexible enough UI within limited scripting space that teletype provides. as such they have to pack as much functionality as possible in as few ops as possible. so, say, the fader control is both limited (it works in a set way and can’t be styled much) and flexible (to be efficient for both coarse and fine adjustments). so the approach to designing grid ops was: try to limit the number of controls and their properties, but provide some other ways to style UI (like drawing on top of other controls).

if we talk about norns specifically though, i think it makes total sense to have a library of typical controls. this will help with building apps quickly, especially since it’ll be more natural to define a grid “button” and work with that, instead of writing code for processing grid presses / maintaining button state / rendering. having a predefined set of controls will also help with usability aspect, but again, i think for simple apps that’s fine but for more complex apps they will likely have a very app specific non traditional UI.

as several people mentioned, this really comes down to having documentation. so if there is some way that that could be simplified too i’m all for it! (when documenting orca i did it in power point because it’s surprisingly easy to use for diagrams, but still it’s a very manual process, i’d love some editor that would simplify that).

and having a catalog of different UI elements/approaches for grid would be a cool thing to get ideas for norns/tt/max etc grid apps!


Agree with all that.

One thing that is nice about this process is that it will over time gradually move from the abstract (“what do we mean by ‘a control’?”) to the concrete, as tangible assets start to accumulate. We will spend less time verbally hand waving and more time writing docs! :wink:


Work is in progress. I’d like to do some real work with it before I distribute it. Does anybody have any grid apps that need some documentation? @tehn? @scanner_darkly? Beuhler? Beuhler?

I started to make “rows” but quickly found that any larger abstractions were just cumbersome to work with in Sketch vs. just changing the brightness of individual buttons.


that looks great! wish i had some grid apps that required documenting :slight_smile: but nothing at the moment. might be cool to try it for some of the teletype grid scenes, once i have a chance to make them more sharing-friendly.

i just had a sad realization moment, sketch is mac only, which means i won’t be able to use it unfortunately. is it something that can be ported to some windows app?

Like I said previously, it will export in a variety of formats. But there is no app that works as nicely as Sketch that I’ve found.

SVG in Inkscape is probably the best free approach.

1 Like

This is probably a bit left field for many, and a little offtopic. But the Haskell Diagrams library is great for making diagrams for those who understand Haskell (this statement is somewhat redundant).


Haskell is also really good for making embedded DSLs, an enterprising individual could create one for describing grid apps which could spit out pretty pictures too. I expect there are similar solutions in other languages.

The big advantage of something like this from a documentation point of view (though maybe not a design PoV), is that the script to generate the diagrams can be stored in you Git repo alongside all your other code.


SVG files are text files, and therefore also possible to store in Git.

That being said, we regularly use Git for binaries at work, and I’ve never seen it cause any problems.

It’s more the script part of it I suppose (for me anyway). It would make it very quick to update documentation alongside code changes.

Yeah, if it’s convenient to generate your grid layout programmatically, I can understand wanting to do that. But at design time, I find it easier to directly manipulate objects as a way of thinking through how things should look and feel. If I have to stop and write code, that pulls me away from paying attention to the embodied nature of the experience and forces me back into an abstract and analytical state of mind. I find it useful to switch back and forth between these two perspectives.

1 Like


Personally I prefer pen and paper for design, but even the switch from a keyboard driven experience (coding) to a mouse driven one is enough to kick in the context change for me.

But similarly, if I have to load up Inkscape/Sketch/etc to update some documentation while I’m coding, it’s probably not going to happen.

Now documentation is emphatically not the same as coding, but do you…

  • update the documentation as you go along
  • only update it before release

Which of these you favour (the first for me) will, I suspect, affect the output.

Not only do I completely separate the tasks, I generally prefer that different people do them.

i doubt we could make it fully scriptable, and i agree it’d be just easier to use some external editor. i do like having documentation close to code as a general rule (since devs are not great at updating docs, so whatever makes it easier for them…)

but: it’d be a nice challenge to built something that would parse teletype grid scenes and generate a sketch for it by parsing grid ops (grid visualizer kinda does that with the control preview…). this would make documenting grid scenes much easier. i imagine the same could be done for norns eventually, at least for a shared library of controls.


Self-documenting code is always a noble goal. Would love to see it realized more often!

Now that the discussion is focusing more towards the UX of grid applications, shall I move all the discussion to a new topic, what do you think?
Would be better so this one can stay more generic.

Fine with me. …