Doc: WebHost: update readme and style guide (#4853)

* Doc: WebHost living standard

* Docs: update style guide for HTML, CSS and JS

* Unblame phar

* Too many words

* The better choice

* More rules

* Removed too much

* Docs: add recommendations for script defer and async

WebHostLib/README.md

@@ -1,46 +1,20 @@
 # WebHost
 
+## Asset License
+
+The image files used in the page design were specifically designed for archipelago.gg and are **not** covered by the top
+level LICENSE.
+See individual LICENSE files in `./static/static/**`.
+
+You are only allowed to use them for personal use, testing and development.
+If the site is reachable over the internet, have a robots.txt in place (see `ASSET_RIGHTS` in `config.yaml`)
+and do not promote it publicly. Alternatively replace or remove the assets.
+
 ## Contribution Guidelines
-**Thank you for your interest in contributing to the Archipelago website!**  
-Much of the content on the website is generated automatically, but there are some things
-that need a personal touch. For those things, we rely on contributions from both the core
-team and the community. The current primary maintainer of the website is Farrak Kilhn.
-He may be found on Discord as `Farrak Kilhn#0418`, or on GitHub as `LegendaryLinux`.
 
-### Small Changes
+Pages should preferably be rendered on the server side with Jinja. Features should work with noscript if feasible.
-Little changes like adding a button or a couple new select elements are perfectly fine.
+Design changes have to fit the overall design.
-Tweaks to style specific to a PR's content are also probably not a problem. For example, if
-you build a new page which needs two side by side tables, and you need to write a CSS file
-specific to your page, that is perfectly reasonable.
 
-### Content Additions
+Introduction of JS dependencies should first be discussed on Discord or in a draft PR.
-Once you develop a new feature or add new content the website, make a pull request. It will
-be reviewed by the community and there will probably be some discussion around it. Depending
-on the size of the feature, and if new styles are required, there may be an additional step
-before the PR is accepted wherein Farrak works with the designer to implement styles.
 
-### Restrictions on Style Changes
+See also [docs/style.md](/docs/style.md) for the style guide.
-A professional designer is paid to develop the styles and assets for the Archipelago website.
-In an effort to maintain a consistent look and feel, pull requests which *exclusively*
-change site styles are rejected. Please note this applies to code which changes the overall
-look and feel of the site, not to small tweaks to CSS for your custom page. The intention
-behind these restrictions is to maintain a curated feel for the design of the site. If
-any PR affects the overall feel of the site but includes additive changes, there will
-likely be a conversation about how to implement those changes without compromising the
-curated site style. It is therefore worth noting there are a couple files which, if
-changed in your pull request, will cause it to draw additional scrutiny.
-
-These closely guarded files are:
-- `globalStyles.css`
-- `islandFooter.css`
-- `landing.css`
-- `markdown.css`
-- `tooltip.css`
-
-### Site Themes
-There are several themes available for game pages. It is possible to request a new theme in
-the `#art-and-design` channel on Discord. Because themes are created by the designer, they
-are not free, and take some time to create. Farrak works closely with the designer to implement
-these themes, and pays for the assets out of pocket. Therefore, only a couple themes per year
-are added. If a proposed theme seems like a cool idea and the community likes it, there is a
-good chance it will become a reality.

docs/style.md

@@ -47,21 +47,27 @@
 
 ## HTML
 
-* Indent with 2 spaces for new code.
+* Indent with 4 spaces for new code.
 * kebab-case for ids and classes.
+* Avoid using on* attributes (onclick, etc.).
 
-## CSS
+## CSS / SCSS
 
-* Indent with 2 spaces for new code.
+* Indent with 4 spaces for new code.
 * `{` on the same line as the selector.
-* No space between selector and `{`.
+* Space between selector and `{`.
 
 ## JS
 
-* Indent with 2 spaces.
+* Indent with 4 spaces.
-* Indent `case` inside `switch ` with 2 spaces.
+* Indent `case` inside `switch ` with 4 spaces.
-* Use single quotes.
+* Prefer double quotation marks (`"`).
 * Semicolons are required after every statement.
+* Use [IIFEs](https://developer.mozilla.org/docs/Glossary/IIFE) to avoid polluting global scope.
+* Prefer to use [defer](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script#defer)
+  in script tags, which retains order of execution but does not block.
+* Avoid `<script async ...` in most cases, see [async and defer](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/script#async_and_defer).
+* Use addEventListener.
 
 ## KV