giving querio a facelift

mariia and i are constantly sharing apps / screens / shots with each other, 'yoo look how cool this is', we've also had a few meetings where we'll be using an app and noticing how good the ux is (elevenlabs for mariia and zed for me), but we then end up asking ourselves why these apps feel so good to use and how we can bring that feeling to querio.

since we introduced our updated design system - we have undoubtedly become quicker drawing up new screens, as a team - both from an engineering perspective as well as the design side. unsurprisingly, there has been some drift between the two systems - design tokens have changed slightly and the changes haven't been reflected in the codebase, but also, and crucially, element sizing and typography has been pretty inconsistent.

not only is consistency such a huge thing for gaining user's trust - particularly in our industry where we're directly handling user's company data, we need to ensure that users don't fall into despair trying to understand how to work our ui.

tightening the screws

this ui botox cycle has had me and mariia at each other's necks trying to wrestle figma screens into something we vibe with. we sat down and worked through exactly how the type scale should look and how that should relate to our design system components and their variations. we don't claim to have gotten this right, and it reminds me of a point i keep making to mariia during the middle of these meetings

i just don't understand how linear have such a tight app experience - what specifically about it makes it feel that way???

and so, we sat down with our plethora of linear screenshots (along with some from other apps we like) and drew directly on figjam what specifically about the design made it feel so polished. at this stage we just identified the 'whats' as opposed to understanding the 'whys'. not only was this a really useful exercise, but we started to identify the patterns behind some of these designs and how they've been replicated across different parts of their application.

ok, so now that we better understand the whats, now for the whys.

honestly, we're still in the midst of figuring this out. we're reading through books like 'refactoring ui' by the tailwind guys trying to better understand exactly why what we're changing is making such a beneficial impact, but the truth is a lot of our design process right now is fuelled by taste and feeling. this might be a bad thing, i don't know, but so long as it ties together our experience, even if incrementally, we think it's worth it. the pursuit of understanding exactly the reasons behind our decisions is still very much something we're working towards, but we're making a deliberate effort here to learn by doing, and i think we're reaping some rewards.

so how exactly have we made meaningful change to the app?

moving to materials

you might remember from the last post we released on our new design system, that we'd moved away from horribly named tailwind classes such as the classic bg-background-grey-very-light-2 to semantic names like bg-background-lvl-1 or bg-background-canvas, while this was an improvement we found that there are a lot of states which still get unaccounted for here, such as hover, pressed, disabled, etc.

we could've created semantic classes for all of them, but we wanted to restrict the number of options to limit confusion from a dx perspective. with that, we decided to move towards a 'material' approach, whereby we define classes like the following bg-background-n1 - this means 'negative 1', which is essentially just #0A0A0A0D.

why is this so nice? because it means we can hot-swap base level colours, like our slate colour or anything else for that matter, but our buttons and interactive elements will still work fine.

similarly, positive classes also exist to elevate surfaces, bg-background-p1. the reasons behind this move:

1. it massively simplifies our colour range for interactive components and components which consistently follow the same elevation / depression pattern
2. it reduces confusion from a development perspective, we can quickly decide which elevation / depression to pick for an element based on context
3. we've opened the door to customisable themes and our long awaited dark mode..

from a user perspective, you'll now notice less variation between different components and elements with the intention of providing a cleaner experience that feels more tightly wound.

size does matter

tidying up sizing across the app has been on the todo list for some time and now that it's beginning to take shape, it's become clear that we should've done this a long time ago.

i'll put my hands up and be the first to admit that i have a tendency to design things that are quite small (much to mariia's disgust). as a result, the implementation of previous designs has been... on the smaller side. this also came down to the fact that our scale just wasn't perfect in some cases and left for some ambiguity.

so what we've done is unified all of our design system components to conform to this new size scale. part of this change also meant us defining what we want the relationship between text and element size to look like.

normally, you'd expect it to look something like this

button (large) -> text-lg

button (medium) -> text-md

button (small) -> text-sm

but what we found is large buttons would rarely, if ever, be used because the text was far too cramped in its container - and just felt out of place across the app. so, we've opted for a more consistent scale, delegating hierarchy predominantly to the size of the element as opposed to the text size.

not only does this feel more consistent, but also creates better visual harmony across the app

and with that, we've bumped up all of our components to default to the 'medium' size across most places (we're still working on refreshing some areas of the product), as opposed to the old 'small' default.

bridging the gap between Figma and code

as mentioned earlier, we found there would often be drift between our design system variables in figma and our codebase, this could be tokens changing values, the addition / deletion / renaming of existing tokens. this would make it particularly annoying especially when moving from figma design to code via mcp or even manual implementation, tokens that weren't present in the codebase would just be hard coded for that specific screen / element. annoying. as. hell.

the beautiful thing about claude code is how it's essentially just unlocked doors for extending software to fit niche / obscure needs that we have as a company, i will talk more on this in a later post. in this case, our design tokens kept drifting and we needed a way to keep them up to date.

introducing, querio token sync - our custom figma plugin.

before you say it, yeah yeah i know this exists already - but why pay for some off the shelf software when we can cook it up ourselves?

this plugin allows mariia to make changes to our figma variables and sync them to querio - opening up a PR on our repo. it works by requesting a fine grained access token from github and making a change on your behalf. the changes get put into a central figma tokens file, in DTCG format, which is then picked up in our build script which builds up the tokens and converts them into CSS variables. we opted to use amazon's style dictionary for this transformation - it's quick and simple and has worked a treat so far.

it's early days for this plugin, but i expect we'll find its feature set will expand as time goes on and as we find more useful quirks we can plug into it.

introducing chat mode

we'd also like to take a quick moment to introduce chat mode, a simpler, more intuitive way to interact with the querio agent.

ultimately the goal here is to strip back some of the complexities of the hybrid mode, the notion of 'cells' and really make it clear that underneath every explore session is simply a conversation and a bag of some outputs. both of these modes are completely interchangeable, so if you start a conversation in chat mode, you can still switch to hybrid at any time and make changes to the underlying notebook if you wish!

one key thing you'll notice is that our changes to sizing, colours and layout have persisted across here too - we're leaning heavily into this new design language and we hope you find it delightful to use.

next up we have a few new exciting features in the pipe and of course dark mode... in the meantime, myself and mariia are going to get to cleaning up some of the smaller screens across the app.

— msh