Lessons Learned: Component Based Design with Paragraphs

Anthony Simone


Senior Developer


Welcome to BADCamp! I work for Elevated Third, a digital agency based in Denver, Colorado.


  • Introduce Atomic Design and component based design principles
  • Discuss component based design within the context of Drupal
  • Examine patterns for successful implementations of the Paragraphs modules
  • Review tools and best practices for theming and frontend execution of your design system

Design Systems

Atomic Design and Component Based Design Systems

Atomic Design Principles

  • Brad Frost's Atomic Design
  • Create highly defined components
  • Start with the smallest pieces available
  • Implement components consistently
  • Assemble small pieces to make larger ones
  • Reuse

Modular Patterns Within Drupal

  • Entities and view modes
  • Fields and field formatters
  • Paragraphs module

Implementing a Design System

Design System Stage Implementation
Intention Wires and designs
Structure Data architecture and site building
Execution Presentation and theming

Content Architecture

  • Architecture tightly couples a design system and its implementation
  • So who's responsibility is this?
    • IA/UX?
    • Back end developer?
    • Front end developer?

Types of Content

  • Structured
    • Event - date, time, location, multiple instance, categories, speakers, sponsors
  • Unstructured
    • Old School - WYSIWYG free for all
    • New School - Build some kind of system around your "unstructured" content

Requirements to Implement Component Based Design in Drupal

1. Structure

  • Entity system handles structured content very well
  • Unstructured content is left to handle on your own
    • Field groups, field collections, paragraphs, panels, custom entities, IEF, custom blocks, mix and match
  • Component based design requires defined structure
  • Paragraphs module! 🎉

2. Controllable Markup

  • Must be able to implement whatever markup patterns you need
  • Patterns should be consistent and easily repeatable
  • Render view modes of entities all the time

3. SASS Framework / Theming

  • The design system is only as flexible and extendible as the organization of the styles backing it up
  • Implement strict selector targeting patterns
  • Strongly leverage your preprocessor to help keep your CSS well organized based on the rules set

Who's Responsibility is the Design System?

  • The frontend developer
  • A design system:
    • Is based on UX goals and design requirements
    • Is implemented by modular CSS/JS
    • Depends on well structured content architecture
  • We aren't architecting data models, but a content system
  • A front and back end developer cannot work independently and expect a cohesive result

Implementing Paragraphs

Paragraphs Examples

Paragraphs Module

  • Simple tool
  • Custom arbitrary entities
  • Very open ended

Consider Your Implementation

  • No rules around this tool
  • Incredibly flexible
  • Opportunity to create a well structure system as well as an unorganized mess
  • Most important part about using the Paragraphs module, can be very challenging
  • You have the power! (...and responsibility)

Create Your Component Framework

Well Defined Paragraphs

  • Design systems require well defined components
  • Clear intention or responsibility
  • Use those definitions to help determine if future functionality should extend existing components or create new ones
  • Make your own rules... and then follow them!

Bundle Hierarchy

  • Implement your own "paragraph types"
  • Add keyword classification in label and machine name
  • Primary keywords - Simple, Compound, Layout, Slideshow, Summary, Header Banner ...
Keyword Role ie - Label ​ie - Machine Name
simple Lightweight group of fields with little opinion about how it's used, very often used as nested component Simple - Content ​simple_content
compound More opinions about structure and layout, often more composition Compound - Media Bar  compound_media_bar
layout Very highly opinionated structure or functionality tied to component, rarely nested inside other components Layout - Tabs layout_tabs

Simple - Content

Compound - Media Bar

Layout - Tabs


  • Create a taxonomy or syntax for designers, developers, and admins to talk about components
  • Implement patterns
  • Use terms consistently to create patterns
    • Card, Bar, Callout, Content, Teaser ...
  • Name based on intention or purpose rather than exact functionality
    • `Content Bar` v `Two Column 2/3 Width No Header`

Building Your Paragraphs

Bundles and Fields

  • Separation of concerns
    • Definition and implementation are separate
    • Easy to extend and modify functionality
Paragraphs Bundles Paragraphs Fields
Definition Implementation
Owns responsibility or intention # of paragraphs allowed
Owns structure (content fields) Types of bundles allowed
Theme definition Functionality (ie - slider, gallery)
Simple - Content (simple_content) field_p_content

Paragraphs Bundles








Paragraphs Fields





The main component field on this landing page.


The items allowed in this component.


The media feature for this component.


The content feature for this component.

Bundles & Fields
















Functional Components

  • Sliders
  • Galleries
  • Tabs
  • Accordions
  • Interactive features
  • Custom views displays
  • Curated content with custom queries
  • Nearly no limit to what a paragraph can do

Theming Patterns

Components are Modular

  • Components have an identity
  • Drupal is already very good at creating these identities for you
    • Entity types
    • View modes
  • Isolate theming - very clear to extend and create new functionality

Components are Self Contained

  • Placeable anywhere
    • IE - a paragraph placed via a field on a node should behave the same as one placed in a block
  • Paragraphs previewer module

Isolate Component Theming

  • Theming and styles should target components in a very consistent, explicit pattern
  • Handle ALL styles for each component within its entity class wrapper
  • Forces you to really think "Where is the responsibility of this style coming from?"
  • The component? A relationship? The implementation? Context?
.paragraph--type--BUNDLE-NAME {
    // Styles go here for items in this component only
    // Every paragraph bundle should be handled this way

Common Component Theming Patterns

Base styles

  • Start with some base styles, extend where necessary
  • Remove paragraphs field wrappers when appropriate
// Content like field for components on a landing page
.field--name-field-p-content {
  & > .paragraph {
    margin: 60px auto;
    padding: 0 30px;
    max-width: 1000px;

// Specific component with background color
.paragraph--type--BUNDLE-NAME {
  .field--name-field-p-content & {
    margin: 0;
    max-width: 100%;
  background-color: green;
  .component-wrapper {
    margin: 60px auto;
    padding: 0 30px;
    max-width: 1000px;

Component Styles

  • Handle ALL styles for each component within its paragraph entity class wrapper
  • Leverage your preprocessor to make this easy to manage
  • This will make adding variations and extending functionality in the future simple and clear

Contextual Styles

  • Moving past basic theming can start to get complex
  • Having a system in place keeps it well structured and organized
  • Neighboring items
  • How it is being used
  • Nesting state

Contextual Styles

Neighboring Component Interactions

// Handle standard spacing for items with or without bg color
.paragraph {
  // With the same bg color, collapse the padding
  &.with-bg.bg-color-light-gray {
    & + & {
      padding-top: 0;

Contextual Styles

Nested Components

.paragraph--type--simple-content {
  h2 {
    color: blue;
    .paragraph--type--compound-media-bar & {
    color: orange;

Contextual Styles


.paragraph--type--simple-content {
  .field--name-field-p-content & {
    @include content-width(narrow);

Complex Paragraph Component Usage


  • Functional content component (accordion, slideshow, gallery, etc...)
  • Easy to handle custom markup within paragraphs
  • Leverage paragraph view modes








Tab Components

View Modes

Summary / Custom View

  • Give the content admin more power and control over referenced content displays
  • Field a paragraph to accept user input and model these rules in whatever way you need
  • Flexible custom view component!

Super Link Field

  • Extend functionality that may not otherwise be straightforward to implement or manage in Drupal
    • `field_p_link`
  • Define the paragraph bundles that can be used
    • Simple - Link
    • Simple - File
    • Simple - Video Modal
    • etc...
  • Functional behavior is tied to those child paragraph components and adding new ones with completely different behavior and requirements is simple!

Flip Card

  • Leverage paragraphs fields to increase the flexibility on an implementation
  • Limit the front and back of the "Flip Card" to different components
  • Allows extending the functionality to only require new component definitions, not tied to fielded data

A Note on Deeply Nested Paragraphs

  • Complexity can increase quickly
  • Nesting paragraphs is not bad, but you MUST have an appropriate intention for doing so
  • EVERY component and field does not need to be necessarily the most flexible it can be
  • Balance client needs, flexibility needs, content admin UI, experience of content admins to make these decisions.
  • There isn't always a single correct solution.

Readable, Extendable, Modular

  • Extend existing components
  • Features and variations are well defined and implementation is well structured
  • Manage, update, edit styles with confidence
  • Easy for other developers to know where to look
  • Add new components for new functionality

Thank You!




Lessons Learned: Component Based Design with Paragraphs

By Anthony Simone

Lessons Learned: Component Based Design with Paragraphs

  • 2,056