# css-cascade

> Every algorithm contract in this domain is listed with its position on the derivation loop, its intent and invariant, the flow it walks, its productions as a…

Page: Ontology · Algorithms
Canonical: https://banes-lab.com/ontology/algorithms#algo-domain-css-cascade

Every algorithm contract in this domain is listed with its position on the derivation loop, its intent and invariant, the flow it walks, its productions as a grammar, what it composes and is composed by, which forces and principles it answers to, what grounds it and what it grounds, and an exemplar where the record carries one. The diagram shows what composes what inside the domain.

Relations diagram

What composes what inside this domain.

```mermaid
flowchart LR
n_cascade_layer_partition["Cascade Layer Partition"]
n_token_source_of_truth["Token Source-of-Truth"]
n_type_keyed_appearance["Type-Keyed Appearance"]
n_custom_type_registration["Custom Type Registration"]
n_governed_construction_boundary["Governed Construction Boundary"]
n_placement_isolation["Placement Isolation"]
n_assembly_composition["Assembly Composition"]
n_layer_fitness_enforcement["Layer Fitness Enforcement"]
n_type_migration_centralization["Type-Migration Centralization"]
n_css_type_cascade_concern["CSS Type-Cascade Kernel"]
n_css_type_cascade_concern --> n_cascade_layer_partition
n_css_type_cascade_concern --> n_token_source_of_truth
n_css_type_cascade_concern --> n_type_keyed_appearance
n_css_type_cascade_concern --> n_custom_type_registration
n_css_type_cascade_concern --> n_placement_isolation
n_css_type_cascade_concern --> n_assembly_composition
n_css_type_cascade_concern --> n_layer_fitness_enforcement
```

### Cascade Layer Partition

- Math type: [algebra](https://banes-lab.com/records/reason/math-type-algebra.md)
- Yields: ordered-structure

Details

Intent
Declare one ordered set of named cascade layers once at the stylesheet root, assign every rule to exactly one layer, and let layer order — not selector specificity nor source order — decide precedence, so values, appearance, placement, and assembly can never fight for the same declaration.

Invariant
Style precedence must be a property of the layer a rule lives in, not of how specific its selector is; an unlayered rule silently outranks every layer and is therefore forbidden.

Flow

```text
Root → LayerOrderDeclaration → PerFileLayerBinding → LayerPrecedence → DeterministicCascade
```

Productions

```bnf
CascadeLayerPartition ::= <LayerOrderDeclaration> "->" <LayeredBindingSet> "->" <PrecedencePolicy>
LayerOrderDeclaration ::= "@layer" "tokens" "," "globals" "," "shell" "," "components" "," "app"
LayeredBinding ::= <StyleFile> "assigned_to" <ExactlyOneLayer>
PrecedencePolicy ::= "app_over_components_over_shell_over_globals_over_tokens" "," "layer_beats_specificity" "," "no_unlayered_rule"
```

Composes
[Architectural Style Boundary](https://banes-lab.com/records/algo/architectural-style-boundary.md), [Responsibility Boundary](https://banes-lab.com/records/algo/responsibility-boundary.md)

Composed by
[CSS Type-Cascade Kernel](https://banes-lab.com/records/algo/css-type-cascade-concern.md)

Forces
[modularity](https://banes-lab.com/records/force/modularity.md)

Grounds
none

Before

```text
.foo { color: red; }
#page .foo { color: blue; }
```

After

```text
@layer tokens, globals, components, app;
@layer globals { [data-el="foo"] { color: var(--fg); } }
@layer app { .foo-view { gap: var(--space-4); } }
```

### Token Source-of-Truth

- Math type: [set-theory](https://banes-lab.com/records/reason/math-type-set-theory.md)
- Yields: set | boolean

Details

Intent
Define every design primitive — color, space, radius, the type scale, size, duration, z-index — exactly once as a custom property in the tokens layer, and forbid any downstream literal where a token exists.

Invariant
Values are canonical data with a single source; a literal in globals, components, or app where a token exists is duplication, not styling.

Flow

```text
Primitive → TokenDeclaration → DownstreamReference → NoLiteralWhereTokenExists
```

Productions

```bnf
TokenSourceOfTruth ::= <PrimitiveSet> "->" <TokenDeclarationSet> "->" <ReferenceOnlyDownstream>
TokenCategory ::= "color" | "space" | "radius" | "type_scale" | "size" | "duration" | "z_index"
LiteralPolicy ::= "reference_token" | "zero_value_exempt"
```

Composes
[Canonical Data](https://banes-lab.com/records/algo/canonical-data.md)

Composed by
[CSS Type-Cascade Kernel](https://banes-lab.com/records/algo/css-type-cascade-concern.md)

Forces
[semantic_consistency](https://banes-lab.com/records/force/semantic-consistency.md), [performance_scaling](https://banes-lab.com/records/force/performance-scaling.md)

Grounds
none

Before

```text
.foo { color: #33bb55; }
.bar { color: #33bb55; }
```

After

```text
@layer tokens { :root { --foo: #33bb55; } }
@layer globals { [data-el="foo"], [data-el="bar"] { color: var(--foo); } }
```

### Type-Keyed Appearance

- Math type: [logic](https://banes-lab.com/records/reason/math-type-logic.md)
- Yields: boolean

Details

Intent
In the globals layer, define how every element and component type looks, its size, and its spacing exactly once, keyed only by element tag, `data-el` custom type, and the orthogonal `data-*` axes (`data-variant` paint, `data-size` scale, `data-gap` child rhythm, `data-tone` palette, `data-measure` width); never key appearance by a purpose-class, and let every value be a token.

Invariant
Appearance is a contract owned by a type, not by a use-site; a purpose-class in globals fragments one type's look across many call-sites and is forbidden.

Flow

```text
Type → GlobalAppearanceRule → DefinedOncePerType → TokenizedValues
```

Productions

```bnf
TypeKeyedAppearance ::= <TypeSelector> "->" <AppearanceRule> "->" <DefinedOncePerType>
TypeSelector ::= <ElementTag> | "[data-el=" <CustomType> "]" | <TypeSelector> "[data-" ("variant"|"size"|"gap"|"tone"|"measure"|"layout") "=" <Value> "]"
AppearanceProperty ::= "look" | "size" | "spacing" | "intrinsic_rendering_behavior"
ForbiddenKey ::= "purpose_class"
```

Composes
[Canonical Data](https://banes-lab.com/records/algo/canonical-data.md), [Domain Boundary](https://banes-lab.com/records/algo/domain-boundary.md)

Composed by
[CSS Type-Cascade Kernel](https://banes-lab.com/records/algo/css-type-cascade-concern.md)

Forces
[contract_compatibility](https://banes-lab.com/records/force/contract-compatibility.md)

Grounds
none

Before

```text
.foo-label { font-size: 12px; color: gray; }
```

After

```text
@layer globals { [data-el="foo"] { font-size: var(--text-sm); color: var(--fg-muted); } }
```

### Custom Type Registration

- Math type: [set-theory](https://banes-lab.com/records/reason/math-type-set-theory.md)
- Yields: set | boolean

Details

Intent
Extend the stylable element vocabulary beyond the native HTML tag set by registering each semantic type against a base tag and a `data-el` stamp; the registered type becomes a first-class node the globals layer binds one appearance contract to, so a concept no native tag can express — a field-label, an icon, a toast, an entry — is styled by its type, never by a class.

Invariant
The set of stylable types is open and self-registered, not limited to the HTML tag set; a new appearance contract is a newly registered type plus one global rule, never a new purpose-class.

Flow

```text
SemanticConcept → DefineElement(type, baseTag, dataEl) → TypeRegistry → DataElStamp → GlobalAppearanceContract
```

Productions

```bnf
CustomTypeRegistration ::= <SemanticConcept> "->" <ElementDefinition> "->" <TypeRegistryEntry> "->" <RenderedTypeStamp> "->" <AppearanceBinding>
ElementDefinition ::= "type" "," "baseTag" "," "dataElToken"
RenderedTypeStamp ::= <BaseTag> "carrying" "data-el=" <DataElToken>
AppearanceBinding ::= "[data-el=" <DataElToken> "]" "owns_exactly_one_global_appearance_rule"
```

Composes
[Extension Point](https://banes-lab.com/records/algo/extension-point.md), [Self-Description Manifest](https://banes-lab.com/records/algo/self-description-manifest.md)

Composed by
[CSS Type-Cascade Kernel](https://banes-lab.com/records/algo/css-type-cascade-concern.md)

Forces
[contract_compatibility](https://banes-lab.com/records/force/contract-compatibility.md), [semantic_consistency](https://banes-lab.com/records/force/semantic-consistency.md)

Grounds
none

Before

```typescript
<span class="foo">…</span>
.foo { color: gray; }
```

After

```typescript
defineElement({ type: "foo", baseTag: "output", dataEl: "foo" });
@layer globals { [data-el="foo"] { color: var(--fg-muted); } }
```

### Governed Construction Boundary

- Math type: [computation](https://banes-lab.com/records/reason/math-type-computation.md)
- Yields: procedure

Details

Intent
Route all DOM creation through one governed factory that resolves a node spec of shape `{ el, variant, size, gap, tone, measure, layout, class, on, children }` against the type, handler, and component registries, maps each axis key to its `data-*` attribute, treats `class` as a gated hook (icon-font glyph, `u-*` utility, or `c-*` component — never bespoke, never appearance), throws on any unknown type, handler, or component, and refuses an inline `style` attribute.

Invariant
The construction surface must be structurally incapable of producing a node that is unstyled-by-type or carries an inline style; the illegal state is unrepresentable, not merely linted after the fact.

Flow

```text
NodeSpec → RegistryResolution → ScalarMapping → UnknownReject|InlineStyleReject → GovernedNode
```

Productions

```bnf
GovernedConstruction ::= <NodeSpec> "->" <RegistryLookup> "->" <ScalarApplication> "->" <GuardSet> "->" <RenderedNode>
NodeSpec ::= "el" "," "variant?" "," "size?" "," "gap?" "," "tone?" "," "measure?" "," "layout?" "," "class?" "," "on?" "," "children?"
ScalarApplication ::= "each_axis_key->data-attr" "," "class=gated_iconfont_or_u_or_c"
GuardSet ::= "throw_on_unknown_element" "," "throw_on_unknown_handler" "," "throw_on_unknown_component" "," "reject_style_attribute"
```

Composes
[Construction Boundary](https://banes-lab.com/records/algo/construction-boundary.md), [Error Boundary](https://banes-lab.com/records/algo/error-boundary.md), [Security Policy](https://banes-lab.com/records/algo/security-policy.md)

Forces
[modularity](https://banes-lab.com/records/force/modularity.md), [object_creation](https://banes-lab.com/records/force/object-creation.md)

Grounds
none

Before

```typescript
const n = document.createElement("div");
n.className = "foo";
n.style.color = "red";
```

After

```typescript
const n = dom({ el: "foo", tone: "bar", children: [text] });
```

### Placement Isolation

- Math type: [topology](https://banes-lab.com/records/reason/math-type-topology.md)
- Yields: boolean

Details

Intent
In the components layer, set only where a component sits — position, offsets, stacking, overlay — keyed by its type, and never its look, size, or spacing, which remain owned by globals.

Invariant
Placement and appearance are separate contracts; a placement rule that also sets a look re-opens a type's appearance outside its single global definition and breaks the layer partition.

Flow

```text
ComponentType → PlacementRule → PositionStackingOverlayOnly → NoAppearanceLeak
```

Productions

```bnf
PlacementIsolation ::= <ComponentType> "->" <PlacementRule> "->" <ForbiddenAppearanceSet>
PlacementProperty ::= "position" | "inset" | "top" | "right" | "bottom" | "left" | "z_index" | "float" | "clear"
ForbiddenInComponents ::= "color" | "font" | "size" | "spacing" | "border" | "radius"
```

Composes
[Responsibility Boundary](https://banes-lab.com/records/algo/responsibility-boundary.md), [Coupling Control](https://banes-lab.com/records/algo/coupling-control.md)

Composed by
[CSS Type-Cascade Kernel](https://banes-lab.com/records/algo/css-type-cascade-concern.md)

Forces
[contract_compatibility](https://banes-lab.com/records/force/contract-compatibility.md)

Grounds
none

Before

```text
@layer components { [data-el="foo"] { position: fixed; inset-block-end: 1rem; color: white; } }
```

After

```text
@layer components { [data-el="foo"] { position: fixed; inset-block-end: var(--space-4); z-index: var(--z-overlay); } }
```

### Assembly Composition

- Math type: [algebra](https://banes-lab.com/records/reason/math-type-algebra.md)
- Yields: ordered-structure

Details

Intent
In the app layer, compose views from structural containers and arrange their children with flex or grid and token-valued gaps, pad each container once so its children are full-width and fill the padded box, forbid horizontal margins, and never set or override any element's or component's look.

Invariant
Assembly arranges typed parts and owns child layout plus gutter discipline, but holds zero appearance authority, so a view can be recomposed without restyling a single type.

Flow

```text
View → ContainerSet → ChildArrangement → GutterConvention → NoAppearanceOverride
```

Productions

```bnf
AssemblyComposition ::= <View> "->" <StructuralContainerSet> "->" <ChildArrangement> "->" <GutterConvention>
ChildArrangement ::= "flex" | "grid" | "token_valued_gap"
GutterConvention ::= "container_pads_once" "," "child_width_100" "," "no_horizontal_margin" "," "narrower_via_explicit_width" "," "zero_margin_exempt"
AppearanceAuthority ::= "none"
```

Composes
[Responsibility Boundary](https://banes-lab.com/records/algo/responsibility-boundary.md)

Composed by
[CSS Type-Cascade Kernel](https://banes-lab.com/records/algo/css-type-cascade-concern.md)

Forces
[modularity](https://banes-lab.com/records/force/modularity.md)

Grounds
none

Before

```text
@layer app { .foo-view .bar { margin: 0 12px; box-shadow: 0 1px 2px; } }
```

After

```text
@layer app { .foo-view { display: grid; gap: var(--space-4); padding-inline: var(--space-4); } }
```

### Layer Fitness Enforcement

- Math type: [optimisation](https://banes-lab.com/records/reason/math-type-optimisation.md)
- Yields: boolean | ranking

Details

Intent
Bind each layer invariant to a machine check — layer order declared once, placement properties barred from globals, class selectors barred from globals, literals barred where a token exists, no horizontal margin, all DOM through the factory, no inline style — run them as hard errors with no warn tier and no inline disables, and gate the push on a clean verdict.

Invariant
A layer contract holds only if a fitness function fails the build when it is broken; the factory makes appearance-by-type unrepresentable and the linters make any residue unshippable.

Flow

```text
LayerInvariant → FitnessFunction → StaticCheck → HardErrorNoWarn → PushGate
```

Productions

```bnf
LayerFitnessEnforcement ::= <InvariantSet> "->" <FitnessFunctionSet> "->" <VerdictGate>
CssFitnessRule ::= "layer_order" | "no_appearance_in_components_or_app" | "no_class_in_globals" | "layered_class_format_c_or_u" | "no_bespoke_class" | "tokens_only" | "axis_value_validation" | "no_horizontal_margin"
DomFitnessRule ::= "factory_only_creation" | "no_inline_style"
GatePolicy ::= "hard_error_no_warn_tier" "," "no_inline_disable" "," "block_push_on_fail"
```

Composes
[Verification Fitness](https://banes-lab.com/records/algo/verification-fitness.md)

Composed by
[CSS Type-Cascade Kernel](https://banes-lab.com/records/algo/css-type-cascade-concern.md)

Forces
[contract_compatibility](https://banes-lab.com/records/force/contract-compatibility.md), [object_creation](https://banes-lab.com/records/force/object-creation.md), [architecture_evolution](https://banes-lab.com/records/force/architecture-evolution.md)

Grounds
none

Before

```typescript
reviewChecklist.push("no appearance in the app layer");
```

After

```typescript
export const rules = { "no-appearance-in-app": "error", "factory-only-creation": "error" };
```

### Type-Migration Centralization

- Math type: [computation](https://banes-lab.com/records/reason/math-type-computation.md)
- Yields: procedure

Details

Intent
To move an existing purpose-class or page-scoped stylesheet into this model, treat every appearance-bearing class rule as a migration unit, derive the element type it decorates, register a custom `data-el` type when no tag or variant expresses it, move its look, size, and spacing into one global rule keyed by that type, demote any residual position into components and any residual layout into app, and verify that zero appearance rule keyed by a purpose-class remains outside the globals layer.

Invariant
Migration is centralization by type: each scattered purpose-class appearance collapses into one type-keyed global rule, and completion is proven by the absence of appearance outside globals, not by a narrative claim.

Flow

```text
PurposeClassRule → DeriveType → RegisterTypeIfNeeded → MoveAppearanceToGlobals → DemoteResidue → ZeroAppearanceClassOutsideGlobals
```

Productions

```bnf
TypeMigration ::= <LegacyAppearanceRuleSet> "->" <TypeDerivation> "->" <GlobalCentralization> "->" <ResidueDemotion> "->" <ZeroDuplicationVerdict>
TypeDerivation ::= "existing_tag" | "existing_variant" | "register_new_data_el_type"
ResidueDemotion ::= "placement->components" "," "layout->app"
ZeroDuplicationVerdict ::= "no_appearance_keyed_by_purpose_class_outside_globals" | "incomplete"
```

Composes
[Centralization Kernel](https://banes-lab.com/records/algo/centralization-kernel.md), [Governance Evolution](https://banes-lab.com/records/algo/governance-evolution.md)

Forces
[semantic_consistency](https://banes-lab.com/records/force/semantic-consistency.md), [correctness_verification](https://banes-lab.com/records/force/correctness-verification.md), [model_governance](https://banes-lab.com/records/force/model-governance.md), [architecture_evolution](https://banes-lab.com/records/force/architecture-evolution.md)

Grounds
none

Before

```text
.foo { color: white; background: blue; position: sticky; top: 0; }
```

After

```text
@layer globals { [data-el="foo"] { color: var(--fg-on-accent); background: var(--bg-accent); } }
@layer components { [data-el="foo"] { position: sticky; top: 0; } }
```

### CSS Type-Cascade Kernel

- Meta record

Details

Intent
Declare one layer order, hold every value in tokens, key every appearance on a type — native or custom-registered — exactly once in globals, hold placement in components and assembly in app, create all DOM through a factory that stamps types and refuses inline style, and gate the whole contract behind machine fitness functions.

Invariant
Styling is reproducible when precedence is layer-decided, appearance is a per-type contract, the type vocabulary is open and factory-stamped, and every invariant has a build-failing check.

Flow

```text
LayerOrder → Tokens → TypeKeyedGlobals → Placement → Assembly → GovernedFactory → Fitness
```

Productions

```bnf
CssTypeCascadeKernel ::= <CascadeLayerPartition> "->" <TokenSourceOfTruth> "->" <TypeKeyedAppearance> "->" <CustomTypeRegistration> "->" <GovernedConstruction> "->" <PlacementIsolation> "->" <AssemblyComposition> "->" <LayerFitnessEnforcement>
StylingBoundary ::= "values_in_tokens" "," "appearance_by_type_in_globals" "," "app_frame_in_shell" "," "structure_in_components" "," "assembly_in_app"
OpenTypeVocabulary ::= "native_tag" | "registered_data_el_custom_type"
CascadeContract ::= "layer_decides_precedence" "," "one_definition_per_property_per_type" "," "factory_and_linters_enforce"
```

Composes
[Cascade Layer Partition](https://banes-lab.com/records/algo/cascade-layer-partition.md), [Token Source-of-Truth](https://banes-lab.com/records/algo/token-source-of-truth.md), [Type-Keyed Appearance](https://banes-lab.com/records/algo/type-keyed-appearance.md), [Custom Type Registration](https://banes-lab.com/records/algo/custom-type-registration.md), [Placement Isolation](https://banes-lab.com/records/algo/placement-isolation.md), [Assembly Composition](https://banes-lab.com/records/algo/assembly-composition.md), [Layer Fitness Enforcement](https://banes-lab.com/records/algo/layer-fitness-enforcement.md)

Forces
[contract_compatibility](https://banes-lab.com/records/force/contract-compatibility.md), [object_creation](https://banes-lab.com/records/force/object-creation.md), [architecture_evolution](https://banes-lab.com/records/force/architecture-evolution.md)

Grounds
none

## Links to

- [Algebra](https://banes-lab.com/records/reason/math-type-algebra.md)
- [Architectural Style Boundary](https://banes-lab.com/records/algo/architectural-style-boundary.md)
- [Responsibility Boundary](https://banes-lab.com/records/algo/responsibility-boundary.md)
- [CSS Type-Cascade Kernel](https://banes-lab.com/records/algo/css-type-cascade-concern.md)
- [modularity](https://banes-lab.com/records/force/modularity.md)
- [Set Theory](https://banes-lab.com/records/reason/math-type-set-theory.md)
- [Canonical Data](https://banes-lab.com/records/algo/canonical-data.md)
- [semantic_consistency](https://banes-lab.com/records/force/semantic-consistency.md)
- [performance_scaling](https://banes-lab.com/records/force/performance-scaling.md)
- [Logic](https://banes-lab.com/records/reason/math-type-logic.md)
- [Domain Boundary](https://banes-lab.com/records/algo/domain-boundary.md)
- [contract_compatibility](https://banes-lab.com/records/force/contract-compatibility.md)
- [Extension Point](https://banes-lab.com/records/algo/extension-point.md)
- [Self-Description Manifest](https://banes-lab.com/records/algo/self-description-manifest.md)
- [Computation](https://banes-lab.com/records/reason/math-type-computation.md)
- [Construction Boundary](https://banes-lab.com/records/algo/construction-boundary.md)
- [Error Boundary](https://banes-lab.com/records/algo/error-boundary.md)
- [Security Policy](https://banes-lab.com/records/algo/security-policy.md)
- [object_creation](https://banes-lab.com/records/force/object-creation.md)
- [Topology](https://banes-lab.com/records/reason/math-type-topology.md)
- [Coupling Control](https://banes-lab.com/records/algo/coupling-control.md)
- [Optimisation](https://banes-lab.com/records/reason/math-type-optimisation.md)
- [Verification Fitness](https://banes-lab.com/records/algo/verification-fitness.md)
- [architecture_evolution](https://banes-lab.com/records/force/architecture-evolution.md)
- [Centralization Kernel](https://banes-lab.com/records/algo/centralization-kernel.md)
- [Governance Evolution](https://banes-lab.com/records/algo/governance-evolution.md)
- [correctness_verification](https://banes-lab.com/records/force/correctness-verification.md)
- [model_governance](https://banes-lab.com/records/force/model-governance.md)
- [Cascade Layer Partition](https://banes-lab.com/records/algo/cascade-layer-partition.md)
- [Token Source-of-Truth](https://banes-lab.com/records/algo/token-source-of-truth.md)
- [Type-Keyed Appearance](https://banes-lab.com/records/algo/type-keyed-appearance.md)
- [Custom Type Registration](https://banes-lab.com/records/algo/custom-type-registration.md)
- [Placement Isolation](https://banes-lab.com/records/algo/placement-isolation.md)
- [Assembly Composition](https://banes-lab.com/records/algo/assembly-composition.md)
- [Layer Fitness Enforcement](https://banes-lab.com/records/algo/layer-fitness-enforcement.md)