Maintaining a Jeet.gs Fraction Grid: Architecture Notes for Legacy Stylus Layouts

The problem this solves

If you have inherited a Stylus codebase that uses column(1/3) and cycle(3) and your grids break whenever items have uneven heights, you are dealing with Jeet.gs, a float-based CSS grid system where layout intent lives in the stylesheet rather than in presentational markup classes. The useful takeaway: Jeet's fraction model is simple and sound, but almost every production bug with it traces back to missing or mismatched cycle/uncycle calls, and the right long-term decision is usually to freeze it in place rather than extend it.

Requirements Jeet was designed for

Jeet exists to answer one question: how do you express "this element is one third of its container, with gutters" without hardcoding a 12-column class system into your HTML? Its answer is fraction-based mixins compiled at build time:

• Column widths are ratios — column(1/3) computes a percentage width, so any denominator works, not just twelfths.
• Gutters are a single ratio argument applied through negative-margin math, so changing gutter size means changing one argument, not recalculating a class family.
• Because it is a preprocessor mixin library (Stylus, with SCSS ports), it compiles away entirely. There is no runtime dependency and no client-side JavaScript.

That last point defines the trust boundary: the only thing you are trusting is a build-time compilation of your own stylesheets. There is no supply-chain surface beyond the pinned npm package itself.

The smallest suitable design

For a legacy codebase, the smallest defensible design is to keep Jeet exactly where it already works and draw a hard line against new usage. Native CSS Grid and Flexbox cover the same use cases without float-clearing bookkeeping, so new layout work should use them. A typical existing Jeet pattern looks like this in Stylus:

.product-list
  center(1200px, 1rem)

.product-card
  column(1/3, gutter: 2)
  cycle(3)
  margin-bottom: 2rem

This compiles to percentage widths with negative margins on the container and per-item margins. Nothing here is magic — which is exactly why it is safe to maintain. The compiled output is plain CSS you can inspect in devtools.

Where the trust and data boundaries sit

There is no data boundary: Jeet never touches content, only geometry. The trust boundary has two edges worth naming:

• Build-time only. The mixin library runs inside your Stylus (or SCSS) compilation. If the compiled CSS is correct, Jeet's job is done; there is nothing to audit at runtime.
• Frozen dependency. Jeet.gs has seen little active maintenance in recent years. Pin the exact version in your package manifest and treat it as frozen legacy tooling. Do not casually upgrade across major versions — the Stylus and SCSS ports differ in mixin names and defaults, so confirm which port and version your project actually uses before changing anything.

The failure mode that matters: cycle and uncycle

Jeet grids are floats. When items in a row have different heights, a shorter item lets the next row's first float catch on a taller one, and the whole grid cascades into misalignment. cycle(n) fixes this by clearing the margin on every nth item so each row starts cleanly. uncycle(n) removes that rule — which you need at responsive breakpoints when items per row change:

.product-card
  column(1/2, cycle: 2)

  @media (min-width: 900px)
    uncycle(2)
    column(1/3, cycle: 3)

The classic bug: a developer changes the breakpoint to show three cards per row, updates column(1/3), but forgets uncycle(2). The old every-second-item clearing now fights the new every-third-item clearing, producing wrapped, staggered rows that look random. When you see a Jeet layout break only at one breakpoint, check for a stale cycle value first — it is the most common cause.

Operational checks

Jeet failures do not throw errors; they manifest as misaligned or wrapped columns. That makes the operational check visual, not log-based:

1. Verify the pin: check package.json and the lockfile for jeet or jeet.gs, and confirm whether the Stylus or SCSS port is installed.
2. Compile a minimal stylesheet using column(1/3) with a gutter argument and inspect the generated CSS to confirm fraction-based percentage widths and negative margins are emitted as expected.
3. Render a grid with deliberately unequal item heights at each target breakpoint and confirm cycle/uncycle prevents wrapping artifacts.
4. Capture screenshots at those breakpoints as regression baselines, so any future mixin or breakpoint edit is checked against a known-good layout.

Run these checks in your normal build pipeline; no special permissions or environment are needed beyond the existing stylesheet compilation step.

Conditions that would change the design

Keep Jeet as-is while the layout is stable and the cost of touching it exceeds the benefit. Revisit the decision when any of these become true: you are adding new responsive breakpoints (each one multiplies cycle/uncycle bookkeeping), you are building new page sections (write those in CSS Grid instead), or the pinned build toolchain itself becomes a maintenance burden. At that point, migrate component by component — a Jeet float grid and a CSS Grid layout can coexist on the same page without conflict, so a gradual replacement is low-risk. The one thing to avoid is the middle ground: extending a float-based fraction grid with new features in 2026 is effort spent on a model the platform already provides natively.