Help

User Guide

The same guide ships inside the app. Press ⌘? in ColorPickr to open it.

Getting Started

Install

Open ColorPickr.dmg and drag ColorPickr onto the Applications folder. Then open it from Applications or Launchpad.

If you open ColorPickr straight from the installer or from Downloads, it offers to move itself to Applications and reopens from there. Say yes: updates and the Screen Recording permission need it to stay in one place.

ColorPickr lives in your menu bar. Look for the eyedropper near the clock. Click it for your latest color, every format, history, and the color vision controls.

Three shortcuts cover most of what you'll do:

⌃⌥C picks a color from anywhere on screen.
⌃⌥V shows your whole screen as someone with a color vision deficiency sees it.
⌃⌥L opens the vision lens, a window that simulates only what's under it.
⌃⌥K opens the command palette: type what you want and press Return.
⌃⌥P shows the floating palette: a project's colors over every app.

Change any of them in Settings › Shortcuts.

Screen Recording permission

macOS only lets apps read screen pixels with Screen Recording permission. ColorPickr asks the first time you pick. Turn it on in System Settings › Privacy & Security › Screen & System Audio Recording, then relaunch ColorPickr.

> ColorPickr never records, saves or uploads your screen. It reads only the pixels you pick, plus the live frames the vision simulation filters on your Mac.

Command Palette

Press ⌃⌥K from any app, or ⌘K while a ColorPickr window is in front. Type a few letters and press Return.

"deut" simulates deuteranopia. "lens" opens the vision lens.
"exp orange tail" copies your Orange palette as Tailwind.
"theme blue" makes a theme from your Blue palette.
Type a color like #2563EB to copy it in any format, make a scale, or start a palette.
Leave it empty to see your recent commands.

Use ↑ and ↓ to choose and Esc to close.

Picking Colors

Press ⌃⌥C. The screen freezes and a magnifier follows your cursor.
Click to pick the pixel in the outlined center square.
The color lands in your history and, by default, on your clipboard.

While the magnifier is open:

Arrow keys move one pixel. Hold ⇧ to move ten.
1, 3 or 5 switch between one pixel and a 3×3 or 5×5 average. Averages are computed in linear light, so antialiased edges read correctly.
Scroll or + and − zoom.
⇧-click picks and keeps the magnifier open, so you can grab several colors in a row.
Esc or a right-click cancels.

Pick into a project

The Pick button appears wherever you work, and it picks into what's in front of you:

In the Library with a board open, picked colors land on the board as chips.
In the Color Wheel, the pick becomes the wheel's base color.
In the floating palette, picks go into its board or palette.

Everywhere else, picks go to your history as usual.

Formats

Every pick is available as HEX, RGB, HSL, HSB, CMYK, OKLCH, Lab, Display P3, SwiftUI, NSColor, UIColor and a CSS variable. Click any row in the menu bar panel to copy it. Choose the format that copies automatically in Settings › General.

Wide-gamut colors

ColorPickr samples in Display P3, so colors richer than sRGB survive. When a pick falls outside sRGB, the panel says so. HEX, RGB and HSL then show the closest sRGB color, while Display P3, OKLCH and native Swift code keep the original.

Mood Boards

Designers think in pictures, so ColorPickr keeps your references next to the colors they inspire.

Open the Library and choose Create › Mood Board, or press ⌘O to pick image files.
Drop photos, screenshots or images dragged from a browser. Paste with ⌘V. Add as many as you like.
The palette at the top updates as the board grows. Every image counts equally, so one large photo can't drown out the rest. Use the stepper to choose how many colors.
Turn on Pick from Images (the eyedropper in the toolbar) and click any image to pin that exact color. A preview follows your pointer. Picked colors become color chips on the board and always lead the palette.
Click Save as Palette. The palette remembers its board and shows the images at the top, so the reference is always one click away. After you change the board, Update Palette refreshes it.

The canvas

Boards open as a freeform canvas. Arrange things the way you think about them.

Drag anything to move it. Drop images exactly where you want them.
Resize with the handle at the bottom-right corner of a selected item. Images and color chips keep their shape.
Add › Note puts a note on the board. Double-click a note to write in it.
Click a color chip to copy it. Double-click it to open it in the Color Wheel.
Tidy Up arranges the images in columns with chips and notes beside them.
Right-click any item to bring it to the front, send it back, duplicate it or delete it. Delete removes the selected item and Esc deselects.
Zoom with a pinch, the controls in the corner, ⌘+, ⌘−, ⌘0 for actual size or ⌘9 to fit.

Prefer a plain grid? Switch with the Canvas / Grid control in the toolbar. Hover an image in the grid to see its own main colors. Double-click the board's name to rename it.

> Every extracted color is a real pixel from your images, never a blend. ColorPickr also ignores the in-between colors that antialiasing creates along edges.

Boards and their images live in ~/Library/Application Support/ColorBody/Boards. ColorPickr keeps a copy of each image, in its original quality, so moving or deleting the original doesn't break the board.

Value Study

Painters squint to see light and dark without color. Values in a board's toolbar does it for you.

Values shows the whole board in grayscale, images and colors alike.
3 Values and Light & Dark simplify everything to three or two tones, so you can check that a composition reads before color takes over.
Your images and colors never change. Switch back to Color any time.

From a website

Choose Create › From Website (or File › Colors from Website, ⇧⌘U), paste an address such as stripe.com, and click Get Colors. ColorPickr opens the page privately, with no cookies or login, and waits for it to finish: loading screens gone, fonts and images in, nothing still changing. It scrolls once to wake up lazy content, then saves a screenshot to a new mood board. The chips are the colors the page actually paints, weighted by how much of the screen each covers, followed by colors only its CSS uses (like hover states). The site's own theme color comes first, and brand colors are favored over the grays most sites use everywhere. Busy sites can take up to half a minute.

On a board, Add › Website… adds a site to that board. You can also copy a link and press ⌘V on a board.

Drag an area on screen

Press ⌃⌥C, then drag a rectangle instead of clicking. ColorPickr saves that part of the screen to the board you opened last (or a new Screen Picks board) and opens it, so its colors join the board's palette. Collecting references from websites and apps is one gesture each.

Floating Palette

Keep a project in view while you work in Figma, Photoshop or your code editor. The floating palette is a small translucent panel that stays above every app and every Space, including full-screen apps, without taking focus away from what you're doing.

Press ⌃⌥P, click Float in the menu bar panel, or click Float in any board or palette toolbar.
Choose the board or palette from the title at the top.
Click a swatch to copy it. Drag it into any app: apps that take colors get the color, everything else gets its hex.
Pick sends what you pick straight into the project, as a chip on a board or a swatch in a palette. ⇧-click to pick several in a row.
Your latest pick sits under it. Click + to add a color you picked earlier.
For a board, the reference images stay in view below the colors. Turn them off in the ⋯ menu.

Drag the panel anywhere. Drop it near an edge or a corner and it snaps there. The ⋯ menu also moves it to an exact spot and switches between a tall Column and a wide Bar. Resize it from any edge. It remembers where you left it.

Brand Sheets

A brand sheet is a one-page summary to send to a client or a developer: the reference images, every color with its HEX, RGB and OKLCH values, and the text pairs that pass WCAG AA. A theme's sheet shows every role in light and dark.

Click Brand Sheet in the toolbar of any mood board, palette or theme. Choose a light or dark background, then Save PDF, Save PNG or Copy Image. PDFs stay sharp at any size; PNGs are rendered at twice the size for Retina screens and slides.

Paste or import

Choose Create › Paste or Import in the Library, or File › Paste or Import Colors (⇧⌘I). Not sure what to paste? Click Try an Example. Paste CSS variables, a Tailwind config, JSON design tokens or a plain list of colors, and ColorPickr finds every color and its name. You can also drop an Adobe Swatch Exchange (.ase) or Apple Color List (.clr) file.

Palettes and Scales

The Library holds your palettes. Open it from the menu bar panel or with File › Open Library.

Add to Palette in the menu bar panel saves the current pick.
Tonal Scale turns one color into a 50 to 950 ramp. Your exact color stays at its nearest step.
Click a swatch to copy it. Right-click for other formats, a scale, or removal.
Rename a palette or a color by clicking its name.

Palette Studio

Create › Palette Studio (⇧⌘G) deals you a fresh palette every time you press Space.

Click the lock on a color you like. Space rerolls everything else and builds around what you kept.
Every roll has a light color and a dark color that are easy to read on each other, so the palette is usable out of the box.
Choose 3 to 8 colors. Drag columns to reorder. Back returns to the previous roll.
Click a color to copy it, or open it in the Color Wheel.
Save as Palette keeps it. Make Theme turns it into four finished themes.

Color Wheel

Create › Color Wheel shows every hue and chroma at one lightness, drawn in OKLCH, so colors at the same distance from the center look equally vivid. Most wheels can't promise that: on an HSL wheel, yellow glows and blue sinks.

Drag any handle. The whole harmony turns with it.
Handles stop at the edge of the gamut, so every color on the wheel is one you can ship. The faded area past the edge is out of reach at this lightness.
Choose sRGB for colors that work everywhere, or Display P3 for the richer colors Mac and iPhone screens show. In P3, a dashed line marks where sRGB ends.
The lightness slider moves the whole wheel lighter or darker. Your chroma comes back when you slide back.
Arrow keys fine-tune: left and right turn the hue, up and down change chroma.
Compare plots any palette on the wheel, so you can see at a glance whether its hues are balanced or crowded.
Save as Palette keeps the harmony. Click any color to copy it.

Open any color in the wheel from Harmony in the menu bar panel, or by right-clicking a palette or board color.

Harmonies

Harmony in the menu bar panel, or Make Harmony on any palette color, builds complementary, analogous, triadic, split complementary, square or monochromatic sets. ColorPickr rotates hue in OKLCH at your color's lightness and chroma, so every member carries the same visual weight.

Edit in OKLCH

Right-click a palette color and choose Edit in OKLCH. Drag lightness, chroma and hue, and compare before and after. Lock lightness keeps contrast steady while you explore hue and saturation. The ΔE readout shows how far you've moved; under 0.02 is invisible.

Gradient Builder

Create › Gradient Builder blends two to five colors and shows the same blend through sRGB, OKLab and OKLCH side by side. sRGB, the CSS default, dips through gray between distant hues; OKLCH stays vivid. Copy CSS gives you a fallback line plus the modern in oklch version. Save Steps as Palette keeps the stops.

Color names

Every pick shows its nearest CSS color name, like "≈ Coral", handy when naming tokens or describing a color out loud. New palette colors get plain names that account for lightness: a dark yellow-green is "olive", a dark blue "navy", a pale green "mint".

Presets

Create › Presets offers ready-made palettes: colors inspired by well-known brands, film looks like Teal & Orange or Neon Noir, and data-viz sets for charts, including the color-blind-safe Okabe-Ito palette and Viridis. Add copies one into your palettes so you can edit, theme and export it.

Themes

A theme says which color does which job, in light mode and in dark mode: the background, the cards, the text, the buttons. ColorPickr shows it the way you'll judge it, on real screens.

Make a theme

Click Make Theme on any mood board or palette. ColorPickr offers four finished themes made from your colors:

Brand: your main color leads, on clean neutrals.
Calm: soft, quiet and easy on the eyes.
Bold: saturated and tinted, using a second color from your set if there is one.
Midnight: made for a rich dark mode.

Switch between a Website, an App and a Dashboard, and between light and dark, to compare them. Click one and Use it, or double-click. Every option is easy to read in both modes before you change anything.

A theme made from a board appears on the board's canvas as a live preview. Use the sun and moon button on the card to flip it, and double-click it to edit.

Change a color

Open the theme. The preview is live: click anything in it, such as a button, the page background or a card, and choose its new color on the right. The choices are the colors the theme was made from, lighter and darker steps of the current color, and the theme's other colors. The sun and moon switch picks which mode you're changing.

Each color in the list shows a green check when everything that uses it is easy to read, or an orange warning when something isn't. Make It Readable fixes it with the smallest change that passes.

Try Another Style shows the four styles again for this theme's colors.

Advanced

Under Advanced you'll find the full role table (rename roles, add your own, point them at palette colors) and the detailed WCAG checks. Name roles by job: a role called on-x is checked against x, and anything starting with text is checked against background and surface.

Design QA

Fix contrast in one click

When a color fails AA as text on white or black, the menu bar panel shows Fix. ColorPickr finds the nearest color that passes, keeping the hue and changing only lightness, then copies it and makes it your current pick. In a theme, Fix on a failing check updates that role. In a palette's Contrast tab, right-click a failing pair to add a fixed text or background color.

Match to your palettes

Every pick is compared with your palettes. "Matches Orange 600" means it's exact. "Looks identical to" means the difference is too small to see. "Close to" means it's near but not the same, which is how you spot a developer's hard-coded color drifting from the design.

Color-blind collisions

Palettes and themes warn when two colors that most people tell apart look nearly identical with protanopia, deuteranopia or tritanopia. Preview shows the palette as those users see it.

> Material Design's error red and success green are a textbook case: they collide under deuteranopia. If colors carry meaning, pair them with an icon or a label.

Contrast

The menu bar panel tells you whether each pick is readable as text on white and on black: Easy to read, Big text only or Hard to read, with the WCAG 2 ratio and APCA lightness contrast (Lc) underneath.

A palette's Contrast tab shows every color as text on every other color as background. Switch between WCAG 2 and APCA, and turn on Only passing pairs to hide the rest.

WCAG 2: 4.5:1 passes AA for body text, 7:1 passes AAA, 3:1 passes for large text.
APCA: an absolute Lc of 60 or more is a sound floor for content text. Positive means dark text on a light background.

Contrast Checker

Create › Contrast Checker tests one text color on one background with a live preview: headlines, body text, small print and buttons.

Pick either color from the screen with its Pick button, or type a hex code. The arrows swap them.
Each kind of text gets a plain verdict, with the WCAG 2 ratio and APCA Lc beside it.
Fix Text Color or Fix Background keeps the hue and changes lightness only, by the smallest amount that makes body text easy to read.
Save Pair as Palette keeps the result.

Color Vision

About 1 in 12 men and 1 in 200 women see color differently. ColorPickr shows you how your work looks to them.

⌃⌥V filters your whole screen, live. Clicks pass through, so keep working.
⌃⌥L opens a lens window that simulates only what's under it. Drag it over part of a design to compare.
Choose the type in the menu bar panel: protanopia (red-blind), deuteranopia (green-blind), tritanopia (blue-blind) or achromatopsia (no color).
The severity slider covers the milder, far more common forms, such as deuteranomaly.

In the Library, Preview as redraws a palette and recomputes its contrast grid as seen with each condition.

> Red and green status colors are the classic failure. Under deuteranopia they turn into nearly the same olive. Pair color with an icon or a label.

Export

Palettes and themes export from the Export menu in the Library toolbar. Copy to the clipboard or save a file.

CSS variables. Themes switch with the system's dark mode, or with data-theme="dark" on any element.
Tailwind v4 @theme blocks, and a Tailwind v3 config for palettes.
Design Tokens JSON in the W3C format. Theme roles reference palette colors, so token tools keep the link.
SwiftUI. Themes become colors that adapt to light and dark automatically.
Android colors.xml resources.
Adobe Swatch Exchange (.ase) for Photoshop, Illustrator and InDesign.
Apple Color List (.clr). Save it into ~/Library/Colors to use the palette in any Mac app's Colors panel.
Xcode Asset Catalog. Drag the folder into Xcode. Theme colors carry both appearances.
SCSS variables, Material UI palettes, Flutter and Jetpack Compose color constants, and CSV for spreadsheets.
Procreate Swatches (.swatches). AirDrop the file to your iPad and tap it to add the palette to Procreate.

Keyboard Shortcuts

⌃⌥C pick a color (global)
⌃⌥V toggle the vision simulation (global)
⌃⌥L toggle the vision lens (global)
⌃⌥K command palette (global), or ⌘K inside ColorPickr
⌃⌥P show or hide the floating palette (global)
⌘N new palette
⌘O new mood board from image files
⇧⌘I paste or import colors
⇧⌘U colors from a website
⇧⌘G Palette Studio, then Space for new colors
⌘V paste images (on a mood board)
⌘+, ⌘−, ⌘0, ⌘9 zoom in, zoom out, actual size, fit (on a board's canvas)
⌘? this guide
⌘, settings

In the magnifier: arrows, ⇧ arrows, 1, 3, 5, scroll, ⇧-click, drag, Esc.

Updates

ColorPickr checks for updates in the background and never interrupts you. When a new version is ready, the eyedropper in the menu bar gets a small dot and the panel shows Update. Click it to see what's new and install. ColorPickr restarts on the new version with everything where you left it.

Check any time with Check for Updates… in the panel's ⋯ menu, the ColorPickr menu, or the command palette.
In Settings › Updates, turn automatic checks on or off, or let updates download in the background so they install the next time you quit.

Uninstall

Quit ColorPickr from the panel's ⋯ menu, then drag it from Applications to the Trash. Your boards, palettes and themes stay in ~/Library/Application Support/ColorBody in case you come back. Delete that folder to remove them too.

Privacy

ColorPickr works offline. Your history, palettes, themes and mood boards stay on your Mac in ~/Library/Application Support/ColorBody (the folder keeps the app's original name). Screen pixels never leave your Mac. ColorPickr connects to the internet only for the update check, which sends your app version and macOS version, and when you ask it to read a website, when it visits that address and nothing else.

Undo

⌘Z undoes changes to boards, palettes and themes: a moved or deleted image, a renamed palette, a changed theme color, a whole new theme. ⇧⌘Z redoes. Typing and dragging count as one step each. Undo works while the Library is open and covers everything since ColorPickr started.

Backups and Feedback

The first time a new version of ColorPickr opens, it copies your history, palettes, themes and boards list to ~/Library/Application Support/ColorBody/Backups before reading them. The five newest backups are kept. After an update, What's New opens once to show what changed.

Help › Send Feedback opens a new report with your ColorPickr version, macOS version and Mac model already filled in. It's also in the menu bar panel's ⋯ menu.

Troubleshooting

Picking shows a permission alert even though access is on

macOS ties the permission to the app's exact signature. After installing a new build, remove ColorPickr from the Screen Recording list with −, open ColorPickr, and allow it again.

An older copy is still running. Quit both from their menus and open ColorPickr again. New launches replace older copies automatically.

The vision simulation looks doubled or smeared

Turn it off and on with ⌃⌥V. If it persists, quit and reopen ColorPickr, and report it from Help › Send Feedback.