<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Paul Bennett-Freeman on Medium]]></title>
        <description><![CDATA[Stories by Paul Bennett-Freeman on Medium]]></description>
        <link>https://medium.com/@OddEssay?source=rss-17c415854467------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*ocYP-vxclboVxfP-.jpg</url>
            <title>Stories by Paul Bennett-Freeman on Medium</title>
            <link>https://medium.com/@OddEssay?source=rss-17c415854467------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Tue, 17 Nov 2026 14:02:07 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@OddEssay/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Why We Built a Living Styleguide of Reusable Components With Mountain View]]></title>
            <link>https://medium.com/@OddEssay/why-we-built-a-living-styleguide-of-reusable-components-with-mountain-view-614b34052136?source=rss-17c415854467------2</link>
            <guid isPermaLink="false">https://medium.com/p/614b34052136</guid>
            <category><![CDATA[ruby-on-rails]]></category>
            <category><![CDATA[web-development]]></category>
            <category><![CDATA[product-engineering]]></category>
            <dc:creator><![CDATA[Paul Bennett-Freeman]]></dc:creator>
            <pubDate>Fri, 13 May 2016 11:01:00 GMT</pubDate>
            <atom:updated>2016-10-24T22:05:53.064Z</atom:updated>
            <content:encoded><![CDATA[<p>As you start adding new views and interactions to your application, the advantages of maintaining a styleguide—a living document of coded modules (i.e. text inputs)—seem to go up exponentially.</p><p>In particular, styleguides pay huge dividends in saving you time, making communication a lot easier, all while keeping design and code consistent across your application.</p><h4>The Styleguide</h4><p>As Susan Robertson lays out on <a href="http://alistapart.com/article/creating-style-guides">A List Apart</a> a styleguide is:</p><blockquote>a living document of code, which details all the various elements and coded modules of your site or application. Beyond its use in consolidating the front-end code, it also documents the visual language, such as header styles and color palettes, used to create the site. This way, it’s a one-stop place for the entire team — from product owners and producers to designers and developers — to reference when discussing site changes and iterations.</blockquote><h3>Starting With Good Intentions</h3><p>Let’s consider a basic text input.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/6af19954bb12fda01499fb956997ef0e/href">https://medium.com/media/6af19954bb12fda01499fb956997ef0e/href</a></iframe><p>We had a static styleguide responsible for the visual design and markup of the component.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*aj5Xf1DsDOcC0WRlZSksiQ.png" /></figure><p>Once we’d developed the design and markup, the components were built using Angular’s Directives function — which enabled us to wrap up a text field (for example) into a component template with logic that could be dropped into a view like this:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/9e7ee363058eedc430f9a5ad23c1cf99/href">https://medium.com/media/9e7ee363058eedc430f9a5ad23c1cf99/href</a></iframe><h4>Two Steps Should’ve Been One</h4><p>Because of the extra work that went into updating the markup and CSS—by manually copying the changes between the styleguide and Angular directives—we quickly ran into problems.</p><p>When it came right down to it:</p><ul><li>We could design new functionality by solely updating an Angular component [but]</li><li>We could not design new functionality by solely updating the static visual styleguide</li></ul><p>We ran into the trap of making quick design changes to the components that were not copied back to the styleguide — causing component and styleguide sync problems.</p><p>The more the styleguide became out of sync, the less useful it became—eroding all of the upside of styleguides themselves.</p><h3>A Better Way?</h3><p>Knowing what caused us headaches with the Fruitful 1.0 styleguide, we had a clear criteria for our new styleguide:</p><h4>A Living Styleguide, Built on Components</h4><p>The styleguide should use the same components that you implement in the application’s views. A change to a component is then reflected both in the styleguide, and across the whole application—removing any potential sync issues. This applies to both the markup in the template, and the CSS.</p><h4>HTML Gets Written as HTML</h4><p>We want to avoid any kind of short cuts when it comes to our source templates, so no HAML or Rails helpers producing tags. We prioritise clarity over cleverness.</p><blockquote>“It’s important that a designer with no specific coding knowledge can look at a template and make sense of it.”</blockquote><h4>Sample Data</h4><p>When dealing with components that can express multiple combinations of options—such as a larger/smaller button—we wanted to be able to view and work on the different variations easily.</p><h4>Self Documenting</h4><p>We want it to be as easy as possible to take a component from the styleguide and implement it in the correct way. We didn’t want to have to view source code or open the browser console in order to see what options a component takes or how to use it.</p><h3>Mountain View</h3><p>Funnily enough, our criteria almost described the Mountain View Gem that we came across on <a href="https://github.com/devnacho/mountain_view/">GitHub</a>.</p><p>After a firing up a test version and getting it working in a couple of minutes, we were quickly convinced it was the right tool for us.</p><h4>Two Lines To Install</h4><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/ea4a5816cb836381c1951f291111bbd6/href">https://medium.com/media/ea4a5816cb836381c1951f291111bbd6/href</a></iframe><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/593bdb3c9270def386a6aa96c39480cb/href">https://medium.com/media/593bdb3c9270def386a6aa96c39480cb/href</a></iframe><h4>It Just Works</h4><p>Creating a new component is as quick as creating a folder with the component <em>name</em> containing a template called <em>_name.html.erb</em>, and the config <em>name.yml</em> for the stubs.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/948/1*RfP1sIFeDla9_6gPVbUQIQ.png" /><figcaption>Text Input Component: One Directory, Two Files.</figcaption></figure><h4>It Matches Your Ruby on Rails Template Settings</h4><p>The examples for Mountain View use HAML and CoffeeScript, so we had a moment of concern it might not fit our preferences. Thankfully, it uses the settings in your <em>config/application.rb</em> as any other generator or loader would so when we use .html.erb files everything works as expected.</p><h4>A Clear Sample Data Configuration File</h4><p>Each component in Mountain View has a YAML file containing an option for some meta data — a description at the top of the component view in the styleguide— and a list of stubs.</p><p>When viewing the component in the styleguide each stub is rendered, letting you see the different combinations playout in one place.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/adb146cce02acb1d6a6a93e848ee9d8e/href">https://medium.com/media/adb146cce02acb1d6a6a93e848ee9d8e/href</a></iframe><h4>Documentation Built In</h4><p>As Mountain View loops over your stubs in the config file, it displays the component on the page with that set of options and shows you details of how it was called inline.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*1rrPINVDxVOGSFOkIcH0CA.png" /></figure><h3>Putting It All Together</h3><h4>Fat HTML, Skinny Code</h4><p>Using a component based workflow means that large forms become much more manageable in views.</p><p>The Text Input demonstrates this perfectly.</p><p>When you add up the input label, styles to give the user additional feedback, help text, placeholders, and inputmask options we have currently 36 lines of templated HTML:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/428ba526ddd84a3d2df07f9b464e86ab/href">https://medium.com/media/428ba526ddd84a3d2df07f9b464e86ab/href</a></iframe><p>When we use this in a view, we only need to provide the data that the component needs—leaving us with a clean and tidy 6 line implementation:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/e1914dca9cad8989d5f089bb0d3effbf/href">https://medium.com/media/e1914dca9cad8989d5f089bb0d3effbf/href</a></iframe><h3>How We Develop Components</h3><p><strong>Keep to existing naming conventions if they exist.</strong> HTML input tag uses the attribute name “value” so we use that as the property name when passing data from the view to the component.</p><p><strong>Provide data and context, not design.</strong> This means avoiding the use of arbitrary classes, and instead facilitating specific functions that convey meaning, so <strong>`size: ‘big’`</strong> and <strong>`has_warning: true`</strong> are preferable to <strong>`class: ‘big’`</strong> and <strong>`class: ‘warning’`</strong>.</p><p><strong>Iteration inside components, not outside.</strong> It’s better to have a property of items and have a loop inside the component, rather than have to loop in the view and render items multiple times.</p><p>For example, a simple navigation list might look like:</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/a07f9ed5058825000e9d22572e4936e3/href">https://medium.com/media/a07f9ed5058825000e9d22572e4936e3/href</a></iframe><p><strong>Components can use components.</strong> For example, we ensure all postal addresses across the application are in the same format. Rather than specifying 5 different input components each time (i.e. address line 1, town, city), the address component renders the child components (mostly text fields).</p><p>Going forward, if we want to add functionality like an address lookup, or change the way we handle addresses completely, we have one place we need to update.</p><p><strong>Planning for Improvement.</strong> By keeping a clear line between data and design we can knock out something basic that we know we want to improve on in the future.</p><p>For example, our Currency component just calls the existing Text Input component with a specific input mask set. Right now we just use a very simple JQuery input mask, but we can see that is likely the change and by keeping this level of separation we are free to consider alternatives without having to address any technical debt.</p><iframe src="" width="0" height="0" frameborder="0" scrolling="no"><a href="https://medium.com/media/a2787bd9bcdbc4674aabdce7573a8655/href">https://medium.com/media/a2787bd9bcdbc4674aabdce7573a8655/href</a></iframe><h4>For Forms &amp; More</h4><p>While we talk about forms a lot when discussing how we use components, they play a role in other places too — Modal views and navigation controls for instance. As a rule, any time we have a design pattern that will be reused in multiple places we wrap it up in a component.</p><h3>Putting the Style into Styleguide</h3><p>Out of the box, Mountain View renders with it’s own layout and then pulls in your SASS and JavaScript from the Rails Asset Pipeline, great if you’re on a vanilla Rails install, but we use Gulp to build our assets and so needed to take a home-brew approach.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*C29RlRJ43zIJmbKQxywsJA.png" /><figcaption>The default Mountain View Layout</figcaption></figure><p>Thankfully, this was as simple as getting the default layout from the Gem using <strong><em>gem open mountain_view, </em></strong>opening <strong><em>app/views/layouts/mountain_view.html.erb</em></strong> from the engine and saving it to our local <strong><em>app/views/layouts/mountain_view.html.erb</em></strong> which gets found by Rails first and so rendered as the prefered layout.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*1xrtGVXPBVFndQVwkaPOow.png" /></figure><p>Incidentally, this should work for any Rails Engine where you want to override the default layout with one of your own.</p><h3>Looking To The Future</h3><h4>Making A Portable Styleguide?</h4><p>Right now we only have one Rails app to focus on — <a href="http://martinfowler.com/bliki/MonolithFirst.html">Monolith First, to use the term Martin Fowler coined </a>— but if we decide to deploy another user facing Rails app, it makes sense to move the styleguide to a Gem and have both projects include that in their Gemfile.</p><p>However, what you gain in portability with this approach you lose in agility, as even a small change needs to be made at source and then a new version re-deployed. That said, by the time this becomes an issue we’d expect to have a much more stable set of design patterns in place and therefore less likely to be making small frequent changes.</p><h3>Further Reading &amp; Resources</h3><ul><li><a href="https://github.com/devnacho/mountain_view/">Mountain View</a> is the Gem we use to build our styleguide, it renders a living styleguide. There is a <a href="https://mountain-view.herokuapp.com/mountain_view/styleguide">demo of a simple styleguide</a> as part of the documentation.</li><li>We use <a href="https://www.browsersync.io/docs/gulp/">BrowserSync and Gulp</a> so we can have multiple browsers livereload as we update templates during development.</li><li>Lonely Planet have their <a href="http://rizzo.lonelyplanet.com/">“Rizzo” styleguide</a> online, and the origional developer Ian Feather blogged about its creation at <a href="http://ianfeather.co.uk/a-maintainable-style-guide/">http://ianfeather.co.uk/a-maintainable-style-guide/</a></li></ul><p><em>This post was originally posted on the </em><a href="http://ingredients.lovefruitful.com/"><em>Fruitful Ingredients</em></a><em> publication.</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=614b34052136" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>