ceorkm/macos-design-skill

Native macOS app design system - Build apps that feel like Apple designed them - ceorkm/macos-design-skill

80 stars · 8 forks

README

macOS Design Skill

Build native-feeling macOS applications that look like Apple designed them.

Overview This skill provides a complete design system for creating native macOS application UIs. It captures years of Apple design knowledge distilled into actionable guidelines, exact values, and production-ready patterns. Features

✅ Complete Layout System - The Apple formula (traffic lights, top bar, sidebar, content) ✅ Visual Design - Colors, typography, blur/vibrancy, shadows, icons, spacing ✅ Interaction Patterns - Keyboard shortcuts, animations, search, drag-and-drop ✅ Light + Dark Mode - Proper differentiation, not naive inversion ✅ Production-Ready - Exact CSS values, code snippets, implementation details ✅ Cross-Platform - Works for web, Electron, Tauri, native frameworks

Quick Start For Claude Code

Install the skill

Use in your project

Manual Usage Read the reference files based on what you're building:

All macOS apps → references/layout-and-composition.md (required) Keyboard shortcuts, panels, search → references/interaction-patterns.md Colors, typography, blur effects → references/visual-design.md

What You'll Build This skill enables you to create:

Desktop utilities that feel native to macOS Screenshot managers, note-taking apps, asset browsers Developer tools, productivity apps, system utilities Anything that should integrate seamlessly with the Mac ecosystem

Key Principles 1. Don't Invert Colors Dark mode needs MORE differentiation between background levels, not less. Design each mode independently. / Light: backgrounds close together / --bg-primary: #FFFFFF; --bg-secondary: #F5F5F7;

/ Dark: backgrounds spread out / --bg-primary: #1C1C1E; --bg-secondary: #2C2C2E;

2. Vibrancy is Essential Use backdrop-filter: blur() with saturate(180%) for sidebars, toolbars, and panels. 3. Layered Shadows The signature 0 0 0 0.5px creates subtle edge definition without visible borders. 4. Keyboard Shortcuts First Every primary action needs a shortcut. Show hints with <kbd> elements. 5. Progressive Disclosure Only show UI when it's useful. Hide filters/toolbars when there's no content. Design System Highlights Typography

Font Stack: -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text" Body Size: 13px (macOS apps use smaller type than web) Weights: Regular (400), Medium (500), Semibold (600), Bold (700)

Spacing (8px Grid)

Context Value

Window padding 16-20px

Section gap 24px

Card gap 12-16px

Button padding 6px 12px

Corner Radii

Element Radius

Window 10px

Card 8px

Button 6px

Input 6px

Animations --ease-out: cubic-bezier(0.25, 0.46, 0.45, 0.94); --duration-fast: 150ms; --duration-normal: 250ms;

Files . ├── SKILL.md # Skill definition and quick-start ├── README.md # This file └── references/ ├── layout-and-composition.md # Layout patterns and structure ├── visual-design.md # Colors, typography, shadows, blur └── interaction-patterns.md # Keyboard, animations, search, drag-drop

Credits Design principles derived from:

Apple Human Interface Guidelines macOS system apps (Finder, Notes, Reminders, Settings) Third-party excellence (Raycast, Paste, Bartender)

License MIT - Feel free to use in your own projects!

Built with ❤️ for macOS designers and developers

source