Kong's open-source, Vue icon component library, partially sourced from Google's Material Symbols.
View all available icons: http://kong.github.io/icons/
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
<AddIcon size="24" />
</button>
</template>
<script setup lang="ts">
import { AddIcon } from '@kong/icons'
</script>
- type:
String
- required:
false
- default:
''
The accessibility text provided to screen readers.
Note: The
color
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 or currentColor
, which inherits the text color of the icon's parent element.
- type:
String
- required:
false
- default:
'block'
Set the CSS display
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 a number
, e.g. 24
or as a string that can be converted to an integer, such as '48'
.
When utilizing a string
, 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.
<CloseIcon as="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 files must:
- have a unique, lowercase and kebab-case filename, regardless of the
/svg/*
subdirectory they are located in- file names must not include the word
icon
(the suffix is automatically added during component generation) - the resulting exported icon name will be a PascalCase file with an added
Icon
suffix (e.g.kebab-case.svg -> KebabCaseIcon.vue
)
- file names must not include the word
- be stored in the
/svg/
directory- All solid (single-color) icon SVG files must be placed in the
/svg/solid/
directory - All flag icon SVG files must be named following the format
{country code}.svg
and must be placed in the/svg/flags/
directory. All country codes must be two-character strings. - All multi-color SVG files must be placed in the
/svg/multi-color/
directory
- All solid (single-color) icon SVG files must be placed in the
- have a default size of
24px
when they are exported - be sourced from and approved of by Kong's Design team
To add a new SVG:
- Ensure the SVG has been exported from the Design team (do not create custom SVG files)
- Icons must 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
- Icons must follow the viewbox and color guidelines to match the standard of existing icons. New icons can be requested on Slack in
- Ensure the filename is lowercase and kebab-case
- Place the SVG file into the corresponding
/svg/*
subdirectory. - Locally, run
pnpm generate
to create the corresponding Vue component - Locally, run
pnpm test -- -u
to run the tests and update the test snapshots - 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.
The pnpm dev
command will automatically call the generate
command to generate the icon components.
To compile the icon components and start the sandbox:
# Generate the Icon Components and start the sandbox
pnpm dev
To run a local preview of the Sandbox site that will be deployed to GitHub Pages:
pnpm build:sandbox
pnpm preview:sandbox
Lint package files, and optionally auto-fix detected issues.
# Lint only
pnpm lint
# Lint and fix
pnpm lint:fix
Unit and component tests are run with Vitest.
The Vitest settings are pre-configured to regenerate the icon components before every run.
# Run tests
pnpm test
# Run tests in the Vitest UI
pnpm test:open
# Update test snapshots
pnpm test -u
When SVG files are added or removed, this will cause the test(s) that compare snapshots to fail. If the snapshot change is expected, run pnpm test -u
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 uses Conventional Commits.
Commitizen and Commitlint are used to help build and enforce commit messages.
It is highly 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.
- A
commit-msg
hook is automatically setup that enforces commit message stands withcommitlint
, seelefthook.ymal
- A
pre-push
hook is used that runseslint
before allowing you to push your changes to the repository
Additionally, CI will use commitlint
to validate the commits associated with a PR in the Lint and Validate
job.
This repository utilizes Semantic Release for automated package publishing and version updates.