Skip to content

Latest commit

 

History

History
79 lines (50 loc) · 4.84 KB

CONTRIBUTING.md

File metadata and controls

79 lines (50 loc) · 4.84 KB

Contributing to Nimble Tokens

Repository layout

Folder Description
build Build scripts for generating files
dist/fonts Fonts for use in applications
dist/icons Icons for use in applications
dist/styledictionary JSON token source files
docs Files used by the documentation
source/icons Illustrator files for editing icons

Getting started

  1. Build the monorepo, see Getting Started

Editing Base Tokens

Base tokens are generated using the Style Dictionary build system, which transforms platform-agnostic token definition files into platform-specific output. These JSON definition files are the source of truth for the colors, fonts, and component design tokens in this repository. To modify the generated tokens, complete these steps:

  1. Edit the JSON files in source/styledictionary/properties. Long term these tokens will be sourced from a Figma design spec but for now it's OK to make manual edits.
  2. Rebuild the generated token files by running the repository's build command, npm run build.
  3. Test your changes locally and create a PR using the normal process.

To style a component with token values, you must first map base tokens to theme-aware tokens.

Updating icons

Icon naming

Use Font Awesome names for icons. If Font Awesome doesn't contain an equivalent icon, minimize the use of metaphors; choose descriptive and unambiguous names instead.

✅ Descriptive name ❌ Metaphor
key access-control
cog system-configuration
arrow-left-from-line logout

Add all appropriate metaphors and synonyms to the icon-metadata.ts file, so clients can quickly find icons in Storybook. You can find ideas for synonyms in the Font Awesome metadata.

Extract icons from Adobe Illustrator

These steps require access to Adobe Illustrator and Perforce so will typically be completed by Brandon O'Keefe, Fred Visser, or another designer.

  1. Get the latest copy of the icon source file from NI internal Perforce at //NIComponents/VisualDesign/ProductionAssets/DiagramPaletteAssets_XML/Nimble/trunk/20.0/source/Nimble_Iconography.ai.

  2. Export high-quality, optimized SVG files from the icon source file, by using the Export for Screens… workflow within Adobe Illustrator to export SVG files:

    1. Choose File » Export » Export for Screens…

    2. In the Export for Screen prompt, confirm that files will be exported to the dist/icons/svg folder, and that the remaining settings match the screenshot below.

    3. Confirm that the SVG settings match the screenshot below.

    4. Choose to replace any existing files in the dist/icons/svg folder.

  3. Proceed to the steps below or create a user story requesting that the Nimble team perform them. If filing an issue, attach the new and modified SVG files to the issue.

Adding icons to Nimble

  1. Search for all <defs>.*</defs> tags in the exported .svg files and remove them. This removes all color from the .svg files and allows us to dynamically change the fill color.

    • Note: In rare cases, icons will be provided with multiple fixed colors that are not intended to change with the theme or severity. These icons should retain the <defs> tags.

  2. Confirm the new icon files will build correctly by running: npm run build -w @ni/nimble-tokens.

  3. Generate and build icon components by running npm run build -w @ni/nimble-components. This step will report an error at this point but is necessary to enable the next step.

  4. Add metadata for the new icons to nimble-components/src/icon-base/tests/icon-metadata.ts.

  5. Run npm run build -w @ni/nimble-components again. It should now succeed.

  6. Preview the built files by running: npm run storybook, and review the Icons story to confirm that your changes appear correctly. Inspect the icons in each Severity and ensure their color changes.

  7. Publish a PR with your changes. If there are any new icons, set changeType and dependentChangeType to minor in the beachball change file.