@krapwoo/ds-viewer 0.4.4 → 0.4.5

package/README.md

@@ -190,13 +190,15 @@ actually apply:
   within what fits a 1280px laptop: 5 compact, 3 regular, or 2 wide columns. `states` items whose
   key matches a row or column key are not repeated below the grid.
 - `specimenSize: 'compact' | 'regular' | 'wide'` — the page's specimen width class.
-- `specimenSurface: 'neutral' | 'white' | 'dark' | 'transparent'` — the catalog-owned background
-  behind every live specimen on this page (list/grouped/grid cells, and a non-token `render()`
-  preview). Defaults to `'neutral'` (a light gray stage, visibly distinct from the surrounding
-  white card) — reach for `'dark'` to check a low-contrast component against a dark background, or
-  `'transparent'` when the surface itself would be misleading (e.g. a component whose own
-  elevation/shadow needs to read against the page, not a chip). Token galleries and sections always
-  keep their current, unstaged presentation regardless of this setting.
+- `specimenSurface: 'auto' | 'neutral' | 'white' | 'dark' | 'transparent'` — the fill of each
+  example's cell (list, grouped and grid cells, and a non-token `render()` preview). Defaults to
+  `'auto'`: after the page draws, a cell turns light gray only when its own example would vanish
+  against white (its largest coloured box is near-white with no visible border, like a white card,
+  sheet or neutral banner; a shadow alone doesn't count). Neighbouring examples keep a white cell,
+  and most pages need nothing. Override it when the guess is wrong: `'neutral'` makes every example
+  cell gray, `'white'` or `'transparent'` keeps them all white, and `'dark'` checks a light
+  component on a dark fill. Detection runs in the browser viewer; elsewhere cells stay white.
+  Token galleries and sections are never filled.
 - `variants`/`states`' own `maxColumns: 1 | 2 | 3 | 4 | 5` — caps how many columns that slot's list
   ever wraps into (e.g. a 3-item size scale that should always read as one row of exactly 3, never
   more just because a laptop is wide). A narrow window still drops below the cap when it has to —

package/dist/native/catalog/tokens.js

@@ -111,6 +111,8 @@ export const CATALOG_COLOR = {
     surfaceMuted: '#fafafa',
     /** Hover and pressed feedback on nav rows and buttons. */
     surfacePressed: '#f1f3f8',
+    /** An example's cell when the example itself is white (`specimenSurface`), darker than surfaceMuted so a white card's edges show. */
+    specimenStage: '#f2f2f2',
     pageBackground: '#f6f6f4',
     chip: '#eeeeee',
     /** Active nav label, prop types, scale bars. */

package/native/catalog/ComparisonGrid.tsx

@@ -2,7 +2,8 @@ import React from 'react';
 import { View, Text, ScrollView, StyleSheet } from 'react-native';
 import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_TYPE } from './tokens';
 import { COLUMN_MIN_WIDTH, MATRIX_LAYOUT, axisItems, cellKey, gridWidthBounds, indexCells, validateComparison } from './comparison';
-import { SpecimenSurface } from './SpecimenSurface';
+import { SpecimenContent, SpecimenSurface } from './SpecimenSurface';
+import { DEFAULT_SPECIMEN_SURFACE } from './specimenSurfaceStyle';
 import type { ComparisonDef, SpecimenSize, SpecimenSurfaceKind } from './types';
 
 /**
@@ -15,7 +16,7 @@ export function ComparisonGrid({
   def,
   size,
   sectionId,
-  surface = 'neutral',
+  surface = DEFAULT_SPECIMEN_SURFACE,
 }: {
   def: ComparisonDef;
   size: SpecimenSize;
@@ -63,17 +64,17 @@ export function ComparisonGrid({
             {columns.map((c, ci) => {
               const cell = cells.get(cellKey(row.key, c.key));
               return (
-                <View key={c.key} role="cell" style={[styles.cell, column, styles.bodyRow, styles.specimenCell, ci === lastColumn && styles.lastColumn]}>
-                  {cell?.node !== undefined ? (
-                    <SpecimenSurface surface={surface} style={cell.fill && styles.fill}>
-                      {cell.node}
-                    </SpecimenSurface>
-                  ) : (
+                cell?.node !== undefined ? (
+                  <SpecimenSurface key={c.key} role="cell" surface={surface} style={[styles.cell, column, styles.bodyRow, styles.specimenCell, ci === lastColumn && styles.lastColumn]}>
+                    <SpecimenContent fill={cell.fill}>{cell.node}</SpecimenContent>
+                  </SpecimenSurface>
+                ) : (
+                  <View key={c.key} role="cell" style={[styles.cell, column, styles.bodyRow, styles.specimenCell, ci === lastColumn && styles.lastColumn]}>
                     <Text style={styles.unavailable}>
                       {cell?.unavailableReason ? `Not supported — ${cell.unavailableReason}` : 'Missing example'}
                     </Text>
-                  )}
-                </View>
+                  </View>
+                )
               );
             })}
           </View>
@@ -102,7 +103,6 @@ const styles = StyleSheet.create({
   headerCell: { backgroundColor: CATALOG_COLOR.surfaceMuted, justifyContent: 'center' },
   bodyRow: { minHeight: MATRIX_LAYOUT.rowMinHeight },
   specimenCell: { alignItems: 'center', justifyContent: 'center' },
-  fill: { alignSelf: 'stretch' },
   headerText: { fontSize: CATALOG_TYPE.tableHeader, fontWeight: '800', letterSpacing: 0.44, color: CATALOG_COLOR.text },
   rowHeaderText: { fontSize: CATALOG_TYPE.md, fontWeight: '700', color: CATALOG_COLOR.text },
   unavailable: { fontSize: CATALOG_TYPE.sm, fontStyle: 'italic', textAlign: 'center', color: CATALOG_COLOR.textMuted },

package/native/catalog/ComparisonGroups.tsx

@@ -2,7 +2,8 @@ import React from 'react';
 import { View, Text, ScrollView, StyleSheet } from 'react-native';
 import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_TYPE } from './tokens';
 import { COLUMN_MIN_WIDTH, MATRIX_LAYOUT, type ListGroup } from './comparison';
-import { SpecimenSurface } from './SpecimenSurface';
+import { SpecimenContent, SpecimenSurface } from './SpecimenSurface';
+import { DEFAULT_SPECIMEN_SURFACE } from './specimenSurfaceStyle';
 import type { SpecimenSize, SpecimenSurfaceKind } from './types';
 
 /**
@@ -16,7 +17,7 @@ export function ComparisonGroups({
   groups,
   size,
   label,
-  surface = 'neutral',
+  surface = DEFAULT_SPECIMEN_SURFACE,
 }: {
   groups: ListGroup[];
   size: SpecimenSize;
@@ -46,11 +47,9 @@ export function ComparisonGroups({
                     <View style={styles.caption}>
                       <Text style={styles.captionText}>{item.label}</Text>
                     </View>
-                    <View style={styles.specimen}>
-                      <SpecimenSurface surface={surface} style={item.fill && styles.fill}>
-                        {item.node as React.ReactNode}
-                      </SpecimenSurface>
-                    </View>
+                    <SpecimenSurface surface={surface} style={styles.specimen}>
+                      <SpecimenContent fill={item.fill}>{item.node as React.ReactNode}</SpecimenContent>
+                    </SpecimenSurface>
                   </View>
                 );
               })}
@@ -102,5 +101,4 @@ const styles = StyleSheet.create({
     alignItems: 'center',
     justifyContent: 'center',
   },
-  fill: { alignSelf: 'stretch' },
 });

package/native/catalog/ComparisonList.tsx

@@ -2,7 +2,8 @@ import React, { useState } from 'react';
 import { View, Text, StyleSheet, type LayoutChangeEvent } from 'react-native';
 import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_TYPE } from './tokens';
 import { MATRIX_LAYOUT, listGeometry, type ListItem } from './comparison';
-import { SpecimenSurface } from './SpecimenSurface';
+import { SpecimenContent, SpecimenSurface } from './SpecimenSurface';
+import { DEFAULT_SPECIMEN_SURFACE } from './specimenSurfaceStyle';
 import type { SpecimenSize, SpecimenSurfaceKind } from './types';
 
 /**
@@ -17,7 +18,7 @@ export function ComparisonList({
   size,
   label,
   maxColumns,
-  surface = 'neutral',
+  surface = DEFAULT_SPECIMEN_SURFACE,
 }: {
   items: ListItem[];
   size: SpecimenSize;
@@ -60,11 +61,9 @@ export function ComparisonList({
                   <View style={styles.caption}>
                     <Text style={styles.captionText}>{item.label}</Text>
                   </View>
-                  <View style={styles.specimen}>
-                    <SpecimenSurface surface={surface} style={item.fill && styles.fill}>
-                      {item.node as React.ReactNode}
-                    </SpecimenSurface>
-                  </View>
+                  <SpecimenSurface surface={surface} style={styles.specimen}>
+                    <SpecimenContent fill={item.fill}>{item.node as React.ReactNode}</SpecimenContent>
+                  </SpecimenSurface>
                 </View>
               );
             })}
@@ -101,5 +100,4 @@ const styles = StyleSheet.create({
     alignItems: 'center',
     justifyContent: 'center',
   },
-  fill: { alignSelf: 'stretch' },
 });

package/native/catalog/SectionBlock.tsx

@@ -6,6 +6,7 @@ import { ComparisonGroups } from './ComparisonGroups';
 import { ComparisonList } from './ComparisonList';
 import { ReferenceDetails } from './ReferenceDetails';
 import { SpecimenSurface } from './SpecimenSurface';
+import { DEFAULT_SPECIMEN_SURFACE } from './specimenSurfaceStyle';
 import { TokenSections } from './TokenLayouts';
 import { choosePlacement, listGeometry, presentationBlocks, type PresentationBlock } from './comparison';
 import type { PreviewWidths, SectionDef, SpecimenSurfaceKind } from './types';
@@ -104,21 +105,23 @@ function frameLabel(width: number): string {
  *  chrome and token galleries. Every frame is its own live instance with its own state. `surface`
  *  is omitted for token galleries, which keep their current, unstaged presentation. */
 function Preview({ render, widths, surface }: { render: () => React.ReactNode; widths: PreviewWidths; surface?: SpecimenSurfaceKind }) {
-  const stage = (node: React.ReactNode) => (surface ? <SpecimenSurface surface={surface}>{node}</SpecimenSurface> : node);
-  if (widths === 'full') return <View style={styles.previewCard}>{stage(render())}</View>;
+  // Token galleries pass no surface: their card stays white.
+  const kind = surface ?? 'transparent';
+  if (widths === 'full') return <SpecimenSurface surface={kind} style={styles.previewCard}>{render()}</SpecimenSurface>;
   return (
     <View style={styles.previewCard}>
       <View style={styles.frames}>
         {widths.map((width, i) => (
-          <View
+          <SpecimenSurface
             key={`${width}-${i}`}
+            surface={kind}
             // Two live instances of the same component: name each so assistive tech can tell them apart.
             {...(widths.length > 1 ? ({ role: 'group', 'aria-label': frameLabel(width) } as Record<string, unknown>) : null)}
             style={[styles.frame, { width }]}
           >
             {widths.length > 1 && <Text style={styles.frameLabel}>{frameLabel(width)}</Text>}
-            {stage(render())}
-          </View>
+            {render()}
+          </SpecimenSurface>
         ))}
       </View>
     </View>
@@ -246,7 +249,7 @@ export function SectionBlock<TId extends string>({
   checkCompleteness(def);
   // Memoized so Blocks' placement effect runs on real changes, not on every render.
   const blocks = useMemo(() => presentationBlocks(def, { defaultPreviewWidths }), [def, defaultPreviewWidths]);
-  const surface = def.specimenSurface ?? 'neutral';
+  const surface = def.specimenSurface ?? DEFAULT_SPECIMEN_SURFACE;
   // react-native-web reads `aria-level`; React Native's prop types do not declare it.
   const headingLevelProps = { 'aria-level': headingLevel } as Record<string, unknown>;
 

package/native/catalog/SpecimenSurface.tsx

@@ -1,46 +1,84 @@
-import React from 'react';
+import React, { useCallback, useEffect, useRef, useState } from 'react';
 import { View, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
-import { CATALOG_COLOR, CATALOG_RADIUS, CATALOG_SPACE } from './tokens';
-import { SPECIMEN_SURFACE_WIDTH_STYLE } from './specimenSurfaceStyle';
+import { CATALOG_COLOR } from './tokens';
+import { DEFAULT_SPECIMEN_SURFACE, SPECIMEN_SURFACE_WIDTH_STYLE } from './specimenSurfaceStyle';
+import { blendsIntoCell, measurePaintedBoxes } from './specimenFill';
 import type { SpecimenSurfaceKind } from './types';
 
+type Browser = {
+  getComputedStyle?: (element: unknown) => never;
+  Element?: new () => unknown;
+  requestAnimationFrame?: (callback: () => void) => number;
+};
+
 /**
- * The catalog-owned background directly behind a live component specimen — shared by
- * `ComparisonList`, `ComparisonGroups`, `ComparisonGrid`, and `SectionBlock`'s component preview,
- * so a page's `specimenSurface` renders identically everywhere a specimen appears. Purely a fixed
- * backdrop: it never reads the wrapped component's own colors, never adds a border, and is never
- * used for token galleries/sections (those keep their existing full-width presentation). Always
- * stretches to its parent's width (see `specimenSurfaceStyle.ts`) rather than shrink-wrapping to
- * its content, centering that content itself — so a percentage-width specimen resolves against
- * the real comparison-cell width instead of collapsing to 0px.
+ * An example's whole cell area — shared by `ComparisonList`, `ComparisonGroups`,
+ * `ComparisonGrid`, and `SectionBlock`'s preview frames, so a page's `specimenSurface` fills every
+ * example cell the same way. With `'auto'` (the default) the cell measures its example after it
+ * draws and turns gray only when the example would vanish against white (a white card, sheet or
+ * neutral banner; see `specimenFill.ts`). Explicit kinds fill the cell without measuring. Adds no
+ * padding or border of its own: pass the cell's own layout in `style`. Measuring needs the
+ * browser's DOM; elsewhere `'auto'` leaves the cell white. Extra props (e.g. `role`) go to the View.
  */
 export function SpecimenSurface({
-  surface = 'neutral',
+  surface = DEFAULT_SPECIMEN_SURFACE,
   style,
   children,
+  ...viewProps
 }: {
   surface?: SpecimenSurfaceKind;
   style?: StyleProp<ViewStyle>;
   children: React.ReactNode;
+  [prop: string]: unknown;
 }) {
-  return <View style={[styles.base, SURFACE_FILL[surface], style]}>{children}</View>;
+  const ref = useRef<View>(null);
+  const [blends, setBlends] = useState(false);
+
+  const measure = useCallback(() => {
+    if (surface !== 'auto') return;
+    const browser = globalThis as unknown as Browser;
+    const node = ref.current as unknown;
+    if (!browser.getComputedStyle || !browser.Element || !(node instanceof browser.Element)) return;
+    const { boxes, cellArea } = measurePaintedBoxes(node as Parameters<typeof measurePaintedBoxes>[0], (element) => browser.getComputedStyle!(element));
+    setBlends(blendsIntoCell(boxes, cellArea));
+  }, [surface]);
+
+  useEffect(() => {
+    const raf = (globalThis as unknown as Browser).requestAnimationFrame;
+    if (surface !== 'auto' || !raf) return;
+    // Two frames, so the example's own styles and fonts have applied before measuring.
+    let cancelled = false;
+    raf(() => raf(() => {
+      if (!cancelled) measure();
+    }));
+    return () => {
+      cancelled = true;
+    };
+  }, [surface, measure]);
+
+  const fill = surface === 'auto' ? (blends ? FILL.neutral : undefined) : FILL[surface];
+  return (
+    <View ref={ref} onLayout={surface === 'auto' ? measure : undefined} style={[style, fill]} {...viewProps}>
+      {children}
+    </View>
+  );
 }
 
-// 'dark' reuses CATALOG_COLOR.text (the catalog's own darkest token) rather than adding a new
-// background-specific color — the catalog chrome has no existing dark-surface token to reach for.
-const SURFACE_FILL: Record<SpecimenSurfaceKind, ViewStyle> = {
-  neutral: { backgroundColor: CATALOG_COLOR.surfaceMuted },
+/** Wraps one example inside its cell: full cell width (so a percentage-width example resolves
+ *  against the cell), centered unless the example fills the cell. */
+export function SpecimenContent({ fill, children }: { fill?: boolean; children: React.ReactNode }) {
+  return <View style={fill ? styles.fill : styles.center}>{children}</View>;
+}
+
+// 'dark' reuses CATALOG_COLOR.text (the catalog's own darkest token); there is no dark-surface token.
+const FILL = StyleSheet.create({
+  neutral: { backgroundColor: CATALOG_COLOR.specimenStage },
   white: { backgroundColor: CATALOG_COLOR.surface },
   dark: { backgroundColor: CATALOG_COLOR.text },
-  transparent: { backgroundColor: 'transparent' },
-};
+  transparent: {},
+});
 
 const styles = StyleSheet.create({
-  base: {
-    ...SPECIMEN_SURFACE_WIDTH_STYLE,
-    alignItems: 'center',
-    justifyContent: 'center',
-    borderRadius: CATALOG_RADIUS.sm,
-    padding: CATALOG_SPACE.md,
-  },
+  center: { ...SPECIMEN_SURFACE_WIDTH_STYLE, alignItems: 'center' },
+  fill: { ...SPECIMEN_SURFACE_WIDTH_STYLE },
 });

package/native/catalog/specimenFill.ts

@@ -0,0 +1,102 @@
+/**
+ * Automatic cell fill for `specimenSurface: 'auto'` (the default): decides whether an example
+ * blends into its white comparison cell, so that one cell can turn gray. Kept free of any runtime
+ * import so `node --test` can assert on it directly (see `__tests__/specimenFill.test.ts`).
+ *
+ * The rule looks only at the example's largest painted box (the element with a background that
+ * covers the most area): if that box is near-white (every channel close to 255, so pale tints
+ * don't count) and has no visible border, the example's edges
+ * vanish against the white cell. A shadow alone doesn't count as an edge. Small boxes (under a
+ * tenth of the cell) and text-only examples never trigger it.
+ */
+
+export interface Rgba { r: number; g: number; b: number; a: number }
+
+/** One element inside an example, as measured in the browser. */
+export interface PaintedBox {
+  area: number;
+  background: Rgba | null;
+  /** The top border's colour when its width is above 0, else null. */
+  border: Rgba | null;
+}
+
+/** A fill is near-white when every channel (after compositing over the white cell) is at least
+ *  this. #fafafa and #f8f8f8 qualify; #f4f4f4 already reads as gray, and pale tints such as a
+ *  positive banner's rgb(240, 255, 244) read as colour, even when they're as bright as white. */
+const NEAR_WHITE_CHANNEL = 247;
+/** At or above this, a border draws the edge itself (#e4e4e4 is 1.27:1). */
+const VISIBLE_BORDER_CONTRAST = 1.2;
+/** A box smaller than this share of the cell is a detail, not the example's body. */
+const MIN_AREA_SHARE = 0.1;
+
+/** Parses a computed CSS colour (`rgb(…)`/`rgba(…)`). Fully transparent or unknown values are null. */
+export function parseCssColor(value: string): Rgba | null {
+  const match = /^rgba?\(\s*([\d.]+)[\s,]+([\d.]+)[\s,]+([\d.]+)(?:\s*[,/]\s*([\d.]+%?))?\s*\)$/.exec(value.trim());
+  if (!match) return null;
+  const alphaText = match[4];
+  const a = alphaText === undefined ? 1 : alphaText.endsWith('%') ? Number(alphaText.slice(0, -1)) / 100 : Number(alphaText);
+  if (!(a > 0)) return null;
+  return { r: Number(match[1]), g: Number(match[2]), b: Number(match[3]), a };
+}
+
+function channel(value: number): number {
+  const s = value / 255;
+  return s <= 0.04045 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+}
+
+/** True when every channel of `color`, composited over white, is at least `NEAR_WHITE_CHANNEL`. */
+export function isNearWhite(color: Rgba): boolean {
+  const over = (c: number) => color.a * c + (1 - color.a) * 255;
+  return Math.min(over(color.r), over(color.g), over(color.b)) >= NEAR_WHITE_CHANNEL;
+}
+
+/** WCAG contrast ratio against white, after compositing a translucent colour over the white cell. */
+export function contrastWithWhite(color: Rgba): number {
+  const over = (c: number) => color.a * c + (1 - color.a) * 255;
+  const luminance = 0.2126 * channel(over(color.r)) + 0.7152 * channel(over(color.g)) + 0.0722 * channel(over(color.b));
+  return 1.05 / (luminance + 0.05);
+}
+
+/** True when the example's body is near-white with no visible border, so it vanishes on a white cell. */
+export function blendsIntoCell(boxes: readonly PaintedBox[], cellArea: number): boolean {
+  let largest: PaintedBox | undefined;
+  for (const box of boxes) {
+    if (!box.background || box.area < cellArea * MIN_AREA_SHARE) continue;
+    if (!largest || box.area > largest.area) largest = box;
+  }
+  if (!largest?.background) return false;
+  if (!isNearWhite(largest.background)) return false;
+  return !(largest.border && contrastWithWhite(largest.border) >= VISIBLE_BORDER_CONTRAST);
+}
+
+/** Minimal DOM shapes, so this file needs no DOM lib types. */
+interface MeasurableElement {
+  getBoundingClientRect(): { width: number; height: number };
+  querySelectorAll(selector: string): ArrayLike<MeasurableElement>;
+}
+type ComputedStyleReader = (element: MeasurableElement) => {
+  backgroundColor: string;
+  borderTopColor: string;
+  borderTopWidth: string;
+  visibility: string;
+  opacity: string;
+};
+
+/** Measures every element inside `cell` (up to `limit`) in the browser. */
+export function measurePaintedBoxes(cell: MeasurableElement, readStyle: ComputedStyleReader, limit = 300): { boxes: PaintedBox[]; cellArea: number } {
+  const cellRect = cell.getBoundingClientRect();
+  const elements = cell.querySelectorAll('*');
+  const boxes: PaintedBox[] = [];
+  for (let i = 0; i < Math.min(elements.length, limit); i++) {
+    const element = elements[i];
+    const style = readStyle(element);
+    if (style.visibility === 'hidden' || Number(style.opacity) === 0) continue;
+    const rect = element.getBoundingClientRect();
+    boxes.push({
+      area: rect.width * rect.height,
+      background: parseCssColor(style.backgroundColor),
+      border: parseFloat(style.borderTopWidth) > 0 ? parseCssColor(style.borderTopColor) : null,
+    });
+  }
+  return { boxes, cellArea: cellRect.width * cellRect.height };
+}

package/native/catalog/specimenSurfaceStyle.ts

@@ -1,8 +1,10 @@
+import type { SpecimenSurfaceKind } from './types.ts';
+
 /**
- * `SpecimenSurface`'s width policy, kept free of any `react-native` import so `node --test` can
- * assert on it directly (see `native/catalog/__tests__/specimenSurfaceStyle.test.ts`).
+ * The example wrapper's width policy inside a cell, kept free of any `react-native` import so
+ * `node --test` can assert on it directly (see `__tests__/specimenSurfaceStyle.test.ts`).
  *
- * The surface always stretches to the full cross-axis width of whatever wraps it (a comparison
+ * The wrapper always stretches to the full cross-axis width of whatever wraps it (a comparison
  * cell, typically centered) rather than shrink-wrapping to its own content — `alignSelf: 'stretch'`
  * overrides a centered parent's `alignItems` for this one child. A compact specimen (e.g. Button)
  * still reads as centered, via `SpecimenSurface`'s own `alignItems`/`justifyContent: 'center'` on
@@ -13,3 +15,7 @@
 export const SPECIMEN_SURFACE_WIDTH_STYLE = {
   alignSelf: 'stretch',
 } as const;
+
+/** Each example's cell turns gray only when its example would vanish against white (see
+ *  `specimenFill.ts`). A page can force a fill with `specimenSurface`. */
+export const DEFAULT_SPECIMEN_SURFACE: SpecimenSurfaceKind = 'auto';

package/native/catalog/tokens.ts

@@ -119,6 +119,8 @@ export const CATALOG_COLOR = {
   surfaceMuted: '#fafafa',
   /** Hover and pressed feedback on nav rows and buttons. */
   surfacePressed: '#f1f3f8',
+  /** An example's cell when the example itself is white (`specimenSurface`), darker than surfaceMuted so a white card's edges show. */
+  specimenStage: '#f2f2f2',
   pageBackground: '#f6f6f4',
   chip: '#eeeeee',
   /** Active nav label, prop types, scale bars. */

package/native/catalog/types.ts

@@ -65,14 +65,12 @@ export type SpecimenSize = 'compact' | 'regular' | 'wide';
  *  content that is not a phone component (catalog chrome, token galleries). */
 export type PreviewWidths = readonly number[] | 'full';
 
-/** Background behind a live component specimen (the list/grouped/grid cell, or the preview frame)
- *  — a neutral (default), explicit white, dark, or transparent catalog-owned stage, so a specimen
- *  reads as visibly separate from the surrounding white card rather than floating on it, which
- *  matters most for a low-contrast or motion-only component that could otherwise blend into a
- *  plain white background. Purely a fixed catalog-chrome backdrop: it never inspects or infers the
- *  wrapped component's own colors, and is never applied to token galleries/sections, which keep
- *  their current full-width, unstaged presentation regardless of this setting. */
-export type SpecimenSurfaceKind = 'neutral' | 'white' | 'dark' | 'transparent';
+/** Fill of each example's cell. `'auto'` (default): a cell turns gray (#f2f2f2) only when its own
+ *  example would vanish against white — a near-white body with no visible border, like a white
+ *  card, sheet or neutral banner — so neighbouring examples keep a white cell. `'neutral'` makes
+ *  every example cell gray, `'white'` and `'transparent'` keep them white, `'dark'` checks light
+ *  components on a dark fill. Never applied to token galleries or sections. */
+export type SpecimenSurfaceKind = 'auto' | 'neutral' | 'white' | 'dark' | 'transparent';
 
 /** One real component this page's component is built from or composed with — rendered as a
  *  "Composition" subsection in Quick reference. `relationship` is `'built-in'` for a component
@@ -218,7 +216,7 @@ export interface SectionDef<TId extends string = string> {
    *  and everything else is 'regular'. */
   specimenSize?: SpecimenSize;
   /** Background stage behind every live component specimen on this page (list/grouped/grid cells,
-   *  and a `render()` preview that isn't a token gallery). Defaults to `'neutral'`. See
+   *  and a `render()` preview that isn't a token gallery). Defaults to `'auto'`. See
    *  `SpecimenSurfaceKind`. */
   specimenSurface?: SpecimenSurfaceKind;
   /** Widths for this page's `render()` preview, e.g. `[402, 320]` to add a small-phone example.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krapwoo/ds-viewer",
-  "version": "0.4.4",
+  "version": "0.4.5",
   "license": "MIT",
   "type": "module",
   "description": "A browsable, always-current catalog for an Expo / React Native design system.",