Summary
With T309109 and T317198, we are refactoring the site architecture to create top-level nav sections for design tokens, components, and icons. Each section will have its own sidebar.
Design tokens and icons already have an overview page, which is the first item in the sidebar:
To maintain consistency and better pair component usage information with the component section, the components section should also have its own overview page.
Challenges
The packages/codex-docs/docs/components directory is automatically emptied and repopulated by the build script (see package.json in the docs package). Therefore, we can't add an overview.md file to that directory and expect it to persist (it would also be gitignored, but that's easy to fix).
We should also keep T317160 in mind, which may involve including mixin demo pages with the components. A solution that works for the overview page might not be sufficient to support mixin pages, which will need to live alongside component pages but won't be generated via vue-docgen-cli.
Content
My initial proposal for content is this:
# Components Components are the interactive building blocks of our design system, used to create consistent and powerful user interfaces. The Codex library contains fully interactive components built with [Vue 3](https://vuejs.org/). In the future, some CSS-only components will be provided via [Less mixins](https://lesscss.org/features/#mixins-feature). Each component in Codex has a demo page where you can interact with working examples, see code samples, and read detailed usage information. ## Resources - Learn how to [use Codex components](../using-codex/usage.html#using-components) - Learn how to [contribute or request a component](../contributing/overview.html)
We also might consider adding the following:
- Moving the "Using components" section from the usage docs to here
- Linking to the mediawiki.org page on using Codex components within MediaWiki
