How do we keep going wrong?
Roundabouts and APIs.

• Incomplete List of Mistakes in the Design of CSS
• W3C Web Platform Design Principles
• Design System Priority of Constituencies
• CSSWG issue for pem and env(preferred-text-scale)
• W3C TAG review for CSS Masonry Layout syntax

Let's get started. I'm going to talk to you about how do we all go wrong in roundabouts and API design? My name is Josh, I've been working at the BBC for 8 years. I love it. And last time, I also had the privilege to join the CSS working group, which has been amazing. I sit there on the Zoom meetings while more clever people talk about things I don't understand.

And I go, yeah, I don't disagree with that. So I'm so glad I can contribute. We'll learn more on that later, but it has been a massive privilege to be there. Some members of the CSS Working Group here. Put your hands up if you're in the group. Yeah. If you want new features on the web, go up to them and shake them and go, please, give me whatever it is you want and maybe it'll happen.

That's how standards works. It's not really. So, yeah, I've been working on the BBC's Design System for 5 years now, we're going to migrate over it to over the course of this year. It's a weird design system because everyone is contributing to it. Not just core components. There's loads of different components, which means we have a big community and lots of people thinking about API design, which is why it's relevant to our talk today.

I want to be talking about, you know, we care so much about good UX design, but are we thinking about developers when we design our platforms for them? How we can get good developer experience? Because, you know, as devs we use APIs all the time, don't we? They are everywhere. And so many can be work very confusingly, difficult mental models to understand, difficult documentation, because it's really hard to write good documentation, after all.

But when you Google for API design, I always find REST APIs come up specifically. There's never anything about more general principles about any API that you're trying to make, how you can make it simple to use.

So in this talk, our goal is to make sure we can understand ourselves how to create good APIs for good user experience. So obviously, we should talk about roundabouts. This was the UK's very first roundabout. I don't know how old it is. Yeah, whoo! Yeah! Yeah! And but, of course, the modern roundabout that the world knows today was invented in 1966. So there you go.

There's still testing today in the similar situation. And then, of course, we invented the mini roundabout. Mini roundabout, you can squeeze it into smaller places than the normal size, and of course, the magic roundabout, we invented that, too, and that's a load of mini roundabouts together, and everyone gets confused thinking it's one roundabout. And of course where I live down the road in Salford, we invented the first cycling roundabout, which is crap.

And if for some reason you cross into as a pedestrian, the cyclists go over the pedestrian bit, as well. So as you can see, as British people, we have some of the greatest inventions of the world! We have come up with so many wonderful things, except we haven't, have we? They're just crap, aren't they?

We go from, like, we go from things like this to whatever the hell this is on the M62. It's like a roundabout in a roundabout. I'm sorry if you live around there. Down the road from me the old stadium. What is this? It's like -- a road going through the middle of the roundabout and some other thing going on, on the side. I have to drive on that every week. It's horrendous.

And then in London -- here's a local one. So this is -- when a roundabout gets this complex, it's actually called a gyratory. I'm not joking. This roundabout was 8 lanes wide at one point. And it's even got a tube station in the middle of it.

So, as we can see, expanding a system while keeping good user experience is hard. I think we can agree on that. There's always growing pains that drive a space, right? When traffic engineers are trying to add capacity or whatever it is they're trying to do to a junction. There's a traffic light here, an extra lane here, and badly scaled roundabouts. And end up with these short-term solutions to try to solve a problem.

To get extra capacity. But are we asking, how much will this confuse drivers? And do we want the extra vehicles on the roundabout in the first place? Is there an alternative to this? Should we talk about APIs? Let's move on. We're going to talk about how we can -- how APIs can go wrong. What principles can help us to improve our APIs, and then, we'll look at examples of how to apply that.

So yeah, how can it all go wrong? Diving into the BBC's design system. Let's look at an example of one of our components. I was helping a team with this recently where they were trying to add a new icon to the sidebar navigation component. So you can see already, it supports this kind of external link icon, which is great. But they wanted to add this arrow icon to indicate you're about to navigate into a new folder and the navigation will change.

And so they were going to do that by adding this new arrow true property, but there's already an arrow -- there's already an external true property. So, hmm, OK. What have you got to do if there's both, like, external true and arrow true? What do you do in that situation? So the API doesn't really make that clear to you. It's not very clear.

So that's one example of a problem with an API. Except like when you do add some traffic lights to a roundabout and it's not a roundabout anymore. What do we do? That's the way of these traffic lights, then. Unless you're in Manchester.

Not me. And I do risk it more, though, since I moved to Manchester. But what about CSS? Well, it's brilliant -- oh -- oh, they don't want you to know.

[ Laughter ]

Yeah, display. I'll awkwardly stand here, again. Should I unplug it and plug it back in, again? OK. Here we go. Here I come. It's going back in. Oh -- no. Now? Oh, I'm sorry. I've got a new adapter.

I should have just got a new laptop before this week, instead. Hey, thank you so much. That's great. So, let's try that, again. What about CSS? So, they have this amazing hall of shame on the Wiki. Let's have a look at some of them. Born a radius, should have been called corner radius. I knew you'd all appreciate it.

It was a lot of things of this around naming. So box sizing should be border box by default. Yeah, sensible defaults, there's a lot of things like that, as well. RGBA and HSL should have been parameter instead and the upper value should have been used the same format as RGBS. So this one's actually been fixed, you can -- there's now a new syntax for specifying code and it's brilliant and great they've been able to go back and fix this one.

The zed index should be called zed order and just work. It is nice when things just work. The top and bottom margins of a single box should never have been allowed to collapse together automatically. This is the root of all evil! So, yeah, if you know, you know.

And then, finally, table layout should be same. That's my favorite one. Yeah. It's hard to get this stuff right. So, it's a bit like when you try and squeeze extra lanes into this roundabout near Buckinghamshire. I don't know where I was..

I took this a year ago. It's easy to say, isn't it? When we've got our rose-tinted glasses. That's silly, you should have never done it that way. But like, you know, we have to acknowledge as human beings, we can never always make the perfect decision. But we can try to set ourselves up with a good foundation.

So on that note, let's have a look at principles. Number one is to stay hydrated. The second one -- sorry, I forgot about this. The W3C have put together this fantastic document, I recommend you check out, I've got it in the links in the description below. And can you tell this? And -- yeah, it's a great document. They've got loads and loads of suggestions here, things you can think about and how to make a good API.

But this is the most important one, we need to set ourselves a really good foundation. Have you heard about this? The priority of constituencies, user needs come before the web page offers which comes from the user agent mentors and come before the needs of specification writers, which come before theoretical purity. This is so important, this one.

Whenever we're thinking about the tradeoffs of the APIs, the users also come first. We must, you know, we mustn't be tempted to make it easier for ourselves. What's the easiest way I can implement this and try to make the user the API kind of squeeze to make it work for my internal mental model. No, we have to put the user first.

And it was brilliant, actually, when I saw this. It would be great to have something similar for design systems. And this guy called Jason Grigsby had the same idea. And I made a poster. User needs come before the needs of component consumers and before the needs of component developers come before the needs of design team which come before theoretical purity. Thank you very much, David, for that.

We always reference this quite often. What would be your priority of constituencies? I recommend you have something like this. Maybe if you worked in the commercial sector, maybe it's money comes before the need of your boss which comes before the needs of their boss, come before the needs of the user.

Think about what yours could be. Number one is to understand how safe it is for you to fail. What do I mean by that? Well, how much are mistakes locked in when you make them? We are going to make mistakes. How can you change it later? How easy is it to do that? If you're working on a project like mine in a big monorepo where if I change a button, suddenly that's rolled out everywhere, no versioning, then, yes, you can make mistakes as much as you will, you can go through everything and fix the API to something you want.

If it's a library like -- such an easy audience, just say anything bad about React and get a reaction. We use React, as well. Sorry. I'll leave -- but, so, yeah, if you're working on a version library like this, you do have to think about only making major breaking changes when you do a major release. You have to probably follow some send the season to do that. And if you're working on the web platform, you might have heard of HTML 5 and CSS level 3 and 4 and 5 and all of this. But actually, web platform is on version 1.x. We're never in the business of destroying websites made in the 90s. We still want them to work. We can never do breaking changes.

Sometimes, it happens, but generally, no. How easy can you go back and fix things? Other thing to think about is keeping the API surface area small. How powerful is your API? Less control and flexibility you give to user need, the more you're able to change underlying implementation in the future. Does it make sense to let people write arbitrary string of text into a component, for example, when you're only expecting a particular word to be used?

You got to think about all of these kinds of things like how much power do you want to give the user or not. That really affects your flexibility of how you can evolve things in the future. And it's good to good names. Every time we've got to name something, no one' saying let's name this thing. They're saying let's bike shed this.

If you've never heard this phrase before, basically, I can't remember the full analogy, but, you know, it's the idea of all of the architects ever building, I don't know, some big nuclear power station or something like that. They're fafing about designing a bike shed or actually, when we're naming things, it is really important to get a good name. Because this name is going to be used forever. This name is going to stick. It's worth having a good name for people to understand, self-explanatory.

This is called a hamburger roundabout or through about. That's another name for them. Is that a good name? Is that a name? You tell me. Think about how your API will evolve in the future. So, for example, let's say on your platform, you've got a config file and you want to say, let this page support doc mode, you could have doc mode true.

A good thing you can do is actually, when you've got an on/off situation, sometimes an enum can be best. Theme, theme light, or also, if you want to add something in the future, maybe a sepia mode in the future, going back to the 1970s, then you can add another option to the enum. It's a really effective way to do that.

So, yeah, see how you can integrate a new feature before doing something brand new. It's kind of another tip in this area. Look at what's already available in that system you're working on or component or whatever it is.

You know, it is a safe, for example, an enum, before you start thinking about a new property, a new argument, whatever it is. And then, of course, you want it to feel nice and simple to use. She's brilliant, she knows a lot about this stuff. She's adapted this phrase from Alan K, make the simple things easy and the complex things possible. I think it's a great thing to think about.

You know, it's worth going the extra effort to make that feature really simple to use. Even if it means hiding a lot of complexity behind the scenes and you've got to do a lot of work to make that possible. You want that API to be as simple as possible for the user to be able to use.

You know, ask yourself, could I use this API if I had little or no documentation to help me? How self-explanatory is it?

So our team have our own kind of principles and guidelines documented, as well. This one has been like built up over the years, basically, as we've tried to kind of observe key issues that come up and we're doing PR reviews or supporting of the teams. And we'll try to add them to the guidelines as we go along. We often do reference these again and again when helping teams in our design system.

How can we apply these principles? If we apply them well, it's like a lovely roundabout where the lane guidance is really clear, you know what's going on when you go into it. I love a good turbo roundabout.

So, oh, sorry, I forgot to have my obligatory drink between sections. So -- so one thing we can think about, here's a good example. An API that communicates in tense. Let's go back to the arrow icon. What do we do about all of this? So it -- well, that's what we thought the problem could be, we got rid of that external true boolean, and we replaced it with type, what type is this?

Is it a folder? Is it a file? Is it an external link? And depending on that, we can insert the correct icon that's intended. So hopefully, it's a much simpler API for people to use. The next one is an API that makes sense to future proof.

So how can we feature proof for dark mode like we were talking about earlier? Because the BBC website is basically just a load of different cards painted different colors depending where you are, the home page, byte size pages, what have you. We have color tokens if you have design system. You're probably familiar with design tokens. We've got design token where they'll give you whatever color you want. And primarily a light-theme website, but we always wanted to be ready for dark mode.

So when people are specifying what colors they want to use. They're not saying I want the blue color, the green color. They're saying, I want a color that semantically works with this coming use case.

So by doing that, you know, makes it more much possible to go, all right, here's the dark mode color when the time comes and they're going to work. No one has to go in and change their pages to make that work. And in fact, that's what has happened. Already, when we've got a news article embedded in the news native app in the web view that we already do enable dark mode on those pages.

And we're hopefully going to be able to roll that out to the rest of the BBC website later this year. We'll see. So here's another one. An API that balances flexibility with simplicity. So a team wanted to add a kind of new button to the corner of our cards. Except another team came along and wanted to do that at the same time, well enough.

The API that they were proposing for it was, oh, yeah, there you go. Some arrows. It was a bit complex. So it was adding a lot of these very domain-specific kind of properties to this component to enable the functionality. And, you know, we had to think, you know, it was a generic highly used component like this the right place? Very domain-specific logic that can only be used on a few pages, we don't know yet.

So what we did instead was if you're familiar with web components, we borrowed this idea of slots. And instead of people making the component themselves, have the job of generating the menu. We gave them the option, here's a slot, whatever button you want in here and we'll make it your problem, I guess, to have the code somewhere else. It's working effectively, hopefully, so far.

Now, let's have a look at CSS Working Group kind of examples. An API that feels nice to use. This is something I actually proposed last summer. So, coming back to web views. We didn't have a way of respecting the user's font size preference. When they go into the operating system settings and increase the font size, we're finding that, well, there is no real nice way on the Web Platform to just use the user's font size they've set.

So I was proposing a way we could do this. And it was around that time I joined the CSS Working Group, they'd actually discussed this problem back in 2019. And what was proposed was an addition to the metaview port tab. You could say, all right, I acknowledge I'm willing, I thought about the user's accessibility font settings, just make my web page in response, please. A toggle like that. Maybe it would look something like this. It would was said what the syntax would be. And Apple came along, it's OK now. We've just added a button increase the font size on each page. Problem solved.

But then we're like, what about web views? Where there are no controls to do things like that? Or the situations like that. iframes, whatever. So when it got discussed, again, what ended up -- what they ended up landing on in the meeting is the idea of a new environment variable. You might see them yet in CSS. But they're now a thing and it was like, obviously, we should use an environment variable for this, we can get the system font size from there.

And it'd be great. And I was like, well, OK, might be a bit awkward. But I'll take what I can get. And that's great. But then, the CSS Working Group pointed out, well, this was a bit awkward using a media query, which is one of the use cases I wanted it for. Imagine trying to type font size, when it used to be the office could write width in a media query. Not ideal.

So what could we do? And then, back in January this year, so Jen Simmons and us suggested what if we have a new unit for this? Oh, new unit. That's cool. So various names were proposed, user em. But just to give you the percentage of the UI is being scaled, the font size is being scaled.

And then, after back shedding, we've landed on pem units. You might be using this in the future. So preferred em. So linking of the existing language in CSS of preferred stuff. So I thought that was a great idea.

Hopefully, this will come up at the next face-to-face meeting in April to kind of finalize this name. But that's where we've landed on so far.

So you can see there how careful iteration has led to a better API design. So that's really cool. And then, finally, we've got an API that balances new and existing capabilities. So who's excited for layouts? Well, you'll be pleased to know that browsers have actually supported and had the implementation for masonry layouts for years. But we still not nailed the API yet, you've still not got it.

Yeah, it's really not been smooth sailing, unfortunately, but the time needs to be given to get this right. So this is how it started, someone went, oh, this would be cool. You could make, you know, grids work like this and get a Pinterest style layout. And everyone was like, cool, this is great. It was discussed as an issue, the initial syntax was proposed like this. It's like a kind of special mode of grid, really cool.

And well, is it more like -- there were discussions around that. And long story short, there's been a lot of discussions. Back in 2014, 2024, sorry, it feels like 2014, time flies when you get to my age.

So there was disagreement between people at Apple and Google proposing, well, should this be part of grid? Or should it be a new layout paradigm with its own masonry display in it and things like this?

I don't know how many of you are familiar with this debate. How many of you prefer the grid syntax? If you're familiar with this? I can't see because of the projector. OK. Few people. Put your hand up if you prefer having a special masonry syntax for -- oh, OK. I think you will have -- it's quite even which is exactly like in the CSS Working Group, as well. Interesting.

So, absolutely no consensus on this so far. Thank you. No. So, you've got this group of the CSS at the W3C called the TAG technical architecture group. They're brilliant. And the group asked, do you have any kind of input you can give into this debate. Give us review and help us decide what to do? And they came back with this fantastic report that came back with all sorts of things, actually, have you thought about more generally the APIs around layouts in CSS?

Like, on a lot of other things like grid and flex and all of this, having some overlaps, as well, how would you generally make all of these things easier? And it was really helpful. So it ended up that we actually did have more consensus on some sort of grid syntax. But there was still concerns, disagreements. But it did give us a new step forward.

And -- but well, so this is interesting proposal. So we've ended up with a kind of middle ground option here, where taking what TAG suggested. What if we have this new generic syntax for kind of specifying certain aspects of all types of layouts? So, you know, you could say, item direction, row, column, row reverse, column reverse.

Does it wrap? Is it densely packed? How much slack does it have? You can look them up. It's a quite interesting proposal so far and giving us this new idea of how it could work. You could still use the grid properties and tracking things, potentially. The debate's still going on. But, you know, it does feel like we're getting closer to a solution now. And you can imagine, if the -- you know, if the web had a product manager, they would be like, ship something and we'll fix it later. But we can't do that with the web. It's not a commercial product. It's something we love and cherish and it needs to be developed over time.

So as national treasure Jeremy Keith said in his talk about baseline, and you know, things move at different rate. So JavaScript, it doesn't move very quickly and the frameworks and new ideas can come out of it, such as when Pinterest and others created these libraries for masonry, and that's cool, we have to go slow with CSS and carefully think about these things over time. I lost track of my notes.

So, I need to stop going ad lib. You know, CSS needs to evolve more slowly to continue to be right for everyone, basically.

So, that's it. Keep practicing good API design. The more you do it, the better it will get, and then, soon you'll be making your own giant survey roundabouts. So thank you very much.

Transcript by Diane (in Iowa) from White Coat Captioning