---
title: "Decoration & visibility (BlockShell)"
description: "Field-level catalog tables below stay in English — they match the machine design schema used by the editor, API, and MCP."
---

Most blocks share one reusable shell: visibility rules and decoration live on the same prop set, not as separate block types. Blocks that use BlockShell list these fields at the end of their Fields section. Visibility controls who/where the block appears (breakpoints, locales, auth, route lock, roles). Decoration controls spacing, background, border, shadow, motion, and related chrome around the block content.

Field-level catalog tables below stay in English — they match the machine design schema used by the editor, API, and MCP.

## Fields

### `showOnBreakpoints`

Per-breakpoint visibility. Set a breakpoint to `false` to hide the block on that viewport. Missing keys default to visible.

### `showOnLocales`

Limit which website locales show the block. Empty / missing means all enabled locales. Set a locale to `false` to hide.

### `authVisibility`

Who can see the block based on website sign-in state.

### `routeLockVisibility`

On locked object routes, show always, only when unlocked, or only when locked.

### `roleVisibility`

Optional list of website user role labels. Empty means all roles. Matching is case-sensitive.

### `entryActionVisibility`

Object-component only: show when the current entry exposes matching actions.

### `queryPageVisibility`

Optional: limit list blocks to the first query page only.

### `customizeEnabled`

Enables the decoration controls below in the editor.

### `paddingEnabled`

Turns padding controls on for this block.

### `padding`

Theme spacing token applied as padding. Tokens let site owners customize spacing while blocks continue to share a consistent design language.

### `paddingByBreakpoint`

Theme spacing token per breakpoint. Use this when the block needs different, but still theme-consistent, spacing at different viewport sizes.

### `marginsEnabled`

Turns margin controls on (configured via size/position maps).

### `sizeByBreakpoint`

Optional width/height constraints per breakpoint. Modes: `fillParent` (stretch), `fitContent` (intrinsic), `static` (fixed length via `widthStatic`/`heightStatic` + unit), `ratio` (percent of the other axis via `widthRatio`/`heightRatio`).

### `overflow`

CSS overflow on the decoration frame.

### `pointerEvents`

Whether the decoration frame receives pointer events. Use `none` for full-page decorative backgrounds so clicks pass through.

### `positionEnabled`

Enables absolute/relative positioning overlays.

### `positionByBreakpoint`

Positioning overlays per breakpoint (`static`, `relative`, `absolute`, `fixed`, `sticky`) with optional offsets in pixels (`top`, `right`, `bottom`, `left`).

### `backgroundEnabled`

Enables background fill, gradient, or image.

### `backgroundWidth`

Background span: page column or full viewport bleed.

### `backgroundKind`

Solid color, gradient, image, muted autoplay video, or canvas animation (particles / reactive grid).

### `backgroundColorLight`

Solid background color in light theme.

### `backgroundColorDark`

Solid background color in dark theme.

### `gradientType`

Linear, radial, or conic gradient when `backgroundKind` is `gradient`.

### `gradientAngle`

Linear gradient direction or conic start angle in degrees when `backgroundKind` is `gradient`.

### `gradientColors`

Gradient stops with light/dark pairs and segment offsets (CSS % is the running sum).

### `backgroundImageSrc`

Background image source when `backgroundKind` is `image`.

### `backgroundImageMode`

How the background image is sized.

### `backgroundRepeatSize`

Tile size in pixels when background image mode is `repeat`.

### `backgroundPosition`

CSS background-position value.

### `backgroundMotionEnabled`

Seamless pan (and optional rotate) for image backgrounds.

### `backgroundMotionDirectionDeg`

Pan direction in degrees (0 = right).

### `backgroundMotionSpeed`

Relative pan speed for seamless cycling.

### `backgroundMotionRotateDegPerSec`

Continuous rotation speed in degrees per second (0 = off).

### `backgroundVideoSrc`

Video URL when `backgroundKind` is `video`. Always muted, autoplay, plays inline; never captures focus.

### `backgroundVideoFit`

`cover` / `fill` use object-fit; `repeat` tiles frames on canvas.

### `backgroundVideoLoop`

Loop the background video (default true).

### `backgroundAnimationMode`

Particle field or reactive grid (filled cells or continuous outlines) when `backgroundKind` is `animation`.

### `backgroundAnimShape`

Built-in shape or custom SVG for particles/grid cells.

### `backgroundAnimSvgSrc`

SVG URL when shape is `svg`.

### `backgroundAnimColorMode`

`solid` tints shapes; `fromAsset` keeps SVG colors.

### `backgroundAnimSize`

Base particle or cell size in pixels.

### `backgroundAnimJitter`

Particle-only 0–1 randomization for count, size, lifetime, and speed.

### `backgroundGridStyle`

Reactive grid rendering: filled `cells`, or `continuous` shape outlines tiled edge-to-edge into one connected lattice that ripples around the cursor. Ignored for `svg` shapes, which always render as cells.

### `backgroundGridHoverGrowLimitPct`

Maximum cell size change at the pointer. Positive values grow cells; negative values shrink them. A value of `50` reaches 150% scale after the configured reaction time.

### `backgroundGridHoverRotateLimitDeg`

Maximum cell rotation at the pointer. Positive values rotate clockwise; negative values rotate counterclockwise.

### `backgroundGridReactionTimeSec`

Seconds for cells or the continuous-grid ripple to reach their configured hover limit, and to return after the pointer leaves.

### `borderEnabled`

Enables border color, style, width, and radius.

### `borderColorLight`

Border color in light theme.

### `borderColorDark`

Border color in dark theme.

### `borderStyle`

CSS border style.

### `borderWidth`

Border width token.

### `borderRadius`

Border radius token.

### `shadowEnabled`

Enables box shadow values for light/dark themes.

### `shadowValueLight`

CSS box-shadow value in light theme.

### `shadowValueDark`

CSS box-shadow value in dark theme.

### `scrollAnimationEnabled`

Enables enter-on-scroll animation.

### `scrollAnimationType`

Enter-on-scroll animation preset.

### `scrollAnimationDuration`

Animation duration in milliseconds.

### `scrollAnimationDelay`

Animation delay in milliseconds.

### `cursorTiltEnabled`

Tilts the block slightly toward the pointer.

### `cursorTiltIntensity`

Strength of the cursor tilt effect.

### `transformEnabled`

Enables CSS transform controls.

### `transformRotateX`

Rotation around the X axis in degrees.

### `transformRotateY`

Rotation around the Y axis in degrees.

### `transformRotateZ`

Rotation around the Z axis in degrees.

### `transformTranslateX`

Horizontal translation in pixels.

### `transformTranslateY`

Vertical translation in pixels.

### `transformTranslateZ`

Depth translation in pixels.

### `transformScale`

Uniform scale factor (unitless).

### `transformPerspective`

CSS perspective distance in pixels.

### `decorationBySelector`

Advanced: apply decoration token overlays for `hover`, `active`, and `focus`. Missing overlay keys inherit the default flat props.

### `clipboard`

Editor-only copy/paste helpers for block props.

## Examples

**Hide on mobile**

```json
{
  "showOnBreakpoints": {
    "mobile": false
  }
}
```

**Signed-in only + light padding**

```json
{
  "authVisibility": "authenticated",
  "customizeEnabled": true,
  "paddingEnabled": true,
  "padding": "md"
}
```