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,118