From 2a077d679075620a3a6afcf1e32cb5bdaefdc3b4 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 14 Jul 2026 23:08:32 +0000 Subject: [PATCH 1/3] =?UTF-8?q?docs:=20equal-height=20cards=20=E2=80=94=20?= =?UTF-8?q?Grid/Cell=20in=20the=20layout=20skill,=20Columns=20flex=20recip?= =?UTF-8?q?e?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes both gaps from #196: - The bestax-layout-scaffold skill never mentioned Grid/Cell and steered agents to Columns for all grids. layout-components.md gains a Grid/Cell section (props tables, auto-fill vs isFixed, card-grid snippet) that positions CSS Grid as preferred for uniform grids (equal heights free); SKILL.md's approach/checklist and the no-Tile note now steer Grid for uniform grids vs Columns for proportional layouts. - The equal-height recipe for Columns (Column display="flex" flexDirection="column" + Card flexGrow="1"; height:100% resolves against auto height and does nothing) is documented in the skill reference, the card-grid archetype, and the docs columns guide (live example); the grid guide notes the free equal heights. The skill's card-grid example now actually renders equal-height cards. Helper prop names verified against useFlexboxClasses (flexGrow is an ungated item property; display gates only container helpers). Closes #196 Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01Pohc8xLkdx4gwXkW3xd7up --- docs/docs/guides/library/columns.md | 32 ++++++++ docs/docs/guides/library/grid.md | 5 +- skills/bestax-layout-scaffold/SKILL.md | 11 ++- .../examples/card-grid.tsx | 7 ++ .../references/archetypes.md | 10 +++ .../references/layout-components.md | 76 ++++++++++++++++++- 6 files changed, 136 insertions(+), 5 deletions(-) diff --git a/docs/docs/guides/library/columns.md b/docs/docs/guides/library/columns.md index fc3b0cdcf..be3140ded 100644 --- a/docs/docs/guides/library/columns.md +++ b/docs/docs/guides/library/columns.md @@ -144,6 +144,38 @@ Offsets are useful for centering or right-aligning columns, but can cause layout ``` +**Equal-Height Cards** + +Columns themselves are equal height (flexbox), but a `Card` inside a `Column` ends at its own +content — and `height: 100%` on the card does nothing, because `100%` resolves against the +column's _auto_ height. Make the column a flex container and let the card grow: + +```tsx live + + + + Short blurb. + + + + + A much longer description that would normally make this card taller than + its neighbors — now they all match. + + + + + Medium-length blurb here. + + + +``` + +:::tip +For **uniform grids** of same-shaped cards, [`Grid`/`Cell`](./grid.md) gives equal-height cells +for free (CSS Grid stretches every cell to its row) — no flex recipe needed. +::: + [View full documentation.](../../api/columns/column) --- diff --git a/docs/docs/guides/library/grid.md b/docs/docs/guides/library/grid.md index ab59e6bbd..cf1544eac 100644 --- a/docs/docs/guides/library/grid.md +++ b/docs/docs/guides/library/grid.md @@ -15,7 +15,10 @@ This page summarizes the Bulma-styled grid system in Bestax, with a brief descri Provides Bulma's advanced CSS Grid layout for complex, modern layouts. Supports responsive and fixed grid modes, gap and min column controls, fixed column counts per breakpoint, and full color/background/utility helpers. Use with `Cell` for granular grid placement. :::info -Use `Grid` for advanced layouts where you need more control than Columns can provide. It supports both auto-fit and fixed column counts. +Use `Grid` for advanced layouts where you need more control than Columns can provide — and for +**uniform card grids**: CSS Grid keeps every cell in a row equal height for free, so cards line +up without the flex recipe [`Columns` needs](./columns.md#column). It supports both auto-fit +and fixed column counts. ::: ```tsx live diff --git a/skills/bestax-layout-scaffold/SKILL.md b/skills/bestax-layout-scaffold/SKILL.md index 026fdcd7e..5491d5573 100644 --- a/skills/bestax-layout-scaffold/SKILL.md +++ b/skills/bestax-layout-scaffold/SKILL.md @@ -36,8 +36,12 @@ Centered; a collection of items → Card grid. For mixed requests, pick the domi ## Approach - Compose pages from the shipped layout components — `Container`, `Section`, `Hero`, `Footer`, - `Level`, `Columns`/`Column`, `Navbar`, `Menu`, `Card`. There is **no `Tile` component** — build - grids with `Columns`/`Column`. + `Level`, `Columns`/`Column`, `Grid`/`Cell`, `Navbar`, `Menu`, `Card`. There is **no `Tile` + component**. For **uniform grids** (card grids, galleries — same-shaped items) prefer + `Grid`/`Cell`: CSS Grid gives equal-height cells for free. Use `Columns`/`Column` for + proportional or per-breakpoint column layouts — and when cards there must be equal height, + apply the flex recipe (`Column display="flex" flexDirection="column"` + `Card flexGrow="1"`; + `height: 100%` on the card does nothing). - Rely on Bulma's responsive defaults: `Columns` sit side by side on tablet and up and stack on mobile. Add responsive `size*` props only to tune the breakpoints. - For a `fixed="top"` `Navbar`, add the `has-navbar-fixed-top` class to `` so content is not @@ -74,7 +78,8 @@ color }}`. Set the app-wide icon library once with ``. - [ ] Do not use `Tile` — it is not shipped. - [ ] Style with helper props (`mt`/`p`, `textAlign`, `textColor`), not inline `style`. diff --git a/skills/bestax-layout-scaffold/examples/card-grid.tsx b/skills/bestax-layout-scaffold/examples/card-grid.tsx index ec5dca125..8d5556c66 100644 --- a/skills/bestax-layout-scaffold/examples/card-grid.tsx +++ b/skills/bestax-layout-scaffold/examples/card-grid.tsx @@ -1,6 +1,10 @@ // Card grid / catalog page — a collection of similar items. // `` wraps cards onto new rows; the responsive column sizes // give 1 card per row on mobile, 2 on tablet, 3 on desktop. +// Equal heights: each Column is a flex container and its Card grows to fill +// it (flexGrow="1"), so short blurbs don't leave ragged card bottoms. +// (`height: 100%` on the card would NOT work — it resolves against auto +// height. For uniform grids, Grid/Cell gives equal heights for free.) import React from 'react'; import { Section, @@ -78,8 +82,11 @@ export default function CatalogPage() { sizeMobile="full" sizeTablet="half" sizeDesktop="one-third" + display="flex" + flexDirection="column" > {item.price}} @@ -183,6 +186,13 @@ search results, "a grid of cards". **Responsive:** `isMultiline` wraps cards onto new rows; the `size*` props set the per-row count — 1 on mobile, 2 on tablet, 3 on desktop here. Change the fractions to change the column count. +**Equal heights:** the `display="flex" flexDirection="column"` on each `Column` plus +`flexGrow="1"` on the `Card` stretches every card to its row's height — without it, cards end +at their content and rows look ragged (`height: 100%` on the card does nothing). Alternatively +build the whole grid with `Grid`/`Cell` (``) — CSS Grid keeps cells equal-height for free; see the +`Grid / Cell` section in `layout-components.md`. + --- ## Combining archetypes diff --git a/skills/bestax-layout-scaffold/references/layout-components.md b/skills/bestax-layout-scaffold/references/layout-components.md index 1dc45b2ea..43d859e46 100644 --- a/skills/bestax-layout-scaffold/references/layout-components.md +++ b/skills/bestax-layout-scaffold/references/layout-components.md @@ -12,6 +12,8 @@ import { Level, Columns, Column, + Grid, + Cell, Navbar, Menu, Card, @@ -26,7 +28,9 @@ Every component also accepts the shared Bulma helper props (`m`/`p` spacing, `te > `textColor="grey"` / `bgColor="light"` not `style={{ color }}`. Spacing scale is `0`–`6` | `auto` > (`4` = 1rem). Reserve `style`/CSS vars only for values the design system doesn't tokenize. -> **There is no `Tile` component.** Build grids and nested layouts with `Columns` / `Column`. +> **There is no `Tile` component.** For uniform grids (cards, galleries) use `Grid` / `Cell` — +> equal-height cells for free; for proportional or per-breakpoint layouts use +> `Columns` / `Column`. ## Container @@ -127,6 +131,76 @@ type BulmaColumnSize = > Columns **stack on mobile** by default and go side-by-side at the tablet breakpoint and up. > Use the per-breakpoint `size*` props to control how many cells share a row at each width. +**Equal-height cards inside Columns** — columns are equal height, but a card inside one does +**not** stretch to fill it (and `height: 100%` on the card resolves against auto height, so it +does nothing). Make the `Column` a flex container and let the card grow: + +```tsx + + {items.map(item => ( + + {item.blurb} + + ))} + +``` + +`display`, `flexDirection`, and `flexGrow` are helper props every component accepts; +`flexGrow` takes a string (`"1"`). + +## Grid / Cell + +Bulma's CSS Grid. **Preferred for uniform grids** — same-shaped items in a repeating pattern +(card grids, galleries, dashboards): CSS Grid gives **equal-height cells for free**, with no +flex recipe needed. Reach for `Columns`/`Column` instead when you need proportional or +per-breakpoint column _sizes_ (a 2/3 + 1/3 split, different counts per breakpoint). + +**Grid** + +| Prop | Type | +| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | +| `gap` / `columnGap` / `rowGap` | `0`–`8` (number or string, same scale as Columns' `gap`) | +| `minCol` | `1`–`32` (smart grid: min column width step, `is-col-min-X`) | +| `isFixed` | `boolean` (fixed column count instead of auto-fill) | +| `fixedCols` (+ `fixedColsMobile` / `fixedColsTablet` / `fixedColsDesktop` / `fixedColsWidescreen` / `fixedColsFullhd`) | `0`–`12` or `'auto'` (fixed grid only) | + +**Cell** + +| Prop | Type | +| ------------------------------------- | --------------------------------------- | +| `colStart` / `colFromEnd` / `colSpan` | `number` (manual column placement/span) | +| `rowStart` / `rowFromEnd` / `rowSpan` | `number` (manual row placement/span) | + +By default the smart grid **auto-fills**: cells flow into as many columns as fit (tune the +minimum width with `minCol`). `isFixed` + `fixedCols*` pins an exact column count per +breakpoint instead. + +```tsx +// Uniform card grid — equal heights for free, responsive column count for free. + + {items.map(item => ( + + {item.blurb} + + ))} + +``` + +> To stretch each card to its cell's full (equal) height, the same `display="flex" +flexDirection="column"` + `flexGrow="1"` pattern applies to `Cell` + `Card`. + ## Navbar `` is the top bar. Subcomponents: `Navbar.Brand`, `Navbar.Item`, `Navbar.Link`, From 650262f3a2ba60493d8c69225332ee9d7ce0165c Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 14 Jul 2026 23:15:07 +0000 Subject: [PATCH 2/3] docs: soften the height-100% claim per review Percentage heights can resolve when the flex item has a definite size; the guidance now says it doesn't help here (auto-height column) and positions flexGrow as the robust pattern. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01Pohc8xLkdx4gwXkW3xd7up --- docs/docs/guides/library/columns.md | 5 +++-- skills/bestax-layout-scaffold/SKILL.md | 2 +- skills/bestax-layout-scaffold/references/archetypes.md | 3 ++- .../bestax-layout-scaffold/references/layout-components.md | 4 ++-- 4 files changed, 8 insertions(+), 6 deletions(-) diff --git a/docs/docs/guides/library/columns.md b/docs/docs/guides/library/columns.md index be3140ded..10ed6f703 100644 --- a/docs/docs/guides/library/columns.md +++ b/docs/docs/guides/library/columns.md @@ -147,8 +147,9 @@ Offsets are useful for centering or right-aligning columns, but can cause layout **Equal-Height Cards** Columns themselves are equal height (flexbox), but a `Card` inside a `Column` ends at its own -content — and `height: 100%` on the card does nothing, because `100%` resolves against the -column's _auto_ height. Make the column a flex container and let the card grow: +content — and `height: 100%` on the card doesn't help here, because `100%` resolves against +the column's _auto_ height (percentage heights only resolve against a definite size). The +robust pattern: make the column a flex container and let the card grow: ```tsx live diff --git a/skills/bestax-layout-scaffold/SKILL.md b/skills/bestax-layout-scaffold/SKILL.md index 5491d5573..c39188dd2 100644 --- a/skills/bestax-layout-scaffold/SKILL.md +++ b/skills/bestax-layout-scaffold/SKILL.md @@ -41,7 +41,7 @@ Centered; a collection of items → Card grid. For mixed requests, pick the domi `Grid`/`Cell`: CSS Grid gives equal-height cells for free. Use `Columns`/`Column` for proportional or per-breakpoint column layouts — and when cards there must be equal height, apply the flex recipe (`Column display="flex" flexDirection="column"` + `Card flexGrow="1"`; - `height: 100%` on the card does nothing). + `height: 100%` on the card doesn't help — the column's height is auto). - Rely on Bulma's responsive defaults: `Columns` sit side by side on tablet and up and stack on mobile. Add responsive `size*` props only to tune the breakpoints. - For a `fixed="top"` `Navbar`, add the `has-navbar-fixed-top` class to `` so content is not diff --git a/skills/bestax-layout-scaffold/references/archetypes.md b/skills/bestax-layout-scaffold/references/archetypes.md index 14171558a..7ab7ab2c3 100644 --- a/skills/bestax-layout-scaffold/references/archetypes.md +++ b/skills/bestax-layout-scaffold/references/archetypes.md @@ -188,7 +188,8 @@ search results, "a grid of cards". **Equal heights:** the `display="flex" flexDirection="column"` on each `Column` plus `flexGrow="1"` on the `Card` stretches every card to its row's height — without it, cards end -at their content and rows look ragged (`height: 100%` on the card does nothing). Alternatively +at their content and rows look ragged (`height: 100%` on the card doesn't help — it resolves +against the column's auto height). Alternatively build the whole grid with `Grid`/`Cell` (``) — CSS Grid keeps cells equal-height for free; see the `Grid / Cell` section in `layout-components.md`. diff --git a/skills/bestax-layout-scaffold/references/layout-components.md b/skills/bestax-layout-scaffold/references/layout-components.md index 43d859e46..8163ddf19 100644 --- a/skills/bestax-layout-scaffold/references/layout-components.md +++ b/skills/bestax-layout-scaffold/references/layout-components.md @@ -132,8 +132,8 @@ type BulmaColumnSize = > Use the per-breakpoint `size*` props to control how many cells share a row at each width. **Equal-height cards inside Columns** — columns are equal height, but a card inside one does -**not** stretch to fill it (and `height: 100%` on the card resolves against auto height, so it -does nothing). Make the `Column` a flex container and let the card grow: +**not** stretch to fill it (and `height: 100%` on the card doesn't help — it resolves against +the column's auto height). Make the `Column` a flex container and let the card grow: ```tsx From 2fe014caa48d47462026eda5afbe96d97c111d62 Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 14 Jul 2026 23:20:47 +0000 Subject: [PATCH 3/3] docs: equal heights are per row; align checklist with approach wording MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CodeRabbit's two follow-ups: (1) checklist now says proportional OR per-breakpoint, matching the approach rule; (2) the equal-heights-free claim is scoped per row — each row's cells match its tallest. The suggested redirect to the flex recipe for cross-row uniformity was declined: flex lines stretch independently too, so both approaches are row-level; the docs now say so explicitly. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01Pohc8xLkdx4gwXkW3xd7up --- docs/docs/guides/library/columns.md | 3 ++- docs/docs/guides/library/grid.md | 4 ++-- skills/bestax-layout-scaffold/SKILL.md | 8 +++++--- .../references/layout-components.md | 4 ++-- 4 files changed, 11 insertions(+), 8 deletions(-) diff --git a/docs/docs/guides/library/columns.md b/docs/docs/guides/library/columns.md index 10ed6f703..7eff0a8a8 100644 --- a/docs/docs/guides/library/columns.md +++ b/docs/docs/guides/library/columns.md @@ -174,7 +174,8 @@ robust pattern: make the column a flex container and let the card grow: :::tip For **uniform grids** of same-shaped cards, [`Grid`/`Cell`](./grid.md) gives equal-height cells -for free (CSS Grid stretches every cell to its row) — no flex recipe needed. +for free (CSS Grid stretches every cell to its row's height) — no flex recipe needed. Both +approaches equalize per row: cards match their own row's tallest card. ::: [View full documentation.](../../api/columns/column) diff --git a/docs/docs/guides/library/grid.md b/docs/docs/guides/library/grid.md index cf1544eac..eae28ba34 100644 --- a/docs/docs/guides/library/grid.md +++ b/docs/docs/guides/library/grid.md @@ -16,8 +16,8 @@ Provides Bulma's advanced CSS Grid layout for complex, modern layouts. Supports :::info Use `Grid` for advanced layouts where you need more control than Columns can provide — and for -**uniform card grids**: CSS Grid keeps every cell in a row equal height for free, so cards line -up without the flex recipe [`Columns` needs](./columns.md#column). It supports both auto-fit +**uniform card grids**: CSS Grid keeps every cell in a row equal height for free (each row +matches its tallest cell), so cards line up without the flex recipe [`Columns` needs](./columns.md#column). It supports both auto-fit and fixed column counts. ::: diff --git a/skills/bestax-layout-scaffold/SKILL.md b/skills/bestax-layout-scaffold/SKILL.md index c39188dd2..e66843603 100644 --- a/skills/bestax-layout-scaffold/SKILL.md +++ b/skills/bestax-layout-scaffold/SKILL.md @@ -38,7 +38,8 @@ Centered; a collection of items → Card grid. For mixed requests, pick the domi - Compose pages from the shipped layout components — `Container`, `Section`, `Hero`, `Footer`, `Level`, `Columns`/`Column`, `Grid`/`Cell`, `Navbar`, `Menu`, `Card`. There is **no `Tile` component**. For **uniform grids** (card grids, galleries — same-shaped items) prefer - `Grid`/`Cell`: CSS Grid gives equal-height cells for free. Use `Columns`/`Column` for + `Grid`/`Cell`: CSS Grid gives equal-height cells for free (per row — each row's cells match + its tallest, same row-level behavior as the flex recipe). Use `Columns`/`Column` for proportional or per-breakpoint column layouts — and when cards there must be equal height, apply the flex recipe (`Column display="flex" flexDirection="column"` + `Card flexGrow="1"`; `height: 100%` on the card doesn't help — the column's height is auto). @@ -78,8 +79,9 @@ color }}`. Set the app-wide icon library once with ``. - [ ] Do not use `Tile` — it is not shipped. - [ ] Style with helper props (`mt`/`p`, `textAlign`, `textColor`), not inline `style`. diff --git a/skills/bestax-layout-scaffold/references/layout-components.md b/skills/bestax-layout-scaffold/references/layout-components.md index 8163ddf19..5a845e3ec 100644 --- a/skills/bestax-layout-scaffold/references/layout-components.md +++ b/skills/bestax-layout-scaffold/references/layout-components.md @@ -157,8 +157,8 @@ the column's auto height). Make the `Column` a flex container and let the card g ## Grid / Cell Bulma's CSS Grid. **Preferred for uniform grids** — same-shaped items in a repeating pattern -(card grids, galleries, dashboards): CSS Grid gives **equal-height cells for free**, with no -flex recipe needed. Reach for `Columns`/`Column` instead when you need proportional or +(card grids, galleries, dashboards): CSS Grid gives **equal-height cells for free** (per row — +each row's cells match its tallest), with no flex recipe needed. Reach for `Columns`/`Column` instead when you need proportional or per-breakpoint column _sizes_ (a 2/3 + 1/3 split, different counts per breakpoint). **Grid**