Responsive HTML Tutorial

by ClickHelp — professional help authoring tool

Do you use your phone to consume online content? Of course, you do!

And if you are a person who writers or develops for the web, you often notice those mobile-related glitches in the layout or style that are common for many web sites. And you tell yourself — “I would never make that silly mistake in my markup if I had to create a mobile-friendly page”.

However, there is no simple list of things to do in order to make a page mobile-friendly. This is a multi-step process. This post will cover some typical steps of this process.

Step 1 — Mobile Screen Emulation

Have you ever thought of what your online documentation looks like when viewed on a 1920x1080 monitor or opened from an iPhone? Well, today you definitely should. It is not a secret for anyone that mobile browsers usage grows rapidly and having a mobile website becomes a must for every online business. But did you know that 1920x1080 seems to be a #2 popular resolution around the web?

According to W3Schools, 1920x1080 is used by 13% of their visitors and the number keeps growing. The bad news for those who love the old-school 4:3 aspect ratio: the time of 4:3 is gone and widescreen monitors seem to become a new de-facto world standard.

What does this mean personally for you as a documentation writer? If you are dealing with online documentation (and hey, online documentation is another “must” for most software businesses), you definitely should check how your documentation stretches from 1920x1080 (widescreen monitor) to 320x568 (iPhone 5, considering pixel aspect ratio). We bet you will be surprised by the result.

In fact, you are also likely to become upset when you see lonely screenshots followed by half-monitor wide empty space on big monitors or trimmed tables and images unpredictably jumping around your page on mobile phones. Although they claim to support high resolutions (even up to 1920x1080 FullHD for some models), they also have pixel aspect ratio of 2 or even 3, so as a result you still get the same small mobile monitor. No magic at all.

So, do you really need to go to the nearest store and buy a bag of mobile phones and order a ton of monitors just to check how your online documentation looks like on a every of them? It is good for everyone that the answer is “no”. In this post, we will cover a few useful tools created just for that.

Things You Must Know about Emulators

Before we start, there are a few things you must be aware of:

1 — Emulation can be far from a real device.

Mobile browser engines can differ from desktop browser engines a lot. Even if your page looks great when you emulate a mobile phone on a desktop computer, it does not have to look that cool on a real device. For example, many mobile browsers do not properly support the ‘position: fixed’ CSS property. So, your top menu will be displayed properly in emulation, but your fixed header is likely to be ignored and scrolled down when you browse the same page from a real mobile device.

2 — Be careful with screen sizes.
 Mobile devices claim to support high display resolutions, but that is just a trick, as described above. The truth is that resolution applies to a virtual viewport in which your page is going to be rendered. And after it’s rendered, it will be resized to fit the small mobile screen. So, make sure you divide the screen resolution by the pixel ratio when emulating a mobile device. Considering the example above, iPhone 5 resolution is 640x1136 and its pixel ratio is 2. So, you divide both values by 2 to get the real screen size: 320x568.

3 — Emulating the screen size is not everything.
 If your content is a set of HTML files, you can safely ignore this point. However, if your online documentation has some back-end with smart logic, like ClickHelp, there is one more thing you need to consider testing. Screen size is not the only difference between mobile and desktop browsers. Another difference is the user agent string passed to the server in every request from the browser.

The user agent string contains some information about your environment: the name and version of your OS, some information on the browser engine, etc. For example, for iPhone 5 the user agent string looks like this:
Mozilla/5.0 (iPhone; CPU iPhone OS 7_0 like Mac OS X; en-us) AppleWebKit/537.51.1 (KHTML, like Gecko) Version/7.0 Mobile/11A465 Safari/9537.53

Some web applications use this information to differentiate mobile and desktop users in order to present them with different styles, layout and sometimes even different content. Just open our web site from a mobile device, and you will see the difference. So, if your online documentation engine is smart enough, you should emulate a proper user agent string along with the screen size.

Screen Size Emulation — 3 Free Tools

Let us consider the tools that can be used to check how your online documentation looks like on a wide screen and on a mobile device. All the mentioned tools are totally free, and that’s so nice!

Built-In Browser Features: Chrome

Let us start with the functionality you already have at hand, but was probab;y unaware of its existence — the mobile browser emulation in Google Chrome.


+ Great features set.
 + Predefined collection of resolutions, pixel ratios and user agent strings for 40 mobile and tablet devices.
 + Simultaneous screen and user agent emulation.
 + Support for custom screen sizes.


- No presets for PC and TV screen sizes.

Chrome mobile emulator is probably the best one we have ever seen and that is the one we use for our tests. It has all the features you might need: a predefined set of mobile and tablet devices with screen sizes and user agent strings; the ability to rotate virtual screen and change its size and pixel ratio easily; the ability to emulate a specific CSS media value (can be used to test printable version of your markup too); nice tap cursor emulating finger size to help you check your topics UI for “pixel hunting”, and so on. Here’s how our website looks like on iPhone 5 emulated in Google Chrome 33:

To enable this feature, just go to Developer Tools (Ctrl + Shift + J), click Settings icon at the top right corner and check the “Show ‘Emulation’ view in console drawer” option. This is it. The UI might change, though, so here is a link to the corresponding help topic: Chrome Mobile emulation.

Built-In Browser Features: Firefox

The other browser that is also providing mobile emulation functionality is Mozilla Firefox.

+ Draggable screen borders to check page reaction to multiple screen sizes at once.
+ Easy screenshots generation in one click (the small camera icon in the top right).
+ Support for custom screen sizes.

- No device-specific screen resolution or user agent presets.
- Poor built-in support for user agent emulation.

According to W3Shools, Firefox is #2 popular browser nowadays, so we cannot ignore it. Sadly, mobile emulation support in Firefox does not seem to be that cool. Firefox does provide support for screen emulation and screen rotation, but it does not have that fancy predefined list of 40 mobile and tablet devices and besides it does not provide an easy way to emulate a user agent string out of box. However, you can still emulate a mobile device in Firefox, even though you will probably need Chrome (or another source) to lookup specific screen sizes and user agent strings. The emulator has a set of 7 predefined popular screen resolutions, but they are not associated with specific devices.

Screen emulation is called “Responsive Design View” in Firefox and it can be invoked via the “Tools | Web Developer | Responsive Design View” menu item (or via the Ctrl + Shift + M shortcut). Here’s a help topic link in case something changes: Responsive Design View.

As for user agent emulation, there is a hacky way to do this out of the box, but we strongly recommend that you use an extension instead. For example, you can use User Agent Switcher. This extension has a predefined set of user agent strings, plus you can add your own values, so it is quite easy to use.

Here is how the same page of our web site looks like in iPhone 5 emulated by Firefox (both with screen size and user agent emulation enabled):

Large Screens Emulation: Screenfly

In addition to browsers, there are specialized tools that provide screen emulation functionality, and some of them are free. We will talk about Screenfly.

+ Presets for TV, Notebook, Netbook and Desktop resolutions.
+ Support for custom screen sizes.
+ Nice rulers to check approximate element sizes.

- Cannot test local HTML files.
- No user-agent emulation.
- A few mobile and tablet presets (as compared to Chrome).

An attentive reader would note that we were talking about widescreen monitors at the beginning of the article but have covered only mobile devices by now. Well, now it’s time for widescreen monitors.

If you are not lucky enough to have one at your disposal, you can always emulate a wide screen inScreenfly. Of course, you can also do this with the other tools mentioned above, but the advantage of Screenfly is that it has presets for popular TV, Notebook, Netbook and Desktop resolutions as well as presets for some tablet and mobile devices (even though the number of presets is not as high as it is in Chrome). Just like the other tools, it does not limit your ability to interact with a web page via the virtual screen. However, it has a limitation which is worth mentioning: Screenfly can only show pages published on the web. In other words, you cannot check your local HTML files with it. So, if your help topics are not published online, you are out of luck with this tool.

Here is what the same page of our web site looks like on a 10” Netbook (1024x600) emulated by Screenfly:

Device Screen Emulation — Summary

Finding the right tools and checking what your help topics look like on different devices is just the first step on your way to creating responsive UI. However, there is nothing to be afraid of here — getting a list of device-specific UI issues is about half of the way. Fixing the issues is another half and we are going to show you how this can be achieved below — keep reading!

Step 2 — Mobile UI Validation Tools

It’s time to make the next step and take a look at the tools helping you detect any UI issues specific to mobile device browsers.

CSS and Mobile Browsers

The idea behind responsive CSS styles is quite simple: you create different styles for different device types and/or screen sizes. However, devil is in the details. Can you adapt your content for all possible screens automatically? Where do you start? What elements should be hidden / displayed or changed depending on the screen resolution? How can you change the layout of your help topics? What screen resolutions you should handle?

So many good questions… Let’s discuss them one by one.

Can you Handle All Possible Screens Automatically?

No. There is no magic bullet, no big red button, no magic spell for this. Come on, you did not think this was that easy, right? You need to plan your HTML design according to the screen sizes you are going to support. We are here to help you with this!

Where to Start?

Now, when we know the answer to the most important question, here are some points to help you get the idea of the next steps:

  1. Choose a screen emulator which will show you what your pages look like on different screens. It should allow you to switch from a mobile phone to a 1920x1080 widescreen monitor emulation easily. Our choice is Google Chrome emulation.
  2. Check your existing content on different virtual screens to build a list of layout problems. If you still cannot forget the magic button above, we have good news for you: there are some tools which can detect mobile-specific issues with your content automatically, they covered further in this post. For example, they can detect large images which are no good for mobile phones with low bandwidth or some elements or CSS properties which are not supported by mobile browsers properly. They can even detect elements which are too small and/or located too dense to be tapped with a finger properly.
  3. Choose your preferred approach to CSS design.
    There are two main approaches: Graceful Degradation when default styles are for big screens, and there are special styles for smaller screens; and Progressive Enhancementwhere things happen vice versa. There is a nice article regarding pros and cons of both approaches: Mobile First Design: Why It’s Great and Why It Sucks, so we will not discuss them here. However, if you already have some content, we bet you originally designed it for a desktop screen, so you should consider using the Graceful Degradation approach most probably.
  4. Plan changes to your page layouts considering specific device types and screen widths you are going to handle. You may need to be very creative trying to push all the page elements into a small mobile screen.
  5. Get familiar with responsive CSS styles. There are a number of resources on the Internet on this subject. We will also talk about this in our future blog posts.
  6. Create your responsive styles. Yep, this is the most tricky part, and we will touch this topic in future posts as well.

Free Tools for Mobile CSS Issues Detection

It is always a good idea to run automatic validations on your pages as you work on them to notice the issues timely before it is too late. In this section, we will cover a few free tools from popular vendors which can help you with that.

1. W3C mobileOK Checker.

This tool provides comprehensive report on all content associated with the given page — markup, styles, images. It checks for various standards compliance, validates against a number of heuristic rules to check for things which are known to cause issues on mobile devices and so on. The main validation targets are page performance (this includes content size and the number of requests) and things which might not be supported by specific mobile devices and therefore might be displayed incorrectly.

Unfortunately, W3C moibleOK Checker does not emulate a mobile device when requesting your page and therefore if you have the same URLs for mobile and desktop pages (like we do), you can end up checking the desktop version of your content against mobile-specific rules. As a result, W3C moibleOK Checker may give poor ratings for your website even if it has a mobile version.

2 . Google PageSpeed Insights.

The name of the tool may cause confusion, but this tool does check both mobile and desktop versions of your pages via proper mobile emulation.

This is the tool of our choice — not because we have been flattered by its output, but because it emulates mobile devices and focuses on clear stuff affecting real user experience, like tap target sizes and density, font readability, content sizing (to fit viewport) and so on.

Just like W3C mobileOk Checker, PageSpeed Insights provides specific numbers which show you how much room you have left for improvement and how important (approximately) these or those changes are for user experience (at least, in Google opinion). However, in case of PageSpeed Insights, the numbers are closer to real life — for example, the tool gives you an estimation of how much traffic you can save if you optimize your images or minify your styles and scripts. This is an important advantage which allows you to decide whether the optimization is worth the efforts.

The last, but not the least note on Google PageSpeed Insights is that its primary purpose is to check the performance of your content — both for mobile and desktop users. And page speed is known to be an important SEO factor for Google and your page visitors who leave after 3 seconds of page loading. Thus, it is worthwhile to spend a few minutes to check your content performance results and automatic improvement suggestions provided by Google PageSpeed Insights. We are not going to cover performance here in detail, but if you are interested in it, check this resource on page speed optimization. Also, take a look at our blog post on lazy-loaded images — this can help you decrease the content size and improve the performance dramatically for pages with a lot of screenshots.

Mobile UI Validation — Summary

Now you know how to emulate mobile devices and how to detect various mobile-specific issues automatically. However, not everything can be automated. There are still layout issues which can only be detected by a human, and it is often unclear how to resolve them. But don’t worry — we’re going to discuss some typical mobile-specific issues, and give recommendations on how to resolve them.

Step 3 — Problems and Solutions

It is time to get to solving mobile experience problems related to the content layout, and this post will give you practical advice.

Typical Mobile Experience Problems

The tools we mentioned in the previous post are able to detect a lot of issues automatically. However, they still don’t cover 100% of situations specific to wide screens or mobile screens. We should not blindly try to fit all their rules. As people say on Stack Overflow, not everything that comes from Google is a “holy grail” just because it comes from Google.

This means that you still need to examine your content manually, and we will consider some typical issues you should be looking for. The majority of problems related to the varying screen sizes has the same root cause: the screen width. Let’s take a look at what may go wrong with it.

Issue #1 — Horizontal Scrolling on Mobile Devices

Since people usually read your content horizontally (left to right or vice versa), they are OK with having a vertical scrollbar. Scrolling the content top to bottom as they read line by line is fine. However, the horizontal scrollbar will force them to scroll each line of your text, which definitely is not good user experience.

Issue #2 — Empty Space on Wide Screens

The opposite situation is the empty space in your content due to the wide screen width. A 500px-wide screenshot occupying an entire line may look fine on a 3x4 desktop monitor. But on a widescreen 1920x1080 monitor the screenshot will occupy only 25% of the screen width. The remaining 75% will be empty space, which does not look good.

Issue #3 — Jumping Floating Elements

After reading about the two previous issues, some skilled technical writers may think they are safe because they use floating <div> elements. “Hey, my blocks will just jump around to fit the screen width and the layout will be fine.” Well, using floating DIVs can help you indeed to a certain extent. However, you are still likely to see some issues if you check how your topics are displayed on a mobile phone or a tablet. For example, if you have a main menu with floating (or inline) elements, how will these elements react to the decreasing screen width? Right, they will jump to the next line. As a result, you will either see menu items leaving their nests and floating over your content, below the header, or you will not see them at all if they appear to be hidden beyond elements with greater z-index values. Responsible menus is an interesting topic and we are going to cover it in a future post.

Mobile Experience — Dos and Don’ts

Now, when you are aware of typical problems, let us examine possible solutions. By following the guidelines below, you will handle the majority of the mobile experience problems in your online documentation. So, let’s get rolling!

Advice #1 — No Hard-coded Widths

Whenever possible, avoid hard-coding element widths. If at least one element in your help topic has a hard-coded width and it is greater than the screen width, you will get a horizontal scrollbar. A very good example of this situation are the screenshots. They are usually rendered as images and they can be wide, causing your help topics to have horizontal scrollbars. One of possible solutions is to set their widths in percentages, not in pixels. For example, for full-width screenshots you can do it like this:

<img src="..." style="width: 100%" />

This may solve a part of the problem. However, this may not look good on wide screens. Consider specifying the max-width and min-width styles as well, if necessary. Remember, if you do not set the image width explicitly, each image element will still have some width assigned to it, and it will be defined in pixels. Here is an example:

<img src="..." style="width: 100%; max-width:600px; min-width: 200px" />

Advice #2 — Percentages and Column Layout

Filling the empty space (the problem we mentioned above) can appear to be tricky depending on your specific layout. If you are working on a documentation project, you can use these free online documentation templates specially adapted to fit 1920x1080 monitors. They are available as a downloadable package, so you can see how the styles are implemented there and do the same for your online content.

To understand the idea we used in those templates, here are some guidelines to consider:

  • Use percentages for width values.
  • Arrange your content in columns via the column-count property introduced in CSS 3. You can change the number of columns dynamically depending on the screen width. Another option is to use floating blocks that jump around and fill the space depending on the width.
  • Think twice before inserting line breaks or block elements. Check how your content looks like with maximum and minimum width respectively using the screen emulation tools we talked about previously.

Advice #3 — Dynamic Menu Layout

Check your UI on different screen widths carefully. If you do face problems with jumping blocks (e.g. in the menus), consider showing / hiding them depending on the screen width. A common example of this approach is responsive menus which either display all their items on wide screens, or move all of them to a popup menu leaving a single small menu button on small screens. We will talk more about implementing this approach in a future post.

Advice #4 — Fat Fingers

Beware of small and dense navigation elements. It may be fine to have a 5x5 pixels icon in your topic header for desktop users. We understand your wish to use small icons in order not to overload the UI, really. But try to hit that icon with your finger when viewing the help topic from a mobile device, especially if there are other navigation elements nearby. You are likely to fail your first 50 attempts, which will drive you mad unless you are good at Zen. Make sure your UI elements are big and sparse enough to be hit with a finger without invoking other elements accidentally. The circle icon emulating the finger size in Google Chrome mobile emulator can help you with this type of testing.

Advice #5 — Hover Events

If you have some popup menus or other navigation elements which are supposed to be invoked by hover events, make sure they can be invoked by clicks as well. Remember that there are no hover events on mobile phones and tablets. This may be a real issue for some interactive behavior triggered by those events. So, if you care about the mobile experience, pay enough attention to this aspect.

Problems and Solutions — Summary

Making your content look great on mobile devices is not a simple task. And it may look scary in the beginning. However, this is still not rocket science — you can figure this out by dealing with every aspect one by one. In this part, we have tried to list the most typical layout problems and give suggestions on how to solve them.

Step 4 — Responsive Styles

It is time for some practice. We suppose that you have already identified issues in your content and in this post we will focus on specific ways to solve them with CSS.

Planning Changes

Here are some options you have when dealing with responsive content:

  1. Use different styles. This means that you can show, hide or change your page elements with conditional CSS depending on device screen size. This is what this post series is all about, so we will focus on this solution.
  2. Use different content. If you have control over the server-side engine of your documentation and the engine is smart enough, you can configure it to display different content for different devices or even use totally different pages with different URLs for mobile and desktop users. But what if you don’t? Well, there are still two other ways. One of them is conditional content, which is supported by the majority of documentation tools, including ClickHelp. You can have different versions of your documentation published for mobile and desktop users. However, making readers choose the needed version manually is annoying and therefore a more realistic option is to handle content changes with JavaScript, which gives you great flexibility and allows changing every piece of your pages. You can even render both mobile and desktop elements on a single page and then hide, show or move them as necessary from JavaScript on the client. However, we strongly recommend that you consider using CSS first as your customers may have scripts disabled in their browsers. Besides, CSS can help you hide multiple elements at once if you apply a special class to them (call it “screenOnly” or “mobileOnly”, depending on the approach you choose).
  3. Use different master pages. Actually this should be a part of #3, but we decided to make it a separate option to stress its importance. Having special navigation elements for mobile version of your content is a good practice due to specifics of mobile navigation described above like missing hover events or taps which are less precise than mouse pointer clicks.

In reality, you are likely to use a combination of these options depending on your specific scenario. And now, let us focus on option #1, which is the most commonly used approach for creating responsive HTML.

Responsive CSS

In CSS 2, you could only apply different styles based on device type with the @media rule. For example:

@media screen
.test {font-size:14px;}

@media print
.test {font-size:20px;color:gray;}

@media screen,print
.test {font-weight:bold;}

You can find a description of this rule here at W3Schools: CSS Media Types.

However, with CSS 3 you have a much better mechanism to control your styles. Instead of focusing on device types (which do not actually guarantee anything, because screen sizes may vary greatly for devices of the same type) you can focus on specific device characteristics. Some of the commonly used are max-width, max-device-width, min-width and min-device-width. The difference between max-width and max-device-width is that the former applies to the browser display area size, while the latter applies to the entire device screen. Also, there are similar properties for height values too.

Note that these conditions can be applied not only to specific pieces of your CSS, but also to your entire stylesheet files. For example:

<link rel="stylesheet" type="text/css" media="all" type="text/css" href="default.css" />
<link rel="stylesheet" type="text/css" media="screen and (min-width: 1000px)" href="bigscreen.css" />

The first stylesheet will always be loaded while the second one will load only if device type is “screen” and the screen width is more than 1000 pixels. You will see more examples in the next section.

Choosing Screen Resolutions

Unfortunately, there is no “one size fits all” solution for how many CSS files you need to have and what conditions you need to check. This depends solely on your layout and specific issues you need to handle. However, if you are dealing with existing content and this content was originally designed for specific width, it can be a good idea to apply special CSS rules for widths which are less than that width. Another tip is to check Google Analytics or other similar stats for your content to see the most common screen sizes. Many documentation tools including ClickHelp provideintegration with Google Analytics to help you gather statistics for your online documentation.

If you do not want to spend time figuring out what screen sizes are specific for your content, you can use some common threshold size values. Twitter Bootstrap can give a good example of threshold width values for both approaches.

For example, here are conditions used in Twitter Bootstrap 2 where they used the Graceful Degradation approach back then:

/* Landscape phones and down */
@media (max-width: 480px) { ... }

/* Landscape phone to portrait tablet */
@media (max-width: 767px) { ... }

/* Portrait tablet to landscape and desktop */
@media (min-width: 768px) and (max-width: 979px) { ... }

/* Large desktop */
@media (min-width: 1200px) { ... }

As time went on and trends changed, Bootstrap 3 switched to the “mobile first” approach, also known as Progressive Enhancement:

/* Extra small devices (phones, less than 768px) */
/* No media query since this is the default in Bootstrap */

/* Small devices (tablets, 768px and up) */
@media (min-width: 768px) { ... }

/* Medium devices (desktops, 992px and up) */
@media (min-width: 992px) { ... }

/* Large devices (large desktops, 1200px and up) */
@media (min-width: 1200px) { ... }

The last but not the least point worth mentioning in regards to conditional CSS is that mobile phones will not treat your *-width conditions the way you expect by default. The width can be affected by device position (portrait or landscape), pixel aspect ratio (you do not want to treat a 1920x1080 mobile phone screen like a 1920x1080 monitor, right?) and zoom.

The good news is there is “one magic tag to rule them all”. Just add it to the section of your pages and you will get predictable logic for your conditional CSS:
<meta name=”viewport” content=”width=device-width, initial-scale=1.0"/>

For example, in ClickHelp, you can use global or project settings to specify any number of custom meta tags which will be appended to the <head> section of your help topics. And if you want to learn more on the magic tag and the problems it solves (like virtual viewports and pixels which are not really pixels), you can find more information here: 
The Viewport Metatag (Mobile Web Part 1)
Using the viewport meta tag to control layout on mobile browsers

Responsive HTML Tutorial — Summary

Now when you have the tools and learned some theory, you should be ready to adapt your content for different screen sizes. However, some specific tasks like creating responsive navigation elements can still be tricky, so we are going to help you with them too at some point — keep an eye on this blog.

Good Luck,
ClickHelp — Professional Help Authoring Tool