 I hope you can hear me fine. I've just a normal microphone because I forgot about pockets so Yeah, welcome to our talk about amber between design and development my name is Lisa and I'm a user interface designer and My passion is like visual design in general, but I also love to bring to life my designs with HTML and CSS This is Francesco. He's my co-worker and our JavaScript developer And he really loves to write clean and efficient code But even more than this he loves to create apps which users really can and want to use So usually we are from Austria from the lovely city of Innsbruck But currently we are on an extended business trip in America to get to know our customers and to conduct some user research So we are working for the company crop sir It is a relatively small company which is based based in Austria and Sacramento And we create all two tools for coffee traders and farmers, but especially coffee roasters so Just recently we launched a new ember best product, which is called crop sir hub It is an online green coffee trading platform and also an auctioning platform and it's totally made out of ember And we are also recently redoing our whole inventory management system for coffee with ember so Why are we holding this talk today? We have been now working together over three years over on multiple ember apps And we've just come to realize how important it is that you have a good collaboration between the off-the-posting groups of designers and developers We have learned that you can save so much time on existing project projects But also new projects when you have like really a good collaboration and documentation So we want to show you today why collaboration is so important Why designers should be able to code and why developers should be able to understand design How documentation can you help within your collaboration process and which documentation we use in our ember apps Which is the code documentation a living style guide and a component guide Hi, so first of all why is collaboration so important think about the engineering of a car So max designs a nice vehicle body for a city car. It's nice and green and he's very happy with it at the same time and Develops tires which are perfect for rough roads She also put a lot of work into it and she's equally happy with the outcome But when the time comes and they put those parts together it doesn't work at all So both did a good job on their own, but they just didn't have the same understanding of the new car They didn't collaborate well enough So how can we apply this to our own industry? Many companies have had a workflow like this for a long time So the designer creates a photoshop design Let's say site design dot PSD hands it to the developer who then implements it with HTML CSS and JavaScript And many companies have been quite successful with this approach. So why should you care to mix it up? Well, in reality the workflow doesn't stop here. So there will be the time When the designer needs to do a few changes to the design so they might create a second Photoshop file site design final dot PSD Hand it to the developer who has to go through the file find the changes and implement them in code But then there will be another round of changes and another And another and another run of changes in the end Everyone wasted a lot of time because the designer had to go through the developer for every little change and Everyone will be unhappy So this might have been a bit exaggerated, but I'm pretty sure many of you have experienced something close to this before So let's imagine a better workflow This better workflow might still start out with the designer creating a static design before the shop but then the designer also writes a basic HTML templates and this CSS and hence all of this over to the developer who then implements the static HTML templates with handlebars and talking about ember and writes a JavaScript logic for it and When a time comes and they have to do some adaptions They can work on it together So it's really just a static design that is the sole responsibility of the designer and JavaScript app code that is the sole responsibility of the developer everything else is shared all iterations are made in code the designer Can do especially smaller changes on their own without bothering the developers and Everyone is happy So of course we know that this kind of workflow requires designers like myself to write valid and meaningful HTML and CSS But we think that this is really important because when you're able to write valid and meaningful HTML and CSS as designer it is Not that easily possible that you create a design which is really hard or impossible to implement so Regarding ember apps we of course also proposed to the designers able to write handlebar templates and Yes, I know when you start to code as designer you sometimes feel not that confident about it, but But in reality when you have a basic understanding of HTML learning handlebars is not that hard I don't say that you have to create Components by yourself or the routes it's great when you can do it but to start out for a designer It's just like you have to go into it and just try to don't mess things up there Develop already made to work. So when you go in here and as designer I want to change something in the styling of the info message I just have to know where to put an additional class I just have to know that that I put the additional class not within the if expression or Another example where you see this unordered list and with the each loop their list elements get generated So as I as designers just have to know when I want to change something I just do it within the each loop so I don't break something So the most important thing about that is don't try to be afraid just try it out and believe me The developer is really happy to help you out when you don't know something So I know sometimes in some project It's it's not possible that the designer can also like do the whole HTML CSS code Or the handlebars template, but still it is really important that the science specifications are really clear So let's just take a simple example. Let's just take a button Designers and yes, I include myself Sometimes complain about you know the developers. They are not able to implement this my design in a way I wanted it to be but have you ever thought about that? Designers do not deliver the designs in a way a developer can really work with it So let's say the button you get a static Photoshop file as developer You will just implement it that way But has the designer also thought about what happens in between those two states So it would be a good beginning if the designer hand this over and say something like, you know The button should have a transition between all those states because an application, of course It's a dynamic application It would be even better if the designer hand this over and say something like, you know The button should have transition on the background color color and the box shadow with our trend Standard transition time which is 0.3 seconds and then isn't in our transition And it would be the best if you could just hand over the sss for that So as long as we're not able to read minds It is really important to designers to live as design specifications in a way a developer can work with it so while we do believe that Designers can be expected to know a bit about html and css. We shouldn't forget the flip side of this We are also strongly believe that we developers can be expected to care about Design to analyze it beyond the obvious and to care about its execution So of course, I do not expect developers to become the designers. I know that I could never actually design an application But I do think that we can do better than we often do So when we receive a design from a designer Don't just we could try to recreate it one-to-one ask yourself. Does the design actually make any sense and Is it consistent to other pages or components you implemented before? So chances are the designer did a conscious decision in Deviating from another component they designed before but maybe they just overlooked something it happens We're all human beings. So talk to the designer In my experience no designer I've worked with so far Has had a problem with explaining their choices to me if I talk to them in a constructive and nice way So don't go to the designer and say hey this looks really bad or it doesn't work at all Try to give a concrete example of what the problem is and maybe even a possible solution for a problem Another thing I want to add is that many developers don't care that much about CSS But CSS is not the trivial So I don't know how many of you have felt something like this when writing CSS I know that I have felt like this a lot of times So this is not the trivial but CSS quality is important So there are many developers who would spend hours trying to optimize a JavaScript class But it would then be quick to just throw in a couple of inline styles on a button because why not it works But it doesn't really work when the time comes and you have to make changes to the UI and the time will come Then this will be very hard to maintain So don't use inline styles and use some kind of consistent naming scheme for your CSS So for this purpose in our project we use BAM which is short for block element modifier I don't want to go into this in any detail. You don't need to use BAM You can use another naming convention. You can come up with your own naming convention It doesn't really matter just have a naming convention and get everyone in your team on board to actually using it The last thing I want to mention is that the data model does not equal the user interface So we developers should not build an application in a way that it makes sense to us We should build an application in a way that it makes sense to the user and just because we might use terms like Items in the app code. It doesn't mean that we should also use these terms in the user interface So now as we have complained enough about the signers and developers We want to talk about how documentation can help you to establish an integrated workflow and the shared vocabulary So why should you do why should you care about documentation at all? The first thing is it's all about consistency Once users know what a specific UI element does in your application They expect the same UI element to do the exact same thing over and over again And if the your element doesn't do that the users gets frustrated and that's bad so The another thing is you get really Faster and it's easier to do cross-browser testing because when you have like a style guide or a component guide You can't just use that guide in any browser or on any device and test the your elements You don't have to go from page to page and test everything and when you have something like an centralized hub for your documentation everyone can go to and You have a faster workflow Chris mentioned it yesterday in his talk about living style guides He said it's really easy that you get new developers or new designers To help them onboarding and that's that's really true. So everyone in your team gets faster You know my thing. Okay, that all sounds very good. But how can I do some kind of documentation in my company? So the most important thing you should remember from this talk is When you do documentation and yes, you should do it You should do it always like integrated in your project. What does that mean? It means your documentation should be always hundred percent in sync with your code piece So that you don't stop doing it. But thanks to emba CLI. This is relatively easy So the first piece of documentation we use is code documentation So I'm guessing or I'm hoping that most all of you use some kind of code documentation in your projects So what we want to add there is that we also feel it's very helpful to have a standalone human readable code Documentation outside of your app source codes command. So for this purpose, we use you a doc, which you might have heard of Basically, it creates a nice documentation from Java doc style comments in your app So this is what this looks like for one of our projects We've made our own seam for it, which is pretty easy to do So on the left pane, you see all the classes we have We can select one class and then you see all the details on the right pane if this appears somewhat familiar to you That's probably because the ember.js API docs also use your doc So it works very well with ember apps. It's not tied at all to ember You can use it with any JavaScript based project There is an add-on ember CLI UI doc which you can use or you can just use the standalone node version for this It's pretty easy to use You just add comments like this on top of your JavaScript files So we just put there a very short description of what the file does if it's a component We like to add a short code snippet of how you would use this component and then we just Define a namespace which would be their object type Component service, etc. Then the class name and what it extends from Then in the class we just document all the Different things in there. So we would document attributes with that attribute and the type We would document methods with that method. You can specify parameters for methods and return values and Actions we document them with at event which is nice because events can also take Parameters and they show up nicely in a different section in a generated documentation So the really nice thing about this is that it's not only useful for developers It can also be used by designers. So for example if a designer is working with a handlebars template They can use this documentation to find out which properties are available on a model or on a Component to actually use in the template and while most develop designers will probably not feel Comfortable diving into the app source code to find out which properties are available Going to this documentation and looking it up there. It's pretty straightforward So let's talk about the living staggered Chris had to talk about the living staggered yesterday We use it a little bit different for us living staggered is a documentation of our CSS classes how they will look like and how you can use them So basically it's called living because it is auto generated from our apps CSS CSS or less depends what you use So why are we like doing the living staggered at all as mentioned before consistency is really important and You only realize how important consistency is if you look at inconsistent examples So when I started with redesigning one of our older applications, I started out within so-called UI inventory That means you go into an in in into an existing application Look for a specific UI element and make just a screenshot of it And every time you see the UI element which does the exact same thing you just make another screenshot So that's what I found when I looked just for a normal button with the same action on it So as you can see we have a lot of different button stylings here But like behind it every one of those buttons does exactly the same thing Why does this happen this happens because a lot of people are working on the same project but without a shared style guide so The next step I do when I create a new application or redesigning existing one I create just a design sheet So basically it is an outline in which the design direction goes it includes like a color theme The basic UI elements some icons and some other things But it's really simple and I take this design sheet and go to the developer and to the project owner and talk about it They give me some feedback on it I iterate over it and then the next step is that I directly implement all those your basic UI elements in our living staggered So how do we do that? We use in our amber projects broccoli living staggered We use that it on because it is especially made for sess and we use sess so as CSS in our projects Then we make some basic configurations there for example like How the staggered should look like or and how the code formatting within the staggered should be and Then I can just start create Susparsals and corresponding markdown files with the same name and then I can serve our living staggered with Amber serve and every time when we change something in one of our markdown files or one of our sus Partials the whole style get gets reloaded. So we make sure to the staggered So basically ember make sure that our staggered is always up to date Then you can just start styling so when everything is set up I create my first a CSS partial which is usually something like button s CSS and I put all the main CSS in it I always then style just a plain tag as well because you should keep it as easy as simple as possible But I also add on another class like dot button when I want to have like a link look like a button And I also put all other modifier classes in it for example button secondary which just changes the color of the button When I'm finished with that I Just add a corresponding markdown file, which is called underscore button MD Which has just all the HTML markup in it and some description if I wanted to be and then Everything gets reloaded and automatically built and the outcome as you can see is Like you see all your elements and the HTML markup and you can just go in and copy and paste the stuff So this is how our file structure in general look like we have this core folder where we put all our Corstals in which means those are things which we which we change from project to project like variables or our theme or our Layout and then we have a lot of files in our modules. Those are things. We've learned we can use from project to project and are very similar So like for example like basic box stylings or charge stylings or whatever They just depend on some variables, but we change the variables from project to project and then we also use like We put also some of our styles directly in our component folders So we can use the amber components from one project to another And another thing we realized while we do a lot of amber projects Oh wait, this is how actually this I get looks like so when it is rendered You can see we also build it in in our Documentation app we added on and navigation so you can jump from one part to another You can see which color variables we use How you can use input forms how our buttons will look like and the cool thing is those are like really the real UI elements so you can just try it out hover over them like get a feeling how they will look like in the real app So and as we work on several amber projects We found out that all some of our amber projects have the same styling So we decided to make a shared it on this shared it on contains all our general styling informations and Then all our other amber projects just use this add-on So how do we do that now workflow? We just said there is developing add-on to return true in our add-ons index.js file And then we create a local copy of our add-on in our amber project and Run this project with amber surf so every time when we change something in our add-ons CSS Also our project our other amber project we work on gets reloaded, which is like really helpful during development So the final piece of documentation we use is the component guide Which is somewhere in between the living style guide and the code documentation So Chris in his talk yesterday about living style guide What he calls living style style guide is what we call a component guide basically so it shows amber components in action How they look like how they can be used? So it's aimed at anyone that works with templates. So in our case both designers and developers And as such is important to not become too techy when describing stuff So it's only really important What a component does and not how it does something? This is what this looks like in our project So this would be the section for form element. For example, we have a C button component And you can see I hope you can see and there's a list of attributes With a type and a short description that you can use for this component Then you actually see the component and the code snippet which shows how you can use the component So right now we don't use any special tools for this This is basically a route in an ember app with the component in it and the description But we might switch to ember freestyle now after Chris talk yesterday that was really impressive and nice So the way we did it now is That we created a very simple component that doesn't do anything fancy. The only thing it does is Make sure that we have a somewhat unified layout for component guide So we put a lot of those in our component guide route For basically every one of our components Each one so on top you would just define how the component is named Then we would define all the attributes that this component can take and with a name and a type and a description Then and this is actually the most important part. We would include the live component So you might think that you could just go ahead and copy paste the HTML output of your component from somewhere in your app And put it in here But that is not a very good idea because it will get outdated When you change something in your component, so really try to include your actual components in here If you're having trouble doing this, that's probably a sign that your components are too tightly coupled to something else Which is something you should avoid anyhow so actually building a component guide like this is also a good way to Find out if you build your components in a reusable and encapsulated way and then finally we have a code block Which is basically the same as the demo block just escape the hand the component So it is not rendered and then we add some syntax highlighting to it So on smaller projects we basically add a route or a collection of routes just in our app Where we put this component guide on This works very well, and it's pretty easy to do However, it has the disadvantage that this will also be served with your app if you deploy it Which is something you might not want so this is something you need to handle in this case So what we do is only locked in administrators, which is us basically can access this routes once we deployed it For bigger projects Lisa mentioned it before we have a couple of internal embed ons that we use And where we have all our styling but also all our reusable components that we use in multiple apps So basically most of our components are in Multiple at ons so we have a separate standalone documentation and that which also includes all these at ons and This documentation ember app is our component guide So this is completely separate from our user-facing apps so it can never be deployed by accident We have set it up in a way that whenever one of that arms changes and we push it to get our build server We'll rebuild the documentation app put it onto our internal server So everyone in the team can look at it, and it's always up to date which is super helpful we also put the living style guide in this documentation app and Your documentation so this is our central hub of documentation for all our ember projects which works really well for us So if you take something out of this talk, it should really be Try to understand your teammate Teammates this could only work if you really sit together open-minded And if the developers try to get a little bit involved in the design process and the designers try to get involved in the Development process and if we find together a way Which works for everyone and the most important thing you should remember here is when you do documentation and Again, you should do documentation Keep it always 100% percent in sync with your code base because when you decide to do a standalone Documentation app trust me there's there's a time when you just stop doing it because you just have no time or you just forget about it and The last point I want to mention is always try to be better Try to reiterate about your work over your workflow and and improve it so even after this talk We would probably go home and Improve our workflow. We have hundreds hundreds of ideas collected here So I would love to come back to the example from the beginning Just imagine if max the designer of the vehicle buddy would have been sit together with and in the beginning And if they would have sketched out a framework in which the car should work Just let's say a city the outcome would have been a completely different car. It would have been a perfect one Thank you So the question was how much time we spent on keeping it up to date the style guide Yeah so It's not too bad if you start doing it from the beginning It's probably pretty hard if you try to tack it on later. So as Lisa mentioned we basically Start coding in the style guide and then we do changes in the style guide and then we look in the app How they look there something like this. So we always do all the changes in the style guide first more or less So that's not really an issue for us So it's like I just can give a quick example like last week one of our developers asked me He needed an input with a dynamic label because we just had an input where you can put like a dollar sign or something But not like a whole word and he said he would need one with a dynamic label So what we did we just like improve the existing one in our style guide and then like he used this one for all other things So we always want to have like the one perfect UI component and we just really do it right in our style guides So then it's not that much work I can just like answer like the first step I come from the client side so I before I work just like a freelancer and that is a lot of design projects and I have to say like I switched over to like creating a design sheet first and just like Implementing right now in the style guide so not always with ember of course But I did it before just like standalone style guides with KSS for example and the outcome was pretty cool because Sometimes when you're like a designer You discuss about things which are like not that important like the color of the green or like something a positioning of something Which is not an important and when you start out just with a design sheet and then like directly implemented within a style guide There is no such discussion about like how exactly you put things you can really focus on improving your UI elements So I actually I think it works pretty good in an agency agency wise as well also a thing I want to add here is that this will something like this will probably It will be worth it a year from now basically So when a year from now the client comes back and wants to do some changes and maybe there are new developers Who will work on this project who haven't worked on it before so they have basically no idea what you did now? If they have something like a style guide they can go there and work from there if they don't have something like this it's basically Do whatever you think is best and this is something you can really help with when you have a style guide It just can say as designer in general when you want it to be a user interface designer You have to be able to code. It's it's not a limitation. It's like an extension of your skills It's just the example I gave in the beginning When I make a user interface, I really have to think about animations and transitions and not only like the static button So I think you have to learn code You