Md3 Expressive Android

md3 expressive android

overview

Implement android ui with real material 3 expressive, not stale material you minimalism and not random ai-generated spacing. Return production-minded Kotlin and Compose code, complete import blocks, and a short design rationale in the user's language.

This skill is also the authority for:

• android 17 (api 37) platform defaults and capability (baklava)
• navigation 3 (typed/state-driven) and adaptive flexbox/grid layouts
• anti ai slop cleanup and agent semantics for ai-assisted ui
• grouped large plaques with real breathing gaps
• motion and shape choreography
• m3e motion physics and spring-based transitions
• typographic balance on narrow screens
• sources-based inspiration from real app code dropped into Sources/

workflow

1. Classify the request:
   • new screen or feature
   • redesign or polish
   • code review or slop cleanup
   • theme, typography, icon, shape, or motion system
   • dependency or version selection
   • source-ingestion and reference extraction
   • android 15 (api 35) migration or compliance
2. Set the target expression level:
   • default to excellent
   • move to transformational only when the product benefits from stronger identity
   • drop to foundational only when the app is intentionally quiet, dense, or enterprise-like
3. Read supporting references before writing code:
   • read references/expressive-foundations.md for layout, hierarchy, grouped plaques, color discipline, text balance, api 35 edge-to-edge, and anti-slop rules
   • read references/motion-system.md for motion system rules, transition choice, choreography, m3e physics, predictive back, and performance
   • read references/shapes-and-morphs.md for shape selection, corner animation, MaterialShapes, and Compose morphing
   • read references/shape-catalog.md when the task asks for all shapes, a specific expressive polygon, or state-shape APIs
   • read references/typography-and-icons.md for font stack, variable fonts, text hierarchy, material symbols, emphasized styles, and adaptive Monet-aware icons
   • read references/import-map.md whenever generating Compose code or imports
   • read references/droidsearch.md whenever versions, coordinates, plugins, or compatibility are current or uncertain
   • read references/repo-patterns.md for concrete app-style reference directions
   • read references/sources-ingestion.md when Sources/ exists or the user wants learning from example apps
4. If the project contains Sources/ and it is not empty, inspect it before proposing a redesign:
   • run python scripts/analyze_sources.py Sources --format markdown
   • identify recurring layout archetypes, spacing rhythm, component families, motion patterns, color discipline, and icon usage
   • treat those samples as inspiration and quality calibration, not as a target for blind copying
5. If versions or coordinates are current or uncertain, run the bundled tool before writing the dependency block:
   • run python scripts/droidsearch.py gradle --channel stable
   • run python scripts/droidsearch.py agp --channel stable
   • run python scripts/droidsearch.py plugin --plugin-id <plugin-id> --channel any
   • run python scripts/droidsearch.py maven --repo google --group <group> --artifact <artifact> --channel stable
   • run python scripts/droidsearch.py maven --repo central --group <group> --artifact <artifact> --channel stable
   • read the JSON output and copy the exact string from chosen.version; when chosen is preview, also mention latest_stable
6. Inspect the existing code or prompt constraints:
   • identify screen purpose, interaction density, device class, and target sdk constraints
   • identify whether the codebase is stable material3 or alpha material3 expressive
   • identify whether the Google Sans family is licensed or available; otherwise use fallbacks
   • identify whether the task needs corner-based surface shapes, expressive polygons, or both
   • identify whether the current UI is suffering from ai-slop gradients, text imbalance, overlap, or random transparency
7. Produce the solution in this order:
   • design intent
   • component and layout decisions
   • motion decisions
   • shape decisions
   • theme, typography, and icon decisions
   • exact imports
   • complete Kotlin, Compose, XML, or Gradle implementation
   • dependency block when needed
   • QA checklist

hard rules

• remove ai slop. do not stack random Spacers, arbitrary paddings, broken cutouts, decorative gradients, fake glass, or decorative shapes with no hierarchy reason.
• enforce android 17 (api 37) adaptive-by-default behavior. ignore orientation locks on >600dp and ensure layout resilience for resizing and multi-window.
• default to solid tonal surfaces and container colors. do not use gradients unless the product, artwork, or brand specifically benefits from them.
• when a gradient is truly justified, keep it controlled: one main direction, one tonal family, low to medium contrast span, and clear text contrast.
• never use muddy red-on-red, brown-on-red, or low-contrast warm gradients behind dense paragraphs.
• do not use transparency to hide weak layout structure. fix hierarchy first.
• use one intentional spacing rhythm per screen. prefer a clean ladder such as 4, 8, 12, 16, 20, 24, 32 dp.
• audit edge-to-edge and inset math before finalizing. do not double-apply scaffold, ime, or system bar padding.
• keep touch targets usable. prefer 48 dp interactive minimum unless a platform component already guarantees it.
• make expressive choices purposeful. do not make every surface loud, oversized, rounded, elevated, colorful, translucent, or morphing at the same time.
• balance long text blocks. do not let a hero paragraph dominate the whole screen while actions collapse into corners or drift off-grid.
• prefer Material 3 Expressive components and expressive sizing when the installed library version supports them.
• never claim a component or shape API is available unless the current dependency set or droidsearch or web verification supports it.
• never invent or round version strings. preserve qualifiers exactly, including -alpha, -beta, -rc, patch digits, and group or artifact names.
• prefer rounded icon style by default for friendly, productivity, and media apps unless a stricter tone calls for another style.
• keep explanations in the user's language. keep code, XML, Gradle, and import identifiers in their original language.

anti ai slop rules

Use these to catch the exact failures common in AI-generated mobile screens:

• do not fake richness with giant full-screen gradients when neutral or tonal container colors would solve the screen better
• do not place a pale button beside a muddy translucent plaque unless both belong to one intentional contrast plan
• do not let two bottom actions fight for attention through mismatched width, weight, opacity, or corner radii
• do not let body copy run as an oversized monolith; split hierarchy into eyebrow, display or title, support text, and actions
• do not let support text and actions fall into unrelated columns; align them to one content spine or use a deliberate two-zone layout
• do not rely on low-opacity cards on top of saturated backgrounds for legibility
• do not use random alpha overlays to simulate depth; prefer tonal elevation and distinct container tokens
• do not leave optical balance to chance: compare left and right mass, headline width, action anchoring, and free space distribution

grouped large plaques

Use grouped large plaques when 2 to 6 sibling surfaces belong to one story: dashboard shortcuts, quick tools, stats, media controls, or settings clusters.

Grouped large plaques are not a single merged blob. They should feel related while still breathing.

Rules:

• keep siblings on one grid and one corner family
• keep inner plaque gaps deliberate, usually 8 to 16 dp
• make the outer section gap larger than the internal plaque gap so the group reads as one unit
• allow one dominant plaque; do not make every plaque equally loud
• keep row heights and internal padding optically aligned
• avoid nested mini-cards inside plaques unless there is a real information boundary
• never remove the gaps just to fake cohesion

motion rules

• select one motion strategy per interaction: state transition, visibility, content swap, size interpolation, or hero morph. do not mix them blindly.
• use motion to explain hierarchy changes, not to decorate idle surfaces.
• pair motion with shape and elevation changes only when the state change deserves it.
• keep interruption safe. user input must win over long decorative motion.
• when grouped plaques expand, move together with shared rhythm instead of random stagger spam.
• when long text or CTA layout changes, prefer stable content movement and size interpolation over jump cuts.

shape family selection

Choose the correct shape family before coding:

• use MaterialTheme.shapes and ShapeDefaults for production surfaces, cards, sheets, buttons, list rows, and containers that must remain ergonomic and layout-stable
• use expressive state-shape holders such as ButtonShapes, ListItemShapes, MenuItemShapes, or ToggleButtonShapes when the library version supports interaction-specific morphing
• use MaterialShapes plus Morph only for expressive hero elements, icon backgrounds, badges, loading visuals, onboarding, selection affordances, and branded motion moments
• do not use polygon morphing as the default container shape for dense text surfaces or core productivity lists

source ingestion

The folder Sources/ is optional and user-managed.

• the user may place one or more pleasant Android app source trees there
• do not assume ownership of those files; analyze them as read-only references unless the user explicitly asks for modification
• use them to learn better layout rhythm, color restraint, navigation patterns, typography ratios, motion taste, component pairing, and code organization
• do not clone one app wholesale; extract reusable principles and explain what was borrowed conceptually
• if Sources/ is empty, skip this path silently

output contract

Always return sections in this order when code is requested:

1. design intent

Explain the screen's hierarchy, target expression level, and the user value of the chosen layout.

2. component decisions

Name the components and explain why they fit this screen better than common alternatives.

3. motion decisions

State what moves, why it moves, and which Compose animation API or expressive motion primitive is appropriate.

4. shape decisions

State which shape family is being used, why it is appropriate, and whether the solution uses stable corner shapes, expressive state-shape APIs, or MaterialShapes morphing.

5. theme, typography, and icon decisions

State dynamic color behavior, font stack, gradient policy, variable-font strategy, and icon style.

6. exact imports

Return a full import block. Do not omit imports if the user asked for a drop-in file or if the code is large.

7. implementation

Return complete Kotlin, Compose, XML, or Gradle code as needed.

8. dependency block

Return exact dependencies only when needed. Use droidsearch or verified sources for current values.

9. qa checklist

Check spacing rhythm, insets, cutouts, tap targets, grouped plaques, gradient discipline, text balance, motion, shape motion, icon theming, dark theme, large-screen behavior, and accessibility.

review mode

When the user gives existing code, audit it against this checklist:

• spacing rhythm is consistent
• edge-to-edge is correct
• scaffold padding is not duplicated
• grouped plaques read as one family with real gaps
• gradients are justified and contrast-safe
• shapes do not clip awkwardly
• hero areas have a real hierarchy purpose
• typography scale is expressive but readable
• long text blocks are balanced and actions stay anchored
• icons match the app tone and support RTL or themed behavior
• dynamic color does not destroy contrast
• dependencies and imports are exact Then return:

1. what is wrong
2. what to change
3. corrected code
4. a short why

resources

• references/expressive-foundations.md: expressive principles, anti-slop guardrails, layout hierarchy, grouped plaques, gradients, text balance, screen archetypes
• references/motion-system.md: compose motion tutorial, choreography rules, transition selection, performance, and expressive motion guardrails
• references/shapes-and-morphs.md: shape tutorial, Compose usage, corner-radius animation, MaterialShapes and Morph guidance
• references/shape-catalog.md: full parsed catalog of core shape tokens, predefined expressive polygons, and state-shape holders
• references/typography-and-icons.md: font stack, variable fonts, typography hierarchy, adaptive icons, Material Symbols, icon policy
• references/import-map.md: import recipes with when-to-use guidance
• references/droidsearch.md: current-version lookup contract, exact-string rules, conflict handling
• references/repo-patterns.md: extracted design directions from Tomato, Navic, and Essentials
• references/sources-ingestion.md: how to analyze example source trees placed in Sources/
• scripts/droidsearch.py: real version resolver for Gradle, AGP, Maven, Google Maven, and Plugin Portal lookups
• scripts/analyze_sources.py: source-tree summarizer for optional UI reference apps placed in Sources/