Reusable component framework for Yammer.com
Permalink
Failed to load latest commit information.
.github Add Jesse and Brendan as approvers (#472) Jul 19, 2018
.vscode Add VSCode Jest Debug script Dec 14, 2017
assets Adding FileBug Icon (#480) Aug 23, 2018
config feat(Pivot): Support the ability to specify Pivot item sizes. (#529) Sep 12, 2018
src refactor(YamUI): Modify indentation of ChoiceGroup component to more … Sep 20, 2018
typings feat(size observer): add size observer component (#443) Jul 3, 2018
.browserslistrc Initial migration from private repo Jul 12, 2017
.dockerignore Update README files (#67) Oct 6, 2017
.eslintrc.json Add Dark Theme (#456) Jul 12, 2018
.gitignore chore: add commonjs build, for consumers that don't understand ES2015 ( May 16, 2018
.markdownlint.json Update README files (#67) Oct 6, 2017
.npmignore chore: add commonjs build, for consumers that don't understand ES2015 ( May 16, 2018
.prettierignore A few linting and dependency chores (#309) May 2, 2018
.prettierrc Update linting rules across the codebase (#283) Mar 21, 2018
.travis.yml Button and ellipsis Text line-heights (#152) Dec 13, 2017
CONTRIBUTING.md Update README files (#67) Oct 6, 2017
Dockerfile chore(docker): Get latest npm within docker image (#525) Sep 6, 2018
LICENSE Wrap lines in LICENSE (#100) Nov 6, 2017
README.md docs(readme): Fixing the asset instruction link. (#513) Aug 23, 2018
docker-compose.yml Replace Storybook with Styleguidist (#84) Nov 2, 2017
package-lock.json Release version 9.4.1 (#534) Sep 20, 2018
package.json Release version 9.4.1 (#534) Sep 20, 2018
postcss.config.js Updating MessageBar to reuse other components and reduce custom CSS (#87 Nov 8, 2017
tsconfig.commonjs.json chore: add commonjs build, for consumers that don't understand ES2015 ( May 16, 2018
tsconfig.json chore: add commonjs build, for consumers that don't understand ES2015 ( May 16, 2018
tslint.json Move all enums.ts files to types.ts (#365) Jun 4, 2018
yamui-docker Remove typescript-string-enums, and move to npm (#75) Oct 23, 2017

README.md

YamUI Travis

This is the UI component framework for Yammer.com.

It is built with React on top of Office UI Fabric components. Unit tests are run through Jest, isolated development environment and documentation is provided by Styleguidist, and visual diff regression is done with Puppeteer and pixelmatch. Visual diff tasks run within a Docker container to ensure consistency between local development environments and CI.

Using YamUI in your own app

If necessary, add YamUI to your project.

npm install --save yamui

Importing the baseline CSS

Import yamui/dist/yamui-base.css into your app. You could link to it directly before your own CSS, or import it through JS/CSS and include it at the top of your CSS bundle. This file is currently about 4kb minified+gzipped. This is a requirement as YamUI expects to own the baseline styles of the page.

Using components

You can read all documentation for our components in our living styleguide.

Each component is compiled from its TypeScript source into yamui/dist/components. This allows you to import the individual components you need and keep your bundle size smaller. Note that each component may import its own CSS and other JS dependencies so you may need to adjust your build process to accommodate.

Example importing a Button component:

import Button, { ButtonSize, ButtonColor } from 'yamui/dist/components/Button';

Example using a Button component:

<Button size={ButtonSize.SMALL} color={ButtonColor.SECONDARY} text="Click me!" />

Installation

git clone https://github.com/Microsoft/YamUI.git
cd YamUI
npm install

To run visual diff regression tests:

  • Install Docker (Docker for macOS / Docker for Windows).
  • Create an alias y in your ~/.zshrc or ~/.bashrc file for the yamui-docker executable that looks like alias y="./yamui-docker". Visual diff tasks need to run in Docker via the y alias, e.g. y run test and y run test:visual.

It's best to have at least 30GB of free space for Docker containers and images. If you find that Docker is taking up too much space, try the following:

  • View your Docker container size (on macOS): ls -lha ~/Library/Containers/com.docker.docker/Data/com.docker.driver.amd64-linux/Docker.qcow2
  • Clear space:
    • Remove all images: docker rmi $(docker images -a -q)
    • Remove all exited containers: docker rm $(docker ps -a -f status=exited -q)
    • Remove everything from disk, directly (on macOS): rm ~/Library/Containers/com.docker.docker/Data/com.docker.driver.amd64-linux/Docker.qcow2

Development

Starting up the dev server

Building some components

  • npm run create:component and provide the necessary information.
  • Tweak <ComponentName>.md file in your component's directory with usage examples. These examples are important because they document how components should be used and what options/configurations they accept. These examples will also be used in visual diff regression tests to ensure new changes are deliberate and approved before PRs are merged.
  • The dev server will pick up any changes you make to components, and automatically update the app in your browser using Hot Module Replacement.

Writing unit tests

  • npm run watch:jest will start Jest in watch mode, showing passing status and a coverage report. The CLI task remains active and will re-test automatically as you make changes.

Running visual diff regression tests

  • y run test:visual will compile the components, build+export a static version of the styleguide, start a dev server, take screenshots of each example, and fail if there are visual changes from the last approved screenshots. Unless you're developing on a Linux computer, this task must run within the Docker container via the y shortcut. Running via npm run on Mac or Windows will use your OS version of PhantomJS Webkit and will fail with subtle visual differences. Running in the Docker Linux container ensures consistent screenshots between all development environments and CI.
  • npm run test:visual:approve will approve your latest test images and overwrite the previous reference images. Use this when you are deliberately changing a component or its examples and you have manually verified that the new visual changes are correct.
  • y run test:visual:component <ComponentName> will do the same as y run test:visual, but only test the specified component. This allows for faster iterations during development.

Testing all the things

  • y run test will run all validations - linting, unit tests and visual diff regression tests. If this passes you should be all good to go.

Size limit

  • npm run size - package test component(s) with webpack and inspect file size. If the size limit is exceeded, the build will fail with Package size limit has exceeded by x KB. Configured in package.json. Add -- --why to visualize the package in the browser.

Adding icons

Releasing a new version

If you want to release a new version of YamUI, do the following to create a release branch. Replace version_type with major, minor or patch as appropriate, based on SemVer:-

git checkout -b awesome-release-branch
npm version version_type -m "Release version %s"
git push

This will add a commit that updates package.json and package-lock.json with the updated version number.

Once this branch's PR is merged to master, create a release tag, and publish the release to npm:-

# requires an npm user with permissions to release
git checkout master
git pull
npm install
npm publish

Roadmap

The YamUI project is currently in a pre-release state. We are building out the components and features we need for Yammer.com to meet our specific UX Design guidelines.

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.

When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Licenses

All files on the YamUI GitHub repository are subject to the MIT license. Please read the LICENSE file at the root of the project.

Note that we depend on Fabric for fonts. Usage of the fonts and icons referenced in YamUI is subject to the terms of the assets license agreement.