Initial commit

2025-11-29 18:02:45 +08:00
commit 31e7ee93ec
15 changed files with 7495 additions and 0 deletions
--- a/skills/documentation/SKILL.md
+++ b/skills/documentation/SKILL.md
@@ -0,0 +1,557 @@
+---
+name: documentation
+description: Generate comprehensive feature documentation including Storybook stories, JSDoc comments, and feature guides. Use after completing a feature (may span multiple commits). Creates documentation for humans and AI to understand features, usage patterns, and design decisions.
+---
+
+# Documentation (TypeScript + React)
+
+Generate comprehensive documentation for features, components, and hooks.
+
+## When to Use
+- After completing a feature (may span multiple commits)
+- When a component/hook needs usage documentation
+- When design decisions need recording
+- For public/shared components and hooks
+
+## Documentation Types
+
+### 1. Storybook Stories (Component Documentation)
+**Purpose**: Visual documentation of component usage and variants
+
+**Creates**: `.stories.tsx` files alongside components
+
+### 2. JSDoc Comments (Code Documentation)
+**Purpose**: Inline documentation for types, props, complex functions
+
+**Location**: In source files (`.ts`, `.tsx`)
+
+### 3. Feature Documentation (Architectural Documentation)
+**Purpose**: WHY decisions were made, HOW feature works, WHAT to extend
+
+**Creates**: `docs/features/[feature-name].md`
+
+## Workflow
+
+### 1. Identify Documentation Needs
+
+Ask:
+- Is this a reusable component? → Storybook story
+- Is this a custom hook? → JSDoc + usage example
+- Is this a complete feature? → Feature documentation
+- Are types/props complex? → JSDoc comments
+
+### 2. Create Storybook Stories
+
+**For each component**, create stories showing:
+- Default state
+- All variants/props
+- Interactive states
+- Edge cases (loading, error, empty)
+
+**Example**:
+```typescript
+// src/components/Button/Button.stories.tsx
+import type { Meta, StoryObj } from '@storybook/react'
+import { Button } from './Button'
+
+const meta: Meta<typeof Button> = {
+  title: 'Components/Button',
+  component: Button,
+  parameters: {
+    layout: 'centered'
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['primary', 'secondary', 'danger']
+    }
+  }
+}
+
+export default meta
+type Story = StoryObj<typeof Button>
+
+// Default story
+export const Primary: Story = {
+  args: {
+    label: 'Button',
+    variant: 'primary',
+    onClick: () => alert('clicked')
+  }
+}
+
+// Variants
+export const Secondary: Story = {
+  args: {
+    ...Primary.args,
+    variant: 'secondary'
+  }
+}
+
+export const Danger: Story = {
+  args: {
+    ...Primary.args,
+    variant: 'danger'
+  }
+}
+
+// States
+export const Disabled: Story = {
+  args: {
+    ...Primary.args,
+    isDisabled: true
+  }
+}
+
+export const Loading: Story = {
+  args: {
+    ...Primary.args,
+    isLoading: true
+  }
+}
+
+// Interactive example
+export const WithIcon: Story = {
+  args: {
+    ...Primary.args,
+    icon: <IconCheck />
+  }
+}
+```
+
+### 3. Add JSDoc Comments
+
+**For public types and interfaces**:
+```typescript
+/**
+ * Props for the Button component.
+ *
+ * @example
+ * ```tsx
+ * <Button
+ *   label="Click me"
+ *   variant="primary"
+ *   onClick={() => console.log('clicked')}
+ * />
+ * ```
+ */
+export interface ButtonProps {
+  /** The text to display on the button */
+  label: string
+
+  /** The visual style variant of the button */
+  variant?: 'primary' | 'secondary' | 'danger'
+
+  /** Callback fired when the button is clicked */
+  onClick: () => void
+
+  /** If true, the button will be disabled */
+  isDisabled?: boolean
+
+  /** If true, the button will show a loading spinner */
+  isLoading?: boolean
+}
+```
+
+**For custom hooks**:
+```typescript
+/**
+ * Custom hook for managing user authentication state.
+ *
+ * Handles login, logout, and persisting auth state to localStorage.
+ * Automatically refreshes token when it expires.
+ *
+ * @param options - Configuration options for authentication
+ * @returns Authentication state and methods
+ *
+ * @example
+ * ```tsx
+ * function LoginForm() {
+ *   const { login, isLoading, error } = useAuth()
+ *
+ *   const handleSubmit = async (email: string, password: string) => {
+ *     await login(email, password)
+ *   }
+ *
+ *   return <Form onSubmit={handleSubmit} isLoading={isLoading} error={error} />
+ * }
+ * ```
+ */
+export function useAuth(options?: AuthOptions): UseAuthReturn {
+  // Implementation
+}
+```
+
+**For complex types**:
+```typescript
+/**
+ * Represents the state of an asynchronous operation.
+ *
+ * Uses discriminated union to ensure invalid states are impossible
+ * (e.g., cannot have both data and error simultaneously).
+ *
+ * @template T - The type of data returned on success
+ *
+ * @example
+ * ```typescript
+ * const [state, setState] = useState<AsyncState<User>>({ status: 'idle' })
+ *
+ * // Type narrowing works automatically
+ * if (state.status === 'success') {
+ *   console.log(state.data.name) // state.data is available and typed
+ * }
+ * ```
+ */
+export type AsyncState<T> =
+  | { status: 'idle' }
+  | { status: 'loading' }
+  | { status: 'success'; data: T }
+  | { status: 'error'; error: Error }
+```
+
+### 4. Create Feature Documentation
+
+**For completed features**, create `docs/features/[feature-name].md`:
+
+**Template**:
+```markdown
+# Feature: [Feature Name]
+
+## Overview
+Brief description of what the feature does and why it exists.
+
+## Problem
+What problem does this feature solve? What was the pain point?
+
+## Solution
+How does this feature solve the problem? What approach was taken?
+
+## Architecture
+
+### Components
+- **ComponentName**: Purpose and responsibility
+- **AnotherComponent**: Purpose and responsibility
+
+### Hooks
+- **useFeatureHook**: What it does and why it's separate
+
+### Context
+- **FeatureContext**: What state it manages and why context was needed
+
+### Types
+- **KeyType**: What it represents and why it's a custom type
+
+## Key Design Decisions
+
+### 1. [Decision Title]
+**Decision**: What was decided
+**Rationale**: Why this approach was chosen
+**Alternatives**: What other approaches were considered
+**Trade-offs**: What we gained and what we gave up
+
+### 2. [Another Decision]
+...
+
+## Usage
+
+### Basic Usage
+```typescript
+// Simple example showing most common use case
+```
+
+### Advanced Usage
+```typescript
+// Example showing advanced features or edge cases
+```
+
+### Integration
+How this feature integrates with other parts of the application.
+
+## API Reference
+
+### Components
+
+#### ComponentName
+Props:
+- `propName` (Type): Description
+
+Events:
+- `onEvent`: When it fires and what it provides
+
+#### AnotherComponent
+...
+
+### Hooks
+
+#### useFeatureHook
+Parameters:
+- `param` (Type): Description
+
+Returns:
+- `returnValue` (Type): Description
+
+### Types
+
+#### TypeName
+```typescript
+type TypeName = ...
+```
+
+Description of when and how to use this type.
+
+## Testing Strategy
+
+### Unit Tests
+- What is tested at the unit level (pure components, hooks)
+- Coverage expectations (100% for leaf components)
+
+### Integration Tests
+- What user flows are tested
+- How mocking is handled (MSW for APIs)
+
+## Accessibility
+
+### Compliance
+- WCAG level compliance (A, AA, AAA)
+- What accessibility features are implemented
+
+### Keyboard Navigation
+- What keyboard shortcuts are supported
+- How tab order works
+
+### Screen Reader Support
+- What ARIA attributes are used
+- What announcements are made
+
+## Performance Considerations
+
+### Optimizations
+- What performance optimizations are implemented
+- Use of memo, useMemo, useCallback
+
+### Bundle Impact
+- Approximate bundle size contribution
+- Any lazy loading or code splitting
+
+## Known Limitations
+
+### Current Limitations
+- What doesn't work yet
+- What edge cases aren't handled
+
+### Future Enhancements
+- What could be improved
+- What features could be added
+
+## Troubleshooting
+
+### Common Issues
+
+#### Issue: [Problem Description]
+**Symptom**: What users will see
+**Cause**: Why this happens
+**Solution**: How to fix it
+
+## Related Features
+- Links to related documentation
+- Dependencies on other features
+- Features that depend on this
+
+## Migration Guide
+(If replacing existing functionality)
+
+### Before
+```typescript
+// Old way
+```
+
+### After
+```typescript
+// New way
+```
+
+### Breaking Changes
+- What changed
+- How to update code
+
+## Changelog
+- v1.1.0 (2024-01-15): Added support for...
+- v1.0.0 (2024-01-01): Initial implementation
+```
+
+## Output Format
+
+After generating documentation:
+
+```
+📚 DOCUMENTATION GENERATED
+
+Feature: User Authentication
+
+Generated Files:
+✅ Storybook Stories (3 components)
+   - src/features/auth/components/LoginForm.stories.tsx
+   - src/features/auth/components/RegisterForm.stories.tsx
+   - src/features/auth/components/PasswordInput.stories.tsx
+
+✅ JSDoc Comments Added
+   - src/features/auth/hooks/useAuth.ts (hook documentation)
+   - src/features/auth/types.ts (type definitions)
+   - src/features/auth/context/AuthContext.tsx (context API)
+
+✅ Feature Documentation
+   - docs/features/authentication.md (complete guide)
+
+📖 Documentation includes:
+   - Problem/solution overview
+   - Architecture and design decisions
+   - Usage examples (basic + advanced)
+   - API reference (components, hooks, types)
+   - Testing strategy
+   - Accessibility features
+   - Performance considerations
+   - Troubleshooting guide
+
+🎯 Next Steps:
+1. Review generated Storybook stories locally: npm run storybook
+2. Review feature documentation: docs/features/authentication.md
+3. Update any project-specific references or links
+4. Commit documentation with feature code
+
+📝 Maintenance:
+- Update Storybook stories when component props change
+- Update JSDoc when APIs change
+- Update feature docs when design decisions change
+- Keep examples working (they're testable!)
+```
+
+## Documentation Principles
+
+### For Humans AND AI
+
+Documentation serves two audiences:
+1. **Human developers**: Need to understand and extend code
+2. **AI assistants**: Need context to help debug and extend features
+
+Write documentation that helps both audiences understand:
+- **WHY** decisions were made (context for future changes)
+- **HOW** the feature works (architecture and flow)
+- **WHAT** can be extended (integration points)
+
+### Show, Don't Tell
+
+Prefer code examples over prose descriptions:
+
+**❌ Bad**:
+```
+The Button component accepts a variant prop that can be primary,
+secondary, or danger, and will style the button accordingly.
+```
+
+**✅ Good**:
+```typescript
+<Button variant="primary" label="Save" />
+<Button variant="secondary" label="Cancel" />
+<Button variant="danger" label="Delete" />
+```
+
+### Keep Examples Executable
+
+Storybook stories and JSDoc examples should be real, working code that compiles and runs.
+
+### Document Design Decisions
+
+Most important: **WHY** decisions were made.
+
+**❌ Bad**:
+```
+// Uses context for state management
+```
+
+**✅ Good**:
+```
+/**
+ * Uses AuthContext for state management instead of prop drilling.
+ *
+ * Decision: Context chosen because auth state is needed in 10+
+ * components across different nesting levels (nav, profile, settings,
+ * protected routes). Prop drilling would be unmaintainable.
+ *
+ * Alternative considered: Redux - overkill for single feature state
+ */
+```
+
+## When to Document
+
+### Always Document
+- Public/shared components
+- Custom hooks (except trivial ones)
+- Complex types (discriminated unions, branded types)
+- Completed features (spanning multiple commits)
+
+### Consider Documenting
+- Complex utility functions
+- Non-obvious algorithms
+- Performance-critical code
+- Edge cases and workarounds
+
+### Don't Over-Document
+- Trivial functions (self-explanatory)
+- Implementation details (private functions)
+- Obvious code (const user = getUser())
+
+## Best Practices
+
+### Storybook
+- One story file per component
+- Show all variants
+- Include interactive controls
+- Document props with argTypes
+- Add accessibility checks (a11y addon)
+
+### JSDoc
+- Use `@param`, `@returns`, `@example` tags
+- Include examples showing typical usage
+- Document complex types inline
+- Link related types with `@see`
+
+### Feature Docs
+- Start with problem/solution
+- Include architecture diagrams (mermaid)
+- Provide working code examples
+- Document WHY, not just WHAT
+- Keep updated as feature evolves
+
+## Tools
+
+### Storybook Commands
+```bash
+# Run Storybook locally
+npm run storybook
+
+# Build static Storybook
+npm run build-storybook
+
+# Test stories (interaction testing)
+npm run test-storybook
+```
+
+### TypeDoc (Alternative to JSDoc)
+```bash
+# Generate API documentation from TypeScript
+npx typedoc --entryPoints src/index.ts
+```
+
+## Key Principles
+
+See reference.md for detailed principles:
+- Document WHY, not just WHAT
+- Show working code examples
+- Keep docs close to code
+- Update docs with code changes
+- Test examples (Storybook)
+- Document for humans AND AI
+- Focus on usage, not implementation
+
+See reference.md for complete documentation templates and examples.