Repository files navigation

Kong's open-source, Vue icon component library, partially sourced fromGoogle's Material Symbols.

View all available icons:http://kong.github.io/icons/

• Usage
  • Installation
  • Import
  • Component Props
• Contributing & Local Development
  • SVG file requirements
  • Adding a new icon
  • Development Sandbox
  • Lint and fix
  • Testing
  • Build for production
  • Committing Changes
  • Approvals
  • Package Publishing

Install the@kong/icons package in your host project.

pnpm add @kong/icons

Icons should be imported individually which allows for proper tree-shaking, so only import the icons you need.

Notice that since the few styles that are included are inlined, there is no stylesheet to import.

<template><button>    Add a service<AddIconsize="24"/></button></template><scriptsetuplang="ts">import{AddIcon}from'@kong/icons'</script>

• type:String
• required:false
• default:''

The accessibility text provided to screen readers.

Note: Thecolor prop only impacts solid, single-color icons generated from the/svg/solid/ directory.

• type:String
• required:false
• default:'currentColor'

Set the icon color to any valid CSS color value orcurrentColor, which inherits the text color of the icon's parent element.

• type:String
• required:false
• default:'block'

Set the CSSdisplay property for the icon wrapper element.

• type:Boolean
• required:false
• default:false

Whether the SVG is meaningful to the page, or just complimentary. Utilized to expose or hide the SVG from screen readers and enable or disable pointer events.

• type:[Number, String]
• required:false
• default:24

The size of the icon, in pixels.

As a convenience, you may pass the size as anumber, e.g.24 or as a string that can be converted to an integer, such as'48'.

When utilizing astring, do not pass any units along with the value.

• type:String
• required:false
• default:'span'

The HTML tag to use in place of the default wrapper<span> tag.

<CloseIconas="button"/>

To get started, install the package dependencies

pnpm install --frozen-lockfile

The exported Vue components are generated from SVG source files located in the/svg/ child directories.

Source SVG filesmust:

• have aunique, lowercase and kebab-case filename, regardless of the/svg/* subdirectory they are located in
  • file namesmust not include the wordicon (the suffix is automatically added during component generation)
  • the resulting exported icon name will be a PascalCase file with an addedIcon suffix (e.g.kebab-case.svg -> KebabCaseIcon.vue)
• be stored in the/svg/ directory
  • All solid (single-color) icon SVG filesmust be placed in the/svg/solid/ directory
  • All flag icon SVG filesmust be named following the format{country code}.svg andmust be placed in the/svg/flags/ directory. All country codes must be two-character strings.
  • All multi-color SVG filesmust be placed in the/svg/multi-color/ directory
• have a default size of24px when they are exported
• be sourced from and approved of by Kong's Design team

To add a new SVG:

1. Ensure the SVG has been exported from the Design team (donot create custom SVG files)
   1. Iconsmust follow the viewbox and color guidelines to match the standard of existing icons. New icons can be requested on Slack in#ask-kong-design-system
2. Ensure the filename is lowercase and kebab-case
3. Place the SVG file into the corresponding/svg/* subdirectory.
4. Locally, runpnpm generate to create the corresponding Vue component
5. Locally, runpnpm test --update to run the tests and update the test snapshots
6. Commit your changes and push up a Pull Request for review

This repository includes a Vue sandbox app (see the/sandbox directory) to allow you to experiment with icons.

Thepnpm dev command will automatically call thegenerate command to generate the icon components.

To compile the icon components and start the sandbox:

# Generate the Icon Components and start the sandboxpnpm dev

To run a local preview of the Sandbox site that will be deployed to GitHub Pages:

pnpm build:sandboxpnpm preview:sandbox

Lint package files, and optionally auto-fix detected issues.

# Lint onlypnpm lint# Lint and fixpnpm lint:fix

Unit and component tests are run withVitest.

The Vitest settings are pre-configured to regenerate the icon components before every run.

# Run testspnpmtest# Run tests in the Vitest UIpnpm test:open# Update test snapshotspnpmtest --update

When SVG files are added or removed, this will cause the test(s) that compare snapshots to fail. If the snapshot change is expected, runpnpm test --update to update the test snapshots accordingly, then commit those changes to your branch.

Process the/svg/ directory, generate the icon components and associated files, and build for production.

pnpm build

This repo usesConventional Commits.

Commitizen andCommitlint are used to help build and enforce commit messages.

It ishighly recommended to use the following command in order to create your commits:

pnpm commit

This will trigger the Commitizen interactive prompt for building your commit message.

Lefthook is used to manage Git Hooks within the repo.

• Acommit-msg hook is automatically setup that enforces commit message stands withcommitlint, seelefthook.ymal
• Apre-push hook is used that runseslint before allowing you to push your changes to the repository

Additionally, CI will usecommitlint to validate the commits associated with a PR in theLint and Validate job.

• All pull requests require review and approval from authorized team members.
• Automated approvals through workflows are strictly prohibited.
  • There is an exception for automated pull request approvals originating from generated dependency updates that satisfy status checks and other requirements.
• Protected branches require at least one approval from code owners.
• All status checks must pass before a pull request may be merged.

This repository utilizesSemantic Release for automated package publishing and version updates.