Components

Documenting components with stories

When we develop components it's important to document them, that means informing what purpose they have, where to use and how to use. There are also tooling around components such as stories that allows us to in an isolated way view and test components. Think of it like OpenAPI/Swagger that is used for APIs, but as a playground and technical documentation for components.

The term "component stories" have become a more general term, which was first used by Storyblok. However we use Histoire to create stories, since it's much more lightweight, uses easier syntax and is better focused on what it tries to solve.

Similar to OpenAPI, using stories also have the advantage of leaving the technical documentation next to the code implementation and automates parts of the documentation. This allows a developer to more easily change the documentation meanwhile making a code change and the documentation will be more guaranteed to be up to date.

More general documentation about components that are not related to the technical aspects of them are placed in a more fitting location. This could be concepts, guides, overview, guidelines, principles and more. Stories are used as a reference to the functionality and implementation of a specific component, meanwhile documentation like the document you're currently reading is used to guide and introduce you to them.

Offcenit.no - Nuxt Content Components

We are currently in the process of developing a new website using Nuxt Content, that also includes an underlying framework of components that are made to be reusable.

We try not to reinvent the wheel with those components, so the best way to go about developing these is using the functionality from other UI libraries that has already been tested and standardised, such as shadcn and shadcn nuxt content. These are made to be themed and customized, but when we port over the components, it's natural to improve on them for our use-case (just keep them somewhat similar so we benefit from updates).

Here's the list of components and their respective status:

•  Hero Covers the whole page to set focus to central element(s). Usage: Landing page, bigger blog entries
• LeftRightSplitContent Content is split in two, nested components on each side Usage: Landing page, blog entries, portfolio.
• Cards
  • QuoteCard
  • ProfileCard Card to use for i.e “about us” or to highlight a person anywhere else on the page.
• CardGroup Usage: Landing page, blogs, portfolio.
• Alert Element that highlights important information, could be a warning, danger, success and so forth. Usage: Documentation pages, blog entries, portfolio.
• DualCounter A component that shows i.e uptime over x amount of websites or projects with x amount of customers. Usage: Landing page and blog entries.
• Carrousel A carrousel that shows i.e logos of companies, frameworks, programming languages etc. Can be clickable. Usage: Landing page.
• CallToAction Usage: Landing page, blogs, portfolio etc.
  • CallToActionForm A form that let’s a user to i.e sign up, contact us, sign up to be pilot, subscribe to newsletter, give feedback etc.
  • CallToActionLink Link to external or internal page
  • CallToActionBooking To show a booking system to reserve an hour.
  • CallToActionBlog Built-in card to show a blog entry
  • CallToActionProduct Built-in card to show a product
  • CallToActionPortfolio Built-in card to show a portfolio entry
• CodeGroup (optional) Usage: Blog entries.
• Tooltip Usage: To explain complex terms in popups instead of in i.e an article.