@krapwoo/ds-viewer 0.1.0 → 0.2.0

package/starter-kit/components/SegmentedToggle/SegmentedToggle.tsx

@@ -0,0 +1,163 @@
+import React, { useState } from 'react';
+import { View, Text, Pressable, Animated, I18nManager, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { DS_SEMANTIC, DS_SPACING, DS_RADIUS, DS_TYPOGRAPHY, DS_ICON_SIZE, DS_SHADOW, DS_A11Y_MIN_TOUCH_TARGET } from '../../tokens';
+import { Icon } from '../../icons/Icon.native';
+import type { IconName } from '../../icons';
+import { useSlideAnim } from './useSlideAnim';
+
+export interface SegmentedToggleOption {
+  value: string;
+  label: string;
+  /** Optional leading icon (16px) shown before the label. */
+  iconName?: IconName;
+  /** Optional count shown in a circular badge after the label (hidden when 0/undefined). */
+  badge?: number;
+}
+
+export interface SegmentedToggleProps {
+  /** The segments. */
+  options: SegmentedToggleOption[];
+  /** The currently-selected option `value`. */
+  value: string;
+  /** Selection handler. */
+  onChange: (value: string) => void;
+  style?: StyleProp<ViewStyle>;
+}
+
+const TRACK_PADDING = DS_SPACING[100]; // recessed track inset
+const GAP = DS_SPACING[100]; // space between segment slots
+const THUMB_INSET = DS_SPACING[100]; // shrinks the thumb inside its slot for breathing room
+const TRACK_COLOR = DS_SEMANTIC.surface.recessed; // track background — matches the secondary Button fill
+const THUMB_COLOR = DS_SEMANTIC.surface.white; // selected thumb (white pill)
+
+/**
+ * Segmented control — a row of mutually-exclusive options on a recessed track. A white "thumb" lifts
+ * the selected option and slides horizontally between segments on change. The thumb sits inset from its
+ * slot so there's a little gap around it. Two or more options.
+ */
+export function SegmentedToggle({ options, value, onChange, style }: SegmentedToggleProps) {
+  const n = options.length;
+  const selectedIndex = Math.max(0, options.findIndex(o => o.value === value));
+  const [trackW, setTrackW] = useState(0);
+  // Which segment currently holds keyboard focus (null = none) — one state for the whole row, since
+  // only one segment can be focused at a time.
+  const [focusedValue, setFocusedValue] = useState<string | null>(null);
+  // Fixed equal-width segments computed analytically, so translateX-only can stay native-driven.
+  const anim = useSlideAnim(selectedIndex, true);
+
+  const innerW = Math.max(0, trackW - TRACK_PADDING * 2);
+  const segW = n > 0 ? (innerW - GAP * (n - 1)) / n : 0;
+  const thumbW = Math.max(0, segW - THUMB_INSET * 2);
+  // Left edge of the thumb at each index (segment left + inset). `track`'s `flexDirection: 'row'`
+  // auto-mirrors the segments themselves in RTL, but this absolute-positioned thumb's `left`/
+  // `translateX` doesn't — so in RTL, index `i` visually renders at the *mirrored* slot (n-1-i).
+  const thumbX =
+    n > 1
+      ? anim.interpolate({
+          inputRange: options.map((_, i) => i),
+          outputRange: options.map((_, i) => {
+            const slot = I18nManager.isRTL ? n - 1 - i : i;
+            return TRACK_PADDING + slot * (segW + GAP) + THUMB_INSET;
+          }),
+        })
+      : TRACK_PADDING + THUMB_INSET;
+
+  return (
+    <View
+      style={[styles.track, style]}
+      onLayout={e => setTrackW(e.nativeEvent.layout.width)}
+      accessibilityRole="tablist"
+    >
+      {trackW > 0 && (
+        <Animated.View
+          pointerEvents="none"
+          style={[styles.thumb, { width: thumbW, transform: [{ translateX: thumbX }] }]}
+        />
+      )}
+      {options.map(opt => {
+        const selected = opt.value === value;
+        // Black label on the white thumb when selected; muted on the recessed track otherwise.
+        const color = selected ? DS_SEMANTIC.text.regular : DS_SEMANTIC.text.muted;
+        // The badge is a filled circle of the label colour; its number is white so it stays legible on
+        // both the black (selected) and muted-grey (unselected) circle.
+        const onColor = DS_SEMANTIC.surface.white;
+        return (
+          <Pressable
+            key={opt.value}
+            onPress={() => onChange(opt.value)}
+            onFocus={() => setFocusedValue(opt.value)}
+            onBlur={() => setFocusedValue(prev => (prev === opt.value ? null : prev))}
+            accessibilityRole="tab"
+            accessibilityLabel={opt.badge != null && opt.badge > 0 ? `${opt.label}, ${opt.badge}` : opt.label}
+            accessibilityState={{ selected }}
+            // Keyboard focus shows the same highlight as a press — a flat in-track target has no
+            // border to recolor, so focus mirrors the pressed treatment (same policy as ListItem).
+            style={({ pressed }) => [styles.segment, (pressed || focusedValue === opt.value) && styles.segmentPressed]}
+          >
+            {opt.iconName && <Icon name={opt.iconName} size={DS_ICON_SIZE.sm} color={color} />}
+            <Text style={[styles.label, { color }]}>{opt.label}</Text>
+            {opt.badge != null && opt.badge > 0 && (
+              <View style={[styles.badge, { backgroundColor: color }]}>
+                <Text style={[styles.badgeText, { color: onColor }]}>{opt.badge}</Text>
+              </View>
+            )}
+          </Pressable>
+        );
+      })}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  track: {
+    flexDirection: 'row',
+    backgroundColor: TRACK_COLOR,
+    borderRadius: DS_RADIUS.round,
+    padding: TRACK_PADDING,
+    gap: GAP,
+  },
+  // The lifted pill behind the selected segment — slides horizontally on change.
+  thumb: {
+    position: 'absolute',
+    left: 0,
+    top: TRACK_PADDING + THUMB_INSET,
+    bottom: TRACK_PADDING + THUMB_INSET,
+    backgroundColor: THUMB_COLOR,
+    borderRadius: DS_RADIUS.round,
+    ...DS_SHADOW.resting,
+  },
+  segment: {
+    flex: 1,
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: DS_SPACING[200],
+    paddingVertical: DS_SPACING[600],
+    // The track's own padding + this segment's content otherwise falls short of the touch-target
+    // minimum; a fixed floor (not a spacing token — this is an accessibility guideline number, not a
+    // design choice) keeps the segment's compact visual padding while still guaranteeing a tappable size.
+    minHeight: DS_A11Y_MIN_TOUCH_TARGET,
+  },
+  segmentPressed: {
+    backgroundColor: DS_SEMANTIC.interaction.pressed,
+    borderRadius: DS_RADIUS.round,
+  },
+  label: {
+    // Matches the section-header label size (labelXs) it stands in for.
+    ...DS_TYPOGRAPHY.labelXs,
+  },
+  // Fixed-diameter circle so the count badge stays round. 18 doesn't match a DS_SPACING/DS_ICON_SIZE
+  // step (16/20 are the neighbors) — sized to comfortably fit a 1-2 digit count at labelXs.
+  badge: {
+    width: 18,
+    height: 18,
+    borderRadius: DS_RADIUS.round,
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  badgeText: {
+    ...DS_TYPOGRAPHY.labelXs,
+    // Pinned to the badge's own 18px diameter (above) so the count sits centered in the circle.
+    lineHeight: 18,
+  },
+});

package/starter-kit/components/SegmentedToggle/index.ts

@@ -0,0 +1,2 @@
+export { SegmentedToggle } from './SegmentedToggle';
+export type { SegmentedToggleProps, SegmentedToggleOption } from './SegmentedToggle';

package/starter-kit/components/SegmentedToggle/useSlideAnim.ts

@@ -0,0 +1,29 @@
+import { useEffect, useRef } from 'react';
+import { Animated, Easing } from 'react-native';
+import { DS_MOTION_DURATION, DS_MOTION_EASING } from '../../tokens';
+
+/** How long the selection indicator takes to slide to its new position. */
+export const SLIDE_ANIM_MS = DS_MOTION_DURATION.base;
+
+/**
+ * Shared by SegmentedToggle and UnderlineTabs: an Animated.Value that eases to `selectedIndex`
+ * whenever it changes. Each component still does its own position math (SegmentedToggle computes
+ * fixed equal-width segments analytically; UnderlineTabs measures each tab's real width via onLayout)
+ * — those differ enough between the two that unifying them isn't safe to do blindly, but the "animate
+ * to the new index" mechanics underneath were byte-identical, so that part is shared here.
+ */
+export function useSlideAnim(selectedIndex: number, useNativeDriver: boolean) {
+  const anim = useRef(new Animated.Value(selectedIndex)).current;
+
+  useEffect(() => {
+    Animated.timing(anim, {
+      toValue: selectedIndex,
+      duration: SLIDE_ANIM_MS,
+      // `standard` — a move that starts and ends on screen (a toggle/swap), per DS_MOTION_EASING_USE.
+      easing: Easing.bezier(...DS_MOTION_EASING.standard),
+      useNativeDriver,
+    }).start();
+  }, [selectedIndex, anim, useNativeDriver]);
+
+  return anim;
+}

package/starter-kit/components/Shimmer/Breathing.catalog.tsx

@@ -0,0 +1,29 @@
+import React from 'react';
+import { StyleSheet } from 'react-native';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { Breathing } from './Shimmer';
+import { DS_RADIUS, DS_SEMANTIC } from '../../tokens';
+
+const styles = StyleSheet.create({
+  block: { width: 160, height: 16, borderRadius: DS_RADIUS.small },
+});
+
+export default defineCatalogPage({
+  component: 'Breathing',
+  group: 'Feedback',
+  description:
+    "The shared animated primitive behind Shimmer — a solid block that breathes between a low and high colour on one shared, module-level clock, so every Breathing/Shimmer instance on screen stays phase-locked instead of drifting out of sync. Exported so a custom composite skeleton can reuse the same pulse directly instead of going through Shimmer's fixed text/circle/container shapes.",
+  a11y: 'Renders a plain Animated.View with no role by default — pass accessibilityRole="progressbar" and accessibilityLabel yourself, the same way Shimmer does internally for its own standalone (non-grouped) blocks.',
+  variants: {
+    itemsFill: true,
+    items: [
+      { key: 'default', name: 'Default', node: <Breathing style={styles.block} /> },
+      {
+        key: 'custom-colors',
+        name: 'Custom colours',
+        props: { low: DS_SEMANTIC.shade.info, high: DS_SEMANTIC.emphasis.info },
+        node: <Breathing style={styles.block} low={DS_SEMANTIC.shade.info} high={DS_SEMANTIC.emphasis.info} />,
+      },
+    ],
+  },
+});

package/starter-kit/components/Shimmer/Shimmer.catalog.tsx

@@ -0,0 +1,89 @@
+import React from 'react';
+import { View, StyleSheet } from 'react-native';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { Shimmer, SkeletonGroup } from './Shimmer';
+import { DS_SPACING } from '../../tokens';
+
+const styles = StyleSheet.create({
+  shimmerLines: { flex: 1, gap: DS_SPACING[400] },
+  previewRow: { flexDirection: 'row', alignItems: 'center', gap: DS_SPACING[600] },
+});
+
+export default defineCatalogPage({
+  component: 'Shimmer',
+  group: 'Feedback',
+  description: 'Loading placeholders that breathe while content loads. `text` stands in for one line of text (an element with 3 lines gets 3 stacked `text` Shimmers, not one tall one), `circle` is always for a circular element, and `container` covers everything else (Card, Banner, image, …) — sized to match the real element it replaces, not an arbitrary block. When several stand in for one element, wrap them in `SkeletonGroup`.',
+  whenToUse: 'A composite skeleton (several Shimmers standing in for one element) → wrap them in SkeletonGroup so it announces "Loading" once, not once per block. A single lone Shimmer needs no wrapper — it announces on its own.',
+  a11y: 'A standalone Shimmer is exposed as accessibilityRole="progressbar" + accessibilityLabel="Loading". Inside a SkeletonGroup, each block goes silent and the group carries one busy "Loading" announcement for the whole skeleton — so a screen reader says "Loading" once, not once per block.',
+  // One standalone example per `variant` enum value (`text` is the default, so it comes first),
+  // plus the composed "Circle + text" usage — shown here too, not just under States, so Variants
+  // reads as complete on its own.
+  variants: {
+    itemsFill: true,
+    items: [
+      { key: 'text', name: 'Text (one line)', props: { variant: 'text' }, node: <Shimmer variant="text" width={160} /> },
+      { key: 'circle', name: 'Circle', props: { variant: 'circle' }, node: <Shimmer variant="circle" size={40} /> },
+      {
+        key: 'container',
+        name: 'Container (matches Card)',
+        props: { variant: 'container' },
+        // Same radius Card itself renders at (DS_RADIUS.medium, via dimensionsForVariant) and a
+        // plausible real Card content height — a container skeleton should reserve the same
+        // layout space the real element will occupy, not an arbitrary block.
+        node: <Shimmer variant="container" height={96} />,
+      },
+      {
+        key: 'circle-and-text',
+        name: 'Circle + text (2 lines)',
+        // SkeletonGroup so the whole avatar+2-lines skeleton announces "Loading" once, not three
+        // times (one per block) — it carries the caller's row layout itself.
+        node: (
+          <SkeletonGroup style={styles.previewRow}>
+            <Shimmer variant="circle" size={40} />
+            {/* Last line ~70% of the others' width — see ShimmerProps.variant's `'text'` doc. */}
+            <View style={styles.shimmerLines}>
+              <Shimmer variant="text" width={160} />
+              <Shimmer variant="text" width={112} />
+            </View>
+          </SkeletonGroup>
+        ),
+      },
+    ],
+  },
+  // Repeated here (not just in Variants) so States / Configurations is independently complete too.
+  states: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'circle-and-text',
+        name: 'Circle + text (2 lines)',
+        // SkeletonGroup so the whole avatar+2-lines skeleton announces "Loading" once, not three
+        // times (one per block) — it carries the caller's row layout itself.
+        node: (
+          <SkeletonGroup style={styles.previewRow}>
+            <Shimmer variant="circle" size={40} />
+            {/* Last line ~70% of the others' width — see ShimmerProps.variant's `'text'` doc. */}
+            <View style={styles.shimmerLines}>
+              <Shimmer variant="text" width={160} />
+              <Shimmer variant="text" width={112} />
+            </View>
+          </SkeletonGroup>
+        ),
+      },
+      {
+        key: 'three-lines',
+        name: 'Three lines of text',
+        node: (
+          // Explicit px widths (not "100%") specifically so the last line's 70% ratio is a real,
+          // checkable relationship to the other two, not two independent percentages. Wrapped in a
+          // SkeletonGroup so all three lines announce as one "Loading" region.
+          <SkeletonGroup style={styles.shimmerLines}>
+            <Shimmer variant="text" width={200} />
+            <Shimmer variant="text" width={200} />
+            <Shimmer variant="text" width={140} />
+          </SkeletonGroup>
+        ),
+      },
+    ],
+  },
+});

package/starter-kit/components/Shimmer/Shimmer.tsx

@@ -0,0 +1,158 @@
+import React, { createContext, useContext, useEffect, useMemo, type ReactNode } from 'react';
+import { View, Animated, Easing, type StyleProp, type ViewStyle } from 'react-native';
+import { DS_RADIUS, DS_SPACING, DS_MOTION_LOOP_DURATION } from '../../tokens';
+import type { ShimmerProps, ShimmerVariant } from './Shimmer.types';
+
+// True for any Shimmer rendered inside a <SkeletonGroup>. When set, individual blocks drop their own
+// "Loading" announcement — the group announces once for the whole skeleton instead (see below).
+const SkeletonGroupContext = createContext(false);
+
+export const SHIMMER_TEXT_HEIGHT = DS_SPACING[800];
+
+// Plain Shimmer blocks pulse between these two values. Translucent black (not an opaque grey) so the
+// shimmer reads correctly as a wash over whatever surface it's placed on — light, dark, or coloured —
+// the same convention DS uses for its other "works on any surface" overlays. Interpolating the colour
+// itself (not a separate `opacity` style) keeps each independent block visually equivalent to a plain
+// alpha wash.
+const PULSE_LOW  = 'rgba(0, 0, 0, 0.02)';
+const PULSE_HIGH = 'rgba(0, 0, 0, 0.05)';
+
+// One pulse cycle, shared by every Shimmer instance.
+const PULSE_CYCLE_MS = DS_MOTION_LOOP_DURATION.pulse;
+
+// A single module-level clock every Shimmer/Breathing instance reads from, instead of each starting
+// its own timer at mount. Two independent per-instance timers would drift out of phase depending on
+// the exact moment each mounted — sharing one clock means any shimmers visible together always pulse
+// in lockstep. `useNativeDriver:false` is required because we interpolate `backgroundColor` (colour
+// interpolation is JS-driven).
+const sharedProgress = new Animated.Value(0);
+let sharedProgressStarted = false;
+function ensureSharedProgressStarted(): void {
+  if (sharedProgressStarted) return;
+  sharedProgressStarted = true;
+  Animated.loop(
+    Animated.timing(sharedProgress, {
+      toValue: 1,
+      duration: PULSE_CYCLE_MS,
+      easing: Easing.linear,
+      useNativeDriver: false,
+    }),
+  ).start();
+}
+
+// ─── Shared animated primitive ────────────────────────────────────────────────
+// A solid block that breathes between `low` and `high` on the shared progress value. Exported so any
+// composite skeleton can reuse the same pulse (and stay in lockstep with plain Shimmers).
+export function Breathing({
+  phase = 0,
+  low = PULSE_LOW,
+  high = PULSE_HIGH,
+  style,
+  accessibilityRole,
+  accessibilityLabel,
+}: {
+  phase?: number;
+  /** Override the pulse's low/high colours. Defaults to the shared translucent pulse. */
+  low?: string;
+  high?: string;
+  style?: StyleProp<ViewStyle>;
+  accessibilityRole?: 'progressbar';
+  accessibilityLabel?: string;
+}) {
+  useEffect(() => {
+    ensureSharedProgressStarted();
+  }, []);
+
+  // (progress + phase) % 1, then a triangle wave: high at 0, low at 0.5, high at 1 — equivalent to the
+  // cosine breathe, driven off the one shared linear clock so all instances stay phase-locked.
+  const backgroundColor = useMemo(
+    () =>
+      Animated.modulo(Animated.add(sharedProgress, phase), 1).interpolate({
+        inputRange: [0, 0.5, 1],
+        outputRange: [high, low, high],
+      }),
+    [phase, low, high],
+  );
+
+  return (
+    <Animated.View
+      style={[style, { backgroundColor }]}
+      accessibilityRole={accessibilityRole}
+      accessibilityLabel={accessibilityLabel}
+    />
+  );
+}
+
+function dimensionsForVariant(
+  variant: ShimmerVariant,
+  width: ShimmerProps['width'],
+  height: ShimmerProps['height'],
+  size: number,
+): ViewStyle {
+  switch (variant) {
+    case 'circle':
+      return { width: size, height: size, borderRadius: DS_RADIUS.round };
+    case 'container':
+      return { width: width ?? '100%', height: height ?? 80, borderRadius: DS_RADIUS.medium };
+    case 'text':
+    default:
+      return { width: width ?? '100%', height: height ?? SHIMMER_TEXT_HEIGHT, borderRadius: DS_RADIUS.small };
+  }
+}
+
+// ─── Shimmer ──────────────────────────────────────────────────────────────────
+/**
+ * A single loading placeholder — see `ShimmerProps.variant` for what each shape stands in for.
+ * A real composite skeleton (e.g. a list row: avatar + a two-line label) is built by stacking
+ * multiple Shimmers of the right variant/count/dimensions, not by inventing one shape to cover
+ * everything — see the "Circle + text" example in the catalog for exactly this composition.
+ */
+export function Shimmer({ variant = 'text', width, height, size = 40, style }: ShimmerProps) {
+  // Inside a <SkeletonGroup>, the group owns the single "Loading" announcement — each block stays
+  // silent so a composite skeleton (avatar + two text lines = 3 blocks) doesn't make a screen
+  // reader read "Loading, Loading, Loading". A standalone Shimmer still announces on its own.
+  const insideGroup = useContext(SkeletonGroupContext);
+  return (
+    <Breathing
+      style={[dimensionsForVariant(variant, width, height, size), style]}
+      accessibilityRole={insideGroup ? undefined : 'progressbar'}
+      accessibilityLabel={insideGroup ? undefined : 'Loading'}
+    />
+  );
+}
+
+// ─── SkeletonGroup ──────────────────────────────────────────────────────────────
+/**
+ * Wraps a composite skeleton (several stacked Shimmers standing in for one real element — e.g. a
+ * list row's avatar + two text lines) so assistive tech announces it as ONE "Loading" region
+ * instead of once per block. Provides {@link SkeletonGroupContext} so every descendant Shimmer drops
+ * its own announcement; the group itself carries the single `progressbar`/busy role. Pass your own
+ * layout via `style` (the group is a plain View, so `flexDirection`/`gap` land where you'd expect) —
+ * it adds no layout of its own.
+ */
+export function SkeletonGroup({
+  label = 'Loading',
+  style,
+  children,
+}: {
+  /** Accessible name for the whole loading region. @default 'Loading' */
+  label?: string;
+  /** Layout for the group (flexDirection, gap, …) — it renders a plain View, so styles land where
+   *  you'd expect. */
+  style?: StyleProp<ViewStyle>;
+  /** The Shimmers making up the skeleton. */
+  children: ReactNode;
+}) {
+  return (
+    <SkeletonGroupContext.Provider value>
+      <View
+        style={style}
+        accessibilityRole="progressbar"
+        accessibilityLabel={label}
+        accessibilityState={{ busy: true }}
+      >
+        {children}
+      </View>
+    </SkeletonGroupContext.Provider>
+  );
+}

package/starter-kit/components/Shimmer/Shimmer.types.ts

@@ -0,0 +1,27 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+
+export type ShimmerVariant = 'text' | 'container' | 'circle';
+
+export interface ShimmerProps {
+  /** Which shape this placeholder stands in for:
+   *  - `'text'` (default) — **one line of text**. A real element with 3 lines of text gets 3
+   *    stacked `text` Shimmers, not one tall one — a skeleton should mirror the real line count.
+   *    When stacking 2+ lines, give the last one ~70% of the others' width — real text rarely fills
+   *    every line edge-to-edge, and a shorter final line reads as "this is where the paragraph
+   *    naturally ends," not a loading glitch.
+   *  - `'circle'` — always a circular element (an Avatar, an icon-only Pill/Button, a status dot) —
+   *    never used for anything that isn't actually round in its loaded state.
+   *  - `'container'` — everything else: a Card, a Banner, an image, any non-text/non-circular UI
+   *    element. Its `width`/`height` should match the real element it's replacing (a Card skeleton
+   *    should be Card-shaped, not an arbitrary block), so the skeleton reserves the same layout
+   *    space the loaded content will actually occupy — no jump when it swaps in. */
+  variant?: ShimmerVariant;
+  /** Width (text and container). Defaults to 100%. */
+  width?: number | `${number}%`;
+  /** Height (text and container). Defaults: text 16, container 80 — override to match the real
+   *  element this stands in for. */
+  height?: number;
+  /** Diameter for `circle` variant. Default 40. */
+  size?: number;
+  style?: StyleProp<ViewStyle>;
+}

package/starter-kit/components/Shimmer/SkeletonGroup.catalog.tsx

@@ -0,0 +1,39 @@
+import React from 'react';
+import { View, StyleSheet } from 'react-native';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { Shimmer, SkeletonGroup } from './Shimmer';
+import { DS_SPACING } from '../../tokens';
+
+const styles = StyleSheet.create({
+  shimmerLines: { flex: 1, gap: DS_SPACING[400] },
+  previewRow: { flexDirection: 'row', alignItems: 'center', gap: DS_SPACING[600] },
+});
+
+export default defineCatalogPage({
+  component: 'SkeletonGroup',
+  group: 'Sub-Parts',
+  description: 'An accessibility wrapper for a composite skeleton — several Shimmers standing in for one real element (e.g. a list row: an avatar + a two-line label). It announces the whole thing as one "Loading" region and silences the individual blocks, so a screen reader says "Loading" once instead of once per Shimmer. Adds no layout of its own — pass your own flexDirection/gap via style.',
+  whenToUse: 'Wrap 2+ Shimmers that together stand in for one element. A single lone Shimmer already announces on its own and needs no wrapper.',
+  a11y: 'Carries accessibilityRole="progressbar" + accessibilityLabel (default "Loading") + accessibilityState={{ busy: true }} for the whole region; provides a context that makes every descendant Shimmer drop its own announcement. Net effect: one "Loading" announcement per skeleton, not one per block.',
+  // No visual variants/states — it's a transparent a11y wrapper. The one example shows the
+  // composite it wraps; Props + Accessibility document its contract.
+  hide: { states: true },
+  variants: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'composite',
+        name: 'Wrapping a composite skeleton',
+        node: (
+          <SkeletonGroup style={styles.previewRow}>
+            <Shimmer variant="circle" size={40} />
+            <View style={styles.shimmerLines}>
+              <Shimmer variant="text" width={160} />
+              <Shimmer variant="text" width={112} />
+            </View>
+          </SkeletonGroup>
+        ),
+      },
+    ],
+  },
+});

package/starter-kit/components/Shimmer/index.ts

@@ -0,0 +1,2 @@
+export { Shimmer, SkeletonGroup, Breathing, SHIMMER_TEXT_HEIGHT } from './Shimmer';
+export type { ShimmerProps, ShimmerVariant } from './Shimmer.types';

package/starter-kit/components/Surface/Surface.catalog.tsx

@@ -0,0 +1,44 @@
+import React from 'react';
+import { Text, StyleSheet } from 'react-native';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { Surface } from './Surface';
+import { DS_SEMANTIC, DS_SPACING, DS_TYPOGRAPHY } from '../../tokens';
+
+const styles = StyleSheet.create({
+  surfaceDemo: { height: 96, justifyContent: 'center', alignItems: 'center', padding: DS_SPACING[800] },
+  surfaceText: { ...DS_TYPOGRAPHY.bodyMd, color: DS_SEMANTIC.text.regular },
+});
+
+export default defineCatalogPage({
+  component: 'Surface',
+  group: 'Surfaces',
+  description:
+    "Declares \"this subtree's background is tone\" — renders a plain View filled with the matching token (surface.white or surface.main) and provides that tone to descendants via context, so a tone-aware component inside (e.g. FieldContainer/InputField) can automatically pick a fill that contrasts with it instead of assuming white.",
+  whenToUse:
+    "Wrap a screen (or any region) wherever its background isn't the default white — a page with a muted/grey background, for instance — so anything inside that needs to contrast with its background picks the right fill automatically.",
+  variants: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'white',
+        name: 'White',
+        props: { tone: 'white' },
+        node: (
+          <Surface tone="white" style={styles.surfaceDemo}>
+            <Text style={styles.surfaceText}>surface.white</Text>
+          </Surface>
+        ),
+      },
+      {
+        key: 'muted',
+        name: 'Muted',
+        props: { tone: 'muted' },
+        node: (
+          <Surface tone="muted" style={styles.surfaceDemo}>
+            <Text style={styles.surfaceText}>surface.main</Text>
+          </Surface>
+        ),
+      },
+    ],
+  },
+});

package/starter-kit/components/Surface/Surface.tsx

@@ -0,0 +1,45 @@
+import React, { createContext, useContext, type ReactNode } from 'react';
+import { View, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { DS_SEMANTIC } from '../../tokens';
+
+export type SurfaceTone = 'white' | 'muted';
+
+// Defaults to 'white' — a screen with no explicit <Surface> ancestor is assumed to sit on a white
+// background, the common case (matches e.g. Card's own default fill).
+const SurfaceToneContext = createContext<SurfaceTone>('white');
+
+/** What background tone the nearest ancestor `<Surface>` declared (or 'white' if there isn't one).
+ *  Components that need to contrast with whatever's actually behind them — FieldContainer/
+ *  InputField today — read this instead of assuming one fixed background. */
+export function useSurfaceTone(): SurfaceTone {
+  return useContext(SurfaceToneContext);
+}
+
+export interface SurfaceProps {
+  /** Which background this surface renders. Descendants read this via `useSurfaceTone()` to
+   *  automatically pick a fill that contrasts with it (e.g. a field goes white on a muted page,
+   *  recessed on a white one) instead of needing to be told individually. */
+  tone: SurfaceTone;
+  style?: StyleProp<ViewStyle>;
+  children?: ReactNode;
+}
+
+/**
+ * Declares "this subtree's background is `tone`" — renders a plain View filled with the matching
+ * token (`surface.white` or `surface.main`) and provides that tone to descendants via context.
+ * Wrap a screen (or any region) in this wherever its background isn't the default white — a page
+ * with a muted/grey background, for instance — so anything inside that needs to contrast with its
+ * background picks the right fill automatically rather than assuming white.
+ */
+export function Surface({ tone, style, children }: SurfaceProps) {
+  return (
+    <SurfaceToneContext.Provider value={tone}>
+      <View style={[tone === 'white' ? styles.white : styles.muted, style]}>{children}</View>
+    </SurfaceToneContext.Provider>
+  );
+}
+
+const styles = StyleSheet.create({
+  white: { backgroundColor: DS_SEMANTIC.surface.white },
+  muted: { backgroundColor: DS_SEMANTIC.surface.main },
+});

package/starter-kit/components/Surface/index.ts

@@ -0,0 +1,2 @@
+export { Surface, useSurfaceTone } from './Surface';
+export type { SurfaceProps, SurfaceTone } from './Surface';