Files
marqdo/doc/design/ext-web-customization/02-shell-css.md
T
cflmyandCursor 155183eb30 feat(web): C2 shell_css modes and page layout presets
Split injected shell CSS into vars/layout/widgets with full|minimal|off, add stacked/bare/rail layouts, and stop forcing has-sidebar when authors opt out.

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-09-04 12:48:50 +08:00

2.4 KiB
Raw Blame History

解决 2:SHELL_CSS 可关 / 可分层

问题 研究 §2
优先级 P1 · 波次 C2
触点 plugins/web/src/render.rs(SHELL_CSS、<style> 拼接)· page/app 元数据 · ext/web 样式装配

1. 目标

  1. 站点主题可选择:不要框架栅格/卡片默认,或只要 reset 级变量。
  2. 壳 CSS 与主题 CSS 的级联顺序可声明、可文档化。
  3. 默认仍注入完整壳(兼容旧站);新主题显式 shell_css=off 即可干净起步。

2. 作者 API(草案)

*应用 = > web.app page=`首页` … shell_css="minimal"*
# 或页面级覆盖
*页 = > `页`.meta …*   # 或 page 选项 shell_css=
值 行为
full(默认) 现网 SHELL_CSS 全文
minimal 仅 :root 变量 + body margin/字体;不含 has-sidebar 双列栅格与卡片表单皮肤
off / none 不注入框架壳样式;只输出站点 style / 外链 CSS

级联顺序锁定为文档约定:

  1. (可选)框架 SHELL_CSS
  2. 站点全局 style 表 / site.css
  3. 页面级 style

禁止再出现「主题写在 extra,却被同特异性壳规则在小屏打穿且无媒体查询」而无开关可关的情况。


3. 插件改动点

改动 说明
拆分 SHELL_CSS SHELL_VARS / SHELL_LAYOUT / SHELL_WIDGETS 三段;full=all,minimal=vars(+极简 layout)
render 读 app.shell_css / page.shell_css 页面覆盖应用
为 has-sidebar 布局加基础媒体查询 即使 full,小屏改为单列(减轻幽灵双列);minimal/off 不负责响应式

4. 兼容策略

  • 默认 full:视觉与现网一致。
  • Tutorial 增加一节「品牌主题请用 shell_css=minimal|off」。

5. 验收

场景 期望
shell_css=off + 站点只写单列 grid 响应里无 grid-template-columns:14rem
minimal 有 CSS 变量;无 .content.cards article 边框默认(或等价皮肤段)
默认示例站 HTML 仍含完整壳 CSS

6. 过渡期 → 已落地

C2 已落地(2026-09): shell_css=full|minimal|off;页面/应用可设;full 含 @media (max-width:720px) 单列。金样 tests/ext/web-c2-shell-layout.mq.md。