企业官网建设流程全解析

• 开发工具
• 版本控制

本指南以本仓库 modern-css 技能 的布局参考文档 layout.md 为骨架，系统讲解在 GitLens webview 及其组件体系中编写 Grid、Flex、尺寸与定位样式时应当遵循的现代默认。读完你将掌握容器查询、子网格（subgrid）、clamp()流体尺寸、逻辑属性、内在尺寸关键字、aspect-ratio、gap与place-*简写这九大特性的取舍逻辑与可复制的写法，并看到它们在 plus/graph 与 commitDetails 等真实模块中的落地形态。

layout.md 在 modern-css 技能体系中的位置

在动手写任何 CSS 之前，本仓库的 SKILL.md 要求先跑一遍"检测主线"：确定浏览器目标（VS Code 扩展路径下，有 web 入口点则目标为 Baseline "widely available"，纯桌面端则映射到 Electron 对应的 Chromium 版本）、确定 token 体系（显式--vscode-*/--gl-*，还是隐式尺度）、确定样式边界（shadow root 内部 / web component 消费者 / light DOM）。

当任务涉及"grid、flex、sizing 或 positioning"时，路由表会指向references/layout.md——这正是本文讨论的文档。它的定位是：结构层 CSS 的现代默认值集合，聚焦四件事：Grid、Flex、尺寸（sizing）与定位（positioning）。所有特性都以Baseline: widely available标注，意味着在项目检测出的目标环境中可以放心使用，不必降级到旧写法。

三大学科规则：先立规矩，再谈特性

layout.md 开篇给出三条贯穿始终的纪律，它们是后面所有特性的决策依据：

1. 优先使用内在尺寸（intrinsic sizing）：min-content、fit-content、clamp()优于写死的像素宽度。内容决定盒子，而不是预先定义好的固定盒子。
2. 默认使用逻辑属性（logical properties）：margin-inline: auto比margin-left: auto; margin-right: auto;更富表现力，padding-block: 1rem比padding-top: 1rem; padding-bottom: 1rem;更简洁。RTL 就绪只是附带收益，主要理由是可读性与简写能力。
3. 子元素间距优先用gap而不是 margin：gap同时适用于 grid 和 flex，多列（multicolumn）场景还能用column-gap。

这三条规则直接对应文末的六条反模式（见后文），是"现代默认"的落地形式。

九大现代布局特性详解

容器查询：组件级响应式

• Baseline：widely available
• 目的：让组件根据所在容器而非视口做响应式适配——组件只知道自己的容器，不该知道视口。
• 优于：在组件上使用视口媒体查询。
• 陷阱：父元素必须先设置container-type: inline-size（或size），@container才生效；同时这会建立一个新的包含块（containing block），绝对定位的后代会改以该元素为定位基准，可能破坏既有布局。

.card-wrapper { container-type: inline-size; } @container (min-width: 400px) { .card-body { flex-direction: row; } }

在 GitLens 的提交图 webview 中，这一特性被高频使用：例如 gitActionsButtons.ts 用命名容器@container graph-titlebar (min-width: 58rem)让标题栏在变宽时切换按钮密度，并在第 740 行设置container-type: inline-size、第 762 行用@container (max-width: 24rem)处理窄屏降级；gl-graph-feedback-dialog.ts 与 gl-graph-git-health.ts 同样在根上声明container-type: inline-size后分别用@container (max-width: 34rem)与@container (max-width: 44rem)做面板级响应；撰写模式面板 gl-details-compose-mode-panel.css.ts 与冲突解决模式 gl-details-resolve-mode-panel.ts 则用命名容器compose-actions/resolve-ready在宽度达到 44rem 时展开操作区。这些都不是视口查询，而是"面板有多大，就按多大排"的组件级响应式。

容器单位：相对容器而不是视口

• Baseline：widely available
• 目的：尺寸相对容器计算。cqw/cqh对应宽/高，cqi/cqb对应内联/块轴，cqmin/cqmax取cqi与cqb的较小/较大值。
• 优于：组件内部的视口单位（vw、vh）。

.card-title { font-size: clamp(1rem, 3cqi, 1.5rem); }

容器单位与clamp()天然配合：字体在容器的 3% 与上下限之间流体缩放，容器多大标题多大，与视口无关。

Subgrid：子网格对齐父网格轨道

• Baseline：widely available（文档标注 2026 年 3 月起）
• 目的：子网格直接对齐父网格的轨道，无需重复定义 track，也无需复杂的calc()对齐。
• 陷阱：父与子都必须display: grid；子元素必须通过grid-column/grid-row显式跨越它想继承的父轨道——没有显式跨轨，subgrid就没有可对齐的对象。

.parent { display: grid; grid-template-columns: 1fr 2fr 1fr; } .child { display: grid; grid-template-columns: subgrid; grid-column: span 3; }

clamp()：单表达式流体尺寸

• Baseline：widely available
• 目的：在一个表达式里同时给出最小值、首选值、最大值。
• 优于：用媒体查询阶梯式切换字号、宽度或间距。

font-size: clamp(1rem, 2vw + 0.5rem, 2rem);

2vw + 0.5rem这种"视口相关 + 基准"的混合写法是最常见形态；在容器语境下把vw换成cqi即可将流体基准从视口切换到容器。

逻辑属性：书写模式无关的尺寸与定位

• Baseline：widely available
• 目的：在 RTL、竖排书写模式与混排方向布局中自动正确。
• 优于：除非明确需要物理方向，否则不用left/right/top/bottom。

.card { margin-inline: auto; padding-block: 1rem; inset-inline: 0; border-inline-start: 3px solid var(--accent); }

GitLens webview 中逻辑属性已是常态：分支悬浮卡片 gl-branch-hover.css.ts 用margin-inline-start: auto把内容推向右端，access-account.ts 用inset-inline-start: 0定位图标，账号芯片 account-chip.ts 用margin-inline-start: auto做弹性分隔。结合仓库 webview-styling.md 的约定，GitLens 的--gl-*token 命名同样遵循语义化原则（如--gl-panel-padding-left/-right这类水平内边距 token）。

内在尺寸关键字：让内容决定盒子

• Baseline：widely available
• 目的：尺寸反映内容而非预定盒子：min-content、max-content、fit-content、auto。
• 优于：对流体内容写死像素宽度。

.tag { width: fit-content; } .grid { grid-template-columns: repeat(auto-fill, minmax(min(250px, 100%), 1fr)); }

第二行是经典的自适应网格：min(250px, 100%)保证在窄容器中不溢出，auto-fill+1fr自动填充尽可能多的列。GitLens 中 gl-details-commit-panel.css.ts 用fit-content(var(--_start-size, 25%))让详情面板在折叠/部分模式下按内容收缩、以百分比为上限，gl-details-compose-mode-panel.css.ts 用同样的fit-content(var(--_start-size, 50%))处理撰写面板，access-account.ts 也用block-size: fit-content让块高随内容自适应。

aspect-ratio：声明式保持比例

• Baseline：widely available
• 目的：声明式维持宽高比。
• 优于：padding-top: 56.25%这类 hack。

.video-wrapper { aspect-ratio: 16 / 9; } .avatar { aspect-ratio: 1; border-radius: 50%; }

GitLens 大量用它做头像与宣传图占位：账号芯片 account-chip.ts 用aspect-ratio: 1 / 1保证方形头像，access-account.ts 用aspect-ratio: 450 / 239承载入门视频缩略图、第 783 行用aspect-ratio: 200 / 88承载横向 logo 占位——比例即设计意图，写进 CSS 而不是靠魔法 padding。

gap：flex 与 grid 的子元素间距

• Baseline：widely available
• 目的：不需要 margin 调剂即可在子元素之间产生间距。
• 优于：子元素 margin +:last-child/:first-child清除。

.stack { display: flex; flex-direction: column; gap: 1rem; }

这是组件库中最常见的"纵向堆叠"抽象：一个 flex 列容器加一个gap，替代 N 条 margin 规则。

place-content / place-items / place-self：双轴简写

• Baseline：widely available
• 目的：align-*与justify-*的简写。一个值同时设置两轴；两个值先 align 后 justify。
• 优于：分别写align-*和justify-*。

.center-everything { display: grid; place-content: center; }

gl-graph-agent-sheet.ts 的 agent 面板就用place-items: center一次性完成主轴与交叉轴居中。

反模式清单：看到就改

layout.md 明确列出了本类别下应当避免的六种旧写法，正好与三大学科规则一一对应：

在 GitLens 仓库中的落地与约束

以上特性不是孤立的最佳实践，它们与本仓库的样式体系深度咬合：

• rem 基准：webview 根元素在 base.scss 设置font-size: 62.5%，即1rem = 10px（详见 webview-styling.md）。因此0.4rem = 4px、1.2rem = 12px，所有布局间距都应基于这一换算。
• token 体系：共享 token 定义在 tokens.scss，包括--gl-space-*间距坡度（0.2rem 起、以 0.2rem 为步进的 2/4/6/8/10/12/16/20/24/28/32/36/40 系列）、--gl-radius-*圆角、--gl-font-*字号与--gl-z-*语义化层级。写布局代码时优先引用这些 token，而不是硬编码数值。
• 边界纪律：SKILL.md 的 load-bearing rules 要求——shadow DOM 内部用:host与::part，消费者只用自定义属性 +::part+::slotted，不得从外部伸进 shadow 内部改布局；层级问题用isolation: isolate或语义层级 token 解决，而不是把原始 z-index 一路往上加。
• Baseline 维护：REFRESH.md 说明每个特性的 Baseline 状态是静态写入的，需在 VS Code 升级 Electron（带来新 Chromium）后按月复核，例如subgrid从newly available升为widely available这类迁移。

综合示例：一个 GitLens 风格的自适应卡片

把九大特性串起来，可以得到一个完全贴合本仓库约定的组件级响应卡片：

.card { container-type: inline-size; /* 建立容器查询上下文 */ display: grid; grid-template-columns: auto 1fr; /* 头像 + 内容 */ gap: var(--gl-space-8); aspect-ratio: 16 / 9; /* 或者不设，改用内在高度 */ padding-block: var(--gl-space-8); margin-inline: var(--gl-space-4); } .card-avatar { aspect-ratio: 1; border-radius: 50%; } .card-body { display: flex; flex-direction: column; gap: var(--gl-space-4); } .card-title { font-size: clamp(1.2rem, 3cqi, 1.4rem); /* 随容器而非视口缩放 */ } @container (min-width: 40rem) { .card-body { flex-direction: row; /* 容器变宽时切换排布 */ } }

要点回顾：容器查询取代视口媒体查询、gap取代 margin 调剂、aspect-ratio取代 padding hack、clamp()与容器单位实现流体尺寸、逻辑属性与--gl-space-*token 保证方向无关且与主题体系一致。这正是 layout.md 定义的"现代默认"在 GitLens 真实代码中的完整形态。

• 开发工具
• 版本控制