TimeWarp.Flexbox library - compute CSS flexbox layouts (positions and sizes) in pure C# with no UI framework; a Native AOT-safe port of Facebook's Yoga engine. Use for laying out boxes/nodes in canvases, terminals, games, PDF/image generation, or custom renderers - anywhere you need flex-direction, flex-grow, wrap, gap, align/justify, percentages, or absolute positioning computed for you.

Maintained in timewarp-flexbox · Canonical file: SKILL.md

Install

npx skills add TimeWarpEngineering/timewarp-flexbox --skill flexbox

Or copy the SKILL.md into your agent's skills directory.

TimeWarp.Flexbox

Pure C# flexbox layout engine — build a tree of nodes, set CSS-flexbox styles, and read back computed pixel positions and sizes. No UI framework involved.

Repository: https://github.com/TimeWarpEngineering/timewarp-flexbox Package: TimeWarp.Flexbox

Behavior is a from-scratch port of Facebook's Yoga engine, verified against Yoga's own conformance suite (530 generated tests, LTR and RTL). Zero runtime dependencies; fully Native AOT and trimming compatible.

When to Use What

Core Model

Five steps, always the same shape:

using TimeWarp.Flexbox;

// 1. Build a node tree
Node root = new();
root.Style.FlexDirection = FlexDirection.Row;
root.Style.SetDimension(Dimension.Width, StyleSizeLength.Points(300));
root.Style.SetDimension(Dimension.Height, StyleSizeLength.Points(200));

Node left = new();
left.Style.FlexGrow = 1;
root.InsertChild(left, 0);          // 2. children attach via InsertChild(child, index)

Node right = new();
right.Style.FlexGrow = 2;
root.InsertChild(right, 1);

// 3. Calculate (float.NaN = unconstrained available space)
CalculateLayout.Calculate(root, float.NaN, float.NaN, Direction.LTR);

// 4. Read computed values from node.Layout
Console.WriteLine($"left:  x={left.Layout.GetPosition(PhysicalEdge.Left)} width={left.Layout.GetDimension(Dimension.Width)}");
Console.WriteLine($"right: x={right.Layout.GetPosition(PhysicalEdge.Left)} width={right.Layout.GetDimension(Dimension.Width)}");
// left:  x=0 width=100
// right: x=100 width=200

// 5. Change styles and re-Calculate any time — style writes dirty the tree automatically

Positions are relative to the parent. For absolute page coordinates, accumulate ancestors' positions (see Reading Results below).

CSS-to-C# Mapping

Two length types — do not mix them up:

• StyleSizeLength for dimensions and flex-basis (supports Auto, MaxContent, FitContent, Stretch).
• StyleLength for edges and gaps (margin, padding, border, position, gap; supports Auto for margins/positions).

Defaults Are Yoga's, Not Web CSS

This is the #1 source of surprises:

For web-style behavior, construct nodes with a web-defaults config:

Config config = new() { UseWebDefaults = true };
Node root = new(config);   // pass the same config to every node in the tree

Reading Results

float x = node.Layout.GetPosition(PhysicalEdge.Left);   // relative to parent
float y = node.Layout.GetPosition(PhysicalEdge.Top);
float w = node.Layout.GetDimension(Dimension.Width);
float h = node.Layout.GetDimension(Dimension.Height);

Positions are parent-relative. Accumulate for absolute coordinates:

static (float X, float Y) AbsolutePosition(Node node)
{
  float x = 0, y = 0;
  for (Node? n = node; n is not null; n = n.Owner)
  {
    x += n.Layout.GetPosition(PhysicalEdge.Left);
    y += n.Layout.GetPosition(PhysicalEdge.Top);
  }

  return (x, y);
}

Recipes

All outputs below are the actual values produced by the engine.

App shell: sidebar + header/main/footer

Node shell = new();
shell.Style.FlexDirection = FlexDirection.Row;
shell.Style.SetDimension(Dimension.Width, StyleSizeLength.Points(420));
shell.Style.SetDimension(Dimension.Height, StyleSizeLength.Points(200));
shell.Style.SetPadding(Edge.All, StyleLength.Points(8));
shell.Style.SetGap(Gutter.All, StyleLength.Points(8));

Node sidebar = new();
sidebar.Style.SetDimension(Dimension.Width, StyleSizeLength.Points(100));
shell.InsertChild(sidebar, 0);

Node content = new();
content.Style.FlexGrow = 1;                       // fill remaining width
content.Style.FlexDirection = FlexDirection.Column;
content.Style.SetGap(Gutter.All, StyleLength.Points(8));
shell.InsertChild(content, 1);

Node header = new();
header.Style.SetDimension(Dimension.Height, StyleSizeLength.Points(48));
content.InsertChild(header, 0);

Node main = new();
main.Style.FlexGrow = 1;                          // fill remaining height
content.InsertChild(main, 1);

Node footer = new();
footer.Style.SetDimension(Dimension.Height, StyleSizeLength.Points(32));
content.InsertChild(footer, 2);

CalculateLayout.Calculate(shell, float.NaN, float.NaN, Direction.LTR);
// sidebar: x=8  w=100 h=184   (stretched to fill cross axis inside padding)
// content: x=116 w=296
// main:    y=56 h=88          (relative to content; absolute = (116, 64))

Wrapping card grid with gap

Node grid = new();
grid.Style.FlexDirection = FlexDirection.Row;
grid.Style.FlexWrap = Wrap.Wrap;
grid.Style.SetGap(Gutter.All, StyleLength.Points(10));
grid.Style.SetDimension(Dimension.Width, StyleSizeLength.Points(250));
grid.Style.SetDimension(Dimension.Height, StyleSizeLength.Points(200));

for (int i = 0; i < 3; i++)
{
  Node card = new();
  card.Style.SetDimension(Dimension.Width, StyleSizeLength.Points(120));
  card.Style.SetDimension(Dimension.Height, StyleSizeLength.Points(60));
  grid.InsertChild(card, i);
}

CalculateLayout.Calculate(grid, float.NaN, float.NaN, Direction.LTR);
// card0: (0, 0)   card1: (130, 0)   card2: (0, 70)  <- wrapped, gap applied both axes

Corner overlay via absolute insets

Node overlay = new();
overlay.Style.PositionType = PositionType.Absolute;
overlay.Style.SetPosition(Edge.Right, StyleLength.Points(20));
overlay.Style.SetPosition(Edge.Bottom, StyleLength.Points(16));
overlay.Style.SetDimension(Dimension.Width, StyleSizeLength.Points(120));
overlay.Style.SetDimension(Dimension.Height, StyleSizeLength.Points(48));
root.InsertChild(overlay, root.Children.Count);
// inside a 420x160 root: overlay at (280, 96)

RTL

CalculateLayout.Calculate(root, float.NaN, float.NaN, Direction.RTL);
// A 200-wide row of two 30x30 children flows right-to-left:
// child0 x=170, child1 x=140

Content-measured leaf (text, images)

For leaves whose size depends on content, attach a measure function. It is called with the available space and a MeasureMode per axis:

Node text = new();
text.SetMeasureFunc((node, width, widthMode, height, heightMode) =>
{
  // widthMode/heightMode: Undefined (size to content), AtMost (fit within),
  // Exactly (value is fixed - your result for that axis is ignored)
  float measuredWidth = Math.Min(80, width);
  return new YGSize(measuredWidth, 20);
});
container.InsertChild(text, 0);
// In a 100x100 container: measure is called once with (100, Exactly, 100, AtMost)
// -> text ends up w=100 (Exactly wins over the measured 80), h=20 (AtMost honors it)

Nodes with a measure function cannot have children (asserted).

Incremental re-layout

Style writes mark the tree dirty automatically; just call Calculate again. Unchanged subtrees hit the internal measurement cache.

// two flexGrow:1 children in a 200-wide row -> a=100, b=100
b.Style.FlexGrow = 3;
CalculateLayout.Calculate(root, float.NaN, float.NaN, Direction.LTR);
// now a=50, b=150

Pitfalls

• A child belongs to one parent. InsertChild takes ownership; inserting a node that already has an owner throws YogaAssertException ("Child already has a owner, it must be removed first."). Call parent.RemoveChild(child) first — removal resets the child's layout and clears its owner.
• float.NaN means "undefined/unconstrained" for available space and any optional float. Check with Comparison.IsUndefined(value), not == NaN.
• StyleSizeLength vs StyleLength: dimensions/flex-basis take the former, edges/gaps the latter. The compiler catches it, but pick the right factory.
• Positions are parent-relative — accumulate up the Owner chain for absolute coordinates.
• One Config per tree: nodes constructed with different UseWebDefaults values cannot be mixed after construction (asserted on SetConfig).
• The whole API is float-based; use f literals or implicit int conversions.

Installation

dotnet add package TimeWarp.Flexbox

The package is on nuget.org and ships XML docs. Targets net10.0, zero dependencies, IsAotCompatible.

Further Reference

• samples/layout-demo/layout-demo.cs in the repo renders layouts as ASCII boxes in the terminal, or (with --html) as a page comparing engine output against the browser's native flexbox side by side.
• test/timewarp-flexbox-tests/Generated/ contains Yoga's conformance suite ported to C# — a searchable catalog of expected values for any flexbox scenario.
• Defaults, enums, and the full style surface: source/timewarp-flexbox/Style/Style.cs and Enums/YGEnums.cs.