How are spacial relations between components documented by the big design systems? They only seem to explain how the components look and behave in isolation, not in relation to each other.

For example, if I have an H1 followed by a paragraph, I would like the distance between them to be 40px. On a different page I have an H1 followed by an image, in which case I want the distance to be 30px.

For different combinations of elements I want to define different distances. I want to document these combinations so that designers and developers don't have to figure this out each time and there is more consistency between pages.

For developers this could be documented in css. Designers typically don't see that. How should these rules be communicated to design teams so they use the appropriate spacing between components in their designs?

What is the best method to communicate / document spacial rules between components to designers?

  • Style guides are a common practice, especially for components with specific exceptions, such as titles with "dynamic" distances. I don't see how else you would be able to communicate this properly.
    – user68158
    Jun 11, 2018 at 14:02
  • @Levano yes agree from a development perspective. Have updated the question, am interested in ways to communicate to designers so they apply correct spacing.
    – Martyn
    Jun 11, 2018 at 14:20
  • Whenever our design teams have a very specific set of design rules to adhere to, we also create styling guidelines, preferably by Wiki's. These online documents are communicated to every designer and leading during every task.
    – user68158
    Jun 12, 2018 at 9:38
  • @Martyn The Style Guides I believe Levano is referring to aren't necessarily (or, at least, not exclusively) for developers (or "from a development perspective"). They wouldn't be a bunch of CSS; they would be (probably pictorial) representations of the rules you've described: examples of combinations of differing components, with min/typical/max distances between them; how sizes of adjacent components should match etc. and notes of any exceptions to the general rules therein.
    – TripeHound
    Jun 12, 2018 at 15:25
  • Exactly, @TripeHound
    – user68158
    Jun 13, 2018 at 8:27

7 Answers 7


This is a great question that highlights a gap in many articles and conversations about design documentation and pattern libraries. By and large, they’re visual designer-centric and focused on atom and molecule components in isolation. To be useful in practical application, design documentation should explain what to do when and why across a breadth of different examples.

This H1 example is perfect for illustrating this point. (I’m deliberately writing pseudo-styles and not valid CSS selectors or attributes because my assumption is that this question is about how to communicate conventions, NOT about how one can technically achieve the different conditional behaviors.)

H1 Headers

Notes: Use sparingly. Adjust white space according to adjacent design elements. 

Font: Helvetica
Font Weight: Bold
Size: 28px
Line height: 32px
Bottom Margin: 
   IF (followed by paragraph text) THEN 
      15px and show a visual example
   ELSE IF (followed by an image) THEN
      30px and show a visual example 
Letter spacing: 1px expanded

That’s my $.02. Design documentation is already a message in a bottle, but without practical and explicit examples it forces people to make their best guess as to what to do.

**Edit to add an example I found **

This article does a great job unpacking the use of space with intent within design systems. The author deconstructs some pattern-based design elements (in this case cards with content) to show the different conditional rules that are being employed:

Image annotated to describe element spacing and identify rules in use

From the article:

Most collaborators can’t see space, a primary reason it’s so arbitrarily applied.

enter image description here

In sum: design documentation meant to support disciplined reuse of patterns should be written with that in mind. User-friendly systems illustrate what to do and when using practical, well-annotated examples.

  • Thanks, I agree it's a gap. Very curious to find out what this community has to say about it.
    – Martyn
    Jun 11, 2018 at 18:21

You shouldn't define the padding and margin in the smallest element of your system. A most important property of an element is the attributes unique for that element type, for example for a heading (h1. h2 etc) or any text element, important attributes to communicate is the size and the color of the text.

You should define the spacing in more complex situations, where multiple elemets interact with each other, let's call them "components".

In any given app or website you would have multiple components with different behaviors, those components might look very similar with just small differences, you should document each specification of these components.

In your case you have a content component with text (text_content_bloc) and content components with an image (image_content_bloc), you should document these blocs individually (if there are visual differences like the padding of h1 )

Design systems are living organisms, you will never complete a system and move to the next one, it needs maintenance, iteration and time to time cleaning.

Few good examples of components:



PS: In my experience best systems are the systems with fewer exceptions, if your h1 that have 100 different paddings, you should try to simplify your system, make it more consistent

  • 1
    +1 some good points made in your answer, it is hard to strike the right balance with these things... but a good design should be simple and consistent as you say :)
    – Michael Lai
    Jun 13, 2018 at 22:40
  • I also like this answer because it calls into question the underlying motivation to include exception and edge cases in documentation at all. A design system that is not simple and has conditional exceptions may defy adoption. So the real problem may be upstream.
    – Luke Smith
    Jun 18, 2018 at 2:21

You could use the adjacent sibling combinator

/* Paragraphs that come immediately after any image */
img + p {
  font-style: bold;

For your case you could add a margin to the paragraph or image.

h1 + p {
    margin-top: 40px;

h1 + img {
    margin-top: 30px;
  • Yes, am familiar with this implementation but am wondering how designers do this. I've not seen any design system mention these rules on their documentation.
    – Martyn
    Jun 11, 2018 at 13:30
  • @Martyn to place constraints on designers would be a nightmare for them! A visual/UI designers want to be free of constraints (within reason) while developers want to put constraints (again within reason), and the UX designer is stuck in the middle trying to work out how much is too much/too little :D
    – Michael Lai
    Jun 13, 2018 at 22:39

It would be helpful for designers to see a visual application and examples of the design pattern. You could explain how the spacing is derived (percentage of x element etc) and also the rationale and context of use.


CSS has a hierarchy, when applied correctly, the language has had what you're asking for built into it for a long time now.

A combination of:

CSS Selectors : https://www.w3schools.com/CSSref/css_selectors.asp


An understanding of CSS hierarchy: https://en.wikibooks.org/wiki/Cascading_Style_Sheets/Applying_CSS_to_HTML_and_XHTML

Will let you "cascade" your styles across a project, it's as easy as adding an ID field to your forms and locking down your selectors to specific sections or having top level selectors affect the entire site.

To go deeper, you have templates, containers/master pages, and directives/user controls that are used to enforce consistency (again from a technical standpoint).

  • 2
    This answer touches more on implementation than UX Jun 13, 2018 at 6:26

I think this comes back to the intent of the design language/systems that have been created and what the limitations are with documentation.

The biggest hurdle with trying to document details like the one regarding spacing that you have highlighted in your question is to be able to come up with a consistent rule that applies to all different potential scenarios. Perhaps when you put all the spacing rules for individual components together it doesn't make in all cases, but if you create too many rules then it is probably easier to provide general guidelines and leave it to the hands of the designer to apply them in a practical if not consistent manner.

You'll be surprise how interactive some of the design systems actually are. For example, the Carbon Design System is integrated with CodePen so you can actually try and play around with the styling and customize it to your own needs.

Other design systems specify general guidelines for application layout like the Clarity Design System so you can see how major components on a page might be laid out.

I think the main reasons why these types of detail are not specified are:

  • They can restrict the design of the layout to the extent where problems with alignment and positioning becomes problematic (since grid systems are not normally pixel specific to be responsive to the size of the page on different devices).
  • They can be difficult to maintain depending on the number of components that you have and the combinations that are used or potentially used, of which most design systems generally have a reasonably large number.
  • It can be difficult to make things work across the whole design system when components are no longer used, replaced or combined with legacy components

But luckily this is where designers can come in and help smooth out these issues by working with the developers that start off with page templates and general guidelines for the components, so that there isn't too much adjustment to make for the developer.

In terms of effort versus benefit, I think existing design systems have the right approach and balance when it comes to the level of detail that is specified in their documentation.


Let's leave CSS aside and talk about the visual design. I assume a website has a reasonable number of the page types: landing, product description, dashboard, etc.

a. Include the distance information into the page template. I would create a couple of template pages, that show the specific distance between the H1 and the image/text. For instance, landing page can have 4x between the H1 and image and 2x for the text.

b. Include the distance information into the element template. Specify the top-margin of the image for every image size. I guess, there should be some layout-specific image sizes, e.g. hero-image, product-main, product-secondary etc. In this case, I'd create a group consisting of an image and a transparent rectangle on top of it, so it will be easy to build the mockup from the pre-defined blocks.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.