Variable naming principles

Difficulty: intermediate

Estimated Time: 20 minutes

PatternFly Core is based on the principles of Atomic design and BEM (Block, Element, Modifier).

BEM is a popular CSS methodology for building modular, scalable applications. It provides scope, avoids inheritance, and reduces CSS specificity and conflicts.

BEM works perfectly with a modular design system, as each unique component can be represented as an independent block. Since a block is tied to a component, developers are able to develop, move around, and nest components without conflicts in their application’s CSS.

PatternFly uses a modified version of BEM for its CSS architecture. Where PatternFly deviates from BEM is in relation to modifiers.

This module covers how PatternFly uses BEM as a framework for its component library. You'll learn how to override and create both global and component-level custom properties and component elements.

Congratulations! You finished the "variable naming principles" course.

Please fill out a quick survey here

Your environment is currently being packaged as a Docker container and the download will begin shortly. To run the image locally, once Docker has been installed, use the commands

cat scrapbook_patternfly_html-css/variable-naming-principles_container.tar | docker load

docker run -it /patternfly_html-css/variable-naming-principles:

Restart Scenario

Next Scenario

Step 1 of 4

Override Component Variables

This step looks at how component variables are named.

In PatternFly, component-level custom properties follow this general formula: --pf-c-block[__element][--modifier][--state][--breakpoint][--pseudo-element]--PropertyCamelCase.

--pf-c-block refers to the block, usually the component or layout name (e.g. --pf-c-alert).
__element refers to the element inside of the block (e.g. __title).
--modifier refers to a modifier class such as .pf-m-danger, and is prefixed with m- in the component variable (e.g.--m-danger).
--state is something like hover or active.
--breakpoint is a media query breakpoint such as sm for $pf-global--breakpoint--sm.
--pseudo-element is one of either before or after.
PropertyCamelCase refers to the property that is being changed.

Katacoda is setting up a new application. Begin coding once the server starts and "Welcome to PatternFly" appears on the lower pane.

In this step, override the title color custom property in the success variation of the alert component.

1) Add a success alert component to index.html.

Click the Copy to Editor button below to add the success component in the index.html file.

<div class="pf-c-alert pf-m-success">
  <div class="pf-c-alert__icon">
    <i class="fas fa-check-circle"></i>
  </div>
  <h4 class="pf-c-alert__title">Success alert title</h4>
</div>

2) Set up the styles file for the alert component.

Click the Copy to Editor button below to set up the stylesheet in the myapp.scss file.

:root {
  // Add global variables here
}

.pf-c-alert {
  // Add Alert component variables here
}

3) Write the block for the custom property name.

Overriding the success variation’s title color means overriding its custom property.

In the myapp.scss file, in the .pf-c-alert{}block, write the custom property name.

In reference to the documentation above, it should be: --pf-c-alert

4) Add the modifier to the custom property name.

Reference the documentation by scrolling down to the bottom to view the alert component's documentation. Note that the success variation class .pf-m-success applies to .pf-c-alert. Add that modifier to the custom property.

The custom property name should now be: --pf-c-alert--m-success

5) Add the element to the custom property name.

The element that is being changed is the title of the alert.

The custom property name should now be: --pf-c-alert--m-success__title

6) Add the property that is being modified.

In this case, modify the color property of the title in the alert component.

The custom property name should now be: --pf-c-alert--m-success__title--Color

7) Add a declaration using the new custom property created in steps 3-6.

PatternFly's global danger color is: --pf-global--danger-color--100.

Assign the custom property name (--pf-c-alert--m-success__title--Color) that is already inside of the .pf-c-alert{} block to the global danger color.

It should look like this: --pf-c-alert--m-success__title--Color: var(--pf-global--danger-color--100);

Note: The alert component should have a new color for the title.

<div class="pf-c-alert pf-m-success" aria-label="Success alert">
  <div class="pf-c-alert__icon">
    <i class="fas fa-check-circle" aria-hidden="true"></i>
  </div>
  <h4 class="pf-c-alert__title">
    <span class="pf-screen-reader">
     Success alert:</span> Success alert title
  </h4>
  <div class="pf-c-alert__description">
    <p> Success alert description.
      <a href="#">This is a link.</a>
    </p>
  </div>
  <div class="pf-c-alert__action">
    <button class="pf-c-button pf-m-plain" type="button" aria-label="Close success alert: Success alert title">
      <i class="fas fa-times" aria-hidden="true"></i>
    </button>
  </div>
</div>

.pf-c-alert {
  --pf-c-alert--m-success__title--Color: var(--pf-global--danger-color--100);
}

Override Global Variables

In PatternFly, global properties follow this general formula: --pf-global--concept--PropertyCamelCase--modifier--state.

They are prefixed with the word global.
A concept is something like a spacer or main-title.
A PropertyCamelCase is something like BackgroundColor or FontSize.
A modifier is something like sm, or lg.
A state is something like hover, or expanded. They are concepts, never tied to an element or component. This is incorrect: --pf-global--h1--FontSize. This is correct: --pf-global--FontSize--3xl.

In this step, override the global link color by setting it to the custom property for danger. Add a button and expandable component to see how changing a global variable has an impact across components.

1) Add two components to index.html.

Click the Copy to Editor button below to add a button component and expandable component to the index.html file.

<button class="pf-c-button pf-m-inline pf-m-link" type="button">
  Inline link
</button>

<div class="pf-c-expandable-section">
  <button type="button" class="pf-c-expandable-section__toggle" aria-expanded="false">
    <span class="pf-c-expandable-section__toggle-icon">
      <i class="fas fa-angle-right" aria-hidden="true"></i>
    </span>
    <span class="pf-c-expandable-section__toggle-text">
      Show more
    </span>
  </button>
</div>

2) Copy code into the myapp.scss file.

Click the Copy to Editor button below to set up the stylesheet in the myapp.scss file.

:root {
  // Add global variables here
}

3) Write the prefix for the global custom property.

Since global custom properties are prefixed with the word global, use that for the beginning of the custom property.

In the myapp.scss file, in the :rootblock, begin writing the global custom property.

It should look like this: --pf-global

4) Add the concept to the global custom property.

The concept for the link color is link. Knowing that the concept comes next, add that to the global custom property.

The global custom property should now look like this: --pf-global--link

5) Add the property to the global custom property.

As the color is being modified, add the color property as the next step.

The global custom property should now look like: --pf-global--link--Color

6) Add a declaration using the new custom property created in steps 2–4.

PatternFly's global danger color is: --pf-global--danger-color--100.

Assign the custom property name (--pf-global--link--Color) that is already inside of the :root block to the global danger color.

It should look like this: --pf-global--link--Color: var(--pf-global--danger-color--100);

Note: The button component and expandable component should inherit different colors.

This is a <a href="#">test link</a>.

:root {
  --pf-global--link--Color: var(--pf-global--danger-color--100);
}

Create component variables using BEM

Its important to understand how BEM is used to override variables and also to create them.

In this step, add a BEM element and custom styles with CSS custom properties to support a badge element in the label component. Assume there is a common use case for adding a badge to the left of text in the label component. When adding the custom badge element to the label component, also apply a margin-right of 8px.

1) Copy code into the index.html file.

Click the Copy to Editor button to add a label component to the index.html file.

<span class="pf-c-label pf-m-purple">
  <span class="pf-c-label__content">
    My custom label
  </span>
</span>

2) Add a badge before the label text.

Add markup for the badge above the text reading, "My custom label":

  <div class="pf-c-badge pf-m-unread">
    4
  </div>

3) Add a new class to the badge added in step 2.

The label component only styles the label itself and the text inside. While this looks okay, its necessary to add space between the badge and the text beside it.

To do this the BEM way, assign a BEM element class to the badge.

After the pf-c-badge class, add the class pf-c-label__badge.

It should look like this:

<span class="pf-c-label pf-m-purple">
  <div class="pf-c-badge pf-m-unread">
    4
  </div>
  <span class="pf-c-label__content">
    My custom label
  </span>
</span>

4) Style the badge and apply a margin to it.

Note: Never apply a global custom property as the value for a property in a component's CSS.

Copy code into the myapp.scss file.

Click the Copy to Editor button below to add the stylesheet to myapp.scss.

.pf-c-label {
  // Add Label component variables here
}

5) Create a new variable to represent the badge's margin.

Within myapp.scss, in the .pf-c-label{} block, define the beginning of the custom property, which is the name of the component.

It should look like: --pf-c-label

6) Define the element that the custom property applies to.

Add the element after the name of the component.

The custom property should now be: --pf-c-label__badge.

7) Add the property being applied to the badge.

Add the property after the element.

It should look like this: --pf-c-label__badge--MarginRight

8) Add a declaration using the new custom property created in steps 5–7.

PatternFly's global variable for 8px of space is --pf-global--spacer--sm.

Assign the custom property name --pf-c-label__badge--MarginRight that is already inside of the .pf-c-label{} block to the global variable for 8px of space.

It should look like this: --pf-c-label__badge--MarginRight: var(--pf-global--spacer--sm);

9) Add a new selector block for the style assigned to the label badge.

Create a new selector block for pf-c-label__badge in myapp.scss. It should be added to the global scope (outside of the existing .pf-c-label selector) to apply the margin styles to it.

It should look like this:

.pf-c-label__badge {
  // Add styles here
}

10) Assign the new custom property name to the property that is being overriden.

Add a margin-right declaration inside of .pf-c-label__badge{} and assign it to the new margin variable.

It should look like this: margin-right: var(--pf-c-label__badge--MarginRight);

Note: Once the preview reloads, there should be space to the right of the badge.

<span class="pf-c-label">
  <i class="pf-c-label__icon fas fa-plus"></i>
  My custom label
</span>

.pf-c-label {
  --pf-c-label__icon--MarginRight: var(--pf-global--spacer--sm);
}

.pf-c-label__icon {
  margin-right: var(--pf-c-label__icon--MarginRight);
}

Create global variables using BEM

Create a new global custom property for a 5xl font size. Use this new global variation to make a new variation of the title component.

Referencing the typography design guidelines, the largest font size PatternFly offers is a "Hero title" size. It is 36px represented by the global variable pf-global--FontSize--4xl. Assume that there is a need for a larger font size for the title component that is used across the entire application.

1) Copy code into the index.html file.

Click the Copy to Editor button below to add a title component using the new modifier of pf-m-5xl in the index.html file.

<h1 class="pf-c-title pf-m-5xl">
  5xl title
</h1>

2) Set up the stylesheet for the title component.

Click the Copy to Editor button below to set up the stylesheet in the myapp.scss file.

:root {
  //Add global variables here
}

.pf-c-title {
  //Add Title component variables here
}

3) Define the global custom property name to be used.

Follow the existing convention for global font size custom properties. Add the new custom property for font size inside of the :root{} block. This applies it to the global scope of the application.

It should look like this: --pf-global--FontSize--5xl

4) Create a declaration using the new custom property.

Assign the property name added in step 3 to the pixel value for the new font size.

Update the line added in step 3 to be 42px.

It should look like this: --pf-global--FontSize--5xl: 42px;

5) Create a local custom property in the title block.

The local custom property should represent the 5xl variation's font size.

Beginning with the component name, write the custom property and add it to the .pf-c-title{} block in the myapp.scss file.

It should look like this: --pf-c-title

6) Add the new modifier to the custom property name.

It should look like this: --pf-c-title--m-5xl

7) Add the property that the custom property represents.

It should look like this: --pf-c-title--m-5xl--FontSize

8) Add a new declaration using the global variable added in steps 3 and 4.

Add this declaration inside of .pf-c-title{}.

It should look like this: --pf-c-title--m-5xl--FontSize: var(--pf-global--FontSize--5xl);

9) Create a CSS selector for the new 5xl variation.

Knowing that the modifier .pf-m-5xl will apply to the title component, use the & in SCSS to nest .pf-m-5xl inside of .pf-c-title. This will create .pf-c-title.pf-m-5xl.

Add this block inside of .pf-c-title, underneath the declaration from step 8.

&.pf-m-5xl {
  //Code goes here
}

10) Create a declaration within the modifier block.

The declaration will define the font size property with a value of the new title component custom property that was created for this variation.

Add font-size: var(--pf-c-title--m-5xl--FontSize); inside of .pf-m-5xl{}.

<h1 class="pf-c-title pf-m-5xl">
  5xl title
</h1>

:root {
  --pf-global--FontSize--5xl: 42px;
}

.pf-c-title {
  --pf-c-title--m-5xl--FontSize: var(--pf-global--FontSize--5xl);

  &.pf-m-5xl {
    font-size: var(--pf-c-title--m-5xl--FontSize);
  }
}

myapp.scss

cd <directory>	Change directory
ls	List directory
echo 'contents' > <file>	Write contents to a file
cat <file>	Output contents of file

i	In Command Mode	Change into Insert Mode, you can now insert and edit text in the file
esc	In Insert Mode	Change into Command Mode, you can now execute commands
:wq	In Command Mode	Save and Exit

Welcome!

Variable naming principles

Congratulations!

You've completed the scenario!

Scenario Rating

Steps