data-* attributes

All attributes

data-body frozen · attribute contract tokens

Space-separated force ids — required to make an element a body. Forces compose.

data-strength number · default 0.5

Force magnitude S.

data-range px · default 280

Influence radius d_max.

data-spin number · default 1

Sign/strength of rotation — swirl, charge, magnetism, lens.

data-angle deg · default 0

Heading — stream, jet, gate, shear, align.

data-color hex

Accent override on engage, and the carried color for pigment.

data-when condition · default ''

Gate the force on a condition: active, fast, slow, hot, cool, scrolling.

data-feedback flag

Opt into two-way density write-back (the --d custom property).

data-shaped flag

Shaped source — forces reference the nearest point on the element box, so matter shells the shape instead of bunching at its centre.

data-charge-gated flag

Opt-in fieldflow mode (magnetized plasma) — the fieldflow force follows only charged matter (charge ≠ 0) so it composes with charge; neutral matter drifts free. Omit for the default, which advects ALL matter (neutral-medium transport).

data-authority anchored | kinematic | dynamic · default anchored

Body-authority (substrate doc 04) — who owns the body position. anchored (default) measures from the DOM/host rect; kinematic = the engine writes the visual transform (the data-move pattern); dynamic = the engine owns position/velocity and the body moves — it integrates under the net field each frame (recoil / field-to-body coupling, doc 04 Step 5); momentum-recoil from own emission + torque are later refinements. Reported by query()/snapshot(). Experimental.

data-affects species

Matter tagging — a comma-separated species set this body acts on (e.g. "1" or "1,2"). Matter whose species is outside the set is skipped entirely (no force, no density sample). Omit to act on all matter (the default). Lets pollen / seeds / spores share one field, each pulled only by its own bodies.

data-species number

The species tag a spawn source stamps on the matter it emits, so a downstream data-affects body can act on it selectively. Particles default to species 0.

data-absorb px · default 64

Capture radius for the sink force.

data-max number · default 60

Load at which a sink supernovas (releases).

data-life frames · default 90 (spawn)

Source budget: how long each particle a spawn source emits lives. An unbudgeted source gets the safe default 300 (and a dev warning).

data-cap number

Source budget: the most live particles a spawn source sustains — the emission rate is clamped to cap/life. The unbudgeted-source safe default is 120.

data-screen-min number · default 0

Floor of the screen modifier's attenuation factor (0 = other forces may cancel fully at the screen's core).

data-fmin / data-fmax number

Variable-font weight range that --d drives on a feedback body.

data-opsz number

Optical-size axis to drive alongside weight.

data-active "1"

Engagement state — set automatically on hover/focus of a [data-hot] element.

data-preset name

Expand a preset into several co-located bodies — blackhole, galaxy, tornado, …

data-pair selector

Warp force: CSS selector for the partner body (the other end of the wormhole). Matter that enters this body is teleported to the partner. Omit on non-warp bodies.

data-twist deg · default 0

Warp force: rotation applied to matter crossing the throat — twist the exit angle.

data-scale number · default 1

Warp force: scale factor applied to matter velocity when it exits the partner throat.

data-budget flag

Source budget flag — marks a spawn source as explicitly budgeted without specifying data-life or data-cap. Suppresses the unbudgeted-source dev warning.

data-sink flag

Secondary budget indicator for a spawn source — if present, the engine treats the source as budgeted (equivalent to data-budget). Useful when paired with the sink force.

data-intent intent

Semantic authoring: a plain-language intent (e.g. "highlight" or "warn") that the engine compiles into the body's forces. When set, data-body is optional — the intent provides a default token + strength.

data-intensity number · default 1

Modifier for data-intent: scales the compiled strength (0 = subtle, 1 = default, 2 = strong). Ignored when data-body is set directly.

data-risk 'low' | 'medium' | 'high'

Intent hint for data-intent compilation — tunes the body's compiled forces when the intent has risk-sensitive variants.

data-field-role role

Semantic role: source / sink / anchor / boundary / sensor / display. Maps the element to a default body token and feedback (data-body is optional). sensor/display are feedback-only (no force).

data-field-boundary flag (engine-set)

Field-ownership marker — ENGINE-SET by a contained host (containerHost / the bounds: option) on its bounds element, not authored. A body belongs to the NEAREST enclosing marked boundary: outer/page-field scans skip bodies inside it, the contained field owns exactly its subtree, and nesting resolves to the nearest. Removed on destroy so the outer field re-adopts on rescan.

Which force reads which

Beyond the universal data-body / data-when / data-feedback, each force reads this subset (declared in the catalog):

attract

data-strengthdata-range

repel

data-strengthdata-range

swirl

data-strengthdata-rangedata-spin

stream

data-strengthdata-rangedata-angle

viscosity

data-strengthdata-range

jet

data-strengthdata-rangedata-angle

tether

data-strengthdata-range

wall

box-sized — no params

sink

data-absorbdata-max

gravity

data-strengthdata-range

charge

data-strengthdata-rangedata-spin

magnetism

data-strengthdata-rangedata-spin

thermal

data-strengthdata-range

collide

data-strengthdata-range

diffuse

data-strengthdata-range

propagate

data-strengthdata-range

memory

data-strengthdata-range

lens

data-strengthdata-rangedata-spin

gate

data-angle

buoyancy

data-strengthdata-range

shear

data-strengthdata-rangedata-angle

crystallize

data-strengthdata-range

align

data-strengthdata-rangedata-angle

wind

data-strengthdata-range

cohesion

data-strengthdata-range

pressure

data-strengthdata-range

hunt

data-strengthdata-range

spawn

data-strengthdata-angle

link

data-strengthdata-range

morph

data-strengthdata-target

resonate

data-strengthdata-spin

spotlight

data-angle

screen

data-strengthdata-rangedata-screen-min

pigment

data-rangedata-color

fieldflow

data-strengthdata-range

warp

data-absorbdata-pair

What the field writes back

Reciprocity has two halves: bodies bend the field through data-*, and the field bends them back through CSS custom properties. A body that opts in (data-feedback) receives these on its element — read them in your own CSS to make type glow, cards lift, or a meter fill. The write target is the element itself, or a body's writeTarget.

<field-root> HTML attributes

The <field-root> custom element mirrors every createField option as a kebab-case HTML attribute. Setting an attribute after mount calls the corresponding setter on the live handle — so declarative markup and imperative runtime control are the same surface.

accent option accent

Travelling accent color hex. Mirrors the accent createField option.

density option density

Particle-count multiplier. Mirrors the density createField option.

waves option waves

Draw background Currents. Mirrors the waves option (opt-in boolean attribute, #979 — presence = on, absence = off).

depth option depth

Optional z volume for a shallow 3D effect. Mirrors the depth createField option.

integrator option integrator

Integration scheme: 'fixed' opts into the partially frame-rate-corrected integrator (dt-scales the decays, not force impulses — doc-04 §Step 3), 'velocity-verlet' into the second-order Verlet scheme (#659); default 'legacy'. Mirrors the integrator createField option. Experimental.

render option render

Underlay render mode (none / dots / trails / links / metaballs / voronoi / streamlines / flow / knockout / redshift / blackbody / depth). Mirrors the render createField option.

overlay option overlay

Overlay reading(s) drawn in front of content — one or space-separated stack. Mirrors the overlay createField option.

palette option palette

Accent color template (built-in name or hex stops, space-separated). Mirrors the palette option.

mass option mass

First-class mass (boolean). Mirrors the mass createField option.

attention option attention

Conserved attention (boolean). Mirrors the attention createField option.

causality option causality

Cross-boundary causality (boolean). Mirrors the causality createField option.

heatmap option heatmap

Density heatmap (boolean). Mirrors the heatmap createField option.

dpr-cap option dprCap

Backing-store DPR ceiling (number). Mirrors the dprCap createField option.

grid-warp option gridWarp

Grid overlay distortion multiplier. Mirrors the gridWarp createField option.

grid-intensity option gridIntensity

Grid overlay stroke intensity. Mirrors the gridIntensity createField option.

theme option theme

Ambient theme preset (warm / cool / mono). Mirrors the theme createField option.

gradient-cool option gradientCool

Cool-end hex for the particle heat ramp. Mirrors the gradientCool createField option.

gradient-warm option gradientWarm

Warm-end hex for the particle heat ramp. Mirrors the gradientWarm createField option.

wave-baseline option waveBaseline

Hex stops for the background-wave baseline (space-separated). Mirrors the waveBaseline createField option.

wave-style option waveStyle

Wave current pattern (linear / circular). Mirrors the waveStyle createField option.

wave-center option waveCenter

Center coordinate for circular waves (space-separated x y). Mirrors the waveCenter createField option.

separation option separation

Short-range particle separation strength. Mirrors the separation createField option.

ambient-orbit option ambientOrbit

DECLARED resting-formation swirl on attract (#978); 0 for a purely radial attract. Mirrors the ambientOrbit createField option.

ambient-wander option ambientWander

DECLARED resting-formation drift (#978); lower for a calmer rest, 0 to still it. Mirrors the ambientWander createField option.

resting-motion option restingMotion

The resting-motion floor (declared, default OFF): 'thermal' | 'flow', optionally followed by a strength multiplier ('flow 0.5'). Honest idle motion for a drawn field with nothing painted; nothing under reduced motion. Mirrors the restingMotion createField option. Construction-time.

background option background

Substrate background (opaque / transparent). Mirrors the background createField option.

formation option formation

Global formation preset name. Mirrors the formation createField option (setFormation).