@krapwoo/ds-viewer 0.4.7 → 0.4.8

package/native/catalog/comparison.ts

@@ -229,6 +229,9 @@ export function remainingStates(states: VariantSlot | undefined, comparison: Com
 
 export interface ListItem {
   key: string;
+  /** Which authored slot this item came from, so a device frame inside it can address it
+   *  (`overlayViewport.ts`). */
+  slot?: 'variants' | 'states';
   label: string;
   node: unknown;
   fill?: boolean;
@@ -265,10 +268,20 @@ export function slotSize<TId extends string>(def: SectionDef<TId>, slot: Variant
   return def.specimenSize ?? (slot.itemsFill ? 'wide' : 'regular');
 }
 
-function slotItems(slot: VariantSlot): ListItem[] {
+/** Full-width (filled) examples are block components (cards, banners, rows): narrower than about a
+ *  third of a laptop's content width they stop reading as themselves, so they wrap at most 3
+ *  across unless the page sets its own `maxColumns`. Small centred examples wrap freely. */
+export const FILLED_SLOT_MAX_COLUMNS = 3;
+
+function slotColumnCap(slot: VariantSlot): { maxColumns?: 1 | 2 | 3 | 4 | 5 } {
+  if (slot.maxColumns !== undefined) return { maxColumns: slot.maxColumns };
+  return slot.itemsFill ? { maxColumns: FILLED_SLOT_MAX_COLUMNS } : {};
+}
+
+function slotItems(slot: VariantSlot, from: 'variants' | 'states'): ListItem[] {
   // Nullish, not `||`: an item's own explicit `fill: false` must override an inherited
   // `itemsFill: true`, which `false || slot.itemsFill` would silently discard.
-  return slot.items.map((item) => ({ key: item.key, label: item.name, node: item.node, fill: item.fill ?? slot.itemsFill, surface: item.surface, align: item.align }));
+  return slot.items.map((item) => ({ key: item.key, slot: from, label: item.name, node: item.node, fill: item.fill ?? slot.itemsFill, surface: item.surface, align: item.align }));
 }
 
 /** Preview widths, each capped at phone width. 'full' is kept for catalog chrome and token pages. */
@@ -289,8 +302,8 @@ function groupStates(variants: VariantSlot, states: VariantSlot): { groups: List
   const groups = variants.items.map((variant) => {
     const own = states.items.filter((s) => s.group === variant.key);
     const items = own.length > 0
-      ? own.map((s) => ({ key: s.key, label: s.name, node: s.node, fill: fill(s, states), surface: s.surface, align: s.align }))
-      : [{ key: variant.key, label: variant.name, node: variant.node, fill: fill(variant, variants), surface: variant.surface, align: variant.align }];
+      ? own.map((s) => ({ key: s.key, slot: 'states' as const, label: s.name, node: s.node, fill: fill(s, states), surface: s.surface, align: s.align }))
+      : [{ key: variant.key, slot: 'variants' as const, label: variant.name, node: variant.node, fill: fill(variant, variants), surface: variant.surface, align: variant.align }];
     return { key: variant.key, label: variant.name, items };
   });
   const rest = states.items.filter((s) => s.group === undefined || !variantKeys.has(s.group));
@@ -337,8 +350,8 @@ export function presentationBlocks<TId extends string>(def: SectionDef<TId>, opt
         kind: 'list',
         title: 'Variants',
         size: slotSize(def, def.variants),
-        items: slotItems(def.variants),
-        ...(def.variants.maxColumns !== undefined ? { maxColumns: def.variants.maxColumns } : {}),
+        items: slotItems(def.variants, 'variants'),
+        ...slotColumnCap(def.variants),
       });
     } else if (def.render) {
       blocks.push({ kind: 'preview', title: 'Preview', widths: previewWidths(def.previewWidths, options.defaultPreviewWidths) });
@@ -351,8 +364,8 @@ export function presentationBlocks<TId extends string>(def: SectionDef<TId>, opt
       kind: 'list',
       title: secondary ? 'Other configurations' : 'States / configurations',
       size: slotSize(def, states),
-      items: slotItems(states),
-      ...(states.maxColumns !== undefined ? { maxColumns: states.maxColumns } : {}),
+      items: slotItems(states, 'states'),
+      ...slotColumnCap(states),
     });
   }
 

package/native/catalog/deviceFrame.ts

@@ -0,0 +1,14 @@
+/**
+ * The device every `PhoneFrame` shows: a real phone's viewport, in points, at the small end of
+ * current phones (iPhone SE, 3rd generation). Examples lay out at exactly these dimensions; a cell
+ * narrower than the device scales the whole viewport down instead of squeezing its layout. Kept
+ * free of runtime imports so `node --test` can check it.
+ */
+export const DEVICE_FRAME = { name: 'iPhone SE', width: 375, height: 667 } as const;
+
+/** How much to scale the device so it fits `availableWidth` (never enlarged). An unmeasured cell
+ *  (0) renders at full size rather than collapsing. */
+export function deviceFrameScale(availableWidth: number): number {
+  if (!(availableWidth > 0)) return 1;
+  return Math.min(1, availableWidth / DEVICE_FRAME.width);
+}

package/native/catalog/overlayViewport.ts

@@ -9,7 +9,7 @@ import type React from 'react';
 import type { SectionDef } from './types.ts';
 
 /** Which block on a page an addressed specimen's `node` lives in — see `findOverlayNode`. */
-export type OverlaySlot = 'variants' | 'states' | 'comparison';
+export type OverlaySlot = 'variants' | 'states' | 'comparison' | 'preview';
 
 /** Identifies exactly one authored specimen: a page id (`SectionDef.id`), which block it lives
  *  in, and that item's own key — `VariantExample.key` for `'variants'`/`'states'`, or this
@@ -23,7 +23,7 @@ export interface OverlayAddress {
   itemKey: string;
 }
 
-const OVERLAY_SLOTS: readonly OverlaySlot[] = ['variants', 'states', 'comparison'];
+const OVERLAY_SLOTS: readonly OverlaySlot[] = ['variants', 'states', 'comparison', 'preview'];
 
 /** `encodeURIComponent` leaves `.` untouched (it's an unreserved character), which would let a
  *  literal `.` inside a segment collide with the `.`-joined encoding below; escape it too so
@@ -117,6 +117,8 @@ export function findOverlayNode(sections: readonly SectionDef<string>[], address
   if (!def) return undefined;
   if (address.slot === 'variants') return def.variants?.items.find((item) => item.key === address.itemKey)?.node;
   if (address.slot === 'states') return def.states?.items.find((item) => item.key === address.itemKey)?.node;
+  // A `render()` page's preview (one per page; `itemKey` is always 'preview').
+  if (address.slot === 'preview') return def.render?.();
   // Matched by recomputing each cell's own canonical key, never by splitting `address.itemKey` —
   // a row/column key may itself contain any delimiter this module could pick.
   return def.comparison?.cells.find((cell) => comparisonCellItemKey(cell.rowKey, cell.columnKey) === address.itemKey)?.node;

package/native/catalog/specimenSurfaceStyle.ts

@@ -88,3 +88,57 @@ export function specimenContentBoundedStyle(align: SpecimenAlign | undefined) {
 /** 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';
+
+/** A `fill` example stretches to its cell, but one with its own fixed width (a 160-point skeleton
+ *  bar) stays that width; it should then sit in the middle of the cell, not against its leading
+ *  edge. True when the measured example is narrower than its wrapper (by more than rounding). */
+export function shouldCenterFilledContent(contentWidth: number, wrapperWidth: number): boolean {
+  if (!(contentWidth > 0) || !(wrapperWidth > 0)) return false;
+  return contentWidth < wrapperWidth - 1;
+}
+
+/** The width of what's actually visible in an example: from the leftmost to the rightmost painted
+ *  box (text, an icon, anything with a fill), ignoring transparent layout wrappers that may span
+ *  the whole cell. */
+export function paintedExtent(boxes: readonly { left: number; right: number; painted: boolean }[]): number {
+  let left = Infinity;
+  let right = -Infinity;
+  for (const box of boxes) {
+    if (!box.painted || box.right <= box.left) continue;
+    left = Math.min(left, box.left);
+    right = Math.max(right, box.right);
+  }
+  return Number.isFinite(left) ? right - left : 0;
+}
+
+/** True when an example is wider than its cell (beyond rounding): its edges are cut off or touch
+ *  the neighbouring cell, so the page should use a wider `specimenSize`. */
+export function overflowsCell(contentWidth: number, cellWidth: number): boolean {
+  return contentWidth > 0 && cellWidth > 0 && contentWidth > cellWidth + 1;
+}
+
+/** One element of an example as measured in the browser. `clips` is true for a container that
+ *  hides or scrolls its overflow (a scrolling row, a device frame). */
+export interface LayoutBox {
+  left: number;
+  right: number;
+  painted: boolean;
+  clips: boolean;
+  children: LayoutBox[];
+}
+
+/** The boxes a reader can actually see: a clipping container counts as its own box, and what it
+ *  hides or scrolls inside it is skipped. */
+export function visibleBoxes(root: LayoutBox): { left: number; right: number; painted: boolean }[] {
+  const out: { left: number; right: number; painted: boolean }[] = [];
+  const walk = (box: LayoutBox, isRoot: boolean) => {
+    if (!isRoot && box.clips) {
+      out.push({ left: box.left, right: box.right, painted: true });
+      return;
+    }
+    if (!isRoot) out.push({ left: box.left, right: box.right, painted: box.painted });
+    for (const child of box.children) walk(child, false);
+  };
+  walk(root, true);
+  return out;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@krapwoo/ds-viewer",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "license": "MIT",
   "type": "module",
   "description": "A browsable, always-current catalog for an Expo / React Native design system.",
@@ -65,9 +65,10 @@
     "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",
-    "check:doctor": "npm run build && cd kit-host && node node_modules/@krapwoo/ds-viewer/dist/cli/main.js doctor --ci",
-    "check:types": "tsc --noEmit -p kit-host",
+    "viewer:dev": "npm run build && cd viewer-host && node node_modules/@krapwoo/ds-viewer/dist/cli/main.js dev",
+    "check:catalog": "npm run build && node scripts/checkCatalogConsole.mjs kit-host && node scripts/checkCatalogConsole.mjs viewer-host",
+    "check:doctor": "npm run build && cd kit-host && node node_modules/@krapwoo/ds-viewer/dist/cli/main.js doctor --ci && cd ../viewer-host && node node_modules/@krapwoo/ds-viewer/dist/cli/main.js doctor --ci",
+    "check:types": "tsc --noEmit -p kit-host && tsc --noEmit -p viewer-host",
     "release": "node scripts/release.mjs"
   }
 }

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

@@ -5,7 +5,7 @@ import { DS_SEMANTIC } from '../../tokens';
 
 export default defineCatalogPage({
   component: 'AnimatedChevron',
-  group: 'Sub-Parts',
+  group: 'Components',
   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: {

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

@@ -31,7 +31,7 @@ const AVATAR_COMPARISON = grid(
 
 export default defineCatalogPage({
   component: 'Avatar',
-  group: 'Surfaces',
+  group: 'Components',
   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).',

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

@@ -51,7 +51,7 @@ const BADGE_COMPARISON = grid(
 
 export default defineCatalogPage({
   component: 'Badge',
-  group: 'Surfaces',
+  group: 'Components',
   specimenSize: 'compact',
   comparison: BADGE_COMPARISON,
   description: 'A small status chip — five semantic variants, with optional leading/trailing icons or icon-only.',

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

@@ -4,7 +4,8 @@ import { Banner } from './Banner';
 
 export default defineCatalogPage({
   component: 'Banner',
-  group: 'Surfaces',
+  group: 'Components',
+  specimenSize: 'regular',
   composedOf: [
     { component: 'AnimatedChevron', role: "The expand/collapse chevron in the header of a collapsible banner.", relationship: 'built-in' },
   ],

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

@@ -69,7 +69,11 @@ function BottomSheetDemo() {
 
 export default defineCatalogPage({
   component: 'BottomSheet',
-  group: 'Navigation',
+  group: 'Components',
+  composedOf: [
+    { component: 'TopNav', role: "The header slot, typically a TopNav with a close or back action.", relationship: 'slot' },
+    { component: 'Dock', role: "The footer slot, typically a Dock with the sheet's primary actions; a Dock footer gets its shadow once the content scrolls.", relationship: 'slot' },
+  ],
   description: 'A sheet that slides up over a dismissible backdrop. Height is driven by its content (not fixed snap points) up to 90% of the available height, then the content area scrolls. Compose header with TopNav and footer with Dock.',
   whenToUse: 'For longer, browsable content, or anything that benefits from a TopNav/Dock header-footer structure. For a short, focused decision that interrupts the flow, use Dialog.',
   a11y: 'The backdrop is a Pressable with accessibilityRole="button" and accessibilityLabel="Dismiss"; header/content/footer carry their own accessibility (e.g. TopNav\'s title as accessibilityRole="header").',

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

@@ -55,7 +55,7 @@ const BUTTON_COMPARISON = grid(
 
 export default defineCatalogPage({
   component: 'Button',
-  group: 'Actions',
+  group: 'Components',
   composedOf: [
     { component: 'Loading', role: "The spinner that replaces the label and icon while loading is true.", relationship: 'built-in' },
   ],

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

@@ -5,7 +5,11 @@ import { Button } from '../Button';
 
 export default defineCatalogPage({
   component: 'ButtonGroup',
-  group: 'Actions',
+  group: 'Components',
+  composedOf: [
+    { component: 'Button', role: "Its children: up to two Buttons side by side, or three stacked.", relationship: 'slot' },
+  ],
+  specimenSize: 'regular',
   description: 'Groups Button elements in one of two layouts: horizontal (up to two, auto-width, trailing-aligned) or vertical (up to three, stretched full width — the same layout Dock\'s own button area uses). Every button in a group should read as one family — the same variant tier (primary/secondary/tertiary/white, never ghost), the same size, and either all icon+label or all label-only, never a mix. Dev-console warns if two or more children disagree.',
   a11y: 'A plain View; each Button child carries its own accessibility role and label.',
   variants: {
@@ -15,6 +19,9 @@ export default defineCatalogPage({
         key: 'horizontal',
         name: 'Horizontal',
         props: { variant: 'horizontal' },
+        // Shown at its own width, centred: stretched, its trailing alignment pushes it to the
+        // cell's edge, which reads as a misplaced example rather than as trailing alignment.
+        fill: false,
         node: (
           <ButtonGroup variant="horizontal">
             <Button label="Cancel" variant="tertiary" onPress={() => {}} />

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

@@ -11,7 +11,8 @@ const styles = StyleSheet.create({
 
 export default defineCatalogPage({
   component: 'Card',
-  group: 'Surfaces',
+  group: 'Components',
+  specimenSize: 'regular',
   description: 'The primary content surface — a rounded white card with a soft resting shadow. Pass children, or onPress to make the whole card a button.',
   whenToUse: 'A standalone, self-contained unit with its own shadow. For a row in a homogeneous stack of peers (with dividers between them), use ListItem inside a List instead.',
   a11y: 'When onPress is set, renders a Pressable with accessibilityRole="button" and a visible focus ring; a plain card is a non-interactive View.',

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

@@ -9,8 +9,8 @@ function CheckboxDemo() {
 
 export default defineCatalogPage({
   component: 'Checkbox',
-  group: 'Controls',
-  specimenSize: 'compact',
+  group: 'Components',
+  specimenSize: 'regular',
   description: 'A square selection control — the box fills with the accent colour and a checkmark when checked.',
   whenToUse: 'An independent on/off fact about this one item — any number can be checked at once. For a setting that takes effect immediately, use Switch; for one-of-many exclusive selection, use Radio.',
   a11y: 'Renders a Pressable with accessibilityRole="checkbox" and accessibilityState.checked; the optional label doubles as its accessibilityLabel.',

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

@@ -33,7 +33,7 @@ function DialogDemo() {
 
 export default defineCatalogPage({
   component: 'Dialog',
-  group: 'Overlays',
+  group: 'Components',
   description: 'A card centred on screen over a dismissible backdrop — fades and scales in, distinct from BottomSheet\'s bottom-anchored slide. Named Dialog (not Modal) to avoid shadowing React Native\'s own built-in Modal.',
   whenToUse: 'A short, focused decision that interrupts the flow (confirm/cancel, a single form). For anything longer, browsable, or that needs its own internal scrolling, use BottomSheet.',
   a11y: 'The backdrop is a Pressable with accessibilityRole="button" and accessibilityLabel="Dismiss"; content you pass as children carries its own accessibility.',

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

@@ -11,7 +11,8 @@ const styles = StyleSheet.create({
 
 export default defineCatalogPage({
   component: 'Divider',
-  group: 'Layout',
+  group: 'Components',
+  specimenSize: 'regular',
   description: 'A 1px hairline separator at the divider token colour.',
   a11y: 'A plain, non-interactive View — purely decorative.',
   // No `variant` prop and no other real configuration exists on Divider — a single hairline is the

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

@@ -5,7 +5,10 @@ import { Dock } from './Dock';
 
 export default defineCatalogPage({
   component: 'Dock',
-  group: 'Navigation',
+  group: 'Components',
+  composedOf: [
+    { component: 'Button', role: "Its children: up to three full-width Buttons, stacked.", relationship: 'slot' },
+  ],
   description: 'Pinned to the bottom of the screen, above the home indicator — holds up to three full-width Buttons stacked vertically, with an optional small caption area above them.',
   a11y: 'A plain View; each Button child carries its own accessibility role and label.',
   // No `variant` prop exists on Dock — its "Variants" column just shows the one default look,

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

@@ -38,7 +38,7 @@ function DropdownDemo() {
 
 export default defineCatalogPage({
   component: 'Dropdown',
-  group: 'Inputs',
+  group: 'Components',
   composedOf: [
     { component: 'FieldContainer', role: "The field frame around the label, value and chevron (the trigger).", relationship: 'built-in' },
     { component: 'BottomSheet', role: "The sheet listing the options while the dropdown is open.", relationship: 'built-in' },

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

@@ -5,7 +5,8 @@ import { DS_SEMANTIC } from '../../tokens';
 
 export default defineCatalogPage({
   component: 'EmptyState',
-  group: 'Layout',
+  group: 'Components',
+  specimenSize: 'regular',
   composedOf: [
     { component: 'Avatar', role: "The icon circle above the title (iconName, default 'users').", relationship: 'built-in' },
     { component: 'ButtonGroup', role: "Stacks the action buttons when action is set.", relationship: 'built-in' },

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

@@ -12,7 +12,11 @@ const styles = StyleSheet.create({
 
 export default defineCatalogPage({
   component: 'FieldContainer',
-  group: 'Sub-Parts',
+  group: 'Components',
+  composedOf: [
+    { component: 'Surface', role: "Reads the surrounding Surface tone: a recessed fill on white, opaque white inside a muted Surface.", relationship: 'related' },
+  ],
+  specimenSize: 'regular',
   description: 'The shared field chrome — white surface, medium radius, a 1px border that darkens on focus and mutes when disabled — behind InputField, TextArea, Dropdown, and SearchField, so all four share one visually-consistent field look instead of each re-implementing it.',
   a11y: 'Renders a plain View by default. Passing onPress (without disabled) makes it a Pressable with accessibilityRole="button" and the given accessibilityLabel — a consumer building a real editable field (InputField\'s editable mode) relies on its own inner TextInput for accessibility instead.',
   variants: {

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

@@ -4,7 +4,7 @@ import { InputClearButton } from './InputClearButton';
 
 export default defineCatalogPage({
   component: 'InputClearButton',
-  group: 'Sub-Parts',
+  group: 'Components',
   description: 'The clear (×) button InputField and SearchField both show once a field is active and holds a value — a filled circle-x icon sized to reach the 44pt touch target via hitSlop, not visual size.',
   a11y: 'A Pressable with accessibilityRole="button" and the given (or default "Clear field") accessibilityLabel; hitSlop of 10 on every side pads its 24×24 visual size out to the 44pt minimum.',
   variants: {

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

@@ -17,9 +17,11 @@ function InputFieldDemo() {
 
 export default defineCatalogPage({
   component: 'InputField',
-  group: 'Inputs',
+  group: 'Components',
+  specimenSize: 'regular',
   composedOf: [
     { component: 'InputClearButton', role: "The clear (\u00d7) button, shown while the field has a value and is focused (or active, when not editable).", relationship: 'built-in' },
+    { component: 'Surface', role: 'Reads the surrounding Surface tone so the field stays visible on a muted Surface.', relationship: 'related' },
   ],
   description: 'A floating-label field. Resting: a centred, body-sized label with no border. Active (focused, or picker with active set) or filled: the label floats to a small top caption, row 2 shows the value/input, and a border fades in while active.',
   whenToUse: 'A named field with a fixed identity ("To", "Arrive by") across the interaction. For free-text search with no floating label, use SearchField; for one of a small known set of choices, use Dropdown.',

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

@@ -8,7 +8,8 @@ import { DS_SEMANTIC } from '../../tokens';
 
 export default defineCatalogPage({
   component: 'List',
-  group: 'Layout',
+  group: 'Components',
+  specimenSize: 'regular',
   composedOf: [
     { component: 'Divider', role: "The hairline between consecutive items (none after the last).", relationship: 'built-in' },
   ],

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

@@ -9,7 +9,13 @@ import { DS_SEMANTIC } from '../../tokens';
 
 export default defineCatalogPage({
   component: 'ListItem',
-  group: 'Layout',
+  group: 'Components',
+  composedOf: [
+    { component: 'Avatar', role: "The leading slot, typically an Avatar (or an icon).", relationship: 'slot' },
+    { component: 'Switch', role: "A trailing-slot option, e.g. a settings toggle.", relationship: 'slot' },
+    { component: 'Button', role: "A trailing-slot option, e.g. an Accept action.", relationship: 'slot' },
+  ],
+  specimenSize: 'regular',
   description: 'A single row: optional leading/trailing slots flanking a title (+ optional subtitle/footer). Stack several inside a List for a settings screen, menu, or search-results list.',
   whenToUse: "A row in a set of visually-light peers sharing a List's own surface and dividers. For a standalone unit with its own shadow, use Card instead.",
   a11y: 'A tappable row (onPress set) renders as a Pressable with accessibilityRole="button" and an accessibilityLabel built from title + subtitle; a plain row is a non-interactive View.',

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

@@ -5,7 +5,8 @@ import { DS_SEMANTIC } from '../../tokens';
 
 export default defineCatalogPage({
   component: 'Loading',
-  group: 'Feedback',
+  group: 'Components',
+  specimenSize: 'regular',
   description: 'An indeterminate loader — the shape fills up, empties out, then fills again, seamlessly. Two variants: circle (used internally by Button and Pill for their own loading states) and linear.',
   a11y: 'Exposed to assistive tech as accessibilityRole="progressbar" with accessibilityLabel="Loading" — no extra wiring needed at the call site.',
   // One example per `variant` enum value — `circle` is the default, so it comes first.

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

@@ -40,7 +40,7 @@ const PILL_COMPARISON = grid(
 
 export default defineCatalogPage({
   component: 'Pill',
-  group: 'Actions',
+  group: 'Components',
   composedOf: [
     { component: 'Loading', role: "The spinner shown instead of the label and icon while loading is true.", relationship: 'built-in' },
   ],

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

@@ -4,7 +4,7 @@ import { PillRow } from './PillRow';
 
 export default defineCatalogPage({
   component: 'PillRow',
-  group: 'Actions',
+  group: 'Components',
   composedOf: [
     { component: 'Pill', role: "Each item in pills, plus the trailing icon-only Edit pill when shown.", relationship: 'built-in' },
   ],

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

@@ -4,7 +4,7 @@ import { ProgressDots } from './ProgressDots';
 
 export default defineCatalogPage({
   component: 'ProgressDots',
-  group: 'Feedback',
+  group: 'Components',
   description: 'A row of dots for a stepped flow; the active dot widens into a pill.',
   a11y: 'Decorative progress indicator; convey the "step X of Y" position in text for screen readers.',
   // No `variant` prop exists on ProgressDots — its "Variants" column just shows the one default

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

@@ -20,8 +20,8 @@ function RadioGroupDemo() {
 
 export default defineCatalogPage({
   component: 'Radio',
-  group: 'Controls',
-  specimenSize: 'compact',
+  group: 'Components',
+  specimenSize: 'regular',
   description: 'A single circular selection control — a filled dot appears in the ring when selected. A group of mutually-exclusive Radios is just multiple instances sharing one selected value in the consumer.',
   whenToUse: 'One selection from a mutually-exclusive set — checking one should un-check another. For an independent on/off fact, use Checkbox; for a setting that takes effect immediately, use Switch.',
   a11y: 'Renders a Pressable with accessibilityRole="radio" and accessibilityState.selected; the optional label doubles as its accessibilityLabel.',

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

@@ -9,7 +9,8 @@ function SearchFieldDemo() {
 
 export default defineCatalogPage({
   component: 'SearchField',
-  group: 'Inputs',
+  group: 'Components',
+  specimenSize: 'regular',
   composedOf: [
     { component: 'FieldContainer', role: "The field frame around the search icon, input and clear button.", relationship: 'built-in' },
     { component: 'InputClearButton', role: "The clear (\u00d7) button, shown while focused with text.", relationship: 'built-in' },

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

@@ -4,7 +4,8 @@ import { SectionHeader } from './SectionHeader';
 
 export default defineCatalogPage({
   component: 'SectionHeader',
-  group: 'Layout',
+  group: 'Components',
+  specimenSize: 'regular',
   composedOf: [
     { component: 'Button', role: "The trailing button, rendered when trailingButtonLabel is set.", relationship: 'built-in' },
   ],

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

@@ -21,9 +21,7 @@ function SegmentedToggleDemo() {
 
 export default defineCatalogPage({
   component: 'SegmentedToggle',
-  group: 'Selection',
-  // Phone width plus a small phone, where long labels truncate.
-  previewWidths: [402, 320],
+  group: 'Components',
   description: 'A row of mutually-exclusive options on a recessed track, with a white thumb that slides to the selected segment. Two or more options.',
   whenToUse: 'A filled, heavier-weight control for a primary, prominent choice on the screen. For quieter secondary navigation, use UnderlineTabs.',
   a11y: 'The row is accessibilityRole="tablist"; each segment is a "tab" with accessibilityState.selected reflecting the current value.',

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

@@ -10,7 +10,8 @@ const styles = StyleSheet.create({
 
 export default defineCatalogPage({
   component: 'Breathing',
-  group: 'Feedback',
+  group: 'Components',
+  specimenSize: 'regular',
   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.',

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

@@ -11,7 +11,8 @@ const styles = StyleSheet.create({
 
 export default defineCatalogPage({
   component: 'Shimmer',
-  group: 'Feedback',
+  group: 'Components',
+  specimenSize: 'regular',
   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.',

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

@@ -11,7 +11,11 @@ const styles = StyleSheet.create({
 
 export default defineCatalogPage({
   component: 'SkeletonGroup',
-  group: 'Sub-Parts',
+  group: 'Components',
+  composedOf: [
+    { component: 'Shimmer', role: 'Its children: the stacked Shimmers that stand in for one element, announced once as a single Loading region.', relationship: 'slot' },
+  ],
+  specimenSize: 'regular',
   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.',

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

@@ -11,7 +11,8 @@ const styles = StyleSheet.create({
 
 export default defineCatalogPage({
   component: 'Surface',
-  group: 'Surfaces',
+  group: 'Components',
+  specimenSize: 'regular',
   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:

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

@@ -14,8 +14,8 @@ function SwitchLabelDemo() {
 
 export default defineCatalogPage({
   component: 'Switch',
-  group: 'Controls',
-  specimenSize: 'compact',
+  group: 'Components',
+  specimenSize: 'regular',
   description: 'A boolean on/off toggle. The thumb slides and the track crossfades colour, sharing SegmentedToggle/UnderlineTabs\' own slide-animation hook for a consistent motion feel.',
   whenToUse: 'A setting that takes effect immediately, no separate save step. For recording a fact a future action (like a form submit) will act on, use Checkbox; for one-of-many exclusive selection, use Radio.',
   a11y: 'Renders a Pressable with accessibilityRole="switch" and accessibilityState.checked — pass accessibilityLabel to say what it controls.',

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

@@ -9,7 +9,8 @@ function TextAreaDemo() {
 
 export default defineCatalogPage({
   component: 'TextArea',
-  group: 'Inputs',
+  group: 'Components',
+  specimenSize: 'regular',
   composedOf: [
     { component: 'FieldContainer', role: "The field frame around the multi-line input.", relationship: 'built-in' },
   ],

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

@@ -28,7 +28,8 @@ function ToastDemo() {
 
 export default defineCatalogPage({
   component: 'Toast',
-  group: 'Feedback',
+  group: 'Components',
+  specimenSize: 'regular',
   description: 'A transient confirmation bar. Without a variant it renders the dark surface with inverse text; a variant shifts to a pastel status color.',
   whenToUse: "Transient and self-contained, floating over the screen, expected to go away on its own or via its own action. For a persistent, in-flow message about a standing condition, use Banner.",
   a11y: 'Rendered with accessibilityRole="alert" so screen readers announce it when it appears.',

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

@@ -31,7 +31,8 @@ function TooltipDemo() {
 
 export default defineCatalogPage({
   component: 'Tooltip',
-  group: 'Overlays',
+  group: 'Components',
+  specimenSize: 'regular',
   description: 'A small floating label anchored above or below its wrapped trigger. Fully controlled — drive `visible` from the trigger\'s own onLongPress/onPressIn, since mobile has no hover.',
   a11y: 'The bubble is a plain, non-interactive View; the trigger you wrap it around carries its own accessibility.',
   variants: {