CascadeLayers

Remarks

Layers exist so that "which of these two rules wins" can be answered by where the rule lives rather than by how specific its selector happens to be. That is what makes the utility system in [doc 09](../../docs/plan/09-ui-framework.md) work at all: a generated `.p-4` is one class and a hand-written `.card .body` is two, so without layers the utility loses every time and the only fix is `!important` everywhere. With @layer base, components, utilities the answer is settled once, in one line, and specificity never enters into it. That line is Vixen's actual ladder — every theme sheet in the tree opens with it, and docs/guide/ui/cascade-layers.md is what it means.

⚠ A layer only wins if something is in a lower one, which is a less obvious condition than it sounds. The ladder above was declared and emitted into for a release before anything else joined it, and a lone @layer utilities against a tree of unlayered component sheets is strictly worse than no layers at all — the utility loses to a one-tag selector it would have beaten on specificity alone. The mechanism was never wrong; it simply had nobody to argue with.

Unlayered styles are not layer zero. They sit above every layer for normal declarations and below every layer for important ones, which is the same reversal importance applies to origins. Unlayered is a distinct index rather than a position in the list precisely so that neither direction can be got by accident.

Nested layers (@layer a.b) are flattened to their full dotted name. A nested layer orders inside its parent, and because a parent is always declared before anything can nest inside it, declaration order over full names already gives that — no tree needed.

Fields and properties (3)

• public const int Unlayered

  The index standing for "not in any layer".

• public int Count

  How many layers have been declared.

• public IReadOnlyList<string> Order

  The layers, in declaration order.

Methods (5)

• public int Declare(string name)

  Declares a layer, or returns the index it already has.

• public bool TryGetIndex(string name, out int index)

  Looks a layer up without declaring it.

• public int NormalRank(int layer)

  Where a layer sorts among normal declarations.

• public int ImportantRank(int layer)

  Where a layer sorts among !important declarations.

• public string NameOf(int layer)

  The name of a layer index, for diagnostics.

Used by (6)

• CascadeOrderTestsVixen.Ui.Styling.Tests
• SelectorMatchingTestsVixen.Ui.Styling.Tests
• StyleResolverVixen.Ui.Styling
• StyleRuleSetVixen.Ui.Styling
• StyleSheetLoaderVixen.Ui.Styling
• StyleSheetLoadingTestsVixen.Ui.Styling.Tests