design-system icon indicating copy to clipboard operation
design-system copied to clipboard

Various feedback for README.md

Open elisechant opened this issue 5 years ago • 1 comments

  1. It would be helpful to clarify what is the point of this repo? Is it for documenting high level concepts or for building a design system in code?

  2. I like the concept (state) => ({ styles, view }), as it makes views also composable, meaning we can could technically build a functional design system without any UI and call that 1.0.0. This might be a good way to start the system, but also useful for flexibility of a styled system in the future.

  3. General readability suggestions:

  • Include Thinkmill's logo and branding at the top of the README
  • Terminology items should be hash links to their navigable heading
  • Where you reference other content such as "State management", why don't you simplify this repo by linking out to that instead of duplicating information to here? State management is not strictly a design system concern. Leave this documentation for design system concerns.
  1. I can see this is early days, but you seem to be missing whole sections like Testing, Types, Type Concepts, Component Inheritance, How to add a component.

elisechant avatar Sep 20 '19 20:09 elisechant

Thanks @elisechant, this is fantastic; and thanks again for engaging 🎉 I'll go through these by bullet point:

  1. Agreed, we'll this to the intro
  2. The ability to build / abstract out the pure functional aspects of a design system has been something we've been exploring for a while now (since October last year i believe), and is very much the inspiration behind DSF (and the above representation of UI). Happy to have a chat with you around this, as I know you're keen to explore this space too.
  3. This is all great, and yes the intention is not to double up on state management content here, but to link out to existing resources where appropriate. We want to include a state management section in the guide so that we capture the state management concepts that are important and also unique to our thinking around design systems.
  4. Thanks for bringing this up, especially Testing

Thanks again for the feedback! Also feel free to submit a PR, definitely keen to collaborate with as many people as possible as we build and refine this guide 🙌

gwyneplaine avatar Sep 24 '19 01:09 gwyneplaine