We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community. Read our Code of Conduct if you haven't already.
Before you make a commit or PR, install our code check tools using npm ci and then npm run bootstrap. Run npm run lint and npm run test to see if everything is in order. Many things can be fixed automatically using npm run lint-fix. Make separate commits for separate purposes. Prefix all your commit message with fix:, feat:, docs: or any of the other allowed commit types. When you make a PR you will need to sign our Contributor License Agreement, so first check with your employer if you need to.
This projects uses the following processes:
- Required code reviews: every PR needs to be approved by (other) maintainers before it can be merged.
- Required code checks: code must match our defined code style, tests and builds need to succeed before a PR can be merged.
- Conventional Commits: commits messages should follow the specified pattern, so we can have nice things such as automatic semantic versioning and automatically generating change logs based on the commit history.
- Semantic Versioning
The project uses the following tools to automate checking and fixing code style rules:
- ESLint (rules)
- EditorConfig
- HTML-validate (rules)
- npm-package-json-lint (rules)
- markdownlint (rules)
- Prettier
- stylelint (rules)
Check of there are plugins available for your code editor of choice, to enable these tools during development. That way you won't find yourself alerted by Husky and lint-staged to fix formatting issues, just when you are about to commit your code.
For automating checks:
- Husky: automatically install Git hooks
- lint-staged - quickly run code style checks for only the files that are staged in Git
CSS is formatted using stylelint. The stylelint configuration is stored in the npm package @wesaynih.dev/stylelint-config.
ESLint is used for JavaScript checks. The ESLint configuration is stored in the npm package @wesaynih.dev/eslint-config.
JSON is formatted using Prettier.
Use the .json file extension where possible: configuration files such as .eslintrc.json have an explicit file extension and is not called simply .eslintrc to ensure all code formatting rules can be applied automatically.
Avoid code formatting in generated JSON files: files generated by tools, such as package.json that regularly updated using npm install, should be excempt from automatic formatting. Configure these files in .prettierignore.
GitHub allows the NL Design System to be maintained in the open. Hosting the content on GitHub has several benefits; all the content is freely available to everything in a central place and can accept contributions from everyone. Version control means that a full history is kept of the progress of and changes to the project. Changes can be reverted when needed.
The easiest way to work with GitHub is through the GitHub Desktop application, available for both macOS and Windows.
For both new additions and changes to existing components or documentation you first need to create a ‘branch’. A branch duplicates the ‘repository’ (all content of the project), and allows you to make changes or additions safely in isolation without impacting the rest of the project.
Once your work is finished you are able to ‘commit’ your changes first to your branch. It is important to describe as clear and concise as possible what you have changed or added in the commit message. This message will be displayed to reviewers and all other contributors of the project. A longer in-depth description message can be provided as well should it be needed.
The project uses Conventional Commits in order for commit messages to follow a consistent pattern.
Commit messages must always start with a type, for example ‘docs:’ for changes to additions to documentation. Other relevant types are ‘feat:’ for new features and ‘fix:’ for bug fixes to components. A full overview of types is available here.
docs: accessibility improvements to status badge
^--^ ^----------------------------------------^
| |
| +-> Consise, short summary
|
+-------> Type
After committing your changes to your branch you need to merge them to the main repository by clicking on the ‘Publish branch’ button. You have to make an additional ‘pull request’ to let reviewers know about your changes.
Before an addition or change is approved and added to the NL Design System it will first go through a review phase. If changes are needed, you will automatically receive an email on the address associated with your GitHub account.
The NL Design System encourages contributions from designers, copywriters, accessibilty experts and other stakeholders. There are many different ways to make a useful contribution, from the addition of (UX) documentation, new design components to fixing typing errors.
In order to contribute you must have a GitHub account.
To ensure the highest shared value, new components and documentation require an established need from at least two products. ‘One-off’ components or documentation that is not reusable should not be added to the design system.
For a component, first verify whether there is an existing component that solves a particular need or use-case.
If there is no available component or documentation, propose a new one. When proposing identify other products that share the need for the same component or documentation. The best way to do that is to add the proposed component or documentation to the backlog and discuss it in the Slack channel or during one of the NL Design System sessions.
Provide a clear description of new components or documentation or edits to existing ones. Gather requirements and identify current industry standards and best practices. If there are any usertest results that support design and documentation, provide these as well. Also investigate specific content and accessibility needs.
For components answer these additional questions:
- Which use case(s) does it cover?
- Are there similar component with comparable functionality?
- Are there specific content guidelines?
- Are there specific a11y guidelines?
- Are there variations to this component?
- Does the component have interactive states (such as hover, focus, disabled)?
- Does the component have feedback states (such as success, warning, error)?
Enhancements or changes to existing components should be discussed via the backlog. Questions and remarks regarding changes or enhancements beforehand can also be discussed via the Slack channel.
For approval of new components or documentation and edits to existing ones at least three domain experts from the community are needed. For design this means that at least three senior UX designers need to vet the proposal, for content at least three content experts, for accessibility at least three accessibility experts, and for front-end code at least three senior front-end developers.
Create design concepts, iterate, refine
Provide design rationale and any documentation needed to succesfully implement and use a component.
Documentation for a component follows the following structure:
- Description, a clear description of the component
- Variant, when a component has different variants list them here
- States, when a component has different (interactive) states list them here
- Design properties, visual design properties of a component
- Content guidelines, component-specfic conent guidelines
- Accessibility, component-specfic accessibility guidelines
- Best practices, dos and don’ts, when to use, when not to use, etc.
- References, articles, usertest results, etc.
TBD
Documentation is written in Markdown, an easy to write and read text format that can easily be converted to other formats. Markdown allows documents to be consistently formatted and structured.
GitHub uses its own ‘flavor’ of Markdown. See this list for an overview of all the formatting options allowed in documentation.
When referencing tokens they should be written between ‘backticks’ (`). This ensures tokens will be rendered as code.
Documentation supports inclusion for Figma-based components.
Details on process and workflow for this to follow.