/engineering-onboarding

name: engineering-onboarding
description: "Create an onboarding guide for an engineer joining a team that consumes the design system. Trigger when someone says: onboard new engineer, developer getting started guide, new engineer guide, engineering onboarding, first day for developers, frontend onboarding, or anything about helping an engineer new to the team get up to speed with the design system."
references:
  - ../../knowledge-notes/design-to-code-contract.md

Context

Engineering onboarding is genuinely different from designer onboarding. The mental model is different (consuming an API vs composing with a library), the first tasks are different (install and import vs connect Figma library), the tooling is different (package manager, TypeScript types, test harness vs Figma, documentation platform). Most importantly, engineers are where component drift originates — wrapping system components in local styled wrappers, hardcoding token values, reimplementing components locally. Proper onboarding from day one is the highest-leverage adoption intervention.

Key principles

**From design-to-code-contract:** Engineers and designers operate on opposite sides of the contract. Designers compose with a library (Figma, Storybook). Engineers consume an API (imports, props, types). The contract is the component signature: what props it accepts, what slots it exposes, what variants are possible. Component drift begins when an engineer builds a local wrapper because "the system component is close but not quite right" — escalating to designers too late means the system lost control. Onboarding embeds the contract from day one.

**Key principle for engineers:** Do not wrap system components. Do not hardcode values. Do not copy source code. Ask first.

Configuration

Before writing the guide, gather these inputs:

1. **Framework:** React, Vue, Web Components, Svelte, Angular, etc. 2. **Package manager:** npm, yarn, pnpm (include install command) 3. **Token consumption:** CSS custom properties, JavaScript imports, Tailwind theme config, Sass variables 4. **Component API patterns:** Props, slots, composition style, controlled vs uncontrolled patterns 5. **TypeScript:** Are component types exported? Import pattern for types? 6. **Testing:** Visual regression tool (Chromatic, Percy), unit testing patterns, accessibility testing expectations 7. **Contribution path:** How does an engineer propose a fix or new component? PR process, code review, approval gates 8. **Known rough edges:** Documented workarounds, temporary incompatibilities, or known limitations 9. **Team contacts:** Slack channel, primary system maintainer, office hours schedule

Steps

**Step 1: Gather system context from the team**

Ask directly: framework, package manager, token consumption method, TypeScript setup, testing tools, contribution expectations. If documentation exists, review it first — you're clarifying, not starting from scratch. Record which information is documented vs tribal knowledge (tribal knowledge is what gets lost in onboarding).

Output: A 5-minute conversation summary or Slack thread capture.

**Step 2: Structure the onboarding guide**

Use this exact section order. Each section builds on prior context. No forward references.

**Step 3: Write the guide introduction**

# Getting started with [Design System Name] — for engineers

**For:** Engineers joining [Team Name]  
**Last updated:** [Today's date]  
**Questions:** [Slack channel or contact email]  
**Estimated time:** 30 minutes to first component render

You're consuming a versioned component library and token system. Your job is to use it correctly, not to rebuild it. This guide shows you how.

**Step 4: Write "What [System Name] is" section**

One paragraph from engineer perspective. Answer: What am I consuming? What can it do? What shouldn't I do?

Example template:

[System Name] is a versioned component library with [X] components and [Y] design tokens. 
It's distributed as an npm package and consumed via import statements in your code. 
The system owns component styling and behavior — your job is to compose components correctly 
and reference tokens instead of hardcoding values. If you need a variant or component that 
doesn't exist, you ask the system team; you don't build a local version.

**Step 5: Write "Installation and setup" section**

Copy-pasteable commands. Mark placeholders in brackets, not in the command itself.

## Installation and setup

Install the package:
\`\`\`bash
npm install @[org]/[design-system-name]
\`\`\`

Import the CSS (or theme provider for React):
\`\`\`jsx
import '@[org]/[design-system-name]/styles/index.css';
\`\`\`

Verify it works — render a Button in your app:
\`\`\`jsx
import { Button } from '@[org]/[design-system-name]';

export default function App() {
  return <Button>Click me</Button>;
}
\`\`\`

You should see a styled button on the screen. If you see an unstyled button or an error, 
check the [install troubleshooting guide](link).

**Step 6: Write "Using components" section**

Import pattern. Prop API conventions. One complete code example. TypeScript types if applicable.

## Using components

All components are named exports. Import what you need:
\`\`\`jsx
import { Button, Input, Card } from '@[org]/[design-system-name]';
\`\`\`

Read prop documentation in Storybook: [link to component docs]. 
Every prop is listed with type and default value.

Example — a login form using system components:
\`\`\`jsx
import { Button, Input, Card, Text } from '@[org]/[design-system-name]';

export default function LoginForm() {
  const [email, setEmail] = useState('');
  
  return (
    <Card padding="large">
      <Text variant="heading">Sign in</Text>
      <Input 
        type="email" 
        placeholder="Email" 
        value={email}
        onChange={(e) => setEmail(e.target.value)}
      />
      <Button variant="primary">Sign in</Button>
    </Card>
  );
}
\`\`\`

For TypeScript, c