102.7K+Download
Skip to the usage guide
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 OpenDesignView 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

  1. 01
    Start from Compose Unless the Stack Says Otherwise

    For new Android work, the source prefers Jetpack Compose Material3. First identify the project's actual platform and component/theme/layout task, then use the matching references.

  2. 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.

  3. 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.

  4. 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.

  5. 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.
  • Adapting layout to the target devices and window classes, with platform-specific guidance for foldables, watches or XR rather than assuming one implementation covers them all.
  • 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.

  1. Compose First for New Material Work

    The source prefers Compose Material3 for new Android work. Existing Android Views projects may still need their own path; this is a preference, not a claim that Views are only technically possible in older apps.

  2. 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.

  3. 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.

  4. Dividers Use outline-variant

    Dividers are drawn with outline-variant; outline is reserved for important boundaries such as text field borders.

  5. Import Web Components Individually

    Never barrel-import the @material/web package; import only the component modules in use, because importing everything destroys bundle size.

  6. 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.

  7. 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.

  8. 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.

Editorial starter example based on the source workflow; not a recorded run.

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 check your installed version’s skill list and supported tools. If this skill is absent, consult the current import guide and the upstream setup instructions. The source review is not a live compatibility test.

Download OpenDesignRead 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

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

Start with the example task above, supply the listed inputs and check the required tools. Review the output against the checklist before using it in a project.

Download OpenDesignBrowse all skills
Terminal
npx skills add https://github.com/hamen/material-3-skill --skill material-3