Start with intent
Expressive does not mean decorative
Material 3 Expressive expands Material 3 through stronger theming, component treatment, motion, typography, and adaptive experiences. Expression should clarify hierarchy, reinforce state, and make important actions easier to understand. If a flourish hides state, delays an action, or creates uncertainty, it is working against the design system.
Android and web share UI/UX intent only. Each platform owns its source code, tokens, APIs, state, accessibility implementation, testing, and release schedule.
Every expressive choice communicates hierarchy, state, feedback, or brand character.
Layouts respond to the available window instead of assuming a device category.
Typography, motion, color, and interaction remain usable across user preferences and input methods.
Components have explicit states and acceptance checks rather than relying on visual similarity alone.
System before components
Expressive foundations
Color communicates roles
Use semantic roles such as primary, surface, container, outline, and their corresponding on-colors. Apply stronger color where it communicates focus or hierarchy, and verify contrast in light, dark, dynamic, and high-contrast conditions. Do not encode state through color alone.
Typography carries personality and structure
Begin with a readable type scale, then use variable axes such as weight, width, optical size, grade, or roundness when the selected font supports them. Axis limits are font-specific. Test the extremes for clipping, reflow, localization, and accessibility font scaling.
Shape groups and distinguishes
Use related shapes to show which surfaces belong together and shape changes to reinforce selection or press state. Joined controls still need clear focus boundaries, hit targets, and separation between distinct actions.
Motion explains change
Prefer motion that shows origin, destination, continuity, or confirmation. Keep high-frequency interactions responsive. Reduced-motion modes should preserve meaning with simpler fades, state layers, or immediate transitions.
Design for the window
Adaptive layouts
Android window size classes and web breakpoints solve the same UI/UX problem through different platform mechanisms. Use compact, medium, and expanded as shared design language, then implement and test them independently.
| Class | Android width | Typical UI change | Web verification |
|---|---|---|---|
| Compact | Under 600dp | Single pane, concise actions, bottom or modal navigation | 360–599 CSS px plus zoom and long text |
| Medium | 600–839dp | More persistent navigation and selective supporting content | 600–839 CSS px with fluid intermediate widths |
| Expanded | 840–1199dp | Multiple panes, richer navigation, more visible context | 840–1199 CSS px and resizable windows |
| Large+ | 1200dp and above | Constrain reading width; add useful panes rather than stretching content | 1200+ CSS px, ultrawide, and browser zoom |
Android dp and CSS px are not physically interchangeable. The ranges provide shared planning language for this project, while each platform must validate its own density, windowing, and input conditions.
From idea to verified component
Development workflow
- 1
Define the job
Write the user goal, primary action, secondary actions, content hierarchy, and what success or failure means.
- 2
Map states and semantics
List applicable rest, hover, focus, pressed, selected, disabled, loading, success, and error states. Define accessible name, role, value, announcements, and keyboard behaviour.
- 3
Build the structural layout
Implement content order, constraints, hit targets, scrolling, safe areas, and adaptive transitions before expressive polish.
- 4
Apply system roles
Use platform-owned color, type, shape, spacing, elevation, and motion tokens. Avoid component-local values that cannot respond to themes.
- 5
Add expression
Introduce variable type, shape morphing, spring motion, waves, or grouped surfaces only where they improve hierarchy or feedback.
- 6
Verify and document
Test states, sizes, inputs, assistive technology, reduced motion, long text, and failure paths. Record intentional platform differences.
Patterns in this repository
Component guidance
Split Buttons
Keep the leading primary action and trailing menu trigger semantically distinct. Opening the menu must not trigger the primary action, and both controls need independent focus and accessible names.
Wavy Progress
Preserve determinate versus indeterminate meaning. Expose progress values, avoid decorative animation during inactive states, and provide a reduced-motion treatment.
Dynamic Typography
Animate font axes deliberately and within the selected font’s supported ranges. Recheck measurement, wrapping, clipping, localization, and font scaling whenever axes change.
Morphing and Hold Actions
Press morphing should remain quick and reversible. Hold confirmation requires visible progress, cancellation when the pointer or touch leaves, and an accessible alternative where holding is a barrier.
Segmented Sections
Use outer and inner shapes to communicate grouping without merging separate semantics. Choose radio, checkbox, tab, or button behaviour according to the actual selection model.
Floating Navigation and Toolbars
Keep frequently used actions reachable without covering content. Adapt orientation and expansion to available space, safe areas, keyboard navigation, and pointer precision.
Independent implementations
Platform guidance
Android and Compose
- Use the checked-in version catalog and inspect current Material 3 release notes before relying on an API.
- Opt in explicitly when the selected dependency marks an expressive API experimental.
- Use MaterialTheme color, typography, and shapes as the system boundary.
- Use current window adaptive information rather than fixed device assumptions.
- Preserve state through resize, rotation, folding, and process recreation where required.
Vanilla web
- Start from semantic HTML and accessible interaction patterns, then apply the visual treatment.
- Own web-specific custom properties and component state; do not translate Compose APIs literally.
- Support keyboard, pointer, touch, zoom, forced colors where practical, and reduced motion.
- Use fluid layout inside breakpoints so the experience remains stable while a window is resized.
- Use ARIA only when native HTML cannot provide the correct semantics.
Definition of done
Verification checklist
Source priority
Official references
Material and Compose APIs evolve. Use the project skills for local conventions, then verify changing platform details against primary documentation.