Communitygithub.com

coastdigitalgroup/coastai-skills

设计并实现一个系统化的多列瀑布流网格布局框架,用于紧密排列可变高度的内容卡片,消除垂直间隙,同时保持严格的视觉层次、逻辑阅读和焦点顺序以及 WCAG AA 无障碍标准。

coastai-skills 是什么?

该技能提供了一个标准化的响应式设计框架,专门用于解决瀑布流布局的核心挑战:将非均匀、可变高度的内容卡片(如摄影作品集、用户生成内容流、混合媒体卡片或编辑类视觉发现面板)紧凑地排列到平行的垂直列中。它详细阐述了三种主要的架构策略:纯 CSS 多列布局(`column-count`)、CSS Grid 行跨度布局(`grid-auto-rows`)和 JavaScript 最短列容器分发。每种策略都有其特定的适用场景、实现细节和权衡,开发者可以根据内容的交互性和阅读顺序要求进行选择。该技能还深入涵盖了防止累积布局偏移 (CLS) 的关键技术,例如使用宽高比盒子、骨架占位符和图片加载监听器。在无障碍方面,它重点解决了 WCAG 2.1 AA 标准中的关键问题,特别是如何协调视觉布局和键盘焦点导航顺序,防止在交互式卡片中出现“键盘 Tab 跳跃”问题。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/coastdigitalgroup/coastai-skills/tree/HEAD/website-design/masonry-grid-layout-system

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

瀑布流网格布局系统

目的

瀑布流网格布局系统提供了一个标准化的响应式设计框架,用于展示非均匀、可变高度的内容卡片(例如摄影作品集、用户生成内容流、混合媒体卡片或编辑类的视觉发现面板)。标准的 CSS Grid 布局强制行高对齐,当项目具有不同的宽高比或文本长度时,会产生尴尬的垂直空白间隙。

设计一个有效的瀑布流网格需要解决以下空间挑战:将项目动态地打包到平行的垂直列中,防止媒体资源加载时出现累积布局偏移 (CLS),确保移动端优雅的列数缩减,并且——最关键的是——防止视觉布局破坏逻辑 DOM 阅读顺序和键盘焦点导航顺序(WCAG 2.1 SC 1.3.2 和 SC 2.1.1)。

用例

  • 摄影与视觉媒体作品集: 以紧凑、无间隙的网格展示具有不同原生宽高比(竖屏、横屏、方形、全景)的图片画廊。
  • 社交与 UGC 动态流: 组织包含短文本更新、长篇文章、嵌入图片和视频预告片的混合社交卡片。
  • 电商 UGC 与评论墙: 以动态发现展示厅的形式呈现客户评论照片、标记的 Instagram 帖子以及产品亮点片段。
  • 编辑类发现与钉板: 构建情绪板、书签管理器和灵感流,其中的卡片包含具有可变垂直高度的多样化内容元素。

何时不使用

  • 统一宽高比网格: 如果所有项目共享相同的宽高比(例如,标准的 16:9 视频卡片或 1:1 产品目录),请使用 responsive-grid-system 或 card-ui-system。
  • 结构化二维不对称高亮区: 对于具有明确二维矩形跨区规则的精选英雄区域(例如,一个 2x2 的主要特色区域加上几个 1x1 的统计块),请使用 bento-grid-layout-system。
  • 严格的表格或对齐数据: 当用户需要跨水平行比较值时(例如,定价表或财务指标),请使用 data-table-ui-system 或 comparison-matrix-system。
  • 顺序叙述与文章: 对于阅读顺序必须严格遵循单一垂直流的线性叙述,请使用 article-layout-system 或 section-composition-system。

输入

  1. 内容清单与宽高比: 媒体和文本内容的类型(图片、视频、文本片段、操作卡片)及其宽高比范围(从 3:4 竖屏到 16:9 横屏)。
  2. 列架构要求: 不同屏幕尺寸下的目标列数(例如,宽屏桌面端 4 列,桌面端 3 列,平板 2 列,手机端 1 列)。
  3. 交互性与焦点要求: 卡片内需要键盘无障碍访问的交互元素(按钮、灯箱、内联切换开关、链接)。
  4. 空间与主题令牌: 灵活的列间距和行间距(gap: clamp(12px, 2vw, 24px))、卡片背景填充、圆角和焦点环令牌(来自 fluid-spacing-system 和 focus-indicator-design-system)。

输出

  1. 瀑布流布局架构规范: 在纯 CSS 多列流、CSS Grid 行跨度(grid-auto-rows)和 JavaScript 最短列填充之间的策略选择和技术蓝图。
  2. 响应式列缩放矩阵: 用于平滑列数过渡和间距缩放的断点定义。
  3. DOM 阅读顺序与键盘焦点映射: 确保键盘导航(Tab / Shift+Tab)遵循自然的视觉阅读顺序,避免混乱的列跳跃的架构。
  4. 布局稳定性与宽高比保留规则: 防止图片和媒体加载期间出现累积布局偏移 (CLS) 的 CSS 架构。

工作流程

1. 选择架构策略

根据交互性和阅读顺序要求选择合适的布局技术:

  • 选项 A:纯 CSS 多列布局 (column-count)
    • 最佳适用于: 静态画廊、图片密集的动态流或非交互式卡片,其流顺序可以是垂直方向先填充第 1 列,然后是第 2 列,依此类推。
    • 实现: column-count: 4; column-gap: var(--space-m);。在子卡片上设置 break-inside: avoid; margin-bottom: var(--space-m);。
    • 权衡: 垂直源顺序(列内从上到下)可能会混淆键盘用户,特别是当卡片包含交互式控件时。
  • 选项 B:带行跨度的 CSS Grid (grid-auto-rows & grid-row: span X)
    • 最佳适用于: 半静态网格,其中卡片高度步长可以量化为固定的行轨道单位(例如,10px 基础轨道)。
    • 实现: display: grid; grid-template-columns: repeat(auto-fill, minmax(280px, 1fr)); grid-auto-rows: 10px; gap: 16px;。JavaScript 计算内容高度并应用 grid-row: span Math.ceil(height / trackHeight)。
    • 权衡: 保留了原生的水平 DOM 顺序,但需要少量的 JS 高度计算或容器查询。
  • 选项 C:JavaScript 最短列容器分发
    • 最佳适用于: 高度交互的混合媒体流,其中从左到右的阅读顺序至关重要,且卡片包含链接、按钮和表单控件。
    • 实现: 创建 $N$ 个弹性列容器(display: flex; flex-direction: column; gap: var(--space-m);)。将新传入的卡片追加到当前总渲染高度最短的列中。
    • 权衡: 需要客户端 DOM 容器管理,但保证了完美的从左到右 DOM 焦点流和零视觉垂直间隙。

2. 定义空间节奏与列间距

在所有列和卡片内边距之间建立一致的间距令牌:

  • 列间距: 使用灵活的间隙间距(例如 gap: clamp(16px, 2.5vw, 28px))。确保堆叠卡片之间的垂直间隙等于水平列间隙,以保持均匀的空间密度。
  • 卡片内边距与内部对齐: 使用流体令牌标准化内部卡片内边距(padding: var(--space-m))。对于纯媒体卡片(例如灯箱触发器),允许图片边缘对齐(padding: 0; overflow: hidden;)。
  • 圆角同步: 对外部卡片容器应用一致的圆角(例如 12px 到 16px)。确保内部元素(例如顶部图片)继承同心圆角(border-top-left-radius: calc(var(--card-radius) - 1px))。

3. 防止布局偏移 (CLS) 和图片失真

瀑布流网格在图片加载期间非常容易出现累积布局偏移:

  • 宽高比盒子: 在图片容器上显式声明 aspect-ratio(aspect-ratio: 4 / 5; object-fit: cover; width: 100%; display: block;),或者在媒体加载完成前计算内联的内边距比率。
  • 骨架占位符: 在远程资源加载时,渲染与预期卡片宽高比匹配的带样式的骨架背景脉冲(background: var(--surface-subtle); animation: pulse 1.5s infinite;)。
  • 图片加载监听器: 如果使用 JS 高度计算,请绑定 ResizeObserver 或图片 load 事件监听器,以便在图片渲染完成后重新计算列高度分配。

4. 协调 DOM 阅读顺序与焦点管理

确保符合 WCAG 1.3.2(有意义的顺序)和 2.1.1(键盘):

  • 避免视觉-DOM 脱节: 如果使用 CSS Columns 且视觉布局垂直向下排列,请确保键盘焦点指示器保持清晰和逻辑。如果卡片包含交互式控件,最好使用 JavaScript 最短列分发或 CSS Grid 行跨度来维持自然的从左到右、从上到下的标签页顺序(Tab 键顺序)。
  • 焦点指示器可见性: 标准化高对比度、未裁剪的焦点指示器(outline: 3px solid var(--focus-ring-color); outline-offset: 3px;)。如果未在裁剪边界内添加足够的焦点指示器内边距,则避免在卡片上使用 overflow: hidden。
  • 灯箱/模态框的键盘快捷键: 如果点击瀑布流卡片会打开模态覆盖层或灯箱,请将键盘焦点限制在覆盖层内(focus-trap),并在关闭后(Escape 键)将焦点返回到触发卡片的起始元素。

5. 实现响应式列缩放

设计断点,以便在不破坏内容平衡的情况下优雅地缩放列数:

  • 宽屏桌面端 (≥ 1440px): 4 列(column-count: 4 或 4 个弹性列轨道)。
  • 标准桌面端 (1024px – 1439px): 3 列(column-count: 3 或 3 个弹性列轨道)。
  • 平板/小屏幕 (640px – 1023px): 2 列(column-count: 2 或 2 个弹性列轨道)。
  • 手机端 (< 640px): 1 列(column-count: 1 或单个垂直堆叠)。所有项目自然地以标准垂直间距堆叠。

决策规则

架构选择矩阵

内容与交互类型推荐架构策略理由
纯图片画廊(灯箱触发器)CSS 多列 (column-count)零 JS 体积,原生浏览器多列性能,干净的垂直图片瀑布流。
交互式卡片(按钮、输入框、链接)JS 最短列弹性分发保留严格的从左到右 DOM 标签页顺序,防止屏幕阅读器和键盘焦点跳跃。
动态加载流(无限滚动)CSS Grid 行跨度或 JS 列分发允许将新卡片平滑地追加到最短的列中,而无需重排整个页面布局。
文本密集型编辑类钉板CSS Grid 行跨度 (grid-auto-rows: 10px)在保持水平阅读顺序的同时,精确适应可变的文本长度。

约束

  • 无障碍(WCAG 2.1 AA 合规性):
    • SC 1.3.2 有意义的顺序: 交互式卡片的视觉排列必须与键盘标签页导航顺序(tabindex="0" 焦点流)逻辑上对齐。
    • SC 1.4.3 对比度(最低): 在卡片表面或图片覆盖层上渲染的文本必须满足至少 4.5:1 的对比度。对于直接放在图片上的文本,必须使用深色遮罩覆盖层(background: linear-gradient(to top, rgba(0,0,0,0.8), transparent))。
    • SC 2.1.1 键盘: 所有交互式卡片元素(如按钮、收藏触发器、外部链接)必须完全能够通过 Space 和 Enter 键操作。
    • SC 2.4.7 焦点可见: 交互式卡片和触发器必须显示一个清晰的焦点环,该焦点环不会被父卡片 overflow: hidden 属性裁剪。
    • SC 2.5.8 目标尺寸: 瀑布流卡片内的所有触摸目标必须保持至少 24x24px 的交互区域(在触摸屏/手机视口上至少为 44x44px)。
  • 布局偏移性能: 瀑布流卡片内的图片必须具有明确定义的内在宽高比或尺寸预留,以保证 CLS 保持在 0.1 以下。

常见失败模式

  • 键盘 Tab 跳跃混乱: 对交互式卡片使用 CSS column-count,导致键盘 Tab 键垂直移动遍历整个第一列(从项目 1 到项目 10),然后才跳回到第 2 列的顶部。
  • 累积布局偏移 (CLS) 混乱: 插入没有宽高比样式或加载骨架的图片,导致瀑布流列在每张图片加载时反复重排和跳跃。
  • 裁剪的焦点环: 在瀑布流卡片上设置 overflow: hidden 以强制实现圆角图片,但这会裁剪掉内部交互元素的标准轮廓焦点环。
  • 移动端未约束的列高: 未能在移动设备上将瀑布流网格折叠为单列,导致出现超窄、挤压的多列卡片,文本换行难以阅读。
  • 不均匀的列计数: 在动态流中顺序跨列追加新项目(1, 2, 3, 1, 2, 3),而不是检查列高,导致在较短的列底部出现巨大的垂直空白区域。

验证标准

  • 架构对齐: 选定的策略(CSS Columns vs. CSS Grid 行跨度 vs. JS 最短列)与卡片交互性要求匹配。
  • 零意外垂直间隙: 卡片紧密排列,没有水平行对齐的空白间隙。
  • 键盘 Tab 导航: 交互式卡片遵循逻辑的视觉标签顺序(从左到右,从上到下)。
  • 布局偏移预防: 宽高比或骨架容器在远程媒体加载时防止 CLS(<0.1)。
  • 响应式断点适配: 网格从宽屏桌面端的 4 列平滑缩放到手机端(<640px)的单个垂直列。
  • WCAG AA 合规性: 所有文本满足 ≥4.5:1 对比度,触摸目标满足 ≥24x24px(手机端 ≥44x44px),焦点环未裁剪且清晰可见。

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for progressive disclosure using accordions, ensuring structural integrity, visual affordances, and accessibility across different content densities and devices.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for long-form content, managing readability, vertical rhythm, and information density to ensure a superior reading experience.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for informational elements that communicate state (Badges) and categorization (Tags) with clarity and accessibility.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for non-overlay notifications, managing global announcements and contextual inline alerts to communicate system states without interrupting the user's flow.

coastdigitalgroup/coastai-skills

Design and implement a systematic, asymmetrical bento-grid layout framework to organize diverse content types cohesively while maintaining strict visual hierarchy, logical focus order, and responsive flexibility.

coastdigitalgroup/coastai-skills

Design a responsive, mobile-first bottom navigation bar and persistent action dock system for mobile websites and web applications, establishing spatial anchors, tab bar anatomy, badge indicators, thumb-zone ergonomics, safe area inset handling, active/inactive state contrast, and desktop responsive adaptation rules.

coastdigitalgroup/coastai-skills

Design a mobile-first bottom sheet overlay system with configurable detents, drag affordances, safe area padding, responsive desktop modal/popover adaptation, and WCAG AA accessibility compliance.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for secondary navigation trails that provide orientation, context, and one-click access to parent levels in deep information architectures.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for buttons and interactive triggers, managing visual hierarchy, variant logic, and action grouping to ensure clear intent and accessible interaction.

coastdigitalgroup/coastai-skills

Design a systematic framework for date and time selection, managing calendar grids, range pickers, and scheduling interfaces to ensure precision and accessibility.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for modular content containers that maintain hierarchy, structural integrity, and action alignment across variable content and responsive viewports.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for horizontal discovery components, managing navigation affordances, scroll behavior, and accessibility to ensure effective content density without compromising usability.

coastdigitalgroup/coastai-skills

Design a systematic, highly accessible, and developer-friendly UI layout framework for code blocks, snippet showcases, multi-file code tabs, line-highlighting, diff views, and syntax token contrast in technical documentation and developer platforms.

coastdigitalgroup/coastai-skills

Design a systematic framework for global command menus (Cmd+K panels) that combines keyboard-driven navigation, command execution, and shortcut discovery into an accessible, responsive overlay.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for threaded conversations, managing nesting depths, action hierarchies, and community signaling to foster engagement and readability.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for side-by-side comparison interfaces, managing high attribute density and responsive complexity to support informed decision-making.

coastdigitalgroup/coastai-skills

Design and implement a systematic framework for user privacy, managing consent banners, preference centers, and persistent privacy controls to balance legal compliance with user trust.

coastdigitalgroup/coastai-skills

Design and implement a systematic, highly accessible, and responsive visual layout framework for conversational chat widgets, live chat boxes, and chatbot panels that ensures clear message scannability, native focus flow, and seamless mobile keyboard adaptation.

coastdigitalgroup/coastai-skills

Design a systematic, accessible, and high-conversion framework for custom select dropdowns and comboboxes, defining anatomy, states, search-filtering, and responsive mobile-adaptive patterns.

coastdigitalgroup/coastai-skills

Design and implement a systematic color palette that ensures WCAG 2.2 accessibility compliance. Trigger this skill when asked to define brand colors, create UI themes, or establish a visual system for a website.

相关技能