文档编写与团队交接
为每个组件编写包含使用示例、属性表和无障碍说明的文档，然后将设计系统发布为 npm 软件包供团队使用。
文档编写与团队交接 是 CoddyKit 上的免费 Tailwind CSS Academy 课时。 这是第 4 节课，共 4 节。 你可以在下方免费阅读本课时的完整内容 — 然后在浏览器中使用内置代码编辑器和全天候 AI 导师进行实践。 这是 Tailwind CSS Academy 学习路径的一部分，你的进度在网页和 CoddyKit 应用中同步。 Tailwind CSS Academy 课程共包含 4 节课。
本课时的部分内容尚未翻译，以英文显示。
Why Documentation Is a First-Class Concern
A design system without documentation is just a collection of files that only its authors understand. Documentation transforms the system into a product that other teams can adopt independently. Good docs reduce the support burden on the design system team, accelerate onboarding for new engineers, and prevent misuse of components that leads to inconsistency across products.
Component Usage Documentation
Each component needs a usage page that covers: when to use the component, live examples of every variant, a props table with name, type, default, and description, and accessibility notes. The live examples can be pulled directly from Storybook stories, ensuring documentation and implementation stay synchronized without duplicating code.
/* 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
Configure Storybook with the Docs addon to auto-generate a documentation page for each component from JSDoc comments and story metadata. The autodocs tag on a story's meta object enables this. Add JSDoc to your component props interface and the Docs addon extracts them into a readable props table — no separate documentation file needed for the props section.
// 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
Document design tokens with a visual reference page that renders every color, spacing, typography, and shadow token. Show the token name, its CSS variable, the resolved primitive value, and a visual swatch. This page is the single source of truth that designers and engineers both use when checking whether a token exists before adding a new one.
/* 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
The Getting Started guide walks a developer from zero to their first rendered component in under five minutes. It covers: installing the package, importing the Tailwind preset into their app config, importing the global CSS, and rendering a Button to confirm the setup works. Keep it minimal — save advanced usage for dedicated component pages.
# 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
Every release of the design system should have a changelog entry in CHANGELOG.md following the Keep a Changelog format. Group changes under: Added, Changed, Deprecated, Removed, Fixed. Use a tool like changesets or conventional-commits to automate changelog generation from commit messages, reducing manual documentation work.
# 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 SafariPublishing as an npm Package
Publish the design system as a private npm package for team consumption. Configure the package.json exports field to expose the component bundle, types, and styles separately. Use tsup or Rollup to bundle the TypeScript source into ESM and CJS formats. Include a types field pointing to the .d.ts declaration files.
// 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
For breaking changes, provide a codemod that automatically migrates consumer code. Tools like jscodeshift can rename props, swap component names, or rewrite import paths across a codebase with a single command. A codemod transforms the upgrade from a manual, error-prone search-and-replace into a confident, automated operation — dramatically increasing upgrade adoption rates.
// 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
Before publishing a new component, run it through a formal design review. The review checklist includes: tokens (does it use semantic tokens, not primitive or hardcoded values?), variants (does the API match the established naming conventions?), accessibility (does it pass axe-core with zero violations?), responsive (does it render correctly at all breakpoints?), and dark mode (do all surfaces have dark variants?).
/* 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 tokensTeam Onboarding to the Design System
Schedule a design system onboarding session for new developers and run it for existing developers whenever a major version ships. Walk through the component documentation site, demonstrate the token system and how dark mode works, show how to look up the correct component before building a custom one, and explain the contribution process for proposing new components or reporting bugs.
/* 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 criteriaMeasuring Design System Adoption
Track adoption metrics to understand how widely the design system is used and where engineers still rely on ad-hoc styles. Run a script that counts component imports per repository and flags files with high rates of custom Tailwind combinations that could be replaced by design system components. Adoption dashboards motivate improvement and justify investment in new components.
// 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
Test your understanding of Tailwind CSS Mastery concepts from this lesson.
Lesson Recap
In this lesson you learned: using Storybook's autodocs tag to generate living documentation from JSDoc and stories, publishing the design system as an npm package with proper exports and type declarations, and providing codemods and onboarding to support teams upgrading and adopting the system. Congratulations — you have completed the full Tailwind CSS Mastery track!
常见问题解答
「文档编写与团队交接」课时是免费的吗？
是的 — 「文档编写与团队交接」的完整文本可在网页上免费阅读。要进行交互式练习（内置代码编辑器和全天候 AI 导师）并解锁 Tailwind CSS Academy 课程的其余内容，请升级到 CoddyKit PRO。 Tailwind CSS Academy 课程共包含 4 节课。
「文档编写与团队交接」这节课中我会学到什么？
为每个组件编写包含使用示例、属性表和无障碍说明的文档，然后将设计系统发布为 npm 软件包供团队使用。 你通过在浏览器中直接运行的动手代码来练习 Tailwind CSS Academy，全天候 AI 导师会在你学习这节课的过程中回答你的问题。
学习 Tailwind CSS Academy 需要有经验吗？
无需任何先前经验。CoddyKit 上的 Tailwind CSS Academy 课程适合初学者到高级学习者，你可以从这里开始或从头开始，按照自己的节奏学习。 这是第 4 节课，共 4 节。
「文档编写与团队交接」课时需要多长时间？
大多数 CoddyKit 课程大约需要 5–10 分钟。每节课都很精短且互动，所以你能稳步进步，并在网页和应用中从离开的地方继续。
我能在这节 Tailwind CSS Academy 课中编写并运行代码吗？
能。每节 Tailwind CSS Academy 课都包含内置代码编辑器，你可以在浏览器中直接编写并运行真实代码，并获得即时 AI 反馈 — 无需本地设置。