Communitygithub.com

brainzcode/premium-landing

建立一個高級行動導航選單 — 漢堡按鈕變形為關閉 X、全螢幕覆蓋面板搭配階梯式連結顯現、滾動鎖定、焦點陷阱與減少動畫處理。

premium-landing 是什麼?

這項技能提供了一個高品質、可無障礙使用的行動選單實作,其核心是單一的 `set(state)` 函式。它完美地協調了四個關鍵元件:一個能流暢變形為 X 的漢堡按鈕、一個具有階梯式動畫的導覽面板、防止背景內容滾動的機制,以及一個確保鍵盤焦點不會洩漏到頁面下方的焦點陷阱。此實作不僅解決了常見的 iOS 橡皮筋效應和 z-index 陷阱,也提供了詳盡的 CSS 與 JavaScript 程式碼。它支援所有現代瀏覽器,並內建 `prefers-reduced-motion` 支援,非常適合用於需要高品質行動導覽的 React、Next.js、Astro 或任何靜態網站專案。

相容平台~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(),沒有忘記滾動鎖定的獨立「關閉」路徑。一個函式,控制所有屬性,雙向都有效。

結構

頁首的層級高於面板,面板則覆蓋其他所有內容:

.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="開啟選單" aria-expanded="false" aria-controls="menu">
    <i></i><i></i>
  </button>
</header>

<div class="menu" id="menu" role="dialog" aria-label="選單" tabindex="-1" inert>
  <nav class="menu__nav">
    <a href="#about"><span class="menu__idx">01</span> 關於</a>
    <a href="#work"><span class="menu__idx">02</span> 作品</a>
  </nav>
  <div class="menu__foot">…</div>
</div>

漢堡按鈕留在頁首並在原地變形。它既是開啟控制項,也是關閉控制項,這就是為什麼頁首必須位於面板之上——請參閱陷阱 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 延遲 */
}

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 ? '關閉選單' : '開啟選單');
    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 — 頁首必須高於面板

漢堡按鈕會變形成 X,因此在面板顯示時它必須保持可點擊。如果面板的 z-index 高於頁首,X 確實會渲染(它在頁首中繪製),但每次點擊都會落在覆蓋層上。選單變成了一個沒有可見出口的陷阱——通常被回報為「關閉按鈕沒有反應」。

賦予頁首高於面板的 z-index,並對照頁面上的每個其他固定圖層(cookie 條和黏性 CTA 是常見的衝突)檢查兩者。一組可行的設定:面板 200,頁首 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。

如果你的頁首是 position: sticky 而非 fixed,這個鎖定會破壞它。 固定的 body 沒有滾動埠,因此 sticky 相對於文件解析,導致頁首跳到頁面頂部——超出螢幕,連同漢堡按鈕一起消失。在選單開啟時將其切換為 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)(ease-out)。快速出發,長時間穩定。絕不使用 ease 或 linear。
  • 時序。 面板 450–600ms,連結在 60ms 間隔下為 600ms,漢堡變形 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、標籤、inert 和滾動鎖定的所有權
  • 頁首的 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.

相關技能