Onboarding

A skill for writing an onboarding guide for someone joining a team that consumes the design system. One guide, with a shared core and a section for the reader's role: designer, engineer, or both. Every fact in it comes from the repository, the Figma library, or the team; anything else is marked [confirm: …] and listed at the top so nobody publishes a guess.

Before you begin: verify references

Confirm that every path in this skill's frontmatter references: exists relative to this SKILL.md. If any is missing, stop: the install is incomplete, usually because a flattening installer (for example npx skills install) dropped the repo-root knowledge-notes/ directory. Tell the user to reinstall by a method in 1-INSTALL.md and run verify-install.sh from the install root. Proceed without the references only if the user explicitly says to, and then say in the output that it was produced without the pack's reference material.

Context

Onboarding docs fail in one of two ways. Written from the system team's side, they assume context and hand the newcomer a reading list instead of a path. Written from a template, they describe a generic design system rather than this one, so the reader learns nothing they couldn't have guessed. Designers and engineers also arrive at the system from opposite sides: a designer composes with a library (Figma, Storybook); an engineer consumes an API (imports, props, types). The drift both create starts in week one, when the system is "close but not quite right" and someone builds around it. A guide that is specific, honest about gaps, and clear about what to do when the system doesn't have something is the highest-leverage adoption work a team can do.

Step 0: Read before asking

Gather the facts from where they already live. Ask the team only for what these can't answer.

Config. .ds-ops-config.yml: system.name, system.framework, system.styling, integrations.figma.file_key, integrations.npm.package_name.

Repository. package.json (package name, exports, peer dependencies, scripts for build, test, lint, storybook), the token source or build output (CSS custom properties, JS token modules, Tailwind theme, Sass), exported TypeScript types, the test setup (Jest or Vitest, Chromatic or Percy, axe or similar), CONTRIBUTING.md, CHANGELOG.md, a docs site or Storybook URL in the README.