|
| 1 | +# Spectrum Token Visualization Tool |
| 2 | + |
| 3 | +Current url of deployed static site: [https://opensource.adobe.com/spectrum-tokens/visualizer/](https://opensource.adobe.com/spectrum-tokens/visualizer/) |
| 4 | + |
| 5 | +<img width="1491" alt="Screenshot 2023-02-28 at 2 40 02 PM" src="https://github.com/adobe/spectrum-tokens/assets/125516/3c57f2de-c42e-41a5-abed-e5da294339f0"> |
| 6 | + |
| 7 | +## Setup for local development |
| 8 | + |
| 9 | +First, checkout the source code |
| 10 | + |
| 11 | +``` |
| 12 | +git clone [email protected]:adobe/spectrum-tokens.git |
| 13 | +``` |
| 14 | + |
| 15 | +Navigate into the spectrum-token-visualization-tool directory. |
| 16 | + |
| 17 | +``` |
| 18 | +cd spectrum-tokens/docs/visualizer/ |
| 19 | +``` |
| 20 | + |
| 21 | +Install package dependencies |
| 22 | + |
| 23 | +``` |
| 24 | +pnpm install |
| 25 | +``` |
| 26 | + |
| 27 | +Startup the local development webserver |
| 28 | + |
| 29 | +``` |
| 30 | +pnpm moon run visualizer:dev |
| 31 | +``` |
| 32 | + |
| 33 | +Now you can edit any project files, and your browser will hot-reload with your changes. |
| 34 | + |
| 35 | +This project is based on the Vite Lit Element Typescript boilerplate static site tooling. |
| 36 | + |
| 37 | +You can read all about Vite here: https://vitejs.dev/guide/ |
| 38 | + |
| 39 | +You can read all about Lit Element here: https://lit.dev/docs/api/LitElement/ |
| 40 | + |
| 41 | +_LOCAL DEVELOPMENT NOTE_ |
| 42 | +Because we use web workers to offload some of the data processing, local development must be done in a browser that supports Worker Ecmascript Modules: https://caniuse.com/mdn-api_worker_worker_ecmascript_modules. In other words, you can use Chrome or Safari, but NOT Firefox ( as of 12.15.2022 ). This note applies ONLY to the local development webserver. Firefox does work correctly with the built static site. |
| 43 | + |
| 44 | +## Updating the deployed static site |
| 45 | + |
| 46 | +The static site is hosted from the `/docs` directory of the `main` branch. |
| 47 | + |
| 48 | +Build the static site locally. This will overwrite the contents of the /docs directory in the project. |
| 49 | + |
| 50 | +``` |
| 51 | +pnpm moon run visualizer:build |
| 52 | +``` |
| 53 | + |
| 54 | +Commit the updated static site files to the git repo. |
| 55 | + |
| 56 | +``` |
| 57 | +git add . |
| 58 | +
|
| 59 | +git commit -m 'description of changes' |
| 60 | +
|
| 61 | +git push |
| 62 | +``` |
| 63 | + |
| 64 | +## What is this prototype? How does it work? |
| 65 | + |
| 66 | +The Spectrum Tokens source-of-truth is persisted in this public GitHub repo: https://github.com/adobe/spectrum-tokens |
| 67 | + |
| 68 | +Within that repository, the tokens are stored in a series of JSON files: https://github.com/adobe/spectrum-tokens/tree/beta/src |
| 69 | + |
| 70 | +This json data structure models a directed graph of conditional relationships between tokens, meant to represent the dynamic value assignments that Spectrum clients have access to when using particular filter configurations, such as 'Spectrum/Light/Desktop' or 'Express/Darkest/Mobile'. |
| 71 | + |
| 72 | +This tool is a static site single page application that... |
| 73 | + |
| 74 | +- Loads all of these JSON files via XHR requests at runtime |
| 75 | +- Converts the token data into a formal node graph |
| 76 | +- Has nodes representing Spectrum Tokens, Spectrum Components, and Spectrum Token Categories |
| 77 | +- Has adjacencies between nodes derived from the source JSON files |
| 78 | +- Renders a dynamic node graph view with zooming and panning |
| 79 | +- Permits the user to simultaneously view any set of adjacency/value filters. eg.'Spectrum/Light/Desktop' or 'Express/Light/Dark/Darkest/Desktop/Mobile' |
| 80 | +- Permits the user to select any combination of Components, Tokens, and Token Categories |
| 81 | +- Permits the user to search for Components, Tokens, and Token Categories by substring OR value |
| 82 | +- Displays the expanded Ancestor and Descendent graphs of all selected nodes |
| 83 | +- Highlights the connecting token paths between selections |
| 84 | +- Highlights the common tokens within overlapping selection descendent graphs |
0 commit comments