When creating products, accessibility can be an afterthought. Understandably, we want to ship our products fast and deliver value to our users. We might think that accessibility is needed for edge cases and therefore not prioritize it. It’s good to be reminded that the World Health Organization (WHO) estimates that 16% of the global population has some form of disability (Dec 2022).
Ignoring such a significant part of your user base simply doesn’t create a good user experience.
Creating accessible products is everyone’s responsibility. Designers, developers, content authors, and whoever else is involved in creating products should do their part and strive towards achieving a better experience for everyone.

It’s not always easy to maintain a high level of accessibility, but it’s definitely easier with a design system. The components we created in Pink Design, Appwrite’s fully open source UI library, have an accessibility level of AA. This is the recommended level of accessibility for most products.

To ensure our products will maintain a high accessibility level, we did the following:

Use high color contrast

Color contrast might be the first thing that comes to mind when thinking about accessibility. A lack of contrast between the text and background might mean some people would be unable or have difficulty reading the text. Similarly, bright colors with high luminance are not readable for others. W3C recommends a contrast ratio between text and background of 4.5 to 1 for conformance level AA.

Not relying on color

The term “color blindness” is often used to describe people who have trouble identifying and distinguishing between certain colors, but color blindness, the inability to see any color, is extremely rare. According to the United Kingdom National Health Service (NHS), red-green color blindness affects 1 out of 12 men and 1 out of 200 women. People with this color vision deficiency may have difficulty differentiating between reds, oranges, yellows, browns, and greens. They also might find it hard to distinguish between shades of purple and may confuse red with black.
Similarly, people with “blue-yellow” color vision deficiency may have difficulty differentiating between blues, greens, and yellows.

We use four system colors in Pink Design — red, orange, green, and blue. Each of these colors represents a state in the Appwrite console — red indicates an error or danger, orange indicates a warning, green indicates success, and blue indicates information. Knowing the difficulties our users might face while seeing these colors, we don’t rely on color to make critical information understandable.

Allow keyboard navigation

People with fine motor control restrictions or disabled hands or arms will be unable to use a mouse. In Pink Design, we provide distinct states for interactive elements. By designing states like focus, hover, and active, we provide the ability to navigate all interactive elements with a keyboard. This is not only an accessible experience but also a better experience for all users who prefer keyboard navigation, including Appwrite’s developer community.

It is possible to enhance accessibility through development as well. In collaboration with our engineering team, we decided to incorporate the following into Pink Design:

Define font size in REM

Browsers have a default font size that users can change via the browser setting. A pixel is an absolute unit for fixed sizes and spaces that ignores browser settings. This means that if we are using pixels and a user (with or without vision impairment) changes the font size in their browser settings, their setting won’t affect our product. That being said, pixels should not cause any problems if the user zooms in, but we make no assumptions about users’ preferences. This is why we decided to define the font size in REM, which is a relative unit.

Allow users to reduce motion

There is no doubt that animations are a nice addition to every product, but animations can also distract people. In some cases, animations can cause dizziness, vertigo, or epileptic seizures. Users that are sensitive to motion might choose to reduce motion in their operating system settings. In this case, we should skip the animation for them. In Pink Design, we decided to create a big animation to show the functionality of the library on the landing page. The animation is 10 seconds long and is the first thing you see on the page. It starts immediately when the page is loaded, but if “reduce motion” is enabled in the operating system, the animation skips to the end.

At Appwrite, accessibility is for sure a team effort. We are all working to maintain and improve the accessible experience in our products, and it’s always in our minds. Using accessible components help us improve our accessibility level, but it’s important to remember, there are many types of disabilities. We have worked on improving the experience for users with vision, mobility, and cognitive disabilities, and we will keep working to improve even further.

If you haven’t already, browse the 💻 Pink Design GitHub Repository or check out our 🚀 Getting Started Guide to use Pink Design in your projects or when contributing to Appwrite.

Accessibility in Pink Design was originally published in Appwrite on Medium, where people are continuing the conversation by highlighting and responding to this story.

However, in 2023, after obtaining most of the main features of CSS Logical Properties, supporting multi-direction language websites is now much easier.

Despite this, CSS Logical Properties still need to be improved and require additional solutions.

In this post, I want to examine how we solved the missing parts of supporting a multi-direction language website.

What are CSS Logical Properties?

Currently, most websites work with fixed axes according to physical directions, such as top/right/bottom/left.

We have our old, familiar CSS Physical Properties from those physical directions, such as margin-right, padding-bottom, border-left, and so on.

The Problem with Physical Properties

When enabling support for a language that goes right-to-left (direction: rtl), as well as left-to-right (direction: ltr), you need to create a kind of horizontal mirror of the website.

Creating the mirror requires a different set of CSS files if using Physical Properties.

Example of How a Multi-Direction Website Can Look Like:

CSS Logical Directions

This problem can be solved with CSS Logical Properties. Instead of the physical directions, we now have two axes:

• Inline axis — this is the axis of the text.
• Block axis — this is the axis of the flow of the website.

Each of those axes has a start and an end direction.

Inline-axis:
To describe the inline axis, we have its two directions:

• Inline-start — describes the start of the line of text; in English, this is the left.
• Inline-end — describes the end of the line of text; in English, this is the right.

Block-axis:
To describe the block axis, we have its two directions:

• Block-start — describes the start of the flow of the website; in English and most languages today, this is the top.
• Block-end — describes the end of the flow of the website; in English, and most languages today, this is the bottom.

CSS Logical Properties

From these logical directions, we obtain updates for most of our physical properties, for example:

margin-left => margin-inline-start
padding-top => padding-block-start

/* position properties - for example for: position: fixed; */

top => inset-block-start
bottom => inset-block-end
left => inset-inline-start
right => inset-inline-end 

When using the new CSS Logical Properties, the values flip according to the direction property value: ltr (left-to-right [default]) or rtl (right-to-left).

Example of left-to-right:

html {
  direction: ltr; /* default value */
}

div {
  margin-inline-start: 20px; /* = margin-left: 20px */
}

Example of right-to-left:

html {
  direction: rtl;
}

div {
  margin-inline-start: 20px; /* = margin-right: 20px */
}

What is Top and Bottom?

The top and bottom directions represent the block-axis, which is the main flow of the website.

Although it is not commonly used on the web, we can use the writing-mode property to affect the block-axis.

Note: Affecting the main flow of the website is made for Far East languages such as Chinese, in which the line of the text can be written from top to bottom.

writing-mode: horizontal-tb; /* top to bottom (default value) */
writing-mode: vertical-rl;   /* right to left */
writing-mode: vertical-lt;   /* left to right */

Changing the writing-mode value into vertical-lr or vertical-rl values will change to flow of the website from top-to-bottom to right-to-left or left-to-right. This means that the top is not the top anymore! The scroll is now horizontal instead of vertical, and the text goes from top to bottom.

Demo (by HJ Chen):

The writing-mode property is mostly unused; 99.99% of websites only work with direction set to ltr or rtl.

This also means that using the main axis/block axis properties, such as margin-block-start, does not typically affect us. However, I still prefer to use CSS Logical Properties throughout a website to be consistent.

Are CSS Logical Properties Good Enough?

CSS Logical Properties will do most of the job, but I encountered a few problems after using them. Let’s talk about those problems and how you can solve them.

Transform Properties

These days, we do most of the layout alignment with modules of CSS Flexbox and CSS Grid. However, in some cases, we want to position things via the transform property using the translateX() function, for example.

The problem with the transform property is that its axes do not work in logical directions. For example, transform: translateX(100px) will always move to the right, regardless of the direction value of the website.

transform: translateX(100px); /* will move the element always right */

Solution

If we need to translate an element based on the type of language, we need the value to change to a negative value instead of a positive value, or if it is negative, it will need to change to a positive one.

To do so, I create a CSS variable that by default has a value of 1.

:root {
  --transform-direction: 1;
}

I multiply this value with the translateX value using the CSS calc() function.

transform: translateX( calc(100px * var(--transform-direction)) );

With the default value of 1, the translation behaves the same.

Support for RTL languages:
Now, the only thing left for me to do is to change the value of the --transform-direction variable to -1.

To do so, I simply create another :root selector, which overrides only when the main <html> element has the native dir=”rtl” attribute on it.

:root[dir="rtl"] {
  --transform-direction: -1;
}

This will take effect only when the <html> element has the dir=”rtl” attribute:

<html dir="rtl">

Related Direction Arrows Icons

When changing the website direction, arrows can point in the wrong direction.

To solve this issue, we can again use the --transform-direction variable, but now in a slightly different way.

To flip the icon horizontally, I’m using the scaleX function of the transform property with the --transform-direction value.

Now, when the scaleX value of the transform property is equal to -1, this value will flip the arrows in the horizontal direction in their place.

.icon-arrow-left,
.icon-arrow-right {
  transform: scaleX(var(--transform-direction));
}

This opposite direction can look strange to us, but remember that this is to support right-to-left languages such as Arabic and Hebrew.

More Things

Some CSS Logical Properties, or more precisely, logical values, are currently not widely supported.

The float property has 2 new logical values: inline-start and inline-end. Unfortunately, for now, they are only supported in Firefox.

To solve this, I am adding two new variables that represent the start and the end of the line.

The default values, are for left-to-right languages, with the ability to override those values in case we have the dir=“rtl” attribute of the <html> element.

CSS Code Example:

/* default - left-to-right languages */
:root {
  --start-direction: left;
  --end-direction: right;
}

/* Support for right-to-left languages */
:root[dir="rtl"] {
  --start-direction: right;
  --end-direction: left;
}

Now the only thing left for me to do is to use the variables according to my need. Example:

float: var(--start-direction);

Those variables can be useful in more cases, such as setting the background-position property, for example:

background-position: var(--end-direction) top;
background-repeat: no-repeat;

CSS Variables for Help

As we saw here, I defined three CSS variables that helped me to complete the support of CSS Logical Properties.

The CSS code looks like this:

/* default - left-to-right languages */
:root {
  --transform-direction: 1;
  --start-direction: left;
  --end-direction: right;
}

/* Support for right-to-left languages */
:root[dir="rtl"] {
  --transform-direction: -1;
  --start-direction: right;
  --end-direction: left;
}

If you are using Sass preprocessor, you can write it in this way:

:root {
  /* default - left-to-right languages */
  --transform-direction: 1;
  --start-direction: left;
  --end-direction: right;

  /* Support for right-to-left languages */
  &[dir="rtl"] {
    --transform-direction: -1;
    --start-direction: right;
    --end-direction: left;
  }
}

To Summarize

In this post, we examined how you can support a multi-direction website.

The first step is to use native CSS Logical Properties wherever you can. The second step is to use additional CSS variables for the less supported CSS Logical Properties.

Final Words

Pink Design is finally out today. Pink Design was built with new inventive CSS methods, and prioritizes accessibility and developer experience. As a company developing an open-source product, this is a big step for Appwrite’s community of contributors. As always, we will keep improving Pink Design, allowing it to grow alongside Appwrite.

Thank you for being a part of our journey! If you haven’t already, browse the 💻 Pink Design GitHub Repository or check out our 🚀 Getting Started Guide to use Pink Design in your projects or when contributing to Appwrite.

Until next time!

Supporting CSS Multi Direction Languages in 2023 was originally published in Appwrite on Medium, where people are continuing the conversation by highlighting and responding to this story.

In this post, I want to explain how I work and organize the colors in our Pink Design system project.

Like everything in life, we have many good ways and even more wrong ways to do the same thing. Before I show you how I organize our CSS variables, let’s discuss the wrong ways to organize colors in CSS.

Note: some parts of our color architecture use Sass preprocess.

The Wrong Ways to Define CSS Color Variables

When reviewing other CSS architecture, I try to think of inefficiencies that make it difficult to maintain.

Using Globals variables for Everything Without Semantic Meaning

I took this small example using the inspect feature from the :root element on the LinkedIn website.

As you can see in the example below, there are more than 900 CSS variables on one :root selector!

Finding something in such an extensive list of variables is almost impossible.

Coupling Colors with Semantic Names

The second option I frequently see is global variable color with semantic names, such as --header-background-color.

The problem with defining logical global naming, first and foremost, is that you have too many of them.

The second problem with creating dark-mode themes is that web designers do not work with the logic that specific colors need to change to other colors in dark-mode. This can cause the creation of too many types of variables that are hard to understand or maintain.

Example from old Appwrite console 1.0:

Furthermore, the overrides of global colors make the code’s debugging unclear, with all the crossline of the overrides in the inspect element of Chrome.

After understanding these issues, I thought about how to better structure our CSS color variables.

How We Decided to Manage Our CSS Color Variables

My main idea was to create a CSS variable for every color group family on the hue spectrum that would connect every group of colors (e.g., blue, green, orange, and red). In this way, I can change the primary hue of each color group and easily replace all shades of this color family.

The only issue I had with this approach was that the color had been defined with hex code colors, by the design team, which are a type of RGB colors and are more difficult to use when creating different shades of the same hue.

In this case, I chose to convert the HEX/RGB colors into HSL colors and try to find the typical hue of every group of colors.

Converting from HEX/RGB to HSL

If we take the information (blue) colors and convert them into HSL colors, we can see that all the hues (first value) are different; they range between 188 and 192.

The main idea was to keep the first value as another CSS variable.

:root {
  --color-info-hue: /* ? */;

  --color-info-10:  189 87% 97%;  /* #F1FCFE */
  --color-info-50:  192 90% 89%;  /* #C8F2FC */
  --color-info-100: 189 100% 38%; /* #00A7C3 */
  --color-info-120: 190 100% 26%; /* #007187 */
  --color-info-200: 188 87% 12%;  /* #04333A */
}

To solve this issue, I decided to use the CSS calc() function, subtracting or adding the difference to the base hue value.

I decided to take the base hue from the primary color of every family group; in our case, the primary color was the “100” color, and the hue of the info (blue) family group was 189.

The result looked like this:

:root {
  --color-info-hue: 189;

  --color-info-10:  var(--color-info-hue) 87% 97%;            /* #F1FCFE */
  --color-info-50:  calc(var(--color-info-hue) + 3) 90% 89%;  /* #C8F2FC */
  --color-info-100: var(--color-info-hue) 100% 38%;           /* #00A7C3 */
  --color-info-120: calc(var(--color-info-hue) + 1) 100% 26%; /* #007187 */
  --color-info-200: calc(var(--color-info-hue) - 1) 87% 12%;  /* #04333A */
}

In this way, I can play with the hue and change all colors created from it.

How to Use These Variables?

When using the color variables, every call must be wrapped with the hsl() function. For example:

background-color: hsl( var(--color-info-100) );

The hsl() function wasn’t added to the variable itself because I want an easy way to control the opacity of the colors if needed.

Example:

background-color: hsl( var(--color-info-100) / 0.5 ); /* with 50% opacity */

Private Local Variable Logic

Because we have different color modes (light/dark modes), in most cases, every partial’s color will change to another color in the second color mode.

In my method, all the colors are global, both light and dark mode colors. To manage the light and dark mode’s color, I added local color variables, which will reference global color variables according to the mode.

To not have a “mess” of too many global variables, I use the concept of private variables for each partial.

To indicate a variable is private, I start it with p-. For example:

.partial {
    --p-variable-name: value;
}

In our button partial, for example, I have the main private variable for the text color, background-color, and border-color.

.button {
    /* Light-mode Theme */
    --p-text-color:   value;
    --p-button-color: value;
    --p-border-color: value;
}

The usage of those variables looks like this:

.button {
    color:            hsl( var(--p-text-color)   ); 
    background-color: hsl( var(--p-button-color) );
    border-color:     hsl( var(--p-border-color) );
}

Variables in a complex partial can have a lot of states. For example, a button can have a default, :hover, :focus, :active, or :disabled state. Those essential inner variables use other inner variables to present any state.

The code of my button variables looks like this:

.button {
    /* Light Theme */
    --p-text-color:            var(--p-text-color-default);
    --p-button-color:          var(--p-button-color-default);
    --p-border-color:          var(--p-border-color-default);

    --p-text-color-default:    var(--color-neutral-5);
    --p-button-color-default:  var(--color-primary-200);
    --p-border-color-default:  var(--color-primary-300);

    --p-text-color-hover:      var(--p-text-color-default);
    --p-button-color-hover:    var(--color-primary-100);
    --p-border-color-hover:    var(--p-border-color-default);

    --p-text-color-focus:      var(--p-text-color-default);
    --p-button-color-focus:    var(--color-primary-200);
    --p-border-color-focus:    var(--color-primary-200);

    --p-text-color-active:     var(--p-text-color-default);
    --p-button-color-active:   var(--color-primary-300);
    --p-border-color-active:   var(--color-primary-300);

    --p-text-color-disabled:   var(--color-neutral-50);
    --p-button-color-disabled: var(--color-neutral-10);
    --p-border-color-disabled: var(--color-neutral-10);
}

Defining States of Button

What is nice now is that I only need to update the variable’s value whenever I want to change the buttons.

These variables can, then, be applied based on the state of the partial.

Basic State Definitions (written in Sass):

/* global Sass Variable */
$disabled: ":disabled, .is-disabled";

.button {
    &:is(:hover) {
        &:where(:not(#{$disabled})) {
            --p-text-color:   var(--p-text-color-hover);
            --p-button-color: var(--p-button-color-hover);
            --p-border-color: var(--p-border-color-hover);
        }
    }
    &:is(:focus-visible) {
        &:where(:not(#{$disabled})) {
            --p-text-color:   var(--p-text-color-focus);
            --p-button-color: var(--p-button-color-focus);
            --p-border-color: var(--p-border-color-focus);
        }
    }
    &:is(:active) {
        &:where(:not(#{$disabled})) {
            --p-text-color:   var(--p-text-color-active);
            --p-button-color: var(--p-button-color-active);
            --p-border-color: var(--p-border-color-active);
        }
    }
    &:where(#{$disabled}) {
            --p-text-color:   var(--p-text-color-disabled);
            --p-button-color: var(--p-button-color-disabled);
            --p-border-color: var(--p-border-color-disabled);
    }
}

I use the Sass variable $disabled so that I can use the style of the disabled button on other elements, such as link elements.

Sass Code:

/* global Sass Variable */
$disabled: ":disabled, .is-disabled";

.button {
    &:where(#{$disabled}) {
            --p-text-color:   var(--p-text-color-disabled);
            --p-button-color: var(--p-button-color-disabled);
            --p-border-color: var(--p-border-color-disabled);
    }
}

Compiled CSS:

.button:where(:disabled, .is-disabled) {
      --p-text-color:   var(--p-text-color-disabled);
      --p-button-color: var(--p-button-color-disabled);
      --p-border-color: var(--p-border-color-disabled);    
}

Will target:

<button class="button" disabled> </button>

<a class="button is-disabled"> </a>

Dark Mode Treatment

After taking care of all the button light-mode states, we now want to take care of our dark-mode states.

Before doing so, I define another global Sass variable representing the dark-mode CSS class state. This state class name will be used in most of our partials to create unique colors for dark mode.

$theme-dark: ".theme-dark";

The .theme-dark class is better defined directly on the <html> element, of course, only when you use the dark-mode state.

If defining it on the <html> element is an issue, it can be defined on the <body> element instead.

<body class="theme-dark"> </body>

This is done to achieve easy global control of all the HTML elements.

Dark-Mode Treatment Inside the Partial

To create the definition of dark mode in the button partial, I add this code segment at the bottom of the partial:

.button {
   /* regular styles and light-mode definitions */

  #{$theme-dark} & { 
         /* definitions for dark-mode */
     }
}

This Sass code will compile to this selector:

.button { /* regular styles and light-mode definitions */ }

.theme-dark .button { /* definitions for dark-mode */ }

Because all the states of the buttons are already declared, the only thing left to do is to define the states’ private color variables in the dark-mode “section”.

If some colors remain the same, they do not need to be overridden in dark mode.

.button {
  #{$theme-dark} & { 
        /* changed colors */
        --p-border-color-default:  var(--color-primary-200);

        --p-button-color-hover:    var(--color-primary-100);
        --p-border-color-hover:    var(--color-primary-100);

        --p-border-color-focus:    var(--color-primary-300);

        --p-border-color-active:   var(--color-primary-300);

        --p-text-color-disabled:   var(--color-neutral-100);
        --p-button-color-disabled: var(--color-neutral-150);
        --p-border-color-disabled: var(--color-neutral-150);
   }
}

What is nice about this method is that we do not need to repeat any CSS selectors or any properties definitions.

More Types of Buttons

In our project, we needed to have different types of buttons.

Because we have already created a solid structure, we only need to define those variables according to the new state of the button.

Define New State

To define a new state, we add our new state class (.is-secondary):

<button class="button is-secondary"></button>

Now, to update the colors for the new type of button, we just override the private colors:

.button {
   &.is-secondary {
        /* Light Mode */
        --p-text-color-default:   var(--color-neutral-100);
        --p-button-color-default: var(--color-neutral-5);
        --p-border-color-default: var(--color-neutral-30);

        --p-text-color-hover:     var(--p-text-color-default);
        --p-button-color-hover:   var(--color-neutral-10);
        --p-border-color-hover:   var(--p-border-color-default);

        --p-text-color-focus:     var(--p-text-color-default);
        --p-button-color-focus:   var(--p-button-color-default);
        --p-border-color-focus:   var(--transparent);

        --p-text-color-active:    var(--color-neutral-300);
        --p-button-color-active:  var(--color-neutral-30);
        --p-border-color-active:  var(--color-neutral-30);

        --p-text-color-disabled:   var(--color-neutral-50);
        --p-button-color-disabled: var(--p-button-color-default);
        --p-border-color-disabled: var(--color-neutral-30);

        /** Dark Mode **/
        #{$theme-dark} & {
            --p-text-color-default:    var(--color-neutral-5);
            --p-button-color-default:  var(--color-neutral-300);
            --p-border-color-default:  var(--color-neutral-150);

            --p-text-color-hover:      var(--p-text-color-default);
            --p-button-color-hover:    var(--transparent);
            --p-border-color-hover:    var(--color-neutral-120);

            --p-text-color-focus:      var(--p-text-color-default);
            --p-button-color-focus:    var(--p-button-color-default);
            --p-border-color-focus:    var(--transparent);

            --p-text-color-active:     var(--p-text-color-default);
            --p-button-color-active:   var(--p-button-color-default);
            --p-border-color-active:   var(--color-neutral-100);

            --p-text-color-disabled:   var(--color-neutral-100);
            --p-button-color-disabled: var(--p-button-color-default);
            --p-border-color-disabled: var(--color-neutral-150);
        }
    }
}

As you can see, I’m only defining variables here, without any properties and or any state selector pseudo-class like :hover, :focus and so on.

CodePen Full Demo:

Open CodePen Demo in separate tab

Global Colors State

In most cases, we do not want to define global color variables that are updated to other colors in dark mode.

However, while this is correct for most cases, in some specific cases we will want to define a state color that looks like one specific color in light mode and another in dark mode.

Global Logic Colors

For that, I created another solution, which I am calling “global logic colors.”

For these, I created global CSS variables that are defined in a separate :root selector; of course, they reference other global color variables.

For dark mode, these variables are changed to another global color variable. Example:

:root {
  /* Global Logic Colors - Light Mode */
  --color-text-info:      var(--color-info-100);
  --color-text-danger:    var(--color-danger-100);
  --color-text-warning:   var(--color-warning-100);
  --color-text-success:   var(--color-success-100);

  --color-border:         var(--color-neutral-10);
  --scroll-color:         var(--color-neutral-50);

  #{$theme-dark} {
    /* Global Logic Colors - Dark Mode */
    --color-text-info:    var(--color-info-120);
    --color-text-danger:  var(--color-danger-120);
    --color-text-warning: var(--color-warning-120);
    --color-text-success: var(--color-success-120);

    --color-border:       var(--color-neutral-200);
    --scroll-color:       var(--color-neutral-150);
  }
}

These CSS variables are used in two ways:

1. Direct usage inside a partial

.icon-checked { color: hsl( var(--color-text-success) ); }

2. As a global utility class

/* Global Utilities colors classes */
.u-color-text-disabled { color: hsl( var(--color-text-disabled) ); }
.u-color-text-offline  { color: hsl( var(--color-text-offline)  ); }
.u-color-text-info     { color: hsl( var(--color-text-info).    ); }
.u-color-text-danger   { color: hsl( var(--color-text-danger).  ); }
.u-color-text-warning  { color: hsl( var(--color-text-warning). ); }
.u-color-text-success  { color: hsl( var(--color-text-success)  ); }

The global utility classes can be used directly on an element and will provide different colors according to the light mode or dark mode theme.

In both ways, the colors are updated according to the state of the color mode scheme.

To Summarize

In this post, we discussed common ways to define CSS color variables and their problems. After that, we explored how to reorganize CSS variables using private variables to create a CSS architecture with well-organized colors.

Final Words

Pink Design is finally out today. Pink Design was built with new inventive CSS architectures and prioritizes accessibility and developer experience. As a company developing an open-source product, this is a big step for Appwrite’s community of contributors. As always, we will keep improving Pink Design, allowing it to grow alongside Appwrite.

Thank you for being a part of our journey! If you haven’t already, browse the 💻 Pink Design GitHub Repository or check out our 🚀 Getting Started Guide to use Pink Design in your projects or when contributing to Appwrite.

Until next time!

CSS Color Architecture was originally published in Appwrite on Medium, where people are continuing the conversation by highlighting and responding to this story.

However, I also like how Normalize CSS handles shadow DOM elements, which we do not have in any of the CSS Reset methods.

Because of this, I always find methods to mix them both. Even then, however, I have had some issues with CSS specificity that I needed to find a method to workaround.

Fast forwarding to today, all browsers now support CSS Layers. Therefore, while working on Pink Design, the open source design system of Appwrite, we started to rethink how we could handle this better.

Before we start, let’s talk a bit about CSS reset methods.

CSS Reset Methods

For many years, there was a “fight” over which method of resetting CSS was better.

In this competition, we had two familiar methods:

1. Normalize CSS — a gentle approach to fix differences between browsers while keeping the native styles of HTML elements such as the heading elements of <h1>, <h2>, and so on.

As mentioned before, Normalize CSS also takes care of shadow DOM elements that sometimes look different in different browsers.

Demo of treatment of shadow DOM elements in Normalize CSS:

/**
 * 1. Correct the inability to style clickable types in iOS and Safari.
 * 2. Change font properties to `inherit` in Safari.
 */
::-webkit-file-upload-button {
  -webkit-appearance: button; /* 1 */
  font: inherit; /* 2 */
}

2. CSS Reset — in contrast, CSS Reset is a more aggressive method that often revokes the default style of the “user-agent stylesheet” of the browser.

Demo of CSS reset

This code will revoke the special font-size, font-weight and margin of the <h1> to a <h6> elements:

h1, h2, h3, h4, h5, h6 {
  margin: 0;
  font-size: inherit; 
  font-weight: inherit;
}

Combining Methods

By combining both methods, Normalize CSS and CSS Reset, you can profit from both approaches.

This ensures that both inner shadow DOM elements are taken care of, and unhelpful styles inherited from the “user-agent stylesheet” are being ignored.

The easiest way to accomplish this is by loading both. Demo of how to implement in Sass preprocessor:

/* CSS Resets */
@use 'normalize';
@use 'reset';

You would think that if we first load Normalize CSS and then CSS Reset, this would make our CSS Reset have a stronger Specificity, right? Not precisely; let’s talk about some issues with this.

Issues with Combining Methods

In Appwrite Pink, we use Normalize CSS while combining it with ‘The New CSS Reset’. ‘The New CSS Reset’ is a new method of resetting CSS that uses the new native CSS reset features.

For both projects of “Normalize CSS” & “The New CSS Reset”, we take them as is, without any changes (from NPM), even the unnecessary parts from Normalize CSS, like fixing the different style of the <h1> element that will be removed with the CSS Reset.

Header <h1> style in “Normalize CSS”:

/**
 * Correct the font size and margin on `h1` elements within `section` and
 * `article` contexts in Chrome, Firefox, and Safari.
 */

h1 {
  font-size: 2em;
  margin: 0.67em 0;
}

General remove style in “The New CSS Reset” (includes <h1> elements):

/*
    Remove all the styles of the "User-Agent-Stylesheet", 
    except for the 'display' property.
    - The "symbol *" part is to solve Firefox SVG sprite bug
 */
*:where(:not(html, iframe, canvas, img, svg, video, audio):not(svg *, symbol *)) {
    all: unset;
    display: revert;
}

But here start our problems. To understand the problems, let's talk about basic CSS which defines our styles:

Order Does Matter

The order of the CSS selectors is important. This is because, usually, what is coming last is stronger than what is coming first. In our case, the order of our CSS Resets files is correct.

First, we want to load the “Normalize CSS”, which will normalize our differences between different browsers, and then we want to remove what we don’t need with a CSS reset, in our case, which is done with “The New CSS Reset”.

Example of imports in Scss:

/* CSS Resets files order */
@use 'normalize'; /* 1 */
@use 'reset';     /* 2 */
/* In general, last code is stronger in CSS */

CSS Specificity

We have the strength of our selectors defined according to the CSS selector strength (elements, class names, and ID names). From weakest to strongest selectors, we have the element, class, and ID selectors.

Example:

In this example, the selector of the ID will win the “CSS Specificity War”, because the ID selector is stronger than the selector of a class name or an element.

This means that the color of the <h1> element, in this case, will be pink.

<h1 class="title" id="mainTitle">some content</h1>

#mainTitle { color:pink;   } /* 1 (ID), 0 (Classes), 0(element) */
.title     { color:yellow; } /* 0 (ID), 1 (Classes), 0(element) */
h1         { color:red;    } /* 0 (ID), 0 (Classes), 1(element) */

Our CSS Specificity Conflict

If we take a look at Normalize CSS selector of <h1> elements, it has the power of one element:

/* 0 (ID), 0 (Classes), 1 (element) */
h1 {...}

This is a relatively low-strength selector.

Let’s have a look at the main CSS Reset selector from “The New CSS Reset” method:

/* 0 (ID), 0 (Classes), 0 (element) */
*:where(:not(html, iframe, canvas, img, svg, video, audio):not(svg *, symbol *)) {...}

To make it with the lowest specificity possible, the :where() pseudo selector is used. One of the main ideas of the :where() pseudo selector is to remove any CSS specificity created by the selector.

But here comes the conflict, the style of the <h1> is stronger than the style of the CSS Reset, and this is an issue for us because we want the CSS Reset to overcome the Normalize CSS.

One way to solve this conflict is to remove the unnecessary parts of Normalize CSS, which means removing all the un shadow DOM parts style. But this can be an issue if we load the project automatically from an NPM package, which is complex to maintain.

CSS Layers to the Rescue

CSS layers were invented to solve cases like this, where we want to tell the browsers that a specific layer is more important than others, and ignore the CSS specificity of another layer.

To do so, we have the @layer rule, which defines a layer. This will wrap part of the styles, define the parts of the layer, and enact out the CSS specificity only inside the layer itself.

@layer normalize {
  /* CSS Normalize Here */
}
@layer the-new-css-reset {
  /* CSS Reset here */
}

This in itself will solve our issue.

To be more precise in defining the order of the layer, we can add the “layer statement” that will determine the order you want the code to appear.

Example:

/* layer statement - define the order, 
   even if the order of the code will not be in the same way */
@layer normalize, the-new-css-reset;

@layer normalize {
  /* CSS Normalize Here */
}
@layer the-new-css-reset {
  /* CSS Reset here */
}

CodePen Demo:

Sass Preprocessor Support

To keep the separation of files while using Sass, we will need to add some adjustments to our Sass code.

@use 'sass:meta';

@layer normalize, the-new-css-reset;

@layer normalize {
  @include meta.load-css('normalize');
}
@layer the-new-css-reset {
  @include meta.load-css('the-new-css-reset');
}

This way, we can keep our CSS layers separate in separate files and ensure that the last layers will win the “cascade war” while keeping our code well organized.

Browser Support

CSS layers have already been implemented in all evergreen browsers for quite a while. In iOS, the functionality exists from version 15.4, which at the time of writing this post, we are currently on version 16.3.

To Summarize

This post covered how we can solve CSS specificity issues, specifically on CSS reset layers.

This method of using CSS layers to solve CSS conflicts will be more commonly used as we approach the end of 2023, as users upgrade their browsers.

While building Pink Design, we had the luxury of building a product for developers, a type of user that updates their browsers regularly. Therefore, we chose to move forward with this new method using CSS Layers.

Final Words

Pink Design is finally out today. Pink Design was built with new inventive CSS methods, and prioritizes accessibility and developer experience. As a company developing an open-source product, this is a big step for Appwrite’s community of contributors. As always, we will keep improving Pink Design, allowing it to grow alongside Appwrite.

Thank you for being a part of our journey! If you haven’t already, browse the 💻 Pink Design GitHub Repository or check out our 🚀 Getting Started Guide to use Pink Design in your projects or when contributing to Appwrite.

Until next time!

Further reading/watching on CSS Layers:

• A Complete Guide to CSS Cascade Layers — by Miriam Suzanne
• Getting Started With CSS Cascade Layers — by Stephanie Eckles
• The CSS Cascade, a deep dive (video) — by Bramus Van Damme

Further reading on The New CSS Reset:

• How Does CSS Work? — by Elad Shechter
• The New CSS Reset — by Elad Shechter

CSS Layers for CSS Resets was originally published in Appwrite on Medium, where people are continuing the conversation by highlighting and responding to this story.

Building software is fun. Building open source software is even better. At Appwrite, open source is at the core of everything we do, and collaboration with our community is what drives us to create better products, but collaborating to build the same product can pose many challenges. To deliver features quickly, consistently, and maintain product identity, it is imperative that everyone working on the same product follow the same guidelines; this is why we’re excited to announce Pink Design.

Pink Design, or Pink, is Appwrite’s fully open source design system for building consistent and reusable user interfaces.

When we began redesigning our product almost a year ago, we discovered that the lack of a design system caused a lot of inconsistencies. It was difficult for a growing team to build a common identity without guidelines. Two months ago, we released Console 2.0 after several months of hard work. During the development of the new console, we also created our components library and documented every decision we made in order to prioritize our core product values better and be more welcoming for community contributions. This became Pink Design.

So why is Pink Design essential?

For Consistency

Consistent behavior is crucial while building a product. It reduces frustration and guides the user to learn the interface faster. This is why we designed Pink — the library contains foundations, layouts, elements, and components with thoroughly documented usage guidelines.

For Collaboration

Appwrite is open source with a growing developer community. With the help of our community members, we always strive to ship new features faster and more efficiently. Pink Design was created to facilitate contributions and collaboration internally and with our community. Pink allows all contributors to build features using a shared set of components, reducing friction.

For Accessibility

To make sure people with disabilities and different skill levels have equal opportunities, we designed every component in our library to comply with most accessibility standards — in both light and dark modes.

For Better Dev-Experience

Developer experience has always been a priority for Appwrite since the beginning, and simplifying software development is what guides us in everything we do. Therefore, Pink Design was created so you could easily integrate with your preferred framework or include the library in your CSS file.

What’s Next?

Pink Design is finally out today. As a company developing an open source product, this is a big step for Appwrite’s community of contributors. As always, we will keep improving Pink Design, allowing it to grow alongside Appwrite.

Thank you for being a part of our journey! If you haven’t already, browse the 💻 Pink Design GitHub Repository or check out our 🚀 Getting Started Guide to use Pink Design in your projects or when contributing to Appwrite.

Until next time!

Announcing Pink Design was originally published in Appwrite on Medium, where people are continuing the conversation by highlighting and responding to this story.

Pink Design is Appwrite’s Open Source design system for building consistent and reusable user interfaces.

This design system was developed with Appwrite’s console in mind, with a particular focus on accessibility and usability, without giving up on style! ;)

Pink Design is versatile in its application. It can be easily integrated with popular frameworks such as React, Svelte, Angular, or Vue or used in conjunction with standard HTML and CSS.

You can use Pink Design in your personal projects or contribute to its development and help us improve Appwrite.

🎨 How do I get Pink Design?

There are two ways to add Pink Design to your project:

By linking the stylesheet directly in your HTML file, like so:

<link rel="stylesheet" href="https://unpkg.com/@appwrite.io/pink" />
<!-- optionally, add icons -->
<link rel="stylesheet" href="https://unpkg.com/@appwrite.io/pink-icons" />

Or by installing it through npm and importing it in your project’s JavaScript file, as follows:

npm install @appwrite.io/pink

and then by importing it like this:

import "@appwrite.io/pink/dist/pink.css";

// optionally, add icons
import "@appwrite.io/pink-icons";

And voilà, once you’ve completed either of these steps, you can start using Pink Design’s UI elements and components!

Make sure to check the Getting Started guide for more information 😊

⌨️ It’s coding time

Pink Design provides many pre-designed UI elements and components, such as buttons, inputs, cards, and more. You can easily use them by adding the corresponding classes to your HTML.

<button class="button">
  <span class="text">Hello world</span>
</button>

Easy as that! 🔥

🏁 Conclusion

And that’s all it takes to add Pink Design to your project. You can view the following resources as well if you want to explore Pink Design further:

Pink Design GitHub

Appwrite Discord

Getting Started with Pink Design was originally published in Appwrite on Medium, where people are continuing the conversation by highlighting and responding to this story.

Our main goal while redesigning the Appwrite console was to improve the user experience in line with the needs and requirements of developers looking for a BaaS (Backend as a Service) solution. While keeping our core values, such as simplicity and consistency, in mind, we attempted to understand the essential problems developers faced in the previous version of the console.

With the collaboration of our developer community, we gathered feedback and prioritised a few updates to the functions screens.

Let’s take a closer look at some of the changes we made.

Home screen details

Our research showed that users wanted to see more details about their functions without the need to navigate to another screen. Like a few other screens in the redesigned console, the new design provides those extra details: function IDs that can easily be copied, the details of the next scheduled CRON job if a time period has been set, or if the user has yet to create a deployment for a function.

Function creation

There is so much more to creating a function than simply choosing a name and selecting a runtime. Community feedback indicated that in the previous version of the console, it wasn’t apparent that you could customise a function during the creation process. Setting execute access, scheduling deployments, or adding variables — things our users felt were essential for customisation — could only be done after a function was created.

The new function setup process now guides users through these optional extra steps, and once complete, directs them to a new Deployments tab where they can create a deployment.

Deployment details

Speaking of deployments, a common issue that arose throughout our research was that the previous version of the console did not make clear which ones were active versus inactive when viewing a function’s details. We decided to separate this information from the function details entirely and create a Deployments tab where active deployments are displayed at the top of the screen. Inactive deployments remain visible in a more condensed table below the currently active deployment. This is in contrast to the previous design, which gave unnecessary emphasis to the name of the function and the function runtime, and the deployment details were displayed in a single table, active or otherwise.

Execution (log) details

When engaging with our users, there was some confusion as to which logs were being displayed and where in the Functions screens, so our first line of business was to specify that the ‘Logs’ mentioned in the tab navigation were, in fact, execution logs. We changed the name of this tab in our redesign to reflect this, and so far the response has been positive.

We also made the decision to include tags with a hover state to display the trigger status of an execution. If an execution was triggered by an event, on hover the user can see the details of the trigger event. If the execution was triggered via a schedule, on hover the user can see the scheduled time for the next execution. (Currently, nothing happens when hovering over the ‘http’ trigger tag).

Full-screen deployment & execution logs

When viewing logs for either deployments or executions, users will now have the full screen at their disposal. Previously, users were limited to viewing their logs in a modal — which is fine if there are only a few lines in the log to view. As it turned out, there were more than a few instances where a user’s build log would span hundreds of lines.

Editable function variables

Another often-requested feature for the Functions service was the ability to edit variables. This wasn’t technically feasible for us in the previous version of the console. If users wanted to edit a variable, they would have needed to delete it and create a new one with the updated details. More recently, our talented engineering team overcame this roadblock. As a result, the redesign of the functions settings screen includes a menu to allow for the editing and deleting of variables. We have also added an inline interactive text component that permits users to view variable values without the friction of having to click to open a modal to see this information.

What’s next?
We may have overhauled our console design, but we are far from finished. Design is an iterative process, after all. We are working on further improvements to the Function screens, including a GUI for scheduling CRON jobs and GitHub integration for deployments.

Thank you for being a part of our journey as we strive to create the best developer experience. We hope you enjoy these changes to the Appwrite console. As always, we’re more than happy to hear your thoughts. Leave a comment, reach out on Discord, or create a GitHub discussion.

Check out our release on 🚀 Product Hunt or our 💻 GitHub repository.

Until next time!

Introducing Console 2.0: Functions was originally published in Appwrite on Medium, where people are continuing the conversation by highlighting and responding to this story.

Our main goal while redesigning the Appwrite console was to improve the user experience in line with the needs and requirements of developers looking for a BaaS (Backend as a Service) solution. While keeping our core values such as simplicity and consistency in mind, we attempted to understand the essential problems developers faced in the previous version of the console.

With the collaboration of our developer community, we gathered feedback and prioritized a few updates to the Databases screens.

Let’s take a closer look at some of the changes we made.

Databases and collections

With Appwrite’s Databases Service, you can create multiple databases. Each database can contain many collections. The Databases and Collections screens have been revamped to make it easier for developers to detect disabled collections and easily copy databases and collections IDs.

New permissions

Permissions can be complicated, we know! That is why we designed a simpler way to manage them in the Appwrite console. Now you can switch a toggle to enable or disable Document Security. If security is enabled, you can update your permissions at the document level. If security is disabled, you can update your permissions at the collection level.

These permissions can be granted to anyone, all guests, all users, or specific users or teams. We’ve even added a setting that enables developers to create custom permissions. Easy, right?

Document creation

Creating attributes is still required before creating a document since they define its structure and help the Appwrite API validate input from your users. Once your attributes have been set, you can create your documents using a simple two-step process. For the first step, you will need to create the document’s data, which means filling in all of the attribute fields you set up earlier. Next, you will be able to set permissions, depending on whether you have enabled document security.

Documents overview

If you have a large table of documents with many attributes, finding what you need in the documents overview screen can be very difficult. In the previous console, if you had 10 or more attributes, there was no way to tell which document you were looking at without a lot of horizontal scrolling. With the new console design, the ID column is sticky. That way you can always see the document ID and copy it easily to use in your code.

Attributes and indexes

Your attributes and indexes play essential roles in your projects. We revamped the screens for both and added a menu to allow for quick actions such as opening an overview, creating an index for a specific attribute, and deleting attributes or indexes from the table.

What’s next?

We may have overhauled our console design, but we are far from finished. Design is an iterative process after all. We are working on further improvements to the Databases screens such as filtering and searching for documents, as well as deleting multiple attributes and/or indexes at once.

Thank you for being a part of our journey as we strive to create the best developer experience. We hope you enjoy these changes to the Appwrite console. As always, we’re more than happy to hear your thoughts. Leave a comment, reach out on Discord, or create a GitHub discussion.

Check out our release on 🚀 Product Hunt or our 💻 GitHub repository

Until next time!

Introducing Console 2.0: Databases was originally published in Appwrite on Medium, where people are continuing the conversation by highlighting and responding to this story.

Our main goal while redesigning the Appwrite console was to improve the user experience in line with the needs and requirements of developers looking for a BaaS (Backend as a Service) solution. While keeping our core values such as simplicity and consistency in mind, we attempted to understand the essential problems developers faced in the previous version of the console.

With the collaboration of our developer community, we gathered feedback and prioritised a few updates to the storage screens.

Let’s take a closer look at some of the changes we made.

Home screen details

Overwhelmingly, our research found that users wanted to see more information about their storage buckets at a glance — in particular, the bucket’s current status. The previous version of this screen showed a list of buckets but provided only the bucket name. Users would need to navigate to the bucket settings screen to see the information they wanted.

The revamped bucket details card, following our new design system, now displays a couple extra details: whether the bucket is currently disabled, or if encryption or antivirus features have been enabled. The bucket details card also allows users to click and copy their bucket ID.

Uploading Files

We updated the file upload functionality to enable drag-and-drop for an effortless uploading process. Files being uploaded have also been made more visible so that users can check their status in a window that persists across the console until closed by the user.

Updating file extensions

Previously, users could update the list of allowed file extensions in a bucket by manually typing them into an input field. Placeholder text within the field provided some suggested extensions, but our users found the manual process to be tedious. To alleviate some of this frustration, we inserted a set of tags with the most common extensions below the input field so users would have the option to click and add extensions.

New permissions

Permissions can be complicated, we know! That is why we designed a simpler way to manage them in the Appwrite console. Now you can switch a toggle to enable or disable File Security. If security is enabled, you can update your permissions at the file level. If security is disabled, you can update your permissions at the bucket level.

These permissions can be granted to anyone, all guests, all users, or to specific users or teams. We’ve even added a setting that enables developers to create custom permissions. Easy, right?

What’s next?
We may have overhauled our console design, but we are far from finished. Design is an iterative process, after all. We are working on further improvements to the storage screens such as enabling the sorting and filtering of files, file search by ID or URL, and the addition of more file details (for instance, the user ID of who uploaded a file outside of the console).

Thank you for being a part of our journey as we strive to create the best developer experience. We hope you enjoy these changes to the Appwrite console. As always, we’re more than happy to hear your thoughts. Leave a comment, reach out on Discord, or create a GitHub discussion.

Check out our release on 🚀 Product Hunt or our 💻 GitHub repository.

Until next time!

Introducing Console 2.0: Storage was originally published in Appwrite on Medium, where people are continuing the conversation by highlighting and responding to this story.

Our main goal while redesigning the Appwrite console was to improve the user experience in line with the needs and requirements of developers looking for a BaaS (Backend as a Service) solution. While keeping our core values such as simplicity and consistency in mind, we attempted to understand the essential problems developers faced in the previous version of the console.

With the collaboration of our developer community, we gathered feedback and prioritized a few updates to the Auth screens.

Let’s take a closer look at some of the changes we made.

Account session

With Appwrite, developers can implement login and registration logic using the Account API. There are different ways to sign in, meaning not all users will be using email and password authentication. When creating a user in the previous console, developers had to enter three inputs: name, email, and password, which does not reflect our current API. Not only should the name be optional, but a phone number cannot be added to a user account. In the new console, we added input for a phone number, as well as making all inputs optional. Fun fact, if all inputs are left empty, an anonymous user will be created.

Search

One of the most critical patterns for a better user experience is the search feature. In the new console, you can search users by name, email, phone, or ID. Unlike the previous version, a smoother experience is provided by the table updating in real-time as you type.

User preferences

One of the most requested features from our community was the ability to edit user preferences in the console. In the new console, you can update your user preferences by storing information on the user’s objects so they can easily be shared across devices and sessions.

Security

The security settings are now located next to Settings in the tabs navigation. The ‘Users Limit’ option was previously available only in the Settings tab, above the authentication methods. We believe security is too important to be hidden and based on feedback from our developer community that ‘Users Limit’ can be hard to notice, we found it correct to make a distinction between security settings and authentication settings.

Settings

On the Settings tab, you will find authentication methods and an extensive list of OAuth2 providers you can enable for your project. The challenge on this screen was to reduce the visual overload without hiding any of the providers. In order to keep the interface clean from distractions, we gathered all authentication methods on one card. The next step was to move the toggle and documents link from the provider’s card to the modal. Now when the user enables providers, they are shown at the top of the list.

What’s next?

We may have overhauled our console design, but we are far from finished. Design is an iterative process, after all. We are working on further improvements to the Auth screens such as setting a session length in the Security tab, creating a membership for an existing user in a more intuitive way, and improving the flow of enabling an OAuth provider.

Thank you for being a part of our journey as we strive to create the best developer experience. We hope you enjoy these changes to the Appwrite console. As always, we’re more than happy to hear your thoughts. Leave a comment, reach out on Discord, or create a GitHub discussion.

Check out our release on 🚀 Product Hunt or our 💻 GitHub repository

Until next time!

Introducing Console 2.0: Auth was originally published in Appwrite on Medium, where people are continuing the conversation by highlighting and responding to this story.