Communitygithub.com

Android 平台设计指南 - Material Design 3

遵循 Material Design 3 和 Android 平台指南,适用于 Jetpack Compose 或 XML 布局构建 Android 应用,实现 Material You、导航和可访问性。

Android 平台设计指南 - Material Design 3 是什么?

该技能提供了全面的 Android 应用设计指南,专注于 Material Design 3 和 Material You 主题系统。它涵盖了动态颜色、色彩角色、明暗主题、导航模式(底部导航栏、导航导轨、抽屉导航)、预测性后退手势、自适应布局(窗口尺寸类、Material 网格)、边缘到边缘显示、可折叠设备支持和排版系统。所有指南都提供了 Kotlin Compose 和 XML 两种实现方式,并附带严格的设计规则,确保遵循 Android 平台最佳实践。该技能适用于从手机到平板的多种屏幕尺寸,并强制支持 Android 12+ 的动态颜色特性,同时为旧设备提供降级方案。主要用于开发人员确保 Android 应用的 UI 设计符合 Google 的 Material Design 3 规范。

兼容平台~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/xzedm/clipplic-landing/tree/HEAD/.agents/skills/android-design-guidelines

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

Android 平台设计指南 — Material Design 3

1. Material You 与主题化 [关键]

1.1 动态颜色

启用从用户壁纸派生的动态颜色。动态颜色是 Android 12+ 的默认设置,应作为主要的主题化策略。

// Compose:动态颜色主题
@Composable
fun AppTheme(
    darkTheme: Boolean = isSystemInDarkTheme(),
    dynamicColor: Boolean = true,
    content: @Composable () -> Unit
) {
    val colorScheme = when {
        dynamicColor && Build.VERSION.SDK_INT >= Build.VERSION_CODES.S -> {
            val context = LocalContext.current
            if (darkTheme) dynamicDarkColorScheme(context)
            else dynamicLightColorScheme(context)
        }
        darkTheme -> darkColorScheme()
        else -> lightColorScheme()
    }
    MaterialTheme(
        colorScheme = colorScheme,
        typography = AppTypography,
        content = content
    )
}
<!-- XML:themes.xml 中的动态颜色 -->
<style name="Theme.App" parent="Theme.Material3.DayNight.NoActionBar">
    <item name="dynamicColorThemeOverlay">@style/ThemeOverlay.Material3.DynamicColors.DayNight</item>
</style>

规则:

  • R1.1:始终为低于 Android 12 的设备提供静态颜色方案的降级方案。
  • R1.2:切勿在组件中硬编码颜色十六进制值。始终从主题中引用颜色角色。
  • R1.3:用至少 3 种不同的壁纸进行测试,以验证动态颜色的和谐性。

1.2 色彩角色

Material 3 定义了一组结构化的色彩角色。根据语义使用它们,而不是基于美观。

角色用途角色上颜色
primary关键操作、激活状态、FABonPrimary
primaryContainer较不突出的主要元素onPrimaryContainer
secondary辅助 UI、过滤芯片onSecondary
secondaryContainer导航栏激活指示器onSecondaryContainer
tertiary强调、对比、互补onTertiary
tertiaryContainer输入字段、较不突出的强调色onTertiaryContainer
surface背景、卡片、面板onSurface
surfaceVariant装饰性元素、分隔线onSurfaceVariant
error错误状态、破坏性操作onError
errorContainer错误背景onErrorContainer
outline边框、分隔线—
outlineVariant微妙边框—
inverseSurfaceSnackbar 背景inverseOnSurface
// 正确:语义化的色彩角色
Text(
    text = "错误消息",
    color = MaterialTheme.colorScheme.error
)
Surface(color = MaterialTheme.colorScheme.errorContainer) {
    Text(text = "错误详情", color = MaterialTheme.colorScheme.onErrorContainer)
}

// 错误:硬编码颜色
Text(text = "错误", color = Color(0xFFB00020)) // 反模式

规则:

  • R1.4:每个前景元素必须为其背景使用匹配的 on 颜色角色(例如,primary 背景上的 onPrimary 文本)。
  • R1.5:使用 surface 及其变体作为背景。切勿将 primary 或 secondary 用作大的背景区域。
  • R1.6:有节制地使用 tertiary,仅用于强调和互补对比。

1.3 明亮与暗黑主题

支持明亮和暗黑两种主题。默认尊重系统设置。

// Compose:检测系统主题
val darkTheme = isSystemInDarkTheme()

规则:

  • R1.7:始终同时支持明亮和暗黑主题。切勿仅发布明亮主题。
  • R1.8:暗黑主题的表面使用基于高度的色调映射,而不是纯黑色 (#000000)。使用 surface 颜色角色,它会自动处理此问题。
  • R1.9:在应用设置中提供手动主题覆盖(系统 / 明亮 / 暗黑)。

1.4 自定义颜色种子

当品牌需要自定义颜色时,提供种子颜色并使用 Material Theme Builder 生成色调调色板。

// 使用品牌种子的自定义颜色方案
private val BrandLightColorScheme = lightColorScheme(
    primary = Color(0xFF1B6D2F),
    onPrimary = Color(0xFFFFFFFF),
    primaryContainer = Color(0xFFA4F6A8),
    onPrimaryContainer = Color(0xFF002107),
    // ... 从种子生成完整调色板
)

规则:

  • R1.10:使用 Material Theme Builder 从种子颜色生成色调调色板。切勿手动选择单个色调。
  • R1.11:使用自定义颜色时,仍应将动态颜色作为默认值,并将自定义颜色作为降级方案。

2. 导航 [关键]

2.1 导航栏(底部)

适用于 3-5 个顶级目标页面的手机主要导航模式。

// Compose:导航栏
NavigationBar {
    items.forEachIndexed { index, item ->
        NavigationBarItem(
            icon = {
                Icon(
                    imageVector = if (selectedItem == index) item.filledIcon else item.outlinedIcon,
                    contentDescription = item.label
                )
            },
            label = { Text(item.label) },
            selected = selectedItem == index,
            onClick = { selectedItem = index }
        )
    }
}

规则:

  • R2.1:在紧凑屏幕上为 3-5 个顶级目标页面使用导航栏。切勿用于少于 3 个或多于 5 个。
  • R2.2:始终在导航栏项上显示标签。不允许仅图标的导航栏。
  • R2.3:选中状态使用填充图标,未选中状态使用轮廓图标。
  • R2.4:活动指示器使用 secondaryContainer 颜色。请勿覆盖。

2.2 导航导轨

适用于中号和展开屏幕(平板电脑、折叠设备、桌面)。

// Compose:针对大屏幕的导航导轨
NavigationRail(
    header = {
        FloatingActionButton(
            onClick = { /* 主要操作 */ },
            containerColor = MaterialTheme.colorScheme.tertiaryContainer
        ) {
            Icon(Icons.Default.Add, contentDescription = "创建")
        }
    }
) {
    items.forEachIndexed { index, item ->
        NavigationRailItem(
            icon = { Icon(item.icon, contentDescription = item.label) },
            label = { Text(item.label) },
            selected = selectedItem == index,
            onClick = { selectedItem = index }
        )
    }
}

规则:

  • R2.5:在中 (600-839dp) 和展开 (840dp+) 窗口大小时使用导航导轨。在紧凑屏幕上与导航栏配对使用。
  • R2.6:可选择在导轨头部包含一个 FAB 用于主要操作。
  • R2.7:导轨上的标签是可选的,但为了清晰起见推荐使用。

2.3 导航抽屉

适用于 5+ 个目标页面或复杂的导航层级,通常在展开屏幕上使用。

// Compose:针对大屏幕的永久导航抽屉
PermanentNavigationDrawer(
    drawerContent = {
        PermanentDrawerSheet {
            Text("应用名称", modifier = Modifier.padding(16.dp),
                 style = MaterialTheme.typography.titleMedium)
            HorizontalDivider()
            items.forEach { item ->
                NavigationDrawerItem(
                    label = { Text(item.label) },
                    selected = item == selectedItem,
                    onClick = { selectedItem = item },
                    icon = { Icon(item.icon, contentDescription = null) }
                )
            }
        }
    }
) {
    Scaffold { /* 页面内容 */ }
}

规则:

  • R2.8:在紧凑屏幕上使用模态抽屉,在展开屏幕上使用永久抽屉。
  • R2.9:将抽屉项分组为带有分隔线和节标题的部分。

2.4 预测性返回手势

Android 13+ 支持带有动画预览的预测性返回。

// Compose:使用 BackHandler 的预测性返回 (androidx.activity.compose)
BackHandler(enabled = true) {
    // 当返回被确认时调用;在导航控制器中返回上一级
    navController.popBackStack()
}
// Compose:使用 predictiveBackHandler 修饰符的预测性返回进度动画
// (androidx.activity:activity-compose 1.8+)
Modifier.predictiveBackHandler(enabled = true) { progress ->
    // progress 是一个 Flow<BackEventCompat>,包含 x, y, swipeEdge, progress (0.0–1.0)
    progress.collect { backEvent ->
        animationState = backEvent.progress
    }
}
<!-- AndroidManifest.xml:选择启用预测性返回 -->
<application android:enableOnBackInvokedCallback="true">

规则:

  • R2.10:在清单中选择启用预测性返回。在 Compose 应用中,使用 BackHandler(来自 androidx.activity.compose)拦截返回事件。在 基于 View 的应用中,实现 OnBackInvokedCallback(API 33+)或 OnBackPressedCallback(AndroidX),而不是重写 onBackPressed()。
  • R2.11:系统返回手势在导航堆栈中返回。向上按钮(工具栏箭头)在应用层级中向上导航。这两者可能不同。
  • R2.12:除非有未保存的用户输入,否则切勿拦截系统返回以显示“你确定吗?”对话框。
  • R2.13:不要压制系统提供的返回预览动画。如果实现了自定义进入/退出过渡,请使用 BackEventCompat.progress (0.0–1.0) 进行插值,并尊重 BackEventCompat.swipeEdge (EDGE_LEFT/EDGE_RIGHT),以便退出屏幕按比例缩小并向触发边缘移动,与系统动画匹配。
  • R2.14:优先识别而非回忆。保持目标页面有标签、选中状态可见、返回堆栈上下文保留,以便用户在每次导航步骤后不必重新构建他们所在的位置。
// Compose:根据预测性返回进度驱动自定义动画
Modifier.predictiveBackHandler(enabled = true) { progress ->
    progress.collect { backEvent ->
        // backEvent.progress: 0.0 (手势开始) → 1.0 (确认)
        // backEvent.swipeEdge: BackEventCompat.EDGE_LEFT 或 EDGE_RIGHT
        exitScale = 1f - (backEvent.progress * 0.1f)
        exitOffsetX = if (backEvent.swipeEdge == BackEventCompat.EDGE_LEFT) -backEvent.progress * 32.dp.toPx() else backEvent.progress * 32.dp.toPx()
    }
}

2.5 导航组件选择

屏幕尺寸3-5 个目标页面5+ 个目标页面
紧凑 (< 600dp)导航栏模态抽屉 + 导航栏
中 (600-839dp)导航导轨模态抽屉 + 导航导轨
展开 (840dp+)导航导轨永久抽屉

3. 布局与响应式 [高优先级]

3.1 窗口尺寸类

使用窗口尺寸类进行自适应布局,而不是原始像素断点。

// Compose:窗口尺寸类
val windowSizeClass = calculateWindowSizeClass(this)
when (windowSizeClass.widthSizeClass) {
    WindowWidthSizeClass.Compact -> CompactLayout()
    WindowWidthSizeClass.Medium -> MediumLayout()
    WindowWidthSizeClass.Expanded -> ExpandedLayout()
}
类宽度典型设备列数
紧凑< 600dp手机竖屏4
中600-839dp平板竖屏、折叠设备8
展开840dp+平板横屏、桌面12

规则:

  • R3.1:始终使用 material3-window-size-class 中的 WindowSizeClass 进行响应式布局决策。
  • R3.2:切勿使用固定像素断点。设备类别是流动的。
  • R3.3:支持所有三种宽度尺寸类。至少支持紧凑和展开。

3.2 Material 网格

应用规范的 Material 网格边距和间距。

尺寸类边距间距列数
紧凑16dp8dp4
中24dp16dp8
展开24dp24dp12

规则:

  • R3.4:在展开屏幕上,内容不应跨越整个宽度。使用约 840dp 的最大内容宽度或列表-详情布局。
  • R3.5:应用与网格规格一致的水平边距。

3.3 边缘到边缘显示

Android 15+ 强制要求边缘到边缘。所有应用应绘制在系统栏后面。

// Compose:边缘到边缘设置
class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        enableEdgeToEdge()
        super.onCreate(savedInstanceState)
        setContent {
            Scaffold(
                modifier = Modifier.fillMaxSize(),
                // Scaffold 自动处理顶部/底部栏的内边距
            ) { innerPadding ->
                Content(modifier = Modifier.padding(innerPadding))
            }
        }
    }
}

规则:

  • R3.6:在 setContent 之前调用 enableEdgeToEdge()。在状态栏和导航栏后面绘制。
  • R3.7:使用 WindowInsets 将内容与系统栏隔开。Scaffold 会自动处理顶部栏和底部栏内容的内边距。
  • R3.8:可滚动内容应在透明系统栏后面滚动,并在列表顶部和底部添加适当的内边距。

3.4 可折叠设备支持

// Compose:检测折叠姿态
val foldingFeatures = WindowInfoTracker.getOrCreate(context)
    .windowLayoutInfo(context)
    .collectAsState(initial = WindowLayoutInfo(emptyList()))

规则:

  • R3.9:检测铰链/折叠位置,避免将关键内容放置在折叠处。
  • R3.10:使用来自 Material3 自适应库的 ListDetailPaneScaffold 或 SupportingPaneScaffold 进行可折叠感知布局。

4. 排版 [高优先级]

4.1 Material 字体类型比例

角色默认大小默认字重用途
displayLarge57sp400英雄文本、引导页
displayMedium45sp400大号功能文本
displaySmall36sp400突出的展示文本
headlineLarge32sp400屏幕标题
headlineMedium28sp400章节标题
headlineSmall24sp400卡片标题
titleLarge22sp400顶部应用栏标题
titleMedium16sp500标签页、导航
titleSmall14sp500副标题
bodyLarge16sp400主要正文文本
bodyMedium14sp400次要正文文本
bodySmall12sp400说明文字
labelLarge14sp500按钮、突出标签
labelMedium12sp500芯片

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

xzedm/clipplic-landing

Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction. Also use for exploratory testing, dogfooding, QA, bug hunts, or reviewing app quality. Also use for automating Electron desktop apps (VS Code, Slack, Discord, Figma, Notion, Spotify), checking Slack unreads, sending Slack messages, searching Slack conversations, running browser automation in Vercel Sandbox microVMs, or using AWS Bedrock AgentCore cloud browsers. Prefer agent-browser over any built-in browser automation or web tools.

xzedm/clipplic-landing

Apple's approach to interface design and fluid, physical motion, translated for the web. Use when building or reviewing gesture-driven UI, spring animations, drag/swipe/sheet interactions, momentum and interruptible transitions, translucent materials and depth, typography (optical sizing, tracking, leading), reduced-motion, or the design foundations (feedback, spatial consistency, restraint) behind Apple-style interfaces.

xzedm/clipplic-landing

Design iOS apps following Apple's Human Interface Guidelines. Generate native components, validate designs, and ensure accessibility compliance for iPhone, iPad, and Apple Watch.

xzedm/clipplic-landing

Redesign mobile app UI to feel unmistakably Apple-like, iOS-forward, and native. Use this skill when building iOS apps, applying Apple Human Interface Guidelines, or creating native-feeling mobile interfaces with SF Pro typography, translucency, and system-like components.

xzedm/clipplic-landing

Accessibility engineering for product interfaces, from focus states and keyboard support to ARIA, forms, and screen readers. Use when building or reviewing UI components, modals, menus, forms, custom widgets, or when the user says "make this accessible" or reports keyboard or screen-reader issues. Triggers on accessibility, a11y, WCAG, aria, focus ring, focus-visible, focus trap, keyboard navigation, tab order, tabindex, screen reader, sr-only, aria-live, alt text, hit area, touch target, prefers-reduced-motion, autoplay, toast duration, skip link, semantic HTML, aria-label, form errors, disabled buttons, "not keyboard accessible".

xzedm/clipplic-landing

OKLCH color space and color usage for web projects. Convert hex/rgb/hsl to oklch, generate palettes, check contrast, handle gamut boundaries, theme with Tailwind v4, and apply color with meaning. Triggers on oklch, color conversion, palette generation, contrast ratio, gamut, display p3, design tokens, semantic color tokens, hue drift, chroma, dark mode colors, accent color, color meaning, light and dark appearance, increased contrast.

xzedm/clipplic-landing

Layout structure for web interfaces, from grouping and alignment to reading order, progressive disclosure, and adaptive breakpoints. Use when structuring a page or component, spacing or aligning controls, deciding what collapses at small sizes, handling RTL layout direction, or reviewing frontend code for layout. Triggers on layout, spacing, alignment, grouping, negative space, whitespace, visual hierarchy, reading order, progressive disclosure, breakpoints, responsive layout, container queries, safe area, full-bleed, edge-to-edge, layout margins, RTL layout, logical properties.

xzedm/clipplic-landing

Web typography from choosing fonts to spacing, wrapping and accessibility. Use when picking or pairing typefaces, configuring variable fonts or OpenType features, setting up a type scale, checking heading hierarchy, styling text in components, truncating text, styling underlines, selection, placeholders or carets, or reviewing frontend code for typography. Triggers on typography, fonts, font formats, woff2, variable fonts, font-weight, opentype, font-feature-settings, letter-spacing, line-height, type scale, heading hierarchy, heading levels, tabular numbers, text-wrap, truncation, line clamp, underlines, text-decoration, text selection, iOS input zoom, scaled input text, font smoothing, text contrast, measure, line length, text-box, smart punctuation, drop cap.

xzedm/clipplic-landing

Design engineering principles for making interfaces feel polished. Use when building UI components, reviewing frontend code, implementing animations, hover states, shadows, borders, micro-interactions, enter/exit animations, choosing or reviewing icons, or any visual detail work. Triggers on UI polish, design details, "make it feel better", "feels off", stagger animations, border radius, optical alignment, image outlines, box shadows, icons, icon stroke weight, icon states, motion restraint.

xzedm/clipplic-landing

Deploy applications and websites to Vercel. Use when the user requests deployment actions like "deploy my app", "deploy and give me the link", "push this live", or "create a preview deployment".

xzedm/clipplic-landing

Generate developer handoff specs from a design. Use when a design is ready for engineering and needs a spec sheet covering layout, design tokens, component props, interaction states, responsive breakpoints, edge cases, and animation details.

xzedm/clipplic-landing

This skill encodes Emil Kowalski's philosophy on UI polish, component design, animation decisions, and the invisible details that make software feel great.

xzedm/clipplic-landing

Extract design primitives from a public website and generate starter token files for your project.

xzedm/clipplic-landing

Use this skill alongside figma-use when the task involves translating an application page, view, or multi-section layout into Figma. Triggers: 'write to Figma', 'create in Figma from code', 'push page to Figma', 'take this app/page and build it in Figma', 'create a screen', 'build a landing page in Figma', 'update the Figma screen to match code', 'convert this modal/dialog/drawer/panel to Figma'. This is the preferred workflow skill whenever the user wants to build or update a full page, modal, dialog, drawer, sidebar, panel, or any composed multi-section view in Figma from code or a description. Discovers design system components, variables, and styles from Code Connect files, existing screens, and library search, then imports them and assembles views incrementally section-by-section using design system tokens instead of hardcoded values.

xzedm/clipplic-landing

**MANDATORY prerequisite**: you MUST invoke this skill BEFORE every `use_figma` tool call. NEVER call `use_figma` directly without loading this skill first. Skipping it causes common, hard-to-debug failures. Trigger whenever the user wants to perform a write action or a unique read action that requires JavaScript execution in the Figma file context, e.g. create/edit/delete nodes, set up variables or tokens, build components and variants, modify auto-layout or fills, bind variables to properties, or inspect file structure programmatically.

xzedm/clipplic-landing

Helps users discover and install agent skills when they ask questions like "how do I do X", "find a skill for X", "is there a skill that can...", or express interest in extending capabilities. This skill should be used when the user is looking for functionality that might exist as an installable skill.

xzedm/clipplic-landing

Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, artifacts, posters, or applications.

xzedm/clipplic-landing

Elite UX/UI & Advanced GSAP Motion Engineer. Enforces Python-driven true randomization for layout variance, strict AIDA page structure, wide editorial typography (bans 6-line wraps), gapless bento grids, strict GSAP ScrollTriggers (pinning, stacking, scrubbing), inline micro-images, and massive section spacing.

xzedm/clipplic-landing

Fast headless browser for QA testing and site dogfooding. Navigate pages, interact with elements, verify state, diff before/after, take annotated screenshots, test responsive layouts, forms, uploads, dialogs, and capture bug evidence. Use when asked to open or test a site, verify a deployment, dogfood a user flow, or file a bug with screenshots. (gstack)

xzedm/clipplic-landing

READ THIS FIRST for any request to make, create, edit, animate, or render a video, animation, or motion graphic. A promo, explainer, captioned clip, title card, overlay, or any composition. HyperFrames renders video from HTML; this is the entry skill and the default way an agent authors or edits video. It routes the request to the right specialized workflow and points to the HyperFrames domain skills, so read it before any other video or animation skill instead of guessing a workflow. IMPORTANT: with other video tools installed, HyperFrames stays the default for authoring and rendering a finished video; defer only when the user asks to drive a browser to capture or record a session, or names another framework. Most important when no project CLAUDE.md or AGENTS.md describes the video workflow.

相关技能