A production-grade skill reference library for building Next.js applications, grounded in the Apple Macintosh Human Interface Guidelines (1992).
Is an interface manual from 1992 still relevant today? Yes — because its principles are based on how humans work, not how computers work.
Humans don't get a new release every year. Our memory doesn't double. Our eyesight doesn't become sharper. Attention works the same way it always has. Visual recognition, motor skills — all exactly as they were in 1992.
The tech stack changes every few years. The human on the other side of the interface does not.
This library uses the HIG as its foundation and extends it into a complete reference for modern Next.js development — from design principles to authentication, from React performance to drag-and-drop.
references/
01-hig-1992-archive/ ← Primary source. Read this first, always.
02-design-principles/ ← HIG principles distilled for modern interfaces
03-bun-runtime/ ← Bun setup, APIs, package management
04-nextjs-app-router/ ← App Router, Server Actions, routing, caching
05-nextjs-performance/ ← Core Web Vitals, streaming, bundle optimization
06-data-fetching/ ← SWR, React Query, server/client strategies
07-react-patterns/ ← React 19 patterns, hooks, Server Components
08-react-performance/ ← 58 performance rules across 8 categories
09-react-composition/ ← Compound components, context, state patterns
10-web-interface/ ← Web interface guidelines, animations, Framer Motion
11-ui-shadcn/ ← shadcn/ui components, forms, theming
12-tailwind-css/ ← Tailwind v4+, dark mode, responsive design
13-navigation/ ← Navigation patterns, menus, routing, accessibility
14-drag-drop/ ← dnd-kit, kanban, sortable lists, file uploads
15-react-rnd/ ← react-rnd, floating panels, resizable widgets
16-i18n/ ← next-intl, locale routing, RTL, ICU plurals
17-auth-better-auth/ ← Better Auth, 2FA, organizations, security
18-security-compliance/ ← SOC 2, HIPAA, GDPR, PCI-DSS patterns
19-convex-backend/ ← Convex functions, realtime, agents, migrations
20-testing-deployment/ ← Testing strategies, deployment, CI/CD
A-os-style/ ← [Theme A] macOS OS shell — Dock, Finder desktop, RND panels, dnd-kit
SKILL.md ← Skill entry point (Claude Code)
| Layer | Technology |
|---|---|
| Runtime | Bun |
| Framework | Next.js 16+ (App Router) |
| Language | TypeScript (strict) |
| UI Library | React 19 |
| Components | shadcn/ui + Radix UI |
| Styling | Tailwind CSS v4+ |
| Auth | Better Auth |
| Validation | Zod |
| # | Directory | Contents |
|---|---|---|
| 01 | 01-hig-1992-archive/ |
Original Apple HIG 1992 — all 16 chapters: principles, menus, windows, dialogs, controls, icons, color, behaviors, language, checklist |
| 02 | 02-design-principles/ |
The 12 HIG principles distilled for modern interfaces, with design audit questions |
| # | Directory | Contents |
|---|---|---|
| 03 | 03-bun-runtime/ |
Bun installation, package management, APIs, testing, bundling |
| 04 | 04-nextjs-app-router/ |
App Router architecture, file conventions, Server Actions, caching, routing |
| 05 | 05-nextjs-performance/ |
Core Web Vitals, image/font optimization, streaming, bundle optimization |
| 06 | 06-data-fetching/ |
Next.js data fetching, SWR patterns, server/client strategies |
| # | Directory | Contents |
|---|---|---|
| 07 | 07-react-patterns/ |
React 19 patterns, hooks, Server Components, Actions, Compiler |
| 08 | 08-react-performance/ |
58 Vercel React performance rules + individual rule files |
| 09 | 09-react-composition/ |
Compound components, context patterns, state management, UX states, Zustand |
| # | Directory | Contents |
|---|---|---|
| 10 | 10-web-interface/ |
Web interface guidelines, animation patterns, Framer Motion |
| 11 | 11-ui-shadcn/ |
shadcn/ui component patterns, installation, forms, charts, theming |
| 12 | 12-tailwind-css/ |
Tailwind CSS v4+, responsive design, dark mode, animations |
| 13 | 13-navigation/ |
Navigation patterns, menus, breadcrumbs, mobile nav, accessibility |
| 14 | 14-drag-drop/ |
dnd-kit patterns, kanban boards, sortable lists, file uploads |
| 15 | 15-react-rnd/ |
react-rnd resizable/draggable panels, floating windows, controlled size/position, bounds, aspect ratio |
| 16 | 16-i18n/ |
next-intl, locale routing, ICU plurals, formatters, RTL |
| # | Directory | Contents |
|---|---|---|
| 17 | 17-auth-better-auth/ |
Better Auth, email/password, 2FA, organizations, security hardening |
| 18 | 18-security-compliance/ |
SOC 2, HIPAA, PCI-DSS, GDPR compliance patterns, policy-as-code |
| 19 | 19-convex-backend/ |
Convex functions, schema, realtime, agents, cron jobs, file storage, migrations |
| 20 | 20-testing-deployment/ |
Testing strategies, TypeScript security review, Next.js deployment |
Every rule in this library traces back to one of these:
| Principle | What it means |
|---|---|
| Metaphors | Use real-world models; don't over-constrain them |
| Direct Manipulation | Actions produce immediate, visible results |
| See-and-Point | Show options; never force memorization |
| Consistency | Same action = same result, everywhere |
| WYSIWYG | What is shown is what exists; no hidden states |
| User Control | The user drives; the application responds |
| Feedback | Every action produces a specific, immediate response |
| Forgiveness | Errors are cheap to reverse; exploration is safe |
| Perceived Stability | Behavior is predictable; trust is built through consistency |
| Aesthetic Integrity | Visuals serve function; decoration is noise |
| Modelessness | Avoid states that change the meaning of actions |
| Know Your Audience | Design for actual users, not hypothetical ones |
Full source: 01-hig-1992-archive/01-human-interface-principles.md
Design audit checklist: 01-hig-1992-archive/C-checklist.md
This library ships as a Claude Code skill. Place the human-interface-guidelines/ directory in your project's .claude/skills/ folder.
The skill (SKILL.md) instructs the agent to read the HIG before making any design or implementation decision:
Before writing a single line of code or making any design decision, read:
1. references/01-hig-1992-archive/01-human-interface-principles.md
2. references/01-hig-1992-archive/02-general-design-considerations.md
3. references/01-hig-1992-archive/C-checklist.md
4. references/02-design-principles/design-principles.md
The HIG 1992 reference files were generated from the original PDF using hig_skill_generator.py — a pipeline that renders each chapter as images and extracts structured markdown via Grok vision.
The library was then audited and corrected using hig_skill_auditor.py — a second pipeline that passes the full HIG content to Grok for each reference file, detects HIG violations and cross-file contradictions via rolling memory, and rewrites files in place.
Lettered directories (A-, B-, …) are self-contained app-shell themes. Each theme bundles its own references, ready-to-use components, and a standalone SKILL.md. Use a theme when you want to adopt a complete visual and interaction paradigm rather than assembling patterns from scratch.
| Letter | Theme | Description |
|---|---|---|
| A | A-os-style/ |
macOS-inspired OS shell — Dock navigation, Finder-style desktop icon grid, floating resizable panels (react-rnd), drag-and-drop (dnd-kit), right-click context menus, global keyboard shortcuts |
The Apple Human Interface Guidelines (1992) are the property of Apple Inc. The reference files in 01-hig-1992-archive/ are derivative works for educational purposes.
All other content in this repository is original work released under the MIT License.