@krapwoo/ds-viewer 0.1.1 → 0.3.0

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,54 @@
+import React from 'react';
+import { defineCatalogPage, grid } from '@krapwoo/ds-viewer';
+import { Avatar } from './Avatar';
+import { DS_SEMANTIC } from '../../tokens';
+
+// Avatar: content Kind × Size (Avatar's `size` is continuous; 24 / 40 default / 64 is the sweep).
+// Neither axis names a real prop — "Kind" is which of 3 optional props is set, not one enum, and
+// `size` has no fixed option set — so both stay unbound. An unbound axis is fully valid; `doctor`
+// only ever reports how many examples are unbound as information, never as an error or a warning.
+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';

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

@@ -0,0 +1,88 @@
+import React from 'react';
+import { defineCatalogPage, grid } from '@krapwoo/ds-viewer';
+import { Badge } from './Badge';
+import type { BadgeVariant } from './Badge.types';
+
+// Badge: Tone × Icon layout. One icon per tone, matching the Variants examples.
+const BADGE_TONES: { key: BadgeVariant; label: string; text: string; icon: React.ComponentProps<typeof Badge>['leadingIcon'] }[] = [
+  { key: 'neutral', label: 'Neutral', text: 'Local', icon: 'pin' },
+  { key: 'info', label: 'Info', text: 'Notice', icon: 'info-circle' },
+  { key: 'positive', label: 'Positive', text: 'On time', icon: 'circle-check' },
+  { key: 'warning', label: 'Warning', text: 'Delayed', icon: 'triangle-alert' },
+  { key: 'negative', label: 'Negative', text: 'Suspended', icon: 'circle-slash' },
+];
+// `rows` is bound to Badge's own `variant` prop (design §4) — written as its own literal array
+// (not `BADGE_TONES.map(...)`) so `doctor`'s static reader can check it without evaluating a
+// function call; `BADGE_TONES` above still drives the real rendering in `cell` below.
+const BADGE_ROWS = {
+  prop: 'variant',
+  items: [
+    { key: 'neutral', label: 'Neutral' },
+    { key: 'info', label: 'Info' },
+    { key: 'positive', label: 'Positive' },
+    { key: 'warning', label: 'Warning' },
+    { key: 'negative', label: 'Negative' },
+  ],
+} as const;
+const BADGE_COMPARISON = grid(
+  'Tone',
+  'Icon',
+  BADGE_ROWS,
+  [
+    { key: 'label-only', label: 'Label only' },
+    { key: 'leading-icon', label: 'Leading icon' },
+    { key: 'trailing-icon', label: 'Trailing icon' },
+    { key: 'icon-only', label: 'Icon-only' },
+  ],
+  (row, column) => {
+    const tone = BADGE_TONES.find((t) => t.key === row)!;
+    if (column === 'icon-only') return <Badge variant={tone.key} leadingIcon={tone.icon} accessibilityLabel={tone.text} />;
+    return (
+      <Badge
+        variant={tone.key}
+        label={tone.text}
+        leadingIcon={column === 'leading-icon' ? tone.icon : undefined}
+        trailingIcon={column === 'trailing-icon' ? tone.icon : undefined}
+      />
+    );
+  },
+  'compact',
+);
+
+export default defineCatalogPage({
+  component: 'Badge',
+  group: 'Surfaces',
+  specimenSize: 'compact',
+  comparison: BADGE_COMPARISON,
+  description: 'A small status chip — five semantic variants, with optional leading/trailing icons or icon-only.',
+  whenToUse: "Read-only and inline, not tappable — for one row's data point. For a tappable chip with a selected state, use Pill; for a message about the whole screen, use Toast or Banner.",
+  a11y: 'A plain View with text; the label carries the meaning, so avoid encoding status by color alone.',
+  variants: {
+    items: [
+      { key: 'neutral', name: 'Neutral', props: { variant: 'neutral' }, node: <Badge variant="neutral" label="Local" /> },
+      { key: 'info', name: 'Info', props: { variant: 'info' }, node: <Badge variant="info" label="Notice" leadingIcon="info-circle" /> },
+      { key: 'positive', name: 'Positive', props: { variant: 'positive' }, node: <Badge variant="positive" label="On time" leadingIcon="circle-check" /> },
+      { key: 'warning', name: 'Warning', props: { variant: 'warning' }, node: <Badge variant="warning" label="Delayed" leadingIcon="triangle-alert" /> },
+      { key: 'negative', name: 'Negative', props: { variant: 'negative' }, node: <Badge variant="negative" label="Suspended" leadingIcon="circle-slash" /> },
+    ],
+  },
+  states: {
+    items: [
+      {
+        key: 'leading-icon',
+        name: 'Leading icon',
+        node: <Badge variant="positive" label="On time" leadingIcon="circle-check" />,
+      },
+      {
+        key: 'trailing-icon',
+        name: 'Trailing icon',
+        node: <Badge variant="positive" label="On time" trailingIcon="circle-check" />,
+      },
+      {
+        key: 'icon-only',
+        name: 'Icon-only',
+        node: <Badge variant="info" leadingIcon="info-circle" accessibilityLabel="Notice" />,
+      },
+    ],
+  },
+});

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

@@ -0,0 +1,56 @@
+import React from 'react';
+import { View, Text, StyleSheet } from 'react-native';
+import { DS_RADIUS, DS_SPACING, DS_TYPOGRAPHY, DS_ICON_SIZE } from '../../tokens';
+import { Icon } from '../../icons/Icon.native';
+import { STATUS_BG, STATUS_FG } from '../statusColors';
+import type { BadgeProps } from './Badge.types';
+
+/**
+ * A small status pill. Composable: label-only, icon-only (a single icon, no label), or a label with
+ * a leading and/or trailing icon. Text + icons sit on the variant background in the variant's own
+ * emphasis colour.
+ */
+export function Badge({ variant = 'neutral', label, leadingIcon, trailingIcon, accessibilityLabel, style }: BadgeProps) {
+  const hasLabel = label != null && label !== '';
+  // Dev-console check (same policy as ButtonGroup's checkConsistency): the docs require an
+  // accessible name for an icon-only badge, but the type can't enforce it — warn instead of
+  // silently rendering an unnameable status glyph.
+  if (__DEV__ && !hasLabel && !accessibilityLabel) {
+    console.warn('[Badge] Icon-only badge (no `label`) needs an `accessibilityLabel` — without one it has no accessible name.');
+  }
+  const fg = STATUS_FG[variant];
+
+  return (
+    <View
+      style={[styles.badge, !hasLabel && styles.iconOnly, { backgroundColor: STATUS_BG[variant] }, style]}
+      accessibilityRole="text"
+      accessibilityLabel={accessibilityLabel}
+    >
+      {leadingIcon ? <Icon name={leadingIcon} size={DS_ICON_SIZE.xs} color={fg} /> : null}
+      {hasLabel ? (
+        <Text style={[styles.label, { color: fg }]} numberOfLines={1}>
+          {label}
+        </Text>
+      ) : null}
+      {trailingIcon ? <Icon name={trailingIcon} size={DS_ICON_SIZE.xs} color={fg} /> : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  badge: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    gap: DS_SPACING[100],
+    paddingVertical: DS_SPACING[200],
+    paddingHorizontal: DS_SPACING[400],
+    borderRadius: DS_RADIUS.round,
+    alignSelf: 'flex-start',
+  },
+  iconOnly: {
+    paddingHorizontal: DS_SPACING[200],
+  },
+  label: {
+    ...DS_TYPOGRAPHY.labelXs,
+  },
+});

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

@@ -0,0 +1,18 @@
+import type { StyleProp, ViewStyle } from 'react-native';
+import type { IconName } from '../../icons';
+
+export type BadgeVariant = 'neutral' | 'info' | 'positive' | 'warning' | 'negative';
+
+export interface BadgeProps {
+  /** Semantic color scheme. */
+  variant?: BadgeVariant;
+  /** Label text. Omit (with a single icon) for an icon-only chip. */
+  label?: string;
+  /** Icon before the label. */
+  leadingIcon?: IconName;
+  /** Icon after the label. */
+  trailingIcon?: IconName;
+  /** Accessible name — required for an icon-only badge (no `label`) so it can be announced. */
+  accessibilityLabel?: string;
+  style?: StyleProp<ViewStyle>;
+}

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

@@ -0,0 +1,2 @@
+export { Badge } from './Badge';
+export type { BadgeProps, BadgeVariant } from './Badge.types';

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

@@ -0,0 +1,87 @@
+import React from 'react';
+import { defineCatalogPage } from '@krapwoo/ds-viewer';
+import { Banner } from './Banner';
+
+export default defineCatalogPage({
+  component: 'Banner',
+  group: 'Surfaces',
+  description: 'An inline callout for status/announcements — five semantic variants, optional collapsible body, inline link, and action button.',
+  whenToUse: "Persistent and in-flow, describing a standing condition about the screen's content. For a transient, self-contained event notification, use Toast instead.",
+  a11y: 'When onPress/action is set the header/button are Pressables; the collapsible header toggles the description with a chevron affordance.',
+  variants: {
+    itemsFill: true,
+    items: [
+      { key: 'neutral', name: 'Neutral', props: { variant: 'neutral' }, node: <Banner variant="neutral" title="Schedule notice" description="Holiday schedule in effect Monday." /> },
+      { key: 'info', name: 'Info', props: { variant: 'info' }, node: <Banner variant="info" title="Weekend service change" description="The 6 runs express in both directions this weekend." /> },
+      { key: 'positive', name: 'Positive', props: { variant: 'positive' }, node: <Banner variant="positive" title="Service restored" description="All lines are running on a normal schedule." /> },
+      { key: 'warning', name: 'Warning', props: { variant: 'warning' }, node: <Banner variant="warning" title="Delays" description="Signal problems near 14 St." /> },
+      { key: 'negative', name: 'Negative', props: { variant: 'negative' }, node: <Banner variant="negative" title="Line suspended" description="No service between 96 St and 137 St until further notice." /> },
+    ],
+  },
+  states: {
+    itemsFill: true,
+    items: [
+      {
+        key: 'tappable',
+        name: 'Tappable',
+        node: (
+          <Banner
+            variant="neutral"
+            title="Alert preferences"
+            description="Tap to manage which alerts you receive."
+            onPress={() => {}}
+          />
+        ),
+      },
+      {
+        key: 'collapsible-expanded',
+        name: 'Collapsible (expanded)',
+        node: (
+          <Banner
+            variant="neutral"
+            title="Trip details"
+            description="Board at the front car for a faster transfer at Union Sq."
+            collapsible
+          />
+        ),
+      },
+      {
+        key: 'collapsible-collapsed',
+        name: 'Collapsible (collapsed)',
+        node: (
+          <Banner
+            variant="neutral"
+            title="Trip details"
+            description="Board at the front car for a faster transfer at Union Sq."
+            collapsible
+            defaultExpanded={false}
+          />
+        ),
+      },
+      {
+        key: 'action',
+        name: 'With action',
+        node: (
+          <Banner
+            variant="info"
+            title="App update available"
+            description="Version 4.2 adds live bus tracking."
+            action={{ label: 'Update', onPress: () => {} }}
+          />
+        ),
+      },
+      {
+        key: 'link',
+        name: 'With link',
+        node: (
+          <Banner
+            variant="neutral"
+            title="Fare increase"
+            description="New fares start March 1."
+            link={{ label: 'Learn more', onPress: () => {} }}
+          />
+        ),
+      },
+    ],
+  },
+});