{"rowid": 265, "title": "Designing for Perfection", "contents": "Hello, 24 ways readers. I hope you\u2019re having a nice run up to Christmas. This holiday season I thought I\u2019d share a few things with you that have been particularly meaningful in my work over the last year or so. They may not make you wet your santa pants with new-idea-excitement, but in the context of 24 ways I think they may serve as a nice lesson and a useful seasonal reminder going into the New Year. Enjoy!\n\nStory\n\nDespite being a largely scruffy individual for most of my life, I had some interesting experiences regarding kitchen tidiness during my third year at university. \n\nAs a kid, my room had always been pretty tidy, and as a teenager I used to enjoy reordering my CDs regularly (by artist, label, colour of spine \u2013 you get the picture); but by the time I was twenty I\u2019d left most of these traits behind me, mainly due to a fear that I was turning into my mother. The one remaining anally retentive part of me that remained however, lived in the kitchen. For some reason, I couldn\u2019t let all the pots and crockery be strewn across the surfaces after cooking. I didn\u2019t care if they were washed up or not, I just needed them tidied. The surfaces needed to be continually free of grated cheese, breadcrumbs and ketchup spills. Also, the sink always needed to be clear. Always. Even a lone teabag, discarded casually into the sink hours previously, would give me what I used to refer to as \u201ckitchen rage\u201d.\n\nWhilst this behaviour didn\u2019t cause any direct conflicts, it did often create weirdness. We would be happily enjoying a few pre-night out beverages (Jack Daniels and Red Bull \u2013 nice) when I\u2019d notice the state of the kitchen following our round of customized 49p Tesco pizzas. Kitchen rage would ensue, and I\u2019d have to blitz the kitchen, which usually resulted in me having to catch everyone up at the bar afterwards.\n\nOne evening as we were just about to go out, I was stood there, in front of the shithole that was our kitchen with the intention of cleaning it all up, when a realization popped into my head. In hindsight, it was a pretty obvious one, but it went along the lines of \u201cWhat the fuck are you doing? Sort your life out\u201d. I sodded the washing up, rolled out with my friends, and had a badass evening of partying.\n\nAfter this point, whenever I got the urge to clean the kitchen, I repeated that same realization in my head. My tidy kitchen obsession strived for a level of perfection that my housemates just didn\u2019t share, so it was ultimately pointless. It didn\u2019t make me feel that good, either; it was like having a cigarette after months of restraint \u2013 initially joyous but soon slightly shameful.\n\nLesson\n\nNow, around seven years later, I\u2019m a designer on the web and my life is chaotic. It features no planning for significant events, no day-to-day routine or structure, no thought about anything remotely long-term, and I like to think I do precisely what I want. It seems my days at striving for something ordered and tidy, in most parts of my life, are long gone.\n\nFor much of my time as a designer, though, it\u2019s been a different story. I relished industry-standard terms such as \u2018pixel perfection\u2019 and \u2018polished PSDs\u2019, taking them into my stride as I strove to design everything that was put on my plate perfectly. Even down to grids and guidelines, all design elements would be painstakingly aligned to a five-pixel grid. There were no seven-pixel margins or gutters to be found in my design work, that\u2019s for sure. I put too much pride and, inadvertently, too much ego into my work. Things took too long to create, and because of the amount of effort put into the work, significant changes, based on client feedback for example, were more difficult to stomach.\n\nOver the last eighteen months I\u2019ve made a conscious effort to change the way I approach designing for the web. Working on applications has probably helped with this; they seem to have a more organic development than rigid content-based websites. Mostly though, a realization similar to my kitchen rage one came about when I had to make significant changes to a painstakingly crafted Photoshop document I had created. The changes shouldn\u2019t have been difficult or time-consuming to implement, but they were turning out to be. One day, frustrated with how long it was taking, the refrain \u201cWhat the fuck are you doing? Sort your life out\u201d again entered my head. I blazed the rest of the work, not rushing or doing scruffy work, but just not adhering to the insane levels of perfection I had previously set for myself. When the changes were presented, everything went down swimmingly. The client in this case (and I\u2019d argue most cases) cared more about the ideas than the perfect way in which they had been implemented. I had taken myself and my ego out of the creative side of the work, and it had been easier to succeed.\n\nArgument\n\nI know many other designers who work on the web share such aspirations to perfection. I think it\u2019s a common part of the designer DNA, but I\u2019m not sure it really has a place when designing for the web.\n\nFirst, there\u2019s the environment. The landscape in which we work is continually shifting and evolving. The inherent imperfection of the medium itself makes attempts to create perfect work for it redundant. Whether you consider it a positive or negative point, the products we make are never complete. They\u2019re always scaling and changing. \n\nLike many aspects of web design, this striving for perfection in our design work is a way of thinking borrowed from other design industries where it\u2019s more suited. A physical product cannot be as easily altered or developed after it has been manufactured, so the need to achieve perfection when designing is more apt.\n\nDesigners who can relate to anything I\u2019ve talked about can easily let go of that anal retentiveness if given the right reasons to do so. Striving for perfection isn\u2019t a bad thing, but I simply don\u2019t think it can be achieved in such a fast-moving, unique industry. I think design for the web works better when it begins with quick and simple, followed by iteration and polish over time. \n\nTo let go of ego and to publish something that you\u2019re not completely happy with is perhaps the most difficult part of the job for designers like us, but it\u2019s followed by a satisfaction of knowing your product is alive and breathing, whereas others (possibly even competitors) may still be sitting in Photoshop, agonizing over whether a margin should be twenty or forty pixels.\n\nI keep telling myself to stop sitting on those two hundred ideas that are all half-finished. Publish them, clean them up and iterate over time. I\u2019ve been telling myself this for months and, hopefully, writing this article will give me the kick in the arse I need. Hopefully, it will also give someone else the same kick.", "year": "2011", "author": "Greg Wood", "author_slug": "gregwood", "published": "2011-12-17T00:00:00+00:00", "url": "https://24ways.org/2011/designing-for-perfection/", "topic": "process"} {"rowid": 272, "title": "Crafting the Front-end", "contents": "Much has been spoken and written recently about the virtues of craftsmanship in the context of web design and development. It seems that we as fabricators of the web are finally tiring of seeking out parallels between ourselves and architects, and are turning instead to the fabled specialist artisans.\n\nIdentifying oneself as a craftsman or craftswoman (let\u2019s just say craftsperson from here onward) will likely be a trend of early 2012. In this pre-emptive strike, I\u2019d like to expound on this movement as I feel it pertains to front-end development, and encourage care and understanding of the true qualities of craftsmanship (craftspersonship).\n\nThe core values\n\nI\u2019ll begin by defining craftspersonship. What distinguishes a craftsperson from a technician? Dictionaries tend to define a craftsperson as one who possesses great skill in a chosen field. The badge of a craftsperson for me, though, is a very special label that should be revered and used sparingly, only where it is truly deserved. A genuine craftsperson encompasses a few other key traits, far beyond raw skill, each of which must be learned and mastered.\n\nA craftsperson has: \n\n\n\tAn appreciation of good work, in both the work of others and their own. And not just good as in \u2018hey, that\u2019s pretty neat\u2019, I mean a goodness like a shining purity \u2013 the kind of good that feels right when you see it.\n\tA belief in quality at every level: every facet of the craftsperson\u2019s product is as crucial as any other, without exception, even those normally hidden from view.\n\tVision: an ability to visualize their path ahead, pre-empting the obstacles that may be encountered to plan a route around them.\n\tA preference for simplicity: an almost Bauhausesque devotion to undecorated functionality, with no unjustifiable parts included.\n\tSincerity: producing work that speaks directly to its purpose with flawless clarity.\n\n\nOnly when you become a custodian of such values in your work can you consider calling yourself a craftsperson. Now let\u2019s take a look at some steps we front-end developers can take on our journey of enlightenment toward craftspersonhood.\n\n Speaking of the craftsman\u2019s journey, be sure to watch out for the video of The Standardistas\u2019 stellar talk at the Build 2011 conference titled The Journey, which should be online sometime soon.\n\nBuilding your own toolbox\n\nMy grandfather was a carpenter and trained as a young apprentice under a master. After observing and practising the many foundation theories, principles and techniques of carpentry, he was tasked with creating his own set of woodworking tools, which he would use and maintain throughout his career. By going through the process of having to create his own tools, he would be connected at the most direct level with every piece of wood he touched, his tools being his own creations and extensions of his own skilled hands. The depth of his knowledge of these tools must have surpassed the intricate as he fathered, used, cleaned and repaired them, day in and day out over many years.\n\nAnd so it should be, ideally, with all crafts. We must understand our tools right down to the most fundamental level. I firmly believe that a level of true craftsmanship cannot be reached while there exists a layer that remains not wholly understood between a creator and his canvas. Of course, our tools as front-end developers are somewhat more complex than those of other crafts \u2013 it may seem reasonable to require that a carpenter create his or her own set of chisels, but somewhat less so to ask a front-end developer to code their own CSS preprocessor, or design their own computer.\n\nHowever, it is still vitally important that you understand how your tools work. This is particularly critical when it comes to things like preprocessors, libraries and frameworks which aim to save you time by automating common processes and functions. For the most part, anything that saves you time is a Good Thing\u2122 but it cannot be stressed enough that using tools like these in earnest should be avoided until you understand exactly what they are doing for you (and, to an extent, how they are doing it). \n\nIn particular, you must understand any drawbacks to using your tools, and any shortcuts they may be taking on your behalf. I\u2019m not suggesting that you steer clear of paid work until you\u2019ve studied each of jQuery\u2019s 9,266 lines of JavaScript source code but, all levity aside, it will further you on your journey to look at interesting or relevant bits of jQuery, and any other libraries you might want to use. Such libraries often directly link to corresponding sections of their source code on sites like GitHub from their official documentation. Better yet, they\u2019re almost always written in high level languages (easy to read), so there\u2019s no excuse not to don your pith helmet and go on something of an exploration. Any kind of tangential learning like this will drive you further toward becoming a true craftsperson, so keep an open mind and always be ready to step out of your comfort zone.\n\nDowntime and tool honing\n\nWith any craft, it is essential to keep your tools in good condition, and a good idea to stay up-to-date with the latest equipment. This is especially true on the web, which, as we like to tell anyone who is still awake more than a minute after asking what it is that we do, advances at a phenomenal pace. A tool or technique that could be considered best practice this week might be the subject of haughty derision in a comment thread within six months.\n\nI have little doubt that you already spend a chunk of time each day keeping up with the latest material from our industry\u2019s finest Interblogs and Twittertubes, but do you honestly put aside time to collect bookmarks and code snippets from things you read into a slowly evolving toolbox? At @media in 2009, Simon Collison delivered a candid talk on his \u2018Ultimate Package\u2019. Those of us who didn\u2019t flee the room anticipating a newfound and unwelcome intimacy with the contents of his trousers were shown how he maintained his own toolkit \u2013 a collection of files and folders all set up and ready to go for a new project. By maintaining a toolkit in this way, he has consistency across projects and a dependable base upon which to learn and improve.\n\nThe assembly and maintenance of such a personalized and familiar toolkit is probably as close as we will get to emulating the tool making stage of more traditional craft trades. Keep a master copy of your toolkit somewhere safe, making copies of it for new projects. When you learn of a way in which part of it can be improved, make changes to the master copy.\n\nSimplicity through modularity\n\nI believe that the user interfaces of all web applications should be thought of as being made up primarily of modular components. Modules in this context are patterns in design that appear repeatedly throughout the app. These can be small collections of elements, like a user profile summary box (profile picture, username, meta data), as well as atomic elements such as headings and list items.\n\nWell-crafted front-end architectures have the ability to support this kind of repeating pattern as modules, with as close to no repetition of CSS (or JavaScript) as possible, and as close to no variations in HTML between instances as possible.\n\nOne of the most fundamental and well known tenets of software engineering is the DRY rule \u2013 don\u2019t repeat yourself. It requires that \u201cevery piece of knowledge must have a single, unambiguous, authoritative representation within a system.\u201d \n\nAs craftspeople, we must hold this rule dear and apply it to the modules we have identified in our site designs. The moment you commit a second style definition for a module, the quality of your output (the front-end code) takes a huge hit. There should only ever be one base style definition for each distinct module or component. Keep these in a separate, sacred place in your CSS. I use a _modules.scss Sass include file, imported near the top of my main CSS files.\n\nBe sure, of course, to avoid making changes to this file lightly, as the smallest adjustment can affect multiple pages (hint: keep a structure list of which modules are used on which pages). Avoid the inevitable temptation to duplicate code late in the project. Sticking to this rule becomes more important the more complex the codebase becomes.\n\nIf you can stick to this rule, using sensible class names and consistent HTML, you can reach a joyous, self-fulfilling plateau stage in each project where you are assembling each interface from your own set of carefully crafted building blocks.\n\nOld school markup\n\nLet\u2019s take a step back. Before we fret about creating a divinely pure modular CSS framework, we need to know the site\u2019s design and what it is made of. The best way to gain this knowledge is to go old school. Print out every comp, mockup, wireframe, sketch or whatever you have. If there are sections of pages that are hidden until some user action takes place, or if the page has multiple states, be sure that you have everything that could become visible to the user on paper.\n\nOnce you have your wedge of paper designs, lay out all the pages on the floor, or stick them to the wall if you can, arranging them logically according to the site hierarchy, by user journey, or whatever guidelines make most sense to you. Once you have the site laid out before you, study it for a while, familiarizing yourself with every part of every interface. This will eliminate nasty surprises late in the project when you realize you\u2019ve duplicated something, or left an interface on the drawing board altogether.\n\nNow that you know the site like it\u2019s your best friend, get out your pens or pencils of choice and attack it. Mark it up like there\u2019s no tomorrow. Pretend you\u2019re a spy trying to identify communications from an enemy network hiding their messages in newspapers. Look for patterns and similarities, drawing circles around them. These are your modules. Start also highlighting the differences between each instance of these modules, working out which is the most basic or common type that will become the base definition from which all other representations are extended.\n\nThis simple but empowering exercise will equip you for your task of actually crafting, instead of just building, the front-end. Without the knowledge gained from this kind of research phase, you will be blundering forward, improvising as best you can, but ultimately making quality-compromising mistakes that could have been avoided.\n\nFor more on this theme, read Anna Debenham\u2019s Front-end Style Guides which recommends a similar process, and the sublime idea of extending this into a guide to refer to during development and beyond.\n\nDesign homogeneity\n\nMoving forward again, you now have your modules defined and things are looking good. I mentioned that many instances of these modules will carry minor differences. These differences must be given significant thinking time, and discussion time with your designer(s).\n\nIt should be common knowledge by now that successful software projects are not the product of distinct design and build phases with little or no bidirectional feedback. The crucial nature of the designer-developer relationship has been covered in depth this year by Paul Robert Lloyd, and a joint effort from both teams throughout the project lifecycle is pivotal to your ability to craft and ship successful products.\n\nThis relationship comes into play when you\u2019re well into the development of the site, and you start noticing these differences between instances of modules (they\u2019ll start to stand out very clearly to you and your carefully regimented modular CSS system). Before you start overriding your base styles, question the differences with the designer to work out why they exist. Perhaps they are required and are important to their context, but perhaps they were oversights from earlier design revisions, or simple mistakes.\n\nThe craftsperson\u2019s gland\n\nAs you grow towards the levels of expertise and experience where you can proudly and honestly consider yourself a craftsperson, you will find that you steadily develop what initially feels like a kind of sixth sense. I think of it more as a new hormonal gland, secreting into your bloodstream a powerful messenger chemical that can either reward or punish your brain. This gland is connected directly to your core understanding of what good quality work looks and feels like, an understanding that itself improves with experience. \n\nThis gland will make itself known to you in two ways. First, when you solve a problem in a beautifully elegant way with clean and unobtrusive code that looks good and just feels right, your craftsperson\u2019s gland will ooze something delicious that makes your brain and soul glow from the inside out. You will beam triumphantly at the succinct lines of code on your computer display before bounding outside with a spring in your step to swim up glittering rainbows and kiss soft fluffy puppies.\n\nThe second way that you may become aware of your craftsperson\u2019s gland, though, is somewhat less pleasurable. In an alternate reality, your parallel self is faced with the same problem, but decides to take a shortcut and get around it by some dubious means \u2013 the kind of technical method that the words hack, kludge and bodge are reserved for. As soon as you have done this, or even as you are doing it, your craftsperson\u2019s gland will damn well let you know that you took the wrong fork in the road. As your craftsperson\u2019s gland begins to secrete a toxic pus, you will at first become entranced into a vacant stare at the monstrous mess you are considering unleashing upon your site\u2019s visitors, before writhing in the horrible agony of an itch that can never be scratched, and a feeling of being coated with the devil\u2019s own deep and penetrating filth that no shower will ever cleanse.\n\nPerhaps I exaggerate slightly, but it is no overstatement to suggest that you will find yourself being guided by proverbial angels and demons perched on opposite shoulders, or a whispering voice inside your head. If you harness this sense, sharpening it as if it were another tool in your kit and letting it guide or at least advise your decision making, you will transcend the rocky realm of random trial and error when faced with problems, and tend toward the right answers instinctively.\n\nThis gland can also empower your ability to assess your own work, becoming a judge before whom all your work is cross-examined. A good craftsperson regularly takes a step back from their work, and questions every facet of their product for its precise alignment with their core values of quality and sincerity, and even the very necessity of each component.\n\nThe wrapping\n\nBy now, you may be thinking that I take this kind of thing far too seriously, but to terrify you further, I haven\u2019t even shared the half of it. Hopefully, though, this gives you an idea of the kind of levels of professionalism and dedication that it should take to get you on your way to becoming a craftsperson. It\u2019s a level of accomplishment and ability toward which we all should strive, both for our personal fulfilment and the betterment of the products we use daily. I look forward to seeing your finely crafted work throughout 2012.", "year": "2011", "author": "Ben Bodien", "author_slug": "benbodien", "published": "2011-12-24T00:00:00+00:00", "url": "https://24ways.org/2011/crafting-the-front-end/", "topic": "process"} {"rowid": 282, "title": "Front-end Style Guides", "contents": "We all know that feeling: some time after we launch a site, new designers and developers come in and make adjustments. They add styles that don\u2019t fit with the content, use typefaces that make us cringe, or chuck in bloated code. But if we didn\u2019t leave behind any documentation, we can\u2019t really blame them for messing up our hard work.\n\nTo counter this problem, graphic designers are often commissioned to produce style guides as part of a rebranding project. A style guide provides details such as how much white space should surround a logo, which typefaces and colours a brand uses, along with when and where it is appropriate to use them.\n\nDesign guidelines\n\nSome design guidelines focus on visual branding and identity. The UK National Health Service (NHS) refer to theirs as \u201cbrand guidelines\u201d. They help any designer create something such as a trustworthy leaflet for an NHS doctor\u2019s surgery. Similarly, Transport for London\u2019s \u201cdesign standards\u201d ensure the correct logos and typefaces are used in communications, and that they comply with the Disability Discrimination Act.\n\nSome guidelines go further, encompassing a whole experience, from the visual branding to the messaging, and the icon sets used. The BBC calls its guidelines a \u201cGlobal Experience Language\u201d or GEL. It\u2019s essential for maintaining coherence across multiple sites under the same BBC brand.\n\n\nThe BBC\u2019s Global Experience Language.\n\nDesign guidelines may be brief and loose to promote creativity, like Mozilla\u2019s \u201cbrand toolkit\u201d, or be precise and run to many pages to encourage greater conformity, such as Apple\u2019s \u201cHuman Interface Guidelines\u201d.\n\nWhatever name or form they\u2019re given, documenting reusable styles is invaluable when maintaining a brand identity over time, particularly when more than one person (who may not be a designer) is producing material.\n\nCode standards documents\n\nWe can make a similar argument for code. For example, in open source projects, where hundreds of developers are submitting code, it makes sense to set some standards. Drupal and Wordpress have written standards that make editing code less confusing for users, and more maintainable for contributors.\n\nEach community has nuances: Drupal requests that developers indent with two spaces, while Wordpress stipulates a tab. Whatever the rules, good code standards documents also explain why they make their recommendations.\n\nThe front-end developer\u2019s style guide\n\nDesign style guides and code standards documents have been a successful way of ensuring brand and code consistency, but in between the code and the design examples, web-based style guides are emerging. These are maintained by front-end developers, and are more dynamic than visual design guidelines, documenting every component and its code on the site in one place.\n\nHere are a few examples I\u2019ve seen in the wild:\n\nNatalie Downe\u2019s pattern portfolio\n\nNatalie created the pattern portfolio system while working at Clearleft. The phrase describes a single HTML page containing all the site\u2019s components and styles that can act as a deliverable.\n\n\nPattern portfolio by Natalie Downe for St Paul\u2019s School, kept up to date when new components are added. The entire page is about four times the length shown.\n\nEach different item within a pattern portfolio is a building block or module. The components are decoupled from the layout, and linearized so they can slot into anywhere on a page.\n\n\n\tThe pattern portfolio expresses every component and layout structure in the smallest number of documents. It sets out how the markup and CSS should be, and is used to illustrate the project\u2019s shared vocabulary.\n\n\tNatalie Downe\n\n\nBy developing a system, rather than individual pages, the result is flexible when the client wants to add more pages later on.\n\nPaul Lloyd\u2019s style guide\n\nPaul Lloyd has written an extremely comprehensive style guide for his site. Not only does it feature every plausible element, but it also explains in detail when it\u2019s appropriate to use each one.\n\n\nPaul\u2019s style guide is also great educational material for people learning to write code.\n\nOli Studholme\u2019s style guide\n\nEven though Oli\u2019s style guide is specific to his site, he\u2019s written it as though it\u2019s for someone else. It\u2019s exhaustive and gives justifications for all his decisions. In some places, he links to browser bug tickets and makes recommendations for cross-browser compatibility.\n\n\nOli has released his style guide under a Creative Commons Attribution Share-alike license, and encourages others to create their own versions.\n\nJeremy Keith\u2019s pattern primer\n\nFront-end style guides may have comments written in the code, annotations that appear on the page, or they may list components alongside their code, like Jeremy\u2019s pattern primer.\n\n\nYou can watch or fork Jeremy\u2019s pattern primer on Github.\n\n\n\nLinearizing components like this resembles a kind of mobile first approach to development, which Jeremy talks about on the 5by5 podcast: The Web Ahead 3.\n\nThe benefits of maintaining a front-end style guide\n\nIf you still need convincing that producing documentation like this for every project is worth the effort, here are a few nice side-effects to working this way:\n\nEasier to test\n\nA unified style guide makes it easier to spot where your design breaks. It\u2019s simple to check how components adapt to different screen widths, test for browser bugs and develop print style sheets when everything is on the same page. When I worked with Natalie, she\u2019d resize the browser window and bump the text size up and down during development to see if anything would break.\n\nBetter workflow\n\nThe approach also forces you to think how something works in relation to the whole site, rather than just a specific page, making it easier to add more pages later on. Starting development by creating a style guide makes a lot more sense than developing on a page-by-page basis.\n\nShared vocabulary\n\nNatalie\u2019s pattern portfolio in particular creates a shared vocabulary of names for components (teaser, global navigation, carousel\u2026), so a team can refer to different regions of the site and have a shared understanding of its meaning.\n\nUseful reference\n\nA combined style guide also helps designers and writers to see the elements that will be incorporated in the site and, therefore, which need to be designed or populated. A boilerplate list of components for every project can act as a reminder of things that may get missed in the design, such as button states or error messages. \n\nCreating your front-end style guide\n\nAs you\u2019ve seen, there are plenty of variations on the web style guide. Which method is best depends on your project and workflow. Let\u2019s say you want to show your content team how blockquotes and asides look, when it\u2019s appropriate to use them, and how to create them within the CMS. In this case, a combination of Jeremy\u2019s pattern primer and Paul\u2019s descriptive style guide \u2013 with the styled component alongside a code snippet and a description of when to use it \u2013 may be ideal. \n\nStart work on your style guide as soon as you can, preferably during the design stage:\n\n\n\tSimply presenting flat image comps is by no means enough\u2009-\u2009it\u2019s only the start\u2026 As layouts become more adaptable, flexible and context-specific, so individual components will become the focus of our design. It is therefore essential to get the foundational aspects of our designs right, and style guides allow us to do that.\n\n\tPaul Lloyd on Style guides for the Web \n\n\n\n\tPrint out the designs and label the unique elements and components you\u2019ll need to add to your style guide. Make a note of the purpose of each component. While you\u2019re doing this, identify the main colours used for things like links, headings and buttons.\nI draw over the print-outs on to tracing paper so I can make more annotations. Here, I\u2019ve started annotating the widths from the designer\u2019s mockup so I can translate these into percentages.\n\tStart developing your style guide with base styles that target core elements: headings, links, tables, blockquotes, ordered lists, unordered lists and forms. For these elements, you could maintain a standard document to reuse for every project.\n\tNext, add the components that override the base styles, like search boxes, breadcrumbs, feedback messages and blog comments. Include interaction styles, such as hover, focus and visited state on links, and hover, focus and active states on buttons.\n\tNow start adding layout and begin slotting the components into place. You may want to present each layout as a separate document, or you could have them all on the same page stacked beneath one another.\n\n\nDocument code practices\n\nCode can look messy when people use different conventions, so note down a standard approach alongside your style guide. For example, Paul Stanton has documented how he writes CSS.\n\nThe gift wrapping\n\nPresenting this documentation to your client may be a little overwhelming so, to be really helpful, create a simple page that links together all your files and explains what each of them do.\n\n\nThis is an example of a contents page that Clearleft produce for their clients. They\u2019ve added date stamps, subversion revision numbers and written notes for each file.\n\nEncourage participation\n\nThere\u2019s always a risk that the person you\u2019re writing the style guide for will ignore it completely, so make your documentation as user-friendly as possible. Justify why you do things a certain way to make it more approachable and encourage similar behaviour.\n\nAs always, good communication helps. Working with the designer to put together this document will improve the site. It\u2019s often not practical for designers to provide a style for everything, so drafting a web style guide and asking for feedback gives designers a chance to make sure any default styles fit in.\n\nIf you work in a team with other developers, documenting your code and development decisions will not only be useful as a deliverable, but will also force you to think about why you do things a certain way.\n\nFuture-friendly\n\nThe roles of designer and developer are increasingly blurred, yet all too often we work in isolation. Working side-by-side with designers on web style guides can vastly improve the quality of our work, and the collaborative approach can spark discussions like \u201chow would this work on a smaller screen?\u201d\n\nSometimes we can be so focused on getting the site ready and live, that we lose sight of what happens after it\u2019s launched, and how it\u2019s going to be maintained. A simple web style guide can make all the difference.\n\nIf you make your own style guide, I\u2019d love to add it to my stash of examples so please share a link to it in the comments.", "year": "2011", "author": "Anna Debenham", "author_slug": "annadebenham", "published": "2011-12-07T00:00:00+00:00", "url": "https://24ways.org/2011/front-end-style-guides/", "topic": "process"} {"rowid": 286, "title": "Defending the Perimeter Against Web Widgets", "contents": "On July 14, 1789, citizens of Paris stormed the Bastille, igniting a revolution that toppled the French monarchy. On July 14 of this year, there was a less dramatic (though more tweeted) takedown: The Deck network, which delivers advertising to some of the most popular web design and culture destinations, was down for about thirty minutes. During this period, most partner sites running ads from The Deck could not be viewed as result.\n\nA few partners were unaffected (aside from not having an ad to display). Fortunately, Dribbble, was one of them. In this article, I\u2019ll discuss outages like this and how to defend against them. But first, a few qualifiers: The Deck has been rock solid \u2013 this is the only downtime we\u2019ve witnessed since joining in June. More importantly, the issues in play are applicable to any web widget you might add to your site to display third-party content.\n\nDown and out\n\nYour defense is only as good as its weakest link. Web pages are filled with links, some of which threaten the ability of your page to load quickly and correctly. If you want your site to work when external resources fail, you need to identify the weak links on your site. In this article, we\u2019ll talk about web widgets as a point of failure and defensive JavaScript techniques for handling them.\n\nWidgets 101\n\nImagine a widget that prints out a Pun of the Day on your site. A simple technique for both widget provider and consumer is for the provider to expose a URL:\n\nhttp://widgetjonesdiary.com/punoftheday.js\n\nwhich returns a JavaScript file like this:\n\ndocument.write(\"

The Pun of the Day

Where do frogs go for beers after work? Hoppy hour!

\");\n\nThe call to document.write() injects the string passed into the document where it is called. So to display the widget on your page, simply add an external script tag where you want it to appear:\n\n
\n \n \n
\n\nThis approach is incredibly easy for both provider and consumer. But there are implications\u2026\n\ndocument.write()\u2026 or wrong?\n\nAs in the example above, scripts may perform a document.write() to inject HTML. Page rendering halts while a script is processed so any output can be inlined into the document. Therefore, page rendering speed depends on how fast the script returns the data. If an external JavaScript widget hangs, so does the page content that follows. It was this scenario that briefly stalled partner sites of The Deck last summer.\n\nThe elegant solution\n\nTo make our web widget more robust, calls to document.write() should be avoided. This can be achieved with a technique called JSONP (AKA JSON with padding). In our example, instead of writing inline with document.write(), a JSONP script passes content to a callback function:\n\npublishPun(\"

Pun of the Day

Where do frogs go for beers after work? Hoppy hour!

\");\n\nThen, it\u2019s up to the widget consumer to implement a callback function responsible for displaying the content. Here\u2019s a simple example where our callback uses jQuery to write the content into a target
:\n\n\n
\n\n\u2026\n\n\n
\nfunction publishPun(content) {\n $(‘.punoftheday’).html(content); // Writes content display location
\n}
\n\n\n\n\nView Example 1\n\nEven if the widget content appears at the top of the page, our script can be included at the bottom so it\u2019s non-blocking: a slow response leaves page rendering unaffected. It simply invokes the callback which, in turn, writes the widget content to its display destination.\n\nThe hack\n\nBut what to do if your provider doesn\u2019t support JSONP? This was our case with The Deck. Returning to our example, I\u2019m reminded of computer scientist David Wheeler\u2019s statement, \u201cAll problems in computer science can be solved by another level of indirection\u2026 Except for the problem of too many layers of indirection.\u201d\n\nIn our case, the indirection is to move the widget content into position after writing it to the page. This allows us to place the widget \n

Pun of the Day

\n

Where do frogs go for beers after work? Hoppy hour!

\n
\n\nThe \u2018loading-dock\u2019
now includes the widget content, albeit hidden from view (if we\u2019ve styled the \u2018hidden\u2019 class with display: none). There\u2019s just one more step: move the content to its display destination. This line of jQuery (from above) does the trick:\n\n$('.punoftheday').append($('.loading-dock').children(':gt(0)'));\n\nThis selects all child elements in the \u2018loading-doc\u2019
except the first \u2013 the widget