Summary

With T314332, we decided to support certain standard visual styles via Less mixins. Some of these mixins, such as Link (T316895), are effectively components that only require shared Less mixins rather than a JavaScript implementation. We should consider how to document component mixins like Link on the docs site, then implement this new infrastructure.

Implementation

Considerations

• We should consider how users of the Codex site will look for components that they want to learn about or use, and organize things in an intuitive and clear way
• In addition to components that are only implemented as Less mixins, we may eventually have components (like Button and some inputs) that are implemented both ways. We should keep this in mind as we develop the architecture for standalone mixins.
• The current component docs infrastructure relies on vue-docgen-cli and a custom script that runs vue-docgen-cli, pulls from the manually-created component demos, and puts everything on a single page in a standard order
• The current design tokens demos are all manually constructed and use various Vue components for standard layouts
• We will need to build out infrastructure for displaying a page for each mixin or a single page with all mixins

Options

Location of component mixin demo pages

Option 1: Include demo pages for component mixins alongside Vue component demo pages

This option would not separate Vue components from mixins, but would place mixins where they logically belong alongside components. This would be further supported when we implement component groupings, which will aim to group components by what they do (rather than what they are or how they're implemented).

For components that are implemented both as a Vue component and a Less mixin, we could document both versions on a single demo page.

Option 2: Include demo pages for component mixins as a separate section, distinct from components

Alternately, we could have a separate section on the docs site for mixins. This would mean changing the site architecture to create a place for mixins, and would mean documenting components implemented both as a Vue component and a less mixin in two separate places.

Infrastructure for component mixin demo pages

These options apply to the first solution for location above (alongside Vue components).

Option 1: Copy mixin demo pages into docs/components/demos

Process:

• As component demos are set up in packages/codex-docs/component-demos, so mixin demos will be set up in packages/codex-docs/mixin-demos
• These mixin demos will take a similar form as the component ones, a markdown file explaining the mixin and providing examples as Vue components
• We write a script that copies all files matching the pattern mixin-demos/[mixin-name]/[mixin-name].md into docs/components/demos at the end of the docgen:build script

Upside: component mixins live alongside components and have the same path
Downside: no HMR out of the box; we'd have to write a script to watch these files for changes and copy them over when they do

Option 2: Static mixin files in a separate directory

Process:

• We set up docs/components/mixins as a directory for static mixin demo pages
• We either list them in a separate section in the sidebar, or mix them into the list of components

Upside: HMR, extremely easy
Downside: mixin demo pages have a different path than component demo pages

---

Acceptance criteria

• Choose an implementation path
• Implement the necessary infrastructure, using the Link component as an example
• Include general instructions on using these mixins