@kong/icons 0.0.2-pr.1.d267e1f.0 → 0.0.2-pr.7.742a879.0

package/README.md

@@ -1,15 +1,107 @@
 # Kong Icons
 
-Kong's open-source icon component library.
+Kong's open-source, Vue icon component library, partially sourced from [Google's Material Symbols](https://fonts.google.com/icons).
 
+Vue components are generated from SVG source files located in the `/svg/` directory.
+
+- [Usage](#usage)
+  - [Installation](#installation)
+  - [Import](#import)
+  - [Component Props](#component-props)
 - [Contributing \& Local Development](#contributing--local-development)
-  - [SVG Requirements](#svg-requirements)
+  - [SVG file requirements](#svg-file-requirements)
   - [Development Sandbox](#development-sandbox)
   - [Lint and fix](#lint-and-fix)
+  - [Testing](#testing)
   - [Build for production](#build-for-production)
   - [Committing Changes](#committing-changes)
   - [Package Publishing](#package-publishing)
 
+## Usage
+
+### Installation
+
+Install the `@kong/icons` package in your host project.
+
+```sh
+yarn add @kong/icons
+```
+
+### Import
+
+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.
+
+```html
+<template>
+  <button>
+    Add a service
+    <AddIcon size="24" />
+  </button>
+</template>
+
+<script setup lang="ts">
+import { AddIcon } from '@kong/icons'
+</script>
+```
+
+### Component Props
+
+#### `title`
+
+- type: `String`
+- required: `false`
+- default: `''`
+
+The accessibility text provided to screen readers.
+
+#### `color`
+
+> **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.
+
+#### `display`
+
+- type: `String`
+- required: `false`
+- default: `'block'`
+
+Set the CSS `display` property for the icon wrapper element.
+
+#### `decorative`
+
+- 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.
+
+#### `size`
+
+- 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.
+
+#### `tag`
+
+- type: `String`
+- required: `false`
+- default: `'span'`
+
+The HTML tag to use in place of the default wrapper `<span>` tag.
+
 ## Contributing & Local Development
 
 To get started, install the package dependencies
@@ -18,16 +110,27 @@ To get started, install the package dependencies
 yarn install --frozen-lockfile
 ```
 
-### SVG Requirements
+### SVG file requirements
+
+Source SVG files **must**:
 
-<!-- TODO: Add a script rule to enforce -->
-- Source svg filenames must be unique, regardless if they are in a subdirectory
+- 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 `flag-{country code}.svg` and **must** be placed in the `/svg/flags/` directory
+  - All multi-color SVG files **must** be placed in the `/svg/multi-color/` directory
+- have a **unique**, `kebab-case` filename, regardless of the `/svg/*` subdirectory they are located in
+- have a default size of `24px` when they are exported
+- be sourced from and approved of by Kong's Design team
 
 ### Development Sandbox
 
-This repository includes a Vue sandbox (see the `/sandbox` directory) to allow you to experiment with icons.
+This repository includes a Vue sandbox app (see the `/sandbox` directory) to allow you to experiment with icons.
 
-To start the sandbox:
+Before running the local dev server, you will need to run the generate command.
+
+> **Note**: You must regenerate the icons and restart the sandbox if you make changes to files outside of the `/sandbox/` directory.
+
+To compile the icon components and start the sandbox:
 
 ```sh
 # Generate the Icon Components
@@ -49,9 +152,28 @@ yarn lint
 yarn lint:fix
 ```
 
+### Testing
+
+Unit and component tests are run with [Vitest](https://vitest.dev/).
+
+The Vitest settings are pre-configured to regenerate the icon components before every run.
+
+```sh
+# Run tests
+yarn test
+
+# Run tests in the Vitest UI
+yarn test:open
+
+# Update test snapshots
+yarn 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 `yarn test -u` to update the test snapshots accordingly, then commit those changes to your branch.
+
 ### Build for production
 
-Utilize the `style-dictionary` CLI to build the token assets for production based on the configuration in `/config.js`.
+Process the `/svg/` directory, generate the icon components and associated files, and build for production.
 
 ```sh
 yarn build