saglitzdesign-mcp 0.3.1

package/knowledge/craft/ux-writing.md

@@ -0,0 +1,185 @@
+---
+id: ux-writing
+title: "UX Writing — Interface Copy That Reduces Cognitive Load"
+category: craft
+platform: both
+tags: [ux-writing, microcopy, errors, empty-states, cognitive-load]
+sources: ["impeccable design skill (local)"]
+updated: 2026-07-08
+---
+
+# UX Writing — Interface Copy That Reduces Cognitive Load
+
+Good UX writing is invisible: users understand instantly without noticing the words. Vague copy creates support tickets and abandonment; specific copy gets users through the task.
+
+## The six clarity rules (apply to every string)
+
+1. **Be specific:** "Enter email," not "Enter value."
+2. **Be concise:** cut every unnecessary word, but never at the cost of clarity.
+3. **Be active:** "Save changes," not "Changes will be saved."
+4. **Be human:** plain language, no system-speak ("System error encountered").
+5. **Tell users what to do next**, not just what happened.
+6. **Be consistent:** one term per concept, everywhere. Variety creates confusion.
+
+## Button and CTA labels
+
+**Never "OK", "Submit", "Yes/No", or "Click here."** Use verb + object that names the outcome:
+
+| Bad | Good | Why |
+|---|---|---|
+| OK | Save changes | Says what will happen |
+| Submit | Create account | Outcome-focused |
+| Yes | Delete message | Confirms the specific action |
+| Cancel | Keep editing | Disambiguates what "cancel" means |
+| Click here | Download PDF | Describes the destination |
+
+Destructive actions name the destruction: **"Delete" not "Remove"** (delete = permanent; remove implies recoverable), and **show the count** — "Delete 5 items," not "Delete selected."
+
+## Error messages — the formula
+
+Every error answers three questions: **(1) What happened? (2) Why? (3) How do I fix it?**
+
+"Email address isn't valid. Please include an @ symbol." — never "Invalid input."
+
+Templates by situation:
+
+| Situation | Template |
+|---|---|
+| Format error | "[Field] needs to be [format]. Example: [example]" |
+| Missing required | "Please enter [what's missing]" |
+| Permission denied | "You don't have access to [thing]. [What to do instead]" |
+| Network error | "We couldn't reach [thing]. Check your connection and [action]." |
+| Server error | "Something went wrong on our end. We're looking into it. [Alternative action]" |
+
+Hard rules:
+- **Never blame the user.** "Please enter a date in MM/DD/YYYY format," not "You entered an invalid date."
+- **Never humor in errors.** Users are already frustrated; be helpful, not cute.
+- No error codes shown to users; plain language only.
+- Place the error next to its source, connected via `aria-describedby`, and **never wipe the user's form**.
+- Include an example when the fix isn't obvious; link help when it exists.
+
+## Empty states are onboarding moments
+
+Three beats: **(1) acknowledge briefly, (2) explain the value of filling it, (3) give one clear action.**
+
+"No projects yet. Create your first project to get started." — never a bare "No items." An empty state with no action is a dead end.
+
+## Loading and waiting
+
+- **Be specific about the work:** "Saving your draft…" not "Loading…".
+- **Set expectations for long waits:** "Analyzing your data… this usually takes 30–60 seconds." Show progress when possible; offer Cancel where appropriate.
+- **Ban AI-slop loading copy** ("Herding pixels", "Teaching robots to dance", "Consulting the magic 8-ball") — instantly recognizable as machine-generated. Write messages about what the product actually does: "Syncing with your team's changes…".
+
+## Success messages
+
+Confirm what happened + what happens next, briefly: "Settings saved! Your changes take effect immediately." Match the emotional size of the moment — celebrate big wins, stay quiet for routine saves.
+
+## Confirmation dialogs: undo beats confirm
+
+Most confirmation dialogs are design failures — users click through them mindlessly. Prefer: act immediately, show an undo toast, commit when the toast expires. Reserve confirmation for truly irreversible actions (account deletion), high-cost actions, or batch operations.
+
+When you must confirm: name the specific object and consequence — "Delete 'Project Alpha'? This can't be undone." — with specific buttons ("Delete project" / "Keep project"), never "Are you sure?" + Yes/No.
+
+## Forms
+
+- **Placeholders are not labels** — they vanish on input. Always visible `<label>` elements.
+- Show format via placeholder example, not instruction text: label "Date of birth", placeholder "MM/DD/YYYY".
+- Explain *why* you're asking when it isn't obvious ("We use this to calculate local taxes").
+- Instructions before the field, not after. Validate on blur, not per keystroke (exception: password strength).
+
+## Help text and tooltips
+
+Add value beyond the label — answer the implicit question ("What is this?" / "Why do you need it?"). "Choose a username. You can change this later in Settings." Never restate the label ("This is the username field").
+
+## Navigation and wayfinding
+
+Specific, descriptive labels users' language would produce: "Your projects", "Team members" — never internal jargon or generic "Items/Stuff". Always show current location (breadcrumbs, active states, progress indicators) so users never build a mental map from memory.
+
+## Voice vs tone
+
+**Voice** = brand personality, constant everywhere. **Tone** = adapts to the user's moment:
+
+| Moment | Tone |
+|---|---|
+| Success | Celebratory, brief: "Done! Your changes are live." |
+| Error | Empathetic, helpful: "That didn't work. Here's what to try…" |
+| Loading | Reassuring: "Saving your work…" |
+| Destructive confirm | Serious, unambiguous: "Delete this project? This can't be undone." |
+
+Playful voice is a brand choice (a bank can be warm, not wacky) — but tone always sobers up at errors and destructive moments.
+
+## Terminology discipline
+
+Pick one term per concept and enforce it with a glossary:
+
+| Inconsistent | Pick one |
+|---|---|
+| Delete / Remove / Trash | Delete |
+| Settings / Preferences / Options | Settings |
+| Sign in / Log in / Enter | Sign in |
+| Create / Add / New | Create |
+
+Also enforce: one capitalization scheme (Title Case vs Sentence case), one punctuation rule (periods on sentences, not labels), same nouns as neighboring features (a "Workspace" here must not be a "Project" there).
+
+## Kill redundancy
+
+If the heading explains it, the intro paragraph is redundant. If the button is clear, don't caption it. Say it once, say it well.
+
+## Writing for accessibility
+
+- **Link text stands alone:** "View pricing plans," never "Click here" (screen readers list links out of context).
+- **Alt text carries the information, not the image:** "Revenue increased 40% in Q4," not "Chart." Decorative images get `alt=""`.
+- **Icon-only buttons need `aria-label`.**
+
+## Writing for translation
+
+- Plan for expansion: German +30%, French +20%, Finnish +30–40%, Chinese −30% characters (but similar width). Layouts must absorb this.
+- Keep numbers out of sentence templates: "New messages: 3" survives word-order changes; "You have 3 new messages" doesn't.
+- Full sentences as single strings; no concatenation. No abbreviations ("5 minutes ago", not "5 mins ago"). Give translators context about where each string appears.
+
+## Cognitive load: the language layer
+
+Copy is a primary cognitive-load lever. Three load types:
+- **Intrinsic** (the task itself): can't remove — structure it. Break into steps, provide defaults/templates/examples, group related decisions, progressively disclose.
+- **Extraneous** (bad design/writing): pure waste — **eliminate ruthlessly**. Jargon forcing translation effort, unclear labels forcing guesses, redundant text competing for attention, inconsistent patterns preventing learning.
+- **Germane** (learning effort): good load — support it with consistent patterns, feedback that confirms understanding, and onboarding that teaches through action, not text walls.
+
+### The working-memory rule: ≤4
+
+Humans hold about 4 items in working memory (Cowan's revision of Miller). At any decision point count what the user must simultaneously consider:
+- **≤4:** manageable · **5–7:** pushing it — group or disclose progressively · **8+:** overloaded; users skip, misclick, abandon.
+
+Practical caps:
+- Navigation: **≤5 top-level items** (group the rest under clear categories)
+- Form sections: **≤4 fields per visual group**
+- Actions: **1 primary + 1–2 secondary**; the rest go in a menu
+- Dashboards: **≤4 key metrics** visible without scrolling
+- Pricing: **≤3 tiers** (more = analysis paralysis)
+
+### The 8-point cognitive load checklist
+
+- [ ] Single focus: primary task completable without competing distractions
+- [ ] Chunking: information grouped in digestible units (≤4 per group)
+- [ ] Grouping: related items visually together (proximity, borders, shared background)
+- [ ] Hierarchy: what matters most is immediately clear
+- [ ] One decision at a time before the next
+- [ ] Minimal choices: ≤4 visible options per decision point
+- [ ] No memory bridges: nothing must be remembered from a previous screen
+- [ ] Progressive disclosure: complexity revealed only when needed
+
+**Score by failures: 0–1 = low load (good) · 2–3 = moderate (address soon) · 4+ = high (critical fix).**
+
+### Eight named violations and their fixes
+
+1. **Wall of Options** — 10+ undifferentiated choices → categorize, highlight a recommended pick, disclose progressively.
+2. **Memory Bridge** — step 3 needs info from step 1 → keep context visible or repeat it where needed.
+3. **Hidden Navigation** — user must build a mental map → always show current location.
+4. **Jargon Barrier** — domain terms force translation → plain language; define unavoidable terms inline.
+5. **Visual Noise Floor** — everything equal weight → one primary element, 2–3 secondary, everything else muted.
+6. **Inconsistent Pattern** — same action works differently in different places → standardize; same action type = same UI.
+7. **Multi-Task Demand** — reading + deciding + navigating simultaneously → sequence into single steps.
+8. **Context Switch** — hopping between screens to gather info for one decision → co-locate the information each decision needs.
+
+## Copy verification
+
+Before shipping any string: Can it be understood without context? Does the user know what to do next? Is it as short as clarity allows? Does it match terminology elsewhere? Is the tone right for the user's emotional moment?

package/knowledge/craft/visual-craft-standards.md

@@ -0,0 +1,161 @@
+---
+id: visual-craft-standards
+title: "Visual Craft Standards — Expert-Level Polish"
+category: craft
+platform: both
+tags: [craft, polish, alignment, spacing, depth, hierarchy]
+sources: ["impeccable design skill (local)"]
+updated: 2026-07-08
+---
+
+# Visual Craft Standards — Expert-Level Polish
+
+What separates expert UI from amateur UI is rarely the big idea. It is spacing discipline, optical honesty, complete states, and a system applied without exceptions. This file is the pixel-level rulebook.
+
+## The two registers
+
+Every craft decision depends on which register you are in. Name it before polishing:
+
+- **Brand register** (landing pages, marketing, portfolios — design IS the product): asymmetric compositions, fluid spacing via `clamp()`, intentional grid-breaking, rhythm through contrast (tight groupings against generous separations). Safe = invisible.
+- **Product register** (apps, dashboards, tools — design serves the task): predictable grids, consistent densities, familiar patterns. Consistency IS an affordance. Theatrics undermine trust; amplification lives in clarity, not drama.
+
+## Spacing discipline
+
+- **Use a 4pt base scale, not 8pt.** 8pt is too coarse — you constantly need 12px. Working set: 4, 8, 12, 16, 24, 32, 48, 64, 96px.
+- **Every gap comes from the scale.** A random 13px gap is a defect. If a value isn't on the scale, it needs a reason or a fix.
+- **Name tokens by relationship** (`--space-sm`, `--space-lg`), never by value (`--spacing-8`).
+- **Use `gap` for sibling spacing**, not margins — it eliminates margin-collapse hacks and cleanup CSS.
+- **Rhythm, not uniformity.** Equal padding everywhere = no hierarchy. Tight grouping for related elements (8–12px between siblings); generous separation between distinct sections (48–96px). Related things sit close; unrelated things sit far.
+- **Vertical rhythm anchor:** derive vertical spacing from the body line-height. 16px body at 1.5 = 24px unit; vertical gaps should be multiples of it.
+- **Density must match content:** data-dense UIs run tighter; marketing surfaces need air. Cramped and wastefully sparse are both failures.
+
+## Alignment and optical corrections
+
+Geometric correctness is not visual correctness. Experts correct for the eye:
+
+- **Text at `margin-left: 0` looks indented** because of letterform side-bearing. Pull large display text back with roughly `-0.05em` negative margin to optically align with a hard edge.
+- **Geometrically centered icons often look off-center.** Play/triangle icons need a nudge right; directional arrows shift slightly toward their direction. Nudge only when you can see it's wrong — never speculatively.
+- **Icons align to adjacent text optically**, not by bounding box.
+- Enable a grid overlay and inspect. Hunt anything that "feels off" — feeling off is usually a 1–3px alignment defect.
+
+## Visual hierarchy
+
+- **The squint test:** blur your eyes (or blur a screenshot). You must still identify the most important element, the second most important, and the groupings. If everything reads the same weight blurred, hierarchy has failed.
+- **Combine 2–3 dimensions** for strong hierarchy — a heading that is larger AND bolder AND has more space above it. Reference thresholds:
+
+| Tool | Strong | Weak |
+|---|---|---|
+| Size | ≥3:1 ratio | <2:1 ratio |
+| Weight | Bold vs Regular | Medium vs Regular |
+| Color | High contrast | Similar tones |
+| Position | Top/left | Bottom/right |
+| Space | Surrounded by whitespace | Crowded |
+
+- **Use the fewest dimensions that work.** Generous whitespace alone can carry hierarchy; the most polished designs often use just space and weight. Add color/size contrast only when simpler means fail.
+- **The 2-second rule:** the most important content on the screen should be obvious within 2 seconds.
+
+## Cards, containers, grids
+
+- **Cards are overused.** Spacing and alignment create grouping naturally. Use a card only when content is truly distinct and actionable, needs grid comparison, or needs a clear interaction boundary.
+- **Never nest cards inside cards.** Use spacing, typography, and subtle dividers inside a card.
+- **Break card-grid monotony:** vary sizes, span columns, mix card and non-card content. Endless icon+heading+text tiles is a template tell.
+- **Flexbox for 1D, Grid for 2D.** Don't default to Grid when `flex-wrap` is simpler.
+- `repeat(auto-fit, minmax(280px, 1fr))` gives breakpoint-free responsive grids. Named `grid-template-areas` for complex page layouts, redefined per breakpoint.
+- **Container queries for components**, viewport queries for pages. A card in a narrow sidebar should compact itself regardless of viewport.
+- **Don't center everything.** Left-aligned asymmetric composition reads as designed; a strict visible grid reads as confident. The failure mode is splitting the difference into a generic centered stack.
+
+## Depth: shadows, borders, elevation
+
+- **Shadows must be subtle. If you can clearly see it, it's probably too strong.** Build a consistent scale (sm → md → lg → xl) and use elevation to reinforce hierarchy, never as decoration.
+- **Semantic z-index scale, never arbitrary numbers:** dropdown (100) → sticky (200) → modal-backdrop (300) → modal (400) → toast (500) → tooltip (600). `z-index: 9999` is a defect.
+- **Dark mode depth comes from surface lightness, not shadows.** Build a 3-step surface scale where higher elevation = lighter (e.g. 15% / 20% / 25% OKLCH lightness), same hue/chroma as the brand color.
+- Borders: reduce thickness or opacity before adding more of them. Heavy alpha/transparency use is a design smell — it signals an incomplete palette and creates unpredictable contrast.
+
+## Color craft (the polish-level rules)
+
+- **Never pure gray or pure black.** Add 0.005–0.015 chroma tinted toward the project's brand hue. Real surfaces always have a color cast.
+- **Never gray text on a colored background** — it reads washed-out and dead. Use a darker shade of that background color, or transparency of the foreground.
+- **60-30-10 by visual weight:** ~60% neutral surfaces/whitespace, ~30% secondary (text, borders), ~10% accent. Accents work because they are rare.
+- Placeholder text still needs 4.5:1 contrast. Light-gray-on-white placeholders are the #1 accessibility fail.
+
+## Touch targets and interactive completeness
+
+- **44×44px minimum touch targets.** Visual size can be smaller — expand the hit area with padding or a pseudo-element:
+
+```css
+.icon-button { width: 24px; height: 24px; position: relative; } /* visual size */
+.icon-button::before { content: ''; position: absolute; inset: -10px; } /* 44px hit area */
+```
+
+- Every interactive element ships all eight states: default, hover, focus-visible, active, disabled, loading, error, success. A missing state is a broken experience, not a nice-to-have.
+- Focus rings: 2–3px thick, offset outside the element, ≥3:1 contrast against adjacent colors, consistent everywhere. Never `outline: none` without a `:focus-visible` replacement.
+
+## The polish pass (order matters)
+
+1. **Never polish before functional completeness.** Polish is the last step.
+2. **Align to the design system first.** Polish without alignment is decoration on drift. For every deviation, name the root cause: **missing token** (patch the system), **one-off implementation** (swap to the shared component), or **conceptual misalignment** (flow/IA doesn't match neighboring features — rework the flow). Fixing symptoms without naming the cause compounds drift.
+3. **Check flow shape, not just surface.** Progressive disclosure depth, modal-vs-page, save-on-blur vs explicit submit, and naming ("Workspace" here must not be "Project" there) must match adjacent features. A settings page exposing 40 fields when the rest of the app reveals 5 at a time is drift even if perfectly styled.
+4. **Triage cosmetic vs functional.** Functional (breaks/blocks/confuses) ships first; cosmetic can follow. Never perfect one corner while leaving another rough — quality must be consistent.
+5. **Then sweep:** alignment/spacing → typography (hierarchy, widows, measure) → color/contrast/tokens → all interaction states → transitions (150–300ms, ease-out family, never bounce/elastic) → copy consistency (terminology, capitalization, punctuation) → icons (one family only) → forms → edge cases (empty/error/loading/long-content) → responsive (44px targets, ≥14px mobile text, no horizontal scroll) → performance (no CLS, 60fps) → code hygiene (no console logs, dead code, `any`).
+6. **Verify by using it yourself**, at multiple viewports, in every state — not just the happy path. Automated detector output is defect evidence only, never proof of quality.
+
+### The full polish checklist
+
+- [ ] Aligned to the design system; every drift named and resolved by root cause
+- [ ] Flow shape and IA match neighboring features
+- [ ] Visual alignment perfect at all breakpoints; spacing entirely from tokens
+- [ ] Typography hierarchy consistent; no widows on headings; measure in range
+- [ ] All eight interaction states implemented on every interactive element
+- [ ] All transitions smooth (60fps), 150–300ms, ease-out family
+- [ ] Copy consistent: one term per concept, one capitalization scheme, one punctuation rule
+- [ ] Icons from a single family, consistently sized, optically aligned to text
+- [ ] Forms labeled and validated; logical tab order; consistent validation timing
+- [ ] Error states helpful; loading states clear; empty states welcoming with an action
+- [ ] Long content, missing data, and overflow handled gracefully
+- [ ] Touch targets ≥44×44px; mobile text ≥14px; no horizontal scroll
+- [ ] Contrast meets WCAG AA; keyboard navigation complete; focus visible
+- [ ] No console errors; no layout shift on load; reduced motion respected
+- [ ] Code clean: no TODOs, console.logs, commented-out code, unused imports
+
+### Post-polish cleanup
+
+- Swap any custom reimplementation for the design-system component it duplicates.
+- Delete orphaned styles/components made obsolete by the polish.
+- Promote repeated new values into tokens; consolidate duplication introduced while polishing.
+
+## Making a design quieter (restraint with precision)
+
+Quiet is harder than loud; subtlety needs precision. Quiet ≠ generic — think luxury, not laziness.
+
+- Desaturate to **70–85% of full saturation**; let neutrals dominate; keep color as a 10% accent.
+- Step weights down: 900 → 600, 700 → 500. Carry hierarchy with weight, size, space instead of color and boldness.
+- Reduce borders (thinner, lower opacity, or gone), flatten layering, strip gradients/glows/multi-shadows that serve nothing.
+- Shrink motion: 10–20px travel instead of 40px, ease-out-quart, remove decorative animation entirely.
+- Reduce scale jumps and even out spacing extremes for calm.
+- **Never:** flatten all hierarchy, remove all color, or erase the point of view. Restrained, not absent — the POV must survive the cuts.
+
+## Making a design bolder (impact without slop)
+
+"Bolder" defaults to slop: cyan/purple gradients, glassmorphism, neon-on-dark, gradient metric text. Reject those first. Bold = distinctive and committed, not "more effects."
+
+- **Pick ONE hero moment** and make it exceptional; amplify contrast around it (big things bigger, small things smaller).
+- Typography: 3×–5× size jumps (not 1.5×); pair weight 900 with 200, not 600 with 400; distinctive faces, variable fonts, condensed/extended widths.
+- Color: let one bold color own ~60% of the design; tinted neutrals; sharp accents; intentional multi-stop gradients — never the stock purple-to-blue.
+- Space: 100–200px section gaps, grid-breaking hero elements, asymmetric tension, 70/30 or 80/20 splits instead of polite symmetry.
+- Texture over glass: grain, halftone, duotone, geometric pattern. Not glassmorphism.
+- Motion: staggered entrance choreography with 50–100ms delays, ease-out-quart/quint/expo. Never bounce or elastic — they cheapen everything.
+- **The test:** if someone would instantly believe "AI made this bolder," it failed.
+
+## Amateur tells — the ban list
+
+- Arbitrary spacing values; equal spacing everywhere
+- Everything wrapped in cards; cards nested in cards; identical icon+heading+text grids
+- Everything centered; the hero-metric template (big decorative number, small label, gradient)
+- Arbitrary z-index (999/9999); visible heavy shadows; shadow-as-decoration
+- Pure #000 / pure gray; gray text on colored backgrounds
+- Hover-only functionality; missing focus states; sub-44px targets
+- Hard-coded values where tokens exist; one-off components duplicating system ones
+- Bounce/elastic easing; animation as loading camouflage
+- Polishing one screen while the system-level defect stays (if spacing is off everywhere, fix the scale, not the screen)
+
+**The exit bar:** every screen defensible in a high-end studio review. Zoom in. Squint. Use it yourself. The little things are the work.

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

@@ -0,0 +1,197 @@
+---
+id: android-app-design
+title: "Android App Design — Complete Guide"
+category: design-language
+platform: mobile
+tags: [android, material, navigation, play-store, adaptive]
+sources: ["https://developer.android.com/about/versions/16/behavior-changes-16", "https://developer.android.com/guide/navigation/custom-back/predictive-back-gesture", "https://developer.android.com/design/ui/mobile/guides/patterns/predictive-back", "https://developer.android.com/develop/ui/views/layout/use-window-size-classes", "https://developer.android.com/design/ui/mobile/guides/layout-and-content/adapt-layout", "https://m3.material.io/components/navigation-bar/specs", "https://developer.android.com/develop/ui/compose/system/icon_design_adaptive", "https://developer.android.com/develop/ui/views/launch/splash-screen", "https://developer.android.com/docs/quality-guidelines/widget-quality", "https://android-developers.googleblog.com/2025/03/introducing-widget-quality-tiers.html", "https://developer.android.com/docs/quality-guidelines/large-screen-app-quality", "https://support.google.com/googleplay/android-developer/answer/9866151", "https://www.androidauthority.com/google-material-3-expressive-features-changes-availability-supported-devices-3556392/"]
+updated: 2026-07-08
+---
+
+# Android App Design — Complete Guide (Android 16 / Material 3 Expressive era)
+
+Structural, app-level guide for Android apps. The general Material 3 system (color roles, shape scale, motion springs, component visuals) lives in the M3 doc — this covers what Android itself demands: app anatomy, system gestures, insets, adaptive layouts, icons, widgets, notifications, and Play Store presence.
+
+Baseline assumptions for 2026: targetSdk 36 (Android 16), Jetpack Compose, Material 3 Expressive components rolling out across Google's own apps since September 2025 (Pixel Android 16 QPR1 onward).
+
+## 1. App anatomy — pick navigation by window size class, not device
+
+Android apps are trees of destinations, not stacks of screens. Choose ONE top-level pattern and let it adapt:
+
+- **Navigation bar (bottom)** — 3–5 peer destinations, compact width (< 600dp). The default for phones.
+  - M3 Expressive "flexible" bar: shorter container (**64dp** vs the classic 80dp).
+  - Active indicator pill **≥ 56×32dp** around a **24dp** icon; label **12sp**, always visible for ≤ 4 destinations (selected-only labels allowed at 5, but avoid).
+  - Horizontal variant (icon beside label in a wider pill) for wider compact windows.
+  - Icons: outlined when inactive, filled when active (Material Symbols pairs).
+- **Navigation rail (side)** — the same 3–7 destinations at medium/expanded width (≥ 600dp).
+  - Collapsed rail **96dp** wide, destinations stacked vertically, top slot for FAB or menu button.
+  - M3 Expressive adds an **expanded rail** (~**220dp**, icon + label rows) that replaces the standard drawer as the wide-screen navigation surface.
+- **Navigation drawer (modal)** — M3 Expressive **deprecates the standard (persistent) drawer**; keep a *modal* drawer only for 7+ destinations or account/label/workspace hierarchies (Gmail labels, Phone app contacts). Sheet width ≤ **360dp**, item height **56dp**, active item gets a full-width shape pill.
+- **Bottom app bar** — largely superseded by the M3E docked toolbar; don't build new UI on it.
+- **Rule: bar ↔ rail must mirror each other.** Same destinations, same order, same icons. The app swaps between them as the window resizes (fold/unfold, split-screen, desktop window) — never show both at once.
+- Tabs (primary/secondary) subdivide content *within* a destination — never use tabs as top-level app navigation (the pre-2015 pattern WhatsApp finally abandoned).
+- Each bottom-bar destination keeps its **own back stack**; switching destinations preserves state (`saveState`/`restoreState` in Navigation). Re-selecting the current destination pops its stack to root.
+- Deep-link every content screen (App Links + `navDeepLink`). Widgets, notifications, shortcuts, and the sharesheet all need stable routes in.
+
+### Top app bar
+- Small top app bar **64dp** tall; medium **112dp**; large **152dp**, collapsing to small on scroll (collapse behavior via `TopAppBarScrollBehavior`).
+- Title is **left-aligned** by default (a center-aligned variant exists, but left is the Android convention — don't import iOS centering reflexively).
+- Up affordance is a **← arrow** (not a chevron, never with a text label). Up goes to the logical parent; system back can differ (see §2).
+- 2–3 icon actions max on the trailing side; everything else in the ⋮ overflow menu.
+- M3 Expressive search app bar: full-width pill search field in the app bar slot, hamburger/avatar sitting *outside* the pill (Gmail/Keep/Chat 2025 pattern).
+- Contextual action bar replaces the top app bar during multi-select: long-press enters selection, bar shows count + batch actions, back/✕ exits.
+
+## 2. Back: predictive, system-wide, non-negotiable
+
+- Back is a **system gesture** (edge swipe from either side, or the 3-button back triangle). Every screen, sheet, dialog, menu, and selection mode must respond to it. There is no "screen without back" on Android.
+- **Predictive back is enabled by default** for apps targeting Android 16 (API 36): back-to-home, cross-activity, and cross-task animations play as the user drags.
+  - `onBackPressed()` is no longer called and `KEYCODE_BACK` is not dispatched for these apps — legacy back interception silently breaks.
+  - Migrate to `OnBackPressedCallback` / Compose `PredictiveBackHandler`; the manifest opt-out (`android:enableOnBackInvokedCallback="false"`) is a temporary crutch, not a strategy.
+- Design rule: the user must be able to **peek** — during the drag, the current surface scales down (to ~90%) revealing the destination beneath, and releasing either commits or cancels. Consequences:
+  - The back destination must be computed *before* the gesture commits.
+  - No "Are you sure you want to exit?" dialogs on back — reserve interception for genuine unsaved-data loss, and even then prefer auto-save/draft.
+  - No back that navigates *forward*, no back-traps on onboarding or paywalls.
+- Back vs Up: back follows the user's actual history (and can cross apps); Up stays inside your hierarchy. From a deep link, Up goes to the parent with a synthesized stack; back returns to the referring app.
+- In-app dismissal order for one back press: keyboard → open menu/dialog → bottom sheet → search view → selection mode → current destination.
+- In-app predictive back should animate too: sheets slide down with the drag, search views collapse back into their bar, list-detail returns to the list. Compose `NavHost` + `SearchBar` + M3 sheets support this natively — custom surfaces must implement `PredictiveBackHandler` progress.
+- Shared-element transitions between destinations that track the back drag are the current polish bar (Google apps, Telegram).
+
+## 3. Edge-to-edge & insets — mandatory, not a style choice
+
+- Targeting SDK 35 (Android 15) forced edge-to-edge with an opt-out attribute; **targeting SDK 36 disables the opt-out** (`windowOptOutEdgeToEdgeEnforcement` is deprecated and ignored on Android 16 devices). Your app *will* draw behind the status bar and the navigation area.
+- Status bar and gesture nav bar are **transparent**. System icon contrast is your responsibility (`WindowInsetsControllerCompat.isAppearanceLightStatusBars` per screen, or per-theme).
+- Never hardcode inset heights (the old 24dp status bar / 48dp nav bar assumptions). Real values vary with display cutouts, foldable postures, 3-button vs gesture nav, and font/display scaling — always read `WindowInsets`.
+- Apply insets **per surface**, not as one global padding:
+  - Top app bar consumes `statusBars` + `displayCutout` (its container extends under the status bar; its content sits below).
+  - Scrolling content: content scrolls *under* the transparent nav bar, with bottom `contentPadding` so the last item can clear it.
+  - Bottom nav bar / docked toolbars: container extends to screen bottom, content padded by `navigationBars` insets.
+  - FABs and bottom sheets offset by `navigationBars`; text fields and sheet CTAs by `ime` insets (keyboard).
+  - Compose `Scaffold` wires most of this via `contentWindowInsets` — don't fight it with manual spacers.
+- 3-button navigation still matters (roughly a third of users): the bar region is taller and opaque-feeling; verify no bottom UI collides. Test every screen in both modes.
+- Let imagery, maps, and feeds flow full-bleed behind system bars; keep *interactive* elements out of inset regions and away from bottom-corner gesture zones.
+- Gesture conflicts: horizontal carousels/sliders near screen edges fight the back gesture — inset them, or use `systemGestureExclusionRects` sparingly (max ~200dp of exclusion is honored).
+- Status-bar scrim hacks (gradient "protection" overlays) are deprecated styling; rely on tonal surfaces and scroll-under elevation change instead.
+
+## 4. Adaptive layouts — window size classes, not "phone vs tablet"
+
+- Classify by **window**, not device. Width classes: **compact < 600dp**, **medium 600–840dp**, **expanded 840–1200dp**, **large 1200–1600dp**, **extra-large ≥ 1600dp** (height classes exist separately).
+- Split-screen puts flagship phones into compact-or-smaller; an unfolded Fold is medium/expanded; a phone in landscape is compact-height. Design to classes and you cover foldables, tablets, ChromeOS, and desktop windowing in one pass.
+- Canonical adaptive layouts (the Compose Material 3 adaptive library implements them):
+  - **List-detail** — list pane + detail pane side-by-side at expanded+; compact shows one pane at a time with predictive back between panes.
+  - **Supporting pane** — primary content + contextual secondary pane (comments, filters, now-playing queue).
+  - **Feed** — responsive grid (`LazyVerticalGrid(columns = Adaptive(minSize = 240.dp))` style) that reflows column count.
+- Pane sizing: common splits are a fixed **360dp** list + fluid detail, or 50/50. Readable text measure caps at ~**640dp**; center a form on a 900dp window, never stretch it full-bleed.
+- Navigation adapts with layout: bottom bar (compact) → rail (medium) → expanded rail (expanded+), per §1.
+- Foldables: observe `FoldingFeature` — in tabletop posture (half-folded, hinge horizontal) put content on the top half and controls on the bottom; never place critical UI across the hinge in dual-pane postures. Trifolds add a second hinge — the same rules apply per fold.
+- **Android 16 ignores orientation, aspect-ratio, and resizability restrictions on displays ≥ 600dp.** Portrait-locking is no longer a shipping strategy — on tablets/foldables your locked app gets resized anyway. Fix the layouts.
+- State must survive rotation, folding, window resize, and process death (`rememberSaveable`, SavedStateHandle). A resize that loses a half-written form fails core app quality.
+- Play ranks and badges by **adaptive/large-screen quality tiers** (Tier 2 "optimized" = layouts + input support; Tier 1 "differentiated" = multitasking, drag-and-drop, stylus, posture support). Tablet/foldable/ChromeOS store placement depends on it.
+- Support keyboard/mouse basics at Tier 2: focus states, Enter/Escape handling, hover states, right-click context menus where natural.
+
+## 5. Dynamic color & theming in practice
+
+- Material You: the system extracts tonal palettes from the user's wallpaper. Opt in with `dynamicColorScheme(context)` and fall back to your brand `ColorScheme` below API 31.
+- Practical stance by app type:
+  - **Utilities and Google-adjacent tools** — adopt dynamic color fully; users expect the app to match their device.
+  - **Strong consumer brands** (Spotify, Airbnb, banks) — keep brand color for primary actions and identity moments; optionally map neutrals/surfaces to dynamic tones.
+  - **Never half-adopt** — brand-green buttons floating on wallpaper-pink dynamic surfaces reads as broken.
+- Whatever the palette source, always design through **M3 color roles** (primary, secondary, surfaceContainer levels, onSurfaceVariant, outline…), never raw hex in components. Roles are what make dynamic color, dark theme, and contrast settings work for free.
+- Dark theme is required, not optional: tone-shifted palettes, not inverted colors; elevation expressed by lighter surfaceContainer levels, not shadows. Default theme setting = "System default".
+- Test the same screens against 4–5 wallpapers × light/dark. Users can also select medium/high contrast schemes (Android 14+) — role-driven UI adapts automatically; hardcoded exceptions don't.
+- App icon, widget, and splash should participate: themed icon (§6), dynamic-color widget backgrounds (§8), splash background from theme (§7).
+
+## 6. App icon — adaptive + themed, no exceptions
+
+- Adaptive icon: **108×108dp** canvas, separate **background** and **foreground** layers (vectors preferred). The outer 18dp ring on each side exists for launcher parallax/resize effects.
+- Keep all critical content inside the **66dp** central safe zone — OEM launchers mask to circle, squircle, rounded square, etc. Never bake your own outline shape, mask, or drop shadow into the layers.
+- **Themed (monochrome) icon** — Android 13+: provide a `<monochrome>` layer.
+  - Single flat glyph, roughly the foreground silhouette, drawn in one color (the system tints to the wallpaper palette, light and dark).
+  - Keep the glyph inside the center safe zone with comfortable margin; no gradients, no wordmarks, no fine detail.
+  - Missing themed icon = your icon is the untinted odd-one-out (or a dull auto-generated tint) on themed home screens — a top "unmaintained app" signal in 2026.
+- Legacy square PNG icons get shrunk into a white circle by modern launchers — instant abandonware look.
+- Long-press **app shortcuts** (static + dynamic; ~4 shown, pinnable to home screen): each needs an icon built on the shortcut template (24dp glyph on a themed circular plate) and a clear 1–2 word label. Treat shortcuts as designed entry points (Compose, Search, Scan…), not an afterthought.
+
+## 7. Splash screen — system API only
+
+- Android 12+ shows a system splash for every cold start whether you design one or not. Use the **SplashScreen API** (`Theme.SplashScreen` / `installSplashScreen()`); a custom splash *activity* now produces an awkward double splash.
+- Element specs:
+  - Icon without a background plate: **288×288dp** canvas, visible glyph within a **192dp** diameter circle.
+  - Icon with its own background plate: **240×240dp**, glyph within a **160dp** circle.
+  - Optional branding image: **200×80dp**, bottom-center — use sparingly; Google's guidance treats it as discouraged-but-supported.
+  - Window background: one color, themed for light/dark (use your surface or brand tone).
+- Default (and correct) behavior is reusing your adaptive icon — verify it survives the circular crop.
+- Animated vector icon allowed; total splash presence should stay ≤ **1000ms** on warm hardware. Never add artificial delay; never show ads, tips, or marketing on the splash.
+- Hold with `setKeepOnScreenCondition { !uiReady }` only until first real content frame; use the exit listener to animate the icon into your UI (shared-element style) for a premium feel.
+
+## 8. Widgets (Glance)
+
+- Build with **Jetpack Glance** (Compose-style API compiling to RemoteViews). Widgets got a 2025 push: a dedicated widget discovery surface and badge on Play, plus **quality tiers** (Tier 1 differentiated / Tier 2 standard / Tier 3 low) scored on layout, color, discovery, and content.
+- Visual rules:
+  - Corner radius from `@android:dimen/system_app_widget_background_radius` (capped **28dp**); inner containers use outer radius − padding.
+  - Use the dynamic-color widget theme (`@style/Theme.DeviceDefault.DayNight` / Glance `GlanceTheme`) so the widget sits naturally on any wallpaper, light and dark.
+  - **16dp** internal padding; touch targets ≥ **48dp**; text at sp so it scales.
+- Responsive, not scaled: define size buckets via `SizeMode.Responsive` (e.g. 2×1, 2×2, 4×2, 4×4 — launcher grid cells vary ~57–70dp so design to dp breakpoints, not cells). Content reflows between buckets; nothing stretches.
+- Use the canonical Glance layouts (Google publishes them) as Tier-1 scaffolds: they encode correct padding, radius, and reflow.
+- Every widget needs: a real-content preview (the API 35 generated-preview path keeps it honest), a deep-link tap action on every meaningful element (never just "opens app home"), and designed empty/loading/error/sign-in states.
+- Configuration screen only when genuinely needed; prefer sensible defaults + reconfigure via long-press.
+
+## 9. Notifications
+
+- **Channels are mandatory** (API 26+): one channel per user-meaningful category (messages, mentions, promos, playback, reminders…), each with honest default importance. Users block channels, not the whole app — if you segment honestly, one annoying campaign doesn't kill your transactional notifications.
+- Runtime permission (Android 13+): ask in context after demonstrating value (e.g., after the user follows something), never as a cold-start popup. Design the pre-permission moment.
+- Small icon: **24dp**, pure white-on-transparent silhouette — the system tints it; colored or detailed icons render as grey blobs. Accent color via `setColor`. Large icon (avatar, album art) is a separate ≥ 48dp slot.
+- Use semantic **styles**, don't rebuild layouts:
+  - `MessagingStyle` for anything conversational — unlocks conversation space ranking, bubbles, per-person avatars, and direct reply.
+  - `BigPictureStyle` / `BigTextStyle` / `InboxStyle` for media, long text, digests.
+  - `MediaStyle` for playback — Android 13+ ignores custom media layouts; the system template with actions is the design.
+  - Android 16 **ProgressStyle / Live Updates** for trackable ongoing events (delivery, rideshare, navigation) — points on a progress tracker, promoted status-bar chip.
+- Max 3 action buttons, verb labels (Reply, Archive, Snooze — never "OK"). Group bursts with a summary notification. Every notification deep-links to the exact relevant screen, with correct Up/back from there.
+- Never: notification-as-ad (Play policy violation), persistent "app is running" noise without user value, or re-posting to defeat a user's swipe-dismiss.
+
+## 10. Haptics
+
+- Use **semantic constants**, not raw vibration: `HapticFeedbackConstants.CONFIRM`, `REJECT`, `LONG_PRESS`, `KEYBOARD_TAP`, `CLOCK_TICK`/`SEGMENT_TICK` and `SEGMENT_FREQUENT_TICK` (pickers, sliders), `TOGGLE_ON`/`TOGGLE_OFF`, `GESTURE_START`/`GESTURE_END`, `DRAG_START`. These route to device-tuned effects.
+- `vibrate(100)`-style duration buzzes are the #1 cheap-feeling tell on Android. Don't.
+- Compose: `LocalHapticFeedback.current.performHapticFeedback(HapticFeedbackType...)`. Richer feedback via `VibrationEffect` predefined effects (CLICK, TICK, DOUBLE_CLICK, HEAVY_CLICK) and composition primitives (`PRIMITIVE_CLICK`, `PRIMITIVE_TICK`, ramps) on capable hardware — check `areAllPrimitivesSupported()` and degrade gracefully.
+- Where haptics belong: long-press entering selection, drag-and-drop pickup/drop, slider detents and picker ticks, pull-to-refresh threshold, toggle flips, success/failure of biometric or payment confirms, error shakes.
+- Where they don't: every tap, scroll ticks on ordinary lists, passive content, marketing moments.
+- Android haptic hardware quality varies enormously — haptics must be decorative reinforcement, never the only feedback channel; respect the system "touch feedback" setting (semantic constants do this automatically).
+
+## 11. Play Store listing (ASO)
+
+- **App icon**: 512×512 PNG, 32-bit with alpha. Upload a full-bleed square — Play applies its own mask (~20% corner radius) and drop shadow. Keep key content centered; no baked shadows, no badges, no "#1 / Best" claims (rejection risk).
+- **Feature graphic**: 1024×500 JPG or 24-bit PNG (no alpha). Required for a promo video and for many promotional placements; it sits behind the play button and in curated collections. Keep the logo + one message in the central safe area (edges crop on some surfaces); design it as a poster, not a screenshot collage; readable at thumbnail size.
+- **Screenshots**: 2–8 per form factor (phone, 7" tablet, 10" tablet, ChromeOS; Wear and TV where applicable).
+  - Promotional-surface eligibility: **≥ 4** screenshots at **≥ 1080px**, aspect 16:9 (landscape) or 9:16 (portrait). Practical standard: 1080×1920 or 1080×2400 portrait.
+  - The first 2–3 frames carry nearly all conversion: one message per frame, short benefit caption (≤ ~6 words) at the top, UI below; the actual app UI must appear (policy).
+  - Ship **real tablet screenshots showing tablet layouts** — stretched phone shots hurt large-screen store placement and signal a lazy port.
+  - No competitor references, ranking claims, time-limited offers ("50% off this week"), or "Install now" CTAs baked into imagery. Add alt text to every asset.
+- **Promo video**: a public YouTube URL; first 5 seconds must work muted; landscape; no ads on the video.
+- Listing text: title ≤ **30 chars**; short description ≤ **80 chars** (benefit + primary keyword — it's the only text above the fold); full description ≤ 4000 (first ~3 lines show pre-expansion). Keyword stuffing is penalized; natural phrasing indexes fine.
+- Iterate with Play's built-in **store listing experiments** (A/B on icon, graphics, descriptions) and custom store listings per country/audience — don't redesign on opinion.
+
+## 12. Porting iOS → Android: what MUST change
+
+1. **Back**: delete the top-left "‹ Back" chevron+label; use an ← Up arrow in the app bar and support system/predictive back on every surface. Never make an in-content button the only exit.
+2. **Navigation metaphors**: iOS tab bar → M3 navigation bar (rail ≥ 600dp); iOS large-title header → M3 medium/large collapsing top app bar; push-from-right transitions → Material shared-axis / fade-through with predictive-back support.
+3. **Controls**: SF Symbols → Material Symbols (24dp grid); iOS switch → M3 switch (with check icon); segmented control → segmented buttons / button group; UIDatePicker wheels → M3 date/time pickers (calendar + clock dial); UIAlertController → M3 dialog (text buttons bottom-right, confirming action rightmost) or a bottom sheet when there are 3+ options.
+4. **Action sheets and half-modals → bottom sheets** with a 32×4dp drag handle, drag-to-dismiss, scrim tap, and back-to-dismiss.
+5. **Share**: system sharesheet (`Intent.createChooser`) with your optional custom actions row — never a fully custom share UI. Also *receive*: register intent filters so your app appears in other apps' sheets.
+6. **Typography**: SF Pro → Roboto / Roboto Flex (or brand font) on the M3 type scale; body 16sp, minimum 12sp; sizes in **sp** and layouts that survive 200% font scale (Android 14 non-linear scaling).
+7. **Feedback**: toasts are legacy — snackbars (optional single action, ~4s) for transient results; inline validation for forms; dialogs only for blocking decisions.
+8. **Touch**: 48×48dp minimum targets; ripple on everything tappable (never suppress it); long-press affordances where iOS uses swipe rows or context menus.
+9. **System integration has no iOS source to port** — adaptive + themed icon, app shortcuts, widgets, splash API, notification channels, predictive back, edge-to-edge, dynamic color decision. These must be designed fresh, not skipped.
+10. **Store assets**: never reuse iOS screenshots (iOS status bar, Dynamic Island, iOS keyboard) on Play — credibility loss and policy risk.
+
+## 13. Ship checklist
+
+- [ ] Nav bar (compact) ↔ rail (medium+) mirror; per-tab back stacks preserved; re-tap pops to root
+- [ ] Predictive back animates on every screen and sheet; no back-traps; ships targeting SDK 36 without the opt-out flag
+- [ ] Edge-to-edge verified: gesture nav, 3-button nav, display cutout, keyboard open, light + dark status icons
+- [ ] Every screen works at compact AND expanded width; no orientation lock; state survives fold/rotate/resize
+- [ ] Dynamic color stance chosen deliberately; all color through M3 roles; dark theme + contrast settings pass
+- [ ] Adaptive icon with monochrome layer; app shortcuts designed; SplashScreen API, ≤ 1s hold
+- [ ] Widgets responsive with dynamic color, deep-link taps, empty/error states
+- [ ] Notification channels segmented; 24dp white small icon; MessagingStyle for chat; permission asked in context
+- [ ] Semantic haptics only; 48dp targets; TalkBack + 200% font scale pass on core flows
+- [ ] Play listing: 512 icon, 1024×500 feature graphic, ≥ 4 phone screenshots at 1080px+, real tablet shots, alt text