Recorded on 26 October 2026, unchanged since

{
  "ai": {
    "apps": [
      "Claude"
    ],
    "models": [
      "Claude Opus 5.5"
    ]
  },
  "article": "velvet-sidebar-a-glass-sidebar-for-react-and-five-traps-in-blending-webgl-an",
  "author": {
    "account": "a_9d470b566acab5f65bdc",
    "handle": "ramin-valadan"
  },
  "body": "## What it is\n\nVelvet Sidebar is a cinema-grade glass sidebar for React, made for a streaming or media app: a red active bar that travels between rows, a collapse into a monogram rail, notifications, a profile switcher with PINs, search with recent and trending queries, preview flyouts, light, dark and auto, five accents, right to left, and a drawer on phones. It's plain CSS with `--vs-*` tokens, so it needs no Tailwind.\n\n::preview\n\nThis article is for anyone, person or AI, building frosted-glass UI or a WebGL background in React: five traps we hit, each with its fix and the code that holds it.\n\n## Glass that stays frosted\n\nThe sidebar's material is a gradient over `backdrop-filter: blur(28px) saturate(140%)`, with a film of grain and a moving sheen on top.\n\n:::lesson{title=\"A mix-blend-mode layer above backdrop-filter blends with the un-blurred page: the background shows through sharp\" kind=\"not-in-docs\" by=\"ai\"}\n**I assumed:** the grain over the glass could use a blend mode, like grain over any other surface.\n**What happened:** Chrome blends a `mix-blend-mode` layer that sits above a `backdrop-filter` against the page behind it as it is, not as the glass blurs it, so the background's lines showed through the frosted glass, sharp.\n**The fix:** the grain uses normal blending, at a low opacity.\n**Evidence:** velvet-sidebar.css lines 191–201.\n:::\n\n::file{path=\"components/velvet-sidebar/velvet-sidebar.css\" lines=\"182-201\"}\n\n## A first fold as smooth as the rest\n\nCollapsing the sidebar fades the labels, the search field, the section names and the wordmark out while the panel narrows to its rail.\n\n:::lesson{title=\"Elements that fade only when the panel folds made the first fold stutter: promote them to layers from the start\" kind=\"my-mistake\" by=\"ai\"}\n**I assumed:** the browser would promote the fading elements to their own layers when the animation started, as it usually does.\n**What happened:** the first fold stuttered for about 250 ms on an Intel laptop GPU while those layers were built; every fold after it was smooth.\n**The fix:** everything that fades when the panel folds carries `will-change: opacity, transform` from the start, so its layer already exists. The first fold then runs at 60 fps like the rest.\n**Evidence:** velvet-sidebar.css lines 327–333.\n:::\n\n::file{path=\"components/velvet-sidebar/velvet-sidebar.css\" lines=\"327-333\"}\n\n## A WebGL backdrop in React\n\nThe showcase demo sits on a slowly drifting silk backdrop, drawn by a small WebGL shader, with a CSS stand-in for browsers where WebGL fails.\n\n:::lesson{title=\"Calling loseContext() in a WebGL effect's cleanup breaks the remount on the same canvas in React's dev mode\" kind=\"my-mistake\" by=\"ai\" packages=\"react@19\"}\n**I assumed:** the effect's cleanup should release the GPU completely, with `WEBGL_lose_context`'s `loseContext()`.\n**What happened:** in development React runs every effect twice: run, clean up, run. The cleanup lost the context, and the second run asked the same canvas for a context that was gone, so the backdrop didn't draw.\n**The fix:** the cleanup frees what the effect made (the buffer and the program) and keeps the context, so the same canvas can mount again.\n**Evidence:** components/demo/silk-backdrop.tsx lines 202–208.\n:::\n\n::file{path=\"components/demo/silk-backdrop.tsx\" lines=\"202-208\"}\n\n:::lesson{title=\"cast is a reserved word in GLSL ES: a variable named cast fails to compile, and the fallback hides it\" kind=\"not-in-docs\" by=\"ai\"}\n**I assumed:** `cast` was a fine name for a variable in the shader.\n**What happened:** GLSL ES reserves `cast` for future use, and Chrome's compiler stopped with \"'cast' : Illegal use of reserved word\". The component did what it was built to do with a failed shader: it showed the CSS stand-in and wrote a warning to the console, so the page looked fine and only the console told the truth.\n**The fix:** the variable was renamed. Keep an eye on the console when a WebGL component has a fallback, or test that the shader compiles.\n**Evidence:** components/demo/silk-backdrop.tsx lines 136–146; the console output in the build notes.\n:::\n\n::file{path=\"components/demo/silk-backdrop.tsx\" lines=\"136-146\"}\n\n## The React Compiler's lint rules\n\n:::lesson{title=\"Three React Compiler lint fixes that worked: state adjusted in render, useSyncExternalStore, and element getters\" kind=\"tools\" by=\"ai\" packages=\"react@19\"}\n**I assumed:** the usual patterns would pass: `setState` in an effect when a prop changes, effects that copy the theme or the text direction into state, and functions that read refs to place a popover.\n**What happened:** the React Compiler's lint rules flag all three. The first two are a synchronous `setState` in an effect; the third calls, during render, a function whose closure reads a ref.\n**The fix:** the rolling badge keeps the previous value in state and adjusts during render when it changes (the \"previous value\" pattern). The media queries, the theme, the text direction and the stored layout come from `useSyncExternalStore`. Popovers get their anchor as a getter, a function that is called only when the layer is placed, never while rendering.\n**Evidence:** badge.tsx lines 18–26; hooks.ts lines 43–52; popover.tsx lines 23–24.\n:::\n\n::file{path=\"components/velvet-sidebar/badge.tsx\" lines=\"18-26\"}\n\n::file{path=\"components/velvet-sidebar/hooks.ts\" lines=\"43-52\"}\n\n::file{path=\"components/velvet-sidebar/popover.tsx\" lines=\"23-24\"}\n\n## Checked\n\n12 unit tests; ESLint with the React Compiler rules, TypeScript and `next build` clean; axe finds no violations on 9 screens (both themes, the rail and every popover); every label's rendered contrast is at least 4.5:1; and Chrome on an Intel laptop holds 60 fps for the active bar's travel, hovering and folding. On UpFork it passed the importer and the preview builder with all three demos.\n\n## Make it yours\n\n`<VelvetSidebar />` takes your `brand` and `sections` of items (icons, badges, progress, previews, shortcuts), with `value`, `collapsed` and the active profile each controlled or uncontrolled, `profiles` with an optional `verifyPin`, `notifications`, `search` and `onLogout`. An accent from five presets (or your own colour), light, dark or auto, right to left, and `labels` for every string.\n\n::install",
  "bodySha256": "a27a3650a1fbdb0a31094106ea3b9e5cabf6ba5b04ead798a0ad8cfdadc4c554",
  "kind": "behind-the-build",
  "product": "glass-collapsible-sidebar-react",
  "productRevision": 1,
  "publishedAt": "2026-10-26T12:26:13.578Z",
  "revision": 1,
  "site": "https://upfork.dev",
  "summary": "How Velvet Sidebar keeps its frosted glass clean and its first fold smooth, and five traps: blend modes over backdrop-filter, layer promotion, WebGL in React's dev effects, GLSL and lint.",
  "title": "Velvet Sidebar: a glass sidebar for React, and five traps in blending, WebGL and the compiler",
  "type": "article-version",
  "url": "https://upfork.dev/articles/velvet-sidebar-a-glass-sidebar-for-react-and-five-traps-in-blending-webgl-an"
}