Skip to content

Commit

Permalink
docs: readme fixes, doc site content correction and additions (#3315)
Browse files Browse the repository at this point in the history 
* doc(readme): improvements to several project readme files

* docs(fast-element): add section on working without decorators

* docs(website): various fixes to content throughout

* docs(readme): re-organize badges

* docs(readme): add back contact section

* docs(readme): add status section

* docs(fast-element): add docs on slotted/children filters

* docs: restructure toc, improve organization and urls, metadata, script

* docs: more readme consistency, content improvement, configuration update

* docs: fixing various content for consistency

* docs: add basic tools docs

* docs: revert package script dev mistake

* docs: link corrections in readmes

* doc(fast-element): add undefined element style recommendation

* docs: ensure all component explorer docs reference fast-components

* docs(readme): remove stack overflow link

* docs(match-media-stylesheets): fix edit url

* docs(faq): add answer to fast vs. fluent community question
  • Loading branch information
@EisenbergEffect
EisenbergEffect authored Jun 19, 2020
1 parent 9dcbc50 commit dda1595
Show file tree
Hide file tree
Showing 60 changed files with 989 additions and 554 deletions.
109 changes: 79 additions & 30 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,19 +3,83 @@

# FAST

An unopinionated system of components, tools, and utilities used à la carte or as a suite to build enterprise-grade websites and applications.
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![lerna](https://img.shields.io/badge/maintained%20with-lerna-cc00ff.svg)](https://lerna.js.org/)
[![TypeScript](https://img.shields.io/badge/%3C%2F%3E-TypeScript-%230074c1.svg)](http://www.typescriptlang.org/)
[![code style: prettier](https://img.shields.io/badge/code_style-prettier-f8bc45.svg)](https://github.com/prettier/prettier)

[![Maintainability](https://api.codeclimate.com/v1/badges/8a74621e634a6e9b9561/maintainability)](https://codeclimate.com/github/Microsoft/fast-dna/maintainability)
[![Test Coverage](https://api.codeclimate.com/v1/badges/8a74621e634a6e9b9561/test_coverage)](https://codeclimate.com/github/Microsoft/fast-dna/test_coverage)
![workflows](https://github.com/microsoft/fast-dna/workflows/CI%20-%20FAST/badge.svg?branch=master&event=push)
[![lerna](https://img.shields.io/badge/maintained%20with-lerna-cc00ff.svg)](https://lerna.js.org/)
[![Discord](https://img.shields.io/badge/support%20with-discord-cc00ff.svg)](https://discord.gg/FcSNfg4)
[![code style: prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat-square)](https://github.com/prettier/prettier)
![license](https://img.shields.io/github/license/mashape/apistatus.svg)

[![Discord](https://img.shields.io/badge/chat%20on-discord-7289da.svg)](https://discord.gg/FcSNfg4)
[![Twitter](https://img.shields.io/twitter/follow/fast_dna.svg?style=social&label=Follow)](https://twitter.com/intent/follow?screen_name=fast_dna)

This is the FAST monorepo, containing web component packages, tools, examples, and documentation. FAST tech can be used à la carte or as a suite to build enterprise-grade websites, applications, components, design systems, and more.

:star: We appreciate your star, it helps!

## Key features & benefits
## Introduction

FAST is a collection of JavaScript packages centered around web standards, designed to help you efficiently tackle some of the most common challenges in website and application design and development.

Have you ever needed a reusable set of UI components that you could drop into your app and have an amazing experience? _**That's FAST.**_

Have you ever needed to create your own components, and share them across your company, including across groups that use different, incompatible front-end frameworks? _**That's FAST.**_

Have you ever needed to implement a branded experience or a design language like Microsoft's Fluent UI or Google's Material Design? _**That's FAST.**_

Have you ever wanted to improve your app's startup time, render speed, or memory consumption? _**That's FAST.**_

Have you ever wanted to adopt more web standards and build your site or app on a native web foundation that's immune to the shifting sands of the modern JavaScript front-end landscape? _**That's FAST.**_

Let's take a look at what each of FAST's core packages give us today.

### fast-element

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm version](https://badge.fury.io/js/%40microsoft%2Ffast-element.svg)](https://badge.fury.io/js/%40microsoft%2Ffast-element)

The `fast-element` library is a lightweight means to easily building performant, memory-efficient, standards-compliant Web Components. FAST Elements work in every major browser and can be used in combination with any front-end framework or even without a framework. To get up and running with `fast-element` see [the Getting Started guide](http://fast.design/docs/fast-element/getting-started).

### fast-foundation

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm version](https://badge.fury.io/js/%40microsoft%2Ffast-foundation.svg)](https://badge.fury.io/js/%40microsoft%2Ffast-foundation)

The `fast-foundation` package is a library of Web Component classes, templates, and other utilities intended to be composed into registered Web Components by design systems (e.g. Fluent Design, Material Design, etc.). The exports of this package can generally be thought of as un-styled base components that implement semantic and accessible markup and behavior.

This package does not export Web Components registered as [custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) - it exports parts and pieces intended to be *composed* into Web Components, allowing you to implement your own design language by simply applying CSS styles and behaviors without having to write all the JavaScript that's involved in building production-quality component implementations.

### fast-components

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm version](https://badge.fury.io/js/%40microsoft%2Ffast-components.svg)](https://badge.fury.io/js/%40microsoft%2Ffast-components)

`fast-components` is a library of Web Components that *composes* the exports of `fast-foundation` with stylesheets aligning to the FAST design language. This composition step registers a custom element. See the [quick start](http://fast.design/components/getting-started) to get stared using the components.

### fast-components-msft

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm version](https://badge.fury.io/js/%40microsoft%2Ffast-components-msft.svg)](https://badge.fury.io/js/%40microsoft%2Ffast-components-msft)

`fast-components-msft` is another library of Web Components that *composes* `fast-foundation`. `fast-components-msft` uses the same custom element names as `fast-components`, but makes use of different stylesheets that align to the Microsoft design language.

### Component Explorer

Launch our [Component Explorer](https://explore.fast.design) to experience our [FAST Components](https://www.npmjs.com/package/@microsoft/fast-components) and development tools.

## Getting Started

If you're looking to get started using our components right away, take a look at [the components quick start](http://fast.design/docs/components/getting-started). You'll also want to check out [our integrations](http://fast.design/docs/integrations/introduction) if you're looking to add the components into a Webpack build or incorporate them with another front-end framework. For those interested in implementing their own design system or customizing the styles of the components, after you [have a look at the components](http://fast.design/docs/components/getting-started), you'll want to read through [our styling docs](http://fast.design/docs/design/introduction). Finally, if your goal is to build your own components or apps with `fast-element`, you can learn all about that in our [guide to building web components with FASTElement](http://fast.design/docs/fast-element/getting-started).

## Joining the Community

Looking to get answers to questions or engage with us in realtime? Our community is most active [on Discord](https://discord.gg/FcSNfg4). You can also ask for help on [Stack Overflow](https://stackoverflow.com/questions/tagged/fast-dna), submit requests and issues on [Github](https://github.com/Microsoft/fast-dna/issues/new/choose), or join us by contributing on [some good first issues via Github](https://github.com/Microsoft/fast-dna/labels/good%20first%20issue).

We look forward to building an amazing open source community with you!

## Features & benefits

### Unopinionated

Expand All @@ -34,36 +98,21 @@ When developing components and views, excellent development tooling can make all

Try out component properties with an auto-generated property UI, get a live preview of the code based on any property’s configuration, preview localization (RTL/LTR) and themes, and preview component compositing with a transparency grid.

Also, we built FAST development tools from re-usable packages so, if you have special needs, you can build your tools from the same shared libraries.
Also, we built FAST development tools from re-usable packages, so if you have special needs, you can build your tools from the same shared libraries.

### Bring your design system

Widely available design systems from companies like Microsoft (Fluent), Google (Material), or Salesforce (Lightning) are useful when it is essential to align with a platform or take advantage of a polished system at low cost, but many companies have their design system of their own, and some may have multiple design systems or variations.
Widely available design systems from companies like Microsoft (Fluent), Google (Material), or Salesforce (Lightning) are useful when it is essential to align with a platform or take advantage of a polished system at low cost, but many companies have a design system of their own, and some may have multiple design systems or variations.

Because FAST has abstracted base components from their style, you get a head start on your design system by building on top of tried and true base components and style libraries like our offerings for color, animation, and elevation.

## Packages

FAST is a mono repository managed with [Lerna](https://github.com/lerna/lerna). Users choose à la carte which package to use in their project.

### Component Explorer
![CD - Component Explorer](https://github.com/microsoft/fast-dna/workflows/CD%20-%20Component%20Explorer/badge.svg?branch=master&event=push)

Launch our [Component Explorer](https://explore.fast.design) to experience our [Microsoft React Components](https://github.com/microsoft/fast-dna/tree/master/packages/react/fast-components-react-msft) package and development tools.

View the [staging site](https://fast-explore-stage.azurewebsites.net/) to see unpublished changes currently staged for release in the master branch.

## Documentation

Visit our [developer documentation](https://www.fast.design/docs/en/contributing/install) to get started.

## Troubleshooting
## Contact

Experiencing problems? Check our infrastructure [health status](https://www.fast.design/docs/en/contributing/status).
* Join the community and chat with us in realtime on [Discord](https://discord.gg/FcSNfg4).
* Ask questions on [Stack Overflow](https://stackoverflow.com/questions/tagged/fast-dna).
* Submit requests and issues on [Github](https://github.com/Microsoft/fast-dna/issues/new/choose).
* Contribute by helping out on some of our recommended first issues on [Github](https://github.com/Microsoft/fast-dna/labels/good%20first%20issue).

## Contact
## Status

* Join the community on [Discord](https://discord.gg/FcSNfg4).
* Ask for help on [Stack Overflow](https://stackoverflow.com/questions/tagged/fast-dna).
* Submit requests and issues on [Github](https://github.com/Microsoft/fast-dna/issues/new/choose).
* Contributors, find good first issues on [Github](https://github.com/Microsoft/fast-dna/labels/good%20first%20issue).
Experiencing problems with our site? Check our infrastructure [health status](https://www.fast.design/docs/en/contributing/status) and feel free to contact us through the channels listed above.
8 changes: 8 additions & 0 deletions packages/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
# FAST Packages

FAST is organized as a monorepo and this is where you'll find the packages we publish.

* `web-components` - Packages that are directly related to web component technologies. This includes tech for building components, our components library, and our design system implementations.
* `utilities` - General purpose packages useful in creating web apps and sites. This includes tech for colors, animation, linting,e tc.
* `tooling` - Packages that contain design and prototyping tools.
* `react` - Legacy React component which predate the modern web component work.
33 changes: 33 additions & 0 deletions packages/web-components/README.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,33 @@
# Web Components

Our web component packages.

## fast-element

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm version](https://badge.fury.io/js/%40microsoft%2Ffast-element.svg)](https://badge.fury.io/js/%40microsoft%2Ffast-element)

The `fast-element` library is a lightweight means to easily building performant, memory-efficient, standards-compliant Web Components. FAST Elements work in every major browser and can be used in combination with any front-end framework or even without a framework. To get up and running with `fast-element` see [the Getting Started guide](http://fast.design/docs/fast-element/getting-started).

## fast-foundation

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm version](https://badge.fury.io/js/%40microsoft%2Ffast-foundation.svg)](https://badge.fury.io/js/%40microsoft%2Ffast-foundation)

The `fast-foundation` package is a library of Web Component classes, templates, and other utilities intended to be composed into registered Web Components by design systems (e.g. Fluent Design, Material Design, etc.). The exports of this package can generally be thought of as un-styled base components that implement semantic and accessible markup and behavior.

This package does not export Web Components registered as [custom elements](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) - it exports parts and pieces intended to be *composed* into Web Components, allowing you to implement your own design language by simply applying CSS styles and behaviors without having to write all the JavaScript that's involved in building production-quality component implementations.

## fast-components

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm version](https://badge.fury.io/js/%40microsoft%2Ffast-components.svg)](https://badge.fury.io/js/%40microsoft%2Ffast-components)

`fast-components` is a library of Web Components that *composes* the exports of `fast-foundation` with stylesheets aligning to the FAST design language. This composition step registers a custom element. See the [quick start](http://fast.design/components/getting-started) to get stared using the components.

## fast-components-msft

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm version](https://badge.fury.io/js/%40microsoft%2Ffast-components-msft.svg)](https://badge.fury.io/js/%40microsoft%2Ffast-components-msft)

`fast-components-msft` is another library of Web Components that *composes* `fast-foundation`. `fast-components-msft` uses the same custom element names as `fast-components`, but makes use of different stylesheets that align to the Microsoft design language.
47 changes: 45 additions & 2 deletions packages/web-components/fast-components-msft/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,53 @@
# FAST Components MSFT

A set of React components which implements the Microsoft styling.
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm version](https://badge.fury.io/js/%40microsoft%2Ffast-components-msft.svg)](https://badge.fury.io/js/%40microsoft%2Ffast-components-msft)

`fast-components-msft` is another library of Web Components that *composes* `fast-foundation`. `fast-components-msft` uses the same custom element names as `fast-components`, but makes use of different stylesheets that align to the Microsoft design language.

## Installation

`npm i --save @microsoft/fast-components-msft`
### From NPM

To install the `fast-components-msft` library, use either `npm` or `yarn` as follows:

```shell
npm install --save @microsoft/fast-components-msft
```

```shell
yarn add @microsoft/fast-components-msft
```

Within your JavaScript or TypeScript code, you can then import library APIs like this:

```ts
import { FASTAnchor } from '@microsoft/fast-components-msft';
```

Looking for a setup that integrates with a particular front-end framework or bundler? Check out [our integration docs](http://fast.design/docs/integrations/introduction).

### From CDN

A pre-bundled script that contains all APIs needed to use FAST Foundation is available on CDN. You can use this script by adding [`type="module"`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) to the script element and then importing from the CDN.

```html
<!DOCTYPE html>
<html lang="en">
<head>
<script type="module" src="https://unpkg.com/@microsoft/fast-components-msft">
</head>
<!-- ... -->
</html>
```
The above CDN location points to the latest release of `fast-components`. It is advised that when you deploy your site or app, you import the specific version you have developed and tested with.
For simplicity, examples throughout the documentation will assume the library has been installed from NPM, but you can always replace the import location with the CDN URL.
## Development
To start the component development environment, run `yarn start`.
### Known issue with Storybook site hot-reloading during development
Expand Down
45 changes: 45 additions & 0 deletions packages/web-components/fast-components/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,50 @@
# FAST Components

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm version](https://badge.fury.io/js/%40microsoft%2Ffast-components.svg)](https://badge.fury.io/js/%40microsoft%2Ffast-components)

`fast-components` is a library of Web Components that *composes* the exports of `fast-foundation` with stylesheets aligning to the FAST design language. This composition step registers a custom element. See the [quick start](http://fast.design/components/getting-started) to get started using the components.

## Installation

### From NPM

To install the `fast-components` library, use either `npm` or `yarn` as follows:

```shell
npm install --save @microsoft/fast-components
```

```shell
yarn add @microsoft/fast-components
```

Within your JavaScript or TypeScript code, you can then import library APIs like this:

```ts
import { FASTAnchor } from '@microsoft/fast-components';
```

Looking for a setup that integrates with a particular front-end framework or bundler? Check out [our integration docs](http://fast.design/docs/integrations/introduction).

### From CDN

A pre-bundled script that contains all APIs needed to use FAST Foundation is available on CDN. You can use this script by adding [`type="module"`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) to the script element and then importing from the CDN.

```html
<!DOCTYPE html>
<html lang="en">
<head>
<script type="module" src="https://unpkg.com/@microsoft/fast-components">
</head>
<!-- ... -->
</html>
```
The above CDN location points to the latest release of `fast-components`. It is advised that when you deploy your site or app, you import the specific version you have developed and tested with.
For simplicity, examples throughout the documentation will assume the library has been installed from NPM, but you can always replace the import location with the CDN URL.
## Development
To start the component development environment, run `yarn start`.
Expand Down
2 changes: 1 addition & 1 deletion ...s/fast-components/docs/guide/color.doc.md → ...ents/fast-components/docs/design/color.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
id: color
title: Color
custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-components/fast-components/docs/guide/color.doc.md
custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-components/fast-components/docs/design/color.md
---

FAST utilizes an adaptive color system that provides some unique advantages:
Expand Down
2 changes: 1 addition & 1 deletion ...omponents/docs/guide/design-system.doc.md → ...t-components/docs/design/design-system.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
id: design-system
title: Design System
custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-components/fast-components/docs/guide/design-system.doc.md
custom_edit_url: https://github.com/microsoft/fast-dna/edit/master/packages/web-components/fast-components/docs/design/design-system.md
---

In FAST, the *design system* is a collection of properties and values that inform the visual design language of the components. These properties are managed and provided through implementations of the [*DesignSystemProvider*](fast-foundation/fast-design-system-provider.md).
Expand Down
Loading

0 comments on commit dda1595

Please sign in to comment.