diff --git a/valdi_modules/navigation_internal/src/NavigationView.tsx b/valdi_modules/navigation_internal/src/NavigationView.tsx
index 9283a18..c10283b 100644
--- a/valdi_modules/navigation_internal/src/NavigationView.tsx
+++ b/valdi_modules/navigation_internal/src/NavigationView.tsx
@@ -59,6 +59,10 @@ interface NavigationPresent extends NavigationInfo {}
 
 type NavigationOperation = (done: () => void) => void;
 
+/**
+ * Web/desktop navigation stack renderer that stacks components as full-screen views and animates push (slide-right) and present (slide-up) transitions.
+ * Manages a serial task queue so navigation animations run sequentially without overlap.
+ */
 export class NavigationView extends StatefulComponent<{}, State, NavigationViewContext> {
   state: State = { stack: [] };
 
diff --git a/valdi_modules/widgets/src/components/animation/AnimationSliding.tsx b/valdi_modules/widgets/src/components/animation/AnimationSliding.tsx
index 975749d..40c4779 100644
--- a/valdi_modules/widgets/src/components/animation/AnimationSliding.tsx
+++ b/valdi_modules/widgets/src/components/animation/AnimationSliding.tsx
@@ -23,6 +23,10 @@ interface AnimationSlidingState {
   progress: number;
 }
 
+/**
+ * Translates its children from a start X/Y offset to an end X/Y offset after an optional delay.
+ * Progress animates from 0 to 1 using the provided animationOptions.
+ */
 export class AnimationSliding extends StatefulComponent<AnimationSlidingViewModel, AnimationSlidingState> {
   state: AnimationSlidingState = {
     progress: 0,
diff --git a/valdi_modules/widgets/src/components/animation/AnimationSquishy.tsx b/valdi_modules/widgets/src/components/animation/AnimationSquishy.tsx
index a531a8a..ca3dd2d 100644
--- a/valdi_modules/widgets/src/components/animation/AnimationSquishy.tsx
+++ b/valdi_modules/widgets/src/components/animation/AnimationSquishy.tsx
@@ -21,6 +21,9 @@ interface AnimationSquishyState {
   progress: number;
 }
 
+/**
+ * Scales its children in ("grow") or out ("shrink") after an optional delay, with optional tilt offsets applied to the translation.
+ */
 export class AnimationSquishy extends StatefulComponent<AnimationSquishyViewModel, AnimationSquishyState> {
   state: AnimationSquishyState = {
     progress: 0,
diff --git a/valdi_modules/widgets/src/components/button/ConfirmationButton.tsx b/valdi_modules/widgets/src/components/button/ConfirmationButton.tsx
index f2ae956..1d58caa 100644
--- a/valdi_modules/widgets/src/components/button/ConfirmationButton.tsx
+++ b/valdi_modules/widgets/src/components/button/ConfirmationButton.tsx
@@ -13,6 +13,9 @@ export interface ConfirmationButtonViewModel {
   accessibilityLabel?: string;
 }
 
+/**
+ * Full-width XL PRIMARY CoreButton pre-configured for confirmation actions; switches to INACTIVE coloring when disabled.
+ */
 export class ConfirmationButton extends Component<ConfirmationButtonViewModel> {
   onRender(): void {
     const viewModel = this.viewModel;
diff --git a/valdi_modules/widgets/src/components/button/FloatingActionButton.tsx b/valdi_modules/widgets/src/components/button/FloatingActionButton.tsx
index 81ae789..7651682 100644
--- a/valdi_modules/widgets/src/components/button/FloatingActionButton.tsx
+++ b/valdi_modules/widgets/src/components/button/FloatingActionButton.tsx
@@ -32,6 +32,10 @@ interface FloatingActionButtonColorTheme {
   icon: SemanticColor;
 }
 
+/**
+ * Absolutely-positioned circular search button anchored to the bottom-right corner.
+ * Slides in or out of view by animating its bottom margin; respects safe area insets on tall devices.
+ */
 export class FloatingActionButton extends StatefulComponent<
   FloatingActionButtonViewModel,
   FloatingActionButtonState,
diff --git a/valdi_modules/widgets/src/components/button/PillButton.tsx b/valdi_modules/widgets/src/components/button/PillButton.tsx
index ce07b5d..a3f944f 100644
--- a/valdi_modules/widgets/src/components/button/PillButton.tsx
+++ b/valdi_modules/widgets/src/components/button/PillButton.tsx
@@ -18,6 +18,9 @@ export interface PillButtonViewModel {
   accessibilityLabel?: string;
 }
 
+/**
+ * SMALL SECONDARY CoreButton with optional icon and selection state; selected items render the foreground in brand primary color.
+ */
 export class PillButton extends Component<PillButtonViewModel> {
   onRender(): void {
     const viewModel = this.viewModel;
diff --git a/valdi_modules/widgets/src/components/card/Card.tsx b/valdi_modules/widgets/src/components/card/Card.tsx
index 04c1de0..8ff1f02 100644
--- a/valdi_modules/widgets/src/components/card/Card.tsx
+++ b/valdi_modules/widgets/src/components/card/Card.tsx
@@ -24,6 +24,9 @@ export enum CardShadow {
   NONE,
 }
 
+/**
+ * Rounded container (10pt radius by default) with an optional drop shadow, configurable background color, and tap handler.
+ */
 export class Card extends Component<CardViewModel> {
   onRender(): void {
     const viewModel = this.viewModel ?? {};
diff --git a/valdi_modules/widgets/src/components/card/CollapsibleCard.tsx b/valdi_modules/widgets/src/components/card/CollapsibleCard.tsx
index 7913cb5..071e900 100644
--- a/valdi_modules/widgets/src/components/card/CollapsibleCard.tsx
+++ b/valdi_modules/widgets/src/components/card/CollapsibleCard.tsx
@@ -76,6 +76,10 @@ const animationOptions: PresetCurveAnimationOptions = {
   duration: 0.2,
 };
 
+/**
+ * Card that initially shows up to `maxNumCollapsedComponents` rows and animates height to reveal or hide additional rows.
+ * Rows can be supplied as render functions or ComponentDef objects; supply `rowHeight` to enable lazy rendering.
+ */
 export class CollapsibleCard<T extends {}> extends StatefulComponent<
   CollapsibleCardViewModel<T>,
   CollapsibleCardState
diff --git a/valdi_modules/widgets/src/components/cell/Cell.tsx b/valdi_modules/widgets/src/components/cell/Cell.tsx
index f91cb5b..6bd3a34 100644
--- a/valdi_modules/widgets/src/components/cell/Cell.tsx
+++ b/valdi_modules/widgets/src/components/cell/Cell.tsx
@@ -54,6 +54,10 @@ export interface CellViewModel {
   accessoryMarginRight?: number;
 }
 
+/**
+ * Standard list row with configurable packing density, left/right accessory slots, and label slots for
+ * title, subtitle, identity, meta, and reason text.
+ */
 export class Cell extends Component<CellViewModel> {
   identityAccessoryRef = new ElementRef();
   rightAccessoryRef = new ElementRef();
diff --git a/valdi_modules/widgets/src/components/cell/subtitle/DelimitedCellSubtitle.tsx b/valdi_modules/widgets/src/components/cell/subtitle/DelimitedCellSubtitle.tsx
index 3fb625e..4936aa0 100644
--- a/valdi_modules/widgets/src/components/cell/subtitle/DelimitedCellSubtitle.tsx
+++ b/valdi_modules/widgets/src/components/cell/subtitle/DelimitedCellSubtitle.tsx
@@ -13,6 +13,9 @@ export interface GenericCellSubtitleViewModel {
   children?: RenderFunction;
 }
 
+/**
+ * Subtitle row that renders an array of render functions separated by a dot delimiter, with an optional left accessory slot.
+ */
 export class DelimitedCellSubtitle extends Component<GenericCellSubtitleViewModel> {
   onRender(): void {
     const viewModel = this.viewModel ?? {};
diff --git a/valdi_modules/widgets/src/components/cell/subtitle/component/SubtitleBadge.tsx b/valdi_modules/widgets/src/components/cell/subtitle/component/SubtitleBadge.tsx
index 3e10954..f8137f1 100644
--- a/valdi_modules/widgets/src/components/cell/subtitle/component/SubtitleBadge.tsx
+++ b/valdi_modules/widgets/src/components/cell/subtitle/component/SubtitleBadge.tsx
@@ -4,6 +4,9 @@ import { TextStyleFont } from 'widgets/src/styles/TextStyleFont';
 import { SemanticColor } from 'widgets/src/styles/semanticColors';
 import { SubtitleText } from './SubtitleText';
 
+/**
+ * Subtitle label rendered in CAPTION_EMPHASIS font and brand-primary color, used to highlight a badge value in a cell subtitle.
+ */
 export class SubtitleBadge extends Component<CommonLabel & ViewAttributes> {
   onRender(): void {
     <SubtitleText {...this.viewModel} font={TextStyleFont.CAPTION_EMPHASIS} color={SemanticColor.Button.PRIMARY} />;
diff --git a/valdi_modules/widgets/src/components/cell/subtitle/component/SubtitleBrand.tsx b/valdi_modules/widgets/src/components/cell/subtitle/component/SubtitleBrand.tsx
index f910f17..46dc149 100644
--- a/valdi_modules/widgets/src/components/cell/subtitle/component/SubtitleBrand.tsx
+++ b/valdi_modules/widgets/src/components/cell/subtitle/component/SubtitleBrand.tsx
@@ -4,6 +4,9 @@ import { TextStyleFont } from 'widgets/src/styles/TextStyleFont';
 import { SemanticColor } from 'widgets/src/styles/semanticColors';
 import { SubtitleText } from './SubtitleText';
 
+/**
+ * Subtitle label rendered in CAPTION font and primary text color, used for brand-name text in a cell subtitle.
+ */
 export class SubtitleBrand extends Component<CommonLabel & ViewAttributes> {
   onRender(): void {
     <SubtitleText {...this.viewModel} font={TextStyleFont.CAPTION} color={SemanticColor.Text.PRIMARY} />;
diff --git a/valdi_modules/widgets/src/components/cell/subtitle/component/SubtitleText.tsx b/valdi_modules/widgets/src/components/cell/subtitle/component/SubtitleText.tsx
index aac9f0a..bec2986 100644
--- a/valdi_modules/widgets/src/components/cell/subtitle/component/SubtitleText.tsx
+++ b/valdi_modules/widgets/src/components/cell/subtitle/component/SubtitleText.tsx
@@ -2,6 +2,9 @@ import { Component } from 'valdi_core/src/Component';
 import { CommonLabel, CommonTextAttributes, ViewAttributes } from 'valdi_tsx/src/NativeTemplateElements';
 import { style } from '../../style';
 
+/**
+ * Base subtitle label that applies the shared cell subtitle style; used directly or via SubtitleBadge/SubtitleBrand.
+ */
 export class SubtitleText extends Component<CommonTextAttributes & ViewAttributes & CommonLabel> {
   onRender(): void {
     <label {...this.viewModel} accessibilityId='result-subtitle' style={style.label.subtitle} />;
diff --git a/valdi_modules/widgets/src/components/grid/GridView.tsx b/valdi_modules/widgets/src/components/grid/GridView.tsx
index 83c5ea0..19a068f 100644
--- a/valdi_modules/widgets/src/components/grid/GridView.tsx
+++ b/valdi_modules/widgets/src/components/grid/GridView.tsx
@@ -37,6 +37,10 @@ interface GridViewContext<T> {
   renderItem(item: T, borderRadius: number, index: number): void;
 }
 
+/**
+ * Renders items in a multi-column grid with lazy layout; defaults to 3 columns with a square aspect ratio per item.
+ * Used internally by GridViewWrapper — prefer GridViewWrapper for most use cases.
+ */
 export class GridView<T> extends StatefulComponent<GridViewModel<T>, GridViewState, GridViewContext<T>> {
   defaultGridRowStyle = new Style<Layout>({
     flexDirection: 'row',
diff --git a/valdi_modules/widgets/src/components/indexview/IndexViewAnchor.tsx b/valdi_modules/widgets/src/components/indexview/IndexViewAnchor.tsx
index 4fb27e0..a7c2449 100644
--- a/valdi_modules/widgets/src/components/indexview/IndexViewAnchor.tsx
+++ b/valdi_modules/widgets/src/components/indexview/IndexViewAnchor.tsx
@@ -7,6 +7,10 @@ export interface IndexViewAnchorViewModel {
   symbol: IndexViewSymbol;
 }
 
+/**
+ * Invisible zero-size layout registered to an IndexViewHandler under a given symbol key.
+ * Place this adjacent to the content section that should be reachable via IndexView.
+ */
 export class IndexViewAnchor extends Component<IndexViewAnchorViewModel> {
   onRender(): void {
     const viewModel = this.viewModel;
diff --git a/valdi_modules/widgets/src/components/indexview/IndexViewHandler.ts b/valdi_modules/widgets/src/components/indexview/IndexViewHandler.ts
index 5c8dddc..1d736c2 100644
--- a/valdi_modules/widgets/src/components/indexview/IndexViewHandler.ts
+++ b/valdi_modules/widgets/src/components/indexview/IndexViewHandler.ts
@@ -1,6 +1,10 @@
 import { ElementRef } from 'valdi_core/src/ElementRef';
 import { IndexViewSymbol } from './IndexViewSymbol';
 
+/**
+ * Maintains a map of IndexViewSymbol keys to ElementRef instances so an IndexView can scroll to named anchors.
+ * Pass to IndexView and IndexViewAnchor to link them together.
+ */
 export class IndexViewHandler {
   private elementRefs: Map<string, ElementRef>;
   constructor() {
diff --git a/valdi_modules/widgets/src/components/inputs/FloatLabeledTextField.tsx b/valdi_modules/widgets/src/components/inputs/FloatLabeledTextField.tsx
index d668c99..5794cf2 100644
--- a/valdi_modules/widgets/src/components/inputs/FloatLabeledTextField.tsx
+++ b/valdi_modules/widgets/src/components/inputs/FloatLabeledTextField.tsx
@@ -45,6 +45,9 @@ interface FloatLabeledTextFieldState {
   text: string;
 }
 
+/**
+ * Text field with a title label that floats above the input when the field is focused or has content, plus an optional inline error message.
+ */
 export class FloatLabeledTextField extends StatefulComponent<
   FloatLabeledTextFieldViewModel,
   FloatLabeledTextFieldState
diff --git a/valdi_modules/widgets/src/components/inputs/PillTextField.tsx b/valdi_modules/widgets/src/components/inputs/PillTextField.tsx
index 983fbef..324a92e 100644
--- a/valdi_modules/widgets/src/components/inputs/PillTextField.tsx
+++ b/valdi_modules/widgets/src/components/inputs/PillTextField.tsx
@@ -79,6 +79,9 @@ interface PillTextFieldState {
   status: string;
 }
 
+/**
+ * Horizontally-scrolling input that combines removable pill chips with an inline text field for token-based entry.
+ */
 export class PillTextField extends StatefulComponent<PillTextFieldViewModel, PillTextFieldState> {
   state: PillTextFieldState = {
     inputValue: '',
diff --git a/valdi_modules/widgets/src/components/inputs/SearchBox.tsx b/valdi_modules/widgets/src/components/inputs/SearchBox.tsx
index 8335200..be48fad 100644
--- a/valdi_modules/widgets/src/components/inputs/SearchBox.tsx
+++ b/valdi_modules/widgets/src/components/inputs/SearchBox.tsx
@@ -59,6 +59,9 @@ interface SearchBoxState {
   status: string;
 }
 
+/**
+ * Rounded search bar with a leading magnifying-glass icon, inline text field, and a trailing clear button that appears when text is present.
+ */
 export class SearchBox extends StatefulComponent<SearchBoxViewModel, SearchBoxState, SearchBoxContext> {
   state: SearchBoxState = {
     inputValue: '',
diff --git a/valdi_modules/widgets/src/components/inputs/TextFieldHandler.ts b/valdi_modules/widgets/src/components/inputs/TextFieldHandler.ts
index 4157e82..b8bc50d 100644
--- a/valdi_modules/widgets/src/components/inputs/TextFieldHandler.ts
+++ b/valdi_modules/widgets/src/components/inputs/TextFieldHandler.ts
@@ -1,6 +1,9 @@
 import { TextFieldInteractive } from 'valdi_tsx/src/NativeTemplateElements';
 import { TextInputHandler } from './TextInputHandler';
 
+/**
+ * TextInputHandler specialized for TextField elements; adds a deprecated setValue helper for imperative value updates.
+ */
 export class TextFieldHandler extends TextInputHandler<TextFieldInteractive> {
   /**
    * @deprecated
diff --git a/valdi_modules/widgets/src/components/inputs/TextInputHandler.ts b/valdi_modules/widgets/src/components/inputs/TextInputHandler.ts
index a3eedbc..c27d27a 100644
--- a/valdi_modules/widgets/src/components/inputs/TextInputHandler.ts
+++ b/valdi_modules/widgets/src/components/inputs/TextInputHandler.ts
@@ -7,6 +7,10 @@ export interface TextInputElement {
   focused?: boolean;
 }
 
+/**
+ * Manages focus state for a text input element; if setFocused(true) is called before the element is created,
+ * it defers focus until the element's onElementCreated callback fires.
+ */
 export class TextInputHandler<T> implements IRenderedElementHolder<T> {
   protected readonly elementRef = new ElementRef<T>();
 
diff --git a/valdi_modules/widgets/src/components/inputs/TextViewHandler.ts b/valdi_modules/widgets/src/components/inputs/TextViewHandler.ts
index 7371857..e9c363d 100644
--- a/valdi_modules/widgets/src/components/inputs/TextViewHandler.ts
+++ b/valdi_modules/widgets/src/components/inputs/TextViewHandler.ts
@@ -1,6 +1,9 @@
 import { TextViewInteractive } from 'valdi_tsx/src/NativeTemplateElements';
 import { TextInputHandler } from './TextInputHandler';
 
+/**
+ * TextInputHandler specialized for TextView elements; adds a deprecated setValue helper for imperative value updates.
+ */
 export class TextViewHandler extends TextInputHandler<TextViewInteractive> {
   /**
    * @deprecated
diff --git a/valdi_modules/widgets/src/components/pickers/IndexPicker.tsx b/valdi_modules/widgets/src/components/pickers/IndexPicker.tsx
index aa202a7..5c09576 100644
--- a/valdi_modules/widgets/src/components/pickers/IndexPicker.tsx
+++ b/valdi_modules/widgets/src/components/pickers/IndexPicker.tsx
@@ -10,6 +10,9 @@ export interface IndexPickerViewModel {
   onChange: (index: number) => void;
 }
 
+/**
+ * Drum-roll style picker that renders a native platform index picker (SCWidgetsIndexPicker on iOS, ValdiIndexPicker on Android).
+ */
 export class IndexPicker extends Component<IndexPickerViewModel, {}> {
   onRender(): void {
     const viewModel = this.viewModel;
diff --git a/valdi_modules/widgets/src/components/pickers/PickerActionSheet.tsx b/valdi_modules/widgets/src/components/pickers/PickerActionSheet.tsx
index 3eb7481..a73c3aa 100644
--- a/valdi_modules/widgets/src/components/pickers/PickerActionSheet.tsx
+++ b/valdi_modules/widgets/src/components/pickers/PickerActionSheet.tsx
@@ -34,6 +34,9 @@ export interface PickerActionSheetViewModel {
  *  android: 'com.snap.valdi.widgets.PickerActionSheet'
  * })
  */
+/**
+ * Bottom sheet containing a title label and a PickerView; fires haptic feedback on creation.
+ */
 export class PickerActionSheet extends StatefulComponent<PickerActionSheetViewModel, {}, {}> {
   override onCreate(): void {
     Device.performHapticFeedback(DeviceHapticFeedbackType.ACTION_SHEET);
diff --git a/valdi_modules/widgets/src/components/refresh/DataSyncingBar.tsx b/valdi_modules/widgets/src/components/refresh/DataSyncingBar.tsx
index 901fc23..9d29373 100644
--- a/valdi_modules/widgets/src/components/refresh/DataSyncingBar.tsx
+++ b/valdi_modules/widgets/src/components/refresh/DataSyncingBar.tsx
@@ -26,6 +26,9 @@ const GRADIENT = linearGradient(
   GradientDirection.LeftToRight,
 );
 
+/**
+ * Animated horizontal loading bar that continuously scrolls a yellow-white-brand gradient to indicate background data syncing.
+ */
 export class DataSyncingBar extends StatefulComponent<{}, DataSyncingBarState> {
   state = {
     width: 0,
diff --git a/valdi_modules/widgets/src/components/rules/HorizontalRule.tsx b/valdi_modules/widgets/src/components/rules/HorizontalRule.tsx
index c134749..19aac99 100644
--- a/valdi_modules/widgets/src/components/rules/HorizontalRule.tsx
+++ b/valdi_modules/widgets/src/components/rules/HorizontalRule.tsx
@@ -2,6 +2,9 @@ import { Component } from 'valdi_core/src/Component';
 import { SemanticColor } from 'widgets/src/styles/semanticColors';
 import { RuleViewModel } from './RuleViewModel';
 
+/**
+ * Full-width horizontal divider line; defaults to 1pt height and the DIVIDER semantic color.
+ */
 export class HorizontalRule extends Component<RuleViewModel> {
   onRender(): void {
     const color = this.viewModel?.color ?? SemanticColor.Layout.DIVIDER;
diff --git a/valdi_modules/widgets/src/components/rules/VerticalRule.tsx b/valdi_modules/widgets/src/components/rules/VerticalRule.tsx
index 101fac4..ac539ed 100644
--- a/valdi_modules/widgets/src/components/rules/VerticalRule.tsx
+++ b/valdi_modules/widgets/src/components/rules/VerticalRule.tsx
@@ -2,6 +2,9 @@ import { Component } from 'valdi_core/src/Component';
 import { SemanticColor } from 'widgets/src/styles/semanticColors';
 import { RuleViewModel } from './RuleViewModel';
 
+/**
+ * Full-height vertical divider line; defaults to 1pt width and the DIVIDER semantic color.
+ */
 export class VerticalRule extends Component<RuleViewModel> {
   onRender(): void {
     const color = this.viewModel?.color ?? SemanticColor.Layout.DIVIDER;
diff --git a/valdi_modules/widgets/src/components/scroll/scrollbar/ScrollBarAnchor.tsx b/valdi_modules/widgets/src/components/scroll/scrollbar/ScrollBarAnchor.tsx
index 70b6666..32b2316 100644
--- a/valdi_modules/widgets/src/components/scroll/scrollbar/ScrollBarAnchor.tsx
+++ b/valdi_modules/widgets/src/components/scroll/scrollbar/ScrollBarAnchor.tsx
@@ -6,6 +6,10 @@ export interface ScrollBarAnchorViewModel {
   readonly label: string;
 }
 
+/**
+ * Invisible zero-size layout registered to a ScrollBarHandler under a given label.
+ * Place this adjacent to content sections to enable scroll-bar position tracking.
+ */
 export class ScrollBarAnchor extends Component<ScrollBarAnchorViewModel> {
   onRender(): void {
     const { handler, label } = this.viewModel;
diff --git a/valdi_modules/widgets/src/components/scroll/snap/ScrollViewSnapAnchor.tsx b/valdi_modules/widgets/src/components/scroll/snap/ScrollViewSnapAnchor.tsx
index ac30f44..5e0ba9b 100644
--- a/valdi_modules/widgets/src/components/scroll/snap/ScrollViewSnapAnchor.tsx
+++ b/valdi_modules/widgets/src/components/scroll/snap/ScrollViewSnapAnchor.tsx
@@ -6,6 +6,10 @@ export interface ScrollViewSnapAnchorViewModel {
   controller: ScrollViewSnapController;
 }
 
+/**
+ * Wraps its slot content in a layout registered to a ScrollViewSnapController so the scroll view can snap to it.
+ * Set enabled=false to temporarily opt out of snapping without removing the anchor.
+ */
 export class ScrollViewSnapAnchor extends Component<ScrollViewSnapAnchorViewModel> {
   onRender(): void {
     const viewModel = this.viewModel;
diff --git a/valdi_modules/widgets/src/components/section/Section.tsx b/valdi_modules/widgets/src/components/section/Section.tsx
index bccbac9..31d2a7c 100644
--- a/valdi_modules/widgets/src/components/section/Section.tsx
+++ b/valdi_modules/widgets/src/components/section/Section.tsx
@@ -4,6 +4,9 @@ import { SectionHeader, SectionHeaderViewModel } from './SectionHeader';
 
 export interface SectionViewModel extends SectionHeaderViewModel, SectionBodyViewModel {}
 
+/**
+ * Convenience wrapper that composes a SectionHeader and a SectionBody with header and content slots.
+ */
 export class Section extends Component<SectionViewModel> {
   onRender(): void {
     const { title, actionButton, actionButtonRenderFn, fullBleed, subtitle, description } = this.viewModel;
diff --git a/valdi_modules/widgets/src/components/section/SectionBadge.tsx b/valdi_modules/widgets/src/components/section/SectionBadge.tsx
index cce2c78..defc0c6 100644
--- a/valdi_modules/widgets/src/components/section/SectionBadge.tsx
+++ b/valdi_modules/widgets/src/components/section/SectionBadge.tsx
@@ -51,6 +51,10 @@ export interface SectionBadgeViewModel {
   theme?: SectionBadgeTheme;
 }
 
+/**
+ * Pill-shaped badge with uppercase text that animates in with a squishy scale effect after a 2.4s delay.
+ * Supports Yellow (default) and Red themes.
+ */
 export class SectionBadge extends Component<SectionBadgeViewModel> {
   onRender(): void {
     const text = this.viewModel?.text.toLocaleUpperCase();
diff --git a/valdi_modules/widgets/src/components/section/SectionBody.tsx b/valdi_modules/widgets/src/components/section/SectionBody.tsx
index 4020ce8..de70150 100644
--- a/valdi_modules/widgets/src/components/section/SectionBody.tsx
+++ b/valdi_modules/widgets/src/components/section/SectionBody.tsx
@@ -10,6 +10,9 @@ export interface SectionBodyViewModel {
   fullBleed?: boolean;
 }
 
+/**
+ * Content wrapper that applies the standard section gutter padding; set fullBleed=true to remove horizontal padding.
+ */
 export class SectionBody extends Component<SectionBodyViewModel> {
   onRender(): void {
     const paddingHorizontal = this.viewModel.fullBleed ? 0 : Subscreen.GUTTER_SIZE;
diff --git a/valdi_modules/widgets/src/components/section/SectionHeader.tsx b/valdi_modules/widgets/src/components/section/SectionHeader.tsx
index 0f04415..4fa9b4a 100644
--- a/valdi_modules/widgets/src/components/section/SectionHeader.tsx
+++ b/valdi_modules/widgets/src/components/section/SectionHeader.tsx
@@ -43,6 +43,10 @@ export interface SectionHeaderViewModel {
   titleMaxLines?: number;
 }
 
+/**
+ * Section header row rendering a bold title, optional subtitle, optional description, and an optional action button.
+ * Supports a slot for additional title-row content and themed text colors.
+ */
 export class SectionHeader extends Component<SectionHeaderViewModel, SectionHeaderContext> {
   private readonly theme = Theme.from(this.context.themeType);
   private readonly style = {
diff --git a/valdi_modules/widgets/src/components/section/SectionSeparator.tsx b/valdi_modules/widgets/src/components/section/SectionSeparator.tsx
index 56cce8f..b722995 100644
--- a/valdi_modules/widgets/src/components/section/SectionSeparator.tsx
+++ b/valdi_modules/widgets/src/components/section/SectionSeparator.tsx
@@ -6,6 +6,9 @@ export interface SectionSeparatorViewModel {
   spacing?: CSSValue;
 }
 
+/**
+ * Vertical spacer used between sections; defaults to MD spacing.
+ */
 export class SectionSeparator extends Component<SectionSeparatorViewModel> {
   onRender(): void {
     const { spacing = Spacing.MD } = this.viewModel; // Standardized value, taken from SearchV2 production value and applied to all features
diff --git a/valdi_modules/widgets/src/components/section/SectionStatusBar.tsx b/valdi_modules/widgets/src/components/section/SectionStatusBar.tsx
index 556b925..e6b5d65 100644
--- a/valdi_modules/widgets/src/components/section/SectionStatusBar.tsx
+++ b/valdi_modules/widgets/src/components/section/SectionStatusBar.tsx
@@ -27,6 +27,9 @@ export enum StatusColor {
   Purple,
 }
 
+/**
+ * Full-width status banner that renders text centered on a tinted background; supports Blue, Red, Green, and Purple color themes.
+ */
 export class SectionStatusBar extends StatefulComponent<SectionStatusBarViewModel, {}> {
   onRender(): void {
     <view
diff --git a/valdi_modules/widgets/src/components/sheet/Sheet.tsx b/valdi_modules/widgets/src/components/sheet/Sheet.tsx
index 3722b51..652f13a 100644
--- a/valdi_modules/widgets/src/components/sheet/Sheet.tsx
+++ b/valdi_modules/widgets/src/components/sheet/Sheet.tsx
@@ -58,6 +58,9 @@ export interface SheetViewModel {
   grabberColor?: string;
 }
 
+/**
+ * Floating bottom sheet with a rounded top and an optional tap-to-dismiss backdrop and grabber handle.
+ */
 export class Sheet extends Component<SheetViewModel> {
   onRender(): void {
     const {
diff --git a/valdi_modules/widgets/src/components/slider/Slider.tsx b/valdi_modules/widgets/src/components/slider/Slider.tsx
index fc065ca..f589d32 100644
--- a/valdi_modules/widgets/src/components/slider/Slider.tsx
+++ b/valdi_modules/widgets/src/components/slider/Slider.tsx
@@ -27,6 +27,9 @@ const BAR_SIZE = 25;
 const DEFAULT_HANDLE_SIZE = 20;
 const DEFAULT_LINE_HEIGHT = 4;
 
+/**
+ * Horizontal drag slider that reports a normalized value between 0 and 1 via onChange; supports customizable track colors and handle size.
+ */
 export class Slider extends StatefulComponent<ViewModel, State> {
   state: State = { value: 0, barWidth: 0 };
 
diff --git a/valdi_modules/widgets/src/components/subscreen/SubscreenSections.tsx b/valdi_modules/widgets/src/components/subscreen/SubscreenSections.tsx
index 7c9bdac..d2e56f2 100644
--- a/valdi_modules/widgets/src/components/subscreen/SubscreenSections.tsx
+++ b/valdi_modules/widgets/src/components/subscreen/SubscreenSections.tsx
@@ -138,6 +138,10 @@ export interface SubscreenSectionViewModel {
   themingEnabled?: boolean;
 }
 
+/**
+ * Pre-wired Subscreen that renders a SectionList with optional IndexView, pull-to-refresh, and scroll-bar support.
+ * Manages ScrollViewHandler and IndexViewHandler internally unless overrides are provided.
+ */
 export class SubscreenSections extends Component<SubscreenSectionViewModel> {
   // To simplify the API, we provide default handlers if the consumer code doesn't need any special behavior
   private indexViewHandler = new IndexViewHandler();
diff --git a/valdi_modules/widgets/src/components/subscreen/SubscreenTabs.tsx b/valdi_modules/widgets/src/components/subscreen/SubscreenTabs.tsx
index ce81509..53283a5 100644
--- a/valdi_modules/widgets/src/components/subscreen/SubscreenTabs.tsx
+++ b/valdi_modules/widgets/src/components/subscreen/SubscreenTabs.tsx
@@ -107,6 +107,10 @@ interface SubscreenTabsState {
   currentTabIndex: number;
 }
 
+/**
+ * Pre-wired Subscreen that renders a TabsHeader and TabsContent with optional pull-to-refresh and scroll-bar support.
+ * Manages TabsCoordinator and ScrollViewHandler internally unless overrides are provided.
+ */
 export class SubscreenTabs extends StatefulComponent<SubscreenTabsViewModel, SubscreenTabsState> {
   state: SubscreenTabsState = {
     currentTabIndex: this.viewModel.tabsItemsInitialIndex || 0,
diff --git a/valdi_modules/widgets/src/components/tabs/TabsContent.tsx b/valdi_modules/widgets/src/components/tabs/TabsContent.tsx
index 70cf9b9..df60914 100644
--- a/valdi_modules/widgets/src/components/tabs/TabsContent.tsx
+++ b/valdi_modules/widgets/src/components/tabs/TabsContent.tsx
@@ -78,6 +78,10 @@ interface TabsContentState {
   verticalScrollViewHeight?: number;
 }
 
+/**
+ * Horizontally-paged content area that renders each tab's content and syncs the active page with a TabsCoordinator.
+ * Supports Greedy, LazyNoUnload, LazyWithUnload, AggressivelyLazy loading strategies.
+ */
 export class TabsContent extends StatefulComponent<TabsContentViewModel, TabsContentState> {
   state: TabsContentState = {};
 
diff --git a/valdi_modules/widgets/src/components/tabs/TabsCoordinator.ts b/valdi_modules/widgets/src/components/tabs/TabsCoordinator.ts
index 56d68ff..34625c4 100644
--- a/valdi_modules/widgets/src/components/tabs/TabsCoordinator.ts
+++ b/valdi_modules/widgets/src/components/tabs/TabsCoordinator.ts
@@ -7,6 +7,10 @@ export interface TabsCoordinatorItems {
   initialIndex?: number;
 }
 
+/**
+ * Observable coordinator that synchronizes TabsHeader and TabsContent.
+ * Pass the same instance to both components; subscribe to index/onNav/onTap for programmatic control.
+ */
 export class TabsCoordinator {
   // Triggered when the exact index is changing
   readonly index = new BehaviorSubject<number | undefined>(undefined);
diff --git a/valdi_modules/widgets/src/components/tabs/TabsHeader.tsx b/valdi_modules/widgets/src/components/tabs/TabsHeader.tsx
index 170c158..6f37194 100644
--- a/valdi_modules/widgets/src/components/tabs/TabsHeader.tsx
+++ b/valdi_modules/widgets/src/components/tabs/TabsHeader.tsx
@@ -102,6 +102,10 @@ interface TabsHeaderState {
   currentIndex?: number;
 }
 
+/**
+ * Horizontally-scrolling tab bar that renders each tab's header and tracks the focused tab with an animated underline indicator.
+ * Syncs selection state with a TabsCoordinator; supports fixed-column widths and configurable underline and ruler styles.
+ */
 export class TabsHeader extends StatefulComponent<TabsHeaderViewModel, TabsHeaderState, TabsHeaderViewContext> {
   private static sides = Spacing.XS;
 
diff --git a/valdi_modules/widgets/src/components/tabs/TabsItem.tsx b/valdi_modules/widgets/src/components/tabs/TabsItem.tsx
index 9a51f9d..a23deff 100644
--- a/valdi_modules/widgets/src/components/tabs/TabsItem.tsx
+++ b/valdi_modules/widgets/src/components/tabs/TabsItem.tsx
@@ -1,5 +1,6 @@
 import { ScrollBarHandler } from 'widgets/src/components/scroll/scrollbar/ScrollBarHandler';
 
+/** Data contract for a single tab: supplies render functions for the header label and the tab content. */
 export interface TabsItem {
   key?: string;
   scrollBarHandler?: ScrollBarHandler;
diff --git a/valdi_modules/widgets/src/components/toggle/CoreJumboToggle.tsx b/valdi_modules/widgets/src/components/toggle/CoreJumboToggle.tsx
index d40e89c..1c67eec 100644
--- a/valdi_modules/widgets/src/components/toggle/CoreJumboToggle.tsx
+++ b/valdi_modules/widgets/src/components/toggle/CoreJumboToggle.tsx
@@ -135,6 +135,9 @@ const onStyle = {
   }),
 };
 
+/**
+ * Large on/off toggle (46×88pt) with a spring-animated thumb, haptic feedback, and optional on/off image overlays on the track.
+ */
 export class CoreJumboToggle extends StatefulComponent<CoreJumboToggleViewModel, State> {
   state = {
     pressed: false,
diff --git a/valdi_modules/widgets/src/components/toggle/CoreToggle.tsx b/valdi_modules/widgets/src/components/toggle/CoreToggle.tsx
index cb440ff..ff029cf 100644
--- a/valdi_modules/widgets/src/components/toggle/CoreToggle.tsx
+++ b/valdi_modules/widgets/src/components/toggle/CoreToggle.tsx
@@ -103,6 +103,9 @@ const onStyle = {
   }),
 };
 
+/**
+ * Small on/off toggle (24×38pt) with a spring-animated thumb and haptic feedback on state change; supports custom track and thumb colors.
+ */
 export class CoreToggle extends StatefulComponent<CoreToggleViewModel, State> {
   state = {
     pressed: false,
diff --git a/valdi_modules/widgets/src/components/toggle/RadioToggle.tsx b/valdi_modules/widgets/src/components/toggle/RadioToggle.tsx
index cce3b42..751859d 100644
--- a/valdi_modules/widgets/src/components/toggle/RadioToggle.tsx
+++ b/valdi_modules/widgets/src/components/toggle/RadioToggle.tsx
@@ -22,6 +22,9 @@ interface RadioToggleState {
   on: boolean;
 }
 
+/**
+ * Radio-button style circle toggle (24pt): grey-filled when off, brand-secondary filled with a white inner circle when on.
+ */
 export class RadioToggle extends StatefulComponent<RadioToggleViewModel, RadioToggleState> {
   state: RadioToggleState = {
     on: false,
diff --git a/valdi_modules/widgets/src/components/toggle/SelectorToggle.tsx b/valdi_modules/widgets/src/components/toggle/SelectorToggle.tsx
index 87d39a4..eb971c2 100644
--- a/valdi_modules/widgets/src/components/toggle/SelectorToggle.tsx
+++ b/valdi_modules/widgets/src/components/toggle/SelectorToggle.tsx
@@ -28,6 +28,9 @@ interface SelectorToggleState {
   on: boolean;
 }
 
+/**
+ * Checkbox-style circle toggle (24pt): grey border when off, filled brand-secondary with a checkmark icon when on.
+ */
 export class SelectorToggle extends StatefulComponent<SelectorToggleViewModel, SelectorToggleState> {
   state: SelectorToggleState = {
     on: false,
diff --git a/valdi_modules/widgets/src/components/util/DragToDismissController.ts b/valdi_modules/widgets/src/components/util/DragToDismissController.ts
index f7bf5f9..15e5b82 100644
--- a/valdi_modules/widgets/src/components/util/DragToDismissController.ts
+++ b/valdi_modules/widgets/src/components/util/DragToDismissController.ts
@@ -1,6 +1,10 @@
 import { ScrollEvent, ScrollDragEndEvent } from 'valdi_tsx/src/GestureEvents';
 import { ScrollViewListener } from 'widgets/src/components/scroll/ScrollViewListener';
 
+/**
+ * ScrollViewListener that monitors scroll events to decide when a downward drag gesture should dismiss a sheet.
+ * Calls onCouldDismiss when the threshold is crossed and onShouldDismiss when the drag ends with enough distance or velocity.
+ */
 export class DragToDismissController implements ScrollViewListener {
   // The current drag session is eligible to trigger a dismiss on end
   public isEligibleForDismiss = true;
diff --git a/valdi_modules/widgets/src/components/util/FocusableComponentRef.ts b/valdi_modules/widgets/src/components/util/FocusableComponentRef.ts
index 736d785..e86d1b9 100644
--- a/valdi_modules/widgets/src/components/util/FocusableComponentRef.ts
+++ b/valdi_modules/widgets/src/components/util/FocusableComponentRef.ts
@@ -13,6 +13,10 @@ interface FocusableComponentRefOptions {
   delayBeforeFocusingOnIOS?: boolean;
 }
 
+/**
+ * ComponentRef wrapper that tracks focus state and defers setFocused(true) to the next component creation when no component is mounted yet.
+ * On iOS, an optional delayBeforeFocusingOnIOS flag adds a one-tick delay to ensure the text field is ready before focusing.
+ */
 export class FocusableComponentRef<T extends FocusableComponent>
   implements IRenderedComponentHolder<T, IRenderedVirtualNode>
 {
diff --git a/valdi_modules/widgets/src/components/util/MeasureCache.ts b/valdi_modules/widgets/src/components/util/MeasureCache.ts
index 182c36f..6645a18 100644
--- a/valdi_modules/widgets/src/components/util/MeasureCache.ts
+++ b/valdi_modules/widgets/src/components/util/MeasureCache.ts
@@ -6,6 +6,10 @@ export interface MeasuredComponentSize {
   height: number;
 }
 
+/**
+ * Observable cache that stores a MeasuredComponentSize and re-emits it whenever populate() is called.
+ * Used together with MeasureCachePopulator to decouple the measurement pass from the render pass.
+ */
 export class MeasureCache {
   readonly observable$: Observable<MeasuredComponentSize>;
   private subject = new Subject<MeasuredComponentSize>();
diff --git a/valdi_modules/widgets/src/components/util/WithInsets.tsx b/valdi_modules/widgets/src/components/util/WithInsets.tsx
index 4f3af96..0973a8c 100644
--- a/valdi_modules/widgets/src/components/util/WithInsets.tsx
+++ b/valdi_modules/widgets/src/components/util/WithInsets.tsx
@@ -30,6 +30,10 @@ interface WithInsetsState {
   };
 }
 
+/**
+ * Layout that automatically applies the device safe-area insets as padding or margin and re-renders whenever the insets change.
+ * Individual edges can be suppressed with ignoreTop/Bottom/Left/Right; provide resolveFn to transform the raw inset values.
+ */
 export class WithInsets extends StatefulComponent<WithInsetsViewModel, WithInsetsState> {
   state = {
     insets: {