@vectoriox/iox-ui 5.13.1 → 5.14.0

package/index.d.ts

@@ -183,6 +183,12 @@ declare class BuilderImageComponent {
     src: string;
     alt: string;
     nodeId: string;
+    /**
+     * What a MARKED image shows while it has no source (design-system DS3) — set by each renderer from
+     * the shared `emptyImageSrc` (`@vectoriox/iox-ui/design-core`): the "Add image" label on the canvas,
+     * the blank on the live site, `null` for an unmarked image, which therefore renders as before.
+     */
+    emptySrc: string | null;
     /**
      * The `src` attribute value, or `null` to OMIT the attribute entirely when there is no image.
      *
@@ -194,8 +200,10 @@ declare class BuilderImageComponent {
      * filled when the visitor interacts (see element-context-state-plan.md).
      */
     get srcAttr(): string | null;
+    /** `data-iox-empty` while the placeholder stands in — the hook the shared fill rule keys on. */
+    get emptyAttr(): '' | null;
     static ɵfac: i0.ɵɵFactoryDeclaration<BuilderImageComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<BuilderImageComponent, "img[iox-img]", never, { "src": { "alias": "src"; "required": false; }; "alt": { "alias": "alt"; "required": false; }; "nodeId": { "alias": "nodeId"; "required": false; }; }, {}, never, never, false, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<BuilderImageComponent, "img[iox-img]", never, { "src": { "alias": "src"; "required": false; }; "alt": { "alias": "alt"; "required": false; }; "nodeId": { "alias": "nodeId"; "required": false; }; "emptySrc": { "alias": "emptySrc"; "required": false; }; }, {}, never, never, false, never>;
 }
 
 /** Directive-host spacer: the `<div>` IS the host — no wrapper. All styles on `.iox-node`. */
@@ -1634,6 +1642,19 @@ interface PageStyleSettings {
      */
     maxWidth: string;
 }
+interface PageStyleOptions {
+    /**
+     * `pageSettings.designSystem` (design-system DS3). A page created with the design system — or
+     * adopted into it (DS7) — falls back to the org's tokens for whatever it does not set itself:
+     * `background: var(--iox-page-bg)` (a PAINT — Glass and Midnight are gradients, so the shorthand),
+     * `color: var(--iox-text)`, `font-family: var(--iox-font-body)`. A page without the flag (every
+     * page saved before DS3) compiles exactly as before, so a seeded org never puts a new ground under
+     * legacy text — the page follows the same opt-in rule as the element-style marker (§3b-bis).
+     */
+    designSystem?: boolean;
+}
+/** The token fallbacks of a design-system page (spec tokens only). */
+declare const PAGE_TOKEN_FALLBACKS: Readonly<Record<string, string>>;
 /**
  * Compile page style settings into CSS declarations.
  *
@@ -1643,7 +1664,7 @@ interface PageStyleSettings {
  * `backgroundType` selects which background field wins — it is derived from the author's
  * colour/image choice rather than picked directly (see the builder's page-background.util).
  */
-declare function compilePageStyle(style: Partial<PageStyleSettings> | null | undefined): Record<string, string>;
+declare function compilePageStyle(style: Partial<PageStyleSettings> | null | undefined, options?: PageStyleOptions): Record<string, string>;
 
 /**
  * Shared data-source resolving pattern — the SINGLE source of truth for how an IoxDataSource
@@ -2772,5 +2793,5 @@ declare class GalleryLoop {
     private emit;
 }
 
-export { AOSService, BACKDROP_TWIN_KEY, BACKDROP_WHOLE_KEY, BREAKPOINTS, Breakpoint, BreakpointQueryKind, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, CONTAINER_HTML_TAGS, CONTEXT_ACTION_TYPES, CardComponent, ClientGalleryComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ContainerComponent, ContextStore, DEFAULT_GALLERY_SCHEDULER, DEFAULT_PAGE_TRANSITION, DEFAULT_PAGE_TRANSITION_DURATION, DEFAULT_PAGE_TRANSITION_EASING, DEFAULT_PAGE_TRANSITION_PERSPECTIVE, DEFAULT_PHOSPHOR_WEIGHT, DEFAULT_WIDTH_BY_TYPE, DeclarationContext, FormRenderState, FormRuntimeService, GALLERY_EFFECTS, GALLERY_EFFECT_DESCRIPTORS, GalleryLoop, HOVER_DEFAULT_TRANSITION, HOVER_STATES, IOX_BUILDER_EVENTS, IOX_FORM_MESSAGES, IOX_FORM_NAVIGATOR, IOX_FORM_TRANSPORT, IS_PREVIEW, IoxAnimateContainer, IoxAosDirective, IoxAosModule, IoxBuilderComponentsModule, IoxComponentRegistryService, IoxDialogComponent, IoxFieldComponent, IoxFormComponent, IoxFormErrorComponent, IoxFormSuccessComponent, IoxPageComponent, IoxPageModule, IoxSubmitButtonComponent, IoxUiModule, LEGACY_HOVER_TRANSITION, LinkedContainerComponent, PAGE_TRANSITION_CATEGORIES, PAGE_TRANSITION_PRESETS, PART_CLASS_NAMES, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, RESERVED_ALIAS_PREFIX, STATE_PSEUDO_CLASS, SUPPRESSED_STYLE_PROPS_BY_TYPE, SWIPER_RESPONSIVE_TRAITS, SectionComponent, TRANSITION_FEELS, TextBlockComponent, VALIDATION_STATES, VALIDATION_STATE_CLASS, VIRTUAL_TRAIT_GROUPS, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, activeActions, applyBindingPipes, applyFeel, breakpointDef, breakpointForWidth, breakpointQueryFor, buildDataSourceFilter, buildPartSelector, buildRelatedFilter, buildSwiperBreakpoints, buildTargetedStateSelector, buildTransitionTimeline, cascadeChain, clearInputOverride, clearOverride, collectContextSlotKeys, collectReferencedAliases, compileDeclarations, compilePageStyle, composeVirtualTraits, computeRelative, containerHtmlTag, contextActionEffect, contextSlotKeys, countOverrides, dataSourcePlanToRequest, declaredInputNames, decomposeBackdropFilter, defaultHoverTransition, defaultMessageResolver, deriveSeoFromContent, describeSeoFields, effectiveTransitionId, excludeSelf, feelFor, getByPath, getSeoValue, hasHoverState, hasOwnTransition, initialSlotValues, isActionEnabled, isContextAction, isInputOverriddenAt, isOverriddenAt, isReservedAlias, isValidSlotKey, isWholeBackdropSet, legacyEnterToTransition, matchRouteParams, mediaQueryFor, mergeSwiperBreakpoints, nearestCommonAncestorId, nodeCssId, nodeUsesContext, normalizeCollectionResult, normalizeGalleryImage, normalizeIconClass, parentBreakpoint, parseUrlList, partClassName, planDataSource, planResponsiveRules, referencedDataSources, referencedDataSourcesDeep, renderDefaultDeclarations, resetSeoField, resolveBoundValue, resolveContextValue, resolveDerivedInto, resolveGalleryEffect, resolveGalleryUrls, resolveInputChain, resolveInputs, resolvePageTransition, resolvePath, resolveRelativeInto, resolveRepeaterItems, resolveSeo, resolveSiblings, resolveSingleItemId, resolveStateStyles, resolveStyleProps, resolveValueChain, rewriteViewportUnits, safeSetInput, setInputOverride, setOverride, setSeoAuto, setSeoBinding, setSeoOverride, setSeoValue, stateNamesIn, statePseudoClass, stripSuppressedProps, variableAliases, variableItemsFrom, withContextSlots, withDefaultHoverTransition, wrapInBreakpointQuery, wrapInMediaQuery };
-export type { BoundValueSpec, BreakpointDef, BuildRelatedFilterOptions, ContextActionEffect, ContextActionLike, ContextItemRef, ContextSlotDefault, ContextValueSpec, ContextWriteScope, DataSourceDomain, DataSourceEndpoints, DataSourceMode, DataSourcePlan, DataSourceQueryFilter, DataSourceRequest, DataSourceRequestSpec, DataSourceRouteFilter, DataSourceSpec, FormMessageResolver, GalleryBoundSource, GalleryDurations, GalleryEffect, GalleryEffectDescriptor, GalleryImage, GalleryLoopOptions, GalleryLoopScheduler, GalleryLoopState, GallerySlideState, IBuilderEventEmitter, InputMap, IoxContextSlot, IoxPipe, OverrideBreakpoint, PageStyleSettings, PageTransitionCategory, PageTransitionCategoryMeta, PageTransitionOptions, PageTransitionPreset, PipeArgSpec, PipeContext, PipeDescriptor, RelativeInputs, RelativeSourceKind, RelativeSourceSpec, ResolveSiblingsOptions, ResolvedPageTransition, ResponsiveLayer, ResponsiveOverrides, ResponsiveRuleSet, RouteContext, SeoDerivedContent, SeoFieldSource, SeoFieldState, SeoResolveContext, SetContextParams, SiblingsResult, StateStyleMap, StyleMap, StyleTreeNode, SwiperBreakpointMap, ToggleableAction, TransitionFeel, TransitionPhase, TransitionTimelineInput, ValueSource, VirtualTraitGroup };
+export { AOSService, BACKDROP_TWIN_KEY, BACKDROP_WHOLE_KEY, BREAKPOINTS, Breakpoint, BreakpointQueryKind, BuilderButtonComponent, BuilderDividerComponent, BuilderHeadingComponent, BuilderIconComponent, BuilderImageComponent, BuilderLinkComponent, BuilderSpacerComponent, ButtonBlockComponent, CONTAINER_HTML_TAGS, CONTEXT_ACTION_TYPES, CardComponent, ClientGalleryComponent, ClientListComponent, ClientListItemComponent, ClientRepeaterComponent, ClientSliderContainerComponent, ClientSliderSlideComponent, ComponentInstanceRegistryService, ContainerComponent, ContextStore, DEFAULT_GALLERY_SCHEDULER, DEFAULT_PAGE_TRANSITION, DEFAULT_PAGE_TRANSITION_DURATION, DEFAULT_PAGE_TRANSITION_EASING, DEFAULT_PAGE_TRANSITION_PERSPECTIVE, DEFAULT_PHOSPHOR_WEIGHT, DEFAULT_WIDTH_BY_TYPE, DeclarationContext, FormRenderState, FormRuntimeService, GALLERY_EFFECTS, GALLERY_EFFECT_DESCRIPTORS, GalleryLoop, HOVER_DEFAULT_TRANSITION, HOVER_STATES, IOX_BUILDER_EVENTS, IOX_FORM_MESSAGES, IOX_FORM_NAVIGATOR, IOX_FORM_TRANSPORT, IS_PREVIEW, IoxAnimateContainer, IoxAosDirective, IoxAosModule, IoxBuilderComponentsModule, IoxComponentRegistryService, IoxDialogComponent, IoxFieldComponent, IoxFormComponent, IoxFormErrorComponent, IoxFormSuccessComponent, IoxPageComponent, IoxPageModule, IoxSubmitButtonComponent, IoxUiModule, LEGACY_HOVER_TRANSITION, LinkedContainerComponent, PAGE_TOKEN_FALLBACKS, PAGE_TRANSITION_CATEGORIES, PAGE_TRANSITION_PRESETS, PART_CLASS_NAMES, PIPE_DESCRIPTORS, PIPE_REGISTRY, PageScrollProvider, RESERVED_ALIAS_PREFIX, STATE_PSEUDO_CLASS, SUPPRESSED_STYLE_PROPS_BY_TYPE, SWIPER_RESPONSIVE_TRAITS, SectionComponent, TRANSITION_FEELS, TextBlockComponent, VALIDATION_STATES, VALIDATION_STATE_CLASS, VIRTUAL_TRAIT_GROUPS, VIRTUAL_TRAIT_KEYS, ViewPositionDirective, ViewPositionModule, activeActions, applyBindingPipes, applyFeel, breakpointDef, breakpointForWidth, breakpointQueryFor, buildDataSourceFilter, buildPartSelector, buildRelatedFilter, buildSwiperBreakpoints, buildTargetedStateSelector, buildTransitionTimeline, cascadeChain, clearInputOverride, clearOverride, collectContextSlotKeys, collectReferencedAliases, compileDeclarations, compilePageStyle, composeVirtualTraits, computeRelative, containerHtmlTag, contextActionEffect, contextSlotKeys, countOverrides, dataSourcePlanToRequest, declaredInputNames, decomposeBackdropFilter, defaultHoverTransition, defaultMessageResolver, deriveSeoFromContent, describeSeoFields, effectiveTransitionId, excludeSelf, feelFor, getByPath, getSeoValue, hasHoverState, hasOwnTransition, initialSlotValues, isActionEnabled, isContextAction, isInputOverriddenAt, isOverriddenAt, isReservedAlias, isValidSlotKey, isWholeBackdropSet, legacyEnterToTransition, matchRouteParams, mediaQueryFor, mergeSwiperBreakpoints, nearestCommonAncestorId, nodeCssId, nodeUsesContext, normalizeCollectionResult, normalizeGalleryImage, normalizeIconClass, parentBreakpoint, parseUrlList, partClassName, planDataSource, planResponsiveRules, referencedDataSources, referencedDataSourcesDeep, renderDefaultDeclarations, resetSeoField, resolveBoundValue, resolveContextValue, resolveDerivedInto, resolveGalleryEffect, resolveGalleryUrls, resolveInputChain, resolveInputs, resolvePageTransition, resolvePath, resolveRelativeInto, resolveRepeaterItems, resolveSeo, resolveSiblings, resolveSingleItemId, resolveStateStyles, resolveStyleProps, resolveValueChain, rewriteViewportUnits, safeSetInput, setInputOverride, setOverride, setSeoAuto, setSeoBinding, setSeoOverride, setSeoValue, stateNamesIn, statePseudoClass, stripSuppressedProps, variableAliases, variableItemsFrom, withContextSlots, withDefaultHoverTransition, wrapInBreakpointQuery, wrapInMediaQuery };
+export type { BoundValueSpec, BreakpointDef, BuildRelatedFilterOptions, ContextActionEffect, ContextActionLike, ContextItemRef, ContextSlotDefault, ContextValueSpec, ContextWriteScope, DataSourceDomain, DataSourceEndpoints, DataSourceMode, DataSourcePlan, DataSourceQueryFilter, DataSourceRequest, DataSourceRequestSpec, DataSourceRouteFilter, DataSourceSpec, FormMessageResolver, GalleryBoundSource, GalleryDurations, GalleryEffect, GalleryEffectDescriptor, GalleryImage, GalleryLoopOptions, GalleryLoopScheduler, GalleryLoopState, GallerySlideState, IBuilderEventEmitter, InputMap, IoxContextSlot, IoxPipe, OverrideBreakpoint, PageStyleOptions, PageStyleSettings, PageTransitionCategory, PageTransitionCategoryMeta, PageTransitionOptions, PageTransitionPreset, PipeArgSpec, PipeContext, PipeDescriptor, RelativeInputs, RelativeSourceKind, RelativeSourceSpec, ResolveSiblingsOptions, ResolvedPageTransition, ResponsiveLayer, ResponsiveOverrides, ResponsiveRuleSet, RouteContext, SeoDerivedContent, SeoFieldSource, SeoFieldState, SeoResolveContext, SetContextParams, SiblingsResult, StateStyleMap, StyleMap, StyleTreeNode, SwiperBreakpointMap, ToggleableAction, TransitionFeel, TransitionPhase, TransitionTimelineInput, ValueSource, VirtualTraitGroup };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.13.1",
+  "version": "5.14.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",

package/src/design-core/element-styles.ts

@@ -272,10 +272,10 @@ export function switchElementStyle(
 
 /**
  * The element-style MARKER (design-system §3b-bis, spec `elementStyleMarker`). A node that wears an
- * element style renders `iox-es iox-es-<id>` in BOTH renderers; every piece of component CSS that
- * carries the system look is scoped to it, so a node saved before DS2 (no `elementStyle`) keeps its
- * exact pre-DS2 component CSS no matter which tokens the org holds. This is the ONLY thing a
- * renderer reads `elementStyle` for.
+ * element style renders `iox-es iox-es-<id>` in BOTH renderers, through the one node-class helper
+ * `nodeDesignClasses` (node-classes.ts); every piece of component CSS that carries the system look is
+ * scoped to it, so a node saved before DS2 (no `elementStyle`) keeps its exact pre-DS2 component CSS
+ * no matter which tokens the org holds.
  */
 export const ELEMENT_STYLE_MARKER_CLASS = 'iox-es';
 
@@ -286,22 +286,6 @@ export function elementStyleClass(id: string | null | undefined): string | null
     return elementStyleById(id) ? `${MARKER_PREFIX}${id}` : null;
 }
 
-/** The marker classes a node renders: `'iox-es iox-es-<id>'`, or `''` for a node with no (known) style. */
-export function elementStyleClasses(node: { elementStyle?: string | null } | null | undefined): string {
-    const own = elementStyleClass(node?.elementStyle);
-    return own ? `${ELEMENT_STYLE_MARKER_CLASS} ${own}` : '';
-}
-
-/** Make an element's marker match `elementStyle` — the live switch on the canvas, and the
- *  component path's one-time stamp. Removes a stale `iox-es-<old>`; touches no other class. */
-export function syncElementStyleMarker(el: { classList: DOMTokenList } | null | undefined, elementStyle: string | null | undefined): void {
-    if (!el?.classList) return;
-    const stale = Array.from(el.classList).filter(c => c === ELEMENT_STYLE_MARKER_CLASS || c.startsWith(MARKER_PREFIX));
-    for (const c of stale) el.classList.remove(c);
-    const classes = elementStyleClasses({ elementStyle });
-    if (classes) el.classList.add(...classes.split(' '));
-}
-
 /**
  * The spec's `headingLevelRule`: changing a Heading's level moves it to the new level's DEFAULT
  * style only when it still wears its old level's default (author changes kept, via

package/src/design-core/empty-image.ts

@@ -0,0 +1,52 @@
+import { hasElementStyleMarker } from './node-classes';
+
+/**
+ * Empty images (design-system DS3). A MARKED Image (`.iox-es-media`) with no source renders a box in
+ * the `surface-2` token with its aspect ratio kept — on the canvas with an "Add image" label, on the
+ * live site with nothing in it. An UNMARKED empty Image renders exactly as before (no `src`).
+ *
+ * Why a placeholder `src` instead of a src-less `<img>`: Chromium paints a src-less image as a broken
+ * image (a frame, an icon and the alt text) and ignores `aspect-ratio` once alt text is present, and no
+ * pseudo-element paints on an `<img>`. A real image with no natural size of its own (an SVG with no
+ * width/height) is a proper replaced element: `aspect-ratio`/`object-fit` apply, the background shows
+ * through, and its default object size (300×150) is the SAME for the canvas label and the live blank,
+ * so both renderers lay the box out identically. The fill itself is shared CSS (`iox-design.css`)
+ * keyed on {@link EMPTY_IMAGE_ATTRIBUTE}.
+ */
+
+/** Set on a marked Image while it has no source — the hook the shared fill rule keys on. */
+export const EMPTY_IMAGE_ATTRIBUTE = 'data-iox-empty';
+
+const svgUri = (svg: string) => `data:image/svg+xml,${encodeURIComponent(svg)}`;
+
+/** The live site's blank: an SVG with no intrinsic size and nothing in it. */
+export const EMPTY_IMAGE_SRC = svgUri('<svg xmlns="http://www.w3.org/2000/svg"/>');
+
+const xmlEscape = (s: string) => s.replace(/[&<>"']/g, c => `&#${c.charCodeAt(0)};`);
+
+/**
+ * The canvas blank: the same no-size SVG with `label` centred as a chip. The chip carries its own
+ * light ground, so it reads on every flavor's `surface-2`, light or dark; it is builder chrome, never
+ * site content. Width is estimated from the label length (an image cannot measure text).
+ */
+export function emptyImageLabelSrc(label: string): string {
+    const text = xmlEscape(label);
+    const width = Math.round(28 + label.length * 7);
+    return svgUri(
+        '<svg xmlns="http://www.w3.org/2000/svg"><svg x="50%" y="50%" overflow="visible">'
+        + `<rect x="${-width / 2}" y="-13" width="${width}" height="26" rx="13" fill="#ffffff" fill-opacity="0.92"/>`
+        + '<text x="0" y="0" text-anchor="middle" dominant-baseline="central" font-family="system-ui, -apple-system, \'Segoe UI\', sans-serif" '
+        + `font-size="12" font-weight="500" fill="#1f1d1b">${text}</text></svg></svg>`,
+    );
+}
+
+/**
+ * The `src` a node's Image renders when its own source is empty: the canvas label (when `label` is
+ * given) or the live blank for a MARKED node; `null` — render exactly as before — for an unmarked
+ * node or one that has a source.
+ */
+export function emptyImageSrc(node: { elementStyle?: string | null } | null | undefined, src: unknown, label?: string | null): string | null {
+    if (src != null && src !== '') return null;
+    if (!hasElementStyleMarker(node)) return null;
+    return label ? emptyImageLabelSrc(label) : EMPTY_IMAGE_SRC;
+}

package/src/design-core/node-classes.ts

@@ -0,0 +1,82 @@
+import { ELEMENT_STYLE_MARKER_CLASS, elementStyleClass } from './element-styles';
+import { SPEC_SCHEMES } from './flavor-spec.generated';
+
+/**
+ * The design-system classes a node renders, in BOTH renderers (builder canvas, engine component
+ * path, engine string path) — ONE helper, so the three can never disagree about which class a node
+ * carries:
+ *
+ * - the element-style MARKER `iox-es iox-es-<id>` (design-system §3b-bis) — component CSS carrying
+ *   the system look is scoped to it, so a node saved before DS2 keeps its pre-DS2 look;
+ * - the section colour scheme `iox-scheme-<id>` (§3c) for a non-default `colorScheme` — the class
+ *   `compileSchemeCss` re-declares tokens on, so everything inside re-resolves.
+ *
+ * Renderers read `elementStyle` and `colorScheme` for exactly this and nothing else.
+ */
+
+/** The section colour schemes — the contract's `schemes` keys. */
+export enum ColorScheme {
+    Default = 'default',
+    Subtle = 'subtle',
+    Inverse = 'inverse',
+    Accent = 'accent',
+}
+
+/** The content trait (stored in `props`, not a style prop) that picks a node's scheme. */
+export const COLOR_SCHEME_TRAIT = 'colorScheme';
+
+/** The node types that offer a scheme (spec §3c: Section/Container; LinkedContainer is a Container that links). */
+export const COLOR_SCHEME_TYPES: ReadonlyArray<string> = ['Section', 'Container', 'LinkedContainer'];
+
+/** Every scheme in contract order, with the contract's label (Default · Subtle · Inverse · Brand). */
+export const COLOR_SCHEMES: ReadonlyArray<{ readonly id: ColorScheme; readonly label: string }> =
+    (Object.keys(SPEC_SCHEMES) as ColorScheme[]).map(id => ({ id, label: (SPEC_SCHEMES as Record<string, { label: string }>)[id].label }));
+
+const SCHEME_IDS = new Set<string>(Object.keys(SPEC_SCHEMES));
+const SCHEME_PREFIX = 'iox-scheme-';
+const MARKER_PREFIX = `${ELEMENT_STYLE_MARKER_CLASS}-`;
+
+/** `iox-scheme-<id>` for a known NON-default scheme, else null — an unknown id never reaches a class attribute. */
+export function colorSchemeClass(id: unknown): string | null {
+    return typeof id === 'string' && id !== ColorScheme.Default && SCHEME_IDS.has(id) ? `${SCHEME_PREFIX}${id}` : null;
+}
+
+/** The node shapes this module reads: a serialized node (`props`) or a builder node (`traits[]`). */
+export interface DesignClassSource {
+    elementStyle?: string | null;
+    props?: Readonly<Record<string, unknown>> | null;
+    traits?: ReadonlyArray<{ name?: string; default?: unknown }> | null;
+}
+
+/** A node's `colorScheme`, from `props` (serialized) or its trait (builder). */
+export function colorSchemeOf(node: DesignClassSource | null | undefined): string | null {
+    if (!node) return null;
+    const fromProps = node.props?.[COLOR_SCHEME_TRAIT];
+    if (fromProps !== undefined) return typeof fromProps === 'string' ? fromProps : null;
+    const trait = node.traits?.find(t => t?.name === COLOR_SCHEME_TRAIT)?.default;
+    return typeof trait === 'string' ? trait : null;
+}
+
+/** True when the node wears a known element style — the marker is on it. */
+export function hasElementStyleMarker(node: { elementStyle?: string | null } | null | undefined): boolean {
+    return elementStyleClass(node?.elementStyle) !== null;
+}
+
+/** The classes a node renders: `'iox-es iox-es-card iox-scheme-inverse'`, or `''` for none. */
+export function nodeDesignClasses(node: DesignClassSource | null | undefined): string {
+    const marker = elementStyleClass(node?.elementStyle);
+    return [marker ? `${ELEMENT_STYLE_MARKER_CLASS} ${marker}` : '', colorSchemeClass(colorSchemeOf(node)) ?? '']
+        .filter(Boolean).join(' ');
+}
+
+const isDesignClass = (c: string) =>
+    c === ELEMENT_STYLE_MARKER_CLASS || c.startsWith(MARKER_PREFIX) || c.startsWith(SCHEME_PREFIX);
+
+/** Make an element's design classes match the node — the live switch on the canvas and the
+ *  component path's one-time stamp. Removes stale ones; touches no other class. */
+export function syncNodeDesignClasses(el: { classList: DOMTokenList } | null | undefined, node: DesignClassSource | null | undefined): void {
+    if (!el?.classList) return;
+    for (const c of Array.from(el.classList).filter(isDesignClass)) el.classList.remove(c);
+    const classes = nodeDesignClasses(node);
+    if (classes) el.classList.add(...classes.split(' '));
+}

package/src/design-core/public-api.ts

@@ -14,6 +14,8 @@ export * from './css-names';
 export * from './token-css';
 export * from './flavor';
 export * from './element-styles';
+export * from './node-classes';
+export * from './empty-image';
 export * from './brand';
 export * from './flavor-tokens';
 export * from './flavor-seed';

package/styles/iox-design.css

@@ -0,0 +1,30 @@
+/* Design-system component CSS that EVERY renderer needs — the ONE copy.
+ *
+ * Same reason as iox-forms.css: the SSR engine's string renderer emits plain markup, the engine's
+ * component path renders the shared components, and the builder canvas renders its own twins, so a
+ * component-scoped copy in each would be three copies that drift. Consumers add this file to their
+ * `angular.json` styles.
+ *
+ * Everything here is scoped to the element-style marker (design-system §3b-bis): a node saved
+ * before element styles never matches, so it renders exactly as before.
+ */
+
+/* Empty images (DS3). A marked Image with no source carries `data-iox-empty` and a size-less
+   placeholder src (design-core `emptyImageSrc`), so it stays a real replaced element: its own
+   aspect-ratio and object-fit apply and this fill shows through — on the canvas behind the
+   "Add image" label, on the live site on its own. Out-specifies the node rule (0,2,1 vs 0,1,0)
+   only while the image is empty. */
+img.iox-es-media[data-iox-empty] {
+    background-color: var(--iox-surface-2);
+}
+
+/* An empty marked Gallery takes the same fill, on the element that carries its node rule (size,
+   radius): the string renderer's one div, or the component's inner `.iox-gallery` under the
+   `<iox-gallery>` host that wears the marker. Its cinematic overlay has nothing to darken. */
+.iox-gallery.iox-es-media[data-iox-empty],
+iox-gallery.iox-es-media[data-iox-empty] > .iox-gallery {
+    background-color: var(--iox-surface-2);
+}
+.iox-es-media[data-iox-empty] .iox-gallery__overlay {
+    display: none;
+}