fix(snap): polish overlays and compact text spacing

bob-obringer · web-flow · commit e4a984bf9e4f · 2026-05-22T11:37:32.000-04:00
diff --git a/examples/component-improvements/src/index.ts b/examples/component-improvements/src/index.ts
@@ -4,6 +4,8 @@ import { registerSnapHandler } from "@farcaster/snap-hono";
 import type { SnapElementInput, SnapHandlerResult } from "@farcaster/snap";
 
 const app = new Hono();
+const SNAP_IMAGE_URL =
+  "https://boey4mnqvpqdktto.public.blob.vercel-storage.com/chain/9d1648dc4d5a42fe.png";
 
 registerSnapHandler(app, async (ctx): Promise<SnapHandlerResult> => {
   const base = snapBaseUrlFromRequest(ctx.request);
@@ -19,7 +21,7 @@ export default app;
 
 function componentImprovementsPage(
   base: string,
-  submitted: boolean,
+  submitted: boolean
 ): SnapHandlerResult {
   return {
     version: "2.0",
@@ -30,14 +32,20 @@ function componentImprovementsPage(
       elements: {
         page: {
           type: "stack",
-          children: ["banner", "showcase-controls", "pager", "actions", "status"],
+          children: [
+            "banner",
+            "showcase-controls",
+            "pager",
+            "actions",
+            "status",
+          ],
         },
         banner: {
           type: "image",
           props: {
-            url: "https://placehold.co/1200x300/0f766e/ffffff.png?text=NEYN-11381",
+            url: SNAP_IMAGE_URL,
             aspect: "4:1",
-            alt: "Compact teal NEYN-11381 banner",
+            alt: "Compact chain banner",
             title: "NEYN-11381 showcase",
             subtitle: "Paginator, image overlays, compact copy, dense grids",
           },
@@ -91,28 +99,32 @@ function componentImprovementsPage(
         "jump-medium-grid": paginatorButton("Medium grid", "paginator_go_to", {
           page: 4,
         }),
-        overview: pageStack("overview-title", "overview-copy", "overview-short"),
+        overview: pageStack(
+          "overview-title",
+          "overview-copy",
+          "overview-short"
+        ),
         "overview-title": heading("Visible paginator"),
         "overview-copy": caption(
           "This example keeps the built-in controls and indicators visible while also using custom local actions outside the paginator.",
-          2,
+          2
         ),
         "overview-short": caption(
-          "Text now wraps by default; add maxLines only when a section needs a bounded height.",
+          "Text now wraps by default; add maxLines only when a section needs a bounded height."
         ),
         copy: pageStack("copy-title", "copy-one-line", "copy-two-lines"),
         "copy-title": heading("Optional text clamping"),
         "copy-one-line": caption(
-          "No maxLines prop here: this long piece of supporting copy can wrap naturally instead of being clamped by default.",
+          "No maxLines prop here: this long piece of supporting copy can wrap naturally instead of being clamped by default."
         ),
         "copy-two-lines": caption(
           "This text opts into maxLines: 2, giving longer explanatory copy a little more room without letting the snap become tall.",
-          2,
+          2
         ),
         grid: pageStack("grid-title", "grid-copy", "dense-grid", "grid-next"),
         "grid-title": heading("Dense 1:1 grid"),
         "grid-copy": caption(
-          "Square cells keep board-like layouts compact and predictable.",
+          "Square cells keep board-like layouts compact and predictable."
         ),
         "dense-grid": {
           type: "cell_grid",
@@ -128,12 +140,12 @@ function componentImprovementsPage(
         "small-grid": pageStack(
           "small-grid-title",
           "small-grid-copy",
-          "small-square-grid",
+          "small-square-grid"
         ),
         "small-grid-title": heading("Small centered grid"),
         "small-grid-copy": caption(
           "maxWidth: sm caps this board, centers it, and keeps every cell square.",
-          2,
+          2
         ),
         "small-square-grid": {
           type: "cell_grid",
@@ -149,12 +161,12 @@ function componentImprovementsPage(
         "medium-grid": pageStack(
           "medium-grid-title",
           "medium-grid-copy",
-          "medium-square-grid",
+          "medium-square-grid"
         ),
         "medium-grid-title": heading("Medium centered grid"),
         "medium-grid-copy": caption(
           "maxWidth: md is wider than sm but still centers itself; lg/default remains full-width.",
-          2,
+          2
         ),
         "medium-square-grid": {
           type: "cell_grid",
@@ -170,12 +182,12 @@ function componentImprovementsPage(
         "custom-nav": pageStack(
           "custom-nav-title",
           "custom-nav-copy",
-          "custom-nav-row",
+          "custom-nav-row"
         ),
         "custom-nav-title": heading("Custom local controls"),
         "custom-nav-copy": caption(
           "Buttons can move the snap's one paginator locally without POSTing.",
-          2,
+          2
         ),
         "custom-nav-row": {
           type: "stack",
@@ -189,7 +201,7 @@ function componentImprovementsPage(
         "image-card-image": {
           type: "image",
           props: {
-            url: "https://placehold.co/1200x300/115e59/ffffff.png?text=4%3A1+Overlay",
+            url: SNAP_IMAGE_URL,
             aspect: "4:1",
             alt: "4:1 card with overlay text",
             title: "Image props, not hero",
@@ -200,13 +212,13 @@ function componentImprovementsPage(
         "many-pages-title": heading("More than six pages"),
         "many-pages-copy": caption(
           "Paginator pages can exceed the normal per-container child count while the global element cap still applies.",
-          2,
+          2
         ),
         limits: pageStack("limits-title", "limits-copy", "limits-back"),
         "limits-title": heading("Validation stays strict"),
         "limits-copy": caption(
           "The local page index never becomes a POST input, and snap-level limits still protect the whole tree.",
-          2,
+          2
         ),
         "limits-back": paginatorButton("Go to first", "paginator_go_to", {
           page: 0,
@@ -215,7 +227,7 @@ function componentImprovementsPage(
         "finish-title": heading("Compact actions"),
         "finish-copy": caption(
           "The shorter button height and restored gaps should feel compact without crowding the layout.",
-          2,
+          2
         ),
         actions: {
           type: "stack",
@@ -286,7 +298,7 @@ function caption(content: string, maxLines?: number): SnapElementInput {
 function paginatorButton(
   label: string,
   action: "paginator_next" | "paginator_prev" | "paginator_go_to",
-  params: Record<string, unknown> = {},
+  params: Record<string, unknown> = {}
 ): SnapElementInput {
   return {
     type: "button",
diff --git a/pkgs/snap/src/react-native/components/snap-image.tsx b/pkgs/snap/src/react-native/components/snap-image.tsx
@@ -36,17 +36,19 @@ export function SnapImage({
         accessibilityLabel={alt || undefined}
       />
       {hasOverlay ? (
-        <View style={styles.overlay}>
-          {title ? (
-            <Text numberOfLines={1} style={styles.title}>
-              {title}
-            </Text>
-          ) : null}
-          {subtitle ? (
-            <Text numberOfLines={1} style={styles.subtitle}>
-              {subtitle}
-            </Text>
-          ) : null}
+        <View style={styles.overlay} pointerEvents="none">
+          <View style={styles.overlayContent}>
+            {title ? (
+              <Text numberOfLines={1} style={styles.title}>
+                {title}
+              </Text>
+            ) : null}
+            {subtitle ? (
+              <Text numberOfLines={1} style={styles.subtitle}>
+                {subtitle}
+              </Text>
+            ) : null}
+          </View>
         </View>
       ) : null}
     </View>
@@ -71,21 +73,33 @@ const styles = StyleSheet.create({
     left: 0,
     right: 0,
     bottom: 0,
-    paddingHorizontal: 12,
-    paddingTop: 24,
-    paddingBottom: 10,
-    backgroundColor: "rgba(0, 0, 0, 0.48)",
+    paddingHorizontal: 3,
+    paddingBottom: 3,
+  },
+  overlayContent: {
+    alignSelf: "flex-start",
+    maxWidth: "100%",
+    borderRadius: 5,
+    paddingHorizontal: 5,
+    paddingVertical: 3,
+    backgroundColor: "rgba(0, 0, 0, 0.22)",
   },
   title: {
     color: "#fff",
     fontSize: 14,
     lineHeight: 18,
     fontWeight: "700",
+    textShadowColor: "#000",
+    textShadowOffset: { width: 1.25, height: 1.25 },
+    textShadowRadius: 1,
   },
   subtitle: {
-    color: "rgba(255, 255, 255, 0.85)",
+    color: "#fff",
     fontSize: 12,
     lineHeight: 16,
     fontWeight: "500",
+    textShadowColor: "#000",
+    textShadowOffset: { width: 1.25, height: 1.25 },
+    textShadowRadius: 1,
   },
 });
diff --git a/pkgs/snap/src/react-native/components/snap-item-group.tsx b/pkgs/snap/src/react-native/components/snap-item-group.tsx
@@ -18,7 +18,10 @@ export function SnapItemGroup({
   const { colors } = useSnapTheme();
   const border = Boolean(props.border);
   const separator = Boolean(props.separator);
-  const gap = GAP_MAP[String(props.gap ?? "sm")] ?? 4;
+  const explicitGap =
+    typeof props.gap === "string" ? String(props.gap) : undefined;
+  const defaultGap = border || separator ? "sm" : "none";
+  const gap = GAP_MAP[explicitGap ?? defaultGap] ?? GAP_MAP[defaultGap]!;
   const items = Children.toArray(children);
 
   return (
diff --git a/pkgs/snap/src/react-native/components/snap-item.tsx b/pkgs/snap/src/react-native/components/snap-item.tsx
@@ -135,8 +135,8 @@ const styles = StyleSheet.create({
     borderRadius: 9999,
   },
   title: {
-    fontSize: 15,
-    lineHeight: 20,
+    fontSize: 14,
+    lineHeight: 19,
     fontWeight: "500",
   },
   description: {
diff --git a/pkgs/snap/src/react-native/components/snap-text.tsx b/pkgs/snap/src/react-native/components/snap-text.tsx
@@ -3,8 +3,15 @@ import { StyleSheet, Text, View } from "react-native";
 import { useSnapStackDirection } from "../stack-direction-context";
 import { useSnapTheme } from "../theme";
 
-const SIZE_STYLES: Record<string, { fontSize: number; lineHeight?: number; fontWeight?: "400" | "500" | "600" | "700" }> = {
-  md: { fontSize: 16, lineHeight: 22 },
+const SIZE_STYLES: Record<
+  string,
+  {
+    fontSize: number;
+    lineHeight?: number;
+    fontWeight?: "400" | "500" | "600" | "700";
+  }
+> = {
+  md: { fontSize: 15, lineHeight: 21 },
   sm: { fontSize: 13, lineHeight: 16 },
 };
 
@@ -20,13 +27,16 @@ export function SnapText({
   const content = String(props.content ?? "");
   const size = String(props.size ?? "md");
   const weight = props.weight ? String(props.weight) : undefined;
-  const align = (props.align as "left" | "center" | "right" | undefined) ?? undefined;
+  const align =
+    (props.align as "left" | "center" | "right" | undefined) ?? undefined;
 
   const sizeStyle = SIZE_STYLES[size] ?? SIZE_STYLES.md;
   const resolvedWeight = weight ? WEIGHT_MAP[weight] : sizeStyle?.fontWeight;
-  const textAlign = align === "center" ? "center" : align === "right" ? "right" : "left";
+  const textAlign =
+    align === "center" ? "center" : align === "right" ? "right" : "left";
   const inHorizontalStack = useSnapStackDirection() === "horizontal";
-  const maxLines = typeof props.maxLines === "number" ? props.maxLines : undefined;
+  const maxLines =
+    typeof props.maxLines === "number" ? props.maxLines : undefined;
 
   return (
     <View style={inHorizontalStack ? styles.wrapRow : styles.wrapCol}>
diff --git a/pkgs/snap/src/react/components/image.tsx b/pkgs/snap/src/react/components/image.tsx
@@ -29,7 +29,7 @@ export function SnapImage({
       ratio={ratio}
       className={cn(
         "relative overflow-hidden rounded-lg",
-        inHorizontalStack ? "min-w-0 flex-1 basis-0" : "w-full",
+        inHorizontalStack ? "min-w-0 flex-1 basis-0" : "w-full"
       )}
     >
       {/* eslint-disable-next-line @next/next/no-img-element */}
@@ -39,14 +39,27 @@ export function SnapImage({
         className="absolute inset-0 size-full object-cover"
       />
       {hasOverlay && (
-        <div className="absolute inset-x-0 bottom-0 bg-gradient-to-t from-black/75 via-black/35 to-transparent p-3 pt-8 text-white">
+        <div className="absolute inset-x-0 bottom-0 bg-gradient-to-t from-black/70 via-black/35 to-transparent p-3 pt-10 text-white">
           {title && (
-            <div className="truncate text-sm font-semibold leading-5">
+            <div
+              className="truncate text-sm font-semibold leading-5"
+              style={{
+                textShadow:
+                  "0 1px 2px rgba(0,0,0,0.95), 0 0 3px rgba(0,0,0,0.9)",
+                WebkitTextStroke: "0.25px rgba(0,0,0,0.75)",
+              }}
+            >
               {title}
             </div>
           )}
           {subtitle && (
-            <div className="truncate text-xs font-medium leading-4 text-white/85">
+            <div
+              className="truncate text-xs font-medium leading-4 text-white/90"
+              style={{
+                textShadow:
+                  "0 1px 2px rgba(0,0,0,0.95), 0 0 3px rgba(0,0,0,0.9)",
+              }}
+            >
               {subtitle}
             </div>
           )}
diff --git a/pkgs/snap/src/react/components/item-group.tsx b/pkgs/snap/src/react/components/item-group.tsx
@@ -21,7 +21,10 @@ export function SnapItemGroup({
 }) {
   const border = Boolean(props.border);
   const separator = Boolean(props.separator);
-  const gap = GAP_MAP[String(props.gap ?? "sm")] ?? "gap-1";
+  const explicitGap =
+    typeof props.gap === "string" ? String(props.gap) : undefined;
+  const defaultGap = border || separator ? "sm" : "none";
+  const gap = GAP_MAP[explicitGap ?? defaultGap] ?? GAP_MAP[defaultGap]!;
   const items = Children.toArray(children);
   const colors = useSnapColors();
 
diff --git a/pkgs/snap/src/react/components/item.tsx b/pkgs/snap/src/react/components/item.tsx
@@ -73,7 +73,7 @@ export function SnapItem({
         "gap-2 py-1.5",
         inBorderedGroup ? "px-2" : "px-0",
         /** Horizontal: share width with peers. Vertical: don't fill column height. */
-        inHorizontalStack && "flex-1",
+        inHorizontalStack && "flex-1"
       )}
       style={{
         columnGap: 8,
@@ -111,7 +111,11 @@ export function SnapItem({
         </ItemMedia>
       )}
       <ItemContent className="gap-0">
-        <ItemTitle style={{ color: colors.text }}>{title}</ItemTitle>
+        <ItemTitle
+          style={{ color: colors.text, fontSize: 14, lineHeight: "19px" }}
+        >
+          {title}
+        </ItemTitle>
         {description && (
           <ItemDescription
             className="mt-0 text-xs leading-snug"
diff --git a/pkgs/snap/src/react/components/text.tsx b/pkgs/snap/src/react/components/text.tsx
