Architecture and Build
Throughout this unit you have learned how to organize CSS into a layered file structure, how to connect it with @import and @layer, how to bundle it into a single production file with a build tool, and how to follow a token-first workflow. This assignment brings all of that together. You will reorganize your portfolio's CSS into the architecture from the readings, set up your chosen build tool, and build out your homepage into a proper landing page styled entirely by the shared architecture.
Assignment Instructions
1. Set Up the Architecture
Create the layered folder structure at the root of your portfolio. If you already have a css/ directory with a main.css from Unit 1, you are building on top of it. When you are finished, your portfolio should include this structure:
[portfolio]
├── css/
│ ├── base/
│ │ ├── elements.css # New
│ │ └── reset.css # New
│ ├── components/
│ ├── layout/
│ ├── tokens/
│ │ ├── colors.css # Update
│ │ └── variables.css # Update
│ ├── utilities/
│ │ └── utilities.css # New
│ └── main.css # Update
├── dist/
│ └── styles.css # New
├── index.html # Update
└── README.md # Update
Your main.css should declare the layer order and import every file into the correct layer, following the pattern from the CSS Architecture reading. Start with the five-layer stack: tokens, base, layout, components, utilities.
2. Extract Your Tokens
Look at the CSS you wrote for the Custom Properties assignment and any other work you have done this semester. Pull your custom properties into the appropriate token files. Colors go in tokens/colors.css. Spacing, typography, radii, shadows, and everything else go in tokens/variables.css. These tokens will be shared across your entire site, so name them by purpose (like --color-primary or --space-md), not by appearance or by the assignment they came from.
Add a reset to base/reset.css and element-level styles (body, headings, links) to base/elements.css. If you have layout rules for the overall page structure, put them in layout/. You may not need files in every folder yet, and that is fine. The folders exist so you have a place for each kind of rule as your site grows.
3. Wire Up Your Build Tool
Initialize npm in your portfolio root (if you have not already) and install the build tool you chose from the Choose Topics: PostCSS or Lightning CSS. Create a build script in your package.json that reads css/main.css and outputs a bundled, minified file to dist/styles.css. Refer to your Choose Topic page for the exact setup steps.
Run the build and verify that dist/styles.css exists, that it contains the contents of all your imported files in a single file, and that it is minified. Commit that file. It is the receipt that you ran a bundler this week. Do not add dist/ to your .gitignore.
Make sure your .gitignore includes node_modules/ before you commit. If you already have one at the root of your portfolio that covers this, you are set. If not, create one now. Leave dist/styles.css tracked so graders can open the receipt in your repository.
4. Confirm GitHub Pages
Your Unit 1 workflow still copies your repository to the website branch. You do not need to add Node.js, npm ci, or npm run build to GitHub Actions for this assignment. A local build is enough to produce the receipt. Confirm that Pages still reads from website at / (root). For the full Unit 1 walkthrough, see Portfolio Setup.
- In your repository, go to Settings → Pages.
- Under Source, select Deploy from a Branch.
- Set the branch to website and the folder to / (root).
- Click Save if anything changed.
5. Build Out Your Homepage
Until now, your portfolio homepage has been minimal scaffolding. It is time to make it real. Open index.html at the root of your repository and build it into a proper landing page for your portfolio. This page must link to your source stylesheet:
Your homepage is the living proof that your architecture works. It is styled by the shared token system, base styles, layout rules, and components that the browser loads from css/main.css and its @import children. It also replaces your README.md as the human-facing table of contents. The README still serves its purpose for developers reading the repository on GitHub, but the homepage is what a visitor to your live site sees.
Your homepage must meet these requirements:
- Include your name and the course title (WDD 331R Advanced CSS)
- Link to every completed assignment and choose topic page from the semester so far
- Be responsive and usable on both mobile and desktop
- Visibly use at least three categories of design tokens from your token files (for example, color, spacing, and typography, or color, radius, and shadow)
-
Include at least one component styled in a file inside
components/and imported through the layer system (a card, a navigation bar, a styled link list, or anything else that makes sense for a landing page)
Beyond these requirements, the design is yours. Some students will create a clean, minimal list of links. Others will build a grid of project cards with descriptions and thumbnails. Both are valid as long as the architecture is doing the work. A flat assignment list is fine for the catalog homepage. In Unit 7 you add a featured case-study page in this same repository. If you want a head start, group links under course themes (for example layout, color, or typography) instead of one long list.
6. Update the README
Update your README.md to reflect the new architecture. At a minimum, document the folder structure, which build tool you chose, and how to run the build. A teammate or future employer reading your repo should be able to understand the project setup without opening every file.
7. Commit, Push, and Verify
Stage your changes, commit with a descriptive message, and push to GitHub:
git add -A
git commit -m "Add CSS architecture, build tool, and homepage"
git push origin main
After pushing, verify your deployment:
- Open the Actions tab in your repository and wait for the Deploy Website workflow to finish. The Unit 1 copy workflow should complete with a green checkmark.
- Visit your live site URL and confirm your homepage loads with styles applied.
-
Open DevTools and check the Network tab. Confirm the browser loads
css/main.cssand then the files it imports. That is how the live page stays styled. -
Open
dist/styles.cssin your repository and confirm it is one minified file. That file is this week's receipt. It is not the required live stylesheet.
If your site does not appear or the workflow fails, check these common issues:
- Workflow Failed: Open the Actions tab, click the failed run, and read the log for the step that errored. Check YAML indentation (spaces, not tabs).
-
No Website Branch: The
websitebranch is created automatically by the workflow on its first successful run. If it does not exist, the workflow has not completed successfully yet. -
Pages Shows a 404: Confirm GitHub Pages is set to deploy from the
websitebranch at the root folder (Step 4). Also verify that the workflow ran successfully and that thewebsitebranch contains files. -
Page Loads but Styles Are Missing: Confirm your
<link>element points tocss/main.cssand that the path is correct from that HTML file. Check that thewebsitebranch contains yourcss/folder after the workflow runs. -
Changes Not Showing Up: The workflow may still be running, or GitHub Pages may need a few minutes to propagate after a deployment. Try a hard refresh (
Ctrl+Shift+RorCmd+Shift+R). If the old content persists after several minutes, check the Actions tab to confirm your latest push triggered a new deployment.
After This Assignment: Stop or Keep
You practiced a real bundler this week so you understand what production CSS tooling does. After you submit, you choose whether that tooling stays part of your portfolio workflow. Instructors grade your source CSS in css/main.css and the layered folders. If dist/styles.css exists, it only shows that you bundled this week. Later assignments look for that week's required CSS in the source. A styled main.css site is not failed for missing Node after this unit.
Stop Using the Bundler
This is the course default. Leave every HTML page on css/main.css (plus any page-local stylesheet). Keep the Unit 1 GitHub Actions workflow that copies files to the website branch. Do not add setup-node, npm ci, or npm run build to that workflow. Keep the committed dist/styles.css from this assignment as the receipt. You may delete node_modules. Confirm the live site is still styled after you do.
Keep Using the Bundler
You may keep running npm run watch locally so the bundle updates when you save. You may also let GitHub rebuild dist/styles.css on every push to main. That is what the Node steps in Actions are for. A forgotten local build then does not leave the live bundle stale or missing. Later assignment snippets will still show css/main.css. Translate those links on the pages that use the bundle.
Do not delete your css/ source tree. You still edit source files. The bundler only writes the output.
Keep package.json and package-lock.json committed. Leave node_modules/ in .gitignore. If this workflow always rebuilds dist/ on GitHub, you may add dist/ to .gitignore. If you skip the Node steps and stay on the Unit 1 copy workflow, keep committing dist/styles.css.
To rebuild the bundle on every push, replace .github/workflows/deploy-website.yml with this file:
name: Deploy Website
on:
push:
branches:
- main
permissions:
contents: write
jobs:
deploy:
concurrency: ci-${{ github.ref }}
runs-on: ubuntu-latest
steps:
- name: Checkout
uses: actions/checkout@v6
- name: Setup Node
uses: actions/setup-node@v4
with:
node-version: 22
- name: Install dependencies
run: npm ci
- name: Build CSS
run: npm run build
- name: Deploy
uses: JamesIves/github-pages-deploy-action@v4
with:
folder: .
branch: website
clean: true
When a page should load the bundle, change its shared stylesheet link to dist/styles.css. Count the ../ segments from that HTML file back to the repository root. A page in unit-4/grid-layouts/ uses ../../dist/styles.css.
After you push, open the Actions tab and confirm the workflow finishes with a green checkmark. Visit the live page and confirm it is styled. In DevTools, open the Network tab and confirm the browser requested the stylesheet you actually linked.
css/main.css is the source entry. The browser loads that file, then loads every file it @imports. dist/styles.css is that same architecture after the bundler: one minified file with the same tokens, the same layers, and the same rules. It is not a second design system.
Each HTML page must choose one of those files as its shared sheet. If you link both on the same page, the browser loads the design system twice. Colors, spacing, and components apply twice. DevTools shows two full stylesheets because it is two copies of the same CSS.
A page-local file such as editorial.css or motion.css is new CSS for that assignment. It is not a second copy of the architecture. That file may sit next to whichever shared sheet the page uses.
You do not have to convert the whole site at once. An older page may keep css/main.css while a newer page uses dist/styles.css. That is two pages making two choices, not one page loading two shared sheets.
Do not do this:
Do this (one shared sheet, plus a page-local sheet when the assignment needs one):
Submission
Complete the report below. When you are finished, download the PDF and submit it to Canvas.
My live portfolio homepage is at and the source code is at .
I chose as my build tool for this assignment.
Write a thoughtful response to each prompt. These are not summaries of what you did. They ask you to reason about why your architecture works the way it does and what would happen if it changed.
Explain the layer order you declared in your main.css. Pick two layers that are adjacent in your stack and describe what would break or change if you swapped their order. Be specific about which rules would win or lose.
Pick one token you defined (a color, a spacing value, a font stack) and trace every file that consumes it. If a teammate joined your project and wanted to change that token, what would they need to understand about your architecture to do it safely? What could go wrong if they changed it without understanding the system?
Describe a CSS rule you were unsure where to place. What made the decision difficult? Which folder did you put it in, and what reasoning led you there? If you were wrong, how would you know, and what would you do about it?