Diamond UI

Bring clarity to
your components

Diamond UI is a methodology for teams who build interfaces.

You’ve heard of Atomic Design, right?

There's also BEM, SMACSS, OOCSS, Tailwind, we've tried them all! But after years of building interfaces, we’ve found a more intuitive way to define components and organise code.

Let us tell you about another way to build interfaces.

The methodology in a nutshell

Each component is created with a single concern from one of four areas of responsibility.

Content components look after the general styles for text and images, but can extend to data-specific patterns such as user profiles or product information.

Examples

  • Heading – title elements, represented in HTML as h1-5
  • Text – a piece of typographic content
  • Icon – a glyph representing something in the app ecosystem
  • Data-specific – a user profile or product summary
 
<h2>Title</h2>
<p>A paragraph of text.</p>

Controls are interactive elements of the page. Anything that can be clicked, dragged, typed into or accessed in some way with the mouse, keyboard or touch is a control.

Examples

  • Button – a clickable component that triggers an action, such as submitting a form
  • Link – a hypertext link that takes the user to another page or section of the app
  • Input – a form input that allows users to enter information
 
<h2>Title</h2>
<p>A paragraph of text.</p>
+ <button type="button">Action</button>

A canvas represents a part of the page that content and controls sit within. Canvases provide padding and backgrounds for their content area, but do not dictate any other layout constraints.

Examples

  • Card – a flat box, often containing an image, title, text and a call to action
  • Header – a floating element at the top of the page, containing the logo and main navigation
  • Hero – the first element in the main content of the page, containing the title and intro
 
+ <div class="card">
    <h2>Title</h2>
    <p>A paragraph of text.</p>
    <button type="button">Action</button>
+ </div>

Compositions are an invisible element of the page that provides layout. Compositions are solely concerned with creating structure and spacing.

Examples

  • Grid – a layout with grid cells arranged in columns and rows
  • Spacing – adds spacing between components or areas of the page
  • Container – sets a max width for a page, block of content or components
 
+ <div class="grid">
+   <div class="grid-item">
      <div class="card">
        <h2>Title</h2>
        <p>A paragraph of text.</p>
        <button type="button">Action</button>
      </div>
+   </div>
+   <div class="grid-item">
      <div class="card">
        <h2>Title</h2>
        <p>A paragraph of text.</p>
        <button type="button">Action</button> 
      </div>
+   </div>
+ </div>

It’s pretty simple, but that’s the whole point!

The four Cs set clear boundaries between component responsibilities.

Are your components overcomplicated?

As a product scales, even the most carefully crafted components can get out of shape.

Components can become:

  • Bloated with props – too complicated
  • Updated every time a new design is handed over – too specific
  • Hard to test – too many variables
  • Awkward to maintain – too much time
  • Conflicting or impossible prop combinations – too specific
  • Unsuitable for emerging needs – low reuse
  • Difficult to understand – too scared to touch them
  • Not composable.

Diamond UI helps avoid this.

 
<page-hero
  title="Page title"
  intro="Lorem ipsum dolor [...etc]"
  button-text="Main action"
  button-url="https://another.site/page-slug"
  button-target="_blank"
  button-rel="noopener noreferrer"
  button-style="secondary"
  theme="grey"
  eyebrow="Eyebrow text"
  eyebrow-tag="h1"
  title-tag="p"
  secondary-button="Secondary action"
  secondary-button-type="button"
  secondary-button-style="secondary"
  on-secondary-button-click="handleButtonClick()"
></page-hero>

Diamond UI keeps your components clean.

By separating responsibilities, we create reusable components that can solve future problems before knowing they exist.

When following Diamond UI methodology:

  • Components stay small and easy to understand.
  • It’s clear when a component is trying to overstep its area of responsibility.
  • With minimal onboarding, developers can quickly understand where to find each type of component.
  • The methodology does not dictate any technology or naming constraints.
 
<dx-grid>
  <dx-grid-item>
    <dx-heading>Title</dx-heading>
    <dx-text size="lg">A paragraph of text.</dx-text>
    <dx-button type="button">Action</dx-button>
  </dx-grid-item>
  <dx-grid-item>
    <dx-img 
      src="image.webp" 
      alt="Description" 
    />
  </dx-grid-item>
</dx-grid>

It pays you back.

When maintaining components that were built with Diamond UI:

  • There are fewer output variations, so components are easier to test.
  • Components use simpler interfaces that are less prone to prop bloat.
  • UI can be constructed in thousands of component combinations to suit the context.
  • When compared to a utility-first framework, components retain human legibility whilst staying flexible. 
<dx-hero>
  <dx-heading>Title</dx-heading>
  <dx-text size="lg">A paragraph of text.</dx-text>
+ <dx-grid>
+   <dx-grid-item>
+     <dx-button type="button">
+       Action
+     </dx-button>
+   </dx-grid-item>
+   <dx-grid-item>
+     <dx-button type="button">
+       Secondary action
+     </dx-button>
+   </dx-grid-item>
+ </dx-grid>
</dx-hero>

It's about clarity, not perfection.

Software products are never finished. Features can always be improved.

Diamond UI makes it easy to see where your interface changes will take effect. Giving you more confidence when developing your product.

Diamond UI is

  • A helping hand to guide teams when creating interfaces
  • A rather simple, yet potentially transformative way of building interfaces
  • The outcome of decades of building complicated interfaces

Diamond UI is not

  • Another UI pattern library
  • A silver bullet…defining and naming things is always tricky
  • The next big thing in “design systems”

Interested in trying it out?

New is exciting, but it comes with friction – we realise there’s more to explain.

Guide

How to get started and use Diamond UI on your next project.

About

The short story of Diamond UI and how it came to be.