CSS Architecture
In the Architecture Philosophies reading you surveyed CUBE CSS, ITCSS, and other methodologies and saw how this course blends them into a single standard: a CUBE-influenced design philosophy with an ITCSS-aligned file structure, powered by native CSS features. That reading showed you the mental model. This one makes it concrete. You are going to build out the folder structure, create the entry-point stylesheet, and learn the workflow for deciding where every new rule belongs.
The structure you set up here is not hypothetical. It is the same architecture this course site uses. Open DevTools on this page right now and inspect the stylesheet imports. You will see the same layer order, the same folder names, and the same token-first pattern you are about to create in your own project. The difference is scale. Your portfolio starts smaller, but the architecture is identical, and it will grow with you through the rest of the course.
The Layer Stack
Every project in this course begins with a single line that declares the cascade order:
You saw this declaration in the philosophies reading. What matters now is understanding exactly what it does. This line does not contain any styles. It tells the browser the order in which layers should be evaluated when two rules from different layers conflict. A rule in utilities beats a rule in components regardless of specificity, because utilities appears later in the declaration. A rule in tokens loses to everything else, which is exactly what you want for design tokens that are meant to be consumed, not to compete.
The declaration must appear before any @import statements. If you import a file into a layer before declaring the full stack, the browser will create that layer on the spot and the ordering may not be what you intended. Declare first, import second.
The @layer declaration line controls the cascade, not the order of your @import statements. You could rearrange the imports and the cascade would stay the same as long as the declaration line stays the same. That said, keeping your imports in the same order as your layers makes the file easier to read and maintain.
Folder Structure
Each layer maps to a directory. A single entry-point file, main.css, declares the layer order and imports every file into the correct layer. Here is the structure you will build for your portfolio:
[css]
├── base/
│ ├── elements.css
│ └── reset.css
├── components/
│ └── card.css
├── layout/
│ └── primary.css
├── tokens/
│ ├── colors.css
│ └── variables.css
├── utilities/
│ └── utilities.css
└── main.css
This is the same shape you will find in this course site's source. Inspect this page in DevTools and expand the stylesheet list. You will see tokens/colors.css, tokens/variables.css, base/reset.css, and the rest following the same pattern. Your portfolio starts with fewer files in each folder, but the folders themselves and the entry point work the same way.
Each folder has a clear responsibility:
-
tokens/holds custom properties. Every design decision that other files reference (colors, spacing, radii, font stacks, shadows) is defined here. -
base/holds your CSS reset and bare element styles. These rules use tag selectors (body,a,h1) and set the baseline appearance before any classes are involved. -
layout/holds structural rules for the page skeleton: the overall grid, content widths, header and footer positioning. Layout classes handle composition without caring what component sits inside them. -
components/holds the styled UI pieces: cards, buttons, navigation, forms. Because tokens and base styles do most of the heavy lifting, component files tend to be lightweight. -
utilities/holds small, single-purpose helper classes like.visually-hiddenor.text-center. They live in the last named layer so they win by layer order without needing!important.
The Entry Point: main.css
Your HTML links to one stylesheet: main.css. That file is the single source of truth for what CSS gets loaded and in what order. Here is what a starter main.css looks like for your portfolio:
/* Layer declaration: controls cascade order */
@layer tokens, base, layout, components, utilities;
/* Tokens */
@import url('tokens/colors.css') layer(tokens);
@import url('tokens/variables.css') layer(tokens);
/* Base */
@import url('base/reset.css') layer(base);
@import url('base/elements.css') layer(base);
/* Layout */
@import url('layout/primary.css') layer(layout);
/* Components */
@import url('components/card.css') layer(components);
/* Utilities */
@import url('utilities/utilities.css') layer(utilities);
Notice the pattern. Every @import includes layer() to assign the file to a specific layer. This is what connects the folder structure to the cascade. When you add a new component file, you create the file in components/, then add one @import line here. When you split a large token file into two smaller ones, you add another import to the tokens group. The main.css file is your project's table of contents.
Compare this to how you wrote CSS in Unit 1. You had a single styles.css file where tokens, resets, layout, and components all lived together. That works for a small page, but as a project grows, finding where a rule lives becomes harder, and the cascade becomes unpredictable. This architecture solves both problems: the file system tells you where to look, and the layer stack tells the browser how to prioritize.
Unlayered Styles
Every rule you have seen so far lives inside a named layer. But CSS also allows rules that sit outside of all layers, and those unlayered rules always win over layered ones regardless of specificity or layer order. This is by design. The browser treats unlayered CSS as higher priority than any named layer, which makes it a powerful escape hatch when you need guaranteed control.
In practice, unlayered styles belong at the bottom of main.css, after all of your @import statements. They are the place for small, surgical overrides that must beat everything else without resorting to !important. A common example is an icon rule that needs to override both your own component styles and any vendor CSS:
@layer tokens, base, layout, components, utilities;
/* ... all @import statements above ... */
/* Unlayered: wins over every named layer */
svg.icon {
width: 1em;
height: 1em;
fill: currentColor;
}
If you inspect this course site's main.css, you will see a small block of unlayered rules at the very bottom that does exactly this. Those rules need to beat the vendor layer without inflating specificity or scattering !important declarations, and being unlayered accomplishes that cleanly.
The key discipline is restraint. If most of your CSS is unlayered, you have lost the benefits of the layer system entirely. Unlayered rules should be rare, well commented, and limited to cases where no layer placement would work. Think of them as the override of last resort, not a convenient shortcut.
The Token-First Workflow
The most important habit this architecture teaches is to reach for a token before writing a raw value. When you need to set a color, spacing, radius, or font size, the question is not "what value do I type?" but "does a token already exist for this, and if not, should I create one?"
This workflow has two parts: where tokens live and how other files consume them.
Where Tokens Live
The tokens/ directory holds two files. colors.css is dedicated to color values. variables.css holds everything else: spacing, border radii, font families, font sizes, shadows, transitions, and any other design decision you want to centralize. Keeping colors separate from other tokens makes it easier to find and update your palette, especially once you start working with modern color functions in Unit 3.
For now, your color tokens can use simple values. The point of this reading is file placement and the token-first mindset, not color science. Here is what a starter colors.css might look like:
:root {
--color-primary: #1d4e89;
--color-primary-light: #2a6cb5;
--color-text: #1a1a2e;
--color-text-muted: #555;
--color-bg: #fff;
--color-surface: #f5f5f5;
--color-accent: #e07a2f;
--color-border: #ddd;
}
And a starter variables.css:
:root {
/* Spacing */
--space-xs: 0.25rem;
--space-sm: 0.5rem;
--space-md: 1rem;
--space-lg: 2rem;
--space-xl: 4rem;
/* Typography */
--font-body: system-ui, sans-serif;
--font-heading: Georgia, serif;
--text-sm: 0.875rem;
--text-base: 1rem;
--text-lg: 1.25rem;
--text-xl: 1.5rem;
/* Borders */
--radius-sm: 0.25rem;
--radius-md: 0.5rem;
--radius-lg: 1rem;
/* Shadows */
--shadow-sm: 0 1px 3px rgba(0, 0, 0, 0.1);
--shadow-md: 0 2px 8px rgba(0, 0, 0, 0.12);
}
When you inspect this course site's tokens/colors.css in DevTools, you will see the same structure but with oklch() and color-mix() values instead of hex codes. You will learn those functions in Unit 3 and upgrade your own tokens then. The architecture stays the same; only the values become more sophisticated.
How Other Files Consume Tokens
Every file outside of tokens/ references tokens with var(). A component file should never contain a raw color value, a hard-coded spacing number, or a font stack typed out in full. If you find yourself typing #1d4e89 inside components/card.css, that is a signal to check whether a token exists and create one if it does not.
/* components/card.css */
.card {
background: var(--color-surface);
border-radius: var(--radius-md);
padding: var(--space-md);
box-shadow: var(--shadow-sm);
}
This pattern means that changing a design decision is a one-file edit. If you decide to increase your medium spacing from 1rem to 1.25rem, you update variables.css and every component that uses --space-md picks up the change automatically. That is the practical payoff of token-first architecture.
Selectors and Nesting Conventions
The architecture tells you where files go. Selector conventions tell you how to write the rules inside those files. This course uses semantic, descriptive class names and native CSS nesting. It does not use BEM naming, as you learned in the philosophies reading.
Semantic Class Names
A class name should describe what an element is, not what it looks like. .card, .site-nav, and .board-header are semantic. .blue-box, .mt-20, and .big-text are presentational. Semantic names survive design changes. If you rename your accent color from blue to orange, .card still makes sense. .blue-box does not.
Keep class names minimal. If an element can be targeted by its tag name inside a nested context, you do not need a class at all. A h3 inside .card does not need a .card-title class unless you have multiple heading levels in the same card that need different treatment.
When Nesting Makes Sense
Native CSS nesting is ideal for rules that belong together because they style a single component or a tightly related group of elements. A .card block with nested rules for its heading, paragraph, and metadata is a good use of nesting because those rules only make sense in the context of a card:
.card {
background: var(--color-surface);
padding: var(--space-md);
border-radius: var(--radius-md);
h3 {
font-size: var(--text-lg);
margin-bottom: var(--space-sm);
}
p {
color: var(--color-text-muted);
}
&:hover {
box-shadow: var(--shadow-md);
}
}
Remember the nesting conventions from CSS Fundamentals: descendant selectors do not need the ampersand. Use & only for pseudo-classes (&:hover), compound selectors (&.featured), or reversing context (.dark-theme &).
When Flat Rules Make Sense
Not everything belongs inside a nest. Rules in base/elements.css style bare HTML tags at the top level. Rules in layout/primary.css define the page skeleton with simple class selectors. These are flat cascade glue: they apply broadly and do not belong inside a component scope.
/* base/elements.css: flat, top-level element styles */
body {
font-family: var(--font-body);
color: var(--color-text);
background: var(--color-bg);
line-height: 1.6;
}
a {
color: var(--color-primary);
&:hover {
color: var(--color-primary-light);
}
}
h1, h2, h3 {
font-family: var(--font-heading);
line-height: 1.2;
}
The rule of thumb: if a set of rules only makes sense inside a specific component, nest them. If a rule applies to the page at large or sets a baseline for a raw HTML element, keep it flat.
Scaling the Architecture
Your portfolio starts small, but this architecture is designed to grow. When you build a new component, the process is always the same:
-
Check if the design values you need already exist as tokens. If not, add them to
tokens/colors.cssortokens/variables.css. -
Create a new file in the appropriate folder (usually
components/). -
Add an
@importline tomain.csswith the correctlayer()assignment.
The same pattern works for layout files, utility classes, or base styles. The architecture never requires reorganization. You just add files and imports.
If you inspect this course site more closely, you will notice it adds a sixth layer called vendor after utilities. That layer holds third-party CSS from JamsEDU and BYU-Idaho institutional styles. Your portfolio does not need a vendor layer right now because it has no external CSS dependencies. But the principle is the same: when external CSS enters a project, giving it a dedicated layer keeps the cascade predictable without any specificity tricks. You can see how the architecture scales naturally from five layers to six (or more) as a project's needs grow.
Putting It All Together
This reading covered the practical side of the architecture you studied in the philosophies reading. You now know how to structure your css/ directory, write a main.css entry point that wires everything together with @layer and @import, follow the token-first workflow for every new design decision, and use semantic selectors with native nesting to keep your rules organized.
In the Architecture and Build assignment you will take the single-file CSS you wrote in Unit 1 and reorganize it into this architecture. You will also run it through a build tool, which is the topic of the next reading. The architecture you set up here will carry through every remaining unit of the course. The bundler will not. Each new assignment adds files to the same folders, and each new concept (modern color in Unit 3, layout patterns in Unit 4, typography in Unit 5) slots into the layer where it belongs.