Spacing and Pattern Structure in Visual Specs & Code

Objectives

All patterns and 'blocks' in IBM.com Library, including the spacing between them, should be simple and easy to understand, fun to use, self-contained, easily stackable, and possible to re-order + re-use, with the least amount of variables and overrides to accommodate special cases.

This research will explore options for Top Down, Bottom Up, or Collapsible Margins in spacing, examine the relationship and naming of respective patterns, and try to create a map and structure that includes pattern names, hierarchy, spacing between them and overall process or system to follow.

Goals

SIMPLICATION EASE OF USE PLAYFULNESS LESS TO THINK ABOUT

Notes

In order to support designers and developers to create an intuitive system between them, and a system that is easily understood and used by adopters, we need to identify and communicate an intuitive system that is coherent from top to bottom with spacing, naming, design and code.

Problem

Original visual specs added padding on top and bottom of patterns, creating need to use margin collapse to accommodate for too much padding between two patterns. Unclear if this resulted in best structure for both design of patterns, the specs, and code.
-Difficulty creating visual specs per pattern, that intuitively and easily fit into overall pattern stacking methodology
Difficulty in QA with current margin collapse method, of figuring out what margin is applied, from which pattern
Difficulty with lack of implicit hierarchy in naming and pattern setup, confusion with generic, somewhat duplicated naming

Additional Information

This issue is for starting research work. More stories may be addded.
- Box Note recording notes as this project evolves: https://ibm.box.com/s/r3ri6uk8z8vzmkjq8nto1x8f0alwoh3n
- Spacing folder on Box for relevant documents: https://ibm.box.com/s/ef3tsu1yab4jdsuvvg97gtzm9s1iwhnd

Tasks

Map out ideas for mix of patterns and spacing using the Learn template as first source
Iterative review and meetings with relevant designers and developers
Revise map, naming, spacing and overall system based on iterations
Develop a rough final map and associated Box note to review with broader team(s)
Determine the revisions needed to the visual specs and schedule the work included in the ibm.com Library board issues (#1525). (#1526) and (#1533)

Process Documentation

Notes during process, as work progresses.

https://ibm.box.com/s/xmt2zdw6fpeggcb6yre00ie57tney97s

Met with Wonil, Jeff, Lara, James. Reviewed latest mapping Sketch file, with both atomic design approach and with current setup of ontology and patterns. Will work more this week, and reconvene next week.

A few notes:

Wonil: If using atomic design system, each element needs to stand on its own. And the parent needs an override system, to handle own spacing.
Decided to explore having a set top and bottom padding for any given child pattern, where the parent overrides and sets that padding to zero, and defines all of its internal padding between the overall patterns (Jeff will review with engineering team)
Seth will try to come up with some examples of this setup to share
Jeff said he's thinking about having a sandbox environment that could help show complete pages using all the patterns, and allow re-arranging the patterns to test and explore new page layouts using same patterns from Learn or Solutions (TBD)
James and Lara are tackling aspects of naming and ontology, Seth will pass link to Box note

Wonil created folder to hold these documents. Seth moved Sketch file and Box note into folder, located here: https://ibm.box.com/s/ef3tsu1yab4jdsuvvg97gtzm9s1iwhnd

Started new layout of full atomic design mental model, including Template and Page levels (visual examples to be added later), and showing the latest concept for spacing and pattern structure
Key point to review asap: a global rule that applies to all levels of this design system, in a connected way, from template all the way down to the smallest pattern elements
The rule in consideration: Every "Cell" has set padding on top and bottom, and would be reflected in respective visual spec, and how it appears in Storybook code. However, when that pattern is placed into a parent like ContentBlockSegmented, the top and bottom margin / padding is set to zero, in order to cleanly and transparently allow the parent to define all padding between its children (this may become more nuanced, where the parent can override any top and bottom padding. it depends on how exacting we want confidence level for source of spacing at each level).
Showed and discussed this initial latest work to Wonil, Lara, Olivia, Jacob, Jenny, Jacob in design review. There were some questions as to how this might affect overall system and that it deserves close study
Wonil asked to share this with Reboot team, and this was done late today. Shixie replied so far
Jeff noted that he reviewed and has some notes on technical feasibility side of this idea. Will likely share notes on Monday
Will meet with James early next week to review this work and see what flags come up from code / dev side, and try to absorb and adjust

@wonilsuhibm

Notes: 5/11

Met with Wonil and Lara late in day. Reviewed spacing and overall pain points with patterns and tasks between DDS and Reboot.

Latest resolution for spacing:

For all patterns: Zero top and bottom padding by default (ie no safe space)
Per pattern, padding is defined between its interior items
This is essentially single-direction margin declaration model, using Top Down approach, where between patterns, "margin-top" set to zero and all focus is on setting "margin-bottom".
This will allow any view or analysis of a pattern, no matter how complex, with ability to know exactly what the spacing is between elements and how it is defined.

Discussion on Naming / Ontology / Organization:

Lara is suggesting split of workstreams between DDS and Reboot, and could apply to what level of complexity each team is working on. For example, DDS creates all core parts of IBM.com, ie Atoms up to Cells, and Reboot develops the Organism and Template levels for adopters, that use all of IBM.com Library pieces.

Discussed idea of DDS or Reboot creating a tool that allows the IBM.com Library core patterns to be put together into test groups and templates, also for DDS to confirm the Library and overall system design is sound.

Seth will split up "Atoms' level of atomic breakdown analysis, to separate items within this column from Carbon or ones created by DDS for IBM.com Library.

Notes: 5/12

Split of "atoms" level into Carbon and DDS items was shared with Lara and Wonil. Notes:

Lara: The top level labels: Atoms, Molecules, Cells, Organisms need to be replaced by our terminology. We may not know the right answer yet but the way I see it we should be able to try and replace these with Elements, Components, Patterns. Seth: Yes, the atomic naming and pattern naming are mostly to support a way to look at and organize the pieces based on complexity and one level of complexity feeding into the next one up the chain.

Todo:

Discuss and figure how and if atomic mapping and hierarchy can be reconciled within IBM model of Elements, Components, Patterns

Notes: 5/14

Created and shared comparison of current Carbon naming and definitions with IBM.com Library with DDS and Reboot, as leads decide on next steps. Also reconciled atomic mapping exercise with how Carbon organizes and defines their structure, using split of Elements, Components, Patterns categories. This version maintains atomic split within analysis, using filler variable naming of sections like XXXXXX, YYYYYY and so on, to compare with Carbon style structure and breakdown.

Notes:

One challenge of the IBM.com Library system seems to come from trying to fit a square shape (IBM.com Library) into a circle hole (Carbon), with attempt to exactly match the organization and wording
It's hard to tell the two systems apart, when they use the same titles but not always the same usage: Elements (Guidelines), Components, and Patterns
At the base level, the equivalent category of Guidelines / Elements for Carbon includes all of its lowest atomic level pieces, guided by IDL
Difference: with IBM.com Library, its lowest level of atomic level pieces combine Carbon Elements, Components and items created by DDS team for IBM.com Library
The current IBM.com Library "Patterns" seem too broad and divided into subsections like Sub-Patterns, Blocks and Sections to fit within single Carbon definition of "Patterns". Closest equivalent in IBM.com Library to Carbon Patterns are the ContentBlocks, the particular groupings of IBM.com Library pieces to help enable the Drupal team templates now (TBD if they have application across IBM.com)

Awaiting input on next steps from DDS and Reboot leads.

Notes: 5/18

Met with James and Jeff re: questions on spacing resolution from 5/11, for technical review / input.

Jeff suggested that it would be difficult to have only zero padding on top and bottom of patterns, leading to requirement for adopter to set the spacing between larger level patterns on their own. We could provide guidelines for this spacing, but might lead towards too much inconsistency on pages.

He suggested creating a vertical rhythm class that would most likely apply a specific bottom margin height for all elements on a page, based on intention for the Template or Page, ie a Short, Medium, or Long, or Small, Medium, or Large. This is similar to 5/4 idea to set a variable that template and patterns read in order to set their spacing.

In this setup, the adopter would be able to select the vertical rhythm desired for the page, either at pattern or page / template level, based on a preset number of options. Their selection would automatically adjust across responsive states for all patterns.

Notes/ Questions:

For ease of use and simplicity, vertical rhythm would be set at higher complexity levels of patterns, ie between largest pattern blocks at template / page level, otherwise set and locked at lower complexity? Or across the board? Needs discussion / review.
Easier and more consistent for adopter to set vertical rhythm for every pattern, or just in one place, at per template / page? A guess is template / page level is easier, with cascading logic to all patterns.
If set at pattern level, the visual specs would show a default, most often used setting, ie Medium. If set at page / template level, the visual spec for each pattern would show zero padding.
How many levels of vertical rhythm would be best? Is three good? Needs exploration, testing and demos with both visual and code.
Guidelines for IBM.com Library would likely need a page about "Vertical Rhythm", outlining the final settings, ie Short, Medium, and Long, using example templates and patterns to show how these selections change the look / feel.

Notes: 5/20

Created a graphic to help explore and resolve vertical rhythm / spacing. using "Page Length" as a simple variable at first, with following definition, as if it is a UI tool choice: "Sets the vertical spacing between items on the page, based on the length of your story". Short, Medium and Long are the choices. This is similar to how Squarespace works, allowing user to set overall vertical heights between elements making up a page layout (Lara shared how their UI works)

Page Length (or another title TBD) would at first be set at code level, though the UI style setting could eventual be used in a web app tool designed to help adopters build and test templates with existing IBM.com Library patterns.

The diagram continues to use the temporary atomic breakdown and naming, to help see every piece clearly defined, towards establishing universal spacing "equation" of sorts. The atom level is skipped (not really relevant).

Shared with Lara and Wonil, also James and Jeff. Feedback and a meeting with all is needed to establish how this "equation" or system can best cascade structured spacing logic across all (or some) patterns in a layout / template.

Side Note: Lara wondered what happens if an adopter winds up making a very short Learn page...does it wind up with Short spacing? On related note, via feedback, an Art Director from MSC asked how this setup could be adjusted to stop gaming the system. For example, what if an adopter stacks many patterns on a page but selects the Small page, in order to keep all page elements vertically close. This is a frequent problem from IBM marketers prioritizing marketing over design, crowding content for SEO or being closer to top of page.

Potential solution: the design system quantifies and understands how many patterns are placed on a given page / template, and based on those quantities, disallows Small, and then Medium, as certain total number of patterns are placed on a page. In a UI example, the system could present a modal window alerting user when they try to add another pattern beyond set limits, their page length will switch to another setting if doing so. Quantifying and establishing these ranges would require a tool to create sample pages using the existing patterns, with ability to plug in max or min content in each pattern. Then we could pretty easily evaluate averages for what makes a Short, Medium, or Long page definition.

Notes: 5/21

Some confusion as to core focus and goal of setting a spacing variable at page / template level.

Seth called it Page Length, with variable set as Small, Medium, or Long, using Learn page as an example, which is a long, reading and narrative centered page. So it's spacing design would fall into a "Long" page.
Lara has questions around whether this is confusing to use page length (short, med, long) versus page intent (learn, solutions, navigation).
Jeff calls it "vertical rhythm" and would be a class in the code base
"Page Length", "Page Intent", "Pattern Height", "Vertical Rhythm". It could be named anything. At core, it is a variable, likely set at Page / Template level, dictating specific spacing applied between patterns. The variable may affect only higher complexity patterns and spacing between them on the page, like "sections" or "blocks".
Some confusion as well from using atomic analysis for the mapping / analysis
Challenge of using current ontology: the spacing variable would need to simultaneously affect Block and Subpatterns, or Section and Block, in order to execute spacing. It's hard to analyze, hard to talk about. The nesting and organization in ontology is a blocker.
Atomic mapping allows a clear look, left to right, at every element in patterns defined, from least to most complex, and respective minimally complex nesting, to try and see what spacing a variable would affect, versus what spacing is fixed at all times, no matter what template or length of page.
James has questions about how zero top and bottom margin as default on patterns would allow for showing background. Seth is confused what this means.

Also some confusion as to overall mission for IBM.com Library: are the patterns supposed to be agnostic, like Carbon, able to stack in varying patterns in exploration, with simple optionals to turn on or off, in trying to create a given template? Is the idea that the patterns are possible to stack and adjust, creating the Learn or Solutions templates, but also other potential templates?

This work is operating under that assumption, to design agnostic spacing logic that can cascade across any template. But it may be the wrong assumption and mission for the library.

Waiting on feedback from Wonil, Lara, James, Jeff. Project has varying levels of confusion in need of clarity. Focusing meanwhile on other ideation task of universal visual spec format.

This story is at a point of a few blockers. 1) team is so busy...hard to absorb input from design + dev 2) no time on calendars for this group to meet in less than week's time 3) pending ontology work will likely have effects on spacing

Some progress has occurred since starting, but achieving goals of work remains elusive. Pausing meanwhile and will work on other Ideation stories.

@sethibm Thank you, Seth. Let's hold off on spending any more time on this ticket, and please focus on the other stories, starting with the spec standards story.

Here is what I gathered fro many team members, a proposal to discuss in a meeting today: https://app.mural.co/invitation/mural/wonilsworkspace4185/1592401555547?sender=wonilsuh19286&key=2e320650-b4dd-4e8a-8309-a98f895905e3

carbon-design-system / digital-design-ideation