6.S063 Design for the Web: Languages and User Interfaces

← Assignment 11

Assignment 12

Due

Submitting your homework

We are going to use Github Classroom for this assignment. You need to have an account on GitHub and be logged in. Authorize Github Classroom here and accept the assignment, then follow the instructions there. Please follow the structure and naming of the starter repo, though you can add any additional files if you need them.

Please make sure each of your exercise-N directories are self contained, i.e. that you don't reference any files outside of the directory (e.g. from your repo root or other exercises). While having a common assets directory for all your exercises might be a good idea in general, we extract each exercise directory separately (as it may be graded by different people), and that will result in your pages not working correctly. Do not use root-relative URLs that expect a local server to run at a specific directory within your repo, and if you cannot avoid it, please document it in a README otherwise links may be broken for whomever is grading your homework.

If you submit after the deadline, it will count towards your slack hours.

Exercise 0: Recovering half credit from HW10 and HW11 (0 – 20% of HW10, 0 – 23.5% of HW11)

If there were any chat app features you did not get to implement in HW10 and HW11, any bugs you didn’t get around to fixing before the deadline, or any flaws pointed out by graders, you can recover half the credit by doing the work now!
**Deliverable:** Your customized prototype of the chat/messaging app in a `chat-client` directory Include a short description of what work you did from HW10 and HW11 in `chat-client/makeup-work.html`. If you are addressing a flaw pointed out by graders, please include how many points you lost for that flaw.

Exercise 1A: Dabbling with data visualization (25%)

**Important:** You only need to do ONE of 1A, 1B not both! If you choose 1A, please delete the `exercise-1b` directory.
Find an open dataset and create a visualization that will provide some insights on this data that one cannot get by simply looking at raw data. Here are some websites you can use that contain open datasets for a variety of topics: - [Data.gov](https://data.gov/) - [World Bank Open Data](https://data.worldbank.org/) - [CDC COVID-19 data](https://data.cdc.gov/browse?tags=covid-19) - [European COVID-19 data](https://www.ecdc.europa.eu/en/covid-19/data) - [Google Health COVID-19 Open Data Repository](https://health.google.com/covid-19/open-data/) If the data you find is only available in CSV/TSV formats, you can convert it to JSON using [PapaParse](https://www.papaparse.com/). Carefully consider the type of visualization that will be most useful. To create the visualization, you can use [Apache eCharts](https://echarts.apache.org/en/index.html). We have found that library to be easy to use and to produce good looking results, but you are free to use any other (or even none if you feel particularly adventurous).
**Deliverable:** An HTML page with your visualization(s). We want the visualization(s) to be generated via JS, do not submit screenshots. Include a few words about why you chose that particular type of visualization, what point it's making, as well as where the dataset is from. Include a `data.json` file with your dataset. If you had to write code to convert the data to JSON, include file with the original data as well.

Exercise 1B: Design your own CSS feature! (25%)

**Important:** You only need to do ONE of 1A, 1B not both! If you choose 1B, please delete the `exercise-1a` directory.
Now that you've used web technologies for quite some time, are there any features you wish CSS had? Write a proposal aimed at the CSS Working Group for your feature. Your feature could be a property, new value(s) for an existing property, new selectors, new @-rules etc. Make sure to discuss: - **Most important:** Motivation. Clearly explain the use cases your feature solves, with examples. Think about generality, typically features that are too specific to a few niche use cases are rejected. - How your feature solves the use cases you mentioned. - Proposed syntax. It's ok if this is not fully fleshed out, but a few ideas help ground the proposal. - If a property: think of initial value, interpolation, whether it inherits, any shorthands/longhands - Edge cases: what happens when you have unexpected inputs? E.g. for a layout mode, a window too narrow, or too wide, or too much content, or too little. - Which CSS module would it be a part of? While not graphical, languages are also a UI, so try to think about the usability principles you have learned while designing your feature. Make sure to avoid proposing features that could create cycles, as these are not implementable. E.g. suppose you wanted to propose a new pseudo-class ":max-width()" which only applies when the element’s width is smaller than the argument. However, this can trivially produce cycles: ```css .comment:max-width(500px) { width: 600px; } ``` Same goes for algorithms that require multiple passes to settle. While these are not a hard no like cycles, they are strongly avoided. Also avoid proposing features that would change the way existing websites look that are written with current CSS code. Even if you'd consider the change an improvement, browsers would be very reluctant to implement your feature. You may find the [Web Platform Design Principles](https://www.w3.org/TR/design-principles/) useful, especially the ones about CSS.
**Deliverable:** HTML writeup of your proposal. Include figures that showcase examples of how your CSS feature would look for certain values.
Important: You only need to do ONE of 1A, 1B not both!

Exercise 2: Publish your own open source Web Component! (72%)

In this exercise, you will create an open source web component for use by other developers and you will publish it on GitHub. This homework will guide you on creating an open source project for your component start to finish, so that you end up with something that is actually usable by other people in their projects. Visit [this spreadsheet](https://docs.google.com/spreadsheets/d/1ORBZS96kjzvXtqDvk-U0a5OQHaLFLw0-3xQIn_iieCY/edit?usp=sharing) to sign up for the web component that you will make. Since this work will happen in the open, only one student can sign up for each component, so sign up quickly or you may not have many options! There are more components listed than active students, so you can change your mind at any point up to the deadline, but please free up your previous component before signing up for a different one. If you want to make something that is not listed, great! We love initiative. Just check with us on Piazza so we can make sure the scope is appropriate. *(The percentages below add up to 100% and correspond to percentages **of this exercise**, not of the entire assignment)* ## Step 1: Design your component’s API and document it (20%) Start a new public repository in your GitHub.com account, and include one or more HTML pages describing your component's API (HTML attributes, children, CSS properties, CSS parts, events, JS methods, JS accessors etc) in a directory called `docs/`. It is important that you do this before writing code, since that way it's easier to focus on what design decisions are best for usability without making compromises to facilitate implementation. It’s the same reason we design graphical interfaces before writing code to implement them. Your component API shoud include at least… - One reflected attribute-property - Two custom CSS properties or one [CSS part](https://developer.mozilla.org/en-US/docs/Web/CSS/::part). Take some time to consider whether parts or properties are more appropriate for the kind of styling you want to expose (the answer may well be both, this is common). - One event, unless not applicable Your documentation should also include code that someone could copy and paste into their own project to use your component (`<script>` tags and/or JS `import` statements). Make sure this code does not depend on any local or localhost URLs, remember your are building a real component for real people to use.
Remember your component needs to be usable (at least for common use cases) by people who cannot write any JS. For example, if you are making a data visualization component, it cannot be accepting its data only via JS, since then it's useless to someone who cannot write JS.
Do not create elaborate styles for your component, it needs just enough CSS to be functional and usable. Look at built-in elements to get an idea of what "plain but functional means". Many web components currently on the Web include a lot of theming CSS that should be the responsibility of the component consumer (or a separate CSS library).
## Step 2: Research prior art and if necessary, iterate (5%) Now that you have designed an API for the component you will build without any outside influences, research existing web components doing the same thing and see how your API compares. If there are no web components doing the exact same thing, research web components doing similar things. What does their API (both in terms of HTML syntax as well as JS and CSS) do well and what could be improved? How does their API compare to the one you designed? Is your API easier to use, or did looking at prior art inspire you to make changes? (both are fine, just document them) - If your API is easier to use, explain why - If you made changes to your API, briefly describe what you changed Include links to the web components you examined in your writeup. ## Step 3: Make a homepage for your component, with demos (20%) Add an `index.html` page introducing your component and showcasing your component with different configurations. You should create at least 5 demos (the more the better), and each demo should include both a live rendering of the component, as well as the HTML (and CSS and JS, where applicable) code used to create it. You could also include some of the demos on a separate page, if that works better. At least one of your demos should showcase the component state reactively updating via JS. Again, start this *before* you actually implement the component. The demos will not work at first since there will be no implementation, but they will allow you to experiment with syntax for different use cases and see if it feels natural. You may realize the API you designed is not ideal and go back to step 1 and change it, that's fine (in fact, it's iterative design in action!). If you do make changes at this stage, please describe them in your writeup. ## Step 3: Add a LICENSE file (2%) Don’t forget to [include a license file in your repo](https://docs.github.com/en/communities/setting-up-your-project-for-healthy-contributions/adding-a-license-to-a-repository), otherwise other people will not be able to legally use your work in their projects. We recommend an [MIT license](https://en.wikipedia.org/wiki/MIT_License) but you’re free to use anything you like. We strongly recommend using a license that will allow people to use your component for free in their projects, since otherwise it's not open source. ## Step 4: Actually implement your component (50%) Include all code for your component in `.js` or `.mjs` files in a `src/` directory. Shadow DOM CSS should live in a separate `.css` or `.js`/`.mjs` file. You may use plain vanilla JS, [Lit](https://lit.dev/), or any of the custom element libraries listed [here](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements#libraries). If you use a library, link to it via an `import` statement that points to a URL so that your component can still be used via a single `import` statement or `<script>` tag. You can implement any number of other components that may be needed for your component (e.g. if your component is about tabs, you may want to also have components for tab panels and/or tabs). Use separate files for each class, with the class being the default export of the file that contains it. ## Step 5: Publish your component (3%) [Publish your website using GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site#creating-your-site=) and add that URL and a description in your repo's details, so that it appears every time someone visits that repo. Add a `README.md` file in the root of your repo with a short description of what it is and links to the website you created. ## Step 6: Add your component to the gallery of 6.S063 components! (5%) Once you finish, send a [pull request](https://help.github.com/articles/using-pull-requests/) to add your component to the list of components in [this file](https://github.com/designftw/components/blob/main/components.json). Make sure to include all necessary information, and link to a picture of your component from your Github Pages website. You will be using and critiquing each other’s components in the last lab of this course. For this reason, even if you plan to use slack hours for this assignment, we expect you to make sure your component repo is in decent shape before lab time and that your component is usable and includes some documentation and examples/demos, even if some things are rough around the edges (no open source project is perfect anyway!).
**Deliverable:** HTML writeup with the research and design decisions described above, a link to your component repo, and a link to your component site.

Exercise 3: HW feedback (3%)

Since this is a new class, we need your constructive feedback about every aspect of it: lectures, homeworks, labs etc. Please fill in your feedback about HW11 AND HW12 in `hw-feedback/index.html`.