Outline Roadmap: v1.0.0

[himerus]

Description

This is intended to be a basic roadmap for Outline. In order to better define what features we expect for a stable release, this roadmap will guide our ticket/issues and help us move more quickly to what we want to consider 1.0.0.

Checklist of high level priorities

• Lit 2 support
• Consistent demo/out of the box styling for ALL components
  • Work with the Storybook specific demo colors/fonts to provide clean starting samples/demonstrations.
• Monorepo
  • New consumer documentation based on monorepo and new methods
  • Test environments and pipelines to ensure it can fully function in multiple consumers
• CLI
  • Creates a "base" consumer
    • Consumes Outline
    • Has a Storybook instance pre-configured
    • Has Tailwind as an optional configuration in the consumer
    • ...
  • Create a new component
    • Optional Storybook story
    • Optional CSS file
    • Optional Tests
  • outline link - yarn link automation/simplification
• Documentation
  • Setting up an Outline design system
    • Best Practices
    • Gotchas
  • Setting up an Outline consumer
    • Best Practices
    • Gotchas
  • Going beyond: What's next?

Conclusion

Let's discuss this through the comments and iterate on a reasonable checklist we can ticket out.

[danmuzyka]

Here are a few more thoughts about what should be on the roadmap.

• 100% agree about the monorepo and architecting Outline into an npm package that can be a dependency of the design system implemented on each project (versus the fork-and-go approach we have now).
  • Would the idea still be that Outline implementations would be in their own repo, separate from the consumer?
  • Related to this, if developers want to use yarn link locally, will they still have to compile the Outline project manually so that there is a build artifact for yarn link to symlink, or will there be an item on the roadmap to streamline this process?
• 100% agree about the CLI tools.
  • The project-level generator described in the list above is a good idea, but I would actually recommend prioritizing a component generator command over that. Both could be on the roadmap, but that's the priority order that makes sense to me. The reasons for that are:
    • A command to scaffold code for a consumer will not be needed nearly as often as a command to instantiate a new component.
    • Plus, having a command to scaffold the boilerplate code for a new component will be particularly useful for less experienced developers, who will be far more likely to be building new components than they will be to setting up a new project and scaffolding a consumer.
  • The VSCode extension to scaffold code for components is nice, but it doesn't generate the entire directory of files. A CLI command would also be editor-agnostic, which is nice.
• I also agree about having at least minimally-styled example components in the defaults that come with Outline, so that someone viewing the Storybook instance for Outline itself could get a clearer picture of what the various default components are like. Maybe a few styling variations of each component would help design and UX team members better understand the flexibility and range of possibilities that each component offers.
• Documentation:
  • The developer documentation in the two projects you and I discussed would be great to backport into the Outline project itself (I suspect this is already the plan).
    • However, I'm seeing inconsistency on those projects in terms of where certain documentation lives. On one project, the README file has some of the basic developer info, but some of that same info is in Storybook on the other project.
    • I think what would make the most sense would be to have any documentation that is an overview, or related to initial project setup, in the README or other documentation linked from the README that is in the repository itself. Developers will need basic setup documentation in the repo itself, because if they start a new Outline project but can't get their environment running, they won't be able to access the documentation that lives in Storybook. That's why I really like the documentation that one project has added to their README file.
  • The class extension code examples on the project that has them in storybook are a good idea. It would be helpful to include more explanation, and code samples of the classes, on the rendered Storybook page (similar to what exists on the Code Style Guide in Storybook for that project), so that developers don't have to go back to their IDE to look at the actual example code.
  • The code style guide should define the following:
    • Standards for component naming conventions (e.g., namespace all project-level components with a three-character prefix).
    • Standards for how to organize the components in the directory structure of the project repository (e.g., create directories that correspond with the categories in Storybook, and put components into those, rather than having all components as siblings of each other in the directory structure).
    • Standards around accessibility expectations.
    • Standards that set expectations for what level of unit testing should components have at minimum.
    • More exposition/explanation of each code sample in the style guide than currently exists in the project's code style guide (which consists mostly of code samples with very little information walking the reader through those code samples).
  • Let's explicitly document what the purpose is of the various subdirectories of src/components/:
    • base
    • controllers
    • examples
    • utility
    • the project-specific components subdirectory
    • etc.
  • Documentation of all of the commands in package.json.
  • Documentation about how to make components accessible.
  • Documentation about how to write unit tests for components.
• Unit tests for all base components (it looks as though nearly all base components have this, but a couple do not).

These are the ideas that come to mind at the moment. I'll write another comment if I think of more.