Building an FSCSS Module

Working modules in the ecosystem (st-core, these two, and later packs) share the same shape:

1. Root tokens — @define X-root(root:root){...} writes every custom property the module needs on a selector (:root by default). Call once before anything else.
2. Scoped base reset — @use(st), @use(st) *{...}, never a bare global *. A global reset inside a component module fights the next module on the same page. Shared helper: scoped-reset from fscss:micros.
3. Structural mixins — one per visual piece (container, line, band…), each with a selector parameter so the same mixin can target different classes.
4. Optional preset — X-preset(st:...) wires the common case; individual mixins stay available for custom composition.

The syntax is forgiving. The mistakes that cost real time were structural.

Don’t wrap a child mixin call in a selector block it doesn’t need

If sk-line(st, w, h) already builds its full selector internally, wrapping the call doubles the selector:

@use(st) .sk-line-1{
  @sk-line(.sk-line-1, 100%)   /* wrong — doubles selector */
}

Compiles cleanly, matches nothing. Call the child with the full selector as the argument:

@sk-line(@use(st) .sk-line-1, 100%)

Stray leading punctuation in the root block

Watch for :@use(root){ vs the intended selector form. Scan every root mixin before ship.

Declared parameter never referenced = silent no-op

sk-list(st, count:5) with a body that hardcodes count(5) means @sk-list(.feed, 6) still renders five items. Every parameter should appear via @use(...) in the body.

@arr.name[] expands as a loop when the reference sits in selector position, followed by a block:

div:nth-child(@arr.colors[]){
  color: @arr.colors[];
}

1.2.x: arrays also resolve cleanly inside declarations — derived arrays, method results as new sources (!.reverse, !.list, !.length, !+[…], !-[index]). Use selector+block when you need N rules; use declaration-time arrays for tokens and parallel data.

When generated rules must not be eaten as a selector wrapper:

empty{ /* preserve */ }
/* loop / generated rules */

Index + values (parallel arrays)

@arr colors[magenta, cyan, green, purple, orange, blue]
@arr colors-i[count(@arr.colors!.length, 1)]

@use(st).band-@arr.colors-i[]{
  /* use @arr.colors[@arr.colors-i[]] etc. */
}

Same idea as st-core@v2 chart points. Shared helper: @mirror(data, idx) from fscss:micros.

As of current FSCSS (1.2.x), count() accepts:

• Literals — count(6), count(6, 1) (end, optional start)
• Parameters — count(@use(n)), count(@use(n), 1) inside @define
• Array length — count(@arr.data!.length), count(@arr.data!.length, 1)

@define bands(st:.wave, n:4){`
  @arr idx[count(@use(n), 1)]
  @use(st) .band-@arr.idx[]{
    /* n items, driven by @use(n) */
  }
`}

@bands(.hero-wave, 6)

@arr data[10, 20, 30, 40, 50]
@arr idx[count(@arr.data!.length, 1)]

/* or */
@import((mirror) from fscss:micros)
@mirror(data, idx)

Older builds were less reliable when count() saw unresolved parameter text — modules from that era used literal count(4) plus a swappable array name. On 1.2.6+ you can pass size through @use or derive it from !.length without that workaround.

exec(_log, "message") remains the reliable way to see expansions. FSCSS still prefers silent empty output over hard failure for some bad expansions — log around the suspect site and compare console vs compiled CSS.

exec(_log, "before loop")
@arr colors-i[count(@arr.colors!.length, 1)]
exec(_log, "@arr.colors-i")

In the browser IDE: compile, watch console + CSS pane. CLI: write output to a file and search for expected selectors.

• Keyframe names — prefix (siri-pulse, flux-flow). Bare pulse collides as soon as a second animated module lands.
• Custom properties — same namespace everywhere (--siri-*, not mixed --wave-* / --siri-wave-*).
• Import names — bare module name or quoted URL/path. Related packs (siri-wave, flux-wave) stay separate module names; family ties live in docs and naming, not a variant path syntax.
• package.json — name drives libck my-module; file.usage.directive should match prefixes, or use "" if helpers are mixed.

Beyond the .fscss source: package.json with file.modules, file.remote, helpers, and optional xfcmd.enable / disable so the IDE can run:

libck my-module
yes

Details: modules guide · create-module · xfcmds guide.