Material Design 3

Add to your project

DESIGN.md encodes Material Design 3's visual language for AI coding tools. Add it to your project so Claude Code, Cursor, or any agent that reads files can reference it directly.

Quick start

Fetch /raw/design-systems/material/design-md/DESIGN.md and use it as the design foundation for this project.

Overview

Material Design 3 (M3), also called Material You, is Google's current design system — the third major iteration since Material Design launched in 2014. It was publicly released with Android 12 in 2021 and has since expanded across web, Flutter, and Jetpack Compose platforms.

M3's defining philosophical departure from its predecessors is the shift from brand-dictated color to user-personalized color. Its Dynamic Color system algorithmically generates an entire UI color scheme from a user's wallpaper or a seed color, meaning an application's visual identity adapts to each individual user. This required a fundamental redesign of how color is modeled: the multi-tier token architecture (reference → system → component) was built specifically to make dynamic theming feasible at scale.

Beyond color, M3 is characterized by:

  • Softness and expressiveness: Rounded corners, pill-shaped components, tonal elevation over shadows
  • Adaptive layout: Window Size Classes and Canonical Layouts for phone-to-foldable-to-tablet scaling
  • Accessibility as a core value: WCAG AA contrast built into tonal palette generation by default
  • M3 Expressive (May 2025): An expansion adding physics-based motion, emphasized typography styles, and new components for emotionally engaging interactions

When to reference this system:

  • Consumer mobile applications (Android, cross-platform)
  • Products requiring robust light/dark theme support with a single token set
  • Any project needing a well-documented multi-tier token architecture as a structural model
  • Reference for Dynamic Color implementation patterns
  • Adaptive layout across diverse screen sizes (phone, tablet, foldable, desktop)
  • When accessibility is a primary constraint — M3's tonal palette system produces accessible contrast by default

When not to use as primary reference:

  • Enterprise SaaS with dense data layouts (Carbon or Lightning are stronger references)
  • Web-only projects — Material Web (@material/web) is in maintenance mode; M3 Expressive is not available on web

Sources

Content TypeSourceNotes
Guidancehttps://m3.material.ioJavaScript SPA; content accessed via search + material-web.dev
Implementation (Web)https://material-web.devMaterial Web component docs; web token reference
Implementation (Android/Compose)https://developer.android.com/develop/ui/compose/designsystems/material3Primary implementation platform
Tokens / Assets (Web)https://github.com/material-components/material-web/tree/main/tokensSCSS token files