diff --git a/src/data/nav-items.yaml b/src/data/nav-items.yaml index bbc46488a58..b8ab6946b86 100644 --- a/src/data/nav-items.yaml +++ b/src/data/nav-items.yaml @@ -51,20 +51,12 @@ pages: - title: Get started path: /contributing/get-started/ - - title: Bugs and requests - path: /contributing/bugs-and-requests/ + - title: Code + path: /contributing/code/ + - title: Design + path: /contributing/design/ - title: Documentation path: /contributing/documentation/ - - title: Components - path: /contributing/component/ - - title: Icons - path: /contributing/contribute-icons/ - - title: Patterns - path: /contributing/pattern/ - - title: Pictograms - path: /contributing/contribute-pictograms/ - - title: Add ons - path: /contributing/add-ons/ - title: Migrating pages: - title: Guide diff --git a/src/pages/contributing/add-ons.mdx b/src/pages/contributing/add-ons.mdx deleted file mode 100644 index 47485d99144..00000000000 --- a/src/pages/contributing/add-ons.mdx +++ /dev/null @@ -1,49 +0,0 @@ ---- -title: Add-ons -description: - Carbon add-ons contain components, tools, and guidance that extend Carbon for - a specific product or experience. ---- - -import { CheckmarkFilled } from '@carbon/icons-react'; - - - -Carbon add-ons -Contributing to add-ons -Ownership and maintenance - - - -## Carbon add-ons - -Carbon add-ons contain components, tools, and guidance that extend Carbon for a -specific product or experience. Add-ons enable teams to create their own custom -patterns and components that follow Carbon's visual style and guidelines. - -If your team is using Carbon and needs components specific to your product or -industry, you should create a Carbon add-on. - -If you feel that your components and/or patterns could be used in other -products, we encourage you to [contribute](/contributing/overview) your work -back to Carbon. - -### Private vs public - -The Carbon Design System is an open-source project and we encourage teams using -Carbon Design System to stay open-source as well. If your product has privacy -constraints, there are options for creating an add-on repo under our GitHub -Enterprise account. - -## Contributing to add-ons - -Add-ons are generally easier to contribute to because they are not fully managed -by the Carbon team. For your add-on to be accepted, your components must meet -WCAG AA standards and include interaction states (hover, active, focus, and -disabled). - -## Ownership and maintenance - -If you build an add-on repo, it's your responsibility to maintain it. This -involves carrying over changes from the core Carbon repo, as well as making sure -it is using the latest major version of Carbon. diff --git a/src/pages/contributing/bugs-and-requests.mdx b/src/pages/contributing/bugs-and-requests.mdx deleted file mode 100644 index 81bcc4752e6..00000000000 --- a/src/pages/contributing/bugs-and-requests.mdx +++ /dev/null @@ -1,68 +0,0 @@ ---- -title: Bugs and requests -description: - Carbon tracks bugs and issues with GitHub. If you have a bug to report or wish - to request a new feature, please check our existing issues before opening a - new one. ---- - - - -Checking for known issues -Creating an issue -Requests for comment -Need more help? - - - -## Checking for known issues - -### GitHub - -We use GitHub to track our bugs. If you have a bug to report or wish to request -a new feature, please check the -[existing issues](https://github.com/carbon-design-system/carbon/issues) before -opening a new one. There may already be something similar in the works. - -### Carbon website - -Please take some time to explore the content on this website before opening an -issue. The site is comprehensive and most guidelines and components are well -documented. - -## Creating an issue - -### GitHub issues - -Report bugs, request features, and leave feedback with a GitHub issue. If you're -unsure which repo to use, please open an issue in the -[Carbon monorepo](https://github.com/carbon-design-system/carbon). - -#### Carbon repos - -- [Carbon website](https://github.com/carbon-design-system/carbon-website/issues/new/choose) -- [Carbon monorepo](https://github.com/carbon-design-system/carbon) -- [Carbon Angular](https://github.com/IBM/carbon-components-angular/issues/new) -- [Carbon Vue](https://github.com/carbon-design-system/carbon-components-vue/issues/new) -- [Carbon charts (beta)](https://github.com/carbon-design-system/carbon-charts/issues/new) -- [Carbon design kit](https://github.com/carbon-design-system/carbon-design-kit/issues/new) -- [Carbon icons](https://github.com/carbon-design-system/carbon-icons/issues/new) - -### GitHub pull requests - -If you have a specific fix or contribution, start by generating a pull request -in the appropriate [Carbon repo](/developing/dev-resources#github-repos). Here -are detailed -[instructions](https://github.com/carbon-design-system/carbon-website/wiki/Creating-a-PR-through-github.com-UI) -for forking the repo and opening a pull request. - -## Requests for comment - -For changes that are larger in scale, an RFC (request for comment) may be -appropriate. Read more about our -[RFC process](https://github.com/carbon-design-system/rfcs). - -## Need more help? - -If you have more questions about issues or requesting features, there are -multiple ways to reach us at [Contact us](/help/contact-us). diff --git a/src/pages/contributing/code.mdx b/src/pages/contributing/code.mdx new file mode 100644 index 00000000000..ac2adb7622b --- /dev/null +++ b/src/pages/contributing/code.mdx @@ -0,0 +1,110 @@ +--- +title: Code +description: + Code contributions can include anything from squashing bugs to adding feature + requests. Check out the instructions below to contribute code effectively. +--- + +export const Title = () => Contribute code; + + + +Code contributions can include anything from squashing bugs to adding feature +requests. Check out the instructions below to contribute code effectively. + + + + + +Step 1: Find a project +Step 2: Set up your environment +Step 3: Refine the issue +Step 4: Get feedback + + + +## Step 1: Find a project + +New issues submitted by the community are initially triaged by Carbon team +members. Any issue that the Carbon team accepts, but can not fit in their +roadmap, is open for community contribution. + +#### Volunteer for existing work + +The best way to volunteer is to look through +[existing GitHub issues](https://github.com/carbon-design-system/carbon/issues?q=is%3Aopen+is%3Aissue+label%3A%22needs%3A+community+contribution%22+) +labeled with `needs: community contribution`. Any issue labeled with +`needs: code contribution` is fair game! Put a comment in the issue saying you'd +like to help. + + + +If you want to join an issue that is already assigned to someone or has a +specific milestone, please discuss with the assignee of the issue or with the +Carbon team to coordinate. + +Issues labeled `good first issue` are great candidates to pick up if you are in +the code for the first time. The Carbon team is also happy to help you. Just +stop by our [Carbon Developer office hours](/whats-happening/meetups/) or +[contact us](/help/contact-us/) directly. + +#### Submit an idea or bug report + +Have a new idea that you think would benefit Carbon? Or do you need to report a +bug? First, be sure to look through the +[issue backlog](https://github.com/carbon-design-system/carbon/issues) to make +sure it is a novel idea or bug. Then, file your proposal on GitHub using the +[issue templates](https://github.com/carbon-design-system/carbon/issues/new/choose). +If you're willing to work on this idea yourself, be sure to let us know in your +issue! Your idea will then go through a triage process by the Carbon team. + +## Step 2: Set up your environment + +[Follow these steps](https://github.com/carbon-design-system/carbon/blob/main/.github/CONTRIBUTING.md) +to install the tools, set up your environment, and learn how to make a pull +request. You can explore all the repositories in the Carbon Design system +[here](https://github.com/carbon-design-system), but you will likely be working +in one of the following: + +- [Carbon website](https://github.com/carbon-design-system/carbon-website/) +- [Carbon monorepo](https://github.com/carbon-design-system/carbon) +- [Carbon Angular](https://github.com/IBM/carbon-components-angular/) +- [Carbon Vue](https://github.com/carbon-design-system/carbon-components-vue/) +- [Carbon charts](https://github.com/carbon-design-system/carbon-charts/) + +If you need help troubleshooting, [reach out](/help/contact-us/) to the Carbon +team. + +## Step 3: Refine the issue + +Your dev environment is set up and you might be tempted to jump into coding. +Before you get started, we recommend you refine the issue by creating a rough +task list and posting it in the issue comments. + +If you have trouble answering any of these questions, reach out to the Carbon +team and we will help you refine your issue: + +- Am I clear on the scope of this work? +- Is this task list feasible for me to do? +- Should a designer get involved to do initial research or create a design spec? +- Do I need to collaborate with anyone else? + +## Step 4: Get feedback + +Most contributors work in groups of 2-3 and either set up weekly sessions or +join [meetups](/whats-happening/meetups/#carbon-office-hours) such as the Data +Viz Guild or Carbon Developer office hours. In these sessions, it is common to +share work in progress and ask lots of questions. As you make progress, update +your GitHub issue. + +Work that results in code will be reviewed directly in a pull request. +Maintainers will be reviewing your work and making comments, asking questions +and suggesting changes to be made before they merge your code. When you need to +make a change, commit and push to your branch normally. Once all revisions to +your pull request are complete, a maintainer will squash and merge your commits +for you. diff --git a/src/pages/contributing/component/images/content-switcher-style-1.png b/src/pages/contributing/component/images/content-switcher-style-1.png deleted file mode 100644 index d79f8c22582..00000000000 Binary files a/src/pages/contributing/component/images/content-switcher-style-1.png and /dev/null differ diff --git a/src/pages/contributing/component/images/contribution-iconography-pictogram.png b/src/pages/contributing/component/images/contribution-iconography-pictogram.png deleted file mode 100644 index 4e4002a9a7e..00000000000 Binary files a/src/pages/contributing/component/images/contribution-iconography-pictogram.png and /dev/null differ diff --git a/src/pages/contributing/component/images/spec.png b/src/pages/contributing/component/images/spec.png deleted file mode 100644 index 5e08409d603..00000000000 Binary files a/src/pages/contributing/component/images/spec.png and /dev/null differ diff --git a/src/pages/contributing/component/index.mdx b/src/pages/contributing/component/index.mdx deleted file mode 100644 index 69c3d330d02..00000000000 --- a/src/pages/contributing/component/index.mdx +++ /dev/null @@ -1,1093 +0,0 @@ ---- -title: Components -description: - Component contributions can take several forms. Most are either component - enhancements or brand new assets. ---- - - - -Component contributions can take several forms. Most are either component -enhancements or brand new assets. - - - - - How to write component guidance - Parts of a component contribution - First steps to contributing - - - -## How to write component guidance - -Our component usage documentation typically contains three parts: usage -guidance, style guidance, and code guidance. Some components are more complex -than others but you should cover each topic included in these templates. - -### Usage template: for components with one variant - -The usage template helps describe when to use a component and how it works. You -can see this template in use for components with only one variant: -[Accordion](/components/accordion/usage) and -[Checkbox](/components/checkbox/usage). - -```markdown ---- -title: Component name -description: Explains what the component is in one or two sentences. -tabs: ['Usage', 'Style', 'Code', 'Accessibility'] ---- - - - - - - - - - -Overview Live demo -Formatting Content -Behaviors Modifiers -Related References -Feedback - - - -## Overview - - - -### When to use - - - -### When not to use (optional) - - - -## Live demo - - - -## Formatting - -### Anatomy - - - -### Sizing (optional) - - - -### Alignment (optional) - - - -### Placement - - - -## Content - -### Main elements - - - -### Overflow content - - - -### Further guidance - - - -## Behaviors - - - -### States - - - -### Interactions - - - -### Validation - - - -### Responsive behavior - - - -### Default selection - - - -### Clickable areas - - - -### Loading - - - -## Modifiers - - - -## Related - - - -## References - - - -## Feedback - - - -Help us improve this component by providing feedback, asking questions, and -leaving any other comments on -[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md). -``` - -### Usage template: for components with multiple variants - -Use this template for documenting components that have multiple types or -variants. You can see this template in use for -[Dropdown](/components/dropdown/usage), [Modal](/components/modal/usage), and -[Notification](/components/notification/usage). - -```markdown ---- -title: Component name -description: Explains what the component is in one or two sentences. -tabs: ['Usage', 'Style', 'Code', 'Accessibility'] ---- - - - - - - - - - -Overview Live demo -Formatting Content -Universal behaviors Component type -name Modifiers -Related References -Feedback - - - -## Overview - - - -### When to use - - - -### When not to use (optional) - - - -### Types - - - -## Live demo - - - -## Formatting - - - -### Sizing (optional) - - - -### Alignment (optional) - - - -### Placement - - - -## Content - -### Main elements - - - -### Overflow content (optional) - - - -### Further guidance - -For further content guidance, see Carbon's -[content guidelines](<[https://www.carbondesignsystem.com/guidelines/content/general](https://www.carbondesignsystem.com/guidelines/content/general)>). - -## Universal behaviors - - - -### States - - - -### Interactions - - - -### Validation - - - -### Responsive behavior - - - -### Default selection - - - -### Clickable areas - - - -### Loading - - - -## Component type name - - - -## Modifiers - - - -## Related - - - -## References - - - -## Feedback - -Help us improve this component by providing feedback, asking questions, and -leaving any other comments on -[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md). -``` - -### Style template - -The style template helps describe how a component looks, including visual -specifications such as color, typography, structure, and size. - -```markdown ---- -title: [Component name] -description: [Explains what the component is in one or two sentences.] -tabs: ['Usage', 'Style', 'Code', 'Accessibility'] ---- - - - -The following page documents visual specifications such as color, typography, -structure, and size. - - - - - -Color Typography -Structure Size -Feedback - - - -## Color - - - -| Element | Property | Color token | -| ------- | ------------- | ------------------ | -| Title | color | `$text-primary` | -| Content | color | `$text-primary` | -| Icon | fill | `$icon-primary` | -| Header | border-top | `$border-subtle`\* | -| | background | Transparent | -| Panel | border-bottom | `$border-subtle`\* | -| | background | Transparent | - - - * Denotes a contextual color token that will change values based on the layer - it is placed on. - - - - - -![enabled state](images/accordion-style-1.png) - - - - -### Interactive state color - - - -| State | Element | Property | Color token | -| -------- | ------- | ---------- | ------------------ | -| Hover | Header | background | `$layer-hover`\* | -| Focus | Header | border | `$focus` | -| Disabled | Header | border-top | `$border-subtle`\* | -| | Title | background | `$text-disabled` | -| | Icon | fill | `$icon-disabled` | - - - * Denotes a contextual color token that will change values based on the layer - it is placed on. - - - - - - - - - -![default accordion alignment interactive states](images/accordion-style-2.png) - - - - - -![flush accordion alignment interactive states](images/accordion-style-3.png) - - - - - - - - -## Typography - - - -All accordion titles are set in sentence case. See the accordion -[content guidelines](/components/accordion/usage#content) for more details. - -| Element | Font-size (px/rem) | Font-weight | Type token | -| ------- | ------------------ | ------------- | ---------- | -| Title | 14 / 0.875 | Regular / 400 | `$body-01` | -| Content | 14 / 0.875 | Regular / 400 | `$body-01` | - -## Structure - - - -| Element | Property | px/rem | Spacing token | -| ------- | ----------- | -------- | ------------- | -| Header | height | 40 / 2.5 | – | -| Item | border-top | 1 | – | -| Title | margin-left | 16 / 1 | `$spacing-05` | - -
- -![Structure measurements for default accordion alignment](images/accordion-style-4.png) - -
- - - Structure measurements for default accordion alignment. | px / rem - - -
- -
- -![Spacing measurements for default accordion alignment](images/accordion-style-5.png) - -
- - - Spacing measurements for default accordion alignment. | px / rem - - -## Size - - - -There are six button sizes: small, medium, large productive, large expressive, -extra large, and 2XL. The large expressive button is used in editorial and -digital marketing experiences. See -[Button sizes](/components/button/usage#button-sizes) on the Usage tab for more -information about specific use cases for each button size. - -| Variant | Size | Height (px / rem) | -| ----------------- | ---------------- | ----------------- | -| Button | Small | 32 / 2 | -| | Medium | 40 / 2.5 | -| | Large productive | 48 / 3 | -| | Large expressive | 48 / 3 | -| Full bleed button | Extra large | 64 / 4 | -| | 2xl | 80 / 5 | - - - - -![Button sizes](images/button_usage_3.png) - - - - -## Feedback - - - -Help us improve this component by providing feedback, asking questions, and -leaving any other comments on -[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md). -``` - -### Code template - -The code template helps developers implement your component. Be specific, -include code snippets, and be sure to update as dependencies and versions -change. - -```markdown ---- -title: Component name (you won't need to write this) -description: Component description (you won't need to write this) -tabs: ['Usage', 'Style', 'Code', 'Accessibility'] ---- - - - - - - - - - -Overview [Component use-case] -Component API References -Feedback - - - -## Overview - - - -### Skeleton - - - -## [Use case, for example, Skeleton state or Sorting] - - - -## Component API - -### [Component name] props - -| Prop | Type | Required | Default | Description | -| ----------- | -------- | -------- | ------- | ----------- | -| `className` | `string` | – | – | – | - - - -#### [Component name][prop name] - - - -## References - - - -## Feedback - -Help us improve this component by providing feedback, asking questions, and -leaving any other comments on -[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md). -``` - -### Accessibility template - -The accessibility template helps designers and developers ensure components are -accessible. The published information helps users understand all the -accessibility considerations that are baked into Carbon. Refer to our guidance -on creating the -[keyboard interaction visuals](https://github.com/hiraaeth/component-contribution-accessibility/wiki/High-fidelity-keyboard-interaction-visuals). - -```markdown ---- -title: Component name (you won't need to write this) -description: Component description (you won't need to write this) -tabs: ['Usage', 'Style', 'Code', 'Accessibility'] ---- - - - - - - - - - What Carbon provides - - Design recommendations - Development considerations - - -## What Carbon provides - -Carbon bakes keyboard operation into its components, improving the experience of -blind users and others who operate via the keyboard. Carbon incorporates many -other accessibility considerations, some of which are described below. - -### Keyboard interaction - - - -Each accordion is a tab stop. `Space` or `Enter` keys expand or collapse -accordions, which are collapsed by default. Interactive elements within expanded -accordions integrate into the tab order automatically. - - - - - - - -![example of (componet_name) keyboard interaction](images/component_name-accessibility-1.png) - - - The (component_name) is reached by Tab and activated by Enter. - - - - - - - -## Design recommendations - -Design annotations are needed for the following instances. - - - -## Development considerations - -Keep these considerations in mind if you are modifying Carbon or creating a -custom component. - - -``` - -## Parts of a component contribution - -Component contributions ideally include all of the following parts. - -#### 1. A rationale - -Explain how your component will add value to the system. Carbon serves the -widest possible range of products, and contributions that increase the scope of -the system are more likely to be accepted. Be sure to include any user -experience and interaction descriptions. - -#### 2. A design spec - -Create sizing and styling annotations for all aspects of the component. This -spec should provide a developer with everything they need to create the design -in code. Check out our -[production guidelines](https://github.com/carbon-design-system/carbon-website/wiki/Production-guidelines#spec-guidelines) -to get started. - -You should include color tokens and type tokens used. - - - - -![Example of a design spec](images/content-switcher-style-1.png) - -Example of a design spec - - - - -#### 3. A Sketch symbol - -Any new components or changes to existing components will also live in the -[Carbon Sketch kit](/designing/kits/sketch) and so we'll need a Sketch symbol. -Check out -[Sketch's guide](https://www.sketch.com/docs/symbols/creating-symbols/) for -creating a symbol. - -This symbol can be contributed with the asset or enhancement, but must be added -to the kit by one of its maintainers. To contribute a symbol, simply open an -issue in the -[kit repo](https://github.com/carbon-design-system/carbon-design-kit/issues). - -#### 4. Usage documentation - -For guidance, see our -[production guidelines](https://github.com/carbon-design-system/carbon-website/wiki/Production-guidelines#spec-guidelines) -and [documentation templates](#documentation-templates) above. Reading through -existing component documentation on the site will help also. Color and type -tokens will live in the style tab. - -#### 5. Working code - -The component or enhancement must be built in one of our supported frameworks -(Vanilla, React, Vue, or Angular). See the contribution guidelines for the -specific repo you intend to contribute to. - - - - - - - - - - - - - - - - - - - - - - - - - - - -#### 6. Accessibility documentation - -Use the -[component accessibility deliverables](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=accessibility&projects=&template=component-accessibility-deliverables.yaml&title=%5BComponent+name%5D+component+%E2%80%93+accessibility+) -to document how the component is usable by people with disabilities. - -#### 7. Code documentation - -Start with our [Code guidance](#code-guidance) template. We recommend reading -through existing code documentation on this site for inspiration. - -## First steps to contributing - -To contribute a component to Carbon, start by -[opening a Github issue](https://github.com/carbon-design-system/carbon/issues/new?assignees=&labels=type%3A+enhancement+%F0%9F%92%A1&template=feature-request-or-enhancement.md&title=). -Include a detailed description in which you: - -- Explain the rationale -- Detail the intended behavior -- Clarify whether it's a variation of an existing component, or a new asset -- Include mockups of any fidelity (optional) -- Include any inspirations from other products (optional) - -This issue will be the staging ground for the contribution and an opportunity -for the community to weigh in with any suggestions. We encourage you to surface -work in progress. Someone in the community may be working on the same component -and interested in collaborating with you. diff --git a/src/pages/contributing/contribute-icons.mdx b/src/pages/contributing/contribute-icons.mdx deleted file mode 100644 index e1ea11968ad..00000000000 --- a/src/pages/contributing/contribute-icons.mdx +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: Icons -label: - Icons are visual symbols used to represent ideas, objects, or actions. They - communicate messages at a glance, afford interactivity, and draw attention to - important information. -description: - Icons are visual symbols used to represent ideas, objects, or actions. They - communicate messages at a glance, afford interactivity, and draw attention to - important information. ---- - - - -Design and production and guidelines -Making an icon -Exporting SVGs -Contribution process - - - -## Design and production guidelines - -Don't see the icon you need in the library? Make your own! Follow these -guidelines to ensure visual consistency and proper formatting. - -- All icons should be unique and not redundant with any existing icons in the - system. Search the [library](/guidelines/icons/library) for the keyword(s) - associated with your proposed new icon to ensure that it is not already - represented. -- All icons should adhere to the - [IBM Design Language visual style](https://www.ibm.com/design/language/iconography/ui-icons/library). -- All icons should comply with IBM - [accessibility standards](/guidelines/accessibility/overview). -- All icons should be usable across all supported platforms and devices. -- All icons should be understandable by a global audience of users, regardless - of nationality or language. - -## Making an icon - -- Create a 16 x 16 or 32 x 32 px artboard for each icon. -- 16 px icons should have 1 px padding. 32 px icons should have 2 px padding. -- Set your workspace up from the start to snap to pixels and round values to - whole pixels to avoid correcting shapes later. -- Never use center borders. Centering can cause half pixels. -- Avoid using the line tool; use the rectangle tool instead. The line tool will - place the vector on half pixels. -- Be aware of automatic alignments which can place vectors on uneven or half - pixels. -- Ungroup icon layers completely. The icon should be on the top-most layer in - your artboard. -- Make sure to properly name layers and artboards _(these names will also be - exported into the code)_. -- Review the - [icon master file](https://github.com/carbon-design-system/carbon/tree/v10/packages/icons/master) - to see these guidelines in practice. - -### Production-ready - -To be considered production-ready, all icon submissions must be delivered in SVG -format at 16 x 16 px (for integration with Carbon components) or 32 x 32 (for -service icons). - -- Icons should be at whole pixels. No decimals are allowed in x and y - coordinates or width and height fields. -- Each artboard and the artwork within it must be aligned to the pixel grid. -- All strokes must be expanded and at full pixel values. -- All possible shapes and paths should be combined. - -## Exporting SVGs - -### Export SVGs from Adobe Illustrator. - -1. Draw a 16 x 16 or 32 x 32 px artboard. 16 px icons should have 1 px padding. - 32 px icons should have 2 px padding. -2. Place the icon squarely on the artboard, making sure it's aligned to the - pixel grid. -3. Expand all strokes `Object` → `Expand`. -4. Select all overlapping shapes and click the "Unite" icon in the Pathfinder - panel to merge all of the shapes together. -5. Make sure the icon is at `#000000` and has no additional styling. -6. Select `File` → `Save a Copy...` from the top navigation. -7. On the `Format` dropdown select "SVG". -8. Below `Format` select `Use Artboard`, then select either all or a range of - artboards, depending on your need. -9. Click `Save`. -10. The `SVG Options` dialog will then open. -11. Make sure the preferences are the same as in the image below. - - - - -![export an icon from Illustrator](component/images/contribution-iconography-pictogram.png) - - - - -## Contribution process - -Does your icon have potential for other products at IBM? If so, please consider -contributing to the design system. IBM welcomes icon contributions to our -iconography library. You’re welcome to submit a single icon or a batch of icons -for approval. - -### Getting started - -Before submitting artwork, first review our -[icons library](https://www.carbondesignsystem.com/guidelines/icons/library/) or -download the -[Carbon icon master .ai file](https://github.com/carbon-design-system/carbon/tree/v10/packages/icons/master) -to check your design for duplication against existing icons. - -### Approval process - -Icons for use within IBM must go through a design review process to ensure -consistency and proper representation of the IBM brand across all environments. -The process begins when you create a GitHub issue. Design review and approval -typically take 14–21 days from issue creation, depending on the number of icons -contributed. - -If your submission is accepted, the team will assign someone to your issue. If -changes are needed, the team will note them in the issue and may return your -submission with recommendations or suggest reworking the icon based on feedback -from the Design System and Brand teams. - -Once the submission is approved it will then go through our process to be -included into the Adobe Illustrator IBM Icon master file and be made available -in the IBM Design Language and Carbon libraries. - -Submit icons for approval by creating a -[single](https://github.ibm.com/brand/ui-icons/issues/new?assignees=&labels=&template=single-ui-icon-approval.md&title=%5Bui-icon%5D) -or -[batch](https://github.ibm.com/brand/ui-icons/issues/new?assignees=&labels=&template=batch-ui-icon-approval-request.md&title=%5Bui-icon-batch%5D) -GitHub issue for your contribution. diff --git a/src/pages/contributing/contribute-pictograms.mdx b/src/pages/contributing/contribute-pictograms.mdx deleted file mode 100644 index 8b7c3a65684..00000000000 --- a/src/pages/contributing/contribute-pictograms.mdx +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: Pictograms -description: - Pictograms are visual symbols used to represent ideas, objects, or narratives - at a glance. They work well in presentations and marketing communications. ---- - - - -IBM's pictograms are visual symbols used to represent ideas, objects, or -narratives. They can communicate messages at a glance, afford interactivity, and -simplify complex ideas. They draw from details found in the Plex typeface and -work well in presentations and marketing communications. - - - - - Producing a pictogram - Producing an icon - Export SVGs from Adobe Illustrator - Contribution process - - -## Producing a pictogram - -Don't see the pictogram you need in the library? Make your own! Follow these -guidelines to ensure visual consistency and proper formatting. - -- All pictograms should be unique and not redundant with any existing pictograms - in the system. Look through the pictograms in the - [Pictogram library](/guidelines/pictograms/library/) to ensure that your - proposed new pictogram is not already represented. -- All pictograms should adhere to the - [IBM Design Language visual style](https://www.ibm.com/design/language/elements/pictograms/design). -- All pictograms should comply with IBM - [accessibility standards](/guidelines/accessibility/overview). -- All pictograms should be usable across all supported platforms and devices. -- All pictograms should be understandable by a global audience of users, - regardless of nationality or language. - -## Producing an icon - -- Create a 32 x 32 px artboard for each pictogram. -- 32 px pictograms should have 1 px padding. -- Set your workspace up from the start to snap to grid. -- Be aware of automatic alignments which can place vectors on uneven or half - pixels. -- The pictogram should be on the top-most layer in your artboard. Strokes should - be grouped appropriately. -- Make sure to properly name layers and artboards (these names will also be - exported into the code). - -### Production-ready - -- To be considered production-ready, all pictogram submissions must be delivered - in Adobe Illustrator format at 32 x 32 px with strokes kept intact. -- Each artboard and the artwork within it must be aligned to the pixel grid - wherever possible. -- All strokes should be kept as is and not converted to shapes. -- Group strokes logically whenever possible. - -## Export SVGs from Adobe Illustrator - -1. Draw a 32 x 32 px artboard. 32 px pictograms should have 1 px padding. -1. Place the icon squarely on the artboard, making sure it's aligned to the - pixel grid. -1. Expand all strokes `Object > Expand`. -1. Select all overlapping shapes and click the `Unite` icon in the `Pathfinder` - panel to merge all of the shapes together. -1. Make sure the icon is at `#000000` and has no additional styling. -1. Select `File > Save a Copy…` from the top navigation. -1. On the `Format` dropdown select `SVG`. -1. Below `Format` select `Use Artboard`, then select either all or a range of - artboards, depending on your need. -1. Click `Save`. -1. The `SVG Options` dialog will then open. -1. Make sure the preferences are the same as in the image below. - - - - -![SVG export options image](component/images/contribution-iconography-pictogram.png) - - - - -## Contribution process - -Does your pictogram have potential for other materials at IBM? If so, please -consider contributing to the design system. IBM welcomes pictogram contributions -in the form of a pull request to our pictogram repository. For now, to make a -pull request, -**[please submit an issue in the repo](https://github.ibm.com/brand/Pictograms/issues/new/choose)** -with the pictogram attached. - -Please note that Carbon contribution is not required in order to introduce a new -pictogram into your materials. If your pictogram is determined to be broadly -useful in Carbon and passes IBM Brand design reviews, then it may also be -integrated into the design system. - -If your submission is accepted, the team will notify you. If changes are needed, -you'll need to create a new contribution issue after reworking it based on -feedback from the Design System and Brand teams. diff --git a/src/pages/contributing/design.mdx b/src/pages/contributing/design.mdx new file mode 100644 index 00000000000..c5c975a10a4 --- /dev/null +++ b/src/pages/contributing/design.mdx @@ -0,0 +1,96 @@ +--- +title: Design +description: + Design contributions can involve anything from creating design specs for + feature requests to maintaining Figma libraries. Below you'll find tips and + best practices to get started. +--- + +export const Title = () => Contribute design; + + + +Design contributions can involve anything from creating design specs for feature +requests to maintaining Figma libraries. Below you'll find tips and best +practices to get started. + + + + + +Step 1: Find a project +Step 2: Refine the issue +Step 3: Get feedback + + + +## Step 1: Find a project + +New issues submitted by the community are initially triaged by Carbon team +members. Any issue that the Carbon team accepts, but can not fit in their +roadmap, is open for community contribution. + +#### Volunteer for existing work + +The best way to volunteer is to look through +[existing GitHub issues](https://github.com/carbon-design-system/carbon/issues?q=is%3Aopen+is%3Aissue+label%3A%22needs%3A+community+contribution%22+) +labeled with `needs: community contribution`. Any issue labeled with +`needs: design contribution` is fair game! Put a comment in the issue saying +you'd like to help. + + + +The most common design requests are related to feature enhancements: researching +UX, creating visual solutions, and crafting a design spec are often required +before a feature enhancement can be put into code. + +If you want to join an issue that is already assigned to someone or has a +specific milestone, please discuss with the assignee of the issue or with the +Carbon team to coordinate. Often contributors work in groups of 2-3. + +We also have many ongoing projects to create and update reusable components in +Figma. This work is not currently tracked in GitHub, so check out the +[status of design kits](https://www.figma.com/file/CFMtqV5Nztdbm0mi2UiDLg/Library-%2B-Template-Planning?type=design&node-id=3713-26762&mode=design&t=HqvAYXUeccKNMstT-0) +and get involved by reaching out to the contacts listed. + +The Carbon team is also happy to help you. Just stop by our +[Carbon Design office hours](/whats-happening/meetups/) or +[contact us](/help/contact-us/) directly. + +#### Submit an idea + +Have a new idea that you think would benefit Carbon? Or do you need to report a +bug? First, be sure to look through the +[issue backlog](https://github.com/carbon-design-system/carbon/issues) to make +sure it is a novel idea or bug. Then, file your proposal on GitHub using the +[issue templates](https://github.com/carbon-design-system/carbon/issues/new/choose). +If you're willing to work on this idea yourself, be sure to let us know in your +issue! Your idea will then go through a triage process by the Carbon team. + +## Step 2: Refine the issue + +Whereas code contributions tend to be well defined, design contributions can be +a little more ambiguous. We recommend you try writing a rough task list of what +you believe your contribution will entail, and post it in the GitHub issue +comments. In most cases, we recommend you then reach out to the Carbon team or +come to Carbon Design office hours. We'll help you further refine your issue, +clarify the scope of work, and connect you to other collaborators. Some good +questions to ask yourself are: + +- Am I clear on the scope of this work? +- Is this task list feasible for me to do? +- Do I need to collaborate with anyone else? +- Do I have a clear definition of done or a plan to pass this to a developer? + +## Step 3: Get feedback + +Most contributors work in groups of 2-3 and either set up weekly sessions or +join [meetups](/whats-happening/meetups/#carbon-office-hours) such as the Data +Viz Guild or Carbon Design office hours. In these sessions, it is common to +share work in progress and ask lots of questions. In return, you'll get candid +feedback and help. As you make progress, update your GitHub issue. diff --git a/src/pages/contributing/documentation.mdx b/src/pages/contributing/documentation.mdx index 17dd6e4bbeb..519559768b9 100644 --- a/src/pages/contributing/documentation.mdx +++ b/src/pages/contributing/documentation.mdx @@ -1403,6 +1403,13 @@ then propose the change with a pull request. Your changes will be reviewed by the Carbon team. This is the easiest and most commonly used approach by contributors. + + #### How to add a new page or image To start, go to the Carbon website repository @@ -1426,6 +1433,13 @@ After filling out the markdown template or adding an image, click you created. If you are in the wrong branch, you will have to copy your content into the correct branch. + + Once you have committed your changes, go to the [Pull requests](https://github.com/carbon-design-system/carbon-website/pulls) page. Compare `base: main` to your branch and click `Create new pull request`. diff --git a/src/pages/contributing/pattern.mdx b/src/pages/contributing/pattern.mdx deleted file mode 100644 index 9b88b85b2eb..00000000000 --- a/src/pages/contributing/pattern.mdx +++ /dev/null @@ -1,430 +0,0 @@ ---- -title: Patterns -description: - Patterns are best practice solutions for how a user achieves a goal. They show - reusable combinations of components and templates that address common user - objectives with sequences and flows. ---- - - - -Patterns are best practice solutions for how a user achieves a goal. They show -reusable combinations of components and templates that address common user -objectives with sequences and flows. - - - -## How to write a pattern - -We’ve created guidelines to help you prepare a complete and comprehensive -pattern. There are two Markdown templates to choose from: - -- **Pattern with a single variant**: Use this template if your pattern has one - primary solution. This is the most common. -- **Pattern with multiple variants**: Use this template if your content covers - multiple variants of the pattern. - -You may need to adjust the topic order to best tell the story but your pattern -should cover all of the topics outlined in each of these templates. - -If you would like some assistance with the best approach for your pattern, -please [reach out](https://www.carbondesignsystem.com/help/contact-us). We'd be -happy to work through the options with you. - -```markdown ---- -title: Pattern name -description: Explain the pattern in one or two sentences. ---- - - - -Explain the pattern in one or two sentences. - - - - - -Overview -Designing with [pattern] -Accessibility -Related -References -Feedback - - - -## Overview - -This section answers the question: “What problem does this pattern solve?” - -- Define the use of your pattern and what it does. -- Explain a user’s needs and how the pattern meets those needs. - -### Anatomy - -Include an image with callouts explaining each part of the pattern. See the -[Forms pattern](https://www.carbondesignsystem.com/patterns/forms-pattern#anatomy-of-a-form) -for an example. - -### When to use - -Include a short list describing situations where this pattern could be applied. - -For example, use this pattern when: - -- Situation 1 -- Situation 2 - -### When not to use (optional) - -If required, include a short explanation about when not to use this pattern. - -## Designing with [pattern] - -This section explains the pattern in detail. Use a combination of written -explanations and visuals to tell the story. - -Describe the elements, components, and content that make up the pattern. - -Show the pattern in context. Use visuals throughout your written commentary to -illustrate your guidance. - -Different patterns require different visuals to best explain the behaviors and -hierarchy. Choose the options that make the most sense for the story you are -telling. - -- Use annotated wireframes or sketches to explain the visual hierarchy of - components. -- Create high-level user flows to explain the big picture. -- Create a functional prototype if that is the best way to illustrate the - pattern's behavior. - -Provide a Sketch file with any symbols you've created in the development of this -pattern. - -Use the following headings as guidelines for the kind of information to include. -Depending on the requirements of your pattern, you may choose to present these -headings as H2 headings or as H3 headings underneath a more general "Designing -with [pattern]" heading. See the -[Dialogs pattern](https://www.carbondesignsystem.com/patterns/dialog-pattern/#designing-with-dialogs) -as an example. - -### Types of [pattern] - -If the pattern has different types or visual treatments that serve different use -cases, cover them here and be sure to explain when to use each type. - -See the -[Empty states](https://www.carbondesignsystem.com/patterns/empty-states-pattern#when-to-use) -pattern and the -[Notification](https://www.carbondesignsystem.com/patterns/notification-pattern#notification-types) -pattern for examples. - -### Behaviors - -Describe behaviors, including guidance on interactions, and changes in states -and content. - -### Best practices - -Are there any do's and don'ts specific to this variant? Include them here. - -For examples of how to lay out this kind of information, see -[Dropdown](https://www.carbondesignsystem.com/components/dropdown/usage) and -[Modal](https://www.carbondesignsystem.com/components/modal/usage#variations). - -### Visual guidance - -Cover any important topics such as alignment, image choice considerations, or -special treatments in situations with no data or multiple instances of elements. -See the -[Empty states pattern](https://www.carbondesignsystem.com/patterns/empty-states-pattern#visual-guidelines-for-smaller-empty-spaces) -and the -[Forms pattern](https://www.carbondesignsystem.com/patterns/forms-pattern#designing-a-form) -for examples. - -### Other use cases - -If there are use cases that require a different solution, include those here -with corresponding explanations and visuals. Be sure to explain the reasons for -using one solution over another. - -## Accessibility - -Evaluate your pattern to ensure it meets -[accessibility standards](notion://www.notion.so/guidelines/accessibility/overview) -and guidelines, and provide details of compliance. - -For example, “Users should be able to TAB into the input field of the search box -to begin typing and press ENTER to run the search query.” - -For examples, see the -[Text toolbar pattern](https://www.carbondesignsystem.com/patterns/text-toolbar-pattern#accessibility) -and the -[Search pattern](https://www.carbondesignsystem.com/patterns/search-pattern#accessibility). - -## Related - -Which components are used when building this pattern? Did you reference other -patterns? List them here. - -If necessary, clarify any differences between this pattern and related patterns. - -## References - -Help designers understand your process by explaining your rationale for the way -you implemented the pattern. Include any research, citations, books or articles -that you found helpful. - -## Feedback - -Help us improve this pattern by providing feedback, asking questions, and -leaving any other comments on -[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md). -``` - -Template for patterns with one primary solution - -```markdown ---- -title: Pattern name (multiple variants) -description: Explain the pattern in one or two sentences. ---- - - - -Explain the pattern in one or two sentences. - - - - - -Overview -Designing with [pattern] -[Pattern] variant -Accessibility -Related -References -Feedback - - - -## Overview - -Include a paragraph or two that describes the primary use cases for the pattern -and details about how it helps the user achieve any tasks. - -The purpose of this overview section is to set context for your readers. - -### Anatomy - -It can be helpful to show images of all of the variants in small form together. -See the -[Dialogs pattern](https://www.carbondesignsystem.com/patterns/dialog-pattern#modal-variants) -and the -[Notifications pattern](https://www.carbondesignsystem.com/patterns/notification-pattern#notification-types) -for examples of this visual treatment. - -Alternatively, if there is one variant that includes common aspects of the -pattern that are seen across all or most variants, include an image with -callouts explaining each part of the pattern. See the -[Forms pattern](https://www.carbondesignsystem.com/patterns/forms-pattern#anatomy-of-a-form) -for an example. - -### [Pattern] variants - -Include a table with the variants discussed in this pattern. Include a short -description about the usage of each pattern variant. The table in -[Modal component](https://www.carbondesignsystem.com/components/modal/usage/#variants) -is a good example of the level of detail required. - -The variant names should link to the H2 headings for the variants below. - -Add more columns, if needed. For example, you could add a column that includes -short explanations about when not to use the variant and guide the user to an -alternative that may be more appropriate. - -## Designing with [pattern] - -This section covers _universal_ content related to all variants, and depending -on the requirements of your pattern, may include the following H3s. - -### When to use - -If you need to elaborate on the content included in the pattern variants table -in the Overview, include that detail here. The -[Notifications pattern](https://www.carbondesignsystem.com/patterns/notification-pattern#when-to-use) -is a good example of the kind of content to include. - -### When not to use (optional) - -If required, include a short explanation about when not to use this pattern and -provide alternatives. - -### Universal behaviors - -Describe any behaviors that are universal to all pattern variants, and include -guidance on interactions, and changes in states and content. - -### Best practices - -List out best practices and include any design considerations that help with -making choices. - -- Do's -- Dont's - -### Visual guidance - -Cover any important topics such as alignment, image choice considerations, or -special treatments in situations with no data or multiple instances of elements. -See -[Empty states](https://www.carbondesignsystem.com/patterns/empty-states-pattern#visual-guidelines-for-smaller-empty-spaces) -for an example. - -### Other considerations - -If there are any other considerations particular to your pattern that are -applicable to all variants, include them here. - -## [Pattern] variant - -Rename this H2 heading with the first pattern variant name, and repeat for all -variants within this pattern. These sections should map directly to the variant -table in the Overview. - -This section describes the pattern variant in detail, and highlights content -that is _unique_ to the pattern variant. Use a combination of written -explanations and visuals to tell the story. - -The H3s headings below are suggested that be included and adapted to suit the -requirements and complexity of the variant. - -Include an introductory paragraph about the pattern variant to set context. - -### [Pattern variant] anatomy - -Include an image with callouts explaining each part of the pattern variant. See -the -[Forms pattern](https://www.carbondesignsystem.com/patterns/forms-pattern#anatomy-of-a-form) -for an example. - -### When to use - -Provide use cases and situations for when this pattern should be used. - -### When not to use - -If required, also include a "When not to use" section with details about when -not to use and suggest alternatives. - -### Designing with [pattern variant] - -Describe the elements, components, and content that make up the pattern. - -Show the variant in context. Use visuals throughout your written commentary to -illustrate your guidance. - -Different patterns require different visuals to best explain the behaviors and -hierarchy. Choose the options that make the most sense for the story you are -telling. - -- Use annotated wireframes or sketches to explain the visual hierarchy of - components. -- Create high-level user flows to explain the big picture. -- Create a functional prototype if that is the best way to illustrate the - pattern's behavior. - -Provide a Sketch file with any symbols you've created in the development of this -pattern. - -### [Pattern variant] behaviors - -Describe behaviors specific to the pattern variant, including guidance on -interactions, and changes in states and content. - -### Best practices - -List out best practices and include any design considerations that help with -making choices. - -- Do's -- Dont's - -For examples of how to lay out this kind of information, see the -[Dropdown component](https://www.carbondesignsystem.com/components/dropdown/usage) -and the -[Modal component](https://www.carbondesignsystem.com/components/modal/usage#variations). - -### Visual guidance - -Cover any important topics such as alignment, image choice considerations, or -special treatments in situations with no data or multiple instances of elements. -See the -[Empty states pattern](https://www.carbondesignsystem.com/patterns/empty-states-pattern#visual-guidelines-for-smaller-empty-spaces) -and the -[Forms pattern](https://www.carbondesignsystem.com/patterns/forms-pattern#designing-a-form) -for examples. - -### Other use cases - -If there are similar use cases that may require a different solution, include -details here and explain the reasons for using one solution over another. - -Repeat the H2 heading `Pattern variant` with the necessary H3 headings for each -variant within the pattern. - -## Accessibility - -Evaluate your pattern to ensure it meets -[accessibility standards](/guidelines/accessibility/overview) and guidelines, -and provide details of compliance. - -For example, “Users should be able to TAB into the input field of the search box -to begin typing and press ENTER to run the search query.” - -## Related - -Which components did you use when building this pattern? Did you reference other -patterns? List them here. - -If necessary, clarify any differences between this pattern and related patterns. - -## References - -Help designers understand your process by explaining your rationale for the way -you implemented the pattern. Include any research, citations, books or articles -that you found helpful. - -## Feedback - -Help us improve this pattern by providing feedback, asking questions, and -leaving any other comments on -[GitHub](https://github.com/carbon-design-system/carbon-website/issues/new?assignees=&labels=feedback&template=feedback.md). -``` - -Template for patterns with multiple variants - -## First steps to contributing - -If you’ve designed a pattern that is not currently in Carbon, contributing it -back allows others in the community to refine and use your pattern in their -projects. - -Start by opening a -[Github issue](https://github.com/carbon-design-system/carbon-website/issues/new). -Include a detailed description in which you: - -- Define your pattern and explain the rationale -- Include mockups and/or prototypes of any fidelity -- Clarify whether it uses existing components, new components, or both -- Include competitive and comparative analysis, and any inspirations from other - products - -This issue will be the staging ground for the pattern contribution, and you -should expect the Carbon core team and the community to weigh in with -suggestions. - -We encourage you to surface work in progress. If you’re not able to complete all -of the parts yourself, someone in the community may be able to help. diff --git a/static/videos/code-contribution.mp4 b/static/videos/code-contribution.mp4 new file mode 100644 index 00000000000..9c5d87bf3b2 Binary files /dev/null and b/static/videos/code-contribution.mp4 differ diff --git a/static/videos/code-contribution.png b/static/videos/code-contribution.png new file mode 100644 index 00000000000..a3f29de8cb3 Binary files /dev/null and b/static/videos/code-contribution.png differ diff --git a/static/videos/design-contribution.mp4 b/static/videos/design-contribution.mp4 new file mode 100644 index 00000000000..3edef7b8330 Binary files /dev/null and b/static/videos/design-contribution.mp4 differ diff --git a/static/videos/design-contribution.png b/static/videos/design-contribution.png new file mode 100644 index 00000000000..a49a76eb85b Binary files /dev/null and b/static/videos/design-contribution.png differ diff --git a/static/videos/edit-this-page-contribution.mp4 b/static/videos/edit-this-page-contribution.mp4 new file mode 100755 index 00000000000..c29f78a6ed9 Binary files /dev/null and b/static/videos/edit-this-page-contribution.mp4 differ diff --git a/static/videos/edit-this-page-contribution.png b/static/videos/edit-this-page-contribution.png new file mode 100644 index 00000000000..86c79ef748b Binary files /dev/null and b/static/videos/edit-this-page-contribution.png differ diff --git a/static/videos/inline-edit-contribution.mp4 b/static/videos/inline-edit-contribution.mp4 new file mode 100644 index 00000000000..bc1e4a4ecc7 Binary files /dev/null and b/static/videos/inline-edit-contribution.mp4 differ diff --git a/static/videos/inline-edit-contribution.png b/static/videos/inline-edit-contribution.png new file mode 100644 index 00000000000..a497e74a9ac Binary files /dev/null and b/static/videos/inline-edit-contribution.png differ