Fast: doc(design): re-work the design system documentation

[EisenbergEffect]

At present, our documentation related to design systems is fairly adhoc. Over the last few weeks we've seen more and more community members coming to FAST who have had trouble figuring out how to accomplish design-system-related tasks. We should lift the "Design" docs out from under "Components" into a top level section in our ToC. Tentative name: "Working with Design Systems". We should plan out a more cohesive and comprehensive content strategy for this section which will walk our customers through the following three primary scenarios:

• Configuring the FAST Frame design system for use in an app
• Creating a new component that leverages a design system
• Creating a new design system from scratch

[ben-girardet]

I totally agree that better doc around design system would be highly beneficial. In my experience trying to use FAST and tweak it, that's definitely where I struggled the most. Thanks for looking into this.

I also thing that the 3 scenarios suggested above are very helpful 👍

Below are a few feedbacks, linked to my short experience with FAST so far:

In the effort for improving design system doc I would like to suggest to include recipes and css behaviors. Especially for scenario 2 (leveraging a design system). I still struggle to grasp the concept of CSS behaviors. Some questions (for me) are:

• How do they actually work ? I see exemples from existing components, but it still seems a little "magical".
• How can I create a behavior ? Should I create more behavior if needed ? Inside a design system or do I need to create a new design system if I need more behavior ?
• For FAST design system: it would help to have more exemples (or better explanation) around which behavior/custom prop should be used in which context. The list on the color page is a good start. Surely some visual exemples would help a lot.

And as a personal feedback, it took me quite a bit of time to understand that components are closely coupled with its design system. At first, reading the doc I thought that it could be just easy to create components (for exemple my-icon) and use them with one design system or with another design system (FAST, Fluent, Material, ...). After experimenting a little I came to the understanding that each design system must provide its own set of supported components. Of course they can leverage foundation (for those related to foundation components), but for custom components developed by consumers not so. Maybe this could be a little more clear from the beginning.

And more importantly: thanks for building FAST. Looks very promising 🥇

[nicholasrice]

Thanks for the feedback @ben-girardet! @litteredwitherrors and I took a stab at an outline for Design System documentation that I believe will address the questions you have / had as well as those highlighted by @EisenbergEffect. As always, feedback is welcomed and this can be expanded and shuffled as necessary to be more intuitive.

Outline

Overview

• What is the Design System?
  
  
  
  • Answers the question "What is a Design System in FAST and what is it for?"
  
  
  • Captures information about UX design
    
    
    
    
    
    • Colors
    
    
    
    • Fonts and font sizes
    
    
    
    • Motion
    
    
    
    • Contrast preferences
    
    
    
    • UI density
    
    
    
    • etc...
    
    
    
  
  
  • Stores Design Tokens
  
  
• How is the Design System used?
  
  
  
  • Values represented as CSS custom properties
  
  
  • Values represented as a JavaScript object
    
    
    
    
    
    • Can be used for programmatic calculation. See "Using design system resolvers"
    
    
    
  
  
  • Provided to components by a DesignSystemProvider
  
  
• What is the DesignSystemProvider?
  
  
  
  • HTML element
  
  
  • Creates CSS custom properties for Design System values
  
  
  • Propogates Design System JavaScript object to descendent elements
  
  
  • Resovles functions of the Design System to CSS custom properties
    
    
    
    
    
    • See color recipes
    
    
    
  
  
  • use-defaults explained
  
  
  • Explain "Adaptive UI"
  
  
  • Describe property inheritance through document structure
  
  
  • Using the DesignSystemProvider to configure and change the Design System
  
  

FAST Frame Design System

• What is FAST Frame
  
  
  
  • A design system implementation of FAST Foundation.
  
  
• Comprehensive properties table with definitions and CSS custom property names (if applicable)
  
  
  
  • Included use cases of properties
  
  
  • Show examples where appropriate
  
  
• Configuring the FAST Frame Design System
  
  
  
  • Setting value driven by content property
  
  
  • Setting value driven by IDL property
  
  
  • Coordinating color palettes and base colors
  
  
• Extending the FAST Frame Design System
  
  
  
  • Create a new DesignSystemProvider that extends FASTDesignSystemProvider
  
  
  • Declare new Design System properties
  
  
  • Use element in HTML
  
  

Using the FAST Design System in a component stylesheet

• Using design system CSS custom properties
• Using design system resolvers (CSS custom property behaviors, conditional CSS, etc)
  
  
  
  • List the available Design System resolvers
  
  
• How to create a Design System resolver.
  
  
  
  • When is this useful?
    
    
    
    
    
    • Adaptive color
    
    
    
    • Directional stylesheets
    
    
    
  
  

Creating a new Design System

• Defining a DesignSystemProvider custom element
• Defining Design System properties
  
  
  
  • default value
  
  
  • CSS custom property name
  
  
  • Common uses (design token)
  
  
  • Other uses (font assets?)
  
  

[litteredwitherrors]

As @nicholasrice and I were working on this, it became apparent to me that referring to the properties and values available in the DesignSystemProvider as the _design system_ can be a bit confusing and somewhere misleading. Especially when we also use the term to describe FAST Frame Components.

While there is no standard as to what makes up a "Design System", the industry does reflect that a design system encompasses more than just properties and values. Properties and values on their own are typically referred to as "design tokens" which are an expression of a visual design language.

I propose that we open the discussion of the use of the term "Design System" in the FAST ecosystem as to create clear definitions that mirrors what is found in the industry.

[EisenbergEffect]

@litteredwitherrors Great feedback! We can start by adding entries for "Design System" and "Design Token" to our glossary document. We can also do a pass across our docs to use these terms consistently and deep link to the new glossary entries.

[litteredwitherrors]

@EisenbergEffect Sounds good. I'll make an issue.