gentleduck/primitives Course
Advanced, project-oriented curriculum for building accessible component systems with gentleduck/primitives.
This course is a systems track, not a demo track. You will build production-quality wrappers and learn how primitives behave under real constraints: nested overlays, async workflows, keyboard-first navigation, and accessibility audits.
Outcomes
After completing the course, you should be able to:
- Build and ship design-system wrappers around primitives.
- Choose controlled vs uncontrolled strategies intentionally.
- Debug focus, dismissal, and layering issues quickly.
- Implement robust motion with
Presenceand reduced-motion support. - Verify accessibility with keyboard and screen reader workflows.
- Build quality gates that catch interaction regressions early.
- Run an internal registry of vetted primitive wrapper examples.
How to run this course
Recommended cadence:
- Read one lesson.
- Build the lab in a local playground.
- Add one production constraint (async, nesting, RTL, or reduced motion).
- Validate with keyboard and screen reader checks.
If you only copy snippets, you will miss the behavioral contracts that matter in production.
Curriculum
| # | Lesson | Core topic | Production lens |
|---|---|---|---|
| 1 | Why Primitives | Behavioral abstraction | What complexity you should never rebuild manually |
| 2 | Your First Dialog | Compound anatomy | State ownership and guarded dismiss flows |
| 3 | The asChild Pattern | Composition model | Ref safety and prop merging contracts |
| 4 | Popover and Positioning | Popper placement | Collision strategy and anchor modeling |
| 5 | Menus, Dropdowns, and Selection | Complex selection UIs | Keyboard routing, item semantics, and submenus |
| 6 | Animation with Presence | Mount lifecycle | Exit timing, forceMount, and reduced-motion policy |
| 7 | Accessibility Deep Dive | ARIA + focus rules | Practical audits and failure modes |
| 8 | Building a Design System | Wrapper architecture | API consistency, defaults, and scaling patterns |
| 9 | Testing and Quality Gates | Reliability engineering | Interaction tests, a11y assertions, CI gates |
| 10 | Operations, Migration, and Internal Registry | Long-term operations | Rollout safety, governance, migration, registry |
Prep checklist
Before lesson 1:
- Install
@gentleduck/primitives. - Create a playground app where you can iterate quickly.
- Set document and provider direction (
ltrorrtl). - Have one keyboard and one screen-reader pass workflow ready.
Suggested capstone
Build this in your own repo while taking the course:
Dialogwrapper with guarded async close.Popoverwrapper with side-aware motion.Menuwrapper with checkbox/radio semantics.Tooltipwrapper with provider defaults.- Internal registry entries for each wrapper with examples and test references.
If you are following this inside this monorepo, use packages/registers/registry-internal/registry-internal.ts as the internal registry entry source.
Then write a short engineering note explaining:
- Why you chose controlled vs uncontrolled for each.
- Which accessibility checks you automated vs manual.
- Which defaults belong in wrappers vs app usage.
Coverage map
Use API docs as the canonical prop/event source: