chore(Docs): Add component docs#1517
Conversation
|
Size stats
|
|
Deploy preview for mistica-web ready! ✅ Preview Built with commit 2b00564. |
|
Accessibility report ℹ️ You can run this locally by executing |
Marcosld
left a comment
Marcosld
left a comment
There was a problem hiding this comment.
Should we already define how do we intend to transition between this and a shared doc for devs and LLMs?
|
|
||
| ### Don't use for | ||
|
|
||
| - Do not use it as a standalone content element; it should decorate another component |
There was a problem hiding this comment.
i don't really like the word "decorate" because isnt a decoration (in terms of accessibility for example)
There was a problem hiding this comment.
Well, actually badge is hidden to screen readers, so we could state that is decorative, but i would't use that wording either. I've removed this point since we use badges standalone.
| - Do not use secondary styling for the main conversion or progression action | ||
| - Do not present too many secondary actions in one group, which can dilute clarity | ||
| - Do not style destructive actions as secondary when risk needs explicit emphasis | ||
|
|
There was a problem hiding this comment.
I can see a lot of "style" verb in this rules... Looks like is talking about style css or something similar. I have doubts about let this kind of "doors" open (mainly to avoid confusion in a human or a machine that can think the buttons can be customize)
| #### Use for | ||
|
|
||
| - Browsing related cards or modules when horizontal exploration is the intended interaction | ||
| - Revealing progressive content with clear page feedback (bullets) and optional directional controls |
There was a problem hiding this comment.
I would replace "bullet" by "page indicator" or similar maybe to make it more agnostic (also in description maybe)
There was a problem hiding this comment.
This may collision with new carousel definition? I was using page bullets / page counter
|
|
||
| #### Use for | ||
|
|
||
| - Showing a small sequence of prominent slides (for example hero banners or featured stories) one page at a |
There was a problem hiding this comment.
mayb can we include Hero component to expose the possibility to combine with this component? (the same in hero component)
|
|
||
| ## ButtonLinkDanger | ||
|
|
||
| ButtonLinkDanger is a low-emphasis destructive action used when risk exists but should not dominate the |
There was a problem hiding this comment.
I would clarify the usage between ButtonDanger vs ButtonLinkDanger. Maybe something like: "Use ButtonDanger for primary destructive actions with maximum prominence; use ButtonLinkDanger for secondary destructive actions that need lighter emphasis."
There was a problem hiding this comment.
I've changed the first bullet point in Don't use for section to redirect users to buttonDanger in maximum prominence destructive actions
| - Do not use ToggleIconButton for multi-step or multi-option choices beyond two states | ||
| - Do not use the same icon/label for checked and unchecked states when meaning changes | ||
| - Do not omit accessible naming for each state; state intent must be understandable to assistive tech | ||
| - Do not use toggle interactions when the action is not reversible or does not represent a true on/off state |
There was a problem hiding this comment.
I'd simplify this to: "Do not use ToggleIconButton for actions that are not truly binary (on/off)." The "reversible" part is implied.
There was a problem hiding this comment.
I wouldn't say is implied and I would keep it, meaning the moment you use a toggle is not to go to a state you cannot come from again, since thats an action
| - Do not use large primary actions in this pattern when compact action treatment is expected | ||
| - Do not present decorative visuals without clear supporting message and intent | ||
|
|
||
| ## CardActionIconButton |
There was a problem hiding this comment.
This component have no description or usage guidelines.
|
|
||
| ## CardActionIconButton | ||
|
|
||
| ## CardActionSpinner |
There was a problem hiding this comment.
This component have no description or usage guidelines.
| - Do not rely on deprecated small-card patterns when `NakedCard size="snap"` is the intended approach | ||
| - Do not overload transparent cards with excessive actions that reduce scanability on busy backgrounds | ||
|
|
||
| ## HighlightedCard |
There was a problem hiding this comment.
I think if they're still in the library we should document them. We could either:
-Keep individual files but add status: deprecated in the frontmatter with a note pointing to the replacement
-Group all deprecated cards into a single DeprecatedCards.md file with each as a subsection
Wdyt?
| @@ -0,0 +1,369 @@ | |||
| // @ts-check | |||
| // Component categories based on Storybook structure (src/__stories__) | |||
There was a problem hiding this comment.
The categories file looks good. After looking into this, adding a synonyms field could help improve search and LLM understanding for categories that might be searched by different names (eg "collapse" for accordions, "toggle" for switch, "tag" for chip). We can keep it as a future idea if we see it's needed
There was a problem hiding this comment.
This file was intended to help autogeneration, I should remove this with the removal of the script
| - Do not rely on decorative circles alone to communicate critical information | ||
| - Do not use low-contrast background and border combinations that reduce legibility | ||
|
|
||
| ## Touchable |
There was a problem hiding this comment.
What's the difference between Touchable and TouchableElement?
There was a problem hiding this comment.
Removed Touchable element, was the typescript type definition not the exported component
|
|
||
| # StackingGroup | ||
|
|
||
| Use stacking group to display a compact set of similarly sized items, optionally overlapped, with a `+N` overflow indicator. |
There was a problem hiding this comment.
Should we add information about the +N element?
| - Binary preferences or settings that can be turned on and off independently | ||
| - Cases where the state change is immediate and does not require a separate confirmation action | ||
| - Interfaces with short, explicit labels (or accessible labels) so users understand the effect of each toggle | ||
| - Optional custom switch row compositions where the control remains semantically exposed as a switch |
There was a problem hiding this comment.
Should we clarify what "switch row composition" means?
There was a problem hiding this comment.
Instead I've added a new line in don't use for recommending using a row with built in switch support
| @@ -0,0 +1,22 @@ | |||
|
|
|||
| # Tag | |||
There was a problem hiding this comment.
Should we make this distinction explicit between Tag and Chip? We could reinforce in each component's documentation that they serve different purposes. Tag is for status/category (non-interactive), while Chip is for actions or selection (interactive).
There was a problem hiding this comment.
I've updated usage section redirecting users to the right component based on purpose
| - Do not rely on overlay dismissal for destructive or irreversible flows without explicit confirmation | ||
| - Do not stack multiple independent overlays when a single coordinated layer can manage focus and dismissal | ||
|
|
||
| ## FocusTrap |
There was a problem hiding this comment.
FocusTrap, Portal, and applyAlpha have ambiguous descriptions. Could we follow how Overlay is documented to improve them?
There was a problem hiding this comment.
Pull request overview
Adds a new set of component documentation pages under doc/components/, intended to describe Mística components/utilities and provide usage + accessibility guidance, plus a category map aligning docs with Storybook structure.
Changes:
- Added many new Markdown docs for components (usage guidelines + accessibility sections).
- Added
doc/components/component-categories.jsmapping Storybook-like categories to documented components. - Included documentation for utilities/hooks alongside UI components.
Reviewed changes
Copilot reviewed 52 out of 52 changed files in this pull request and generated 11 comments.
Show a summary per file
| File | Description |
|---|---|
| doc/components/accordions.md | New docs for Accordion components + accessibility notes |
| doc/components/avatar.md | New docs for Avatar usage guidance |
| doc/components/badge.md | New docs for Badge usage + accessibility behavior |
| doc/components/breadcrumbs.md | New docs for Breadcrumbs usage + accessibility behavior |
| doc/components/buttons.md | New docs for button components + accessibility guidance |
| doc/components/callout.md | New docs for Callout usage + accessibility roles/labels |
| doc/components/cards.md | New docs for card components + accessibility guidance |
| doc/components/carousels.md | New docs for carousel components + accessibility guidance |
| doc/components/checkbox.md | New docs for Checkbox usage + accessibility guidance |
| doc/components/chip.md | New docs for Chip usage + accessibility guidance |
| doc/components/community.md | New docs for community components (blocks) |
| doc/components/component-categories.js | Category-to-components mapping for docs alignment |
| doc/components/counter.md | New docs for Counter usage + accessibility labels |
| doc/components/data-visualizations.md | New docs for Meter usage + accessibility guidance |
| doc/components/empty-states.md | New docs for EmptyState usage guidance |
| doc/components/feedback.md | New docs for feedback screens/components |
| doc/components/forms.md | New docs for Form-related APIs + accessibility guidance |
| doc/components/headers.md | New docs for header components + heading accessibility |
| doc/components/hero.md | New docs for Hero/CoverHero + accessibility guidance |
| doc/components/hooks.md | New docs for hooks list (descriptions + usage guidance) |
| doc/components/input-fields.md | New docs for input field components/utilities + accessibility |
| doc/components/layout.md | New docs for layout primitives + accessibility guidance |
| doc/components/lists.md | New docs for list components + accessibility guidance |
| doc/components/loading.md | New docs for loading components + accessibility guidance |
| doc/components/logo.md | New docs for Logo components |
| doc/components/menu.md | New docs for Menu components + accessibility guidance |
| doc/components/modals.md | New docs for modal/sheet/drawer patterns + accessibility guidance |
| doc/components/mosaic.md | New docs for Mosaic components + accessibility guidance |
| doc/components/navigation-bars.md | New docs for navigation bar components + accessibility guidance |
| doc/components/popover.md | New docs for Popover usage + accessibility guidance |
| doc/components/primitives.md | New docs for primitives (Image/Video/etc.) + accessibility guidance |
| doc/components/progress-indicators.md | New docs for ProgressBar components + accessibility guidance |
| doc/components/radio-button.md | New docs for RadioButton/RadioGroup + accessibility guidance |
| doc/components/rating.md | New docs for Rating components + accessibility guidance |
| doc/components/select.md | New docs for Select usage + accessibility guidance |
| doc/components/skeletons.md | New docs for skeleton components usage guidance |
| doc/components/skip-link.md | New docs for SkipLink/SkipLinkNav + accessibility guidance |
| doc/components/slider.md | New docs for Slider usage + accessibility guidance |
| doc/components/snackbar.md | New docs for Snackbar + useSnackbar + accessibility guidance |
| doc/components/stacking-group.md | New docs for StackingGroup usage + accessibility guidance |
| doc/components/stepper.md | New docs for Stepper usage + accessibility guidance |
| doc/components/switch.md | New docs for Switch usage + accessibility guidance |
| doc/components/table.md | New docs for Table usage + accessibility guidance |
| doc/components/tabs.md | New docs for Tabs usage + accessibility guidance |
| doc/components/tag.md | New docs for Tag usage + accessibility guidance |
| doc/components/text-link.md | New docs for TextLink usage + accessibility guidance |
| doc/components/text.md | New docs for Text + presets (Text1–Text10) |
| doc/components/timeline.md | New docs for Timeline components + accessibility guidance |
| doc/components/timer.md | New docs for Timer/TextTimer + accessibility guidance |
| doc/components/titles.md | New docs for Title1–Title4 + heading accessibility |
| doc/components/tooltip.md | New docs for Tooltip usage + accessibility guidance |
| doc/components/utilities.md | New docs for theming/util utilities (contexts, overlays, helpers) |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| #### Don't use for | ||
|
|
||
| - Don't use a timeline to guide a user through a step flow use the stepper or |
|
|
||
| ## Spinner | ||
|
|
||
| spinner. You can see how to apply spinner in buttons here. |
| #### Use for | ||
|
|
||
| - Collecting user input with clear labels and contextual help text | ||
| - Supporting validation and accessible feedback in form flows | ||
|
|
||
| #### Don't use for | ||
|
|
||
| - Don't use a spinner when: | ||
| - If you don’t want the spinner to be read by a screen reader, it can be deactivated. |
|
|
||
| ## TimeField | ||
|
|
||
| information that the user needs to enter in the field. |
| - For a better understanding of input usage in forms read our forms documentation. | ||
| - Collecting user input with clear labels and contextual help text | ||
| - Supporting validation and accessible feedback in form flows |
|
|
||
| ## ThemeConfig | ||
|
|
||
| ThemeConfig provides reusable behavior to keep component logic consistent across the product. |
|
|
||
| ## ThemeContext | ||
|
|
||
| ThemeContext provides reusable behavior to keep component logic consistent across the product. |
|
|
||
| ## ThemeContextProvider | ||
|
|
||
| ThemeContextProvider provides reusable behavior to keep component logic consistent across the product. |
| The Timeline component is used to represent events in a chronological timeline. It can be used to visually and | ||
| organizedly display processes,. |
| - Collecting user input with clear labels and contextual help text | ||
| - Supporting validation and accessible feedback in form flows | ||
|
|
||
| #### Don't use for | ||
|
|
||
| - Do not use this component to display read-only information | ||
| - Do not hide validation context that users need to complete the task |
Add component docs under docs/component