Custom Properties
In the previous readings you learned how preprocessors like Sass and LESS introduced variables to CSS, giving developers a way to store and reuse values across a stylesheet. You also explored how modern CSS now includes native math functions like calc(), clamp(), min(), and max(). Custom properties bring together the best of both worlds: reusable, named values that live directly in the browser and participate in the cascade, combined with math functions that make those values dynamic and responsive.
This page covers the var() function, how custom properties inherit and scope through the DOM, how fallback values protect your styles, and how to begin thinking in design tokens. These concepts set the stage for organizing your CSS with @import and @layer in upcoming material. If you want to go deeper after reading this page, the MDN guide on custom properties is an excellent reference.
Declaring and Using Custom Properties
A custom property is any property name that starts with two dashes (--). You declare it just like any other CSS property, and you retrieve its value with the var() function. Here is the simplest possible example:
:root {
--brand-blue: #1d4e89;
}
.header {
background-color: var(--brand-blue);
}
The :root selector targets the top of the document (the <html> element), so --brand-blue is available everywhere on the page. The var() function reads the current value of that property wherever it is used. If you later decide the brand color should be a different shade, you change it in one place and every rule that references it updates automatically.
This might look similar to Sass variables at first glance, but there is a critical difference. Sass variables are replaced with their literal values at compile time and then disappear. Custom properties are live values that exist in the browser at runtime. You can inspect them in DevTools, change them with JavaScript, and override them at different levels of the DOM. That runtime behavior is what makes custom properties so powerful.
Naming Rules
Custom property names are case sensitive. --brand-blue and --Brand-Blue are two completely different properties. The convention used by most teams is lowercase with hyphens, similar to standard CSS property names. Choose names that describe what the value represents rather than what it literally is. For example, --color-primary tells you the role of the color in your design system, while --blue-hex only tells you what the color looks like right now.
Where You Can Use var()
The var() function works anywhere a property value is expected. You can use it for colors, sizes, spacing, font stacks, shadows, and more. The one place you cannot use it is in property names or selectors. For instance, you cannot write var(--my-property): 10px; because the browser needs to know the property name before it can evaluate the value.
Fallback Values
The var() function accepts an optional second argument: a fallback value. If the custom property is not defined in the current scope, the browser uses the fallback instead. This is your safety net.
.card {
/* If --card-radius is not defined, use 0.5rem */
border-radius: var(--card-radius, 0.5rem);
}
Fallbacks are especially useful when you build reusable components. Imagine you create a .card class that you use across multiple projects. Some projects define --card-radius in their token file; others do not. With a fallback in place, the card still looks correct either way.
Nested Fallbacks
You can nest var() calls inside a fallback, creating a chain of preferences. The browser works through them from left to right and stops at the first value it finds.
.button {
background-color: var(--button-bg, var(--color-primary, #3498db));
}
In this example the browser first checks for --button-bg. If that is not defined, it checks --color-primary. If neither exists, it falls back to #3498db. This pattern lets you create components that are flexible enough to work in many contexts without losing their default appearance.
A common misunderstanding is that fallback values help older browsers that do not support custom properties at all. They do not. If a browser does not understand the var() function, it ignores the entire declaration. Fallbacks only apply when the browser supports var() but the referenced property is not defined or has an invalid value.
Inheritance and Scoping
Custom properties inherit from parent elements to children, just like color or font-family. This is the feature that separates them most sharply from preprocessor variables. In Sass, a variable defined at the top of a file is simply replaced everywhere during compilation. There is no concept of a parent element passing a value down to its children. Custom properties, on the other hand, flow through the DOM tree according to the same cascade rules you already know.
Global Scope with :root
Declaring custom properties on :root makes them available to every element on the page because everything in the document is a descendant of the root element. This is the right place for values that genuinely apply site wide, like your brand colors, base font size, or global spacing scale.
:root {
--color-primary: #1d4e89;
--color-accent: #e2a03f;
--spacing-md: 1rem;
--font-body: 'Segoe UI', sans-serif;
}
Component Scope
You can also declare custom properties on any selector, and those values will only apply to that element and its descendants. This is called component scoping. Think of it like the way a bishop leads a single ward. The bishop sets the tone and direction for that ward, but his decisions do not override what happens in a neighboring ward. Each ward (component) can have its own set of values while still following the broader guidelines from Church headquarters (the global :root tokens).
:root {
--card-bg: #ffffff;
--card-text: #333333;
}
.card-dark {
--card-bg: #1a1a2e;
--card-text: #e0e0e0;
}
.card {
background-color: var(--card-bg);
color: var(--card-text);
padding: var(--spacing-md);
}
Every .card uses the same rule, but a card inside a .card-dark container automatically picks up the darker values because it inherits the overridden properties from its parent. No duplicate rules, no extra classes on the card itself.
See It in Action
The demo below shows inheritance at work. Two cards use the exact same .card class, but they sit inside different parent containers that redefine the custom properties. Toggle the button to swap which container uses the alternate theme:
Announcements
Ward activity this Saturday at 6:00 PM in the cultural hall.
Announcements
Stake youth fireside on Friday at 7:00 PM in the chapel.
Both cards use the same CSS rules. The only thing that changes is which parent container carries the .ward-alternate class, which redefines the custom properties. The cards inherit the new values automatically. This is inheritance and scoping working together.
Thinking in Design Tokens
So far you have seen custom properties used one at a time. That is useful, but the real payoff comes when you organize all of your reusable values into a single, central location. In the industry, these centralized values are called design tokens. A design token is a named value that captures a design decision: a color, a spacing unit, a font size, a border radius, a shadow. Instead of scattering raw values throughout dozens of CSS rules, you define each decision once and reference it everywhere else.
Think of it this way. The Church of Jesus Christ of Latter-day Saints publishes the General Handbook as a single source of truth for Church policy and procedure. A bishop does not make up meeting schedules, interview guidelines, or welfare policies from scratch. He consults the handbook. When Church leadership updates a policy, they change it in the handbook, and every unit worldwide has the updated guidance in one place. Design tokens work the same way for your stylesheets. You define your design decisions in one file, and every component in your project consults that file. When a decision changes, you update the token, and the change ripples everywhere automatically.
A Simple Token File
In practice, you create a CSS file that contains nothing but custom property declarations on :root. This file is your token file. Here is a small example:
/* tokens.css */
:root {
/* Colors */
--color-primary: #1d4e89;
--color-accent: #e2a03f;
--color-text: #2c2c2c;
--color-bg: #fafafa;
--color-danger: #c0392b;
--color-success: #27ae60;
/* Spacing */
--space-xs: 0.25rem;
--space-sm: 0.5rem;
--space-md: 1rem;
--space-lg: 2rem;
--space-xl: 4rem;
/* Typography */
--font-body: 'Segoe UI', system-ui, sans-serif;
--font-heading: Georgia, serif;
--text-base: 1rem;
--text-lg: 1.25rem;
--text-xl: 1.75rem;
/* Borders and Shadows */
--radius: 0.375rem;
--shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.12);
--shadow-md: 0 4px 12px rgba(0, 0, 0, 0.1);
}
Then, in any other stylesheet for your project, you reference these tokens instead of writing raw values:
/* components.css */
.card {
background-color: var(--color-bg);
color: var(--color-text);
padding: var(--space-md);
border-radius: var(--radius);
box-shadow: var(--shadow-sm);
font-family: var(--font-body);
}
.card-title {
font-family: var(--font-heading);
font-size: var(--text-xl);
margin-bottom: var(--space-sm);
}
Notice that components.css contains zero hard coded colors, zero magic numbers. If you need to adjust the primary color for a seasonal theme or a client rebrand, you open tokens.css, change one line, and you are done. In upcoming material you will learn how to use @import to pull this token file into your main stylesheet and @layer to control how its declarations interact with the rest of your CSS. For now, the important takeaway is the habit: define once, reference everywhere.
Token Demo
The interactive demo below lets you change token values and immediately see how they affect every element that references them. Try adjusting the primary color and spacing to see the ripple effect.
Gospel Doctrine
Sunday class covering the Book of Mormon this year. Meets in room 204 after sacrament meeting.
SundayElders Quorum
Service project this week: helping a family move on Saturday morning at 8:00 AM.
ServiceRelief Society
Enrichment night on Wednesday. Theme: developing Christlike attributes through creative arts.
ActivityEvery card, tag, heading color, border, and spacing value in that demo is driven by just three custom properties. When you adjust the color picker or sliders, a small script sets the property on the container element, and every descendant that references those tokens updates instantly. This is the power of the single source of truth approach. In a real project, your token file is that single source, and every component consults it.
Putting the Pieces Together
Here is a quick summary of how each concept you learned on this page connects to the next:
- var() lets you reference custom properties anywhere a value is expected, keeping your CSS DRY and readable.
- Fallback values protect your components so they always have a sensible default, even when a token is missing.
- Inheritance means you can override tokens on a parent element and all descendants pick up the new values automatically, enabling powerful scoping and theming.
- Design tokens take all of this and give it structure: one file, one source of truth, referenced by everything in your project.
As you move forward in this course, you will use @import to load your token file into a main stylesheet and @layer to control the priority of your tokens relative to component styles and overrides. For now, start building the habit of reaching for a custom property instead of hard coding a value. Your future self (and your teammates) will thank you.
Check Your Understanding
A student just completed a learning activity on CSS custom properties. They learned how to declare custom properties with the -- prefix, use var() to reference them, provide fallback values as a second argument to var(), scope properties to specific elements vs :root for global scope, and think about organizing values as design tokens in a central location.\n They are working on creating a set of design tokens on :root and a .profile-card component that uses those tokens with proper fallbacks. Review their code and give direct feedback. Tell them what they did well and where they need to improve. Check that they declared meaningful token names on :root, used var() correctly in the component, included at least one fallback value, and scoped at least one property override to a variation class. Watch for common mistakes like forgetting the -- prefix, putting var() in a property name instead of a value, using fallbacks incorrectly, or naming tokens after their literal appearance instead of their purpose. Guide them back to the concepts rather than providing complete solutions.
/**
* 1. On :root, declare at least 5 design tokens covering
* color, spacing, and border-radius. Name them by
* purpose, not appearance (e.g. --color-primary, not
* --blue).
*
* 2. Create a .profile-card rule that uses var() to
* reference your tokens for background, text color,
* padding, border-radius, and box-shadow.
*
* 3. Add a fallback value to at least one var() call.
*
* 4. Create a .profile-card-dark variation class that
* overrides two or more tokens to create an alternate
* look using component scoping.
*/
:root {
/* Your tokens go here. */
}
.profile-card {
/* Your component styles go here. */
}
.profile-card-dark {
/* Your scoped overrides go here. */
}