@krapwoo/ds-viewer 0.1.0 → 0.2.0

package/starter-kit/pages/SavedTrips.catalog.tsx

@@ -0,0 +1,247 @@
+import React, { useEffect, useRef, useState } from 'react';
+import { View, Text, ScrollView, StyleSheet } from 'react-native';
+import { defineCatalogPage, PhoneFrame } from '@krapwoo/ds-viewer';
+import { Avatar } from '../components/Avatar';
+import { Badge } from '../components/Badge';
+import { Button } from '../components/Button';
+import { Dock } from '../components/Dock';
+import { Dropdown } from '../components/Dropdown';
+import { EmptyState } from '../components/EmptyState';
+import { List } from '../components/List';
+import { ListItem } from '../components/ListItem';
+import { Loading } from '../components/Loading';
+import { PillRow, type PillRowItem } from '../components/PillRow';
+import { SearchField } from '../components/SearchField';
+import { SectionHeader } from '../components/SectionHeader';
+import { SegmentedToggle } from '../components/SegmentedToggle';
+import { Surface } from '../components/Surface';
+import { Toast } from '../components/Toast';
+import { Tooltip } from '../components/Tooltip';
+import { TopNav } from '../components/TopNav';
+import { UnderlineTabs } from '../components/UnderlineTabs';
+import { Icon } from '../icons/Icon.native';
+import { DS_ICON_SIZE, DS_MOTION_DURATION, DS_SEMANTIC, DS_SPACING, DS_TYPOGRAPHY } from '../tokens';
+
+const styles = StyleSheet.create({
+  // Saved trips recipe — fills PhoneFrame edge-to-edge (like dropdownFrameContent), with a
+  // fixed TopNav header and Dock footer around a scrollable middle, the same fixed-header/
+  // scrollable-body/fixed-footer shape a real screen would use.
+  savedTripsScreen: { flex: 1, alignSelf: 'stretch' },
+  // A fixed cap (not `flex: 1`) — sidesteps a web-only flexbox quirk where a `flex: 1` ScrollView
+  // nested inside PhoneFrame's own fixed height doesn't actually shrink to the space left after
+  // TopNav/Dock, and grows PhoneFrame itself past its intended 480px instead of scrolling.
+  savedTripsScroll: { maxHeight: 320 },
+  savedTripsScrollContent: { padding: DS_SPACING[800], gap: DS_SPACING[600] },
+  // Shared by SavedTrips' small inline rows — the "Updating arrival times…" loading row and each
+  // list row's trailing badge+button cluster (identical layout, one key).
+  savedTripsInlineRow: { flexDirection: 'row', alignItems: 'center', gap: DS_SPACING[300] },
+  savedTripsLoadingText: { ...DS_TYPOGRAPHY.bodyXs, color: DS_SEMANTIC.text.muted },
+  // Floats over the top of the screen — same top/left/right inset Toast's own catalog demo uses —
+  // instead of sitting inline in the flex flow and pushing the Dock down. A column with a small
+  // gap, since back-to-back removals stack one toast per removal (newest on top).
+  savedTripsToastOverlay: { position: 'absolute', top: DS_SPACING[800], left: DS_SPACING[600], right: DS_SPACING[600], zIndex: 20, gap: DS_SPACING[300] },
+  // Map mode's stand-in — a real map isn't in scope for this recipe, just enough to show the
+  // SegmentedToggle actually switches the screen's content, not just its own thumb.
+  savedTripsMapPlaceholder: { alignItems: 'center', justifyContent: 'center', gap: DS_SPACING[400], paddingVertical: DS_SPACING[2400] },
+  savedTripsMapPlaceholderText: { ...DS_TYPOGRAPHY.bodySm, color: DS_SEMANTIC.text.muted },
+});
+
+const SAVED_TRIPS_INITIAL = [
+  { id: 'uptown', title: 'Uptown & The Bronx', subtitle: '4 min · Subway', iconName: 'subway' as const, badgeVariant: 'positive' as const, badgeLabel: 'On time' },
+  { id: 'downtown', title: 'Downtown & Brooklyn', subtitle: '12 min · Train', iconName: 'train' as const, badgeVariant: 'warning' as const, badgeLabel: 'Delayed' },
+  { id: 'airport', title: 'Airport Express', subtitle: '22 min · Train', iconName: 'train' as const, badgeVariant: 'neutral' as const, badgeLabel: 'Scheduled' },
+];
+const SAVED_TRIPS_SORT_OPTIONS = [
+  { value: 'arrival', label: 'Arrival time' },
+  { value: 'distance', label: 'Distance' },
+  { value: 'name', label: 'Name' },
+];
+// How long the "Trip removed" toast stays up before auto-dismissing, same as a real snackbar —
+// matches Toast's own doc comment ("expected to go away on its own or via its own action").
+const SAVED_TRIPS_TOAST_MS = 3000;
+
+function SavedTripsDemo() {
+  const [tab, setTab] = useState('all');
+  const [viewMode, setViewMode] = useState('list');
+  const [query, setQuery] = useState('');
+  const [sortBy, setSortBy] = useState('arrival');
+  const [pills, setPills] = useState<PillRowItem[]>([
+    { id: 'subway', label: 'Subway', variant: 'selected', iconName: 'subway' },
+    { id: 'train', label: 'Train', variant: 'not_selected', iconName: 'train' },
+    { id: 'ferry', label: 'Ferry', variant: 'not_selected', iconName: 'ferry' },
+  ]);
+  const [showFilterTip, setShowFilterTip] = useState(false);
+  const [trips, setTrips] = useState(SAVED_TRIPS_INITIAL);
+  // Toasts only appear right after a real action (removing a trip) and auto-dismiss — they never
+  // sit statically in the initial render, since that's not what Toast is for. Each removal gets its
+  // OWN stacked toast on its own 3s clock (newest on top), so removing a second trip while the
+  // first toast is still up never cuts the first one short — the earlier single-toast version
+  // reused one `visible` boolean, which couldn't restart its timer for a back-to-back removal.
+  // `visible: false` plays Toast's own exit animation; the entry is dropped from the array only
+  // after that animation has had time to run.
+  const [toasts, setToasts] = useState<
+    Array<{ key: number; trip: (typeof SAVED_TRIPS_INITIAL)[number]; visible: boolean }>
+  >([]);
+  const nextToastKey = useRef(0);
+  const toastTimers = useRef<Array<ReturnType<typeof setTimeout>>>([]);
+  // Timers are scheduled per-removal (in event handlers, not an effect), so unmount cleanup is one
+  // sweep here rather than per-timer effect returns.
+  useEffect(() => () => toastTimers.current.forEach(clearTimeout), []);
+
+  const hideToast = (key: number) => {
+    setToasts((prev) => prev.map((t) => (t.key === key ? { ...t, visible: false } : t)));
+    // Drop the entry once Toast's exit animation (it exits at DS_MOTION_DURATION.fast) has played.
+    toastTimers.current.push(
+      setTimeout(() => setToasts((prev) => prev.filter((t) => t.key !== key)), DS_MOTION_DURATION.fast),
+    );
+  };
+  const removeTrip = (id: string) => {
+    const removed = trips.find((t) => t.id === id);
+    if (!removed) return;
+    setTrips((prev) => prev.filter((t) => t.id !== id));
+    const key = nextToastKey.current++;
+    setToasts((prev) => [{ key, trip: removed, visible: true }, ...prev]);
+    toastTimers.current.push(setTimeout(() => hideToast(key), SAVED_TRIPS_TOAST_MS));
+  };
+  const undoRemove = (key: number, trip: (typeof SAVED_TRIPS_INITIAL)[number]) => {
+    setTrips((prev) => [...prev, trip]);
+    hideToast(key);
+  };
+
+  return (
+    <PhoneFrame>
+      <View style={styles.savedTripsScreen}>
+        <TopNav
+          title="Saved trips"
+          trailing={
+            <Tooltip visible={showFilterTip} label="Filter by mode" placement="bottom" align="right">
+              <Button
+                variant="secondary"
+                size="small"
+                showIcon
+                showLabel={false}
+                iconName="menu"
+                accessibilityLabel="Filters"
+                onPress={() => setShowFilterTip((v) => !v)}
+              />
+            </Tooltip>
+          }
+        />
+        <Surface tone="muted">
+          <ScrollView style={styles.savedTripsScroll} contentContainerStyle={styles.savedTripsScrollContent}>
+            <SearchField value={query} onChangeText={setQuery} placeholder="Search stations" />
+            <SegmentedToggle
+              value={viewMode}
+              onChange={setViewMode}
+              options={[
+                { value: 'list', label: 'List', iconName: 'menu' },
+                { value: 'map', label: 'Map', iconName: 'map' },
+              ]}
+            />
+            {viewMode === 'map' ? (
+              <View style={styles.savedTripsMapPlaceholder}>
+                <Icon name="map" size={DS_ICON_SIZE.xl} color={DS_SEMANTIC.text.muted} />
+                <Text style={styles.savedTripsMapPlaceholderText}>Map view</Text>
+              </View>
+            ) : (
+              <>
+                <UnderlineTabs
+                  value={tab}
+                  onChange={setTab}
+                  options={[
+                    { value: 'all', label: 'All' },
+                    { value: 'nearby', label: 'Nearby' },
+                    { value: 'favorites', label: 'Favorites' },
+                  ]}
+                />
+                {tab === 'favorites' ? (
+                  <EmptyState
+                    iconName="waypoints"
+                    title="No favorites yet"
+                    description="Star a trip to see it here."
+                    action={{ label: 'Browse trips', onPress: () => setTab('all') }}
+                    secondaryAction={{ label: 'Not now', onPress: () => {} }}
+                  />
+                ) : (
+                  <>
+                    <PillRow
+                      pills={pills.map((p) => ({ ...p, onPress: () => setPills((prev) => prev.map((x) => ({ ...x, variant: x.id === p.id ? 'selected' : 'not_selected' }))) }))}
+                      showAddPill={false}
+                    />
+                    <View style={styles.savedTripsInlineRow}>
+                      <Loading size={14} />
+                      <Text style={styles.savedTripsLoadingText}>Updating arrival times…</Text>
+                    </View>
+                    {/* Dropdown's own `label` prop, not a hand-rolled Text above it — the component
+                        already owns the labeled-field pattern (PillRow, which has no label prop, is
+                        the case where an external label is legitimately the only option). */}
+                    <Dropdown label="Sort by" value={sortBy} onChange={setSortBy} options={SAVED_TRIPS_SORT_OPTIONS} />
+                    <SectionHeader title="Nearby stations" />
+                    {trips.length > 0 ? (
+                      <List>
+                        {trips.map((trip) => (
+                          <ListItem
+                            key={trip.id}
+                            title={trip.title}
+                            subtitle={trip.subtitle}
+                            leading={<Avatar iconName={trip.iconName} size={40} />}
+                            trailing={
+                              <View style={styles.savedTripsInlineRow}>
+                                <Badge variant={trip.badgeVariant} label={trip.badgeLabel} />
+                                <Button
+                                  variant="ghost"
+                                  size="small"
+                                  showIcon
+                                  showLabel={false}
+                                  iconName="clear"
+                                  accessibilityLabel={`Remove ${trip.title}`}
+                                  onPress={() => removeTrip(trip.id)}
+                                />
+                              </View>
+                            }
+                          />
+                        ))}
+                      </List>
+                    ) : (
+                      <EmptyState
+                        iconName="waypoints"
+                        title="No nearby trips"
+                        description="Removed trips you save will show up here again."
+                      />
+                    )}
+                  </>
+                )}
+              </>
+            )}
+          </ScrollView>
+        </Surface>
+        {/* Absolutely positioned over the top of the screen (not inline in the flex flow — a real
+            toast floats over content, it doesn't push the Dock down) — same placement Toast's own
+            catalog demo uses. One Toast per pending removal, stacked newest-on-top; each entry
+            stays in the array (with `visible: false`) through its own exit animation instead of
+            being yanked out of the tree mid-motion. */}
+        <View style={styles.savedTripsToastOverlay} pointerEvents="box-none">
+          {toasts.map((t) => (
+            <Toast
+              key={t.key}
+              visible={t.visible}
+              message={`${t.trip.title} removed`}
+              action={{ label: 'Undo', onPress: () => undoRemove(t.key, t.trip) }}
+            />
+          ))}
+        </View>
+        <Dock>
+          <Button label="Plan a new trip" onPress={() => {}} />
+        </Dock>
+      </View>
+    </PhoneFrame>
+  );
+}
+
+export default defineCatalogPage({
+  group: 'Recipes',
+  description: 'A composed real screen — a saved-trips list with a search bar, tab switcher, mode filter pills, a sort Dropdown, and a bottom action bar. Switch to the "Favorites" tab (or remove every row) to see the EmptyState alternative to the list; tap the header icon to see its Tooltip; tap a row\'s trailing × to see the Toast, which only appears after that real action and auto-dismisses (or Undo) — remove two rows back-to-back and each removal gets its own stacked toast on its own clock.',
+  tokenGallery: true,
+  fullWidthLabel: 'Preview',
+  render: () => <SavedTripsDemo />,
+});

package/starter-kit/pages/Shadow.catalog.tsx

@@ -0,0 +1,34 @@
+import React from 'react';
+import { View, Text, StyleSheet } from 'react-native';
+import { defineCatalogPage, TokenRow } from '@krapwoo/ds-viewer';
+import { DS_RADIUS, DS_SEMANTIC, DS_SHADOW, DS_SHADOW_USE, DS_SPACING, DS_TYPOGRAPHY, type ShadowToken } from '../tokens';
+
+const styles = StyleSheet.create({
+  tokenStack: { gap: DS_SPACING[800] },
+  previewRow: { flexDirection: 'row', alignItems: 'center', gap: DS_SPACING[600] },
+  previewLabel: { minWidth: 64, ...DS_TYPOGRAPHY.labelSm, color: DS_SEMANTIC.text.regular },
+  shadowBox: { width: 56, height: 40, borderRadius: DS_RADIUS.medium, backgroundColor: DS_SEMANTIC.surface.white },
+});
+
+function ShadowGallery() {
+  const steps = Object.keys(DS_SHADOW) as ShadowToken[];
+  return (
+    <View style={styles.tokenStack}>
+      {steps.map((step, i) => (
+        <TokenRow key={step} use={DS_SHADOW_USE[step]} last={i === steps.length - 1}>
+          <View style={styles.previewRow}>
+            <Text style={styles.previewLabel}>{step}</Text>
+            <View style={[styles.shadowBox, DS_SHADOW[step]]} />
+          </View>
+        </TokenRow>
+      ))}
+    </View>
+  );
+}
+
+export default defineCatalogPage({
+  group: 'Tokens',
+  description: 'Elevation tokens as ready-to-spread React Native style objects (shadowColor/Offset/Opacity/Radius + Android elevation).',
+  tokenGallery: true,
+  render: () => <ShadowGallery />,
+});

package/starter-kit/pages/Spacing.catalog.tsx

@@ -0,0 +1,12 @@
+import React from 'react';
+import { defineCatalogPage, SpacingScaleGallery } from '@krapwoo/ds-viewer';
+import { DS_SPACING, DS_SPACING_STEPS, DS_SPACING_USE } from '../tokens';
+
+export default defineCatalogPage({
+  group: 'Tokens',
+  description: 'The spacing scale (token number ÷ 50 = px), each step with a grounded "when to use this" note from DS_SPACING_USE. Reference steps directly — DS_SPACING[800], never a raw 16 — the key union is typo-safe by itself.',
+  tokenGallery: true,
+  render: () => (
+    <SpacingScaleGallery steps={DS_SPACING_STEPS} values={DS_SPACING} useNotes={DS_SPACING_USE} />
+  ),
+});

package/starter-kit/pages/TripPlannerForm.catalog.tsx

@@ -0,0 +1,48 @@
+import React, { useState } from 'react';
+import { View, StyleSheet } from 'react-native';
+import { defineCatalogPage, PhoneFrame } from '@krapwoo/ds-viewer';
+import { Button } from '../components/Button';
+import { Card } from '../components/Card';
+import { Divider } from '../components/Divider';
+import { InputField } from '../components/InputField';
+import { DS_SPACING } from '../tokens';
+
+const styles = StyleSheet.create({
+  // Trip planner recipe — fills PhoneFrame edge-to-edge (`flex:1` + `alignSelf:'stretch'` override
+  // PhoneFrame's own `alignItems/justifyContent:'center'`).
+  recipeFrameContent: { flex: 1, alignSelf: 'stretch', padding: DS_SPACING[800] },
+  recipeFields: { gap: DS_SPACING[600] },
+  recipeDivider: { marginVertical: DS_SPACING[600] },
+  recipeActions: { flexDirection: 'row', justifyContent: 'space-between', alignItems: 'center' },
+});
+
+function TripPlannerFormDemo() {
+  const [from, setFrom] = useState('Current location');
+  const [to, setTo] = useState('');
+  return (
+    <PhoneFrame>
+      <View style={styles.recipeFrameContent}>
+        <Card>
+          <View style={styles.recipeFields}>
+            <InputField label="From" value={from} onChangeText={setFrom} editable />
+            <InputField label="To" value={to} onChangeText={setTo} editable placeholder="Where to?" />
+          </View>
+          <Divider style={styles.recipeDivider} />
+          <View style={styles.recipeActions}>
+            <Button variant="tertiary" size="medium" label="Add stop" onPress={() => {}} />
+            {/* trim() so a whitespace-only "destination" can't enable Continue. */}
+            <Button variant="primary" size="medium" label="Continue" onPress={() => {}} disabled={!to.trim()} />
+          </View>
+        </Card>
+      </View>
+    </PhoneFrame>
+  );
+}
+
+export default defineCatalogPage({
+  group: 'Recipes',
+  description: 'A composed real screen — not one component in isolation — showing how Card, InputField, Divider, and Button actually fit together: a From/To trip form with a secondary "Add stop" action and a primary "Continue" that\'s disabled until a destination is entered.',
+  tokenGallery: true,
+  fullWidthLabel: 'Preview',
+  render: () => <TripPlannerFormDemo />,
+});

package/starter-kit/pages/Typography.catalog.tsx

@@ -0,0 +1,17 @@
+import React from 'react';
+import { defineCatalogPage, TypeScaleGallery } from '@krapwoo/ds-viewer';
+import { DS_TYPOGRAPHY, DS_TYPOGRAPHY_USE, type TypographyToken } from '../tokens';
+
+export default defineCatalogPage({
+  group: 'Tokens',
+  description: 'The type scale, rendered at its real sizes with a grounded "when to use this" note from DS_TYPOGRAPHY_USE per token — label* are semibold UI labels, body* regular reading text, emphasis*/title/display headlines.',
+  tokenGallery: true,
+  render: () => (
+    <TypeScaleGallery
+      steps={Object.keys(DS_TYPOGRAPHY) as TypographyToken[]}
+      sampleStyle={(name) => DS_TYPOGRAPHY[name]}
+      meta={(name) => `${DS_TYPOGRAPHY[name].fontSize}/${DS_TYPOGRAPHY[name].fontWeight}`}
+      useNotes={DS_TYPOGRAPHY_USE}
+    />
+  ),
+});

package/starter-kit/tokens/index.ts

@@ -0,0 +1,50 @@
+/**
+ * Design tokens — the single source of truth for the native component tree.
+ *
+ * Nothing here is platform-specific: values are plain hexes, numbers, and font-weight strings. The
+ * RN components import these directly. Kept platform-neutral on purpose so a future non-native
+ * platform (web, desktop, …) can consume the same values — see the repo README.
+ */
+export {
+  PALETTE_STEPS,
+  DS_PALETTE,
+  paletteTokenForColor,
+  colorValueLabel,
+} from './palette';
+export type { PaletteName, PaletteStep } from './palette';
+
+export { DS_SEMANTIC } from './semantic';
+
+export {
+  DS_SPACING,
+  DS_SPACING_STEPS,
+  DS_SPACING_USE,
+  DS_RADIUS,
+  DS_RADIUS_STEPS,
+  DS_RADIUS_USE,
+  DS_ICON_SIZE,
+  DS_ICON_SIZE_STEPS,
+  DS_A11Y_MIN_TOUCH_TARGET,
+} from './scales';
+export type { SpacingStep, RadiusStep, IconSizeStep } from './scales';
+
+export { DS_FONT_WEIGHT, DS_FONT_WEIGHT_USE, DS_TYPOGRAPHY, DS_TYPOGRAPHY_USE } from './typography';
+export type { FontWeightName, TypographyToken } from './typography';
+
+export { DS_SHADOW, DS_SHADOW_USE } from './shadow';
+export type { ShadowToken } from './shadow';
+
+export {
+  DS_MOTION_DURATION,
+  DS_MOTION_DURATION_STEPS,
+  DS_MOTION_DURATION_USE,
+  DS_MOTION_EASING,
+  DS_MOTION_EASING_STEPS,
+  DS_MOTION_EASING_USE,
+  DS_MOTION_SPRING,
+  DS_MOTION_SPRING_USE,
+  DS_MOTION_LOOP_DURATION,
+  DS_MOTION_LOOP_DURATION_STEPS,
+  DS_MOTION_LOOP_DURATION_USE,
+} from './motion';
+export type { MotionDurationStep, MotionEasingStep, MotionSpringConfig, MotionLoopDurationStep } from './motion';

package/starter-kit/tokens/motion.ts

@@ -0,0 +1,90 @@
+/**
+ * Motion tokens — duration and easing curves for transitions/animations.
+ *
+ * Easing curves are plain cubic-bezier tuples (`[x1, y1, x2, y2]`, matching CSS `cubic-bezier()` /
+ * RN `Easing.bezier()`) rather than `Easing` function objects, so this file stays free of any
+ * `react-native` import — the same platform-neutral shape every other token file follows. Convert
+ * at the call site: `Easing.bezier(...DS_MOTION_EASING.standard)`.
+ */
+export const DS_MOTION_DURATION_STEPS = ['fast', 'base', 'slow'] as const;
+export type MotionDurationStep = (typeof DS_MOTION_DURATION_STEPS)[number];
+
+export const DS_MOTION_DURATION: Record<MotionDurationStep, number> = {
+  fast: 150,
+  base: 240,
+  slow: 400,
+};
+
+export const DS_MOTION_EASING_STEPS = ['standard', 'decelerate', 'accelerate'] as const;
+export type MotionEasingStep = (typeof DS_MOTION_EASING_STEPS)[number];
+
+export const DS_MOTION_EASING: Record<MotionEasingStep, readonly [number, number, number, number]> = {
+  standard: [0.4, 0.0, 0.2, 1],
+  decelerate: [0.0, 0.0, 0.2, 1],
+  accelerate: [0.4, 0.0, 1, 1],
+};
+
+/**
+ * When to reach for each duration/easing step — grounded in this template's own real animations
+ * (AnimatedChevron's 240ms rotate, CollapsibleSwap's 240ms default) where a value already exists;
+ * `fast`/`accelerate`/`decelerate` are the standard Material-motion counterparts alongside it, for
+ * the short taps and exits this template doesn't yet have a named constant for.
+ */
+export const DS_MOTION_DURATION_USE: Record<MotionDurationStep, string> = {
+  fast: 'A quick, barely-there transition — a pressed-state feedback flash, a small icon swap.',
+  base: "The default — AnimatedChevron's rotate and CollapsibleSwap's expand/collapse both already run at 240ms. Reach for this first.",
+  slow: 'A deliberate, noticeable transition — a sheet or panel entering/exiting the screen.',
+};
+
+export const DS_MOTION_EASING_USE: Record<MotionEasingStep, string> = {
+  standard: 'The default for most transitions — eases in and out symmetrically, for a move that starts and ends in the same place (a toggle, a swap).',
+  decelerate: 'Fast start, gentle stop — for something entering the screen (a sheet sliding up, a toast appearing).',
+  accelerate: 'Gentle start, fast finish — for something leaving the screen (a sheet dismissing, a toast exiting).',
+};
+
+/** Spring physics config, shaped for `Animated.spring(value, DS_MOTION_SPRING)` (or Reanimated's
+ *  `withSpring`). Grounded in the metro-native app this template was extracted from, where this exact
+ *  config (there, `SHEET_SPRING_CONFIG`) drives its BottomSheet's snap-point transitions — a
+ *  near-critically-damped spring (high damping relative to stiffness, `overshootClamping` on) that
+ *  settles quickly with no bounce, unlike a playful/bouncy spring. */
+export interface MotionSpringConfig {
+  stiffness: number;
+  damping: number;
+  mass: number;
+  overshootClamping: boolean;
+  restDisplacementThreshold: number;
+  restSpeedThreshold: number;
+}
+
+export const DS_MOTION_SPRING: MotionSpringConfig = {
+  stiffness: 1000,
+  damping: 500,
+  mass: 3,
+  overshootClamping: true,
+  restDisplacementThreshold: 1,
+  restSpeedThreshold: 1,
+};
+
+export const DS_MOTION_SPRING_USE =
+  'A snappy, near-critically-damped spring for programmatic snap-point transitions — e.g. a bottom sheet or panel settling into position after a drag, rather than a fixed-duration timing curve.';
+
+/**
+ * Durations for continuous, indeterminate loops (a spinner's fill→empty cycle, a shimmer's pulse) —
+ * a distinct category from `DS_MOTION_DURATION`'s one-shot transitions, and generally slower: a loop
+ * has to read as calm and ongoing rather than a quick state change. Grounded in this template's own
+ * two existing loops: Loading's circle/linear fill-cycle (`duration` prop, default 1200) and
+ * Shimmer's shared pulse clock (`PULSE_CYCLE_MS`, 1800 — deliberately slower and calmer than the
+ * spinner, since a shimmer stands in for content that just hasn't loaded yet, not an active process).
+ */
+export const DS_MOTION_LOOP_DURATION_STEPS = ['spinner', 'pulse'] as const;
+export type MotionLoopDurationStep = (typeof DS_MOTION_LOOP_DURATION_STEPS)[number];
+
+export const DS_MOTION_LOOP_DURATION: Record<MotionLoopDurationStep, number> = {
+  spinner: 1200,
+  pulse: 1800,
+};
+
+export const DS_MOTION_LOOP_DURATION_USE: Record<MotionLoopDurationStep, string> = {
+  spinner: "An active, ongoing process the user is waiting on — Loading's own default for both its circle and linear variants.",
+  pulse: "Content that hasn't loaded yet, not an active process — deliberately slower/calmer than spinner. Shimmer's shared pulse clock runs at this rate so every visible shimmer stays in lockstep.",
+};

package/starter-kit/tokens/palette.ts

@@ -0,0 +1,111 @@
+/**
+ * Raw color palette — the base scale every semantic token is built from.
+ *
+ * Each hue steps 0 (lightest) → 800 (darkest). These are RAW values; app code should almost
+ * always reach for a semantic token (see semantic.ts) instead of a palette step directly, so a
+ * rebrand only touches this file + semantic.ts. To rebrand: swap these hexes for your own scale
+ * (keep the 0–800 shape) and the whole system re-themes.
+ */
+export const PALETTE_STEPS = [0, 100, 200, 300, 400, 500, 600, 700, 800] as const;
+export type PaletteStep = (typeof PALETTE_STEPS)[number];
+
+export const DS_PALETTE = {
+  grey: {
+    0: '#FFFFFF',
+    100: '#F5F5F5',
+    200: '#E5E5E5',
+    300: '#D4D4D4',
+    400: '#A3A3A3',
+    500: '#737373',
+    600: '#404040',
+    700: '#171717',
+    800: '#000000',
+  },
+  green: {
+    0: '#F0FFF4',
+    100: '#C6F6D5',
+    200: '#9AE6B4',
+    300: '#68D391',
+    400: '#48BB78',
+    500: '#38A169',
+    600: '#2F855A',
+    700: '#276749',
+    800: '#1C4532',
+  },
+  blue: {
+    0: '#EBF8FF',
+    100: '#BEE3F8',
+    200: '#90CDF4',
+    300: '#63B3ED',
+    400: '#4299E1',
+    500: '#3182CE',
+    600: '#2B6CB0',
+    700: '#2C5282',
+    800: '#1A365D',
+  },
+  red: {
+    0: '#FFF5F5',
+    100: '#FED7D7',
+    200: '#FEB2B2',
+    300: '#FC8181',
+    400: '#F56565',
+    500: '#E53E3E',
+    600: '#C53030',
+    700: '#9B2C2C',
+    800: '#63171B',
+  },
+  yellow: {
+    0: '#FFF4EB',
+    100: '#FFE3C7',
+    200: '#FFD099',
+    300: '#FFB966',
+    400: '#FFA333',
+    500: '#FF8C00',
+    600: '#D67600',
+    700: '#A35A00',
+    800: '#703E00',
+  },
+  purple: {
+    0: '#FAF5FF',
+    100: '#E9D8FD',
+    200: '#D6BCFA',
+    300: '#B794F4',
+    400: '#9F7AEA',
+    500: '#805AD5',
+    600: '#6B46C1',
+    700: '#553C9A',
+    800: '#322659',
+  },
+} as const;
+
+export type PaletteName = keyof typeof DS_PALETTE;
+
+function normalizeHex(color: string): string | null {
+  const trimmed = color.trim();
+  if (!trimmed.startsWith('#')) return null;
+  let hex = trimmed.toUpperCase();
+  if (hex.length === 4) {
+    hex = `#${hex[1]}${hex[1]}${hex[2]}${hex[2]}${hex[3]}${hex[3]}`;
+  }
+  return hex;
+}
+
+/** Resolves a hex color to a palette token name (e.g. `green-600`), or null if not in DS_PALETTE. */
+export function paletteTokenForColor(color: string): string | null {
+  const target = normalizeHex(color);
+  if (!target) return null;
+
+  for (const name of Object.keys(DS_PALETTE) as PaletteName[]) {
+    for (const step of PALETTE_STEPS) {
+      if (normalizeHex(DS_PALETTE[name][step]) === target) {
+        return `${name}-${step}`;
+      }
+    }
+  }
+  return null;
+}
+
+/** Palette token when mapped; otherwise the raw value (hex / rgba). Used by the catalog. */
+export function colorValueLabel(color: string): string {
+  return paletteTokenForColor(color) ?? color;
+}