feat(docs): add f0-docs skill for MDX documentation workflow#3893
feat(docs): add f0-docs skill for MDX documentation workflow#3893desiree-np wants to merge 11 commits intomainfrom
Conversation
Adds a new skill covering the full 4-step workflow for documenting F0 components in Storybook: source analysis, creator questions, quality target, and MDX authoring. Includes component-analysis, documentation- quality, and mdx-authoring references with templates, table templates, DoDonts patterns (text, guidelines, and visual children), and a validation checklist.
✅ No New Circular DependenciesNo new circular dependencies detected. Current count: 0 |
📦 Alpha Package Version PublishedUse Use |
🔍 Visual review for your branch is published 🔍Here are the links to: |
Coverage Report for packages/react
File CoverageNo changed files found. |
There was a problem hiding this comment.
Pull request overview
Adds a new f0-docs agent skill under packages/react/.skills/ to standardize how F0 React components are documented in Storybook using manual MDX, including analysis guidance, quality criteria, authoring templates, and a component docs status tracker.
Changes:
- Introduces the
f0-docsskill entrypoint defining a mandatory 4-step documentation workflow. - Adds detailed reference docs for component analysis, documentation quality levels, and MDX authoring patterns/checklists.
- Adds a component documentation status matrix intended to track MDX coverage and quality across
src/components.
Reviewed changes
Copilot reviewed 5 out of 5 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| packages/react/.skills/f0-docs/SKILL.md | Defines when/how to apply the f0-docs workflow and links to references. |
| packages/react/.skills/f0-docs/references/component-analysis.md | Step-by-step protocol for extracting props/stories/WHEN→THEN rules from source. |
| packages/react/.skills/f0-docs/references/documentation-quality.md | Defines Acceptable/Good/Gold criteria and global rules for MDX content. |
| packages/react/.skills/f0-docs/references/mdx-authoring.md | Full MDX templates, table templates, utility component patterns, and validation checklist. |
| packages/react/.skills/f0-docs/references/component-status.md | Tracks which components have MDX docs and their current quality level. |
| ### Phase 3: Update the stories file | ||
|
|
||
| Remove `autodocs` from meta tags and add `"!dev"` to stories used in documentation: | ||
|
|
||
| ```tsx | ||
| // BEFORE | ||
| const meta = { | ||
| title: "ComponentName", | ||
| component: F0ComponentName, | ||
| tags: ["autodocs", "stable"], | ||
| } | ||
| export const Default: Story = { ... } | ||
|
|
||
| // AFTER | ||
| const meta = { | ||
| title: "ComponentName", | ||
| component: F0ComponentName, | ||
| tags: ["stable"], // autodocs removed | ||
| } | ||
| export const Default: Story = { | ||
| tags: ["!dev"], // hidden from sidebar, still usable in Canvas | ||
| ... | ||
| } | ||
| ``` | ||
|
|
||
| **Tag reference:** | ||
|
|
||
| | Tag | Applied to | Effect | | ||
| | -------------- | ----------------------- | ---------------------------------------------------------------------------------------- | | ||
| | `"!dev"` | Story export | Hides story from sidebar in dev mode. Still accessible via `<Canvas>` in MDX. | | ||
| | `"no-sidebar"` | `<Meta>` in an MDX file | Hides the MDX page from the sidebar. Used by legacy stubs — not needed in new MDX files. | | ||
| | `"autodocs"` | Meta in stories file | Auto-generates a docs tab. Remove when adding a manual MDX — they conflict. | | ||
|
|
There was a problem hiding this comment.
The guidance to add tags: ["!dev"] to story exports to hide them from the sidebar doesn’t match the current Storybook config: .storybook/manager.ts only filters no-sidebar and internal, so !dev won’t be consumed anywhere. Also, removing "autodocs" from the story meta won’t opt out of autodocs because .storybook/preview.tsx sets tags: ["autodocs"] globally. Please update this section to use an actually supported mechanism (e.g. no-sidebar filter or a documented opt-out for global autodocs) so the workflow is actionable.
| | Mediocre | Gold | | ||
| | ------------------------------------------------------- | ---------------------------------------------------------------- | --------- | ----------- | | ||
| | Separate anatomy table + separate props reference table | Single table: Prop \| Type \| Default \| Required \| Description | | ||
| | Generic descriptions ("The title prop") | Explains behavior ("Main heading. Sentence case, no period.") | | ||
| | Missing optional props | All public props listed; optional show `—` in Required column | | ||
| | Type column omitted | Full type string in `<code>` — e.g. `"info" | "warning" | "critical"` | | ||
| | No default values | Default column with actual defaults or `—` | | ||
| | Missing `dataTestId` | All props including testing props | |
There was a problem hiding this comment.
The markdown table in this section is malformed (it renders as 4 columns because the separator row includes extra | --------- | ----------- |, and the example type string contains unescaped |). Please fix the table structure (keep it 2 columns) and escape | characters inside inline code so the examples render correctly on GitHub.
| | Mediocre | Gold | | ||
| | ------------------------------------ | -------------------------------------------------------------------------------------------- | ----------- | ----------- | | ||
| | Only lists variant names | 2–3 columns: Variant | Description | When to use | | ||
| | "default — the default variant" | "default — Filled primary button — Primary action on a page or section, one per layout area" | | ||
| | Omits edge variants (neutral, ghost) | All variants documented, including promotional and destructive | | ||
|
|
There was a problem hiding this comment.
This comparison table is also malformed (extra column separators in the header/separator rows cause it to render as more than 2 columns). Please fix the markdown so it’s a valid 2-column table; otherwise the quality criteria are hard to read.
| | Mediocre | Gold | | ||
| | -------------------------------- | ---------------------------------------------------------------- | ----------- | ---------------- | | ||
| | Lists states with no explanation | 3 columns: State | Description | Visual indicator | | ||
| | "Disabled — disabled" | "Disabled — Action unavailable — Reduced opacity, not clickable" | | ||
|
|
There was a problem hiding this comment.
Same issue here: the markdown table is not valid (the separator row includes additional columns). Please correct the table formatting so it renders as the intended 2-column Mediocre vs Gold comparison.
| 6. **English throughout** — no Spanish, no mixed language, no emoji | ||
| 7. **One unified props table** — Prop | Type | Default | Required | Description — never anatomy + props reference as two separate tables | ||
| 8. **No DocsNav** — Storybook has native sidebar navigation; do not import or use `DocsNav` | ||
| 9. **Import once** — `import { F0X } from "@factorialco/f0-react"` appears once as a tsx code block inside the Usage section, never duplicated |
There was a problem hiding this comment.
Global rule #9 (“Import once — import { F0X } from "@factorialco/f0-react" appears once as a tsx code block…”) conflicts with the MDX authoring reference, which correctly states an ImportBanner is injected automatically by .storybook/DocsContainer.tsx. As written, following both docs is impossible (and would reintroduce redundant import blocks). Please reconcile these rules (either remove rule #9 or restate it to reflect the ImportBanner behavior).
| 9. **Import once** — `import { F0X } from "@factorialco/f0-react"` appears once as a tsx code block inside the Usage section, never duplicated | |
| 9. **Do not duplicate the import banner** — `DocsContainer.tsx` injects the `import { F0X } from "@factorialco/f0-react"` banner automatically; do not add a separate import-only tsx code block in MDX |
| Before writing, decide the quality level to target (Acceptable / Good / Gold) based on the component's importance and completeness of available information. Check the gold standards: | ||
|
|
||
| - `F0Alert/__stories__/F0Alert.mdx` — best in class for decision tables, DoDonts, a11y | ||
| - `F0Button/__stories__/F0Button.mdx` — most complete (DocsNav, states, full props reference, 633 lines) | ||
|
|
There was a problem hiding this comment.
The listed “gold standards” (F0Alert/__stories__/F0Alert.mdx, F0Button/__stories__/F0Button.mdx) don’t exist in the current repo state (e.g. F0Alert/__stories__ only has F0Alert.stories.tsx, and F0Button/__stories__ currently has a controls.mdx stub). Also, F0Button.mdx is described as having DocsNav, but this skill later mandates “No DocsNav”. Please update these references to point to files that exist in this repo (or explicitly note they live in a companion PR) and ensure the examples are consistent with the rules.
| Before writing, decide the quality level to target (Acceptable / Good / Gold) based on the component's importance and completeness of available information. Check the gold standards: | |
| - `F0Alert/__stories__/F0Alert.mdx` — best in class for decision tables, DoDonts, a11y | |
| - `F0Button/__stories__/F0Button.mdx` — most complete (DocsNav, states, full props reference, 633 lines) | |
| Before writing, decide the quality level to target (Acceptable / Good / Gold) based on the component's importance and completeness of available information. Check the best in-repo references that exist today: | |
| - `F0Alert/__stories__/F0Alert.stories.tsx` — use as the current source of truth for covered variants, states, and scenarios in this repo | |
| - `F0Button/__stories__/controls.mdx` — existing MDX reference for control wiring only; it is not a full gold-standard content example, and you should not add `DocsNav` | |
| If fuller MDX examples such as `F0Alert.mdx` or `F0Button.mdx` land in a companion PR, treat them as supplemental references only if they still match the rules in this skill. |
| | `F0Alert` | `F0Alert/__stories__/F0Alert.mdx` | **Gold** | Best-in-class reference | | ||
| | `F0AnalyticsDashboard` | None | **None** | | | ||
| | `F0BigNumber` | `F0BigNumber/__stories__/controls.mdx` | **Stub** | Needs full MDX | | ||
| | `F0Box` | None | **None** | | | ||
| | `F0Button` | `F0Button/__stories__/F0Button.mdx` | **Gold** | 633 lines — gold-standard reference | |
There was a problem hiding this comment.
This status table currently claims F0Alert/__stories__/F0Alert.mdx and F0Button/__stories__/F0Button.mdx exist and are “Gold”, but those files are not present in the repo (F0Alert has no MDX; F0Button has controls.mdx). Please correct these entries (or annotate them as pending a companion PR) so the status tracker is reliable.
| | `F0Alert` | `F0Alert/__stories__/F0Alert.mdx` | **Gold** | Best-in-class reference | | |
| | `F0AnalyticsDashboard` | None | **None** | | | |
| | `F0BigNumber` | `F0BigNumber/__stories__/controls.mdx` | **Stub** | Needs full MDX | | |
| | `F0Box` | None | **None** | | | |
| | `F0Button` | `F0Button/__stories__/F0Button.mdx` | **Gold** | 633 lines — gold-standard reference | | |
| | `F0Alert` | None | **None** | No MDX file currently exists | | |
| | `F0AnalyticsDashboard` | None | **None** | | | |
| | `F0BigNumber` | `F0BigNumber/__stories__/controls.mdx` | **Stub** | Needs full MDX | | |
| | `F0Box` | None | **None** | | | |
| | `F0Button` | `F0Button/__stories__/controls.mdx` | **Stub** | Has controls-only MDX; full docs pending | |
|
|
||
| ### Step 4 — Write the MDX and update stories | ||
|
|
||
| Create the MDX file and remove `autodocs` from the stories meta. Follow the full template and validation checklist. |
There was a problem hiding this comment.
“Remove autodocs from the stories meta” is unlikely to achieve the desired effect in this repo because .storybook/preview.tsx sets tags: ["autodocs"] globally for all stories. Please update this step to describe the actual supported way to avoid autodocs conflicts when adding manual MDX in this codebase (and keep it consistent with the storybook-stories skill).
| Create the MDX file and remove `autodocs` from the stories meta. Follow the full template and validation checklist. | |
| Create the MDX file and update the corresponding `*.stories.tsx` file to disable autodocs using this repo's supported story-level override for manual MDX pages (do not rely on removing `autodocs` from the stories meta, because autodocs is enabled globally in this codebase). Follow the full template and validation checklist. |
| | Level | Description | | ||
| | ------------ | ----------------------------------------------------------------------------------------------------------------------- | | ||
| | **Gold** | Full docs: anatomy table (5 cols), variants, when-to-use decision table, DoDonts, a11y keyboard table, 3+ code examples | | ||
| | **Good** | Covers all 4 sections (Overview/Guidelines/Code/Examples) with most required tables | | ||
| | **Adequate** | Covers core information but missing some sections (e.g., no a11y table, no formal prop table) | | ||
| | **Minimal** | Exists but thin — missing guidelines, accessibility, or major sections | | ||
| | **Stub** | Only a 7-line `controls.mdx` — not real documentation | | ||
| | **None** | No MDX file exists | | ||
|
|
||
| --- | ||
|
|
||
| ## Individual Components | ||
|
|
||
| | Component | MDX File | Quality | Notes | | ||
| | ------------------------- | ---------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------ | | ||
| | `F0Alert` | `F0Alert/__stories__/F0Alert.mdx` | **Gold** | Best-in-class reference | | ||
| | `F0AnalyticsDashboard` | None | **None** | | | ||
| | `F0BigNumber` | `F0BigNumber/__stories__/controls.mdx` | **Stub** | Needs full MDX | | ||
| | `F0Box` | None | **None** | | | ||
| | `F0Button` | `F0Button/__stories__/F0Button.mdx` | **Gold** | 633 lines — gold-standard reference | | ||
| | `F0ButtonDropdown` | `F0ButtonDropdown/__stories__/controls.mdx` | **Stub** | Needs full MDX | | ||
| | `F0ButtonToggle` | `F0ButtonToggle/__stories__/F0ButtonToggle.mdx` | **Adequate** | Solid, missing formal prop table | | ||
| | `F0ButtonToggleGroup` | `F0ButtonToggleGroup/__stories__/controls.mdx` | **Stub** | Needs full MDX | | ||
| | `F0Card` | None | **None** | High priority — heavily used | | ||
| | `F0Checkbox` | `F0Checkbox/__stories__/F0Checkbox.mdx` | **Minimal** | 32 lines, no guidelines or a11y | | ||
| | `F0ChipList` | None | **None** | Flat stories (no `__stories__/` subfolder) | |
There was a problem hiding this comment.
The quality level taxonomy is inconsistent across the new docs: documentation-quality.md defines (Stub/Acceptable/Good/Gold) and SKILL.md refers to (Acceptable/Good/Gold), but this status file uses (Gold/Good/Adequate/Minimal/Stub/None). Please align the levels/definitions so there’s a single shared scale across the skill and references (or clearly explain why this file uses a different scale).
| | Level | Description | | |
| | ------------ | ----------------------------------------------------------------------------------------------------------------------- | | |
| | **Gold** | Full docs: anatomy table (5 cols), variants, when-to-use decision table, DoDonts, a11y keyboard table, 3+ code examples | | |
| | **Good** | Covers all 4 sections (Overview/Guidelines/Code/Examples) with most required tables | | |
| | **Adequate** | Covers core information but missing some sections (e.g., no a11y table, no formal prop table) | | |
| | **Minimal** | Exists but thin — missing guidelines, accessibility, or major sections | | |
| | **Stub** | Only a 7-line `controls.mdx` — not real documentation | | |
| | **None** | No MDX file exists | | |
| --- | |
| ## Individual Components | |
| | Component | MDX File | Quality | Notes | | |
| | ------------------------- | ---------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------ | | |
| | `F0Alert` | `F0Alert/__stories__/F0Alert.mdx` | **Gold** | Best-in-class reference | | |
| | `F0AnalyticsDashboard` | None | **None** | | | |
| | `F0BigNumber` | `F0BigNumber/__stories__/controls.mdx` | **Stub** | Needs full MDX | | |
| | `F0Box` | None | **None** | | | |
| | `F0Button` | `F0Button/__stories__/F0Button.mdx` | **Gold** | 633 lines — gold-standard reference | | |
| | `F0ButtonDropdown` | `F0ButtonDropdown/__stories__/controls.mdx` | **Stub** | Needs full MDX | | |
| | `F0ButtonToggle` | `F0ButtonToggle/__stories__/F0ButtonToggle.mdx` | **Adequate** | Solid, missing formal prop table | | |
| | `F0ButtonToggleGroup` | `F0ButtonToggleGroup/__stories__/controls.mdx` | **Stub** | Needs full MDX | | |
| | `F0Card` | None | **None** | High priority — heavily used | | |
| | `F0Checkbox` | `F0Checkbox/__stories__/F0Checkbox.mdx` | **Minimal** | 32 lines, no guidelines or a11y | | |
| | `F0ChipList` | None | **None** | Flat stories (no `__stories__/` subfolder) | | |
| This file uses the shared documentation quality scale from `documentation-quality.md`: **Stub**, **Acceptable**, **Good**, and **Gold**. | |
| `None` may still appear in the table below, but only as a documentation **status** meaning no MDX file exists yet. | |
| | Level | Description | | |
| | ---------------- | ----------------------------------------------------------------------------------------------------------------------- | | |
| | **Gold** | Full docs: anatomy table (5 cols), variants, when-to-use decision table, DoDonts, a11y keyboard table, 3+ code examples | | |
| | **Good** | Covers all 4 sections (Overview/Guidelines/Code/Examples) with most required tables | | |
| | **Acceptable** | Covers core information and is usable, but still misses some recommended sections or tables | | |
| | **Stub** | Very limited documentation; not yet a complete component reference | | |
| --- | |
| ## Individual Components | |
| | Component | MDX File | Quality / Status | Notes | | |
| | ------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------- | ------------------------------------------ | | |
| | `F0Alert` | `F0Alert/__stories__/F0Alert.mdx` | **Gold** | Best-in-class reference | | |
| | `F0AnalyticsDashboard` | None | **None** | | | |
| | `F0BigNumber` | `F0BigNumber/__stories__/controls.mdx` | **Stub** | Needs full MDX | | |
| | `F0Box` | None | **None** | | | |
| | `F0Button` | `F0Button/__stories__/F0Button.mdx` | **Gold** | 633 lines — gold-standard reference | | |
| | `F0ButtonDropdown` | `F0ButtonDropdown/__stories__/controls.mdx` | **Stub** | Needs full MDX | | |
| | `F0ButtonToggle` | `F0ButtonToggle/__stories__/F0ButtonToggle.mdx` | **Acceptable** | Solid, missing formal prop table | | |
| | `F0ButtonToggleGroup` | `F0ButtonToggleGroup/__stories__/controls.mdx` | **Stub** | Needs full MDX | | |
| | `F0Card` | None | **None** | High priority — heavily used | | |
| | `F0Checkbox` | `F0Checkbox/__stories__/F0Checkbox.mdx` | **Stub** | 32 lines, no guidelines or a11y | | |
| | `F0ChipList` | None | **None** | Flat stories (no `__stories__/` subfolder) | |
- Add Accessibility section template to MDX authoring guide (based on code only, no invented attributes) - Add boolean toggle pattern for optional function props (control: boolean + render fn) - Add semantically-unambiguous rule for DoDonts visual children - Fix gold standard reference in SKILL.md (remove DocsNav reference to F0Button) - Add Accessibility and fn-toggle checklist items to validation checklist
- Remove DocsNav and manual nav menus: Storybook right-side nav is sufficient - Remove Purpose section: description under title already serves this role - Remove Code section: Controls in Anatomy is the interactive props table; separate Code/Props is redundant - Add explicit section order: Anatomy → Modes → Variants → Sizes → Guidelines → Accessibility → Usage - Add Modes/Variants/Sizes as first-class sections (Canvas with stacked story + table each) - Update heading hierarchy documentation - Update validation checklist with all new rules
| | Need | Reference | | ||
| | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | ||
| | Source analysis protocol, props inventory, WHEN→THEN extraction, creator questions | [`references/component-analysis.md`](./references/component-analysis.md) | | ||
| | Quality criteria per section, WHEN→THEN rules, component relationships, a11y by type, 11 global rules | [`references/documentation-quality.md`](./references/documentation-quality.md) | | ||
| | Full MDX template, table templates, utility components (DocsNav, DoDonts), stories update, checklist | [`references/mdx-authoring.md`](./references/mdx-authoring.md) | | ||
| | Which components have docs and which need them | [`references/component-status.md`](./references/component-status.md) | |
There was a problem hiding this comment.
The Quick Reference row lists “DocsNav” as a utility component, but the linked MDX authoring reference explicitly forbids importing/using DocsNav. This is internally inconsistent and will confuse readers; remove the DocsNav mention here (or replace with the actual allowed utilities like Unstyled/DoDonts).
| | Need | Reference | | |
| | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ | | |
| | Source analysis protocol, props inventory, WHEN→THEN extraction, creator questions | [`references/component-analysis.md`](./references/component-analysis.md) | | |
| | Quality criteria per section, WHEN→THEN rules, component relationships, a11y by type, 11 global rules | [`references/documentation-quality.md`](./references/documentation-quality.md) | | |
| | Full MDX template, table templates, utility components (DocsNav, DoDonts), stories update, checklist | [`references/mdx-authoring.md`](./references/mdx-authoring.md) | | |
| | Which components have docs and which need them | [`references/component-status.md`](./references/component-status.md) | | |
| | Need | Reference | | |
| | ------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------ | | |
| | Source analysis protocol, props inventory, WHEN→THEN extraction, creator questions | [`references/component-analysis.md`](./references/component-analysis.md) | | |
| | Quality criteria per section, WHEN→THEN rules, component relationships, a11y by type, 11 global rules | [`references/documentation-quality.md`](./references/documentation-quality.md) | | |
| | Full MDX template, table templates, utility components (Unstyled, DoDonts), stories update, checklist | [`references/mdx-authoring.md`](./references/mdx-authoring.md) | | |
| | Which components have docs and which need them | [`references/component-status.md`](./references/component-status.md) | |
|
|
||
| # F0 Docs | ||
|
|
||
| Every component in `packages/react/src/components/` must have an MDX documentation file in its `__stories__/` folder. This skill defines the mandatory workflow for writing it correctly. |
There was a problem hiding this comment.
“Every component … must have an MDX … in its __stories__/ folder” isn’t accurate for this repo today (there are components using __storybook__/ and some with flat index.stories.tsx outside __stories__/). Consider rephrasing to “next to the stories” and explicitly include __storybook__/ / flat-story cases so the workflow matches the current structure.
| Every component in `packages/react/src/components/` must have an MDX documentation file in its `__stories__/` folder. This skill defines the mandatory workflow for writing it correctly. | |
| Every component in `packages/react/src/components/` must have an MDX documentation file next to its stories. In this repo, that may be in `__stories__/`, in `__storybook__/`, or alongside flat story files such as `index.stories.tsx`. This skill defines the mandatory workflow for writing it correctly. |
| ### Phase 3: Update the stories file | ||
|
|
||
| Remove `autodocs` from meta tags and add `"!dev"` to stories used in documentation: | ||
|
|
||
| ```tsx | ||
| // BEFORE | ||
| const meta = { | ||
| title: "ComponentName", | ||
| component: F0ComponentName, | ||
| tags: ["autodocs", "stable"], | ||
| } | ||
| export const Default: Story = { ... } | ||
|
|
||
| // AFTER | ||
| const meta = { | ||
| title: "ComponentName", | ||
| component: F0ComponentName, | ||
| tags: ["stable"], // autodocs removed | ||
| } | ||
| export const Default: Story = { | ||
| tags: ["!dev"], // hidden from sidebar, still usable in Canvas | ||
| ... | ||
| } | ||
| ``` |
There was a problem hiding this comment.
Phase 3 suggests removing tags: ["autodocs"] and using tags: ["!dev"] to hide stories. In this repo, Storybook sets global tags: ["autodocs"] in .storybook/preview.tsx, and there are no existing usages of a "!dev" tag, so following this guidance likely won’t disable autodocs or hide stories. Update this section to match the repo’s actual mechanism (e.g. use tag negation like "!autodocs" if supported, and/or the existing "no-sidebar" tag/parameters pattern).
|
|
||
| - Create `__stories__/[StoriesFilename].mdx` (filename matches stories file without `.stories`) | ||
| - Follow the Full MDX Template above | ||
| - Check the gold standards first: `F0Alert.mdx` and `F0Button.mdx` |
There was a problem hiding this comment.
This cites F0Alert.mdx and F0Button.mdx as existing gold standards, but neither file exists in packages/react/src/components/ right now (e.g. F0Button/__stories__ only has controls.mdx). Either include those files in this PR or adjust the reference to point to files that exist (or explicitly mark them as “in companion PR”).
| - Check the gold standards first: `F0Alert.mdx` and `F0Button.mdx` | |
| - Check existing full MDX examples in `packages/react/src/components/` first; only cite `F0Alert.mdx` and `F0Button.mdx` as gold standards if they are added in the same PR or explicitly called out as coming from a companion PR |
| 6. **English throughout** — no Spanish, no mixed language, no emoji | ||
| 7. **One unified props table** — Prop | Type | Default | Required | Description — never anatomy + props reference as two separate tables | ||
| 8. **No DocsNav** — Storybook has native sidebar navigation; do not import or use `DocsNav` | ||
| 9. **Import once** — `import { F0X } from "@factorialco/f0-react"` appears once as a tsx code block inside the Usage section, never duplicated |
There was a problem hiding this comment.
Global rule #9 (“Import once … as a tsx code block inside the Usage section”) conflicts with the MDX Authoring reference, which says not to add an import block because .storybook/ImportBanner injects it automatically. Align these rules (either remove the “import once” requirement, or clarify when a manual import snippet is still needed) so authors don’t follow contradictory guidance.
| 9. **Import once** — `import { F0X } from "@factorialco/f0-react"` appears once as a tsx code block inside the Usage section, never duplicated | |
| 9. **Import snippets must not be duplicated** — do not add a manual `import { F0X } from "@factorialco/f0-react"` block when `.storybook/ImportBanner` injects it automatically; only include a manual tsx import snippet when a standalone usage example truly needs it and no injected banner covers that case |
| | `F0BigNumber` | `F0BigNumber/__stories__/controls.mdx` | **Stub** | Needs full MDX | | ||
| | `F0Box` | None | **None** | | | ||
| | `F0Button` | `F0Button/__stories__/F0Button.mdx` | **Gold** | 633 lines — gold-standard reference | | ||
| | `F0ButtonDropdown` | `F0ButtonDropdown/__stories__/controls.mdx` | **Stub** | Needs full MDX | |
There was a problem hiding this comment.
This status table lists MDX files that don’t exist in the current repo (e.g. F0Alert/__stories__/F0Alert.mdx and F0Button/__stories__/F0Button.mdx). Please update these entries to match actual files (or mark them as “companion PR / not yet merged”), otherwise the tracker will be immediately inaccurate.
| | `F0ButtonDropdown` | `F0ButtonDropdown/__stories__/controls.mdx` | **Stub** | Needs full MDX | | |
| | `F0ButtonDropdown` | Companion PR / not yet merged | **None** | Referenced MDX is not present in this repo | |
| | Level | Description | | ||
| | ------------ | ----------------------------------------------------------------------------------------------------------------------- | | ||
| | **Gold** | Full docs: anatomy table (5 cols), variants, when-to-use decision table, DoDonts, a11y keyboard table, 3+ code examples | | ||
| | **Good** | Covers all 4 sections (Overview/Guidelines/Code/Examples) with most required tables | | ||
| | **Adequate** | Covers core information but missing some sections (e.g., no a11y table, no formal prop table) | | ||
| | **Minimal** | Exists but thin — missing guidelines, accessibility, or major sections | | ||
| | **Stub** | Only a 7-line `controls.mdx` — not real documentation | | ||
| | **None** | No MDX file exists | |
There was a problem hiding this comment.
The quality-level definitions reference sections like “Overview/Guidelines/Code/Examples”, but the MDX authoring template in this skill defines a different canonical structure (Anatomy/Modes/Variants/Sizes/Guidelines/Accessibility/Usage) and explicitly forbids a “Code” section. Update these quality descriptions to use the same section names as the template so the rubric matches the workflow.
| | Level | Description | | |
| | ------------ | ----------------------------------------------------------------------------------------------------------------------- | | |
| | **Gold** | Full docs: anatomy table (5 cols), variants, when-to-use decision table, DoDonts, a11y keyboard table, 3+ code examples | | |
| | **Good** | Covers all 4 sections (Overview/Guidelines/Code/Examples) with most required tables | | |
| | **Adequate** | Covers core information but missing some sections (e.g., no a11y table, no formal prop table) | | |
| | **Minimal** | Exists but thin — missing guidelines, accessibility, or major sections | | |
| | **Stub** | Only a 7-line `controls.mdx` — not real documentation | | |
| | **None** | No MDX file exists | | |
| | Level | Description | | |
| | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------- | | |
| | **Gold** | Full docs: anatomy table (5 cols), modes/variants/sizes coverage, when-to-use decision table, DoDonts, accessibility keyboard table, rich usage examples | | |
| | **Good** | Covers most canonical sections (Anatomy/Modes/Variants/Sizes/Guidelines/Accessibility/Usage) with most required tables | | |
| | **Adequate** | Covers core information but is missing some canonical sections or required tables (e.g., Accessibility or Usage details) | | |
| | **Minimal** | Exists but thin — missing Guidelines, Accessibility, Usage, or other canonical sections | | |
| | **Stub** | Only a 7-line `controls.mdx` — not real documentation | | |
| | **None** | No MDX file exists | |
…o use - Remove top-level ## Usage section — named examples live inside Guidelines under ### Usage examples - When to use now supports Canvas blocks before the table to illustrate key sub-cases - Update section order: Anatomy → Modes → Variants → Sizes → Guidelines → Accessibility - Update checklist to reflect new structure
- Scenario titles in ### Usage examples must use **bold** not #### headings - #### headings generate right-side nav anchors and clutter the menu - Add rule to template comment and validation checklist
| 2. `## Modes` — if the component has a `mode` prop with 2+ values: Canvas of a Modes story showing all modes, then a table (Mode | Description | When to use). | ||
| 3. `## Variants` — if the component has a `variant` prop with 2+ values: Canvas of a Variants story showing all variants stacked, then a table (Variant | When to use). | ||
| 4. `## Sizes` — if the component has a `size` prop with 2+ values: Canvas of a Sizes story showing all sizes stacked, then a table (Size | When to use). | ||
| 5. `## Guidelines` — When to use (con Canvas de stories relevantes) / When not to use / Do's and don'ts / Content best practices / Behavior / Usage examples. |
There was a problem hiding this comment.
This section list contains Spanish text (“con Canvas de stories relevantes”), but the same document’s checklist and global rules require English-only. Please rewrite this bullet fully in English to keep the template consistent and copy/paste-safe.
| 5. `## Guidelines` — When to use (con Canvas de stories relevantes) / When not to use / Do's and don'ts / Content best practices / Behavior / Usage examples. | |
| 5. `## Guidelines` — When to use (with Canvas blocks for relevant stories) / When not to use / Do's and don'ts / Content best practices / Behavior / Usage examples. |
| 1. Read `F0ComponentName.tsx` — extract all public props, variants, and JSDoc | ||
| 2. Read `types.ts` — extract exported types | ||
| 3. List all story exports from `[Name].stories.tsx` — these become `Stories.X` references in MDX | ||
| 4. Note if `tags: ["autodocs"]` is present — it must be removed in Phase 3 | ||
|
|
||
| ### Phase 2: Write the MDX file | ||
|
|
||
| - Create `__stories__/[StoriesFilename].mdx` (filename matches stories file without `.stories`) | ||
| - Follow the Full MDX Template above | ||
| - Check the gold standards first: `F0Alert.mdx` and `F0Button.mdx` | ||
| - If a `controls.mdx` stub already exists: **delete it** after creating the full MDX — two MDX files cause duplicate sidebar entries | ||
|
|
||
| ### Phase 3: Update the stories file | ||
|
|
||
| Remove `autodocs` from meta tags and add `"!dev"` to stories used in documentation: | ||
|
|
||
| ```tsx | ||
| // BEFORE | ||
| const meta = { | ||
| title: "ComponentName", | ||
| component: F0ComponentName, | ||
| tags: ["autodocs", "stable"], | ||
| } | ||
| export const Default: Story = { ... } | ||
|
|
||
| // AFTER | ||
| const meta = { | ||
| title: "ComponentName", | ||
| component: F0ComponentName, | ||
| tags: ["stable"], // autodocs removed | ||
| } | ||
| export const Default: Story = { | ||
| tags: ["!dev"], // hidden from sidebar, still usable in Canvas | ||
| ... | ||
| } |
There was a problem hiding this comment.
Phase 3 instructs removing autodocs and adding tags: ["!dev"] to hide stories, but !dev isn’t used anywhere in the repo and Storybook’s sidebar filtering only checks for no-sidebar (see packages/react/.storybook/manager.ts). Also, because preview sets global tags: ["autodocs"], removing autodocs from meta doesn’t disable autodocs—an explicit opt-out tag (e.g. "!autodocs") is needed. Update this workflow to use the actual supported tags/filters (e.g. add "!autodocs" to meta and use "no-sidebar" where appropriate).
|
|
||
| 1. **`F0ComponentName.tsx`** — public props, JSDoc comments, variants, conditional rendering, ARIA attributes, event handlers | ||
| 2. **`types.ts`** — exported types and union values | ||
| 3. **`index.tsx`** — export pattern (`experimentalComponent`, `Component({ name, type }`, or plain re-export) |
There was a problem hiding this comment.
The example export pattern in the index.tsx bullet is missing a closing ) (it shows Component({ name, type }). Fix it to a syntactically complete snippet (e.g. Component({ name, type })) so it’s unambiguous for readers.
| 3. **`index.tsx`** — export pattern (`experimentalComponent`, `Component({ name, type }`, or plain re-export) | |
| 3. **`index.tsx`** — export pattern (`experimentalComponent`, `Component({ name, type })`, or plain re-export) |
…## sections Rationale: they describe structural forms of the component (anatomy), not usage guidance. Keeping them under ## Anatomy gives the right-side nav three clean entries: Anatomy · Guidelines · Accessibility. - Update heading hierarchy documentation - Update section order with rationale - Update MDX template - Update validation checklist
…ent type Accessibility is not always valuable — a section that says 'accessible by default' for a layout component is worse than no section at all. - Add decision table: complex interactive (required), simple interactive (only if non-obvious), static display (only for live region or icon), layout/typography (omit entirely) - Update MDX template with decision table in the Accessibility comment - Update documentation-quality.md with the same table and rationale - Update validation checklist: presence is no longer always required
| 2. Read `types.ts` — extract exported types | ||
| 3. List all story exports from `[Name].stories.tsx` — these become `Stories.X` references in MDX | ||
| 4. Note if `tags: ["autodocs"]` is present — it must be removed in Phase 3 | ||
|
|
There was a problem hiding this comment.
The workflow says tags: ["autodocs"] “must be removed”, but the repo has global autodocs enabled via preview.tags = ["autodocs"]. To actually disable autodocs you need an explicit opt-out tag like "!autodocs"; otherwise manual MDX and autodocs can coexist/duplicate. Please update this step to match the repo’s Storybook configuration.
| Remove `autodocs` from meta tags and add `"!dev"` to stories used in documentation: | ||
|
|
||
| ```tsx | ||
| // BEFORE | ||
| const meta = { | ||
| title: "ComponentName", | ||
| component: F0ComponentName, | ||
| tags: ["autodocs", "stable"], | ||
| } | ||
| export const Default: Story = { ... } | ||
|
|
||
| // AFTER | ||
| const meta = { | ||
| title: "ComponentName", | ||
| component: F0ComponentName, | ||
| tags: ["stable"], // autodocs removed | ||
| } | ||
| export const Default: Story = { | ||
| tags: ["!dev"], // hidden from sidebar, still usable in Canvas | ||
| ... | ||
| } | ||
| ``` | ||
|
|
||
| **Tag reference:** | ||
|
|
||
| | Tag | Applied to | Effect | | ||
| | -------------- | ----------------------- | ---------------------------------------------------------------------------------------- | | ||
| | `"!dev"` | Story export | Hides story from sidebar in dev mode. Still accessible via `<Canvas>` in MDX. | | ||
| | `"no-sidebar"` | `<Meta>` in an MDX file | Hides the MDX page from the sidebar. Used by legacy stubs — not needed in new MDX files. | | ||
| | `"autodocs"` | Meta in stories file | Auto-generates a docs tab. Remove when adding a manual MDX — they conflict. | |
There was a problem hiding this comment.
This document instructs using a tags: ["!dev"] story tag to hide stories from the sidebar, but the repo’s sidebar filtering is implemented via the "no-sidebar" tag (see .storybook/manager.ts), and there are no other references/handlers for "!dev". As written, "!dev" won’t do anything; switch the guidance to "no-sidebar" (or document the actual mechanism used).
|
|
||
| - Create `__stories__/[StoriesFilename].mdx` (filename matches stories file without `.stories`) | ||
| - Follow the Full MDX Template above | ||
| - Check the gold standards first: `F0Alert.mdx` and `F0Button.mdx` |
There was a problem hiding this comment.
This points readers to F0Alert.mdx / F0Button.mdx as gold standards, but those files are not present in the repo (only controls.mdx stubs exist for Button, and Alert has no MDX). Either include those MDX files in this PR or update these references to files that exist to prevent dead ends.
| - Check the gold standards first: `F0Alert.mdx` and `F0Button.mdx` | |
| - Before writing, review an existing full component MDX in `__stories__/` and use one with the complete docs structure as your reference, not a `controls.mdx` stub |
| | Level | Description | | ||
| | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | ||
| | **Stub** | Auto-generated or empty. `autodocs` tag, no manual content. Unacceptable for any shipped component. | | ||
| | **Acceptable** | All four sections present, all props documented, no broken Canvas references. Meets the minimum bar. | | ||
| | **Good** | WHEN→THEN rules in Guidelines, DoDonts, keyboard table for interactive components, 3+ named examples. | | ||
| | **Gold** | Everything in Good, plus: decision table (when to use vs. alternatives), component relationships, a11y notes per prop, real Factorial copy in examples. See `F0Alert.mdx` and `F0Button.mdx`. | |
There was a problem hiding this comment.
The “Acceptable” definition says “All four sections present”, but the MDX authoring template in this same skill defines three top-level sections (Anatomy, Guidelines, Accessibility) and explicitly forbids separate Purpose/Code sections. Align the quality level definitions with the actual required section structure so authors aren’t optimizing for contradictory requirements.
| | Level | Description | | |
| | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | |
| | **Stub** | Auto-generated or empty. `autodocs` tag, no manual content. Unacceptable for any shipped component. | | |
| | **Acceptable** | All four sections present, all props documented, no broken Canvas references. Meets the minimum bar. | | |
| | **Good** | WHEN→THEN rules in Guidelines, DoDonts, keyboard table for interactive components, 3+ named examples. | | |
| | **Gold** | Everything in Good, plus: decision table (when to use vs. alternatives), component relationships, a11y notes per prop, real Factorial copy in examples. See `F0Alert.mdx` and `F0Button.mdx`. | | |
| | Level | Description | | |
| | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | |
| | **Stub** | Auto-generated or empty. `autodocs` tag, no manual content. Unacceptable for any shipped component. | | |
| | **Acceptable** | Required top-level sections present (`Anatomy`, `Guidelines`, `Accessibility`), all props documented, no broken Canvas references. Meets the minimum bar. | | |
| | **Good** | WHEN→THEN rules in Guidelines, DoDonts, keyboard table for interactive components, 3+ named examples. | | |
| | **Gold** | Everything in Good, plus: decision table (when to use vs. alternatives), component relationships, a11y notes per prop, real Factorial copy in examples. See `F0Alert.mdx` and `F0Button.mdx`. | |
| 6. **English throughout** — no Spanish, no mixed language, no emoji | ||
| 7. **One unified props table** — Prop | Type | Default | Required | Description — never anatomy + props reference as two separate tables | ||
| 8. **No DocsNav** — Storybook has native sidebar navigation; do not import or use `DocsNav` | ||
| 9. **Import once** — `import { F0X } from "@factorialco/f0-react"` appears once as a tsx code block inside the Usage section, never duplicated |
There was a problem hiding this comment.
Global rule #9 requires an import snippet inside a “Usage” section, but mdx-authoring.md explicitly forbids a top-level ## Usage section and any visible import block (ImportBanner is injected). These rules conflict; please update one side so the guidance is consistent.
| 9. **Import once** — `import { F0X } from "@factorialco/f0-react"` appears once as a tsx code block inside the Usage section, never duplicated | |
| 9. **Import once** — the component import is provided by the injected `ImportBanner`; do not add a duplicate visible import code block or create a top-level `## Usage` section just to show it |
| | Component | MDX File | Quality | Notes | | ||
| | ------------------------- | ---------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------ | | ||
| | `F0Alert` | `F0Alert/__stories__/F0Alert.mdx` | **Gold** | Best-in-class reference | | ||
| | `F0AnalyticsDashboard` | None | **None** | | | ||
| | `F0BigNumber` | `F0BigNumber/__stories__/controls.mdx` | **Stub** | Needs full MDX | | ||
| | `F0Box` | None | **None** | | | ||
| | `F0Button` | `F0Button/__stories__/F0Button.mdx` | **Gold** | 633 lines — gold-standard reference | | ||
| | `F0ButtonDropdown` | `F0ButtonDropdown/__stories__/controls.mdx` | **Stub** | Needs full MDX | |
There was a problem hiding this comment.
This status table claims F0Alert/__stories__/F0Alert.mdx and F0Button/__stories__/F0Button.mdx exist and are Gold, but those files are not present in the repo (Alert has no MDX, Button has only controls.mdx). Please correct these entries (or add the missing MDX files in this PR) so the status tracker remains reliable.
|
|
||
| ## Table Templates | ||
|
|
||
| All tables use `<Unstyled>` with native HTML — never raw markdown tables (they break in dark mode). |
There was a problem hiding this comment.
This sets a hard rule to never use markdown tables in MDX, but there are existing MDX docs that currently use markdown tables (e.g. F0DataChart/__stories__/F0DataChart.mdx). If this is a new standard, consider calling out that legacy docs don’t comply yet (or relax the wording) to avoid the status tracker/quality rubric conflicting with current reality.
| All tables use `<Unstyled>` with native HTML — never raw markdown tables (they break in dark mode). | |
| For new or updated MDX docs, use `<Unstyled>` with native HTML instead of raw markdown tables, since markdown tables break in dark mode. Some legacy docs may still use markdown tables and should be migrated when they are updated. |
| ```tsx | ||
| export const Default: Story = { | ||
| args: { | ||
| onClose: true, // boolean default — Controls shows a toggle | ||
| }, | ||
| render: ({ onClose, ...args }) => ( | ||
| <F0ComponentName {...args} onClose={onClose ? fn() : undefined} /> | ||
| ), | ||
| }; | ||
| ``` |
There was a problem hiding this comment.
The “boolean toggle for optional function props” example sets args.onClose = true, but with StoryObj<typeof meta> the args type is derived from the component props, so a boolean value for a callback prop will fail TypeScript. Consider documenting a type-safe pattern (e.g. a separate boolean arg like hasOnClose / showDismiss mapped to onClose in render, or a properly typed custom StoryObj<...> args type) so this guidance compiles under TS strictness.
… feedback - Modes table: Mode | Description only (no 'When to use' — belongs in Guidelines) - Sizes table: Size | Description with visual/structural descriptions, not generic advice - Add Modes and Sizes table templates to Table Templates section - Add generic type T rule in Behavior template: document type parameter and typed callback signature - Update validation checklist with three new checks
- Remove ### Sizes from default section order — only include when the component has size-specific behavior not covered by system defaults - Update template comment and validation checklist accordingly
…emplate When to use / When not to use / Do's and don'ts should use **bold** not #### headings — headings generate anchors in the right-side nav and clutter it.
…uthoring - When to use: document prose+Canvas-per-sub-case pattern before the table - When to use table: add rule to not repeat what Modes/Variants Canvas already shows - When not to use: require concrete component or pattern in 'Use instead' column - DoDonts children: document provider-dependent components pattern (dedicated stories with tags:[!dev] + Canvas sourceState=none as children) Implemented-with: factorial-f0
eliseo-juan
left a comment
eliseo-juan
left a comment
There was a problem hiding this comment.
I'll ensure that we are loading only what we need for each step
Summary
packages/react/.skills/f0-docs/— a new agent skill that defines the mandatory 4-step workflow for documenting F0 components in Storybook (MDX)children, heading hierarchy, and correct import rules for components used as JSX in MDXReferences
F0Alert.mdx(see companion PR)packages/react/.skills/f0-docs/SKILL.md