saglitzdesign-mcp 0.3.1

package/knowledge/design-languages/macos-app-design.md

@@ -0,0 +1,202 @@
+---
+id: macos-app-design
+title: "macOS App Design — Complete Guide"
+category: design-language
+platform: macos
+tags: [macos, apple, hig, menu-bar, keyboard, windows]
+sources: ["https://developer.apple.com/design/human-interface-guidelines/the-menu-bar", "https://developer.apple.com/design/human-interface-guidelines/windows", "https://developer.apple.com/design/human-interface-guidelines/toolbars", "https://developer.apple.com/design/human-interface-guidelines/keyboards", "https://www.apple.com/newsroom/2025/06/apple-introduces-a-delightful-and-elegant-new-software-design/", "https://pfandrade.me/blog/mac-assed-swiftui-app/", "https://daringfireball.net/2020/11/sketch_mac_app_mac_apps", "https://www.sketch.com/blog/part-of-your-world-why-we-re-proud-to-build-a-truly-native-mac-app/", "https://evilmartians.com/chronicles/how-to-make-absolutely-any-app-look-like-a-macos-app", "https://successfulsoftware.net/2025/09/26/updating-application-icons-for-macos-26-tahoe-and-liquid-glass/", "https://zenn.dev/usagimaru/articles/b2a328775124ef", "https://troz.net/post/2025/swiftui-mac-2025/", "https://www.macrumors.com/2025/09/24/all-the-new-macos-tahoe-features/"]
+updated: 2026-07-08
+---
+
+# macOS App Design — Complete Guide (macOS Tahoe 26 era)
+
+How to design a real Mac app — window anatomy, menus, keyboard, pointer, and the conventions that separate native apps from web wrappers. Liquid Glass material details live in `apple-hig-liquid-glass`; this doc is app-structural.
+
+## 1. Window anatomy & types
+
+- **Main/document windows**: freely resizable, remember size/position per window, restore state on relaunch. Set a sensible minimum (~460×300 for utility apps); content must **reflow, not letterbox**, at any size. Default first-launch size: comfortable on a 13" display (~1100×700 max), roughly centered.
+- **Title bar**: traffic lights top-leading (close ⌘W, minimize ⌘M, full screen ^⌘F; ⌥-hover zoom reveals tiling options). Document windows show a **proxy icon** beside the title (drag it to move/attach the file, ⌘-click it for the path popover) and an edited/dirty indicator for unsaved changes.
+- **Window tabs**: document apps should support native tabbing (View → Show Tab Bar, ⌘⇧\ cycling, Window → Merge All Windows) for free via standard window classes.
+- **Tiling (Tahoe)**: windows tile to halves/quarters by dragging to screen edges, via the ⌥-hover zoom-button menu, and Window → Move & Resize shortcuts. Apps must behave at exactly 50%/25% of common displays — check 720pt-wide layouts.
+- **Window levels**: normal windows only; avoid always-on-top unless the app is a utility whose whole point is floating (color picker, timer), and then make it a setting.
+- **Unified toolbar** (the modern default): toolbar merges with the title bar, ~52pt tall. Toolbar items are icon-first SF Symbols (~24pt), grouped by function; in Tahoe related actions cluster into shared Liquid Glass capsules floating over content. Support **right-click → Customize Toolbar…** with drag-to-arrange, and graceful overflow (») when the window narrows.
+- **Panels**: floating auxiliary windows (torn-off inspectors, color/font panels). Non-activating, closable with Esc where transient; HUD style only in media/full-screen contexts.
+- **Alerts**: app-modal sheet (document-specific) or window (app-level): icon + bold message (~13pt bold) + informative text (11pt), buttons bottom-trailing with the default (Return) rightmost and Cancel (Esc) beside it. Max 3 buttons; destructive alerts get a safe default and a "Don't ask again" checkbox where repeat-confirmed.
+- **Open/Save**: always the system `NSOpenPanel`/`NSSavePanel` (users rely on their sidebar favorites, search, and expanded/collapsed state). Never a custom file browser.
+
+### Sidebar (source list)
+- Leading column, translucent (sidebar material — in Tahoe it refracts the desktop/content behind). Width 220–320pt, user-resizable, collapsible via toolbar button and `⌃⌘S`.
+- Rows: 24pt (small), 28pt (medium/default), 32pt (large), following the user's "Sidebar icon size" setting in System Settings. Section headers: 11pt semibold, secondary label color.
+- Sidebar icons take the **accent color**; never hardcode row icon colors unless brand-critical (Finder-style multicolor is acceptable).
+- Sidebar = top-level navigation/collections only, not a junk drawer. Support drag-in (drop to add to a collection), context menus on every row, inline rename on Return, and reordering.
+
+### Split views & inspector
+- Standard layout: sidebar | content | **inspector** (trailing, fixed ~250–280pt, toggled by a toolbar button and `⌃⌥⌘I`/`⌥⌘I` convention). The inspector shows properties of the current selection and updates live — no Apply button, ever.
+- Give every column a minimum width and let the content column absorb slack. Column dividers are draggable with a wider invisible hit area (~10pt); double-click a divider to reset.
+- Content density: macOS body text is **13pt** (system scale: largeTitle 26 · title1 22 · title2 17 · title3 15 · headline 13 bold · body 13 · callout 12 · subheadline 11 · footnote 10 · caption 10). Controls come in large/regular/small/mini — regular (~22pt-tall buttons) for most UI. Do NOT ship 44pt iOS-density controls on the Mac.
+
+### Tables & outlines
+- Real tables have: sortable click-able column headers, draggable column resize/reorder, alternating row backgrounds for wide tables, type-select, multi-column sort indicators, and a context menu on headers to show/hide columns.
+- Rows 24–28pt; text truncates with middle-ellipsis for file paths, tail elsewhere; tooltips reveal full truncated values on hover.
+- Double-click = open/act; single click = select; Return = rename (Finder convention) or activate (list-of-actions convention) — pick the family your app belongs to and be consistent.
+
+### Metrics quick reference
+
+| Element | Spec |
+|---|---|
+| Unified toolbar height | ~52pt (compact style ~38pt) |
+| Toolbar symbols | ~24pt SF Symbols, regular weight |
+| Sidebar width | 220–320pt, resizable; collapse via ⌃⌘S |
+| Sidebar rows | 24 / 28 / 32pt (small / medium / large) |
+| Inspector width | ~250–280pt fixed |
+| Table/list rows | 24–28pt |
+| Body text | 13pt (11pt small controls, 10pt mini) |
+| Push button (regular) | ~22pt tall; large ~28pt |
+| Minimum click target | ~24×24pt (pointer precision > touch) |
+| Form/content margins | 20pt; 8pt between related controls |
+| Alert width | ~260pt content column |
+
+### Loading, progress, empty states
+
+- Empty views: centered symbol + one-line explanation + the action that fills the view ("Create your first project", drag-and-drop hint). Never a blank white pane.
+- Progress: determinate bars whenever total is knowable; indeterminate spinners (16pt inline, 32pt view-level) only briefly. Long operations belong in a non-blocking progress UI with Cancel — never a modal that locks the window for minutes.
+- Errors: inline where the problem is (form field, row badge) with recovery wording; alerts only for blocking failures. Include the failing detail ("Couldn't save 'Report.md' — disk full"), not error codes.
+
+## 2. The menu bar
+
+The menu bar is the app's **complete command inventory**. Rule: *every* feature must be reachable from a menu item, even if it also exists as a toolbar button or gesture — this is what makes features discoverable (Help-menu search finds them), user-remappable (custom shortcuts in System Settings → Keyboard), and AppleScript/accessibility-visible.
+
+Standard order and contents:
+
+| Menu | Contains |
+|---|---|
+| **App menu** (bold app name) | About [App], Settings… (⌘,), Services, Hide [App] (⌘H), Hide Others (⌥⌘H), Quit (⌘Q) |
+| **File** | New (⌘N), Open (⌘O), Open Recent ▸, Close (⌘W), Save (⌘S), Duplicate (⇧⌘S), Rename…, Move To…, Export…, Page Setup, Print (⌘P) |
+| **Edit** | Undo (⌘Z) / Redo (⇧⌘Z), Cut/Copy/Paste (⌘X/⌘C/⌘V), Paste and Match Style (⌥⇧⌘V), Delete, Select All (⌘A), Find ▸ (⌘F/⌘G/⌘E), Spelling, AutoFill, Emoji & Symbols |
+| **Format** (content-editing apps) | Font ▸ (⌘B/⌘I/⌘U), Text ▸ (alignment), styles |
+| **View** | Show/Hide Sidebar (⌃⌘S), Show/Hide Inspector, view options (as ⌘1/⌘2… where view modes exist), Show/Hide Toolbar, Enter Full Screen (^⌘F) |
+| **Window** | Minimize (⌘M), Zoom, Move & Resize ▸ (Tahoe tiling), Bring All to Front, open-window list |
+| **Help** | [App] Help (⌘?), searchable — the search field auto-indexes every menu item |
+
+- Menu items: **verb-first Title Case**; trailing ellipsis (…) when the item requires further input before acting (opens a dialog); no ellipsis for immediate actions. Toggles either check-mark or flip their title ("Show Sidebar"/"Hide Sidebar") — never both.
+- Make items **dynamic**: "Undo Rename", "Paste 3 Items"; disabled (dimmed), not hidden, when inapplicable. Hold ⌥ to reveal alternates (Close → Close All, ⌥⌘W).
+- Submenus max one level deep; group with separators by task, ~7±2 items per group.
+- **Menu bar extras** (status items): only for background/global utilities with always-on value (VPN state, capture, now-playing). Template (monochrome) icon that adapts to the transparent Tahoe menu bar; menu on click; make the extra optional via a setting. Never make an extra the app's only UI unless it's a true menu-bar utility — and then still provide Settings and Quit in its menu.
+
+## 3. Keyboard-first design
+
+- Ship the standard set plus shortcuts on every high-frequency action. Convention: primary modifier ⌘; add ⇧ for inverse/variant; ⌥ for alternate; ⌃ sparingly (heavily used by the system). Glyph display order: ⌃⌥⇧⌘ + key.
+
+### Standard shortcut vocabulary (users assume these)
+
+| Shortcut | Action | Shortcut | Action |
+|---|---|---|---|
+| ⌘N | New window/document | ⌘Z / ⇧⌘Z | Undo / Redo |
+| ⌘O | Open | ⌘X ⌘C ⌘V | Cut / Copy / Paste |
+| ⌘W / ⌥⌘W | Close window / all | ⌥⇧⌘V | Paste and Match Style |
+| ⌘S / ⇧⌘S | Save / Duplicate | ⌘A | Select All |
+| ⌘P | Print | ⌘F / ⌘G / ⇧⌘G | Find / Next / Previous |
+| ⌘Q | Quit | ⌘E | Use Selection for Find |
+| ⌘, | Settings | ⌘B ⌘I ⌘U | Bold / Italic / Underline |
+| ⌘M | Minimize | ⌘+ ⌘− ⌘0 | Zoom in / out / actual size |
+| ⌘H / ⌥⌘H | Hide app / others | ⌘T | New tab (or Fonts panel in editors) |
+| ⌘? | Help | ⇧⌘\ | Show all tabs |
+| ^⌘F | Toggle full screen | ⌘R | Refresh/reload (where applicable) |
+| ⌃⌘S | Toggle sidebar | ⌘⌫ | Delete / move to Trash |
+| ⌘` | Cycle app windows | ⌘1…9 | View modes or tab jump |
+
+- Other reserved/expected behaviors: Space = Quick Look (where previews make sense) · Esc = cancel/exit/stop editing · Return = default button, or inline rename in Finder-like lists · Delete removes selection · ⌘-click multi-select, ⇧-click range select · ⌘←→/↑↓ = line/document jumps in text · Tab/⇧Tab moves focus.
+- **Full Keyboard Access** must work: everything focusable via Tab/arrow keys, visible accent-colored focus ring (system-drawn — never suppress it), no pointer-only features. Lists support type-select (typing jumps to the matching item).
+- Text editing honors all system behaviors: ⌥-arrow word jumps, standard emacs bindings (⌃A/⌃E/⌃K), smart quotes/dashes settings, dictation, Password AutoFill, and the user's custom text replacements.
+- Design "keyboard flows": the core loop of the app (triage mail, tag photos, move tasks) should be completable without touching the pointer. Power users judge the app on this within minutes.
+
+## 4. Settings, About, onboarding
+
+- **Settings window** (⌘, and App menu → "Settings…"): toolbar-style tab bar (`.preference` toolbar style) with icon+label tabs — never a sidebar, never fake tabs. General first, Advanced last. Fixed width; height animates per tab.
+- **Changes apply instantly** — no OK/Apply/Cancel row. Non-resizable, not restorable, centers on the main screen on first open, ⌘W closes it.
+- Settings content uses the form layout: right-aligned labels, left-aligned controls in a single column, 20pt content margins, related controls grouped with 8pt spacing and groups separated by 20pt. Keep it to what users actually need to change — the best Mac apps have shockingly few settings.
+- **About window**: small fixed panel with icon, app name, version + build, copyright, optional scrolling Credits. Don't turn it into a marketing page; do link acknowledgements/licenses there.
+- **Onboarding**: Mac apps mostly skip it. Acceptable patterns: a single welcome window (recents + "New Document" + template picker), or one-screen permission priming for tools needing Accessibility/Screen Recording/Full Disk access — explain why, deep-link to the exact System Settings pane, and detect the grant live so the user never hunts. Never a swipe-through carousel; never gate launch on login for a local tool.
+
+## 5. macOS Tahoe 26 / Liquid Glass on the desktop
+
+- Toolbars, sidebars, and menus are Liquid Glass: they refract the content and desktop behind them; content scrolls under bars with a scroll-edge effect (progressive blur). Don't paint opaque bar backgrounds and don't stack custom glass on system glass.
+- The **menu bar is fully transparent** by default (users can restore a background in System Settings → Menu Bar); menu bar extras must be legible over any wallpaper — template icons only.
+- Windows and controls use **concentric corner radii** aligned to the window's rounded corners; derive nested radii from the container, never hardcode. Controls lean capsule-shaped and slightly taller; menus/popovers morph out of the control that opened them.
+- Adopt by compiling with Xcode 26 and *removing* customizations rather than adding any. Test with Reduce Transparency and Increase Contrast — glass falls back to opaque and layouts must survive.
+- **App icon**: mandatory rounded-rectangle (squircle). Freeform icons that overflow the shape get auto-boxed onto a generic background and look broken. Author a layered **Icon Composer `.icon`** file (≤4 layer groups, 1024pt canvas, no baked shadows/gloss); the system renders Default, Dark, Clear Light/Dark, Tinted Light/Dark variants plus the glass depth. Keep legacy `.icns` only as a fallback for older macOS.
+- Desktop hosts widgets and iPhone-style Controls; Spotlight runs App Intents actions directly — model core commands as App Intents on Mac too, and expose them to Shortcuts.
+- Mac widgets follow the iOS widget rules (glanceable, deep-linking, tint/clear-mode safe) and additionally render on the desktop behind windows — verify legibility at reduced desktop opacity.
+- The compatibility opt-out (`UIDesignRequiresCompatibility`) is temporary; treat Liquid Glass as the only target. Screenshots and marketing imagery should show the Tahoe appearance — pre-26 chrome instantly dates the product page.
+- Full-height sidebars now extend behind the toolbar region; use the safe-area APIs rather than hardcoding a title-bar offset, and let the scroll-edge effect handle content/bar separation.
+
+## 6. Typography, color, and materials
+
+- System font is SF Pro at the 13pt-body scale (table above in §1); use text styles, not fixed sizes — macOS Sonoma+ supports Dynamic Type-like scaling in some contexts and larger text accessibility settings affect layouts.
+- Semantic colors only: `labelColor`, `secondaryLabelColor`, `tertiaryLabelColor`, `windowBackgroundColor`, `controlBackgroundColor`, `separatorColor`, plus `controlAccentColor` for the user's chosen accent. Hardcoded hex breaks dark mode, accent settings, and increased-contrast mode.
+- **Vibrancy**: text/symbols on sidebar and toolbar materials should use vibrant label colors (automatic with system components) so they modulate with the material — flat gray text on a vibrant sidebar is a port tell.
+- Emphasis hierarchy: one accent-tinted control per context (default button); everything else neutral. Destructive menu/dialog actions in red only when they destroy data.
+- Dark mode is a separate design pass: check shadow legibility, image assets with baked white backgrounds, and desaturated accent contrast.
+
+## 7. Notifications, Dock, and background behavior
+
+- Notifications go through the system Notification Center: title ≤ ~40 chars, actionable buttons where a one-click response exists, thread grouping, and correct interruption level. Never build an in-app toast system for OS-level events.
+- **Dock badge**: a count of items needing attention (unread, failed) — not a marketing beacon; keep it accurate and clear it when the user has seen the items. Dock icon menu (right-click) should offer the app's quick actions (New Window, recent documents).
+- Long-running work continues when windows close; reflect progress in the Dock icon (determinate progress bar) or a menu bar extra, not a blocking modal.
+- Support **Sudden Termination** and login-item restraint: background helpers show up in System Settings → Login Items with your app's name — earn their place.
+
+## 8. Pointer, trackpad, context menus, drag & drop
+
+- **Hover is information**: tooltips on every toolbar icon and truncated label (~1s delay), row hover reveals inline affordances (subtle — the list shouldn't shimmer), ghost/toolbar buttons get a soft hover background. Standard push buttons do NOT react to hover — that's a web tell.
+- Cursor stays default except: I-beam over editable/selectable text, pointing hand only for web-style links, resize arrows on dividers/edges, open-hand/closed-hand for pannable canvases.
+- **Context menus everywhere**: right-click on any object offers its relevant actions — same names and shortcut glyphs as the menu bar. A context menu must never be the *only* home of an action.
+- **Drag & drop is a first-class transport**: drag content out (text, images, files — provide file promises so drops materialize real files), accept drops in with a highlighted target (inset ring / row gap indicator), multi-item drags show a badge count, containers spring-load on hover, ⌥-drag copies. Every drag is cancelable with Esc; a failed drop animates back to source.
+- Trackpad: honor system scroll elasticity/momentum, pinch-zoom where zoom exists, two-finger swipe-back where history exists, rotate where rotation exists; never hijack system gestures (Mission Control, Spaces swipes).
+
+## 9. What makes an app "Mac-assed" (vs a web wrapper)
+
+Concrete tells, in priority order:
+1. **Density & metrics** — 13pt body, 24–28pt rows, mini/small controls where appropriate, compact padding. iOS-sized (17pt text / 44pt controls) chrome instantly reads as a port.
+2. **Resizable everything** — any window size works; panels collapse before content squishes; no fixed-canvas layouts; full screen and Tahoe window tiling behave.
+3. **Multiple windows** — ⌘N opens another window/document; two projects side by side; state is per-window, not per-app. Closing the last window doesn't quit a document app.
+4. **Undo everywhere** — every mutating action goes through the undo stack with named entries ("Undo Move Card"), effectively unlimited depth, ⌘Z/⇧⌘Z. Confirmation dialogs are a smell; undo is the Mac answer to mistakes.
+5. **Document model** (content apps) — real files users own in Finder: autosave + Versions (Revert To ▸ Browse All Versions…), Rename/Move via the title-bar menu, proxy-icon drag, Open Recent, Quick Look previews, correct UTI/file icons.
+6. **Selection model** — click selects, ⌘-click toggles, ⇧-click extends, drag-marquee where spatial; selection in an inactive window turns gray, not accent-colored.
+7. **System integration** — respects accent + highlight color, native dark mode, Shortcuts/AppleScript automation, Services menu, Share menu, Spotlight indexing, system notifications with actions, Handoff/Continuity where data syncs, Sudden Termination support.
+8. **Instant** — cold-launches to a usable window in under a second; no splash screen, no loading shell, no "checking for updates" blocking launch.
+9. **Text behaves** — content text is selectable and copyable; labels aren't; fonts render with system smoothing; find (⌘F) works in any long view.
+
+Anti-patterns that scream wrapper:
+- Custom-drawn traffic lights, title bar, or window chrome; in-window hamburger menu; bottom tab bars
+- Hover effects on every element and web-style cursors (pointing hand on buttons)
+- The browser context menu, or no context menus at all
+- ⌘-shortcuts that exist nowhere in the menu bar; Esc and Return doing nothing in dialogs
+- Electron-default 14px web fonts and 44pt touch paddings; scrollbars that ignore the system setting
+- "Sign out" as the only File-menu item; update prompts rendered inside the window content
+- Single fixed-size window; no state restoration; multi-second launch with a splash screen
+
+## 10. Catalyst / SwiftUI multiplatform pitfalls
+
+- **Never ship the iPad idiom raw.** Catalyst: choose "Optimize Interface for Mac" (native AppKit controls, correct density) over scaled-iPad (75% blur). SwiftUI: audit every screen on Mac — the framework shares defaults, not conventions.
+- Replace iOS navigation furniture: tab bars → sidebar (or a toolbar-style switcher); navigation stacks → split view + selection; sheets presenting peer content → separate windows (`openWindow` / `WindowGroup`); swipe actions → context menus + menu bar commands; pull-to-refresh → ⌘R and automatic refresh.
+- Build the menu bar deliberately (`Commands` API): SwiftUI gives a skeleton; every feature still needs a real menu item with a shortcut. Wire `focusedSceneValue`/`FocusedValue` so items enable/disable per the active window and selection.
+- Known SwiftUI gaps to design around (2026): toolbar semantic placements (`.primaryAction` etc.) order items unpredictably — use explicit placements; drag sessions expose no source-side state (dimming dragged rows risks stuck UI when drops land outside the window); `.onMoveCommand` arrow-key handling is macOS-only; keyboard navigation while a TextField has focus needs manual handling; context-menu-open state isn't exposed, so focus rings around menu targets need workarounds.
+- Drop to AppKit (`NSViewRepresentable`) without guilt for the fidelity-critical 10%: tables, text views, drag sources, and window management.
+- Windowing in SwiftUI: use `Window` (single) vs `WindowGroup` (multi) deliberately, set `windowResizability(.contentSize)` for fixed utilities, `defaultSize`/`defaultPosition` for first launch, and `Settings { }` for the settings scene — it wires ⌘, and the menu item automatically.
+- Electron/web-tech apps can still pass as Mac-like if they implement §9 behaviors (real menu bar via native APIs, keyboard set, context menus, density) — the tell is behavior, not the rendering engine. But default-configured wrappers fail every test above.
+- Test the trifecta every release: full keyboard pass, resize pass (minimum size → full screen), menu-bar completeness pass.
+
+## 11. Ship checklist
+
+- [ ] Windows resizable, restorable, multi-window; sensible minimums; unified 52pt toolbar with Customize Toolbar…
+- [ ] Sidebar/inspector follow source-list conventions; 13pt-scale density; real tables with sortable headers
+- [ ] Every feature in the menu bar; verb-first names, ellipsis rules, dynamic Undo/Paste labels, ⌥-alternates
+- [ ] Standard shortcut set + Full Keyboard Access + type-select all pass; core loop is pointer-free
+- [ ] Settings: toolbar tabs, instant apply, ⌘,; standard About window
+- [ ] Tahoe: no custom bar backgrounds, concentric radii, template menu-bar-extra icons, Icon Composer squircle icon with all variants
+- [ ] Tooltips, right-click menus on every object, multi-item drag & drop with file promises
+- [ ] Undo on every mutation; document model (if content app) with autosave + Versions + proxy icon
+- [ ] System open/save panels, accent color, dark mode, Shortcuts/AppleScript surface
+- [ ] Catalyst/SwiftUI audit: no iPad furniture, explicit toolbar placements, menus wired to window focus
+- [ ] Empty/progress/error states designed; long work non-blocking with Dock progress
+- [ ] Cold launch < 1s to a usable window; state restoration on relaunch verified

package/knowledge/design-languages/material-3.md

@@ -0,0 +1,113 @@
+---
+id: material-3
+title: "Material 3 & Material 3 Expressive"
+category: design-language
+platform: mobile
+tags: [android, material, motion, color, shape, compose, wear-os]
+sources: ["https://m3.material.io/blog/building-with-m3-expressive", "https://m3.material.io/blog/m3-expressive-motion-theming", "https://m3.material.io/styles/shape/corner-radius-scale", "https://m3.material.io/styles/motion/", "https://supercharge.design/blog/material-3-expressive", "https://android-developers.googleblog.com/2025/08/introducing-material-3-expressive-for-wear-os.html", "https://www.androidauthority.com/google-material-3-expressive-features-changes-availability-supported-devices-3556392/", "https://developer.android.com/develop/ui/compose/designsystems/material3", "https://proandroiddev.com/material-3-expressive-design-a-new-era-9ea77959a262"]
+updated: 2026-07-08
+---
+
+# Material 3 & Material 3 Expressive
+
+Material 3 (M3) is Google's design system for Android, Wear OS, and the web. **Material 3 Expressive** (announced May 2025, rolled out through 2025–2026 with Android 16 and Wear OS 6) is its current evolution: springier motion, bolder shapes and color, and a set of new components. Google backed it with 46 research studies and 18,000+ participants; expressive designs tested as both preferred and *more usable* across age groups. As of 2026, M3 Expressive is the default look-and-feel target for new Android apps.
+
+## Core principles
+
+1. **Personal** — Dynamic color derives an app's scheme from the user's wallpaper; apps adapt to the person, not the other way around.
+2. **Adaptive** — Layouts, type, and motion scale across phone, foldable, tablet, Wear OS, and web via tokens and window size classes.
+3. **Expressive** — Shape, motion, and color are used to create emphasis and emotional resonance, not just decoration. Emphasis should map to importance: the most expressive treatment goes to the most important action on screen.
+
+## Color system
+
+- **Dynamic color**: schemes are generated from a source color (wallpaper or brand seed) into tonal palettes (primary, secondary, tertiary, neutral, neutral-variant, error), each with tone steps 0–100.
+- **Roles, not hexes**: always style with roles (`primary`, `onPrimary`, `primaryContainer`, `onPrimaryContainer`, `surface`, `surfaceContainer[Low/High/Highest]`, `outline`, etc.). Never hardcode hex values in components.
+- Expressive pushes **higher saturation and more tonal contrast** between surfaces. Use the `surfaceContainer` ladder to build depth without shadows.
+- Apps may enforce brand colors (static scheme) while still honoring light/dark and contrast preferences. Support the user-selectable **contrast levels** (standard, medium, high).
+
+**Do**
+- Generate light + dark schemes from one seed color; verify on-color contrast (tone delta ≥ 40 between container and on-container roles, e.g., tone 90 container / tone 10 on-container).
+- Use `tertiary` for expressive accent moments (badges, hero highlights).
+
+**Don't**
+- Don't mix dynamic color with hardcoded brand hexes in the same surface hierarchy.
+- Don't use `error` roles for anything but errors/destructive actions.
+
+## Shape system
+
+M3 corner radius scale (tokens, dp):
+
+| Token | Radius |
+|---|---|
+| none | 0dp |
+| extra-small | 4dp |
+| small | 8dp |
+| medium | 12dp |
+| large | 16dp |
+| large-increased | 20dp |
+| extra-large | 28dp |
+| extra-large-increased | 32dp |
+| extra-extra-large | 48dp |
+| full | fully rounded (pill/circle) |
+
+- Typical mapping: chips/small controls → small; cards → medium; FABs/nav drawers → large; bottom sheets/dialogs → extra-large; buttons → full (pill) by default in Expressive.
+- **Expressive shape library**: 35 new non-rectangular shapes (cookie/flower/scallop variants) available in Compose (`MaterialShapes`) and the Figma Material Shapes library. Use them for avatars, loading indicators, and decorative emphasis — not for tap targets whose bounds users must predict.
+- **Shape morphing** is built in: animate one shape to another to signal state (e.g., button square→circle on selection; loading indicator morphing between waveforms). Morphs should ride on spatial spring tokens (below).
+
+## Motion: the physics system
+
+Expressive replaces the old easing + duration model with a **spring physics motion system**. Springs are defined by stiffness (speed/energy) and damping ratio (bounce decay; 1.0 = no bounce, lower = more overshoot).
+
+- **Two motion schemes**:
+  - **Expressive scheme** (recommended default): lower damping, visible overshoot/bounce. Use for hero moments, navigation transitions, key interactions.
+  - **Standard scheme**: high damping, minimal bounce. Use for utilitarian/dense productivity surfaces.
+- **Two token families × three speeds** (fast / default / slow):
+  - **Spatial tokens** — position, size, orientation, shape changes. Configured to allow overshoot.
+  - **Effect tokens** — color, opacity, elevation changes. Critically damped: never bounce color or alpha.
+- Token values are device-class dependent (watch vs phone vs tablet) so "fast" feels fast in context — reference tokens, never raw spring constants.
+- Motion is interruptible and gesture-driven: dismissing a notification drags neighbors with it; springs pick up velocity from the gesture. Pair meaningful physical events with haptics.
+- Legacy easing tokens still exist (`md.sys.motion.easing.standard` cubic-bezier(0.2, 0, 0, 1), emphasized variants; durations short1 50ms → extra-long4 1000ms) for platforms without spring support.
+
+**Do**: use spatial tokens for anything that moves or morphs; effect tokens for fades/recolors; respect "reduce motion" by falling back to the standard scheme or fades.
+**Don't**: don't apply bounce to opacity/color; don't hand-tune spring constants per component; don't make bounce so strong it delays task completion.
+
+## Typography
+
+- Type scale roles: **Display, Headline, Title, Body, Label**, each in small/medium/large. Default face: Roboto / Roboto Flex (variable).
+- Expressive adds **emphasized** styles (heavier weights, tighter tracking) for hero text, and encourages larger, bolder headlines paired with variable-font weight animation.
+- Body text baseline: Body Large = 16sp/24 line height. Labels (buttons): Label Large = 14sp, medium weight.
+
+## New & updated components (Expressive, 2025–2026)
+
+Five headline new components plus updates:
+
+- **Button groups** — containers applying coordinated shape/width/motion to sets of buttons or icon buttons; buttons squish and reshape on press. Work with all button sizes XS–XL. Use for segmented actions and filter rows.
+- **FAB menu** — replaces speed-dial/stacked mini-FABs. Opens from any FAB size/color style; large, high-contrast items. Max ~6 actions.
+- **Loading indicator** — a morphing-shape indicator for waits **under 5 seconds** and pull-to-refresh; replaces most indeterminate circular progress uses. For longer waits keep determinate linear/circular progress.
+- **Split button** — leading action + trailing menu button that spins and morphs when activated. Five sizes (matching button sizes), four styles: elevated, filled, tonal, outlined.
+- **Toolbars (docked & floating)** — the **bottom app bar is deprecated**; replace with the shorter, more flexible **docked toolbar**, or a **floating toolbar** for contextual actions. Toolbars can hold buttons, icon buttons, text, and can pair with a FAB.
+- **Updated**: buttons now come in 5 sizes (XS–XL) with selectable round/square shapes and press morphs; app bars are more customizable (larger flexible titles); progress indicators gained wavy variants; carousels, expanded navigation rail, and grouped list "gap" styling (contained lists with gaps between groups, per late-2025 menu/list redesigns).
+
+## Component quick specs
+
+- Minimum touch target: **48×48dp** (visual element may be smaller).
+- Common button height: 40dp (medium); XS 32dp up to XL 96dp in Expressive sizing.
+- FAB: 56dp (default), 40dp (small), 96dp+ (large/extended variants); large radius or full shape.
+- Elevation levels: 0 / 1 (+1dp) / 2 (+3dp) / 3 (+6dp) / 4 (+8dp) / 5 (+12dp) — prefer tonal surface color over shadow for depth in dark theme.
+- Standard nav: navigation bar (bottom, 3–5 destinations), navigation rail (medium+ widths), navigation drawer (expanded widths).
+
+## When to use Material 3 Expressive
+
+- **Use fully** for consumer Android apps, media/social/lifestyle products, Wear OS apps (Expressive is the Wear OS 6 default), and anywhere brand warmth and engagement matter.
+- **Use the standard motion scheme + restrained shapes** for productivity, enterprise, finance dashboards, and dense data UIs — Expressive components still apply, but dial emphasis down.
+- **Avoid** forcing M3 visuals on iOS builds of cross-platform apps; map tokens to platform-appropriate equivalents instead (see design-tokens-theming.md).
+- Adopt via Jetpack Compose `androidx.compose.material3` (Expressive APIs in material3 1.4+ / `MaterialExpressiveTheme`), MDC-Android, or Material Web components.
+
+## Migration checklist (M3 → M3 Expressive)
+
+1. Swap bottom app bars for docked toolbars; replace speed-dial FABs with FAB menu.
+2. Adopt spring motion scheme tokens; delete hardcoded durations/easings.
+3. Re-map corner radii to the new scale; opt pill buttons into shape-morph press states.
+4. Enable dynamic color with a brand-seeded fallback scheme; test all three contrast levels.
+5. Replace small indeterminate spinners with the loading indicator where waits < 5s.
+6. Audit reduced-motion behavior: springs → fades, morphs → crossfades.

package/knowledge/design-languages/web-trends-2026.md

@@ -0,0 +1,87 @@
+---
+id: web-trends-2026
+title: "Modern Web Design Trends 2025–2026"
+category: design-language
+platform: web
+tags: [web, trends, bento, glassmorphism, brutalism, dark-mode, typography, animation, ai]
+sources: ["https://dev.to/studiomeyer_io/web-design-trends-2026-what-actually-held-up-after-six-months-23p8", "https://studiomeyer.io/en/blog/webdesign-trends-2026-reality-check", "https://www.figma.com/resource-library/web-design-trends/", "https://line25.com/articles/web-design-trends-2026/", "https://midrocket.com/en/guides/ui-design-trends-2026/", "https://lucky.graphics/learn/ui-design-trends-2026/", "https://muz.li/blog/web-design-trends-2026/", "https://www.theedigital.com/blog/web-design-trends", "https://uiuxshowcase.com/blog/21-web-design-trends-2026-design-for-humans-ai-first-web/"]
+updated: 2026-07-08
+---
+
+# Web Design Trends 2025–2026 — What Works, What Doesn't
+
+A prescriptive, mid-2026 reality check. Trends below are graded by real-world adoption, not hype. Use this to decide what to recommend, what to use sparingly, and what to skip.
+
+## Tier 1 — Proven, adopt by default
+
+### Bento grids
+Modular, mixed-size card layouts (Apple-popularized) are now a **default layout approach** for feature sections, dashboards, and portfolios. Measured ~**23% more scroll depth** vs traditional 12-column layouts; adopted by Apple, Google, Microsoft, Spotify.
+- **Do**: build with CSS Grid (`grid-template-areas` or dense auto-flow); vary cell sizes to encode importance (biggest cell = primary message); keep 12–24px consistent gaps; one interactive focus per cell; collapse to single column on mobile.
+- **Don't**: don't cram equal-weight content into every cell (bento without hierarchy is just a broken grid); don't exceed ~8 cells per section.
+
+### Dark mode as a first-class theme
+~**82% of smartphone users** run at least one app in dark mode; dark-aware sites measured ~18% longer sessions. Mature teams now **design dark first** (or in parallel), never as an inverted afterthought.
+- **Do**: use semantic tokens so themes are a value swap (see design-tokens-theming.md); use dark gray surfaces (#121212–#1E1E1E), not pure black, with elevation = lighter surface; desaturate accent colors ~10–20% in dark; respect `prefers-color-scheme` and persist a manual toggle; check 4.5:1 contrast both ways.
+- **Don't**: don't invert shadows (use surface lightness for depth); don't use saturated brand colors on dark at full strength (halation); don't ship pure-white text (#FFF → use ~#E6E6E6 / 87% opacity).
+
+### Design systems + tokens
+Every serious 2026 project ships a token system, component library, and automated visual regression tests. This is infrastructure, not a trend.
+
+### Variable fonts
+Now infrastructure, not optional: one variable file replaces many static weights, cutting font payload dramatically. Used for responsive/fluid typography (weight and optical size interpolate with viewport via `font-variation-settings` and `clamp()`), and subtle interactive weight shifts on hover/scroll.
+- **Do**: subset + `woff2`; pair a characterful display face with a workhorse body face; use fluid type scales (`clamp(1rem, 0.9rem + 0.5vw, 1.25rem)`).
+- **Don't**: don't animate axes on body text; don't load more than 2 font families.
+
+### Micro-interactions
+Small functional animations (button press morphs, checkbox ticks, progress with personality, hover reveals) are the expected polish layer and a narrative tool: they explain cause and effect.
+- **Specs**: state feedback 100–200ms; component transitions 200–300ms; ease-out on enter, ease-in on exit; springs for tactile elements. Always honor `prefers-reduced-motion`.
+- **Rule**: every interactive element needs visible hover, active, focus-visible, and disabled states — this is the cheapest quality signal in web UI.
+
+### Scroll-driven animations (CSS-native)
+The CSS Scroll-Driven Animations spec (`animation-timeline: scroll()` / `view()`) is supported across Chrome, Edge, Firefox, and Safari — scroll-linked reveals, progress bars, and parallax **without JavaScript**.
+- **Do**: use for progressive reveals, reading-progress indicators, subtle parallax (≤ 10–20px translation); treat as progressive enhancement with `@supports`; gate behind `prefers-reduced-motion`.
+- **Don't**: don't scroll-jack (hijacking wheel velocity still tests terribly); don't animate layout properties (stick to transform/opacity); don't gate content comprehension on animation completing.
+
+## Tier 2 — Real but use sparingly
+
+### Glassmorphism (post-Liquid Glass evolution)
+Apple's Liquid Glass renewed the frosted-glass wave, but on the web `backdrop-filter` costs **15–30% FPS on real devices**. 2026 best practice: glass communicates *information architecture* — a floating layer above content — and is confined to **navigation bars, headers, and modals only**.
+- **Specs that work**: `backdrop-filter: blur(10–16px) saturate(1.4–1.8)`; background `rgba` fill 55–75% opacity; 1px inner border at ~15% white (light) / ~8% white (dark); one glass layer maximum — never glass on glass.
+- **Don't**: no glass hero sections or card grids; always ship a solid-color `@supports not (backdrop-filter: blur(1px))` fallback; verify text contrast over the busiest possible background.
+
+### Brutalism / anti-grid
+An active **counter-movement to AI-generated sameness**: deliberately broken layouts, raw HTML aesthetics, monospace type, harsh borders, unpolished color. Also visible as hand-drawn scribbles/annotations layered over clean UI.
+- **When**: differentiation plays — studios, fashion, music, editorial, personal sites.
+- **When not**: conversion-critical B2B, e-commerce checkout, accessibility-sensitive products. Brutalism must still pass contrast and keyboard navigation; "raw" is a style, not an excuse.
+
+### Expressive/kinetic typography
+Oversized headlines, mixed serif+sans pairings, and text as hero imagery are strong 2026 moves. Full kinetic typography (morphing, scroll-reactive letterforms) mostly stayed a demo-reel technique: it fights screen readers and crawlers and causes layout shift that hurts Core Web Vitals.
+- **Do**: big static type with one animated accent moment; animate opacity/transform of whole lines, not letter-by-letter reflow; keep animated text out of the accessibility tree's critical path (aria-label the final text).
+
+### 3D & WebGL
+Underdelivered at scale: a single Spline scene ships 0.8–2MB of JS. Reserve for brand-critical hero experiences (product configurators, launches); lazy-load, cap at one scene, provide a static poster fallback.
+
+## Tier 3 — New in the AI era
+
+### AI readability as a design layer
+The unexpected winner of 2026: designing for machine readers alongside humans. Structured data (schema.org), **llms.txt**, and **agents.json** drive citations in AI answers/copilots (one studio tracked 2,300 Bing Copilot citations in 3 months from structured-data work). Semantic HTML, real headings, and server-rendered content are now discovery-critical, not just a11y hygiene.
+- **Do**: semantic landmarks, one h1, descriptive alt text, schema markup on products/articles/FAQs, llms.txt at root; keep key content out of JS-only rendering.
+
+### AI-era aesthetics & personalization
+AI-assisted layout/personalization exists but shipped conservatively (GDPR pressure in the EU). The visible aesthetic response is *humanist*: hand-drawn elements, imperfect textures, grain/noise, photography over generic AI imagery — signals of human authorship as a trust marker.
+
+### Conversational & adaptive UI
+Chat-style entry points and intent-driven interfaces (search-as-command-palette, ⌘K patterns) are standard in SaaS. Design them as first-class navigation, with keyboard access and clear affordances for what the AI can do.
+
+## Quick prescriptive checklist for a 2026-grade site
+
+1. Token-based theming with parallel light/dark from day one.
+2. Bento-style modular sections with real hierarchy; single-column mobile.
+3. One variable display font + one body font, fluid type scale.
+4. Micro-interactions on all interactive elements; 150–300ms; reduced-motion safe.
+5. CSS scroll-driven reveals as progressive enhancement; no scroll-jacking.
+6. Glass only on nav/modals with fallbacks; solid content surfaces.
+7. Semantic HTML + schema + llms.txt for AI discovery.
+8. Core Web Vitals budget: LCP < 2.5s, CLS < 0.1, INP < 200ms — trends never override performance.
+9. WCAG 2.2 AA: contrast, focus-visible, 24px minimum target spacing.
+10. One signature "wow" moment per page, not five.