Block Attribute Schema (Wbcom Block Quality Standard)

WB Gamification blocks adhere to the canonical Wbcom Block Quality Standard — a uniform attribute schema that every block carries so themes, page builders, and assistive tools can rely on the same controls (responsive spacing, typography, hover colours, visibility) across every Wbcom plugin.

This document is the reference for that schema as it ships in wb-gamification. Consumers building editor plugins, custom blocks that extend ours, or REST integrations should read it before relying on attribute names.

Source of truth: src/shared/utils/attributes.js (JavaScript export) and src/Blocks/CSS.php (PHP consumer). The standard is shared with wbcom-essential; both are derived from ~/.claude/skills/wp-block-development/references/block-quality-standard.md.

Directory casing matters. Block sources live at src/Blocks/<slug>/ (capital B, matches the WBGam\Blocks\ PSR-4 namespace) and compile to build/Blocks/<slug>/. The Registrar scans build/Blocks/ — case-sensitive on Linux production.

Where the schema lives

src/shared/utils/attributes.js   ← exported attribute groups
src/shared/utils/css.js          ← matching CSS generator (editor preview)
src/Blocks/CSS.php               ← PHP CSS generator (frontend render)

Spread the standard groups into a block’s attributes to opt in:

import { getStandardAttributes } from '../../shared';

export default {
  apiVersion: 3,
  name: 'wb-gamification/redemption-store',
  attributes: {
    ...getStandardAttributes(),
    // Block-specific attributes here.
    columns: { type: 'number', default: 3 },
  },
};

getStandardAttributes() is the union of uniqueIdAttribute, spacingAttributes, shadowAttributes, borderAttributes, and visibilityAttributes. Typography is opt-in (most blocks don’t need a built-in font picker) — import typographyAttributes separately when you do.

Attribute groups

`uniqueIdAttribute`

Key	Type	Default	Purpose
`uniqueId`	string	`''`	Per-instance scope. Generated by `useUniqueId()` on first render and persisted into post content. CSS rules emitted by `CSS::generate()` are scoped to `.wb-gam-block-{uniqueId}`.

Always include this attribute. Without it, two instances of the same block on a single page collide.

`spacingAttributes`

Per-side padding and margin with three responsive variants. Defaults: padding 24px on all sides; margin 0.

Key	Type	Default	Purpose
`padding`	object	`{ top: 24, right: 24, bottom: 24, left: 24 }`	Desktop.
`paddingTablet`	object	`undefined`	≤ 1024px.
`paddingMobile`	object	`undefined`	≤ 767px.
`paddingUnit`	string	`'px'`	One unit applies to all three breakpoints.
`margin`, `marginTablet`, `marginMobile`, `marginUnit`	—	—	Same shape.

undefined on tablet/mobile means “inherit desktop”. The CSS generator only emits a media-query block when the attribute is a populated object.

`typographyAttributes`

Optional. Import explicitly when a block exposes type controls.

Key	Type	Default	Purpose
`fontFamily`	string	`''`	CSS family list, sanitised on render.
`fontSize`, `fontSizeTablet`, `fontSizeMobile`	number	`undefined`	Three breakpoints.
`fontSizeUnit`	string	`'px'`	One unit for all three.
`fontWeight`	string	`''`	`normal`, `500`, etc.
`lineHeight`, `lineHeightUnit`	number / string	`undefined` / `''`	Unitless when blank.
`letterSpacing`	number	`undefined`	Always rendered as `px`.
`textTransform`	string	`''`	One of `none`, `uppercase`, `lowercase`, `capitalize`.

`shadowAttributes`

Key	Type	Default	Purpose
`boxShadow`	boolean	`false`	Master toggle. Other shadow keys are ignored when this is `false`.
`shadowHorizontal`	number	`0`	px
`shadowVertical`	number	`4`	px
`shadowBlur`	number	`8`	px (absolute)
`shadowSpread`	number	`0`	px
`shadowColor`	string	`'rgba(0, 0, 0, 0.12)'`	Any valid CSS colour.

`borderAttributes`

Key	Type	Default	Purpose
`borderRadius`	object	`{ top: 0, right: 0, bottom: 0, left: 0 }`	Per-corner radius. The standard treats the four object keys as TL/TR/BR/BL.
`borderRadiusUnit`	string	`'px'`

`visibilityAttributes`

Key	Type	Default	Purpose
`hideOnDesktop`	boolean	`false`	Adds `wb-gam-hide-desktop` class on the wrapper.
`hideOnTablet`	boolean	`false`	`wb-gam-hide-tablet`.
`hideOnMobile`	boolean	`false`	`wb-gam-hide-mobile`.

The matching utility classes live in src/shared/base.css and apply display: none !important at the matching breakpoint.

Render-side contract (PHP)

Every standardised block calls CSS::add( $unique_id, $attrs ) from its render.php to emit a scoped style tag in the page footer:

use WBGam\Blocks\CSS;

function wb_gam_render_redemption_store( array $attributes, string $content, $block ): string {
  $unique_id = ! empty( $attributes['uniqueId'] )
    ? $attributes['uniqueId']
    : substr( md5( wp_json_encode( $attributes ) ), 0, 10 );

  CSS::add( $unique_id, $attributes );

  $wrapper_attrs = get_block_wrapper_attributes(
    array(
      'class' => sprintf(
        'wb-gam-block-%s %s',
        sanitize_html_class( $unique_id ),
        CSS::get_visibility_classes( $attributes )
      ),
    )
  );

  return sprintf( '<div %s>…</div>', $wrapper_attrs );
}

The generator emits desktop rules at the top, then @media (max-width: 1024px) for tablet, then @media (max-width: 767px) for mobile — matching the breakpoints in useResponsiveValue.js.

Filter hooks

Hook	Args	Purpose
`wb_gam_block_css` (filter)	`(string $css, string $unique_id, array $attrs)`	Override or augment the generated CSS for a given instance. Useful for theme override packs.
`wb_gam_block_manifests` (filter)	`(string[] $manifest_paths)`	Filter the list of `block.json` paths discovered by the auto-registrar.

Backwards compatibility

Saved post content containing the pre-migration block markup will gain deprecated migrations during Phase D of WBCOM-BLOCK-STANDARD-MIGRATION. Until then, only blocks rebuilt to the new schema (redemption-store first) carry these attributes.

Block Attribute Schema (Wbcom Block Quality Standard)

Where the schema lives

Attribute groups

uniqueIdAttribute

spacingAttributes

typographyAttributes

shadowAttributes

borderAttributes

visibilityAttributes