Skip to content

documentation.md

Latest commit

 

History

History
239 lines (152 loc) · 7.57 KB

documentation.md

File metadata and controls

239 lines (152 loc) · 7.57 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

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

  2. Don't: Anti-pattern example

    <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 when used within a Form.

Suggested Improvements

  • Improvement 1: Description of potential enhancement
  • Improvement 2: Description of potential enhancement
  • Improvement 3: Description of potential enhancement

Related Components


## 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`, `validationState`, `autoFocus`, `tooltip`, `description`, `rules`, etc.) — they are documented on the Field Properties page.

### Form Integration

For input components: "This component supports all [Field properties](/docs/getting-started-field-properties--docs) 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
- [ ] Suggested improvements section
- [ ] 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:



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