/* Materials and depth. SOURCE: developer.apple.com/design/human-interface-guidelines/materials, read via Apple's Markdown endpoint. Every numeric value below that is Apple's is marked; the rest are this system's conversion to CSS, because Apple publishes materials as API names (Material.thin, UIVibrancyEffectStyle.label) with no published RGB or blur radii. THE TWO LAYERS, which is the rule the rest of the file hangs off. Apple splits the interface in two: a FUNCTIONAL layer of controls and navigation — tab bars, sidebars, toolbars — which uses Liquid Glass and floats above; and a CONTENT layer beneath it, which uses the four STANDARD materials for visual differentiation. They are not interchangeable: • Don't use Liquid Glass in the content layer. Apple: it 'can result in unnecessary complexity and a confusing visual hierarchy'. Use a standard material for app backgrounds and content-layer grouping instead. • The one exception: a content-layer control with a transient interactive element — a slider or a toggle — takes on a Liquid Glass appearance WHILE being manipulated, to emphasise interactivity, then drops it. • Use Liquid Glass sparingly on custom controls. System components adopt it automatically; hand-applying it to several custom controls distracts from content. Limit it to the most important functional elements. Shadows are soft, low-contrast and almost always vertical-only — there is no hard drop shadow anywhere in the system. Content underneath the functional layer is never blurred by the app; the material does the blurring. */ :root { /* ---- Standard materials: the CONTENT layer ---- iOS and iPadOS define exactly four, in thickness order, and `regular` is the default. Thicker = more opaque = better contrast for text and fine features. Thinner = more translucent = better at reminding people what's behind. Choose by that trade-off and by semantic use, never by the colour the material happens to impart — system settings change that colour out from under you. ---- */ --material-thin-blur: saturate(180%) blur(20px); /* @kind other */ --material-regular-blur: saturate(180%) blur(30px); /* @kind other */ --material-thick-blur: saturate(180%) blur(50px); /* @kind other */ --material-ultra-thin: rgba(255, 255, 255, 0.44); --material-thin: rgba(255, 255, 255, 0.6); --material-regular: rgba(255, 255, 255, 0.72); --material-thick: rgba(255, 255, 255, 0.84); --material-chrome: rgba(255, 255, 255, 0.78); /* ---- THE ONE RULE THAT GOVERNS ALL GLASS USE (materials.md > Liquid Glass) ---- VERIFIED September 2026. **Do not use Liquid Glass in the content layer.** Glass is a distinct FUNCTIONAL layer for controls and navigation that floats above content. Putting it in the content layer produces unnecessary complexity and a confusing hierarchy. Content- layer elements — app backgrounds, section groupings — take STANDARD materials (the thickness scale further down this file), not glass. The single exception Apple names: a content-layer control with a TRANSIENT interactive element — sliders and toggles — takes on a Liquid Glass appearance while a person is actively manipulating it, then drops back. Glass here marks the moment of interaction, not the resting state. **Use Liquid Glass sparingly on custom controls.** System components adopt it automatically. Applying it to many custom controls distracts from the content the material exists to reveal — limit it to the most important functional elements. ---- Liquid Glass variants. Apple is specific about when each applies: */ REGULAR Blurs and adjusts the LUMINOSITY of background content to keep foreground legible. Most system components use this. Choose it when the background might cause legibility problems, or when the component carries a significant amount of text — Apple names alerts, sidebars and popovers. CLEAR Highly translucent, for prioritising the visibility of what is behind. Its purpose is components floating over VISUALLY RICH backgrounds — photos and video — to make the content experience more immersive. Both variants change appearance in response to system settings: the user's preferred Liquid Glass look, Reduce Transparency, and Increase Contrast. */ --glass-fill: rgba(255, 255, 255, 0.62); --glass-edge: rgba(255, 255, 255, 0.75); --glass-shadow: 0 1px 3px rgba(0, 0, 0, 0.08), 0 8px 24px rgba(0, 0, 0, 0.08); --glass-clear-fill: rgba(255, 255, 255, 0.24); --glass-clear-edge: rgba(255, 255, 255, 0.34); --glass-clear-blur: saturate(140%) blur(12px); /* Dimming layer — sits UNDER clear glass. 35% is the ONE numeric value Apple publishes anywhere for Liquid Glass, and the condition matters as much as the number: apply it when the underlying content is BRIGHT. If the content is already sufficiently dark, or you are using AVKit's standard playback controls (which bring their own dimming), add nothing. */ --glass-dim: rgba(0, 0, 0, 0.35); /* Scroll edge effect — visual separation between a floating bar and the scrolling content behind it. VERIFIED against scroll-views.md, September 2026 (page revised June 8, 2026). iOS, iPadOS and macOS only. automatic DEFAULT, and Apple says to prefer it. The MORE OPAQUE separation — it is what keeps a top toolbar legible when it holds many controls, text sitting outside a Liquid Glass control, or pinned table headers. soft A variable blur fading gently toward the bar's edge. If you choose it over automatic, Apple asks you to test legibility thoroughly across contexts. hard A more opaque blur with a defined edge at the bar's boundary. Two rules, both verbatim from the source: scroll edge effects are **not decorative** — use one only where a scroll view passes behind floating interface elements, and note they neither block nor darken like an overlay, they only keep controls distinct. And apply **one per view**; in an iPad or Mac split view each pane may have its own, but keep their heights consistent so they align. */ --scroll-edge-top: linear-gradient(to bottom, var(--bg-primary), rgba(255, 255, 255, 0)); --scroll-edge-soft: linear-gradient(to bottom, color-mix(in srgb, var(--bg-primary) 82%, transparent), rgba(255, 255, 255, 0)); --scroll-edge-height: 28px; --scroll-edge-hard-line: var(--hairline) solid var(--separator); /* ---- Liquid Glass shape and interaction ---- ⚠️ PROVENANCE: materials.md publishes NO geometry for Liquid Glass — no radii, no spacing, no merge behaviour. Everything in this block is this system's own convention, kept because the components need consistent values, but it must not be cited as Apple guidance. (An earlier version of this file asserted a "40pt system default merge distance" at which glass elements fuse. No such figure appears in materials.md. The token is retained below as our spacing convention and renamed accordingly.) */ /* ---- WHERE BRAND COLOUR GOES ---- ⚠️ ATTRIBUTION CORRECTED, September 2026. An earlier pass credited the rule below to "branding.md, revised September 2026". On re-reading, branding.md contains NO such statement — it covers accent colour, custom fonts, deferring to content, and trademark rules, and says nothing about the content layer. The attribution was wrong. What IS verified, from buttons.md and tab-bars.md in those pages' own words: avoid giving button and tab labels a colour close to the content-layer background, and when the content layer is bright and colourful, prefer the DEFAULT MONOCHROMATIC label appearance over any tint. From toolbars.md: let the content layer inform the toolbar's colour, and custom appearances interfere with the system background effects. From materials.md: glass is a functional layer and must not be used in the content layer at all. The synthesis below — put brand colour in the CONTENT layer and let the glass pick it up, rather than tinting the chrome — follows from those verified rules and is a sound reading of them, but it is OUR formulation, not a sentence Apple publishes. Treat it as this design system's guidance. On the controls themselves, use the accent colour sparingly and deliberately — the primary action, a status indicator, an unread badge, the selected tab. Tinting every control dilutes the accent to the point that nothing reads as primary. Two corollaries that appear on buttons.md and tab-bars.md in the same words: avoid giving button labels and tab labels a colour close to the content-layer background, and when the content layer is already bright and colourful, prefer the DEFAULT MONOCHROMATIC label appearance over any tint at all. */ --glass-radius-control: var(--radius-capsule); --glass-radius-panel: 20px; /* Ours, not Apple's — the spacing below which we draw two glass elements as one surface rather than two. Previously mislabelled as a system default. */ --glass-group-merge-spacing: 40px; /* The tint used for PROMINENT glass. Deliberately NOT --tint: white on --system-blue is 3.52:1, which fails 4.5:1 for a normal-weight label. Not --system-blue-contrast either (4.57:1) — the 88% tint strength still dilutes the colour against what shows through, so the glass needs headroom the flat swatch doesn't. #0062CC reaches 5.80:1 flat and holds up diluted. This one is ours, not Apple's. See guidelines/cards/a11y-white-on-color.html. */ --glass-tint-color: #0062CC; --glass-tint-strength: 0.88; /* alpha of the tint over the blur — high enough that full-opacity white label text clears 4.5:1. Mixing a tint into the translucent white fill instead just produces a pale wash that white text cannot sit on. @kind other */ --glass-interactive-brighten: rgba(255, 255, 255, 0.18); --glass-interactive-press-scale: 0.97; /* ---- Elevation ---- */ --shadow-none: none; --shadow-raised: 0 1px 2px rgba(0, 0, 0, 0.04), 0 1px 1px rgba(0, 0, 0, 0.04); --shadow-card: 0 1px 3px rgba(0, 0, 0, 0.06), 0 4px 12px rgba(0, 0, 0, 0.05); --shadow-popover: 0 4px 12px rgba(0, 0, 0, 0.1), 0 16px 40px rgba(0, 0, 0, 0.12); --shadow-sheet: 0 -1px 0 rgba(0, 0, 0, 0.04), 0 -12px 40px rgba(0, 0, 0, 0.14); --shadow-window: 0 12px 40px rgba(0, 0, 0, 0.2), 0 2px 6px rgba(0, 0, 0, 0.12); --shadow-focus-ring: 0 0 0 3.5px color-mix(in srgb, var(--tint) 45%, transparent); /* ---- Which standard material, per platform (materials.md > Platform considerations) ---- Apple names a recommended use for each thickness, and the recommendations DIFFER by platform — the same token means different things on a TV and on a headset. tvOS: ultraThin full-screen views that require a LIGHT colour scheme thin overlays that partly obscure content and require a light colour scheme regular overlays that partly obscure content thick overlays that partly obscure content and require a DARK colour scheme visionOS (no Dark Mode at all — glass adapts to the luminance behind it instead): thin brings attention to interactive elements: buttons, selected items regular separates sections of the app: a sidebar, a grouped table view thick a dark element that stays distinct on top of a regular background A visionOS button on a glass window uses THIN as its background; a button floating free in space uses the glass material itself. macOS additionally has two background BLENDING modes — behind-window and within-window — which have no CSS equivalent; backdrop-filter is always behind-element. Noted so the gap is known rather than silently approximated. ---- */ /* ---- Vibrancy overlay for content sitting on a material ---- Apple's rule is flat: whatever material you chose, put VIBRANT colours on top of it, and never a fixed gray — the systemGray3 symbol on a translucent button is Apple's own illustration of getting this wrong. Vibrancy has four label levels and three fill levels; default has the HIGHEST contrast and quaternary the lowest. One hard exclusion: avoid quaternary on the `thin` and `ultraThin` materials — Apple says the contrast is too low. Separators have a single level that works on all four. visionOS is narrower still: three label levels only (label / secondary / tertiary), with tertiary reserved for inactive elements where legibility is not required. ---- */ --vibrancy-label: var(--label-primary); --vibrancy-label-secondary: var(--label-secondary); --vibrancy-label-tertiary: var(--label-tertiary); /* Do not place this on --material-thin or --material-ultra-thin. */ --vibrancy-label-quaternary: var(--label-quaternary); --vibrancy-fill: var(--fill-primary); --vibrancy-fill-secondary: var(--fill-secondary); --vibrancy-fill-tertiary: var(--fill-tertiary); --vibrancy-separator: rgba(0, 0, 0, 0.08); } /* ---- Per-platform Liquid Glass behaviour (materials.md > Platform considerations) ---- VERIFIED September 2026. No tokens — these are behaviours, recorded so the system states them somewhere. tvOS. Liquid Glass runs through navigation, Top Shelf and Control Center, and — the part with design consequences — **image views and buttons ADOPT Liquid Glass when they gain focus**. So a tvOS focus state is not just a scale-up; the element changes material. Anything custom that takes focus should do the same. visionOS. Windows use an unmodifiable system material called *glass* — you cannot restyle it. It limits the range of background colour information so a window keeps contrast for app content while brightening or darkening with the wearer's physical surroundings. **visionOS has no Dark Mode setting at all**; glass adapts to the luminance behind it instead. Prefer translucency to opaque colour: opacity blocks the view, which makes people feel constricted and reduces awareness of what is physically around them. watchOS. Full-screen modal views are common, and the material layer is what orients people and separates controls from content. **Do not remove or replace the default material background on a modal sheet.** macOS. Provides vibrant versions of all the specification colours, plus two background BLENDING modes — behind-window and within-window. Neither has a CSS equivalent: backdrop-filter always samples what is directly behind the element, so within-window blending cannot be reproduced here. Recorded as a known gap rather than silently approximated. */ :root.dark { --material-ultra-thin: rgba(28, 28, 30, 0.44); --material-thin: rgba(28, 28, 30, 0.6); --material-regular: rgba(28, 28, 30, 0.74); --material-thick: rgba(28, 28, 30, 0.86); --material-chrome: rgba(28, 28, 30, 0.8); --glass-fill: rgba(58, 58, 60, 0.58); --glass-edge: rgba(255, 255, 255, 0.14); --glass-shadow: 0 1px 3px rgba(0, 0, 0, 0.4), 0 8px 24px rgba(0, 0, 0, 0.4); --glass-clear-fill: rgba(28, 28, 30, 0.26); --glass-clear-edge: rgba(255, 255, 255, 0.1); --glass-dim: rgba(0, 0, 0, 0.35); --glass-interactive-brighten: rgba(255, 255, 255, 0.1); --scroll-edge-top: linear-gradient(to bottom, var(--bg-primary), rgba(0, 0, 0, 0)); --scroll-edge-soft: linear-gradient(to bottom, color-mix(in srgb, var(--bg-primary) 82%, transparent), rgba(0, 0, 0, 0)); --scroll-edge-hard-line: var(--hairline) solid var(--separator); --shadow-raised: 0 1px 2px rgba(0, 0, 0, 0.5); --shadow-card: 0 1px 3px rgba(0, 0, 0, 0.5), 0 4px 12px rgba(0, 0, 0, 0.4); --shadow-popover: 0 4px 12px rgba(0, 0, 0, 0.6), 0 16px 40px rgba(0, 0, 0, 0.5); --shadow-sheet: 0 -12px 40px rgba(0, 0, 0, 0.6); --shadow-window: 0 12px 40px rgba(0, 0, 0, 0.7), 0 2px 6px rgba(0, 0, 0, 0.5); --vibrancy-separator: rgba(255, 255, 255, 0.12); } /* ---- Reduce Transparency. Materials and glass both respond to this setting on Apple platforms (materials.md > Liquid Glass: the variants "differ in response to ... accessibility settings that reduce transparency or increase contrast"). Every translucent surface goes opaque and every blur is dropped. ---- */ @media (prefers-reduced-transparency: reduce) { :root { --material-thin-blur: none; --material-regular-blur: none; --material-thick-blur: none; --glass-clear-blur: none; --material-ultra-thin: #FFFFFF; --material-thin: #FFFFFF; --material-regular: #FFFFFF; --material-thick: #FFFFFF; --material-chrome: #F7F7F9; --glass-fill: #F7F7F9; --glass-edge: var(--separator); --glass-clear-fill: #F7F7F9; --glass-clear-edge: var(--separator); --glass-dim: rgba(0, 0, 0, 0.55); --glass-interactive-brighten: rgba(0, 0, 0, 0.06); } :root.dark { --material-ultra-thin: #1C1C1E; --material-thin: #1C1C1E; --material-regular: #1C1C1E; --material-thick: #1C1C1E; --material-chrome: #2C2C2E; --glass-fill: #2C2C2E; --glass-clear-fill: #2C2C2E; --glass-interactive-brighten: rgba(255, 255, 255, 0.08); } }