We are making widgets for a corporate website and I'm trying to figure out the best way to describe them. Something like writing a documentation.

There are at least 10 of these, but here is one component structured for example:



  • Containers component is designed to show mixed content like text, image or button.
  • Container can be split in one, two, three, four columns
  • Container can have other components inside itself:

    • for example: if you make a container with background image, content inside will still be distributed by columns and rows (like table)

    enter image description here

VARIABLE ELEMENTS: Number of columns, content of each column. Text, image, button and other component (other component can be for example slideshow)

EXAMPLE: [we provide screenshot here]

LINK: [we provide link to a prototype]

Is this enough descriptive? What can I do to help developers understand better?

  • I think it would be a good idea to look at some of the design systems that are published and widely used to give you an idea of where to start. Bootstrap and Material.io are very good places to start.
    – Michael Lai
    Commented Jul 10, 2018 at 0:21
  • Those are nice examples to have in mind. We are making custom solutions that are more complex, like website builder with specified purpose. Any resources with more complex components? Commented Jul 10, 2018 at 10:22
  • You probably won't find a lot of complex UI elements in the standards (since they are customized elements which means they are not standard), perhaps with the exception of things like dashboard widgets. But I think the example that you provided should give plenty of details. I am not aware of standards that are used to describe complex layouts and widgets because they are not generally reusable.
    – Michael Lai
    Commented Jul 11, 2018 at 1:15

2 Answers 2


I'm not a developer, but seeing your example, I have the following questions and comments:

  • First, what is the main purpose of the component from a user point of view? In my experience, developers prefer to know why they should do x, y, z, not just execute requirements without understanding. Plus, when they know why they're doing it, there are fewer risks of misunderstanding on other specifications.
  • In which context will this container be used? (Is it part of a page,...?)
  • In the illustration, the container is split into 3 rows, not only columns: how many rows could a container have?
  • Is the image always the background for the entire container, or could it be only in one row / column / cell?
  • Is there any minimum / maximum criteria: dimensions, number of components, in addition to the max number of rows and columns?
  • The complete list of possible components that can be included into the container should be provided, not only examples.
  • If there are any conditions / limitations associated with a component being included into a container, they should be listed too.
  • Developers are familiar with what they are building. But its up to us (ux designers) to make components and define them. What we ended up doing is describing element briefly, describing variable elements (like when you describe database fields) with screenshots and links to live prototype. Commented Jul 10, 2018 at 10:11

I guess there is no real solution to this problem. What we did is, we made a table with columns: component, short description, variable fields, screenshot examples, link to prototype. Now we have A3 landscape document that links (using bookmarks) related components and describes them.

Example of one component:

  • Component: Tariff
  • Short description: Tariff component is designed to show multiple tariff packages.
  • Variable fields:
    • Featured(true/false)
    • Package name and package type
    • 3x Custom fields
    • 'see details' button name
    • discount
    • price
    • buy button
  • Screenshot examples:
    • enter image description here
  • Link to prototype: live demo link

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.