Skip to content
This repository has been archived by the owner on May 15, 2024. It is now read-only.

Latest commit

 

History

History
104 lines (73 loc) · 9.3 KB

CONTRIBUTING.md

File metadata and controls

104 lines (73 loc) · 9.3 KB
Raw

How to contribute

We welcome and appreciate pull requests from everyone.

You can participate in many ways. The documentation is available in a Git repository with the design assets needed for your project. You can get all of them, change anything and send the changes back.

Setting up

Fork, then clone the repo:

$ git clone git@github.com:your-username/WikimediaUI-Style-Guide.git

Setup your system. Change to the cloned folder and let npm package manager install needed packages. Make sure you have npm installed beforehand.

$ npm install

Make your changes. To automatically watch for changes, run:

$ npm run start

Make sure the tests pass and the CSS for production is built:

$ npm run test
$ npm run build

Get the design repository

The Wikimedia Design Style Guide repository is available to download. It contains this documentation, Sketch and SVG templates and other resources. Select the “clone or download” button to get the repository.

Commit changes

Easily contribute to the content of the style guide by adding new recommendations, making corrections or adding examples in the form of images or videos:

If you have Git installed on your system, cloning is preferred way to get the contents since it allows you to contribute back.

In order to publish the updated contents to be available live, go to the repo and launch the following command from a terminal: git push -f origin your-branch. It will be reviewed in a timely manner and merged accordingly.

Please add specific topics into a single commit, make sure that you refer to the open Github issue or Phabricator task and also take into account the Wikimedia commit message guidelines.

Push to your fork and submit a pull request

In order for the pushed changes to be available live, members of Wikimedia design review them first, provide feedback and put them on the production server as final step.

Contribute beyond content

You can also help to improve how this documentation looks and works.

When modifying aspects such as the CSS styling you'll need to rebuild the production files using Grunt (which requires Node.js and npm). The first time you have to run npm install in a terminal from the style guide's main folder in order to get all necessary dependencies. To rebuild the CSS files after changing them in wmui-style-guide.dev.css you just need to launch the grunt command in a terminal, also from the main folder.

We're using stylelint to ensure the CSS aligns with our coding conventions.

These requirements provide our contributors a reliable environment and our viewers a performant experience.

Contribute by designing or extending a component

Designing a new component or extending an existing component is an important part on Wikimedia Design Style Guide (DSG). We would like to provide a process list for a successful addition:

1. Research and prepare

A. Find any related components to the one you need. Look in these places:

  1. DSG itself,
  2. WVUI Storybook demo or former standard library OOUI demos
  3. OOUI Phabricator board with widget/component requests (40+ products using OOUI alone), or
  4. Mediawiki-interface Phabricator board.

B. File a Phabricator task with the new component request, an overview of current related components in different Wikimedia products from above and its improvements over existing components. Be sure to flag to the product owners, to make them aware of a new component – by either adding product tags on new task or referencing it on older open tasks. C. Ensure the problem statement for the addition is clear and that Design Systems Lead or Principal Designer has provided “go” for this new component or this type.

2. Design

  • Follow DSG's visual style and components guidelines to provide a consistent experience. Incorporate responsive design from the beginning.
  • Ensure different device interactions are provided. Example: Mobile vs tablet vs desktop.
  • Ensure internationalization needs and various language scripts are considered. Example: German word length or Burmese letter box height.
  • Research accessibility best-practices around the type of component to be met. Example: Ensure to think about different modes of interaction like keyboard navigation.

3. Test

  • Gather user feedback and iterate. Example: Consider reaching out to accessibility consultants on higher complex components.

4. Handover to development

5. Design quality assurance

  • Does the component behave as expected and follow the templates?
  • Does it work across required browsers, viewports, assistive technology as intended? QA engineers support needed.

6. Finalize and document

  • Add DSG's new component page or extend an existing component if it's a contextual addition as new type. Example: Thinking of different kind of menu treatment in a typeahead search vs page lists.
  • Ensure that user-interface library's demo is provided. Example: Codex documentation instance.

Contribute by designing or changing an icon

Designing a new or changing an existing icon helps to expand Wikimedia Design Style Guide icon collection and will improve user-interface consistency. It basically follows the same process as adding a component above, with small modifications:

  • Research includes comparing current icons in DSG's icon collection with an online demo available in Codex.
  • File a task on Phabricator for each icon.
  • Design with icon guidelines in mind. Ensure to incorporate feedback until open questions are resolved on task. Provide the icon as SVG in right-to-left together with left-to-right variant if needed.
  • Finalize design by
    • updating the Design System WikimediaUI Icons Figma file. Please ensure that you use Figma's “save to version history” after updating to make the changes clear to other designers using the file.
    • making a pull request with code-optimized SVG to DSG's resources folder, icon collection Zip file of whole folder with the new icon.
  • With all of above steps fulfilled, the icon will be updated in the Wikimedia user-interface libraries (at this moment Codex and OOUI) by developers.
  • Review once more on the library demo as soon as the code commit has been merged. Design Systems team is here to help in case of further questions.