Skip to content

documentation.md

Latest commit

 

History

History
239 lines (148 loc) · 7.66 KB

documentation.md

File metadata and controls

239 lines (148 loc) · 7.66 KB
Raw

Component Documentation Guidelines

Key Principles

  1. Accessibility First: Document React Aria features and keyboard/screen reader support
  2. Style System: Document tasty styling capabilities (sub-elements, modifiers, style props)
  3. Code Examples Required: CRITICAL - Stories alone are NOT code examples. Always include actual JSX code snippets showing usage.
  4. Clear Structure: Follow the prescribed structure below

Documentation Structure

import { Meta, Canvas, Story } from '@storybook/addon-docs/blocks';
import { ComponentName } from './ComponentName';
import * as ComponentStories from './ComponentName.stories';

<Meta of={ComponentStories} />

# ComponentName

Brief description of what the component is and its primary purpose.

## When to Use

- Scenario 1 where this component is appropriate
- Scenario 2 where this component is appropriate
- Scenario 3 where this component is appropriate

## Component

<Story of={ComponentStories.Default} />

---

### Properties

- **`propName`** `type` (default: `value`) — Description of the property
- **`anotherProp`** `boolean` (default: `false`) — Description of the property

### Base Properties

Supports [Base properties](/docs/getting-started-base-properties--docs)

### Field Properties

[For input components only]

Supports all [Field properties](/docs/getting-started-field-properties--docs)

### Styling Properties

#### styles

Customizes the root element of the component.

**Sub-elements:**
- `ElementName` - Description of what this element represents

#### [additionalStyles] (if applicable)

Customizes the [specific part] of the component.

**Sub-elements:**
- `SubElementName` - Description of what this sub-element represents

### Style Properties

These properties allow direct style application without using the `styles` prop:

- **Base:** `display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, `transition`
- **Dimension:** `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`

### Modifiers

The `mods` property accepts the following modifiers you can override:

| Modifier | Type | Description |
|----------|------|-------------|
| modifierName | `boolean` | Description of what this modifier does |

## Variants

### Types

- `primary` - Description of primary type
- `secondary` - Description of secondary type

### Themes

- `default` - Standard appearance
- `danger` - Used for destructive actions

### Sizes

- `small` - Compact size for dense interfaces
- `medium` - Default size
- `large` - Emphasized size for important actions

## Examples

**IMPORTANT: Stories are for interactive demos. You MUST also provide JSX code snippets in this section.**

### Basic Usage

```jsx
<ComponentName arg="something" />
```

### [Additional Examples as needed]

**Each example must show actual code, not just reference a story.**

## Accessibility

### Keyboard Navigation

- `Tab` - Moves focus to the component
- `Space/Enter` - Activates the component
- [Additional keyboard shortcuts]

### Screen Reader Support

- Component announces as "[role]" to screen readers
- State changes are announced (e.g., "pressed", "expanded")
- [Additional screen reader considerations]

### ARIA Properties

- `aria-label` - Provides accessible label when no visible label exists
- [Additional ARIA properties]

## Best Practices

1. **Do**: Best practice example

   ```jsx
   <ComponentName label="Clear Label">Content</ComponentName>
   ```

2. **Don't**: Anti-pattern example

   ```jsx
   <ComponentName>Unclear usage</ComponentName>
   ```

3. **Accessibility**: Always provide meaningful labels
4. **Performance**: Consider performance implications for specific use cases

## Integration with Forms

[For input components only] This component supports all [Field properties](/docs/getting-started-field-properties--docs) when used within a Form.

## Related Components

- [RelatedComponent1](/components/RelatedComponent1) - When to use instead
- [RelatedComponent2](/components/RelatedComponent2) - Complementary component

Include sections that describe the component's actual contract. Omit inapplicable variants, form integration and speculative improvement lists; document a current limitation only when it affects usage.

Guidelines

Properties

  • Props List: List all component-specific properties using the definition list format. Properties, types, defaults, and descriptions must match the argTypes defined in the corresponding .stories.tsx file. Format: - **`propName`** `type` (default: `value`) — Description
  • Base Properties: Link to /docs/getting-started-base-properties--docs instead of listing (unless qa has special behavior)
  • Styling Properties: Document styles/*Styles props. List sub-elements that can be overridden (check component's tasty styles)
  • Style Properties: Managed by pnpm audit-docs --fix-docs. Groups props by category (Base, Position, Dimension, Block, Color, Text, Flow, Other). Do not edit manually.
  • React Aria Properties: Document any React Aria properties that need extra clarification

Examples

  • CRITICAL: Must include JSX code snippets, not just story references
  • Provide real-world examples with clear purpose
  • Avoid pure styling examples unless demonstrating essential capabilities
  • More sophisticated components need more examples to cover all cases

Modifiers

  • Document all mods property values
  • Explain effects on appearance/behavior
  • Note special modifier combinations

Accessibility

  • Keyboard navigation patterns
  • Screen reader behavior
  • Relevant ARIA properties
  • Accessible implementation guidance

Field Properties

For input components: Add Supports all [Field properties](/docs/getting-started-field-properties--docs) in the Properties section, right after Base Properties. Do NOT duplicate field-level props (label, name, isRequired, isDisabled, isReadOnly, isLoading, isInvalid, isValid, autoFocus, labelTooltip, description, rules, etc.) — they are documented on the Field Properties page.

Form Integration

For input components: "This component supports all Field properties when used within a Form."

File Naming

ComponentName.tsx → ComponentName.docs.mdx in same directory

Review Checklist

  • JSX code snippets provided (not just stories)
  • All component-specific properties explicitly listed
  • Follows prescribed structure
  • Styling properties and sub-elements documented
  • Modifiers listed with descriptions
  • Accessibility section complete
  • Best practices included
  • Only relevant sections included; limitations describe current behavior
  • Style props vs styling props separated
  • Form integration noted (input components)
  • Base properties linked, not listed (except qa)
  • Icons from @tabler/icons-react or /src/icons

Updating Existing Documentation

When updating {ComponentName}.docs.mdx, also look at:

  • Implementation — {ComponentName}.tsx
  • Tests — {ComponentName}.test.tsx
  • Storybook — {ComponentName}.stories.tsx

Align the documentation with the current implementation. Look for use cases in Storybook and code examples in tests.

Don't include ALL stories in the documentation — only those that make sense to document. Some stories exist only to test visuals or basic interactions. Virtualization is a key performance feature, but since it is enabled by default it shouldn't appear as a documented story.

Use story links in the following format:


- [FilterListBox](/docs/forms-filterlistbox--docs)

Where /docs/ is the standard prefix, forms is the section, filterlistbox is the lower-cased component name, and --docs is the standard suffix.