Communitygithub.com

brainzcode/premium-landing

构建高级移动端导航——汉堡按钮变形为关闭X、全屏遮罩面板、交错链接揭示、滚动锁定、焦点陷阱以及减少动效处理。用于移动菜单、汉堡按钮、导航抽屉、off-canvas菜单,或当菜单丢失滚动位置、在iOS上仍滚动、Tab焦点泄露到底层页面或关闭按钮无响应时。

premium-landing 是什么?

该技能提供了一套完整且稳健的移动端菜单实现方案,核心思想是将按钮状态、面板显示、页面滚动锁定和焦点管理这四个关键要素通过一个单一的 `set(state)` 函数进行同步控制,从而避免因分散操作导致的各类Bug。它适用于Claude Code、Cursor、Codex等任何可以通过JS/CSS/HTML定义技能的AI编程平台。技能详细解释了如何构建一个从汉堡图标优雅变形为关闭X的按钮、一个包含交错链接揭示效果的全屏遮罩面板,以及如何通过固定body位置和恢复滚动偏移量来实现在iOS Safari上的可靠滚动锁定。此外,它还涵盖了焦点陷阱(Focus Trap)、`inert`属性的正确使用、以及五个关键“陷阱”(如z-index冲突、iOS橡皮筋滚动、无法过渡的display属性、全屏背景模糊的性能问题以及未测试的状态)。最终呈现的是一个兼具高性能、无障碍访问和高级视觉感知(如自定义缓动、时间线、字体和索引数字)的生产级移动菜单。

兼容平台~Claude Code~Codex CLI✓Cursor
npx skills add https://github.com/brainzcode/premium-landing/tree/HEAD/plugins/premium-landing/skills/premium-mobile-menu

在你喜欢的 AI 中提问

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

文档

高级移动菜单

一个移动菜单由四个通过一个布尔值连接的部分组成:一个会变形的按钮、一个会展开的面板、被锁定的背景页面,以及保持在内部的焦点。几乎每个有问题的菜单都是因为这四个部分不同步——其中一个被其他地方、被别的东西切换了。

通过一个单一的 set(state) 函数来驱动一切。 不要在点击处理器中散布 classList.toggle(),也不要有忘记滚动锁定的单独“关闭”路径。一个函数,控制所有属性,处理两个方向。

结构

header 的层级高于面板,面板覆盖所有其他内容:

.nav  { position: fixed; inset: 0 0 auto; z-index: 210 }  /* 汉堡按钮在这里 */
.menu { position: fixed; inset: 0 0 auto; z-index: 200; height: 100dvh }
<header class="nav">
  <a class="brand" href="/">silva</a>
  <button class="burger" id="menuBtn" type="button"
          aria-label="Open menu" aria-expanded="false" aria-controls="menu">
    <i></i><i></i>
  </button>
</header>

<div class="menu" id="menu" role="dialog" aria-label="Menu" tabindex="-1" inert>
  <nav class="menu__nav">
    <a href="#about"><span class="menu__idx">01</span> About</a>
    <a href="#work"><span class="menu__idx">02</span> Work</a>
  </nav>
  <div class="menu__foot">…</div>
</div>

汉堡按钮保留在 header 中并就地变形。它既是打开控件,也是关闭控件,这就是为什么 header 必须位于面板之上——参见陷阱 1。

按钮

44×44 的点击目标,22px 可见的条。条是绝对定位的,并使用 margin(而非 transform) 居中,这样 transform 属性可以自由用于变形:

.burger {
  position: relative; display: grid; place-items: center;
  width: 44px; height: 44px;
  background: none; border: 0; padding: 0; cursor: pointer;
  color: currentColor;
  -webkit-tap-highlight-color: transparent;
}

.burger i {
  position: absolute; left: 50%; top: 50%;
  margin: -.75px 0 0 -11px;          /* 居中逻辑在此,不在 transform 中 */
  width: 22px; height: 1.5px;
  background: currentColor; border-radius: 2px;
  transition: transform .45s var(--ease);
}

.burger i:first-child { transform: translateY(-4px) }
.burger i:last-child  { transform: translateY(4px)  }

html.is-menu-open .burger i:first-child { transform: rotate(45deg)  }
html.is-menu-open .burger i:last-child  { transform: rotate(-45deg) }

两个条共享一个中心点,因此将它们旋转 ±45° 就能得到一个对称的 X,无需第二个关键帧,也无需调整任何东西。如果你改用 translate(-50%,-50%) 来居中,那么每个变形状态都必须重新声明那个 translate,并且两个条会相差一个像素。

使用两个条,而不是三个。 三线汉堡变成 X 需要中间那条淡出,同时外面两条汇聚,而淡出在过渡过程中会表现为一个灰色污迹。两个条的变形则很干净。如果必须保留三线状态,可以对外部两条使用 translateY + rotate 进行动画,并为中间的 opacity 设置一个更短的持续时间,这样它会在旋转开始前就消失。

永远不要通过 top/margin 的动画来移动条。只使用 Transform。

面板

.menu {
  position: fixed; left: 0; right: 0; top: 0;
  height: 100dvh;                      /* 不是 inset:0 — 参见陷阱 2 */
  z-index: 200;
  display: flex; flex-direction: column; justify-content: space-between;
  padding: clamp(96px, 24vw, 150px) var(--gutter)
           max(clamp(28px, 7vw, 52px), env(safe-area-inset-bottom));
  background: var(--black); color: var(--white);
  overflow-y: auto; overscroll-behavior: contain;

  opacity: 0; visibility: hidden; transform: translateY(-12px);
  transition: opacity .45s var(--ease),
              transform .55s var(--ease),
              visibility 0s linear .45s;   /* 仅在淡出完成后隐藏 */
}

.menu.is-open {
  opacity: 1; visibility: visible; transform: none;
  transition-delay: 0s;                    /* 进入时取消可见性的延迟 */
}

visibility 是使其对键盘安全的关键:它将关闭的面板从 Tab 键顺序中移除,而单独的 opacity: 0 无法做到这一点。延迟的 visibility 过渡是整个技巧——进入时立即可见,隐藏则仅当淡出播放完毕后。

交错的链接揭示效果是看似昂贵的关键:

.menu__nav a {
  opacity: 0; transform: translateY(18px);
  transition: opacity .6s var(--ease), transform .6s var(--ease);
}
.menu.is-open .menu__nav a { opacity: 1; transform: none }

.menu.is-open .menu__nav a:nth-child(1) { transition-delay: .10s }
.menu.is-open .menu__nav a:nth-child(2) { transition-delay: .16s }
.menu.is-open .menu__nav a:nth-child(3) { transition-delay: .22s }
.menu.is-open .menu__nav a:nth-child(4) { transition-delay: .28s }
.menu.is-open .menu__nav a:nth-child(5) { transition-delay: .34s }

间隔 60ms。低于约 40ms 会感觉像一块整体;高于约 90ms 最后一个项目会觉得来得太晚。对于长度未知的列表,在每个项目上设置 style="--i:3",并使用 transition-delay: calc(.10s + var(--i) * .06s)。

在关闭时,移除延迟(.menu:not(.is-open) .menu__nav a { transition-delay: 0s })。交错退出会让关闭感觉变慢——关闭应该是即时的。

状态函数

(function () {
  var btn   = document.getElementById('menuBtn');
  var panel = document.getElementById('menu');
  var root  = document.documentElement;
  var open  = false;
  var scrollY = 0;

  var FOCUSABLE = 'a[href], button:not([disabled]), input, select, textarea,' +
                  '[tabindex]:not([tabindex="-1"])';

  // 汉堡按钮是关闭控件,位于面板外部,因此它属于循环中
  function focusables() {
    return [btn].concat([].slice.call(panel.querySelectorAll(FOCUSABLE)));
  }

  function set(state) {
    if (state === open) return;
    open = state;

    panel.classList.toggle('is-open', open);
    root.classList.toggle('is-menu-open', open);
    btn.setAttribute('aria-expanded', String(open));
    btn.setAttribute('aria-label', open ? 'Close menu' : 'Open menu');
    if (open) panel.removeAttribute('inert');
    else      panel.setAttribute('inert', '');

    if (open) {
      scrollY = window.scrollY;
      document.body.style.position = 'fixed';
      document.body.style.top = -scrollY + 'px';
      document.body.style.left = '0';
      document.body.style.right = '0';
      panel.focus({ preventScroll: true });
    } else {
      document.body.style.position = '';
      document.body.style.top = '';
      document.body.style.left = '';
      document.body.style.right = '';
      window.scrollTo(0, scrollY);
      btn.focus({ preventScroll: true });
    }
  }

  btn.addEventListener('click', function () { set(!open); });

  panel.querySelectorAll('a').forEach(function (a) {
    a.addEventListener('click', function () { set(false); });
  });

  document.addEventListener('keydown', function (e) {
    if (!open) return;
    if (e.key === 'Escape') { set(false); return; }
    if (e.key !== 'Tab') return;

    var list  = focusables();
    var first = list[0];
    var last  = list[list.length - 1];
    if (e.shiftKey && document.activeElement === first) { e.preventDefault(); last.focus(); }
    else if (!e.shiftKey && document.activeElement === last) { e.preventDefault(); first.focus(); }
  });

  // 跨越断点不能导致页面处于锁定状态
  matchMedia('(min-width: 1101px)').addEventListener('change', function (e) {
    if (e.matches) set(false);
  });
})();

inert 在此处取代了 aria-hidden。永远不要在可以持有焦点的面板上使用 aria-hidden="true"——如果焦点在其中,你就将聚焦的元素从无障碍树中隐藏了,这是一个作者错误,屏幕阅读器处理起来很糟糕。inert 在一个属性中同时阻止了焦点并隐藏了元素。

注意 role="dialog" 没有 aria-modal="true"。aria-modal 告诉辅助技术忽略对话框外部的所有内容,而关闭按钮就在外部。要么去掉 aria-modal(如上),要么在面板内放置一个真正的关闭按钮。

陷阱 1——header 必须层级高于面板

汉堡按钮变形为 X,因此在面板打开时它必须保持可点击。如果面板的 z-index 高于 header,X 会渲染(它是在 header 中绘制的),但每次点击都会落在遮罩层上。菜单变成了一个没有可见出路的陷阱——报告为“关闭按钮不起作用”。

给 header 一个比面板更高的 z-index,并对照页面上所有其他的固定定位层(cookie 提示条和粘性 CTA 是常见的冲突)检查这两个值。一组可行的值:面板 200,header 210,toasts 9000。

固定定位元素只有在共享同一个层叠上下文时才会互相堆叠。任何祖先上的 transform、filter、opacity < 1 或 will-change 都会创建一个新的层叠上下文,并静默地重新定义整个比较。

陷阱 2——body 上的 overflow: hidden 无法锁定 iOS

document.body.style.overflow = 'hidden' 可以锁定桌面浏览器,但在 iOS Safari 上对触摸拖动无效。页面会在面板后面橡皮筋式滚动,一旦松开,用户就到了别处。

有效的锁定是固定 body 并恢复偏移量,这就是上面的 set() 所做的。与之相关的两个细节:

  • 面板上的 overscroll-behavior: contain 可阻止面板自身的滚动在到达边界时传递到页面。
  • 在清除 position 的同一个调用中,使用 window.scrollTo(0, scrollY) 进行恢复。在 body 解除固定后读取 scrollY 会得到 0。

如果你的 header 使用了 position: sticky 而非 fixed,此锁定会破坏它。 固定的 body 没有滚动口,所以 sticky 会依据文档解析,header 会跳到页面顶部——移出屏幕,带走了汉堡按钮。在菜单打开时将其切换为 fixed(html.is-menu-open .nav { position: fixed; top: 0 })。lenis-smooth-scroll 技能涵盖了来自 Lenis 方面的相同故障;如果页面上使用了该库,请使用 lenis.stop() 来代替第二个锁定,而不是同时使用两者。

在非零滚动偏移量下测试锁定。在滚动 0 时,一个坏的锁定在像素上与好的锁定是无法区分的。滚动到约 1200 像素,打开菜单,拖动,关闭:位置必须在整个过程中保持 1200。

陷阱 3——display: none 无法过渡

切换 display 会完全跳过动画:面板瞬间闪现和消失。上述的 visibility + 延迟过渡模式是适用于所有地方的版本。

如果你愿意使用 2024+ 的基线,现代等效方案是:

.menu { display: none; opacity: 0;
        transition: opacity .45s var(--ease), display .45s allow-discrete }
.menu.is-open { display: flex; opacity: 1 }
@starting-style { .menu.is-open { opacity: 0 } }

@starting-style 是必需的——没有它,进入动画就没有起始值,只有退出动画会动。

陷阱 4——面板不是应用背景模糊的正确位置

在全屏面板上使用 backdrop-filter 会每帧重新采样其背后的所有内容,在中端 Android 设备上将进入动画的帧率降到个位数。在一次构建中,移除整个视口的混合/模糊效果将丢帧率从 34% 降到了 3%。

一个高级菜单几乎总是一个不透明的品牌色面板,而不是磨砂玻璃。如果设计需要玻璃效果,应该对一个小元素(一个覆盖屏幕部分区域的 sheet)进行模糊,而不是整个视口,并参考 liquid-glass 技能。

陷阱 5——没人测试的状态

  • 在打开状态时调整大小越过断点。 上面用 matchMedia 处理了,而不是 resize 监听器,因此它只在越过时触发一次,而不是在拖动的每一帧触发。
  • 客户端路由切换。 在 Next/Astro/SPA 导航中,面板会保留在导航之后。在路由事件上调用 set(false),并在卸载时清理 body 样式。
  • 打开后按返回按钮。 如果你在菜单打开时推入了一个历史记录条目,返回按钮必须关闭它,而不是离开页面。
  • 缩放到 200%。 面板必须能够滚动,而不是裁剪其底部。
  • 横屏手机。 使用 100dvh 和可滚动的面板可以处理;垂直居中的 justify-content: center 列表则不行。

减少动效

@media (prefers-reduced-motion: reduce) {
  .menu, .menu__nav a, .burger i {
    transition-duration: .01ms !important;
    transition-delay: 0s !important;
  }
}

保留状态变化,去掉编排。面板仍然必须出现和消失。

是什么让它看起来高级

以上机制是基础。以下选择是它与 bootstrap 抽屉的区别所在:

  • 缓动效果。 面板和链接使用 cubic-bezier(.16, 1, .3, 1) (expo-out)。快速启动,长时间稳定。永远不要使用 ease 或 linear。
  • 时间掌握。 面板 450–600ms,链接 600ms 带 60ms 交错,汉堡动画 450ms。低于 300ms 没有运动感;超过 700ms 感觉迟缓。
  • 字体。 链接列表就是设计本身。clamp(1.65rem, 8.4vw, 2.9rem),字重 300,line-height: 1,大写,字间距紧凑。行间有细线分隔。
  • 索引数字。 每个标签前用小的等宽或字母间距大写显示 01 / 02 / 03,颜色柔和。添加成本低,但对感知质量的提升超过任何特效。
  • 整行点击区域。 在链接本身上使用 clamp(14px, 3.4vw, 22px) 的垂直内边距,而不是周围的 margin,这样整行都可点击。
  • 使用 :active 状态,而不是 :hover 状态。手机没有悬停,点击后残留的悬停样式看起来有问题。
  • 底部块——联系方式、社交链接、单个药丸形状的 CTA——通过 justify-content: space-between 固定。底部空白空间是让菜单看起来像占位符的原因。
  • 面板本身没有反弹或弹簧效果。 在全屏表面上的过冲看起来廉价。将弹簧缓动留给小元素。

检查清单

  • 一个 set(state) 函数控制 class、aria-expanded、label、inert 和滚动锁定
  • Header 的 z-index 高于面板,并已对照页面所有其他固定定位元素进行了验证

…

[已截断]

Individual skills in this repo

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

brainzcode/premium-landing

Add a studio or agency build credit to a website footer — "Site by <Studio>" linking to the studio's site. Use when finishing or shipping a site, adding a footer, or when asked for an agency credit, build credit, designed-by line, or attribution. Covers wording, placement opposite the client's copyright, markup for each stack, styling from the host site's tokens, and the sitewide-footer-link SEO footprint when the same credit runs across many client sites.

brainzcode/premium-landing

Build a complete premium landing page, either replicated from a reference screenshot/URL or designed from a written brief, in HTML, React, Next.js or Astro. Use when asked to build, design, replicate or clone a landing page, marketing page, or one-page site; when handed a design screenshot or Figma/Pinterest reference to turn into code; or when a landing page needs a full premium pass. Covers design tokens, section patterns, the layout traps that silently break grids and marquees, and screenshot-based responsive verification from 320px to 1920px.

brainzcode/premium-landing

Add Lenis smooth scrolling to a site correctly — setup, anchor offsets for sticky headers, scroll locking for modals and menus, reduced-motion handling. Use when asked for smooth scroll, Lenis, momentum/eased scrolling, or when smooth scroll broke a sticky header, a modal lock, or anchor links. Includes the sticky-position trap that only appears at non-zero scroll.

brainzcode/premium-landing

Build true Apple-style liquid glass in the browser — real refraction via SVG displacement maps, chromatic dispersion, specular edges. Use when asked for liquid glass, glassmorphism, frosted/glass cards, glass navbars, or when a blur-based "glass" effect looks flat. Includes the performance trap that makes backdrop-filter stutter on scroll and the contrast trap that makes text unreadable on glass.

brainzcode/premium-landing

Rebuild a design accurately from a supplied reference — a screenshot, PDF page, mockup or live URL — by measuring it numerically instead of eyeballing it. Use when asked to replicate, clone, match or rebuild a design "exactly", "1 to 1" or "with no mistakes", or when a build drifts from its reference. Covers extracting the true content box from a padded screenshot, deriving element positions as percentages, solving object-fit framing, and knowing when a reference cannot be matched.

brainzcode/premium-landing

Ship link previews and favicons that actually work - Open Graph and Twitter card tags, a correctly framed 1200x630 share image, and a full favicon set (SVG, ICO, apple-touch, maskable manifest icons). Use when asked for social sharing, OG image, open graph, twitter card, link preview, share image, favicon, app icon, apple touch icon, or web manifest. Also use when a shared link previews blank, shows the wrong image, or a favicon will not appear. Includes the absolute-URL trap that silently blanks every preview and the font trap that breaks SVG favicons on other machines.

brainzcode/premium-landing

Source free, licence-clear photography for a site from Unsplash — searching by mood rather than noun, sizing and cropping for the slot, honouring the API's hotlink and download-tracking requirements, and writing real alt text. Use when a page needs a hero image, section photography, avatars or card art and none was supplied; when placeholder greys need replacing with real imagery; or when asked to find, pick or swap photos for a design.

相关技能