FSCSS Component Architecture: A Modular, Composition-First Approach to CSS

#tutorial #fscss #sharepoint #opensource

FSCSS component architecture is built around a modular, composition-first model that compiles to plain CSS. It emphasizes reusable style units, design tokens, conditional logic, and selective imports—with almost no runtime JavaScript required for the final output. Components in FSCSS are treated as pure style definitions rather than framework-specific widgets, keeping stylesheets readable, highly reusable, and free of classic “mega-stylesheet” problems while still producing standard CSS that any browser understands.

Core Building Blocks

FSCSS provides a focused set of primitives for defining and composing styles:

Primitive	Purpose	Best for	Introduced / Key version
`str(name, "…")`	Named blocks of CSS declarations	Simple reusable style snippets	Core
`@fun(name){…}`	Key-value stores (design tokens)	Spacing scales, color palettes, property groups	Core
`@define name(params)`	Parameterized mixins	Themed components, variants, full structures	1.1.15+
`pattern(threshold: "desc", "…")`	Semantic / fuzzy matching	Natural-language style injection	1.1.25+
`@event name(param)`	Conditional value functions	Themes, states, calculations	Core
`@arr(name[…])`	Arrays + iteration	Generated classes, loops, scales	Core
`@import`	Selective / wildcard module loading	Modular architecture & ecosystem modules	Core

How Components Are Structured

1. Atomic / Token Layer (@fun + variables)

Design tokens sit at the foundation so every component draws from a single source of truth:

@fun(tokens) {
  primary: #2563eb;
  radius-md: 8px;
  space-4: 1rem;
  shadow-sm: 0 1px 3px rgba(0,0,0,.1);
}

2. Base Style Blocks (str() or @fun full-block)

Related declarations are grouped into reusable blocks that can be dropped into any selector:

str(card-base, "
  padding: @fun.tokens.space-4.value;
  border-radius: @fun.tokens.radius-md.value;
  box-shadow: @fun.tokens.shadow-sm.value;
  background: white;
")

3. Parameterized Components (@define)

True mixins accept arguments and can be composed freely:

@define button(bg: #2563eb, fg: white, pad: 0.75rem 1.5rem) {
  background: @use(bg);
  color: @use(fg);
  padding: @use(pad);
  border: none;
  border-radius: @fun.tokens.radius-md.value;
  cursor: pointer;
}

@define button-hover(bg) {`
  &:hover { background: @use(bg); }
`}

.btn-primary {
  @button()
  @button-hover(#1d4ed8)
}

4. Semantic / Intent-based Styles (pattern())

Styles can be described in plain language; FSCSS matches by similarity:

pattern(0.6: "elevated card with soft shadow", `
  border-radius: 12px;
  padding: 1.5rem;
  box-shadow: 0 10px 25px rgba(0,0,0,.08);
  background: white;
`)

.product-card {
  elevated card with soft shadow
}

5. Conditional & Dynamic Behavior (@event + @arr)

Themes, states, and generated variants are handled at compile time without external logic:

@event theme(mode) {
  if mode: dark { return: #0f172a; }
  el { return: #f8fafc; }
}

body {
  background: @event.theme(dark);
}

Modular Architecture & Ecosystem

FSCSS encourages splitting styles into focused modules and importing only what is needed:

@import((page-root, page-hero) from customizable)
@import((*) from form)
@import((st-chart-line, st-stat-card) from st-core)

Modules that follow this pattern:

st-core — pure-CSS charts & stat cards (data via CSS custom properties)
form — floating labels, checkboxes, switches, validation (checkbox-hack style)
circle-progress — progress rings with color logic driven by @event + @arr
customizable — page shells (nav, hero, CTA, footer, typography)
cube — pure CSS 3D cube faces with micro-effects

Each module is self-contained, token-driven, and designed so multiple modules can coexist on one page without conflicts.

Recommended Project Layout

styles/
  tokens.fscss          ← @fun + $variables
  components/
    button.fscss        ← @define + str()
    card.fscss
    form.fscss
  layouts/
    page.fscss
  main.fscss            ← selective @imports + composition

Compile with the CLI for production (fscss main.fscss dist/styles.css) so the shipped CSS has zero runtime dependency.

Key Design Principles

Composition over inheritance — stack small @defines and str() blocks.
Tokens first — everything reads from @fun or $variables.
Selective imports — pull only the mixins a page needs.
Compile-time resolution — almost all logic runs at build time and disappears from the final CSS.
Progressive enhancement — start with simple str() / @fun, then graduate to @define and pattern() as complexity grows.

This architecture keeps stylesheets readable, highly reusable, and free of the classic “mega-stylesheet” problems while still producing standard CSS that any browser understands.

DEV Community