selfdefined / web-app Goto Github PK

As a visitor to selfdefined.app, I want to be able to easily identify the discrete sections on the homepage, so I can focus on one at a time.

In the homepage, the header / intro section and the dictionary section don't have vertical whitespace between them, making it tough to parse visually.

In particular, text that reaches the bottom of the header and the top of the dictionary seem to flow into one another with no indication that they are in separate sections. Example:

A solution would be to add margin-top to the second section.

Suggest adding "tone-deaf" to list of words defined and viable non-ableist alternatives, such as "insensitive" (I'm sure there are others as well.)

I asked @tatianamac on Twitter about the word 'dude'. She said these gender codified language belong in the app. Creating a new issue. Thank you, @tatianamac

Here is the tweet: https://twitter.com/TatianaTMac/status/1262982728481300480

I think dude—and other gender codified language—has its place in the app (and would welcome > you filing an issue).

First time, I was corrected when I used 'Hey guys' was by a slack bot. It made sense to me then and I understood I had to change. I find it difficult at first but I have improved a lot since.

I read this discussion in the comments of r/webdev subreddit. A person was educating why the usage of 'dude' was wrong. Like always, he was downvoted. There was a common trend in those discussions. "We use it as a gender neutral term. It is you who is thinking about the gender." These words are used by some female friends in passing. I understand subconsciously these small biases add up and this gender gap takes place. I know these words belong here. But how do I explain what's wrong with them? (May be not the place to ask either. Sorry about that.)

Because this project now outputs to /dist, the _site directory can be deleted. I double-checked and there appears to be no reference to _site in the code base; its use is overridden by .eleventyconfig.js

Add a Sass function to convert px to rem, so that contributers can still reference/use px but with the responsiveness of rems

Guide article:
https://css-tricks.com/snippets/sass/px-to-em-functions/

Found an instance of Preferred Pronouns in my application which I knew was incorrect as it implies gender is merely a preference. Would like a reference in selfdefinedapp that explains how to appropriately discuss pronoun usage.

https://twitter.com/TatianaTMac/status/1230611632352456704?s=20

(fwiw I'm happy to submit the PR for this just feel uneducated on the topic myself, doing more research before I submit)

Safari 12.1.2, macOS 10.14.6. Spotted as of just now.

If I load https://selfdefined.netlify.com/#crazy at a window width of ~1220px, the left-hand column layout leaks into the right-hand column:

As soon as I change the width of the window, the content reflows back into the two-column layout:

Thanks for writing up a definition for pronouns! I noticed what I think is an unfinished sentence under the Considerations subheading. I'm quoting the sentence below:

Hence, why it is important to

I would really appreciate it if the sentence were finished :)

Problem

The default focus indicators provided by some browsers and operating systems are inaccessible to many users. The below screenshot of selfdefined illustrates the default focus indicator in Firefox: a thin, dotted outline.

Solution

Use the :focus pseudoclass to define a custom color and style for the focus outline in selfdefined. Ensure that the color contrast is at least 3:1 with the background of the app.

The $primary-color defined in base.css would be a great solution here!

Further reading

• Understanding Success Criterion 2.4.7: Focus Visible
• Understanding Success Criterion 1.4.11: Non-text Contrast

There are several words and concepts that can be added to this project that are centered around fatphobia. They include (but aren't limited to):

• Fatphobia
• Fat shaming
• Overweight
• Obese

Problem

Right now, the Typekit font bundle significantly slows page-load times. In limited local testing, it adds >1 second to load time on a simulated "average" 3G connection. This number increases significantly on lower-quality simulated connections, leading to average load times >5 seconds on "regular 2G" simulations.

Since a significant number of users browse the web on their phones, we should do our best to load these fonts progressively, so that they do not block user interaction on the page.

Proposal

Use Filament Group's LoadCSS library to bring support for link rel="preload" to all browsers.

With lazy-loading established, we can use it in the future for other non-critical styles that we may write for the app.

Benefits & trade-offs

➕ Page load time will decrease; user will be able to read, interact with our content sooner

➖ Browser may re-paint if there's a significant delay in loading the typekit bundle

Hi all, really appreciated the work that @ovlb provided in PR #31.

I've cleaned the master branch by deleting the node_modules directory.

Edit: Creating an issue so I can connect a PR

With the merge of #31 we have some basic documentation on the website and in contributing.md. However, this needs to be fleshed out. The following points would need to be addressed:

• Preferred way of proposing/updating definitions is through issues.
• Add more examples to website docs
• Create issue templates (docs here) to help structuring contributions

Depending on the column flow, flags are occasionally split across two lines of text. More often it happens with longer words and longer flags.

Bienvenue ! If you would like to help translate words into French, please:

1. See selfdefined.app for current and complete list of English-defined words.
2. Read our Contributing Guidelines.
3. Comment here what definition(s) you would like to define.
4. Open a pull request with your translations.
5. Invite a colleague/friend to edit if you can. If you don't know anyone, we can help find an editor for you.

To Be Defined

• 👌 [ok sign] (#81)
• ableism (#81)
• Asian-American
• East Asian
• South Asian
• Southeast Asian
• barbaric
• bierasure
• biromantic
• bisexual
• cisgender (#81)
• crazy
• derpy
• digital Blackface
• dude
• dumb
• English as Second Language
• fatphobia
• gaslighting (#81)
• gender pronouns
• Hispanic
• hysterical
• Latin American/Latino/Latina
• Latinx
• mansplain
• minoritised
• minorities
• -misia
• neopronouns
• non-binary
• Obsessive Compulsive Disorder (OCD)
• Oriental
• overrrepresented majority
• pansexual
• performative allyship
• -phobia
• polyamory
• pow-wow
• preferred pronoun
• pronouns
• r-word
• sane
• sanity check
• savage
• spaz
• suicide
• tone-deaf
• transfeminine
• transgender
• underrepresented minority
• unreal
• white feminism
• white fragility (#81)
• women and people of colour

Overview

Currently, the tags (e.g., 🚨 ableist slur) operate as a visual overview. A page like ?ableist-slurs would exist.

To enhance this feature, we'd like to link those tags so that they show a view that includes:

• all terms that possess that tag
• an overview on the tag/what it means/caveats

Task Requires

• [UX/UI design] of what this page could look like
• [Frontend dev] Enhancing the tagging structure so that each tag label will automatically be added to the list
• [UX/UI design] Bringing tag design into the individual definition.njk template

Bruce Lawson wrote a very insightful article about the usefulness of <article> over <section>. Key points:

1. <section> communicates no semantic value for assistive technologies (whereas <article> does.
2. Apple’s Reader mode ignores content displayed in <section> in favour of content displayed in <article> (you can see this in action when you use Safari’s Reader mode on selfdefinedapp.com—only the top definition is displayed.)

He also includes a lovely little simile that made me understand the use of <article> better:

think of <article> not just as a newspaper article, or a blog post, but as an article of clothing — a discrete entity that can be reused in another context. So your trousers are an article, and you can wear them with a different outfit; your shirt is an article, and can be worn with different trousers;

This would not be a straight swap of <section> for <article>, as there are some semantic considerations, given that an article should have a heading (in theory the same goes for <section>. Perhaps some of the containers would be better suited as <section> or even <div> with an aria-label attribute (there’s a nice example in the article above.)

I don’t like to get too silly or argumentative about semantics, but in terms of inclusivity, I believe this is an easy win.

Having reviewed the CSS, I also believe no CSS is applied to the <section> element, so changing the HTML in this instance should not negatively impact any other part of the site.

First, this project is rad. :>

As someone who has practiced polyamory and other forms of ethical non-monogamy, I'd propose a change to polyamory's definition:

an umbrella term for various types of relationships where all partners involved consent to non-monogamy, such as open relationships, polycules, throuples, group marriages, etc.

While there are absolutely plenty of ways to practice polyamory, the greater umbrella term I've seen used most often is "ethical non-monogamy." In my experience, one of the stigmas polyamorous people face is that it's perceived as "just about sex," and it is often conflated with open relationships that are otherwise romantically exclusive as a result. What distinguishes polyamory ("many loves," albeit in an awkward union of Greek and Latin) is the conscious choice to cultivate and allow the space for multiple relationships that might be coded as romantic or quasi-romantic, which may or may not involve sex at all.

Would love to hear other thoughts on this.

Currently using Netlify DNS with Porkbun as domain registrar. I expect both selfdefined.app and www.selfdefined.app to forward to selfdefined.netlify.com and only the latter does.

Netlify Domain Settings

Porkbun DNS Settings

I'm not sure if I've set this up backwards.

Problem

Clicking on a definition scrolls the user to that definition, but:

• Keyboard focus remains on that link, which could confuse keyboard users and especially screen-reader users
• Because multiple definitions appear close together, it is not always obvious where a sighted user's attention should go

Proposed solution

• Use tabindex and javascript to move focus to the heading where a word is defined
• Apply a gentle, temporary highlight to the wrapper behind the definition, so sighted users know where to look

Further reading

This codepen on drawing attention to internal focus utilizes a pattern that I think would be helpful here.

Overview

Content warnings are current listed as a label, so it shows up on the homepage. It's looking a bit cluttered and lacks context.

Instead, the content warning flag should trigger adding a note to a word definition page to the effect of:

"You may want to add a content warning before discussing or showing imagery involving this topic, as it is a topic that can elicit negative feelings and visceral reactions like a panic attack or trauma. Content warnings usually take the form of: "Content warning: [topic]" and should precede the subject matter. Please ensure your content warnings are accessible."

Overview

It's common for people to use "sane" as a ableist slur as in "this is a sane pull request" or "our tests provide a sanity check". These usages imply that being sane is good and being neurodiverse is bad or a failure.

Submitting this issue first to get agreement and to discuss how to categorize it before I submit a PR. If this is a good addition, would we add it as it's own page or roll into https://www.selfdefined.app/definitions/crazy/?

Add code of conduct language to site. Eventually I would like to adjust/customise given the uniqueness of this project, but we need something in place immediately given the sensitivity of the discussions we have.

Contributor Covenant I think is a good place to start

Problem

• Self-Defined sometimes builds page titles in ways that don't accurately reflect the user's path through the site.
• There's no obvious breadcrumb path on the page as the user navigates the site.

Example

When the user interacts with the Documentation link, they're taken to a page whose title reads: "Docs « Documentation « Self-Defined". Because this title has three segments, users who read or hear it might believe they have taken two steps through the site when they have only taken one.

Navigating to an individual definition causes a similarly unexpected title-path jump.

Possible solutions

• Improve the pattern of page-titling such that titles are more predictable.
• Provide a navigation breadcrumb so the user can find their way through multiple navigation levels of the site.

In the case of the "Documentation" page and some others, we could "flatten" the title structure a bit more. "Documentation" is the root of the "Documentation" section; it does not need a third title segment.

Overview

Build a component that follows each definition that encourages readers to submit revisions if needed.

Recommendation would be to build a separate .njk block that can be called by the definition template.

Design

Threw together a rough wireframe in Figma. It's not in the correct fonts but should give you an idea of the general structure.

Reach out with any questions!

Hello!
I am learning a lot of things with self defined, even if the definitions are not in my native language, French. I was wondering if it was possible to propose translations for the existing definitions? In my case, I would be glad to help for the French ones.

I assume you would need several people speaking French (in this case) to review each proposed translation. Is it something that could be interesting?

Cheers! ❤️

Overview

As the project grows, having a full separate about page that explains the context for the project would be beneficial.

Things to cover

• Back story; why does this project exist and why is it important
• Caveats about how language evolves
• Caveats about how self-identifying terms do not necessarily always have consensus and how we shouldn't be seeking consensus
• Content warnings
• Usage/licensing
• Open source backbone of project
• Future plans

Helpful resources

• README

The standard markdown-it parser that ships with Eleventy does not parse emojis, which can lead to accessibility issues.

The ideal outcome has been described by Léonie Watson in her article Accessible emoji.

There is an existing plugin for markdown-it which has no accessible output by default but allows you to change it. Judging by the discussion in markdown-it/markdown-it-emoji#33 we also need to provide an own emoji library. 🤷‍♀️

As the site grows, the homepage gets more and more crowded and impossible to scan. I think we should link to detail pages for single definitions (e.g. /definitions/crazy instead of #crazy).

Edit: I keep track of this issue and update the to-do list in #75. So have a look there for the current status

Current pattern exists here:
https://codepen.io/tatianamac/pen/zYOqZRp

Headline overflows at below settings.

Challenge

I think Self-Defined's docs would benefit from both a content and structure overall. We have an opportunity to make navigating them more intuitive, and to use them to cover a broader base of knowledge. With these changes, we could make Self-Defined more beginner-inclusive and perhaps even teach them a few programming skills.

Goals

I'd love feedback on the matter of what, exactly, is in scope for this project. Some ideas:

• Write a page dedicated to helping the reader set up their local dev environment (Install each of: a text editor, Node, NPM, Git/Gitbash)
• Explain the technologies and languages used to write Self-Defined
  • What is Eleventy? How do I use Nunjucks? Explain a bit about each, and/or link to helpful reading
  • What is Sass and how do I use it to write CSS? Write or link to explanations
• Write a page or pages to walk through important parts of the code base
  • Explain our templates, layouts, shortcodes, and Eleventy config
  • Explain our Sass structure
• Make our definition examples more robust

I am happy to take on this project, and equally to share it with anyone who would like to help!

I think axe-core( https://github.com/dequelabs/axe-core ) is a lovely little tool we could incorporate into our dev workflow to catch any accessibility violations at the earliest. Would love to hear thoughts on this

Current type system does not necessarily scale well. Intentionally developing a system that does upon the current typography would be great!

Current

Ways to help

• Submit words and definitions through pull requests.
  

• Sponsor this work through GitHub Sponsors.
  

• Volunteer writing, design, dev help by DMing me @tatianatmac on Twitter.
  

Ideal

• Remove DM prompt.
• Link to readme/documentation
• Link to issues
• Generic way to contact
• Link to Open Collective or GitHub Sponsors.

Problem

The following screenshots show a link reading "Obsessive Compulsive Disorder (OCD)" as seen on the Self-Defined website, with the site's red custom focus drawn around it.

In Firefox, the outline is drawn around each line of the wrapped text, making the text hard to read.

In Safari and Chrome, the outline is drawn around the whole anchor element. This way, the outline does not obscure any text.

Possible fixes

@wuz (Conlin) suggested using text-decoration styling to restore word-level underline to links when they are rendered as inline-blocks. Here's Conlin's codepen demo.

The support matrix for text-decoration styling on caniuse looks good.

Edit:
I was initially stoked about Conlin's suggestion, but further research into custom underline properties made me sad. :(
We could also:

• display links as inline-block
• add a child span to them
• apply a bottom border to the child span instead of the link

This approach works in more browsers – even modern browsers do not support custom underlines with text-decoration properties – and is most like our current styles. I made a CodePen to compare the two approaches.

Details for nerds

As evidenced in the Firefox source code, this seems to be a known issue related to how Firefox chooses to draw the focus outline.

• allows folks to subscribe and keep up to date with new additions
• to check: curious if RSS/Atom can be setup to push edits/updates as well

And of course 11ty has a plugin for this: https://www.11ty.dev/docs/plugins/rss/

Reproduction steps:

1. Clone the selfdefined repo.
2. Install its dependencies (npm install).
3. Execute npm run build

Expected behavior:
The CSS, along with the other production files, is compiled into the dist directory, where it can be ignored by the developer's version control.

Actual behavior:
The CSS appears om /assets/css, where version control recognizes and attempts to track it.

Proposed solution:
Modify the build:css script so that parcel outputs to /dist/assets/css/

Improve documentation for defining words.
Use #70 for context.

• Share common resources
• Itemise different definition components (Avoid/Use Instead, etc) more fully
• Give do's and don't's
• Break down examples of specific definitions to illustrate nuance.
• Explicitly determine style guide (preferably common English external one like CMoS to start, then build upon with customisations as needed, i.e., using International English)

Challenge

As we've started to translate definitions into languages other than English, I'd like to make sure we're considering how to to show them both from a data management and design perspective.

Technical Considerations

• Translations will be spotty as they're done on an ad hoc basis. So, some words will have translations in some languages and not others.
• Full-site language switching is something we'll need to consider in the future, but is likely a bit silly until we hit a certain threshold.
• Storage/organisation: How should we manage the folder/hierarchical structure for translations? How do we make this clear when someone wants to contribute a definition?

Human Considerations

• Reviewing will require coming in with than one person who speaks the language beyond me (as I review most of the English translations)
• It could be weird to have some definitions have multiple translations and others have none.
• Do we allow words that do not yet have an English translation? For example, words that have consequence in another language but not English.

Next Steps

• Determine how to support translations in the short and long term
• Place within roadmap
• Create subsequent tasks

This article from the Simmons University Library is a great introduction to the differences and distinctions between the "-phobia" and "-misia" suffixes.

As noted in the Simmons article, the use of "-phobia" equates bigotry with mental health issues, and similar to other definitions in Self-Defined, it can also leave room for bad-faith arguments about how someone isn't "afraid" of x, they just don't like/believe in it etc.

There are a number of fat liberation activists writing about fatmisia, including Kivan Bay who also writes about the intersection of fatmisia and transmisia.

We could consider adding more data-driven links between definitions than just the alternative words we have currently.

The current state is on one-way. Define an alt-word, and it will be linked if it is defined. We can further add inbound links. Example: crazy links to unreal. We could add a «words that link here» (or similar) section inside the definition body of «unreal».

Another easily solvable content point is the linking of synonyms/antonyms. Live example for an antonym is cis-/transgender. At the moment, authors have to add the sentence «Opposite of xxx» themselves. my proposed solution is to add synonym and/or antonym to the front matter:

---
title: Cisgender
slug: cisgender
speech: adj
defined: true
antonym: transgender
---

of, relating to, or characterised by being a gender that matches the gender they were assigned at birth.

For synonyms, this might allow for a bit more nuance in the definitions, as the alt words are currently mostly in use to provide better suggestions.

Ensure considers accessibility per #48.

Tools to be integrated

• ESLint (#78)
• Prettier
• Stylelint (#92)
• Editorconfig
• axe
• Unit Testing (#78)
• Codecov (or a similar tool for collecting test coverage)
• e2e testing (Cypress?)

Dev infrastructure

These tooling will enable us to ensure consistent code quality across branches and remove the need for manual style corrections in PRs.

If we find a way to apply the formatting configured through the tools above for contributors who are not able to set up an advanced dev workflow on their machines (no shame in that) this will be A++.

• Husky or another solution for running npm scripts pre-push and/or -commit
• lint-staged
• CI (CircleCI or GitHub actions might make sense; CD is handled by Netlify)

There are probably things I miss right now. Will keep the list updated. And if anyone reading this has input, please post it!

This list shall act as a tracking issue.

If you want to work on integrating of one or more of these tools, please open a PR and I will link it in the list. Thanks.

EDIT: by @ovlb; added tracking list

Overview

As the product grows, the homepage will migrate away from being a long list of words and toward an overview of the product. Therefore, building in a search function will be one of many steps to accomplishing this.

Features

Minimum

Minimum feature expectations would include:

• serving a search results page

Advanced feature expectations would include:

• autofill considerations (though these are not often done accessibly)

Just what it says on the title. I would mark this one down to templating weirdness.

This screenshot shows the Firefox dev tools inspecting part of the footer. The documentation link appears 4 times, but only the first occurrence of the link has content. Empty links could confuse users, particularly those who rely on screen readers.

Further reading:

• Understanding WCAG SC 2.4.4: Link Purpose (In Context)
• Understanding WCAG SC 4.1.2: Name, Role, Value
• Links Must Have Discernible Text (Deque University)

Idea Summary

Netlify CMS allows users to create pull requests via the Netlify CMS interface. See: https://www.netlifycms.org/docs/open-authoring/

I think in terms of facilitating contributions from users who are less technically-savvy, this could be great! You log in with a GitHub account, use a CMS interface to create your definition, and then when you submit it for review, Netlify CMS opens a pull request in the background.

Prerequisites

This would require:

• Configuring the site for editing using Netlify CMS
• Enabling Netlify Open Authoring

The problem

The text color of all "avoid" warnings falls below the recommended text contrast threshold.

This screenshot shows the "Minorities" noun on selfdefined, as well as the red "avoid" warning above.

Proposed solution

Increase the color contrast of this warning, either by changing the red or adding a background to all signals. Selfdefined should target a contrast ration of at least 4.5:1 to meet WCAG AA, or 7:1 to meet WCAG AAA.

Further reading

• Understanding Success Criterion 1.4.3: Contrast (Minimum)

I don't think I could write a definition for it, but it's a word I've seen used more frequently in the last year or so. (It's not a word I use myself, and I don't yet have a good grasp on how it's used. Geez, if only there was a dictionary of words or something…)

Do you think it's appropriate here?

Hi! On my phone the intro paragraph / subheading of the site gets cut off.

I'm happy to submit a pr if desired—thank you for doing this work.