From 4b6e9a4e5131a2ccbdd3eb5ebb5c3f4e165464d3 Mon Sep 17 00:00:00 2001 From: Chris Holt Date: Fri, 6 Dec 2019 10:49:21 -0800 Subject: [PATCH] chore: add getting started documentation (#2478) * chore: add getting started documentation * add link to react context, fix spelling and example syntax * add working with jss blurb and example --- docs/en/getting-started/design-system.md | 31 +++++++++ docs/en/getting-started/jss.md | 20 ++++++ .../getting-started/modifying-components.md | 67 ++++++++++++++++++ docs/en/getting-started/the-basics.md | 68 +++++++++++++++++++ docs/en/getting-started/utilities.md | 10 +++ website/sidebars.json | 7 ++ 6 files changed, 203 insertions(+) create mode 100644 docs/en/getting-started/design-system.md create mode 100644 docs/en/getting-started/jss.md create mode 100644 docs/en/getting-started/modifying-components.md create mode 100644 docs/en/getting-started/the-basics.md create mode 100644 docs/en/getting-started/utilities.md diff --git a/docs/en/getting-started/design-system.md b/docs/en/getting-started/design-system.md new file mode 100644 index 000000000..384721e3e --- /dev/null +++ b/docs/en/getting-started/design-system.md @@ -0,0 +1,31 @@ +--- +id: design-system +title: Design system +sidebar_label: Design system +--- + +# Design System + +## Working with the design system provider +The `DesignSystemProvider` is a React component that provides, via [React context](https://reactjs.org/docs/context.html), the *design-system* object to descendent context consumers. + +It accepts a `designSystem` property: +```jsx + + /* children */ + +``` + +The `DesignSystemProvider` is designed to apply scoped changes to the *design-system* object, so it will merge the applied *design-system* with any upstream *design-system* object: + +```jsx + + /* Stylesheet generated with {backgroundColor: "#FFF", density: 3} */ + I'm a styled button + + + /* Stylesheet generated with {backgroundColor: "#AAA", density: 3} */ + I'm another styled button + + +``` \ No newline at end of file diff --git a/docs/en/getting-started/jss.md b/docs/en/getting-started/jss.md new file mode 100644 index 000000000..aacdac5a8 --- /dev/null +++ b/docs/en/getting-started/jss.md @@ -0,0 +1,20 @@ +--- +id: jss +title: JSS (JavaScript Style Sheets) +sidebar_label: JSS (JavaScript Style Sheets) +--- + +# Working with JSS +For info on how to write JSS stylesheets, visit [https://cssinjs.org/jss-syntax?v=v10.0.0](https://cssinjs.org/jss-syntax?v=v10.0.0) + +## Accessing the design system in JSS +The `JSSManager` allows us to access the current contextual design system by assigning a function value to a JSS rule. The only argument to this callback will be the current design system. For more information on the providing a design system object to the styles, see the documentation for [fast-jss-manager-react](https://www.fast.design/docs/en/packages/fast-jss-manager-react/). + +```js +// This code assumes a property `backgroundProperty` exists on the design system +const styles = { + button: { + backgroundColor: (designSystem) => designSystem.backgroundColor + } +} +``` \ No newline at end of file diff --git a/docs/en/getting-started/modifying-components.md b/docs/en/getting-started/modifying-components.md new file mode 100644 index 000000000..fde44222f --- /dev/null +++ b/docs/en/getting-started/modifying-components.md @@ -0,0 +1,67 @@ +--- +id: modifying-components +title: Modifying components +sidebar_label: Modifying components +--- + +# Modifying components + +## Using Props + +Each component will have its own set of [props](https://reactjs.org/docs/components-and-props.html#rendering-a-component) corresponding to the functionality needed for that component. + +```jsx + + Hello World + +``` +## Unhandled props +FAST components implement a model of props know as *handled* and *unhandled* props. *Handled* props can be thought of as first-class props explicitly used or expected by the component. *Unhandled* props are all other props. In general, all *unhandled* props will be passed along to the root element of the component, and are generally used to address instance accessibility requirements, custom event listeners, and add telemetry meta-data. + +```jsx +/* + * aria-label is an unhandled prop, so it gets + * applied to the root of the Button component + */ + + Hello world + +``` + +## Changing style + +### Using classes +```jsx + + Hello World + +``` + +### Using props +Instance style overrides can be applied using the `jssStyleSheet` property and targetting properties of the [class-name contract](#class-name-contracts). + +```jsx +let styles = { + button: { + margin: "0 auto" + } +}; + + + Hello World + +``` + +### Using inline-styles +Additionally, you can always use inline-styles. This will be treated as a *unhandled* prop and +applied to the root element of the component. + +```jsx + + Hello World + +``` diff --git a/docs/en/getting-started/the-basics.md b/docs/en/getting-started/the-basics.md new file mode 100644 index 000000000..ffae8bde3 --- /dev/null +++ b/docs/en/getting-started/the-basics.md @@ -0,0 +1,68 @@ +--- +id: the-basics +title: The basics +sidebar_label: The basics +--- + +# The basics + +This document assumes a basic understanding of React. If you're unfamiliar, please read [React's getting started](https://reactjs.org/docs/getting-started.html) documentation first. + +## Add a component to your page + + +An easy way to get started with FAST styled components is the `@microsoft/fast-components-react-msft` package which conforms to Microsoft style guidance. + +To use a styled component, simply import it from the package: + +```jsx +import { AccentButton } from "@microsoft/fast-components-react-msft"; +``` +And add the component to your markup: +```jsx +function render() { + return Hello world +} +``` + +A full list of these components and their documentation can be found [here](https://explore.fast.design/). + +--- + +## Core concepts + +### Base components +At the heart of the FAST component system are *base* components. *Base* components are general purpose, unstyled React components designed to meet semantic and accessability requirements for common UI patterns. In general, *base* components implement [*roles*](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/ARIA_Techniques) from the ARIA specification. + +### Styled components +Styled components are implementations of the base components coupled with CSS styles to achieve visual design requirements. These can either be a simple styling layer over the *base* component, or components that extend *base* components with additional functionality or convenience features. These components tend to be more opinionated due the the nature of design implementation. + +### Class name contracts +Each base component implements a *class-name contract* - an enumeration and implementation of all classes used by the component. Simple components such as `Hyperlink` may only expose a single class name in the *class-name contract*. More complicated components such as `Breadcrumb` will have multiple class names and will apply them to the appropriate elements. For instance, the `Breadcrumb` component implements the following *class-name contract*: + +```typescript +interface BreadcrumbClassNameContract { + breadcrumb: string; // Applied to the root of the component + breadcrumb_item: string; // Applied to each breadcrumb item + breadcrumb_item__current: string; // Applied to the item representing the location in the breadcrumb + breadcrumb_itemsContainer: string; // Applied to the container of all the breadcrumb items + breadcrumb_separator: string; // Applied to the element representing the separator of the breadcrumb items +} +``` + +When the base component renders, it will apply classes to elements from the *class-name contract* properties of the `managedClasses` prop: + +```jsx +// Inside the Breadcrumb render function +
+
+ /* ...etc */ +
+
+``` + +#### How are components styled? +Base components are styled using [JSS](https://cssinjs.org/?v=v10.0.0) - a tool for generating stylesheets from JavaScript objects. Each JSS stylesheet conforms the the class-name contract defined by the component. [@microsoft/fast-jss-manager-react](https://github.com/microsoft/fast-dna/tree/master/packages/fast-jss-manager-react) is used to compose a component stylesheet with a base component, and will manage CSS creation, update, and removal processes during the component lifecycle. + +#### What is the design system? +The *design-system* is all of the design data - it captures design thinking into a configuration object that informs components how to render. This can include information about color, font-weights, UI density, motion, and more. In practice, this object is provided to JSS stylesheets so that the resulting CSS is a product of the *design-system*. diff --git a/docs/en/getting-started/utilities.md b/docs/en/getting-started/utilities.md new file mode 100644 index 000000000..6ab6feb40 --- /dev/null +++ b/docs/en/getting-started/utilities.md @@ -0,0 +1,10 @@ +--- +id: utilities +title: Utilities +sidebar_label: Utilities +--- + +# Utilities +FAST has two utility libraries for common operations: +1. [https://github.com/microsoft/fast-dna/tree/master/packages/fast-web-utilities](@microsoft/fast-web-utilities) contains general-purpose JavaScript utilities +2. [https://github.com/microsoft/fast-dna/tree/master/packages/fast-jss-utilities](@microsoft/fast-jss-utilities) are utilities intended to be used in JSS stylesheets \ No newline at end of file diff --git a/website/sidebars.json b/website/sidebars.json index 3c842d14d..049fb82d4 100644 --- a/website/sidebars.json +++ b/website/sidebars.json @@ -1,5 +1,12 @@ { "docs": { + "Getting started": [ + "en/getting-started/the-basics", + "en/getting-started/modifying-components", + "en/getting-started/design-system", + "en/getting-started/jss", + "en/getting-started/utilities" + ], "Contributing": [ "en/contributing/install", "en/contributing/working",