macOS 27 design kit
Read when: you build, restyle, review or draw Mac UI and need the exact number Apple's kit uses. Owns: the macOS 27 kit's measured values — colours, text styles, materials, control styles and every component page.
The values come from Apple's macOS 27 UI Kit (developer.apple.com/design/resources, Sketch v27.0.3, 28 October 2026), read by script. Apple's licence for the Apple Design Resources applies to the kits themselves; this skill holds only measured values and written descriptions, not Apple's files or artwork.
TL;DR
- Take values only from these files. If a value is not here, say "not in the kit". Why: a guess from memory, the HIG or a framework default looks right and is off by a point or a shade, which is the error this skill exists to stop.
- Every colour has a light and a dark value. Vibrant colours (
… Vibrant (use plus darker)/(use plus lighter)) only look right drawn with that blend mode. - Content Area and Over-glass are two contexts. The kit draws a control one way on window content and another way on glass bars (toolbars, sidebars). Pick the one where the control sits.
- The system control comes first. Use these specs to check a custom part against Apple's, to restyle a custom component so it matches, or to draw Mac UI in images (website art, App Store pages).
- Start with the component's reference. Go to the raw page dump only for a value no reference lists, and name the component line it came from.
Where each topic lives
| Need | File |
|---|---|
| A colour (system colours, labels, fills, grays, separators, window backgrounds) | references/colors.md |
| A text style (Large Title … Caption 2, emphasized, loose and tight leading) | references/text-styles.md |
| Liquid Glass and materials | references/materials.md |
| Window, panel, sidebar backgrounds and global helpers (focus ring, glyph styles) | references/surface-styles.md |
| The fill a control uses per state (Idle, Hover, Clicked, Disabled) on window content | references/control-styles-content-area.md |
| The same on glass bars | references/control-styles-over-glass.md |
| The kit's setup notes and licence, in summary | references/getting-started.md |
| One component | references/<component>.md, listed below |
Components
Windows and bars: windows, titlebars-and-toolbars (values in titlebars-and-toolbars-values), sidebars, menu-bar-and-dock, popovers, alerts, dialogs, notifications, tooltips
Buttons and menus: buttons (colours in buttons-colours), pop-up-and-pull-down-buttons, segmented-controls, menus, disclosure-controls
Toggles: checkboxes, radio-buttons, switches
Fields and forms: text-fields, search-fields, combo-boxes, forms, steppers, color-wells, image-wells
Values and progress: sliders, progress-indicators, scrollbars, group-boxes
Other: pointers, product-bezels
Each component file lists what the kit leaves out and where the kit contradicts itself, so you can name the source instead of guessing.
The raw page dump (specs/, built locally)
Component references cite specs/<page>.txt. That folder is not shipped: it is a full dump of Apple's kit file,
so you build it on your own machine from your own download of the kit (steps 1–3 under "Updating to a newer kit",
then pass the dump folder to gen_tokens.py). Keep it out of anything you publish.
Each line is one layer; indentation shows nesting.
| Token | Meaning |
|---|---|
COMPONENT "A/B/C" W×H |
A kit component. The name path holds its variant axes: appearance, context, size (Mn, Sm, Rg, Lg, XL) and state |
BOARD |
A documentation artboard |
@x,y |
Position inside the parent, in points |
use "…" → Path [overrides] |
An instance of another component, with its overrides |
text "layer" "content" Font size lhN kernN colour align |
Font is a PostScript name, lh is line height, kern is tracking |
fill … |
Stacked fills, bottom first |
border W inside |
Border width and position |
shadow / inner-shadow |
x, y, blur, spread, colour |
blur background / blur glass |
Background blur or Sketch's glass effect, with radius and the other values |
corners R smoothingS styleN |
Corner radius (max = capsule or circle) and smoothing |
radius R |
Corner radius set per point |
stack h|v gapN padT,R,B,L |
Auto layout |
#RRGGBB@NN% |
Colour with alpha |
{Name} |
The kit swatch the colour is bound to |
style="…" |
A shared layer style |
blend plus-darker / blend plus-lighter |
Blend mode |
Hidden layers are left out. specs/change-log.txt lists Apple's changes per kit version.
Updating to a newer kit
Run from this skill's folder. Python 3.10 or newer.
- Download the macOS Sketch kit from Apple Design Resources (its link is a sketch.com share with a Download button). Accept Apple's licence there yourself.
- Unzip its JSON into a work folder outside this skill:
unzip "Apple macOS 27 UI Kit.sketch" 'document.json' 'meta.json' 'pages/*' -d <work>/kit. - Dump the pages:
python3 scripts/extract.py <work>/kit <work>/dump. - Rebuild the token pages:
python3 scripts/gen_tokens.py <work>/kit . <work>/dump. This rewritescolors.md,text-styles.md,materials.md,surface-styles.mdand both control-style pages, and copies the dump tospecs/. - Rewrite the component references whose pages changed;
specs/change-log.txtlists what Apple changed. - Check the new pages stay under 400 lines; split a long one into
<name>.mdand<name>-values.md.