Primitives

Primitives are the fastest way to prove your setup and the cleanest way to build geometric UI surfaces without external assets.

They are the right default when your scene language is still simple: panels, discs, badges, capsules, plates, blocks.

Supported types

• box
• sphere
• plane
• cylinder

When to use them

Use primitives when:

• you want zero asset loading
• the DOM box should define the visible form
• you are testing transforms, lights, materials, and filters first
• the scene is intentionally abstract or UI-like

Runtime contract

Activation

<div string="3d" string-3d="box"></div>

Attributes

Important CSS inputs

• shared transforms such as --translate-z and --rotate-y
• shared material inputs such as --material-type, --material-color, --material-metalness, --material-roughness
• shadow flags such as --shadow-cast and --shadow-receive

Example

<div
  string="3d"
  string-3d="box"
  style="
    width: 160px;
    height: 160px;
    --material-type: standard;
    --material-color: #ff6b2b;
    --material-metalness: 0.5;
    --material-roughness: 0.2;
    --rotate-y: 20;
    --translate-z: 60;
  "
></div>

Per-type mental model

Box

Best for cards, blocks, device-like surfaces, and any DOM rectangle that should keep its panel logic in 3D.

Sphere

Best for badges, blobs, tokens, or obviously volumetric accents.

Plane

Best for flat surfaces that should still receive perspective, light, and filter treatment.

Cylinder

Best for pills, rounded capsules, and soft industrial forms.

What the runtime does

• box and plane are mapped from the DOM box directly.
• sphere and cylinder use the DOM size as their layout anchor but build different underlying geometry.
• Material generation is shared with the rest of the rendering system, so primitives are not second-class test objects. They are full participants in the pipeline.

Practical note

If you are not sure where to start, start with a primitive. In most projects, box and plane cover the first 80% of scene experimentation.