@krapwoo/ds-viewer 0.1.0 → 0.2.0

package/native/catalog/CatalogSidebar.tsx

@@ -1,6 +1,8 @@
 import { useState } from 'react';
-import { View, Text, ScrollView, Pressable, StyleSheet } from 'react-native';
-import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_RADIUS, CATALOG_TYPE } from './tokens';
+import { View, Text, ScrollView, Pressable, StyleSheet, Image } from 'react-native';
+import type { ImageSourcePropType, LayoutChangeEvent, NativeSyntheticEvent, ImageLoadEventData } from 'react-native';
+import { CATALOG_COLOR, CATALOG_LAYOUT, CATALOG_RADIUS, CATALOG_SPACE, CATALOG_TYPE } from './tokens';
+import { logoLayout } from './logoLayout';
 import { filterGroups, hashForId } from './catalogNavigation';
 import type { NavGroup } from './types';
 import { CatalogSearchInput } from './CatalogSearchInput';
@@ -48,25 +50,108 @@ function NavItem<TId extends string>({ id, active, onPress }: { id: TId; active:
  */
 export function CatalogSidebar<TId extends string>({
   logo,
+  logoImageSource,
   caption,
   groups,
   active,
   onPress,
 }: {
   logo: string;
+  /** Optional logo image, validated and bundled by `cli/workspace.ts` from the project's `logo`
+   *  config field. Visual spec: docs/design/2026-10-08-ds-viewer-sidebar-logo-approved.html
+   *  ("C · Adaptive", approved 2026-10-08) — a mark (aspect ratio ≤ 2) sits beside the name; a
+   *  wordmark (> 2) replaces the name text, carrying it as its own accessible label instead. */
+  logoImageSource?: ImageSourcePropType;
   caption: string;
   groups: NavGroup<TId>[];
   active: TId | undefined;
   onPress: (id: TId) => void;
 }) {
   const [query, setQuery] = useState('');
+  // A bundled local image (the only kind `cli/workspace.ts` ever produces — see its doc comment
+  // above) already carries its own `width`/`height` on the required module object, both on native
+  // and on react-native-web (confirmed by reading `AssetRegistry`/Metro's asset plugin output) — no
+  // need to wait for a load event for the common case. `onLoad` below is kept only as a fallback for
+  // a source with no static dimensions (e.g. a bare `{ uri }`); the mock prober stops rendering as
+  // soon as either resolves an aspect.
+  const staticSource = typeof logoImageSource === 'object' && logoImageSource !== null && !Array.isArray(logoImageSource)
+    ? (logoImageSource as { width?: number; height?: number })
+    : undefined;
+  const staticAspect = staticSource?.width && staticSource?.height ? staticSource.width / staticSource.height : undefined;
+  const [loadedAspect, setLoadedAspect] = useState<number | undefined>(undefined);
+  const [logoFailed, setLogoFailed] = useState(false);
+  const [nameWrapped, setNameWrapped] = useState(false);
   const filtered = filterGroups(groups, query);
 
+  const logoAspect = staticAspect ?? loadedAspect;
+  const attemptingLogo = Boolean(logoImageSource) && !logoFailed;
+  const header = attemptingLogo ? logoLayout(logoAspect) : 'text';
+
+  // Fallback only (see the comment above `staticSource`) — and native-only in practice: on web,
+  // `ImageLoader.load`'s `onLoad` fires after `HTMLImageElement.decode()` resolves, by which point
+  // Chrome has already nulled the underlying DOM event's `target`, so `native.source` below reads
+  // `undefined` on react-native-web (confirmed empirically — `event.target` reads non-null only
+  // when read synchronously inside `onload`, before any `await`) and this handler never sets
+  // `loadedAspect` there. Native's real `Image` reports `source.{width,height}` on its `onLoad`
+  // nativeEvent instead, which this still reads correctly. Kept rather than removed (Minor finding,
+  // Fable's implementation review) because a non-bundled source with no static dimensions (e.g. a
+  // bare `{ uri }`) is still possible on native, even though `cli/workspace.ts` only ever generates
+  // a bundled `require()` today.
+  const onLogoLoad = (e: NativeSyntheticEvent<ImageLoadEventData>) => {
+    const native = e.nativeEvent as unknown as { source?: { width: number; height: number } };
+    const width = native.source?.width;
+    const height = native.source?.height;
+    if (width && height) setLoadedAspect(width / height);
+  };
+  const onLogoError = () => setLogoFailed(true);
+  // Wrap detection for the "mark" row: the name Text's own measured height, not `onTextLayout`
+  // (react-native-web's `Text` doesn't implement it) and not a character-count heuristic (wraps at
+  // a different length per name). More than one line of `CATALOG_TYPE.brand` means it wrapped.
+  const NAME_LINE_HEIGHT = Math.round(CATALOG_TYPE.brand * 1.3);
+  const onNameLayout = (e: LayoutChangeEvent) => {
+    setNameWrapped(e.nativeEvent.layout.height > NAME_LINE_HEIGHT * 1.5);
+  };
+
   return (
     <View role="navigation" aria-label="Catalog pages" style={styles.sidebar}>
       <ScrollView style={styles.scroll} contentContainerStyle={styles.content} showsVerticalScrollIndicator={false}>
-        <Text style={styles.logo}>{logo}</Text>
-        <Text style={styles.subtitle}>{caption}</Text>
+        <View style={styles.header}>
+          {/* Invisible — exists only so a configured logo's `onLoad`/`onError` can fire at all
+              while `header` is still `'text'` (the aspect isn't known yet). Once `logoAspect`
+              resolves (or the image fails), `header` switches and this prober stops rendering. */}
+          {attemptingLogo && logoAspect === undefined && (
+            <Image source={logoImageSource} style={styles.logoProbe} onLoad={onLogoLoad} onError={onLogoError} />
+          )}
+          {header === 'wordmark' && (
+            <>
+              <Image
+                source={logoImageSource}
+                accessibilityRole="image"
+                accessibilityLabel={logo}
+                resizeMode="contain"
+                style={[styles.wordmark, { width: Math.min(CATALOG_LAYOUT.logoWordmarkHeight * (logoAspect ?? 0), 228) }]}
+                onLoad={onLogoLoad}
+                onError={onLogoError}
+              />
+              <Text style={[styles.subtitle, styles.subtitleAfterWordmark]}>{caption}</Text>
+            </>
+          )}
+          {header === 'mark' && (
+            <View style={[styles.inlineHeader, nameWrapped && styles.inlineHeaderTop]}>
+              <Image source={logoImageSource} resizeMode="contain" style={styles.mark} onLoad={onLogoLoad} onError={onLogoError} />
+              <View style={styles.inlineText}>
+                <Text style={styles.logo} onLayout={onNameLayout}>{logo}</Text>
+                <Text style={styles.subtitle}>{caption}</Text>
+              </View>
+            </View>
+          )}
+          {header === 'text' && (
+            <>
+              <Text style={styles.logo}>{logo}</Text>
+              <Text style={styles.subtitle}>{caption}</Text>
+            </>
+          )}
+        </View>
 
         <CatalogSearchInput value={query} onChangeText={setQuery} placeholder="Filter components…" />
 
@@ -97,8 +182,16 @@ const styles = StyleSheet.create({
     paddingHorizontal: CATALOG_LAYOUT.sidebarPaddingX,
     paddingBottom: CATALOG_LAYOUT.sidebarPaddingTop,
   },
+  header: { marginBottom: 20 },
   logo: { fontSize: CATALOG_TYPE.brand, fontWeight: '800', color: CATALOG_COLOR.text },
-  subtitle: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted, marginTop: 2, marginBottom: 20 },
+  subtitle: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted, marginTop: 2 },
+  subtitleAfterWordmark: { marginTop: CATALOG_LAYOUT.logoCaptionGap },
+  mark: { width: CATALOG_LAYOUT.logoMark, height: CATALOG_LAYOUT.logoMark },
+  wordmark: { height: CATALOG_LAYOUT.logoWordmarkHeight, alignSelf: 'flex-start' },
+  logoProbe: { position: 'absolute', width: 1, height: 1, opacity: 0 },
+  inlineHeader: { flexDirection: 'row', alignItems: 'center', gap: CATALOG_SPACE.md },
+  inlineHeaderTop: { alignItems: 'flex-start' },
+  inlineText: { flex: 1, minWidth: 0 },
   empty: { fontSize: CATALOG_TYPE.sm, color: CATALOG_COLOR.textMuted, paddingHorizontal: CATALOG_LAYOUT.navItemPaddingX, paddingVertical: 8 },
   groupLabel: {
     fontSize: CATALOG_TYPE.xs,

package/native/catalog/TokenRow.tsx

@@ -4,8 +4,9 @@ import { CATALOG_TYPE, CATALOG_COLOR, CATALOG_SPACE } from './tokens';
 
 /**
  * Wraps one token's rendered example with a grounded "when to use this" note beneath it — the
- * shared shape behind every token-gallery row (Spacing, Type Scale, …) in both CatalogExample.tsx
- * and CatalogFrameworkExample.tsx. The row's own content (a spacing bar, a type sample, …) is
+ * shared shape behind every token-gallery row (Spacing, Type Scale, …) in both the starter kit's
+ * own token pages and the catalog framework's own `kit-host/viewer-pages/` pages. The row's own
+ * content (a spacing bar, a type sample, …) is
  * freeform `children`; only the value-plus-use-note stacking is standardized here.
  *
  * Draws a 1px `CATALOG_COLOR.border` bottom divider by default (the same divider PropsTable's rows use) so a stack of TokenRows

package/native/catalog/index.ts

@@ -6,11 +6,11 @@
  * token group, each with a `render()` that uses that app's real components) and a `NavGroup[]`
  * (how to bucket those sections in the sidebar), then render a single `<CatalogShell />`.
  *
- * See ./CatalogExample.tsx ("Native App DS Template") for a full worked example, built from this
- * template's own components. See ./CatalogFrameworkExample.tsx ("Design System DS Catalog") for a
- * worked example documenting this framework's own eleven pieces — the same catalog shape, one level
- * up. Neither is re-exported here, on purpose: this barrel stays free of any specific component
- * (including its own) so it can be copied into a different app's repo as-is.
+ * A page is written with `defineCatalogPage()` from this barrel and placed next to its component
+ * (or standalone, for tokens/recipes) — see the starter kit under `starter-kit/` for worked
+ * examples, and `kit-host/viewer-pages/` for pages documenting this framework's own pieces. This
+ * barrel itself stays free of any specific component (including its own) so it can be copied into
+ * a different app's repo as-is.
  */
 export { CatalogShell } from './CatalogShell';
 export { CatalogSidebar } from './CatalogSidebar';
@@ -33,6 +33,7 @@ export type { ComponentManifestEntry, ManifestExample } from './manifest';
 export { defineCatalogPage, buildCatalogSections } from './pageApi';
 export type { CatalogPage, CatalogPageInput, GeneratedComponent, GeneratedPropRecord } from './pageApi';
 export type { PropDef, SectionDef, NavGroup, SpecimenSize, ComparisonDef, ComparisonCell, ComparisonAxisItem, PreviewWidths } from './types';
+export type { ListGroup, ListItem } from './comparison';
 export {
   CATALOG_TYPE,
   CATALOG_TYPE_USE,

package/native/catalog/logoLayout.ts

@@ -0,0 +1,12 @@
+/** Sidebar logo header layout (design `docs/design/2026-10-08-ds-viewer-sidebar-logo-approved.html`,
+ *  "C · Adaptive", approved 2026-10-08): the configured logo image's own aspect ratio decides the
+ *  layout — no config field chooses it. An unknown or invalid aspect falls back to the safer
+ *  text-only header rather than guessing (`CatalogSidebar.tsx` renders this case until the image's
+ *  `onLoad` reports a real size, and whenever there is no logo, it failed to load, or its file is
+ *  missing). */
+export const LOGO_WORDMARK_MIN_ASPECT = 2;
+
+export function logoLayout(aspect: number | undefined): 'text' | 'mark' | 'wordmark' {
+  if (aspect === undefined || !Number.isFinite(aspect) || aspect <= 0) return 'text';
+  return aspect > LOGO_WORDMARK_MIN_ASPECT ? 'wordmark' : 'mark';
+}

package/native/catalog/pageApi.ts

@@ -59,13 +59,22 @@ export interface GeneratedComponent {
 }
 
 function mergePropNotes(component: GeneratedComponent, propNotes: Record<string, string> | undefined): PropDef[] {
-  return component.props.map((prop) => ({
+  const own = component.props.map((prop) => ({
     name: prop.name,
     type: prop.type,
     required: prop.required,
     default: prop.default,
     desc: propNotes?.[prop.name] ? `${prop.desc} ${propNotes[prop.name]}`.trim() : prop.desc,
   }));
+  // Design §3: props inherited from node_modules (e.g. `extends TextInputProps`) are summarised as
+  // one row per source instead of being listed individually.
+  const inherited = component.inheritedFrom.map((source) => ({
+    name: `${source} props`,
+    type: 'inherited',
+    required: true,
+    desc: `Plus all ${source} props, not listed individually.`,
+  }));
+  return [...own, ...inherited];
 }
 
 function orderGroups(groupIds: Map<string, string[]>, groupOrder: string[] | undefined): { label: string; ids: string[] }[] {

package/native/catalog/tokens.ts

@@ -58,6 +58,11 @@ export const CATALOG_LAYOUT = {
   factPaddingY: 9,
   blockLabelGap: 14,
   blockGap: 28,
+  /** Sidebar logo header (design `docs/design/2026-10-08-ds-viewer-sidebar-logo-approved.html`,
+   *  "C · Adaptive", approved 2026-10-08) — see `native/catalog/logoLayout.ts`. */
+  logoMark: 32,
+  logoWordmarkHeight: 28,
+  logoCaptionGap: 6,
 } as const;
 
 /** Max width of the main content column. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krapwoo/ds-viewer",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "license": "MIT",
   "type": "module",
   "description": "A browsable, always-current catalog for an Expo / React Native design system.",
@@ -25,9 +25,8 @@
   },
   "files": [
     "native/catalog",
-    "!native/catalog/CatalogExample.tsx",
-    "!native/catalog/CatalogFrameworkExample.tsx",
     "!native/catalog/**/__tests__",
+    "starter-kit",
     "dist/cli",
     "dist/config",
     "config/index.ts",
@@ -39,22 +38,27 @@
     "react": "*",
     "react-dom": "*",
     "react-native": "*",
-    "react-native-web": "*",
-    "react-native-safe-area-context": "*"
+    "react-native-safe-area-context": "*",
+    "react-native-web": "*"
   },
   "peerDependenciesMeta": {
-    "react-native-safe-area-context": { "optional": true }
+    "react-native-safe-area-context": {
+      "optional": true
+    }
   },
   "dependencies": {
     "typescript": "^6.0.0"
   },
   "devDependencies": {
-    "@types/node": "^22.0.0"
+    "@types/node": "^22.0.0",
+    "puppeteer": "^25.12.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
     "test": "node --experimental-strip-types --test 'cli/**/*.test.ts' 'config/**/*.test.ts' 'native/catalog/__tests__/*.test.ts'",
     "typecheck": "tsc -p tsconfig.json --noEmit",
+    "kit:dev": "npm run build && cd kit-host && node node_modules/@krapwoo/ds-viewer/dist/cli/main.js dev",
+    "check:catalog": "npm run build && node scripts/checkCatalogConsole.mjs kit-host",
     "release": "node scripts/release.mjs"
   }
 }

package/starter-kit/WHEN_TO_USE.md

@@ -0,0 +1,124 @@
+# When to use X vs Y
+
+Disambiguation for components whose names or looks overlap, so a new screen reaches for the right
+one on the first try instead of the closest-looking one. Each entry names the deciding question —
+answer it and the choice falls out. For the full prop/variant/state list per component, read
+`native/catalog/manifest.ts`'s `buildComponentManifest()` output (rendered live at the catalog's
+"Manifest" page) rather than guessing from a component's name alone.
+
+## InputField vs SearchField vs Dropdown
+
+All three render on the same field chrome (`FieldContainer`) and can look identical at rest. The
+deciding question: **what happens when the user taps in?**
+
+- **InputField** — a labeled field with a *floating label* (the label shrinks to a caption once
+  active/filled). Use for a named piece of data with a fixed identity across the interaction — "To",
+  "From", "Arrive by", a person's name. Supports a live `editable` TextInput mode *or* a tappable
+  picker mode (`active` forced from outside, e.g. by a Dropdown/BottomSheet you're driving).
+- **SearchField** — a single-purpose live text input with a permanent leading search icon and no
+  floating label (there's nothing to float to — "search" *is* the label, implied by the icon). Use
+  for free-text filtering/searching, never for a named field with a fixed value.
+- **Dropdown** — not a text input at all. A label-above-value trigger that opens a `BottomSheet`
+  picker with a fixed option list. Use when the answer is one of a small, known set of choices
+  (a direction, a filter value) — never for free text.
+
+Rule of thumb: known short list → **Dropdown**. Free-text filter/search → **SearchField**. Anything
+else the user types or picks, with its own persistent label → **InputField**.
+
+## Button vs Pill
+
+Both are tappable, labeled, and can carry an icon.
+
+- **Button** — an *action*. Something happens when you tap it (save, confirm, navigate, submit).
+  Five weights (`primary`/`secondary`/`tertiary`/`white`/`ghost`) express visual priority among
+  multiple actions on the same screen.
+- **Pill** — a *selection toggle*, not an action. Tapping it flips a `selected`/`not_selected`
+  state that persists (a filter chip, a saved-place shortcut). If tapping it doesn't leave something
+  visibly "on," it should be a Button, not a Pill.
+
+## Toast vs Banner
+
+Both show a status message with an icon and optional action, and both support the same five
+semantic variants.
+
+- **Toast** — *transient* and *self-contained*. Appears on top of the current screen, unrelated to
+  the content beneath it, and is expected to go away on its own or via its own action ("Undo",
+  "Retry"). Owns no layout space — it floats.
+- **Banner** — *persistent* and *in-flow*. Lives inside the screen's own layout (top of a list,
+  inside a card stack) for as long as the condition it describes is true ("Fare increase", "Line
+  suspended"). Never auto-dismisses; the condition or an explicit user action clears it.
+
+If the message is about something happening *right now, because of something the user just did* →
+Toast. If it's a standing fact about the current screen's data → Banner.
+
+## Badge vs Pill vs a Toast/Banner variant
+
+All three can render the same five semantic colors, which makes them easy to reach for
+interchangeably. They aren't interchangeable:
+
+- **Badge** — *read-only status label*. Not tappable. Use inline next to other content ("On time"
+  next to a train row, "Suspended" next to a line name).
+- **Pill** — *tappable selection*. Use it when the same-looking chip needs to respond to a tap and
+  hold a selected state.
+- **Toast/Banner variant** — the color describes a *message about the whole screen or a transient
+  event*, not a single inline data point. If you're tagging one row's status, that's a Badge; if
+  you're telling the user something happened, that's a Toast or Banner.
+
+## Dialog vs BottomSheet
+
+Both are overlay containers with a backdrop.
+
+- **Dialog** — center-screen, fades and scales in. Use for a short, focused decision that
+  interrupts the flow (confirm/cancel, a single form). Named `Dialog` (not `Modal`) specifically to
+  avoid shadowing React Native's own built-in `Modal`.
+- **BottomSheet** — bottom-anchored, slides up, height driven by content up to 90% of the screen.
+  Use for anything longer, browsable, or that benefits from a `TopNav`/`Dock` header-footer
+  structure (an option picker, a detail view, a multi-field form). If the content would need its
+  own internal scrolling, it's a BottomSheet, not a Dialog.
+
+## Card vs ListItem (inside a List)
+
+Both hold a leading element, a title, and secondary text.
+
+- **ListItem** (inside **List**) — a *row in a set of peers* — settings, a menu, search results.
+  Rows are visually light (no individual shadow/border) because the *List* container supplies the
+  shared surface and the dividers between them.
+- **Card** — a *standalone, self-contained unit* with its own shadow and rounded surface. Use when
+  the content doesn't belong to a homogeneous list — a single trip summary, a promo, one dashboard
+  tile sitting alongside other, differently-shaped content.
+
+If you're about to render more than one of the same shape in a vertical stack with dividers between
+them, that's `List`/`ListItem`, not a stack of `Card`s.
+
+## SegmentedToggle vs UnderlineTabs
+
+Same `options`/`value`/`onChange` API, same job (switch between a small set of views) — the
+difference is purely visual weight.
+
+- **SegmentedToggle** — a filled, recessed track with a sliding white thumb. Heavier visual weight;
+  use when the choice is a primary, prominent control on the screen (e.g. Map/List view).
+  - **UnderlineTabs** — left-aligned labels over a hairline rule with a sliding underline. Quieter;
+  use for secondary navigation within a screen that already has a clear primary focus.
+
+## Checkbox vs Switch vs Radio
+
+All three are binary-ish controls; the difference is what the value means and how many can be true
+at once.
+
+- **Checkbox** — an independent on/off fact about *this one item* ("Remember this trip"). Any number
+  of checkboxes on a screen can be checked at once, independently.
+- **Switch** — an on/off *setting* that takes effect immediately (no separate "Save" step). Reach
+  for Switch specifically when toggling it *does something right away*; reach for Checkbox when it's
+  just recording a fact that a future action (a form submit) will act on.
+- **Radio** — one selection from a *mutually exclusive* set (only one can be selected across a group
+  of Radios sharing one consumer-held value). If checking one should un-check another, it's Radio,
+  never Checkbox.
+
+## EmptyState vs Banner
+
+- **EmptyState** — fills the *entire* content area of a screen or section because there is
+  *nothing else to show* (no results, no saved items, first run). Centered, icon-led, optionally one
+  action.
+- **Banner** — sits *alongside* other real content, describing a condition about that content or the
+  screen in general. If the screen would otherwise be blank, use EmptyState; if it has content and
+  you're adding a note above/around it, use Banner.

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

@@ -0,0 +1,23 @@
+import React from 'react';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { AnimatedChevron } from './AnimatedChevron';
+import { DS_SEMANTIC } from '../../tokens';
+
+export default defineCatalogPage({
+  component: 'AnimatedChevron',
+  group: 'Sub-Parts',
+  description: 'A chevron that morphs between down (collapsed) and up (expanded) — flipping vertically in place instead of rotating through a sideways-pointing angle, and instead of swapping icons. The morph Banner\'s own collapsible header uses for its disclosure indicator. Not commonly used on its own; exported for building a custom disclosure/accordion toggle.',
+  a11y: 'Purely decorative — no accessibility role of its own. Wrap it in an accessible parent (the way Banner\'s own header Pressable does) if the toggle needs to be announced.',
+  variants: {
+    items: [
+      { key: 'collapsed', name: 'Collapsed', props: { expanded: false }, node: <AnimatedChevron expanded={false} /> },
+      { key: 'expanded', name: 'Expanded', props: { expanded: true }, node: <AnimatedChevron expanded={true} /> },
+    ],
+  },
+  states: {
+    items: [
+      { key: 'size', name: 'Custom size', node: <AnimatedChevron expanded={false} size={28} /> },
+      { key: 'color', name: 'Custom color', node: <AnimatedChevron expanded={true} color={DS_SEMANTIC.emphasis.info} /> },
+    ],
+  },
+});

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

@@ -0,0 +1,46 @@
+import React, { useEffect, useRef } from 'react';
+import { Animated, Easing } from 'react-native';
+import { Icon } from '../../icons/Icon.native';
+import { DS_MOTION_DURATION, DS_MOTION_EASING } from '../../tokens';
+
+export interface AnimatedChevronProps {
+  /** When true the chevron points up; when false it points down. */
+  expanded: boolean;
+  /** Icon size in px. */
+  size?: number;
+  /** Icon color. */
+  color?: string;
+  /** Morph duration in ms. Defaults to DS_MOTION_DURATION.base (240). */
+  duration?: number;
+}
+
+/**
+ * A chevron that morphs between down (collapsed) and up (expanded) by flipping vertically in place
+ * (`scaleY` 1 → 0 → -1) rather than rotating through a sideways-pointing intermediate angle — a
+ * plain chevron-down glyph mirrored on its own vertical centre (`scaleY: -1`) is exactly chevron-up,
+ * so no second icon or path swap is needed. Uses the core `Animated` API with `useNativeDriver:
+ * true` (transform-only), so it's smooth on the New Architecture in dev and release.
+ */
+export function AnimatedChevron({ expanded, size = 16, color, duration = DS_MOTION_DURATION.base }: AnimatedChevronProps) {
+  const progress = useRef(new Animated.Value(expanded ? 1 : 0)).current;
+
+  useEffect(() => {
+    const anim = Animated.timing(progress, {
+      toValue: expanded ? 1 : 0,
+      duration,
+      // `standard` — an in-place morph (a swap), per DS_MOTION_EASING_USE.
+      easing: Easing.bezier(...DS_MOTION_EASING.standard),
+      useNativeDriver: true,
+    });
+    anim.start();
+    return () => anim.stop();
+  }, [expanded, duration, progress]);
+
+  const scaleY = progress.interpolate({ inputRange: [0, 1], outputRange: [1, -1] });
+
+  return (
+    <Animated.View style={{ transform: [{ scaleY }] }}>
+      <Icon name="chevron-down" size={size} color={color} />
+    </Animated.View>
+  );
+}

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

@@ -0,0 +1,2 @@
+export { AnimatedChevron } from './AnimatedChevron';
+export type { AnimatedChevronProps } from './AnimatedChevron';

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

@@ -0,0 +1,72 @@
+import React from 'react';
+import { defineCatalogPage, type ComparisonDef } from '@krapwoo/ds-viewer';
+import { Avatar } from './Avatar';
+import { DS_SEMANTIC } from '../../tokens';
+
+// Grid comparisons: each cell is a real instance with exactly the props its row and column name.
+// Never build these by multiplying `variants` with `states` — those are pre-rendered nodes and
+// cannot combine.
+function grid(
+  rowLabel: string,
+  columnLabel: string,
+  rows: { key: string; label: string }[],
+  columns: { key: string; label: string }[],
+  cell: (row: string, column: string) => React.ReactNode,
+  size?: ComparisonDef['size'],
+): ComparisonDef {
+  return {
+    rowLabel,
+    columnLabel,
+    rows,
+    columns,
+    cells: rows.flatMap((row) => columns.map((column) => ({ rowKey: row.key, columnKey: column.key, node: cell(row.key, column.key) }))),
+    size,
+  };
+}
+
+// Avatar: content Kind × Size (Avatar's `size` is continuous; 24 / 40 default / 64 is the sweep).
+const AVATAR_COMPARISON = grid(
+  'Kind',
+  'Size',
+  [
+    { key: 'image', label: 'Image' },
+    { key: 'icon', label: 'Icon' },
+    { key: 'initials', label: 'Initials fallback' },
+  ],
+  [
+    { key: 'small', label: 'Small · 24' },
+    { key: 'medium', label: 'Medium · 40 (default)' },
+    { key: 'large', label: 'Large · 64' },
+  ],
+  (row, column) => {
+    const size = column === 'small' ? 24 : column === 'large' ? 64 : 40;
+    if (row === 'image') return <Avatar imageUrl="https://i.pravatar.cc/100" accessibilityLabel="Jordan Lee" size={size} />;
+    if (row === 'icon') return <Avatar iconName="users" accessibilityLabel="Guest" size={size} />;
+    return <Avatar initials="JL" accessibilityLabel="Jordan Lee" size={size} />;
+  },
+  'compact',
+);
+
+export default defineCatalogPage({
+  component: 'Avatar',
+  group: 'Surfaces',
+  specimenSize: 'compact',
+  comparison: AVATAR_COMPARISON,
+  description: 'A circular image, or an initials fallback on a solid fill when there\'s no image (or it fails to load).',
+  a11y: 'Renders with accessibilityRole="image"; pass accessibilityLabel for a meaningful name, otherwise it falls back to the initials text.',
+  variants: {
+    items: [
+      { key: 'image', name: 'Image', node: <Avatar imageUrl="https://i.pravatar.cc/100" accessibilityLabel="Jordan Lee" /> },
+      { key: 'icon', name: 'Icon', node: <Avatar iconName="users" accessibilityLabel="Guest" /> },
+      { key: 'initials', name: 'Initials fallback', node: <Avatar initials="JL" accessibilityLabel="Jordan Lee" /> },
+    ],
+  },
+  states: {
+    items: [
+      { key: 'small', name: 'Small', node: <Avatar initials="JL" size={24} /> },
+      { key: 'medium', name: 'Medium (default)', node: <Avatar initials="JL" size={40} /> },
+      { key: 'large', name: 'Large', node: <Avatar initials="JL" size={64} /> },
+      { key: 'custom-color', name: 'Custom colour', node: <Avatar initials="AC" backgroundColor={DS_SEMANTIC.emphasis.info} /> },
+    ],
+  },
+});

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

@@ -0,0 +1,74 @@
+import React from 'react';
+import { View, Text, Image, StyleSheet, type StyleProp, type ViewStyle } from 'react-native';
+import { DS_SEMANTIC, DS_FONT_WEIGHT } from '../../tokens';
+import { Icon } from '../../icons/Icon.native';
+import type { IconName } from '../../icons';
+
+export interface AvatarProps {
+  /** Remote image URL. Takes precedence over `iconName`/`initials`; falls back to them when omitted
+   *  or the image fails to load. */
+  imageUrl?: string;
+  /** Icon shown instead of initials — e.g. for a generic/anonymous avatar. Takes precedence over
+   *  `initials` when there's no image. */
+  iconName?: IconName;
+  /** Shown when there's no image or icon — the first 1-2 characters are used, uppercased. */
+  initials?: string;
+  /** Diameter in px. @default 40 */
+  size?: number;
+  /** Fill colour behind the icon/initials. Defaults to a neutral muted surface (with dark
+   *  foreground); passing a custom colour switches the icon/initials to light (inverse) text,
+   *  assuming a saturated/dark fill — match that pairing if you override this. */
+  backgroundColor?: string;
+  accessibilityLabel?: string;
+  style?: StyleProp<ViewStyle>;
+}
+
+/** A circular image, icon, or initials fallback on a solid fill — in that order of precedence. */
+export function Avatar({
+  imageUrl,
+  iconName,
+  initials,
+  size = 40,
+  backgroundColor,
+  accessibilityLabel,
+  style,
+}: AvatarProps) {
+  const [imageFailed, setImageFailed] = React.useState(false);
+  const showImage = !!imageUrl && !imageFailed;
+  const showIcon = !showImage && !!iconName;
+  const dimension = { width: size, height: size, borderRadius: size / 2 };
+  // The default fill (surface.muted) is light, so its icon/initials need dark text; a caller-supplied
+  // backgroundColor is assumed saturated/dark (the existing convention — see the "Custom colour"
+  // catalog example), so it keeps the light inverse text that pairing needs.
+  const contentColor = backgroundColor ? DS_SEMANTIC.text.inverse : DS_SEMANTIC.text.regular;
+
+  return (
+    <View
+      style={[styles.circle, dimension, !showImage && { backgroundColor: backgroundColor ?? DS_SEMANTIC.surface.muted }, style]}
+      accessible
+      accessibilityRole="image"
+      accessibilityLabel={accessibilityLabel ?? initials}
+    >
+      {showImage ? (
+        <Image source={{ uri: imageUrl }} style={dimension} onError={() => setImageFailed(true)} />
+      ) : showIcon ? (
+        <Icon name={iconName} size={Math.round(size * 0.5)} color={contentColor} />
+      ) : (
+        <Text style={[styles.initials, { fontSize: Math.round(size * 0.4), color: contentColor }]} numberOfLines={1}>
+          {(initials ?? '?').slice(0, 2).toUpperCase()}
+        </Text>
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  circle: {
+    alignItems: 'center',
+    justifyContent: 'center',
+    overflow: 'hidden',
+  },
+  initials: {
+    fontWeight: DS_FONT_WEIGHT.semibold,
+  },
+});

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

@@ -0,0 +1,2 @@
+export { Avatar } from './Avatar';
+export type { AvatarProps } from './Avatar';