docs(snap): vertical stacks should default justify (omit it)

.changeset/quick-jars-retire.md

@@ -0,0 +1,5 @@
+---
+"@farcaster/snap": patch
+---
+
+docs(snap): clarify that vertical stacks should default `justify` (omit it). The shipped `llms.txt` and SKILL.md now steer agents toward the implicit `start` packing for content columns and reserve `justify: "between"` / `"around"` / `"evenly"` for cases that genuinely need children pushed to edges (e.g. a horizontal Back/Next nav row). Surfaces the foot-gun where `justify: "between"` on a vertical column peered with a tall image spreads children across empty column height rather than packing at the top.

apps/docs/public/2.0/SKILL.md

@@ -106,6 +106,15 @@ Design guidance:
   `"row,col"`); OR set `select: "single"` / `"multiple"` for press-to-select with a
   visual ring and pair with a separate submit `button`. Don't combine `on.press` with a
   non-`off` `select` — `on.press` is ignored when `select` is on.
+- **Default `justify` (omit it) on vertical stacks.** Omitting `justify` packs children
+  at the top with their `gap` — almost always what you want for content. Only set
+  `justify: "between"` / `"around"` / `"evenly"` when you specifically want children
+  pushed to edges (a horizontal nav row with Back on the left and Next on the right is
+  the canonical case; a content column is not). On a vertical column whose row peer is
+  taller (e.g. an image), a distributing `justify` spreads the children across the column
+  height — which reads as awkward empty space rather than as designed layout. If a list
+  of items looks weirdly spread top-to-bottom, the first thing to check is whether
+  `justify` was set on the column.
 - **Stack `gap` defaults are column-aware** for horizontal stacks: 2 cols → `"lg"`
   (16px), 3 cols → `"md"` (8px), 4+ cols → `"sm"` (4px). Vertical stacks default to
   `"md"` (16px). Trust the default first — don't set `gap` on a horizontal stack just

apps/docs/public/SKILL.md

@@ -106,6 +106,15 @@ Design guidance:
   `"row,col"`); OR set `select: "single"` / `"multiple"` for press-to-select with a
   visual ring and pair with a separate submit `button`. Don't combine `on.press` with a
   non-`off` `select` — `on.press` is ignored when `select` is on.
+- **Default `justify` (omit it) on vertical stacks.** Omitting `justify` packs children
+  at the top with their `gap` — almost always what you want for content. Only set
+  `justify: "between"` / `"around"` / `"evenly"` when you specifically want children
+  pushed to edges (a horizontal nav row with Back on the left and Next on the right is
+  the canonical case; a content column is not). On a vertical column whose row peer is
+  taller (e.g. an image), a distributing `justify` spreads the children across the column
+  height — which reads as awkward empty space rather than as designed layout. If a list
+  of items looks weirdly spread top-to-bottom, the first thing to check is whether
+  `justify` was set on the column.
 - **Stack `gap` defaults are column-aware** for horizontal stacks: 2 cols → `"lg"`
   (16px), 3 cols → `"md"` (8px), 4+ cols → `"sm"` (4px). Vertical stacks default to
   `"md"` (16px). Trust the default first — don't set `gap` on a horizontal stack just

apps/docs/public/llms.txt

@@ -106,7 +106,7 @@ Top-level fields: `version` (required, `"1.0"` or `"2.0"`), `theme` (optional, `
 **stack** — Layout container.
 - `direction` (optional): `"vertical"` | `"horizontal"`. Default: `"vertical"`
 - `gap` (optional): `"none"` | `"sm"` | `"md"` | `"lg"`. Vertical px: 0/8/16/24. Horizontal px: 0/4/8/16 (tighter, since children sit side-by-side). Default for vertical: `"md"`. Default for horizontal is column-aware: 2 cols → `"lg"` (16px), 3 cols → `"md"` (8px), 4+ cols → `"sm"` (4px), unknown → `"md"` (8px). An explicit value always wins — override the default when you have a deliberate visual reason (e.g. tighter toolbar, extra breathing room around a hero row).
-- `justify` (optional): `"start"` | `"center"` | `"end"` | `"between"` | `"around"`
+- `justify` (optional): `"start"` | `"center"` | `"end"` | `"between"` | `"around"`. Default behavior (omit) packs children at the start of the main axis with their `gap` — this is almost always correct for vertical content columns. Only use a distributing value (`"between"` / `"around"` / `"evenly"`) when you explicitly want children pushed to edges (a horizontal nav row with Back/Next is the canonical case). Setting `justify: "between"` on a vertical column whose row peer is taller (e.g. an image) will spread children across the empty column height — reads as awkward, not designed.
 - `columns` (optional, horizontal only): `2`–`6` — CSS grid with equal columns (mixed children or layout that needs fixed column counts).
 - Children are element IDs
 

pkgs/snap/llms.txt

@@ -106,7 +106,7 @@ Top-level fields: `version` (required, `"1.0"` or `"2.0"`), `theme` (optional, `
 **stack** — Layout container.
 - `direction` (optional): `"vertical"` | `"horizontal"`. Default: `"vertical"`
 - `gap` (optional): `"none"` | `"sm"` | `"md"` | `"lg"`. Vertical px: 0/8/16/24. Horizontal px: 0/4/8/16 (tighter, since children sit side-by-side). Default for vertical: `"md"`. Default for horizontal is column-aware: 2 cols → `"lg"` (16px), 3 cols → `"md"` (8px), 4+ cols → `"sm"` (4px), unknown → `"md"` (8px). An explicit value always wins — override the default when you have a deliberate visual reason (e.g. tighter toolbar, extra breathing room around a hero row).
-- `justify` (optional): `"start"` | `"center"` | `"end"` | `"between"` | `"around"`
+- `justify` (optional): `"start"` | `"center"` | `"end"` | `"between"` | `"around"`. Default behavior (omit) packs children at the start of the main axis with their `gap` — this is almost always correct for vertical content columns. Only use a distributing value (`"between"` / `"around"` / `"evenly"`) when you explicitly want children pushed to edges (a horizontal nav row with Back/Next is the canonical case). Setting `justify: "between"` on a vertical column whose row peer is taller (e.g. an image) will spread children across the empty column height — reads as awkward, not designed.
 - `columns` (optional, horizontal only): `2`–`6` — CSS grid with equal columns (mixed children or layout that needs fixed column counts).
 - Children are element IDs