<!-- mobian-agent-page publisher="dailydev" canonical="https://daily.dev/posts/under-the-hood-a-closer-look-at-the-css-architecture-behind-the-redesign-vtl5gxm3z" -->

---
title: Under the hood: a closer look at the CSS architecture...
description: A detailed breakdown of the CSS architecture behind a personal site redesign built on Astro with minimal JavaScript. Covers a cascade-layer-based file...
canonical: https://daily.dev/posts/under-the-hood-a-closer-look-at-the-css-architecture-behind-the-redesign-vtl5gxm3z
twitter:card: summary_large_image
twitter:site: @dailydotdev
og:type: website
og:site_name: daily.dev
og:title: Under the hood: a closer look at the CSS architecture behind the redesign | daily.dev
og:description: A detailed breakdown of the CSS architecture behind a personal site redesign built on Astro with minimal JavaScript. Covers a cascade-layer-based file...
og:url: https://daily.dev/posts/under-the-hood-a-closer-look-at-the-css-architecture-behind-the-redesign-vtl5gxm3z
og:image: https://api.daily.dev/og/posts/VTl5Gxm3z.png
og:image:alt: Under the hood: a closer look at the CSS architecture behind the redesign
og:image:width: 1200
og:image:height: 630
og:locale: en
---

> ## Documentation Index
> Fetch the complete documentation index at: https://daily.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Under the hood: a closer look at the CSS architecture behind the redesign

**[utilitybend](https://daily.dev/sources/utilitybend)** · 19 min read · 0 upvotes · 0 comments

## Summary

A detailed breakdown of the CSS architecture behind a personal site redesign built on Astro with minimal JavaScript. Covers a cascade-layer-based file structure (vendor, tokens, reset, atoms, molecules, organisms, pages, utilities), a three-tier design token naming convention (primitives, semantic, component) inspired by Brad Frost and Ian Frost's Subatomic course, migrating dark mode from a separate 193-line override file to light-dark(), a highly opinionated modern CSS reset using :where() for zero specificity, converting component-level media queries to container queries, going all-in on logical properties, and treating progressive enhancement as a structural file-organization decision using @supports-gated files.

## Full article

daily.dev links to this article rather than hosting it. Read it at the original source: <https://utilitybend.com/blog/under-the-hood-a-closer-look-at-the-css-architecture-behind-the-redesign>

## Questions this post answers

### How do I migrate dark mode from a separate .dark class override file to the light-dark() CSS function?

Define semantic color tokens using light-dark(var(--light-value), var(--dark-value)) directly in :root, then control the active theme by setting color-scheme via a class on the html element, such as html.light { color-scheme: light only } or html.dark { color-scheme: dark only }. This replaced a 193-line dark.css file that re-declared every token under a .dark class, removing the need to maintain a separate override file for every new token, though light-dark() only works with color values, not properties like box-shadow, opacity, or blend-mode.

_Developers untangling dark mode theming can compare CSS approaches like this one on daily.dev._

### What is a three-tier CSS design token naming convention and how should tokens be structured?

A three-tier system splits tokens into primitives (--p-, raw values like colors and spacing with no theme opinions), semantic tokens (--s-, theme-aware tokens that map primitives to meaning, such as --s-color-text), and component tokens (--c-, override hooks scoped to individual components using patterns like var(--c-btn-color, var(--s-color-brand-primary-dark))). The rule enforced is that components never reference primitives directly, only semantic tokens, keeping theming consistent and centralized.

_Teams designing a token system can study structured breakdowns like this on daily.dev before scaling their own._

### When should I use CSS container queries instead of viewport media queries for a component?

Use container queries when a component's layout should respond to its own available space rather than the browser viewport, such as a reusable card component that appears in a wide blog list, a homepage grid, and a narrow sidebar. Set container-type: inline-size on the parent and use @container (min-width: 680px) rules inside the component; keep true viewport media queries for layout-level concerns like header navigation toggles that genuinely depend on screen width.

_Developers deciding between container queries and media queries can weigh real implementation examples on daily.dev._

## Similar posts on daily.dev

- [Nerdy Design Details](https://daily.dev/posts/nerdy-design-details-uhtk6vxkh) · Kitty says hi. · 22 upvotes · 4 comments
- [Moving away from Tailwind, and learning to structure my CSS](https://daily.dev/posts/moving-away-from-tailwind-and-learning-to-structure-my-css-xxb4xb5uk) · Julia Evans · 113 upvotes · 13 comments
- [Design Systems \+ Horizontal @layer – Master.dev Blog](https://daily.dev/posts/design-systems-horizontal-layer-master-dev-blog-vaqxpniun) · Frontend Masters · 6 upvotes · 0 comments
- [CSS-in-JS: The Great Betrayal of Frontend Sanity](https://daily.dev/posts/css-in-js-the-great-betrayal-of-frontend-sanity-yltrsmn2c) · The New Stack · 0 upvotes · 0 comments
- [Issue \#760: Why GitHub now ships more CSS, not less — Frontend Focus](https://daily.dev/posts/issue-760-why-github-now-ships-more-css-not-less-frontend-focus-oi6kowdye) · Frontend Focus · 2 upvotes · 0 comments

---

Tags: [#css](https://daily.dev/tags/css), [#ui-design](https://daily.dev/tags/ui-design), [#astro](https://daily.dev/tags/astro)

[View this post on daily.dev](https://daily.dev/posts/under-the-hood-a-closer-look-at-the-css-architecture-behind-the-redesign-vtl5gxm3z)

```json
{"@context":"https://schema.org","@graph":[{"@type":"Organization","@id":"https://daily.dev/#organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180},"sameAs":["https://twitter.com/dailydotdev","https://github.com/dailydotdev","https://www.linkedin.com/company/daily-dev-ltd"]},{"@type":"WebSite","@id":"https://daily.dev/#website","url":"https://daily.dev","name":"daily.dev","publisher":{"@id":"https://daily.dev/#organization"},"potentialAction":{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https://daily.dev/search?q={search_term_string}"},"query-input":"required name=search_term_string"}}]}
{"@context":"https://schema.org","@type":"TechArticle","headline":"Under the hood: a closer look at the CSS architecture behind the redesign","url":"https://daily.dev/posts/under-the-hood-a-closer-look-at-the-css-architecture-behind-the-redesign-vtl5gxm3z","mainEntityOfPage":{"@type":"WebPage","@id":"https://daily.dev/posts/under-the-hood-a-closer-look-at-the-css-architecture-behind-the-redesign-vtl5gxm3z"},"datePublished":"2026-09-20T07:43:27.963Z","dateModified":"2026-09-20T08:14:04.196Z","description":"A detailed breakdown of the CSS architecture behind a personal site redesign built on Astro with minimal JavaScript. Covers a cascade-layer-based file...","image":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/1ddeda9e58ab0e397d39bbb4e7b1fbf1?_a=AQAEuop","thumbnailUrl":"https://media.daily.dev/image/upload/f_auto,q_auto/v1/posts/1ddeda9e58ab0e397d39bbb4e7b1fbf1?_a=AQAEuop","isAccessibleForFree":true,"articleSection":"utilitybend","inLanguage":"en","publisher":{"@type":"Organization","name":"daily.dev","url":"https://daily.dev","logo":{"@type":"ImageObject","url":"https://daily.dev/apple-touch-icon.png","width":180,"height":180}},"author":{"@type":"Organization","name":"utilitybend","logo":"https://media.daily.dev/image/upload/s--hONVFSz4--/f_auto,q_auto/v1789890196/logos/utilitybend?_a=BAMAMicg0","url":"https://daily.dev/sources/utilitybend"},"commentCount":0,"discussionUrl":"https://daily.dev/posts/under-the-hood-a-closer-look-at-the-css-architecture-behind-the-redesign-vtl5gxm3z","interactionStatistic":[{"@type":"InteractionCounter","interactionType":{"@type":"LikeAction"},"userInteractionCount":0},{"@type":"InteractionCounter","interactionType":{"@type":"CommentAction"},"userInteractionCount":0}],"keywords":"css,ui-design,astro","timeRequired":"PT19M"}
{"@context":"https://schema.org","@type":"BreadcrumbList","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https://daily.dev"},{"@type":"ListItem","position":2,"name":"utilitybend","item":"https://daily.dev/sources/utilitybend"},{"@type":"ListItem","position":3,"name":"Under the hood: a closer look at the CSS architecture behind the redesign"}]}
{"@context":"https://schema.org","@type":"FAQPage","@id":"https://daily.dev/posts/under-the-hood-a-closer-look-at-the-css-architecture-behind-the-redesign-vtl5gxm3z#faq","mainEntity":[{"@type":"Question","name":"How do I migrate dark mode from a separate .dark class override file to the light-dark() CSS function?","acceptedAnswer":{"@type":"Answer","text":"Define semantic color tokens using light-dark(var(--light-value), var(--dark-value)) directly in :root, then control the active theme by setting color-scheme via a class on the html element, such as html.light { color-scheme: light only } or html.dark { color-scheme: dark only }. This replaced a 193-line dark.css file that re-declared every token under a .dark class, removing the need to maintain a separate override file for every new token, though light-dark() only works with color values, not properties like box-shadow, opacity, or blend-mode. Developers untangling dark mode theming can compare CSS approaches like this one on daily.dev."}},{"@type":"Question","name":"What is a three-tier CSS design token naming convention and how should tokens be structured?","acceptedAnswer":{"@type":"Answer","text":"A three-tier system splits tokens into primitives (--p-, raw values like colors and spacing with no theme opinions), semantic tokens (--s-, theme-aware tokens that map primitives to meaning, such as --s-color-text), and component tokens (--c-, override hooks scoped to individual components using patterns like var(--c-btn-color, var(--s-color-brand-primary-dark))). The rule enforced is that components never reference primitives directly, only semantic tokens, keeping theming consistent and centralized. Teams designing a token system can study structured breakdowns like this on daily.dev before scaling their own."}},{"@type":"Question","name":"When should I use CSS container queries instead of viewport media queries for a component?","acceptedAnswer":{"@type":"Answer","text":"Use container queries when a component's layout should respond to its own available space rather than the browser viewport, such as a reusable card component that appears in a wide blog list, a homepage grid, and a narrow sidebar. Set container-type: inline-size on the parent and use @container (min-width: 680px) rules inside the component; keep true viewport media queries for layout-level concerns like header navigation toggles that genuinely depend on screen width. Developers deciding between container queries and media queries can weigh real implementation examples on daily.dev."}}]}
```

