Documentação e transferência para a equipe

Why Documentation Is a First-Class Concern

Component Usage Documentation

/* Example component documentation structure */

# Button

## When to use
Use Button for primary actions (Save, Submit), secondary actions
(Cancel, Back), and destructive actions (Delete, Remove).
Do NOT use Button for navigation — use a Link component instead.

## Variants
[Live Storybook iframe: AllVariants story]

## Props
| Prop     | Type                              | Default   | Description |
|----------|-----------------------------------|-----------|-------------|
| variant  | primary|secondary|ghost|danger   | primary   | Visual style |
| size     | sm|md|lg                        | md        | Button size  |
| disabled | boolean                          | false     | Disable state |

## Accessibility
Icon-only buttons must include aria-label.

Storybook as Living Documentation

// Button.stories.tsx
const meta: Meta<typeof Button> = {
  component: Button,
  title: 'Primitives/Button',
  tags: ['autodocs'],  // ← enables auto-generated docs page
  parameters: {
    docs: {
      description: {
        component: 'Primary action trigger. Supports four visual variants and three sizes.',
      },
    },
  },
};
export default meta;

// In Button.tsx — JSDoc populates the props table:
interface ButtonProps {
  /** Visual style variant */
  variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
  /** Button size — controls padding and font size */
  size?: 'sm' | 'md' | 'lg';
}

Token Documentation Page

/* Token documentation page example */

# Color Tokens

## Semantic Colors

| Token              | CSS Variable           | Value       | Swatch |
|--------------------|------------------------|-------------|--------|
| color.primary      | --color-primary        | #2563eb     |   ■    |
| color.surface      | --color-surface        | #ffffff     |   □    |
| color.text.primary | --color-text-primary   | #111827     |   ■    |

## Usage
Always use semantic tokens in components:
`bg-primary` ✅ not `bg-blue-600` ❌

Writing a Getting Started Guide

# Getting Started

## 1. Install the package
npm install @acme/ui

## 2. Add the Tailwind preset
```js
// tailwind.config.js
module.exports = {
  presets: [require('@acme/tailwind-config')],
  content: ['./src/**/*.{js,ts,jsx,tsx}'],
};

## 3. Import global styles
import '@acme/ui/styles/globals.css';

## 4. Use a component
import { Button } from '@acme/ui';
export default function App() {
  return <Button variant='primary'>Hello design system!</Button>;
}

Changelog and Release Notes

# Changelog

## [2.0.0] — 2026-06-20
### Breaking Changes
- Button: renamed `variant='danger'` to `variant='destructive'`
- Input: `errorText` prop renamed to `error`

## [1.3.0] — 2026-06-01
### Added
- Toast component with success/error/warning/info variants
- Tooltip component (CSS-only)
- Avatar component with size variants and initials fallback

## [1.2.1] — 2026-05-15
### Fixed
- Button: missing focus-visible ring in Safari

Publishing as an npm Package

// packages/ui/package.json
{
  "name": "@acme/ui",
  "version": "1.3.0",
  "main": "./dist/index.cjs",
  "module": "./dist/index.esm.js",
  "types": "./dist/index.d.ts",
  "exports": {
    ".": {
      "import": "./dist/index.esm.js",
      "require": "./dist/index.cjs",
      "types": "./dist/index.d.ts"
    },
    "./styles/globals.css": "./dist/styles/globals.css"
  },
  "scripts": {
    "build": "tsup src/index.ts --format esm,cjs --dts --out-dir dist"
  }
}

Semantic Versioning and Codemod

// codemods/2.0.0-rename-danger-variant.js (jscodeshift)
export default function transform(file, api) {
  const j = api.jscodeshift;
  return j(file.source)
    .find(j.JSXAttribute, {
      name: { name: 'variant' },
      value: { value: 'danger' },
    })
    .replaceWith(() =>
      j.jsxAttribute(
        j.jsxIdentifier('variant'),
        j.stringLiteral('destructive')
      )
    )
    .toSource();
}

// Run:
npx jscodeshift -t codemods/2.0.0-rename-danger-variant.js src/

Component Design Review Process

/* New Component Review Checklist */

Token Usage:
  [ ] No hardcoded hex colors — only semantic token utilities
  [ ] No arbitrary spacing values — only theme scale

API Conventions:
  [ ] Variant prop uses established names (primary/secondary/etc)
  [ ] Size prop uses sm/md/lg
  [ ] className forwarding enabled for extension

Accessibility:
  [ ] axe-core in Storybook a11y addon shows 0 violations
  [ ] Focus visible ring present
  [ ] Screen reader announcement verified

Dark Mode:
  [ ] All bg-* utilities have dark: equivalents or use semantic tokens

Team Onboarding to the Design System

/* Onboarding session agenda (60 min) */

10min: Design system philosophy
  — Why we have a system (consistency, speed, accessibility)
  — What it covers and what it does not

20min: Token and config layer
  — Primitive vs semantic tokens
  — How to use bg-primary, text-text-primary
  — Dark mode switching demo

20min: Component library walkthrough
  — Finding the right component in docs
  — Using CVA variants: <Button variant='danger'>
  — Extending with className prop

10min: Contribution process
  — How to propose a new component
  — PR review and acceptance criteria

Measuring Design System Adoption

// scripts/measure-adoption.js
const glob = require('glob');
const fs = require('fs');

const files = glob.sync('apps/**/*.{jsx,tsx}');
let importCount = 0;
let buttonCount = 0;

files.forEach(f => {
  const src = fs.readFileSync(f, 'utf8');
  if (src.includes('@acme/ui')) importCount++;
  if (src.includes('<Button')) buttonCount++;
});

console.log(`Files using @acme/ui: ${importCount} / ${files.length}`);
console.log(`Button component uses: ${buttonCount}`);

Quick Check

Lesson Recap