From 4d8db690cc34357e5038d46de4e7f76cc0d60971 Mon Sep 17 00:00:00 2001 From: Josh Black Date: Mon, 23 Mar 2020 19:33:51 -0500 Subject: [PATCH] docs(icons): add docs around icon metadata (#5662) * docs(icons): add docs around icon metadata * Update contributing.md expanded description of the renaming/removal processes * Update contributing.md expanded the description of the renaming/removal processes * chore(format): run prettier * Update contributing.md typo `nem` -> `new` * Update contributing.md typo `nem` -> `new` Co-authored-by: Chris Connors <35537391+chrisconnors-ibm@users.noreply.github.com> --- .../src/components/button/_button.scss | 2 +- .../src/components/button/_mixins.scss | 7 +- packages/icons/docs/contributing.md | 68 +++++++++++++++++++ packages/pictograms/docs/contributing.md | 67 ++++++++++++++++++ 4 files changed, 139 insertions(+), 5 deletions(-) create mode 100644 packages/icons/docs/contributing.md create mode 100644 packages/pictograms/docs/contributing.md diff --git a/packages/components/src/components/button/_button.scss b/packages/components/src/components/button/_button.scss index e19c2c7d91ce..fe8a1cc34cb7 100644 --- a/packages/components/src/components/button/_button.scss +++ b/packages/components/src/components/button/_button.scss @@ -83,7 +83,7 @@ $interactive-03, $hover-tertiary, currentColor, - $active-tertiary, + $active-tertiary ); &:hover { diff --git a/packages/components/src/components/button/_mixins.scss b/packages/components/src/components/button/_mixins.scss index 8b347bcc7f7d..38a4134535fc 100644 --- a/packages/components/src/components/button/_mixins.scss +++ b/packages/components/src/components/button/_mixins.scss @@ -63,7 +63,7 @@ $font-color, $hover-bg-color, $icon-color, - $active-color, + $active-color ) { background-color: $bg-color; border-width: $button-outline-width; @@ -77,9 +77,8 @@ &:focus { border-color: $focus; - box-shadow: - inset 0 0 0 $button-border-width $focus, - inset 0 0 0 ($button-border-width + $button-outline-width) $ui-02; + box-shadow: inset 0 0 0 $button-border-width $focus, + inset 0 0 0 ($button-border-width + $button-outline-width) $ui-02; } &:active { diff --git a/packages/icons/docs/contributing.md b/packages/icons/docs/contributing.md new file mode 100644 index 000000000000..061018230ce7 --- /dev/null +++ b/packages/icons/docs/contributing.md @@ -0,0 +1,68 @@ +# Contributing + + + + +## Table of Contents + +- [Metadata](#metadata) + - [`icons.yml`](#iconsyml) + - [`categories.yml`](#categoriesyml) + - [`deprecated.yml`](#deprecatedyml) + + + + +## Metadata + +The information for each icon that is used by our website is hosted in +[YAML](https://en.wikipedia.org/wiki/YAML) files inside of the icons package, +located [here](../). Different files hold different types of information for our +icons. The most notable ones include: + +- [Icon name, friendly name, alias, and size](../icons.yml) +- [Categories for icons](../categories.yml) +- [Deprecations](../deprecated.yml) + +You can edit each of these files using GitHub UI by clicking on the "edit" icon. +We go into more detail for each of the file formats below. + +### `icons.yml` + +This file contains information about an icon's name, "friendly" name, aliases, +and sizes. The friendly name for an icon is what is displayed to an end-user on +our website. The name for an icon matches the asset name in our folder of SVG +assets. Similarly, the sizes correspond to the sizes found in our folder of SVG +assets for the given icon. Finally, alises for an icon are used during search as +alternative ways of finding the icon. + +### `categories.yml` + +This file contains grouping information for icons and the categories, or +subcategories, to which they belong. Feel free to add or update categories, +subcategories, members, and more in this file. + +### `deprecated.yml` + +This file contains information mapping assets that have changed in the current +release. Typically, this file will indicate which icons have been renamed or +removed. This file contains a list of deprecated icons with a required `name` +field alongside an optional `reason` field. You can use the `reason` field to +indicate that: + +- The icon has been replaced by an alternate icon +- The icon has been removed + +Use `deprecated.yml` when assets are renamed to indicate the change. This will +hide the depreacated name from display on the web site, and signal to teams that +the originally named file is a candidate for future removal. It's recommended +that you also add the deprecated name to `aliases` for the asset in `icons.yml`, +so that the new asset name will be a search result for the deprecated name. We +then persist both named assets in the repo for 2 releases to allow teams time to +migrate to the new asset name. + +When an asset is removed with no replacement, it is also captured in +`deprecated.yml`. Removed icon assets represent breaking changes and should be +carefully considered. To remove an asset, add the asset name to +`deprecated.yml`; we then persist the to-be removed assets in the repo for 2 +releases to allow teams time to migrate to a different asset. diff --git a/packages/pictograms/docs/contributing.md b/packages/pictograms/docs/contributing.md new file mode 100644 index 000000000000..559e34fc7943 --- /dev/null +++ b/packages/pictograms/docs/contributing.md @@ -0,0 +1,67 @@ +# Contributing + + + + +## Table of Contents + +- [Metadata](#metadata) + - [`pictograms.yml`](#pictogramsyml) + - [`categories.yml`](#categoriesyml) + - [`deprecated.yml`](#deprecatedyml) + + + + +## Metadata + +The information for each pictogram that is used by our website is hosted in +[YAML](https://en.wikipedia.org/wiki/YAML) files inside of the pictograms +package, located [here](../). Different files hold different types of +information for our pictograms. The most notable ones include: + +- [Icon name, friendly name, and aliases](../pictograms.yml) +- [Categories for pictograms](../categories.yml) +- [Deprecations](../deprecated.yml) + +You can edit each of these files using GitHub UI by clicking on the "edit" +pictogram. We go into more detail for each of the file formats below. + +### `pictograms.yml` + +This file contains information about a pictogram's name, "friendly" name, and +aliases. The friendly name for an pictogram is what is displayed to an end-user +on our website. The name for an pictogram matches the asset name in our folder +of SVG assets. Finally, alises for an pictogram are used during search as +alternative ways of finding the pictogram. + +### `categories.yml` + +This file contains grouping information for pictograms and the categories, or +subcategories, to which they belong. Feel free to add or update categories, +subcategories, members, and more in this file. + +### `deprecated.yml` + +This file contains information mapping assets that have changed in the current +release. Typically, this file will indicate which pictograms have been renamed +or removed. This file contains a list of deprecated pictograms with a required +`name` field alongside an optional `reason` field. You can use the `reason` +field to indicate that: + +- The icon has been replaced by an alternate icon +- The icon has been removed + +Use `deprecated.yml` when assets are renamed to indicate the change. This will +hide the depreacated name from display on the web site, and signal to teams that +the originally named file is a candidate for future removal. It's recommended +that you also add the deprecated name to `aliases` for the asset in `icons.yml`, +so that the new asset name will be a search result for the deprecated name. We +then persist both named assets in the repo for 2 releases to allow teams time to +migrate to the new asset name. + +When an asset is removed with no replacement, it is also captured in +`deprecated.yml`. Removed icon assets represent breaking changes and should be +carefully considered. To remove an asset, add the asset name to +`deprecated.yml`; we then persist the to-be removed assets in the repo for 2 +releases to allow teams time to migrate to a different asset.