@krapwoo/ds-viewer 0.1.0 → 0.2.0

package/starter-kit/tokens/scales.ts

@@ -0,0 +1,106 @@
+/**
+ * Numeric scales — spacing, radius, icon size. Values are in px/points (identical on RN and web).
+ *
+ * Spacing keys mirror a Figma-style scale where the token number ÷ 50 = px (800 → 16). Reference
+ * tokens directly at call sites (`DS_SPACING[800]`, `DS_RADIUS.medium`) — the convention every
+ * component here follows; the key unions are typo-safe already, so no accessor wrapper is needed.
+ */
+
+// ─── Spacing ────────────────────────────────────────────────────────────────
+export const DS_SPACING_STEPS = [
+  'none',
+  100, 200, 300, 400, 600, 800, 1200, 1600, 2000, 2400, 2800, 3200,
+] as const;
+export type SpacingStep = (typeof DS_SPACING_STEPS)[number];
+
+export const DS_SPACING = {
+  none: 0,
+  100: 2,
+  200: 4,
+  300: 6,
+  400: 8,
+  600: 12,
+  800: 16,
+  1200: 24,
+  1600: 32,
+  2000: 40,
+  2400: 48,
+  2800: 56,
+  3200: 64,
+} as const;
+
+/**
+ * When to reach for each spacing step — grounded in how the existing components actually use them
+ * (surveyed across native/components + the source app), not aspirational. Meant to be read by
+ * whoever (human or AI) is deciding which step fits a new layout; also rendered in the catalog's
+ * Spacing page. When in doubt, reach for 800 first — it's what most components converge on.
+ */
+export const DS_SPACING_USE: Record<SpacingStep, string> = {
+  none: 'Flush — no gap, e.g. an icon glued directly to adjacent content.',
+  100: "Micro-gap inside a tightly clustered pair — a ghost button's icon+label, a segmented toggle's track inset/segment gap.",
+  200: "Tight gap between closely related elements — a section header's icon+title, a tab's icon+label, a pill's internal gap.",
+  300: "A small nudge, rarely needed — e.g. a toast's icon-to-text gap when 200 reads cramped and 400 too loose.",
+  400: "Compact standard gap/padding — a status dot to its label, a pill's tight horizontal padding.",
+  600: "Medium gap/padding — a nested card's internal gap, a pill row's spacing, a row's horizontal padding.",
+  800: "The default — card padding, a button's vertical padding, most rows' gap. Reach for this first.",
+  1200: "Large horizontal padding — e.g. a large button's side padding.",
+  1600: 'Section-level spacing between stacked blocks on a screen (margin/gap between sections, not inside a component).',
+  2000: "A fixed control dimension, not a gap — e.g. an icon-only pill's height.",
+  2400: "Bottom padding for a scrollable screen's content.",
+  2800: 'Reserved — no current consumer; a step between 2400 and 3200 if both read wrong.',
+  3200: 'Large bottom padding for sheets/scroll content that must clear a safe area or tab bar.',
+};
+
+// ─── Radius ─────────────────────────────────────────────────────────────────
+export const DS_RADIUS_STEPS = ['none', 'xs', 'small', 'medium', 'large', 'round'] as const;
+export type RadiusStep = (typeof DS_RADIUS_STEPS)[number];
+
+export const DS_RADIUS = {
+  none: 0,
+  xs: 4,
+  small: 8,
+  medium: 12,
+  large: 24,
+  round: 999,
+} as const;
+
+/**
+ * When to reach for each radius step — grounded in how the existing components actually use them
+ * (surveyed across native/components), not aspirational.
+ */
+export const DS_RADIUS_USE: Record<RadiusStep, string> = {
+  none: 'Flush corners — no rounding.',
+  xs: "Small corner softening — a banner's small action button, tiny placeholder blocks.",
+  small: "Compact rounding — a ghost button, a text-shimmer placeholder, UnderlineTabs' sliding indicator.",
+  medium: "The default card/field radius — Banner's callout, FieldContainer's input chrome, Toast, a container shimmer.",
+  large: "Prominent rounding for large surfaces — Dialog, BottomSheet's top corners.",
+  round: "Fully circular/pill — Button, Pill, Badge, Status dot, SegmentedToggle's track/thumb. Reach for this on anything meant to read as a chip, dot, or pill.",
+};
+
+// ─── Icon size ────────────────────────────────────────────────────────────────
+/**
+ * Icon sizes pair with text scales — use the same step as the text beside the icon.
+ *   xxs (12) tight badges · xs (14) small label rows · sm (16) standard inline (default)
+ *   md (20) prominent inline / tabs · lg (24) nav / actions · xl (32) section leads · 2xl (40) hero
+ */
+export const DS_ICON_SIZE_STEPS = ['xxs', 'xs', 'sm', 'md', 'lg', 'xl', '2xl'] as const;
+export type IconSizeStep = (typeof DS_ICON_SIZE_STEPS)[number];
+
+export const DS_ICON_SIZE: Record<IconSizeStep, number> = {
+  xxs: 12,
+  xs: 14,
+  sm: 16,
+  md: 20,
+  lg: 24,
+  xl: 32,
+  '2xl': 40,
+} as const;
+
+// ─── Accessibility ──────────────────────────────────────────────────────────────
+/**
+ * Minimum tappable width/height (iOS's own 44pt guideline) — every control smaller than this pads
+ * its touch target out to it via `hitSlop` (small controls: Checkbox, Radio, Switch) or `minHeight`
+ * (row-shaped controls: ListItem, SegmentedToggle, UnderlineTabs, TopNav's icon slots), rather than
+ * each one hardcoding the number `44` independently.
+ */
+export const DS_A11Y_MIN_TOUCH_TARGET = 44;

package/starter-kit/tokens/semantic.ts

@@ -0,0 +1,98 @@
+/**
+ * Semantic color tokens — the layer app code should consume.
+ *
+ * Every value points at a palette step (or a deliberate one-off). Components reference these names
+ * (surface.main, text.regular, emphasis.positive…) not raw hexes, so a rebrand is: edit palette.ts,
+ * then re-point anything here you want to shift. Grouped by role: surface, text, element, interaction,
+ * border, emphasis (saturated accents), shade (tinted fills).
+ */
+import { DS_PALETTE } from './palette';
+
+const grey = DS_PALETTE.grey;
+const green = DS_PALETTE.green;
+const blue = DS_PALETTE.blue;
+const red = DS_PALETTE.red;
+const yellow = DS_PALETTE.yellow;
+const purple = DS_PALETTE.purple;
+
+export const DS_SEMANTIC = {
+  surface: {
+    main: grey[100],
+    muted: grey[300],
+    white: grey[0],
+    onTap: grey[100],
+    inverse: grey[800],
+    /** Translucent secondary fill — secondary buttons, recessed tracks (SegmentedToggle), field
+     *  chrome (FieldContainer/InputField). Adapts to whatever surface sits under it. */
+    recessed: 'rgba(0, 0, 0, 0.10)',
+    /** Pressed state for a `recessed`-filled surface — a deliberately tuned darker translucent
+     *  value, not `interaction.pressed` stacked on top of `recessed`: two independently-chosen
+     *  overlays compositing together produce whatever their alpha math happens to yield, not a
+     *  value anyone actually looked at and picked. Every `recessed` surface's pressed state should
+     *  point here instead, so it's one tuned, reusable, nameable value. */
+    recessedPressed: 'rgba(0, 0, 0, 0.20)',
+    /** Disabled state for a `recessed`-filled surface — same reasoning as `recessedPressed`: a
+     *  deliberately tuned lighter translucent value (reads as washed-out/inactive) rather than a
+     *  second overlay stacked on top. */
+    recessedDisabled: 'rgba(0, 0, 0, 0.05)',
+  },
+  text: {
+    regular: grey[800],
+    /** Secondary/muted text. grey[500] alone falls just short of WCAG AA (4.5:1) for 12–14px text on
+     *  the surface.main background (~4.34:1) — grey[600] is the next step up and clears it
+     *  comfortably (~9.5:1), so every semantic colour traces to the palette. */
+    muted: grey[600],
+    /** Disabled field/value text — a step lighter than `muted` (which doubles as hint/placeholder
+     *  text), so a disabled field's text doesn't just read as an empty hint. WCAG contrast isn't
+     *  required for disabled UI (1.4.3 exempts inactive components), so this deliberately sits
+     *  below the step `muted` was tuned to clear. */
+    disabled: grey[500],
+    inverse: grey[0],
+    /** Inline text links — same value as emphasis.info, so a link and an "info" status read as the
+     *  same accent, but named for what it's actually used for (Banner's `link` prop) rather than
+     *  reusing the status-emphasis name at every call site. Clears WCAG AA (~5.6:1) against white
+     *  and every `shade.*` tint a link might sit on (all near-white). */
+    link: blue[600],
+  },
+  element: {
+    divider: 'rgba(0, 0, 0, 0.12)',
+    overlayBackdrop: 'rgba(0, 0, 0, 0.34)',
+  },
+  interaction: {
+    /** Universal pressed overlay — apply on top of any light surface. */
+    pressed: 'rgba(0, 0, 0, 0.08)',
+    /** Lighter hover overlay (web). */
+    hover: 'rgba(0, 0, 0, 0.04)',
+    /** 2px focus ring color — visible on light surfaces. */
+    focused: grey[800],
+    /** Disabled opacity — apply to the whole tappable element. */
+    disabledOpacity: 0.38,
+  },
+  border: {
+    dark: grey[700],
+    light: grey[400],
+    /** Subtle UI separators — between divider opacity and border.light. */
+    subtle: grey[300],
+  },
+  /** Saturated accents for text/icons that must read as a status. Each one is set to the step that
+   *  clears WCAG AA (4.5:1) against its matching `shade` background — `positive`/`warning` need step
+   *  700 for that (green/yellow are lighter hues than red/blue at the same step, so 600 falls short:
+   *  ~4.39:1 and ~3.0:1 respectively); `negative`/`info` already clear it at 600. */
+  emphasis: {
+    neutral: grey[600],
+    positive: green[700],
+    warning: yellow[700],
+    negative: red[600],
+    info: blue[600],
+    accent: purple[700],
+  },
+  /** Light tinted fills for badges/banners/cards of each status. */
+  shade: {
+    neutral: grey[0],
+    positive: green[0],
+    warning: yellow[0],
+    negative: red[0],
+    info: blue[0],
+    accent: purple[100],
+  },
+} as const;

package/starter-kit/tokens/shadow.ts

@@ -0,0 +1,36 @@
+/** Elevation tokens as React Native style objects (shadowColor/Offset/Opacity/Radius + Android elevation). */
+export const DS_SHADOW = {
+  /** Resting lift for cards / unselected pills — barely there. */
+  resting: {
+    shadowColor: '#000000',
+    shadowOffset: { width: 0, height: 0 },
+    shadowOpacity: 0.02,
+    shadowRadius: 4,
+    elevation: 1,
+  },
+  /** Gentle drop shadow for card surfaces. */
+  card: {
+    shadowColor: '#000000',
+    shadowOffset: { width: 0, height: 2 },
+    shadowOpacity: 0.08,
+    shadowRadius: 8,
+    elevation: 3,
+  },
+  /** Upward-cast shadow for bottom sheets — casts above the sheet edge. */
+  bottomSheet: {
+    shadowColor: '#000000',
+    shadowOffset: { width: 0, height: -4 },
+    shadowOpacity: 0.12,
+    shadowRadius: 12,
+    elevation: 8,
+  },
+} as const;
+
+export type ShadowToken = keyof typeof DS_SHADOW;
+
+/** When to reach for each shadow — grounded in real usage across native/components. */
+export const DS_SHADOW_USE: Record<ShadowToken, string> = {
+  resting: 'Barely-there lift for surfaces that sit at rest on the page — Card, Pill, SegmentedToggle. Reach for this first.',
+  card: "A stronger, deliberate lift for a surface that floats above the page — Toast's bar.",
+  bottomSheet: 'An upward-cast shadow (offset negative, casting above the element) for anything pinned to the bottom edge — a bottom sheet or Dock.',
+};

package/starter-kit/tokens/typography.ts

@@ -0,0 +1,72 @@
+/**
+ * Type scale + font weights.
+ *
+ * DS_TYPOGRAPHY entries are RN-shaped (fontSize/fontWeight/lineHeight numbers). On web the same
+ * numbers apply as `font-size`/`font-weight`/`line-height` (px). Naming: `label*` are semibold UI
+ * labels, `body*` are regular reading text, `emphasis*`/`display`/`title` are headline weights.
+ */
+export const DS_FONT_WEIGHT = {
+  normal: '400' as const,
+  medium: '500' as const,
+  semibold: '600' as const,
+  bold: '700' as const,
+  extrabold: '800' as const,
+  black: '900' as const,
+};
+export type FontWeightName = keyof typeof DS_FONT_WEIGHT;
+
+/**
+ * When to reach for each font weight — grounded in real usage. Most components get their weight
+ * via a spread `DS_TYPOGRAPHY` token (`label*` tokens embed `semibold`, `emphasis*`/`display`/`title`
+ * embed `bold`) rather than referencing `DS_FONT_WEIGHT` directly — noted below where that's the case.
+ */
+export const DS_FONT_WEIGHT_USE: Record<FontWeightName, string> = {
+  normal: "Regular body text — every DS_TYPOGRAPHY `body*` token embeds this; rarely referenced directly.",
+  medium: "A touch heavier than body text without reading as a full label — Toast's message text.",
+  semibold: "Standard UI label weight — Button's label, SectionHeader's title; embedded in every DS_TYPOGRAPHY `label*` token.",
+  bold: "Headline weight — embedded in every DS_TYPOGRAPHY `emphasis*`/`display`/`title` token; no component references it directly outside those.",
+  extrabold: 'Reserved — no current consumer.',
+  black: 'Reserved — no current consumer.',
+};
+
+// Every token now carries an explicit lineHeight — before this, labelXs/Sm/Md and emphasisSm/Md/
+// display/title fell back to each platform's own implicit default, which differs between iOS,
+// Android, and web and was a real source of inconsistent vertical rhythm. Two rules set the values:
+//  - label* matches its same-fontSize body* counterpart (12→16, 14→20, 16→22) — a label and body
+//    line sitting next to each other should land on the same baseline grid regardless of weight.
+//  - emphasis*/display/title (no body-scale equivalent to borrow from) extend emphasisLg's own
+//    already-established +8 relationship (48→56).
+export const DS_TYPOGRAPHY = {
+  labelXs: { fontSize: 12, fontWeight: '600' as const, lineHeight: 16 },
+  labelSm: { fontSize: 14, fontWeight: '600' as const, lineHeight: 20 },
+  labelMd: { fontSize: 16, fontWeight: '600' as const, lineHeight: 22 },
+  bodyXs: { fontSize: 12, fontWeight: '400' as const, lineHeight: 16 },
+  bodySm: { fontSize: 14, fontWeight: '400' as const, lineHeight: 20 },
+  bodyMd: { fontSize: 16, fontWeight: '400' as const, lineHeight: 22 },
+  emphasisSm: { fontSize: 32, fontWeight: '700' as const, lineHeight: 40 },
+  emphasisMd: { fontSize: 40, fontWeight: '700' as const, lineHeight: 48 },
+  emphasisLg: { fontSize: 48, fontWeight: '700' as const, lineHeight: 56 },
+  display: { fontSize: 88, fontWeight: '700' as const, lineHeight: 96 },
+  title: { fontSize: 24, fontWeight: '700' as const, lineHeight: 32 },
+} as const;
+
+export type TypographyToken = keyof typeof DS_TYPOGRAPHY;
+
+/**
+ * When to reach for each type token — grounded in how the source app actually uses them, not
+ * aspirational. Meant to be read by whoever (human or AI) is deciding which token fits a new piece
+ * of UI text; also rendered in the catalog's Typography page.
+ */
+export const DS_TYPOGRAPHY_USE: Record<TypographyToken, string> = {
+  labelXs: "Smallest UI label — tab labels, a status row's label, a section header's trailing button text.",
+  labelSm: "Small UI label — a pill's text, a small button's label, a banner's title.",
+  labelMd: "Standard UI label — a large button's label, an emphasized banner title.",
+  bodyXs: "Fine print / secondary meta text — settings captions, a bug-report hint, a train-info row's footnote.",
+  bodySm: "Small reading text — a toast's message, a text area's input, a banner's description.",
+  bodyMd: "Standard reading text — a search field's input, an input field's value, a screen's body copy.",
+  emphasisSm: "A prominent standalone number — a train countdown, a success sheet's headline number.",
+  emphasisMd: 'A bigger emphasis number/headline — onboarding hero screens, a key stat on a saved/map screen.',
+  emphasisLg: "The largest 'big number' emphasis — an onboarding welcome hero, a live arrival countdown.",
+  display: 'Reserved for a true hero/display moment — the largest size on the scale; no current consumer.',
+  title: "A screen/page title — a settings screen's heading, an error state's title.",
+};