SCSS reference / 02
SCSS Architecture
How src/scss/ is organized, and the class-naming convention used across the template.
The five layers
Everything compiles from two entry points, tokens.scss and main.scss,
each importing partials from one of five folders in a fixed order. The order matters for the cascade:
base rules first, then layout-agnostic objects, then the visual components built on top of them, then
utility overrides last so they always win.
| Layer | Folder | What lives there |
|---|---|---|
| Settings | settings/ | Design tokens, as CSS custom properties
(colors, type scale, spacing, radii — see below). Compiles separately to its own
tokens.css file. |
| Base | base/ | The reset, bare/unclassed element rules
(body, a, img…), the skip link, and shared type
utility classes (.d, .m, .kicker). |
| Objects | objects/ | Undecorated, reusable layout primitives with no visual identity of their own — section rhythm/skins and buttons. See Objects. |
| Components | components/ | One partial per UI section of the site — the header, hero, every content band, the footer. This is most of the stylesheet: 29 partials. See Components. |
| Utilities | utilities/ | Responsive breakpoint overrides, imported last so they win the cascade. See Utilities. |
Two entry points, two output files
tokens.scss imports only settings/_settings.tokens.scss and compiles to
dist/css/tokens.css. main.scss imports base, objects, components and
utilities (everything except settings) and compiles to dist/css/main.css. Every page links
both files as two separate <link> tags, tokens first — the same split the
original hand-authored two-file stylesheet used before this Sass restructure, kept so
tokens.css stays comparable byte-for-byte against the token files in Fieldcraft's other
deliverables (the WordPress theme, the framework ports).
Design tokens stay CSS custom properties
Every design value — color, font size, spacing, radius — is defined once in
settings/_settings.tokens.scss as a :root custom property
(--amber, --space-8, --text-display-hero, and so on) and
referenced everywhere else with var(…). The Sass layer never introduces a second,
parallel token system (no $sass-variables holding colors or spacing) — Sass here is
used purely for file organization and selector nesting, not for design values. That keeps a single
source of truth: change a value in one place and it applies everywhere that custom property is used,
across every deliverable that imports the same tokens file.
Class-naming convention
Fieldcraft does not use a BEM-style layer prefix (no .o-/.c-/.u-
convention on class names). Every class is a short, plain, component-scoped name matching what it
represents — .hero, .trow, .feature-band,
.faq, .pager — nested under its own Sass partial with child-element
classes as plain descendant selectors (.trow .media, .faq summary) rather than
double-underscore element suffixes. A handful of shared modifier classes recur across components:
.rv (scroll-reveal, see the reveals component),
on-dark/on-paper (which text-emphasis skin a section uses),
and .paper (the light section skin, from the section
object). There is no separate "utility" naming convention either — the one utilities partial
(responsive overrides) reuses each component's own existing class
names inside @media blocks rather than introducing single-purpose helper classes.
Why there's no tools/ layer in use
The folder structure includes a tools/ directory (for Sass mixins and functions), but
it's currently an empty placeholder — tools/_tools.README.scss explains why: a sweep
of every partial found no repeated computed value or duplicated selector pattern that would justify
extracting a mixin. Every design value already lives as a CSS custom property, so there's no
px-to-rem conversion function or color-math helper to write. If a genuinely repeated pattern emerges in
a future component, that's where it belongs.
What's next
Continue to Objects for the two layout primitives, or jump straight to Components to look up a specific UI section.