|
| 1 | +# Contributing to Wokwi Elements |
| 2 | + |
| 3 | +First of all, thank you for considering contributing to Wokwi Elements! |
| 4 | +Please go over these guidelines to ensure that your contribution lands |
| 5 | +successfully. |
| 6 | + |
| 7 | +## Creating a New Element |
| 8 | + |
| 9 | +Before starting to work on a new element, please |
| 10 | +[file an issue](https://github.com/wokwi/wokwi-elements/issues/new/choose) |
| 11 | +to discuss the implementation. |
| 12 | + |
| 13 | +Also, please make sure that any 3d-party graphics that you use |
| 14 | +for the element is released under a permissive license (such as |
| 15 | +MIT, BSD, Apache, or CC-BY), and that you give credits to the |
| 16 | +original authors as required. |
| 17 | + |
| 18 | +To create the element, use our hygen generator, by running: |
| 19 | + |
| 20 | +``` |
| 21 | +npm run new-element --name demo |
| 22 | +``` |
| 23 | + |
| 24 | +Replacing `demo` with your actual element name (e.g. `led`). |
| 25 | + |
| 26 | +Running this command will also generate a Storybook file for |
| 27 | +the new element. You can then start Storybook by runnning: |
| 28 | + |
| 29 | +``` |
| 30 | +npm run storybook |
| 31 | +``` |
| 32 | + |
| 33 | +This will open a local dev server at http://localhost:6006, where you |
| 34 | +can interact with your new element and see any changes live, similar to |
| 35 | +https://elements.wokwi.com. |
| 36 | + |
| 37 | +## Element Guidelines |
| 38 | + |
| 39 | +Please make sure to follow these guidelines when working on your new element: |
| 40 | + |
| 41 | +1. If the element is an input element (knob, button, slider, etc.), it has |
| 42 | + to be keyboard accessible (i.e. adding the `tabindex` attribute, listening |
| 43 | + for the `keydown` and `keyup` events, etc). |
| 44 | +2. Make sure that your element renders well and functions on mobile devices. |
| 45 | +3. Add docstring to the element class and any public properties/methods. These |
| 46 | + doc strings will appear in the Docs tag in storybook. Check out the [Resistor |
| 47 | + Element](src/resistor-element.ts) for an example. |
| 48 | +4. Your commit messages should follow the [conventional commits |
| 49 | + standard](https://www.conventionalcommits.org/), e.g.: |
| 50 | + `feat: add neopixel element` |
| 51 | + |
| 52 | +## Video Tutorial and Blog Post |
| 53 | + |
| 54 | +The [Membrane keypad element live-coding video tutorial](https://www.youtube.com/watch?v=gh27icNatwA) walks |
| 55 | +through the complete process behind creating an element: research, drawing, and writing the code / |
| 56 | +stories. |
| 57 | + |
| 58 | +If you prefer reading over watching a video, please check out [Recreating The Arduino Pushbutton Using SVG And <lit-element>](https://www.smashingmagazine.com/2020/01/recreating-arduino-pushbutton-svg/). |
0 commit comments