Bespoke Apple HIG design

Purpose & trigger

Design, refactor, and audit web interfaces against Apple Human Interface Guidelines using an 8pt grid, system typography, translucent materials, spring motion, and measured contrast. Use for HIG-aligned web UI, design-token work, Apple-adjacent product surfaces, or an accessibility audit of an existing interface.

Source

Portable instructions served exactly from the validated skill package.

---
name: bespoke-apple-hig-design
description: Design, refactor, and audit web interfaces against Apple Human Interface Guidelines using an 8pt grid, system typography, translucent materials, spring motion, and measured contrast. Use for HIG-aligned web UI, design-token work, Apple-adjacent product surfaces, or an accessibility audit of an existing interface.
---

# Bespoke Apple HIG Design

## Apply the system

1. Read the existing design system, theme mechanism, and brand constraints before adding tokens. Never overwrite an established token layer without authorisation; extend or namespace the addition instead.
2. Adopt `reference/tokens.css` as the token source. Map both `prefers-color-scheme` and any explicit theme attribute the project already uses, so a stored theme choice still wins over the system scheme.
3. Keep the system font stack. Introduce a web font only when a brand guideline overrides HIG, and state the override.
4. Size every margin, padding, and gap from the 8pt scale. Optical alignment may deviate; record the reason when it does.
5. Group related content into rounded surfaces on the secondary background token. Prefer elevation and background contrast over hard structural borders.
6. Reserve translucent material for fixed chrome that content scrolls beneath. Always pair it with an opaque fallback for engines without `backdrop-filter`.
7. Give standalone controls a 44x44px minimum hit area. Links inline in running text are exempt: enlarging them breaks the text block, so give the block adequate line spacing instead.
8. Express state with scale and opacity on spring curves, not abrupt colour flashes.
9. Honour `prefers-reduced-motion` by dropping transforms to opacity or removing the transition. Motion must never be the only signal for a state change.
10. Apply a visible focus ring with an offset to every focusable element.

## Verify before claiming

11. Run `reference/verify-hig.mjs` against the rendered page at 390px and 1440px in both colour schemes.
12. Report the measured contrast, touch-target, and grid results. An audit that was not run is not a pass.

## Protect design truth

- Body text needs 4.5:1. `--label-secondary` (~3.4:1 on white) and `--system-blue` (~4.0:1 on white) do not reach it. Use them for large text, secondary labels, and UI components, never for body copy.
- `--label-tertiary` (~1.7:1 on white) is decorative. Never place it behind text a user must read.
- Apple's system palette is tuned for Apple's own rendering. Re-measure contrast against the actual background in the project rather than assuming a token is safe.
- Translucent material changes effective contrast. Measure text over the composited result, not over the base token.
- Do not claim HIG conformance, platform endorsement, or Apple affiliation. This applies HIG principles to the web; it is not an Apple product and carries no Apple review.

Bundled files

• SKILL.md — Portable Apple HIG design instructions.
• reference/tokens.css — HIG design tokens with measured contrast notes.
• reference/verify-hig.mjs — Playwright evidence gate for the HIG contract.

Verification evidence

• Token contrast ratios computed from sRGB relative luminance and recorded in tokens.css.
• Evidence gate exercised against a rendered page; catches undersized controls, off-grid spacing, and sub-threshold contrast.

Known limitations

• Applies HIG principles to the web. It is not an Apple product and carries no Apple review.
• The gate measures computed styles only; it cannot judge visual hierarchy, copy, or brand fit.
• Contrast sampling walks ancestor backgrounds and cannot resolve text over images or gradients.