macos-notch-ui
Add a Dynamic Island-style notch UI to a macOS app. Use this skill whenever the user wants to create a notch overlay, notch extender, Dynamic Island for Mac, notch indicator, or any UI that extends from the MacBook notch area. Also trigger when the user mentions "notch shape", "notch window", "notch cutout", "notch panel", "recording indicator near the notch", "Dynamic Island style", or wants to show status/content that appears to emerge from the hardware notch. This covers the NSPanel setup, the NotchShape with concave Bezier ear curves, screen positioning math, spring animations, and show/hide choreography.
- Installs
- 566
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/fayazara/macos-app-skills --skill macos-notch-ui- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads macos-notch-ui automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
macOS Notch UI (Dynamic Island Style)
This skill creates a Dynamic Island-style overlay that extends from the MacBook's hardware notch. The overlay is a transparent floating panel positioned flush against the top of the screen, using a custom shape with concave "ear" curves that blend seamlessly with the physical notch cutout.
Architecture
The implementation has 3 parts:
NotchWindow(NSPanel subclass) -- a borderless, transparent, click-through panel atCGShieldingWindowLevelthat sits above everything, including the menu barNotchShape(SwiftUI Shape) -- draws the Dynamic Island silhouette with concave quadratic Bezier curves at the top corners and convex rounded corners at the bottom- Your content view -- whatever you want to show inside the notch (status indicators, waveforms, text, icons)
How It Works
The MacBook notch is a black rectangle at the top-center of the screen. By placing a black-filled NotchShape at that exact position at the highest window level, it visually extends the notch area. Content inside the shape appears to "emerge" from the hardware notch.
The key positioning math:
// Use full screen frame (not visibleFrame) to include the menu bar / notch area
let screen = NSScreen.main!
let x = screen.frame.origin.x + (screen.frame.width - totalWidth) / 2
let y = screen.frame.origin.y + screen.frame.height - totalHeight
Using screen.frame (not screen.visibleFrame) is critical -- visibleFrame excludes the menu bar area where the notch lives.
Reference Files
references/NotchWindow.swift-- Drop-in NSPanel subclass with show/hide and positioningreferences/NotchShape.swift-- The Dynamic Island shape with animatable corner radii
Step-by-Step Integration
1. Add the NotchShape
Copy references/NotchShape.swift. This is a SwiftUI Shape with two configurable corner radii:
topCornerRadius(default 10) -- the concave "ear" curves at the top that mimic the hardware notch's inverse cornersbottomCornerRadius(default 16) -- the standard convex rounded corners at the bottom
Both are animatable via animatableData, so SwiftUI can smoothly interpolate shape changes.
2. Create Your Content View
Build whatever you want to show inside the notch. The content should be clipped to NotchShape and filled with black background:
struct NotchContentView: View {
var isVisible: Bool
var body: some View {
HStack {
Image(systemName: "mic.fill")
.foregroundStyle(.red)
Text("Recording")
.font(.system(size: 13, weight: .medium))
.foregroundStyle(.white)
}
.frame(width: isVisible ? 200 : 0)
.frame(height: 32)
.background(NotchShape().fill(.black))
.clipShape(NotchShape())
.animation(.spring(response: 0.35, dampingFraction: 0.75), value: isVisible)
.frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .top)
}
}
3. Add the NotchWindow
Copy references/NotchWindow.swift. This is a generic NSPanel that:
- Creates a borderless, transparent, non-activating panel
- Positions at
CGShieldingWindowLevel(above everything) - Centers at the top of the screen, flush with the top edge
- Ignores mouse events (fully click-through)
- Joins all spaces and survives fullscreen
4. Show and Hide
// Create once and reuse
let notchWindow = NotchWindow()
// Show with your content
let content = NotchContentView(isVisible: true)
notchWindow.showNotch(content: content)
// Hide with spring collapse animation
notchWindow.hideNotch()
Spring Animation Choreography
The Dynamic Island effect comes from a specific animation sequence:
Show:
- Window appears instantly (
orderFront) - On the next runloop tick,
isVisibletoggles totrue - The width animates from 0 to the target width with
.spring(response: 0.35, dampingFraction: 0.75)
This two-step approach (instant window, then animated content) is necessary because SwiftUI needs the view to be in the hierarchy before it can animate.
Hide (3-step choreography):
- Clear any expanded content (text, details) -- collapses to compact shape
- After 0.25s, set
isVisible = false-- triggers the spring width collapse to 0 - After 0.65s, remove the window (
orderOut)
The delays are tuned so each animation completes before the next starts. This creates the smooth "shrink into the notch" effect.
// Step 1: collapse content
state.isExpanded = false
// Step 2: shrink width
DispatchQueue.main.asyncAfter(deadline: .now() + 0.25) {
state.isVisible = false
}
// Step 3: remove window
DispatchQueue.main.asyncAfter(deadline: .now() + 0.65) {
window.orderOut(nil)
}
Screen Geometry Details
| Property | Value | Why |
|---|---|---|
| Window level | CGShieldingWindowLevel() | Above everything including menu bar |
| Position origin | NSScreen.main.frame (not visibleFrame) | Must include the notch/menu bar area |
| Horizontal | Centered: (screen.width - totalWidth) / 2 | Aligned with the hardware notch |
| Vertical | Flush top: screen.height - totalHeight | Top edge touches the screen edge |
| Collection behavior | .stationary, .canJoinAllSpaces, .fullScreenAuxiliary, .ignoresCycle | Doesn't move with Spaces, survives fullscreen, hidden from Cmd+Tab |
Fallback for Non-Notch Macs
Not all Macs have a notch (e.g., external displays, older MacBooks). You can detect this:
var hasNotch: Bool {
guard let screen = NSScreen.main else { return false }
// Notch Macs have a safe area inset at the top
return screen.safeAreaInsets.top > 0
}
For non-notch displays, fall back to a floating pill at the bottom of the screen using screen.visibleFrame and standard .floating window level.
Design Guidelines
- Fill the shape with solid black -- this is what makes it blend with the hardware notch
- Use white or colored text/icons on the black background for contrast
- Keep content compact -- the notch area is small. A single row with an icon + short text works best
- Use red for recording indicators -- matches iOS convention
- Animate width, not opacity -- the Dynamic Island effect is about the shape growing/shrinking, not fading
FAQ
What does the macos-notch-ui skill do?
Add a Dynamic Island-style notch UI to a macOS app. Use this skill whenever the user wants to create a notch overlay, notch extender, Dynamic Island for Mac, notch indicator, or any UI that extends from the MacBook notch area. Also trigger when the user mentions "notch shape", "notch window", "notch cutout", "notch panel", "recording indicator near the notch", "Dynamic Island style", or wants to show status/content that appears to emerge from the hardware notch. This covers the NSPanel setup, the NotchShape with concave Bezier ear curves, screen positioning math, spring animations, and show/hide choreography.
How do I install macos-notch-ui?
Run npx skills add https://github.com/fayazara/macos-app-skills --skill macos-notch-ui in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/macos-notch-ui/ (personal) or .claude/skills/macos-notch-ui/ (project).
Which AI agents can use macos-notch-ui?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is macos-notch-ui safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains macos-notch-ui?
It is published by fayazara in fayazara/macos-app-skills. It has 566 recorded installs.
More from fayazara/macos-app-skills
macos-patterns
fayazara/macos-app-skills
Essential native macOS development patterns that web developers don't know about. Use this skill whenever the user is building a macOS app and needs guidance on native patterns, or when they ask about menu bar apps, floating panels, window levels, keyboard shortcuts, file pickers, clipboard, drag and drop, screen capture, activation policy, Quick Look, launch at login, or any macOS-specific API. Also trigger when the user seems to be applying web development patterns to macOS (e.g., using z-index thinking for windows, expecting simple clipboard APIs, or not understanding focus/activation). This is the "how things actually work on macOS" reference that prevents the AI from generating confident but wrong code. Use this skill proactively whenever building any native macOS app.
macos-settings-ui
fayazara/macos-app-skills
Build a proper macOS settings/preferences window with liquid glass support for macOS 26 (Tahoe). Use this skill whenever the user asks to create a settings window, preferences UI, settings view, or preferences pane for a macOS app. Also trigger when the user mentions "liquid glass settings", "NavigationSplitView settings", "grouped Form settings", "macOS settings layout", or wants to add/fix/rebuild a settings screen in any native macOS SwiftUI app. This includes phrases like "add settings to my app", "create a preferences window", "my settings look wrong", "fix my settings UI", or even just "I need a settings view". If the user is building a macOS app and mentions settings or preferences in any context, use this skill.
macos-build
fayazara/macos-app-skills
Build a native macOS app using xcodebuild from the command line. Use this skill whenever the user asks to build, compile, or check if their macOS project compiles successfully. Also use it when the user asks to fix build errors, verify changes compile, or run a debug build. Trigger on phrases like "build the app", "does it compile", "run xcodebuild", "fix build errors", or even just "build".
macos-release
fayazara/macos-app-skills
Release a native macOS app to GitHub with DMG packaging and Sparkle appcast updates. Use this skill whenever the user wants to publish a new version, create a release, ship an update, push a release to GitHub, or update the appcast. Also trigger when the user mentions DMG creation, Sparkle signing, notarization, archiving, or anything related to distributing a new version of their macOS app. This covers the full release pipeline: archive, notarize, export, create DMG, sign with Sparkle EdDSA, update appcast.xml, git push, and GitHub release creation.
macos-auto-update
fayazara/macos-app-skills
Add Sparkle auto-update support to a native macOS app. Use this skill whenever the user wants to add auto-updates, implement Sparkle, set up an appcast feed, add "Check for Updates" to their app, or integrate automatic update checking. Also trigger when the user mentions Sparkle, appcast, SUFeedURL, EdDSA signing, or update notifications. This covers the full setup: adding the Sparkle SPM dependency, creating the UpdaterManager singleton, wiring it into the app delegate and UI, configuring Info.plist, and generating the initial appcast.xml.
Popular frontend & design skills
setup-matt-pocock-skills
mattpocock/skills
Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.
frontend-design
anthropics/skills
Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.
hyperframes-animation
heygen-com/hyperframes
All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.
prototype
mattpocock/skills
Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
hyperframes-core
heygen-com/hyperframes
The HyperFrames composition contract — build one renderable project. Use for composition structure, the data- timing attributes, class="clip", tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.
vercel-react-best-practices
vercel-labs/agent-skills
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.