Onboarding

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.

Figma. If a Figma MCP is connected and a file key is known: the library's page names, the variable collections and their modes, whether tokens are styles or variables, and the published component set names. If not, ask for the library link and mark the rest [confirm].

Existing onboarding. A README section, a wiki page, a Notion doc. If one exists, this skill updates it rather than starting over: keep what is accurate, replace what the files contradict, and say what changed.

Record which facts came from files and which from the team. Anything neither confirms goes in as [confirm: …].

Step 1: Ask the team for the rest

• Who the reader is: a designer, an engineer, or a guide with both sections
• Team contacts: channel, primary maintainer, office hours if any
• The contribution route: how someone proposes a fix or an addition, and roughly how long it takes
• Policies that are decisions, not facts in the repo: the accessibility guarantee the system makes and against which standard, how often consumers are expected to update, what the team's rule on local wrappers and overrides is, whether Figma library updates are pushed or pulled
• Known rough edges: documented workarounds, components that are mid-migration, docs that lag

Don't fill a policy in from good practice. "Update monthly" is a policy the team sets, not a fact the skill knows. Leave it as [confirm: update cadence].

Step 2: Write the guide

Use this order. Each section stands alone; no forward references. Write examples in the detected stack (Vue single-file components, Web Components, Vitest and so on), using the real package name, exports, token names and Figma library names.

# Getting started with [System name]

**For:** [designers / engineers / both] joining [team]
**Last updated:** [today]
**Questions:** [channel or contact]
**Still to confirm:** [every `[confirm: …]` left in the guide, or "none"]

Shared core (every reader)

What [System name] is. One paragraph from the reader's side: what the system covers (components, tokens, patterns, docs), what it deliberately doesn't (product-specific patterns, local conventions), who maintains it, and where it lives (Figma library, docs URL, package name). Be honest about the current state: "the component library is mature; the docs are catching up in [area]" is more useful than "comprehensive".

How we work.

• Start with what exists. If the system has it, use it.
• Tokens are decisions the system owns. In Figma they are [styles / variables, from Step 0]; in code they are [the token access pattern, from Step 0]. Never hardcode a value the system has a token for; use semantic tokens, not primitives, so theming keeps working.
• When the system doesn't have what you need: check the docs, ask in [channel], check whether another team has solved it, then raise it through [the contribution route]. Don't build a local version first; local versions are where drift starts. [confirm: the team's rule for temporary workarounds, if any]

Your first two weeks. Checkbox tasks that start with orientation and end with one real piece of work using only system parts. Include one human task: pair with [name] on a recent feature built with the system.

Common questions. Four or five the reader will actually ask: the system doesn't have X; I found a bug; can I modify a component; who owns this; how do I keep up with changes. Answers come from Step 0 and Step 1, or are [confirm].