material-3by hamen

Material 3 Skill.

A Claude Code and Codex skill for mobile app design: implements Material Design 3 tokens, components, and adaptive layouts.

Mobile Apps
UI code

Download OpenDesign View usage guide

hamen/material-3-skill · skills/material-3/SKILL.mdSKILL.md

--- name: material-3 description: Implement Google's Material Design 3 (Material You) UI system. Primary: Jetpack Compose Material3 (MaterialTheme, components, adaptive layout). Also Flutter and limited web (@material/web, maintenance mode). Covers tokens, 30+ components, layout, theming, M3 Expressive (platform matrix), and accessibility. Use when: "material design", "MD3", "material you", "Jetpack Compose", "MaterialTheme", "material component", … --- ## Philosophy ## Current Updates: Google I/O 2026 ## Decision Tree ## Design Token System ## Jetpack Compose (primary) ## Web (limited): @material/web

Front matter and section headings read from the upstream file on 2026-09-14 · 31,218 characters in full

01 What it does

What the material-3 Skill Does in Claude Code and Codex

Summary, workflow and outputs, all read from the skill's SKILL.md.

From the SKILL.mdRead 2026-09-14 · not a recorded run

In the Skill's Own Terms

Guides implementation of Google's Material Design 3 (Material You) with Jetpack Compose Material3 as the primary target, plus Flutter and a limited web path through @material/web. It covers the md.sys token system for color, typescale, shape, elevation and motion, a quick reference to 30+ components with their variants, adaptive layout and navigation, theming and dynamic color, the M3 Expressive platform matrix, and accessibility.

An audit mode scores an app or a page 0-10 across ten categories and produces a compliance report. It is for designers and developers who need concrete MD3 defaults: five window size classes, tonal elevation instead of shadows, an 8dp spacing system, and max content widths on large windows.

What it produces

A markdown MD3 compliance report with an overall score and per-category scores, critical issues, warnings, passing items and prioritized fixes.
A Compose theme built from MaterialTheme with a colorScheme supplied by dynamicLightColorScheme, lightColorScheme or generated theme code.
A CSS theme block of md-sys custom properties, including a dark theme variant applied by media query or class.

See the example prompt ↗

How It Works

01
Start from Compose Unless the Stack Says Otherwise
The file treats Jetpack Compose Material3 as the default path and the Decision Tree routes app shells, single components, themes, forms, navigation and data display to specific sections and reference files before any code is written.
02
Apply the Token Layer
All MD3 tokens live in the md.sys namespace; Compose maps the same semantic roles onto MaterialTheme.colorScheme, typography and shapes, while web maps them onto CSS custom properties prefixed md-sys.
03
Pick Components from the Quick Reference
The component table lists each component's web element name, key variants and category, and flags which ones have no @material/web implementation so they can be built from CSS custom properties with standard HTML instead.
04
Assemble with the Common Patterns
The App Shell, Card Grid and Form Layout patterns are given as HTML plus CSS, including a breakpoint that turns the navigation rail into bottom navigation on compact widths.
05
Audit When Asked
Invoked with audit, the skill inspects a URL, source files or a running app and scores ten categories from 0 to 10 before writing the report.

02 Find your fit

When to Use the material-3 Skill

Use the material-3 skill in Claude Code or Codex when the job is mobile app design of this kind. Fit and limits below are taken from the skill's own file.

Good Fit

Building a new Android screen or app in Jetpack Compose with androidx.compose.material3 composables such as Scaffold, Button and NavigationBar.
Generating a theme from the user's wallpaper with dynamic color on Android 12 and above, falling back to static light and dark schemes otherwise.
One layout that adapts across phone, foldable, desktop, watch and XR instead of a fixed phone-first design.
Auditing an existing app or page against MD3 and getting a scored report to work from.
Theming a web UI by setting MD3 CSS custom properties on the root or any ancestor element.

Know the Boundaries

Expecting M3 Expressive features on the web, since Material Web is maintenance-only and Expressive is not implemented there.
Server-side rendering without a hydration strategy, because the web components are custom elements that need JavaScript.
Projects that still mix Material 2 and Material 3 libraries, whose APIs and styling are incompatible.
Phone-only layouts that ignore large screens and foldables, including interactive content placed across a hinge.

What to Provide

A task argumentThe skill takes a component, theme, layout, scaffold or audit argument followed by a short description or a URL, which selects which section or reference file to follow.
A target to auditFor audit work, supply a URL for browser inspection, file paths to read source from, or access to a running app.
A seed color for custom themingA single seed color is enough to derive a full color scheme; the file points to the material-color-utilities package for generating the values.
Source files for code auditsCompose audits read Kotlin files to find MaterialTheme usage, composables, raw Color values, hard-coded Dp and missing semantics.

03 Inside the skill

Rules the material-3 Skill Gives Claude Code and Codex

8 concrete instructions, defaults and limits the SKILL.md sets for the agent — the part of the file that changes the result.

Compose First for New Material Work
For new Android work the file says to prefer Jetpack Compose Material3 for components, expressive APIs, adaptive scaffolds and Styles API integration; Android Views are only acceptable in existing apps.
Never Hardcode Colors
Use the md-sys-color tokens rather than raw hex or rgb values, because hardcoded colors break dynamic theming, dark mode and contrast adjustment.
Keep the Intended Tonal Pairs
Only combine colors as designed, for example primary with on-primary and surface-container with on-surface; arbitrary pairings break contrast in dynamic color and high contrast modes.
Dividers Use outline-variant
Dividers are drawn with outline-variant; outline is reserved for important boundaries such as text field borders.
Import Web Components Individually
Never barrel-import the @material/web package; import only the component modules in use, because importing everything destroys bundle size.
Constrain Width on Large Windows
On Large (1200dp+) and Extra-large (1600dp+) windows content is capped at a max width of 840-1040dp, because endless-width text lines are unreadable.
Elevation Is Tonal, Not Shadow
MD3 communicates elevation through tonal surface color rather than shadows; shadows are only added when an element needs extra separation from a busy background.
Roboto Is Correct in MD3
Roboto or Roboto Flex is the default Material typeface and the frontend-design advice to avoid Roboto does not apply; replace it only when intentionally customizing the type scale.

04 Put it to work

Install material-3 in Claude Code or Codex

One npx skills add command, then a first task in your agent and a checklist for the result.

Add material-3 to Claude Code, Codex or Your Agent

Run in your project; the installer asks which agent to add it to.

Terminal

npx skills add https://github.com/hamen/material-3-skill --skill material-3

Generic skills CLI form for skills/material-3/SKILL.md; the repository may document its own path.

Give the Skill a First Mobile App Design Task

Written in the skill's own terms; replace the bracketed parts with your material.

Starter prompt

We're moving our [Android app] from Material 2 to MD3. Set up MaterialTheme with dynamic color on Android 12+ and wire the md.sys color, type and shape tokens, then rebuild [screen name] as a Scaffold with a navigation rail on medium and expanded window size classes. We ship on foldables too, so keep interactive content off the hinge and constrain content width on large windows.

Source: written from the SKILL.md in the skill's own terms.

Check the First Result

What the SKILL.md itself says a correct result looks like:

Verify contrast ratios and touch targets, not just the use of MD3 roles.
Search the web stylesheets for hardcoded hex colors.
Search Kotlin sources for raw Color values.
Search JavaScript and TypeScript for leftover Material 2 imports.
Resize the viewport or use responsive mode to check the layout at each breakpoint.

In OpenDesign import material-3 from its SKILL.md link: Plugins → Add → Skill → Import from link, then pick it in the top bar.

Download OpenDesign Read the quickstart

05 Open source, traceable

Source, License and Verification

Where this page's facts come from, and when they were last checked.

Author: hamen
Repository: github.com/hamen/material-3-skill Branch master
Skill file: skills/material-3/SKILL.md Content checksum recorded at verification; commit 14385f2
License: MIT From LICENSE.
Repository stars: 1,384 GitHub snapshot taken 2026-09-14 for the whole hamen/material-3-skill repository. Not a rating or usage count for material-3.
Verified by OpenDesign: 2026-09-14 Source file, path, license text and star count were checked. Not bundled in OpenDesign main (checked 2026-08-28); a live run has not been recorded on this page.

Inside the SKILL.md

PhilosophyThree principles, personal, adaptive and expressive, that define dynamic color, window size classes and spring motion.
Decision TreeRoutes what you are building and which platform to sections and reference files.
Design Token Systemmd.sys color, type, shape, elevation and motion tokens with Compose and CSS mappings.
Component Quick ReferenceTable of 30+ components with web elements, key variants and category.
Jetpack Compose (primary)androidx.compose.material3 setup, MaterialTheme, dynamic color, adaptive UI and insets.
Web (limited): @material/webMaintenance-mode web components, individual imports, CSS custom property theming and dark theme.
Common PatternsApp shell, card grid and form layout snippets in HTML and CSS.
Anti-PatternsHard prohibitions covering MD2 mix

The Skill's Own Description

“Implement Google's Material Design 3 (Material You) UI system. Primary: Jetpack Compose Material3 (MaterialTheme, components, adaptive layout). Also Flutter and limited web (@material/web, maintenance mode). Covers tokens, 30+ components, layout, theming, M3 Expressive (platform matrix), and accessibility. Use when: "material design", "MD3", "material you", "Jetpack Compose", "MaterialTheme", "material component", "md3 button".”

Front-matter description from SKILL.md. The full file is about 31,218 characters. Read the full file on GitHub.

Material 3

Run material-3 on a Real Mobile App Design Task.

Download OpenDesign, import material-3 from its SKILL.md link, paste the prompt above, and read the plan before the result.

Download OpenDesign Browse all skills

Terminal

npx skills add https://github.com/hamen/material-3-skill --skill material-3

What the material-3 Skill Does in Claude Code and Codex

In the Skill's Own Terms

How It Works

When to Use the material-3 Skill

Good Fit

Know the Boundaries

What to Provide

Rules the material-3 Skill Gives Claude Code and Codex

Compose First for New Material Work

Never Hardcode Colors

Keep the Intended Tonal Pairs

Dividers Use outline-variant

Import Web Components Individually

Constrain Width on Large Windows

Elevation Is Tonal, Not Shadow

Roboto Is Correct in MD3