Lessons Learned: Component Based Design with Paragraphs

Anthony Simone

https://slides.com/anthonysimone/paragraphs

ANTHONY SIMONE
Senior Developer

asimone@elevatedthird.com

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

Goals

  • 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

Naming

  • 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

(definition)

simple_content

compound_content_bar

compound_media_bar

simple_image

simple_content

simple_card

Paragraphs Fields

(implementation)

Text

Text

field_p_content

The main component field on this landing page.

field_p_content_bar_items

The items allowed in this component.

field_p_media_item

The media feature for this component.

field_p_content_item

The content feature for this component.

Bundles & Fields

Fields

Bundles

field_p_content

simple_content

compound_media_bar

simple_content

simple_image

field_p_media_item

field_p_content_item

compound_content_bar

simple_card

field_p_content_bar_items

simple_card

simple_card

simple_card

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

Implementation

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

Complex Paragraph Component Usage

Tabs

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

field_title

field_description

field_p_tabs

compound_tab

tab_button

tab_content

Fields

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!

https://slides.com/anthonysimone/paragraphs

asimone@elevatedthird.com

Questions?

Lessons Learned: Component Based Design with Paragraphs

By Anthony Simone

Lessons Learned: Component Based Design with Paragraphs

  • 2,133