feat(Components): improve documentation (AI enabled)

[joelharkes]

Todo

• Check with Joanna on the resulting quality.

Context

I upgraded the documentation with help of claude:

Steps taken

1. First extracted documentation from: https://fondue.frontify.com/document/50#/-/fondue-components to storybook
2. I let AI as a copy writer iterate of the storybook documentation and migrate stuff to Props JSDoc
3. Then I let AI define consistent rules to add as a Claude command. (see first file checked in)
4. I let AI extract a report (copied below)
5. Then I Claude fill in the blanks based on this report and make documentation more consistent.

Component Documentation Audit Report

Audit date: 2026-02-14 | Scope: packages/components/src/components/ (35 components)

---

Executive Summary

The Fondue component library has strong documentation in its best components (Button, Notice, Badge, Accordion, Checkbox) that could serve as the gold standard for the rest. However, there is significant inconsistency across the library — roughly a third of components have excellent prop-level JSDoc, a third have partial coverage, and a third are barely documented. Storybook descriptions follow a similar pattern: only ~6 of 30 story files include a component-level description.

Overall documentation health: 6/10 — good bones, inconsistent execution.

---

Part 1: Storybook Documentation Audit

1.1 Coverage

• 30 of 35 components have Storybook stories (86%)
• All stories use tags: ['autodocs'] and parameters.status
• Only 6 stories include a docs.description.component block

1.2 Component Descriptions — Who Has Them

Has description	Missing description
Accordion, Button, Checkbox, Notice, Badge (brief), Dialog (minimal)	Box, Flex, Grid, Divider, Dropdown, Flyout, Label, Link, RadioList, ScrollArea, SegmentedControl, Select, Slider, Switch, Tabs, Tag, Text, Textarea, TextInput, Tooltip, ColorPicker, Table, SplitButton

1.3 What Good Descriptions Look Like

The best descriptions (Accordion, Button, Checkbox) follow a clear template:

Line 1: What it is (one sentence, starts with "A…" or "An…")
Line 2: (blank)
Line 3: **When to use:** Guidance on the right context
Line 4: (blank)
Line 5+: **Feature label:** Specific guidance on key features

Example (Button):

An interactive element that triggers actions — from submitting a form to opening a menu. At least one content element must be included: a label, an icon, or both.

When to use: For actions and commands only. Use links for navigation — buttons trigger an immediate result, links navigate to a new location.

Icon: Pass an icon as a child to add visual context. Use aspect="square" for icon-only buttons.

1.4 argTypes Usage

Only 5 of 30 stories define argTypes with descriptions:

• Slider (9 argTypes — best example, includes table metadata)
• Link (8 argTypes)
• Table (layout and gutter)
• RadioList (3 argTypes)
• Switch (size control only)

Finding: Most components rely on autodocs to pull descriptions from JSDoc. This works well when JSDoc exists, but leaves the controls table blank for undocumented props.

1.5 Story Variant Coverage

Most components have decent variant coverage through named stories. Notable patterns:

Coverage level	Components
Excellent (10+ stories)	Notice, Dialog, Dropdown, Flyout, Select, ScrollArea, Tag, Badge
Good (5–9 stories)	Accordion, Button, Checkbox, Switch, SegmentedControl, Label, Slider, Tabs
Minimal (1–4 stories)	Box, Divider, Grid, Link, Text, Tooltip, ColorPicker

1.6 Anti-patterns Found

1. No JSDoc on individual stories — No story uses parameters.docs.description.story to explain why a variant exists
2. Lorem Ipsum overuse — ScrollArea stories are 90% Lorem Ipsum with no meaningful content showing realistic usage
3. No args defaults in most stories — Only Button and Accordion set sensible args defaults in meta
4. Missing subcomponents declarations — Some compound components don't list their sub-components in meta

---

Part 2: JSDoc / Prop Documentation Audit

2.1 Tier System

Tier 1 — Excellent (100% or near-complete prop documentation)

Component	Props documented	Coverage	Notes
Button	12/15	80%	Gold standard for descriptions; missing form, children, className
Notice	10/10	100%	Every prop has a clear, contextual description
Badge	7/8	88%	Clear variant explanations
Accordion	Sub-components well documented	~90%	Good @deprecated usage
Checkbox	Comprehensive	~90%	Includes accessibility notes
Link	All props	100%	Concise and clear
Label	All props	100%	—
Divider	All props	100%	Good a11y doc for decorative
LoadingCircle	All props	100%	—

Tier 2 — Partial (key props documented, gaps in secondary props)

Component	Coverage	Key gaps
Dialog	~85%	Sub-components well documented, some children props missing
Flyout	~80%	Good FlyoutContent docs, sparse on Header/Footer
Dropdown	~80%	Some brief/generic descriptions
TextInput	~75%	Missing id, name, className
Textarea	~75%	Good @deprecated on extraActions
Switch	~65%	Wrong terminology (says "select" instead of "switch")
Slider	~70%	Missing onChange vs onCommit explanation
Select	~60%	Insufficient for such a complex component
Tabs	~70%	Typo in variant description

Tier 3 — Poor (minimal or no prop documentation)

Component	Coverage	Notes
Heading	0%	Zero JSDoc on any prop — worst in the library
Text	~55%	Has some docs but inconsistent with Heading
Box	~50%	Only as and display documented; inherited layout props undocumented
Flex	~30%	Layout-specific props (direction, align, justify) undocumented
Grid	~30%	Same as Flex
Section	~20%	—
ScrollArea	~40%	—
SegmentedControl	~50%	—

2.2 Terminology Bugs

Component	Prop	Issue
Switch	value	Says "The active value in the select component" — should say "switch"
Switch	defaultValue	Says "The default value of the select component" — should say "switch"
Switch	disabled	Says "Disables the select component" — should say "switch"
Switch	onBlur / onFocus	Says "called when the checkbox is blurred/focused" — should say "switch"
Tabs	variant	Malformed JSDoc: "default 'default'" (missing @ prefix)

2.3 Description Style Inconsistencies

Problem: Two different documentation voices exist

Voice A — Contextual/designer-friendly (Button, Notice, Badge):

Controls visual weight. 'strong' for primary actions, 'default' for common actions, 'weak' for secondary or less prominent options.

Voice B — Mechanical/developer-only (Slider, TextInput, Switch):

The default value of the slider, used for uncontrolled components.

Voice A explains when and why to use each option. Voice B just restates the type. Voice A should be the standard.

2.4 Default Value Documentation

Good news: @default tags are used consistently when JSDoc exists. The pattern is well-established.

Issue: Some defaults are quoted (@default "button") and others are not (@default medium). Minor but inconsistent.

2.5 Missing Patterns

1. No @example tags anywhere — Would help with complex props
2. No top-level JSDoc on compound component exports — export const Dialog = { Root, Trigger, ... } has no doc comment explaining the composition pattern
3. children props rarely documented — When children must be specific components (e.g., Accordion.Item inside Accordion.Root), this constraint isn't noted
4. Inherited prop types undocumented — LayoutComponentProps, CommonAriaProps, CommonAriaAttrs are used widely but their individual props aren't documented at the usage site

---

Part 3: Cross-cutting Issues

3.1 Storybook ↔ JSDoc Misalignment

For autodocs to work well, JSDoc must be complete. When it's not, the Storybook controls table shows props without descriptions. This is the case for:

• All Tier 3 components
• Inherited props from LayoutComponentProps (affects Box, Flex, Grid, Section)
• CommonAriaProps and CommonAriaAttrs spread props

3.2 Component Selection Guide (AI.md) vs Storybook

The AI.md component selection guide is excellent and comprehensive. But Storybook descriptions — the developer-facing docs — don't include "when to use" guidance for most components. Developers using Storybook directly miss the decision-making context that exists in AI.md.

3.3 Priority Fix List (Quick Wins)

1. Fix Switch terminology — 5 JSDoc strings reference the wrong component name
2. Fix Tabs variant JSDoc — Malformed comment
3. Add JSDoc to Heading — Zero documentation on a fundamental component
4. Add Storybook descriptions to form components — TextInput, Textarea, Select, RadioList, Switch
5. Add Storybook descriptions to layout components — Box, Flex, Grid
6. Document LayoutComponentProps — One fix helps Box, Flex, Grid, and Section

---

Part 4: Component-by-Component Scoreboard

Component	JSDoc coverage	Storybook desc	Story count	Overall
Accordion	A	A	9	A
Badge	A	B	13	A-
Box	D	F	2	D
Button	A	A	6	A
Checkbox	A	A	8	A
ColorPicker	C	F	5	C-
Dialog	B+	D	19	B
Divider	A	F	5	B-
Dropdown	B	F	18	B-
Flex	D	F	5	D
Flyout	B	F	22	B-
Grid	D	F	3	D
Heading	F	—	—	F
Label	A	F	8	B-
Link	A	F	3	B
LoadingBar	B	—	—	C
LoadingCircle	A	—	—	B
Notice	A	A	15	A+
RadioList	C	F	6	C
ScrollArea	D	F	10	C-
Section	D	—	—	D
SegmentedControl	C	F	7	C
Select	C	F	25	C
Slider	B	F	9	B-
SplitButton	C	F	—	C-
Switch	C*	F	8	C-
Table	C	F	—	C
Tabs	C	F	3	C
Tag	C	F	14	C
Text	C	F	—	C-
Textarea	B	F	5	B-
TextInput	B	F	5	B-
Tooltip	B	F	5	B
ThemeProvider	C	—	—	C
RouterProvider	D	—	—	D

Switch: C with a critical terminology bug — see Part 2.2

---

Part 5: Recommendations Summary

Must Fix (Bugs)

1. Switch: Replace all "select component" / "checkbox" references with "switch"
2. Tabs: Fix malformed @default comment on variant

High Priority (Gap-closing)

3. Add JSDoc to Heading — match Text component's style
4. Add Storybook docs.description.component to all 24 missing components
5. Document LayoutComponentProps shared props (benefits 4 components)
6. Add JSDoc to Flex and Grid specific layout props

Medium Priority (Consistency)

7. Standardize on "Voice A" (contextual, designer-friendly) for all prop descriptions
8. Add top-level JSDoc comment to all compound component exports
9. Document children constraints where they exist
10. Quote all @default values consistently: @default "medium" not @default medium

Nice to Have

11. Add @example tags for complex props
12. Add parameters.docs.description.story to story variants that aren't self-explanatory
13. Set args defaults in all story meta blocks

[changeset-bot]

🦋 Changeset detected

Latest commit: 018f3cb

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 3 packages

Name	Type
@frontify/fondue-components	Patch
@frontify/fondue	Patch
@frontify/fondue-rte	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[github-actions]

PR Preview Action v1.6.2
🚀 View preview at https://Frontify.github.io/fondue/pr-preview/pr-2627/
Built to branch gh-pages at 2026-02-19 15:03 UTC. Preview will be ready when the GitHub Pages deployment is complete.