funkwhale/front/ui-docs/using-color.md

<script setup>
import { color } from "~/composables/colors.ts"
import Button from "~/components/ui/Button.vue"
import Card from "~/components/ui/Card.vue"
import Link from "~/components/ui/Link.vue"
import Layout from "~/components/ui/Layout.vue"
import Alert from "~/components/ui/Alert.vue"
import Spacer from "~/components/ui/layout/Spacer.vue"
</script>

<Link disabled to="#theme-color-definitions">Want to fix colors?</Link>
<Link solid primary to="#change-a-color-value">Change a color value</Link>
<Link solid primary to="#alter-the-shade-of-a-color">Alter the shade of a color</Link>
<Link solid primary to="#choose-a-different-style-for-a-specific-variant">Modify a specific variant</Link>

# Using Color

## Add color via props

[Alerts](components/ui/alert) support [Pastel](#pastel) attributes. [Buttons](components/ui/button) accept [Color](#color) and [Variant](#variant) attributes. [Cards](components/ui/card) accept [Pastel](#pastel), [Variant](#variant), [Neutral](#neutral) and [Raised](#raised) attributes.

<Layout flex>

```vue-html
<Card solid red title='🌈' />
```

<div class="preview">
  <Card solid red title='🌈' />
</div>

</Layout>

## Add color to a any component or Html tag

1. Choose either:
   - [base color](#colors) (`primary | secondary | destructive`) or
   - [pastel color](#pastel) (`blue | red | green | yellow`) or
   - [neutral beige or gray](#neutral) (`default`) for surfaces
2. Choose a [variant](#color-variants) (`solid | ghost | outline`)
3. Add [interactivity and raise the surface](#interactive-andor-raised)

<Layout flex>

```vue
<script setup>
import { color } from "~/composables/colors.ts";
</script>

<template>
  <div v-bind="color('primary solid interactive raised')" />
</template>
```

<div class="preview">
  <div :class="$style.swatch" v-bind="color('primary solid interactive raised')" />
</div>

</Layout>

## Base colors

Keep most of the screen neutral. Secondary surfaces indicate actionability. Use them sparingly. Primary and destructive surfaces immediately catch the eye. Use them only once or twice per screen.

### Neutral

Use neutral colors for non-interactive surfaces

<Layout flex>
  <div class="force-dark-theme">
    <div v-bind="color('default solid')">
      <div :class="$style.swatch" v-bind="color('default solid')" />
      <div :class="[$style.swatch, $style.deemphasized]" v-bind="color('default solid interactive')" />
    </div><div v-bind="color('default solid raised')">
      <div :class="$style.swatch" v-bind="color('default solid raised')" />
      <div :class="[$style.swatch, $style.deemphasized]" v-bind="color('default solid raised interactive')" />
    </div>
  </div>

  <div class="force-light-theme">
    <div v-bind="color('default solid')">
      <div :class="$style.swatch" v-bind="color('default solid')" />
      <div :class="[$style.swatch, $style.deemphasized]" v-bind="color('default solid interactive')" />
    </div><div v-bind="color('default solid raised')">
      <div :class="$style.swatch" v-bind="color('default solid raised')" />
      <div :class="[$style.swatch, $style.deemphasized]" v-bind="color('default solid raised interactive')" />
    </div>
  </div>
</Layout>

### Color

#### Primary

Only use for at most one call-to-action on a screen

<Layout flex>
  <div class="force-dark-theme">
    <div v-bind="color('default solid')">
      <div :class="[$style.swatch, $style.deemphasized]" v-bind="color('primary solid')" />
      <div :class="[$style.swatch]" v-bind="color('primary solid interactive')" />
    </div><div v-bind="color('default solid raised')">
      <div :class="[$style.swatch, $style.deemphasized]" v-bind="color('primary solid raised')" />
      <div :class="[$style.swatch]" v-bind="color('primary solid raised interactive')" />
    </div>
  </div>

  <div class="force-light-theme">
    <div v-bind="color('default solid')">
      <div :class="[$style.swatch, $style.deemphasized]" v-bind="color('primary solid')" />
      <div :class="[$style.swatch]" v-bind="color('primary solid interactive')" />
    </div><div v-bind="color('default solid raised')">
      <div :class="[$style.swatch, $style.deemphasized]" v-bind="color('primary solid raised')" />
      <div :class="[$style.swatch]" v-bind="color('primary solid raised interactive')" />
    </div>
  </div>
</Layout>

#### Secondary

Use for interactive items and non-permanent surfaces such as menus and modals

<Layout flex>
  <div class="force-dark-theme">
    <div v-bind="color('default solid')">
      <div :class="$style.swatch" v-bind="color('secondary solid')" />
      <div :class="[$style.swatch]" v-bind="color('secondary solid interactive')" />
    </div><div v-bind="color('default solid raised')">
      <div :class="$style.swatch" v-bind="color('secondary solid raised')" />
      <div :class="[$style.swatch]" v-bind="color('secondary solid raised interactive')" />
    </div>
  </div>

  <div class="force-light-theme">
    <div v-bind="color('default solid')">
      <div :class="$style.swatch" v-bind="color('secondary solid')" />
      <div :class="[$style.swatch]" v-bind="color('secondary solid interactive')" />
    </div><div v-bind="color('default solid raised')">
      <div :class="$style.swatch" v-bind="color('secondary solid raised')" />
      <div :class="[$style.swatch]" v-bind="color('secondary solid raised interactive')" />
    </div>
  </div>
</Layout>

#### Destructive

Use for dangerous actions

<Layout flex>
  <div class="force-dark-theme">
    <div v-bind="color('default solid')">
      <div :class="[$style.swatch, $style.deemphasized]" v-bind="color('destructive solid')" />
      <div :class="[$style.swatch]" v-bind="color('destructive solid interactive')" />
    </div><div v-bind="color('default solid raised')">
      <div :class="[$style.swatch, $style.deemphasized]" v-bind="color('destructive solid raised')" />
      <div :class="[$style.swatch]" v-bind="color('destructive solid raised interactive')" />
    </div>
  </div>

  <div class="force-light-theme">
    <div v-bind="color('default solid')">
      <div :class="[$style.swatch, $style.deemphasized]" v-bind="color('destructive solid')" />
      <div :class="[$style.swatch]" v-bind="color('destructive solid interactive')" />
    </div><div v-bind="color('default solid raised')">
      <div :class="[$style.swatch, $style.deemphasized]" v-bind="color('destructive solid raised')" />
      <div :class="[$style.swatch]" v-bind="color('destructive solid raised interactive')" />
    </div>
  </div>
</Layout>

### Pastel

Use `Blue`, `Red`, `Purple`, `Green`, `Yellow` for user-defined tags and for friendly messages such as
Alerts

<div :class="$style.swatch" v-bind="color('blue solid interactive')" />
<div :class="$style.swatch" v-bind="color('red solid interactive')" />
<div :class="$style.swatch" v-bind="color('purple solid interactive')" />
<div :class="$style.swatch" v-bind="color('green solid interactive')" />
<div :class="$style.swatch" v-bind="color('yellow solid interactive')" />

### Variant

You can de-emphasize interactive elements by hiding their background and/or outline.

`Solid` (default), `Ghost`, `Outline`:

<Button round shadow icon="bi-x" solid />

<div :class="$style.swatch" v-bind="color('solid raised')">
  <Button round icon="bi-x" ghost />
  <Spacer />
  <Button round icon="bi-x" outline />
</div>

<br/>

<Button round shadow icon="bi-x" primary solid />

<div :class="$style.swatch" v-bind="color('primary solid')">
  <Button round icon="bi-x" primary ghost />
  <Spacer />
  <Button round icon="bi-x" primary outline />
</div>

### Interactive and/or Raised

Use raised surfaces sparingly, about ¼ of the screen. Only use raised surfaces to highlight one area of a component over others. Good examples are `aside`s such as the sidebar or info-boxes.

Space out interactive surfaces.

<Layout>

<div class="force-light-theme">

<Layout flex>
  <div>
    <div v-bind="color('default solid')">
      <div :class="[$style.swatch]" v-bind="color('solid')" />
      <div :class="[$style.swatch]" v-bind="color('solid interactive')" />
      <div :class="[$style.swatch]" v-bind="color('solid interactive')" disabled/>
      <div :class="[$style.swatch]" v-bind="color('solid interactive')" aria-pressed="true"/>
    </div>
    <div v-bind="color('secondary solid')">
      <div :class="[$style.swatch]" v-bind="color('solid')" />
      <div :class="[$style.swatch]" v-bind="color('solid interactive')" />
      <div :class="[$style.swatch]" v-bind="color('solid interactive')" disabled/>
      <div :class="[$style.swatch]" v-bind="color('solid interactive')" aria-pressed="true"/>
    </div>
    <div v-bind="color('primary solid')">
      <div :class="[$style.swatch]" v-bind="color('solid')" />
      <div :class="[$style.swatch]" v-bind="color('solid interactive')" />
      <div :class="[$style.swatch]" v-bind="color('solid interactive')" disabled/>
      <div :class="[$style.swatch]" v-bind="color('solid interactive')" aria-pressed="true"/>
    </div>
  </div><div>
    <div v-bind="color('default raised solid')">
      <div :class="[$style.swatch]" v-bind="color('solid raised')" />
      <div :class="[$style.swatch]" v-bind="color('solid interactive raised')" />
      <div :class="[$style.swatch]" v-bind="color('solid interactive raised')" disabled/>
      <div :class="[$style.swatch]" v-bind="color('solid interactive raised')" aria-pressed="true"/>
    </div>
    <div v-bind="color('secondary raised solid')">
      <div :class="[$style.swatch]" v-bind="color('solid raised')" />
      <div :class="[$style.swatch]" v-bind="color('solid interactive raised')" />
      <div :class="[$style.swatch]" v-bind="color('solid interactive raised')" disabled/>
      <div :class="[$style.swatch]" v-bind="color('solid interactive raised')" aria-pressed="true"/>
    </div>
    <div v-bind="color('primary raised solid')">
      <div :class="[$style.swatch]" v-bind="color('solid raised')" />
      <div :class="[$style.swatch]" v-bind="color('solid interactive raised')" />
      <div :class="[$style.swatch]" v-bind="color('solid interactive raised')" disabled/>
      <div :class="[$style.swatch]" v-bind="color('solid interactive raised')" aria-pressed="true"/>
    </div>
  </div>
</Layout>

</div>

<div class="force-dark-theme">

<Layout flex>
  <div>
    <div v-bind="color('default solid')">
      <div :class="[$style.swatch]" v-bind="color('solid')" />
      <div :class="[$style.swatch]" v-bind="color('solid interactive')" />
      <div :class="[$style.swatch]" v-bind="color('solid interactive')" disabled/>
      <div :class="[$style.swatch]" v-bind="color('solid interactive')" aria-pressed="true"/>
    </div>
    <div v-bind="color('secondary solid')">
      <div :class="[$style.swatch]" v-bind="color('solid')" />
      <div :class="[$style.swatch]" v-bind="color('solid interactive')" />
      <div :class="[$style.swatch]" v-bind="color('solid interactive')" disabled/>
      <div :class="[$style.swatch]" v-bind="color('solid interactive')" aria-pressed="true"/>
    </div>
    <div v-bind="color('primary solid')">
      <div :class="[$style.swatch]" v-bind="color('solid')" />
      <div :class="[$style.swatch]" v-bind="color('solid interactive')" />
      <div :class="[$style.swatch]" v-bind="color('solid interactive')" disabled/>
      <div :class="[$style.swatch]" v-bind="color('solid interactive')" aria-pressed="true"/>
    </div><br/>Normal
  </div><div>
    <div v-bind="color('default raised solid')">
      <div :class="[$style.swatch]" v-bind="color('solid raised')" />
      <div :class="[$style.swatch]" v-bind="color('solid interactive raised')" />
      <div :class="[$style.swatch]" v-bind="color('solid interactive raised')" disabled/>
      <div :class="[$style.swatch]" v-bind="color('solid interactive raised')" aria-pressed="true"/>
    </div>
    <div v-bind="color('secondary raised solid')">
      <div :class="[$style.swatch]" v-bind="color('solid raised')" />
      <div :class="[$style.swatch]" v-bind="color('solid interactive raised')" />
      <div :class="[$style.swatch]" v-bind="color('solid interactive raised')" disabled/>
      <div :class="[$style.swatch]" v-bind="color('solid interactive raised')" aria-pressed="true"/>
    </div>
    <div v-bind="color('primary raised solid')">
      <div :class="[$style.swatch]" v-bind="color('solid raised')" />
      <div :class="[$style.swatch]" v-bind="color('solid interactive raised')" />
      <div :class="[$style.swatch]" v-bind="color('solid interactive raised')" disabled/>
      <div :class="[$style.swatch]" v-bind="color('solid interactive raised')" aria-pressed="true"/>
    </div><br/><strong>Raised</strong>
  </div>
</Layout>
</div>

</Layout>

<Layout flex style="align-items: center;">

| neutral   |
| --------- |
| secondary |
| primary   |

| (normal) | interactive | disabled | pressed |
| -------- | ----------- | -------- | ------- |

</Layout>

## Palette

The color palette consists of Blues, Reds, Grays, Beiges, as well as pastel blue/red/green/yellow.

`fw-blue-010 - 100 - 400..900`

<div :class="[$style.swatch, $style.tiny]" style="background:var(--fw-blue-010)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-blue-100)" />
   
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-blue-400)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-blue-500)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-blue-600)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-blue-700)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-blue-800)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-blue-900)" />

`fw-red-010 - 100 - 400..900`

<div :class="[$style.swatch, $style.tiny]" style="background:var(--fw-red-010)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-red-100)" />
   
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-red-400)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-red-500)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-red-600)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-red-700)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-red-800)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-red-900)" />

`fw-gray-100..800 - 850 - 900 - 950 - 960 - 970`

<div :class="[$style.swatch, $style.small]" style="background:var(--fw-gray-100)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-gray-200)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-gray-300)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-gray-400)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-gray-500)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-gray-600)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-gray-700)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-gray-800)" />
<div :class="[$style.swatch, $style.tiny]" style="background:var(--fw-gray-850)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-gray-900)" />
<div :class="[$style.swatch, $style.tiny]" style="background:var(--fw-gray-950)" />
<div :class="[$style.swatch, $style.tiny]" style="background:var(--fw-gray-960)" />
<div :class="[$style.swatch, $style.tiny]" style="background:var(--fw-gray-970)" />

`fw-beige-100..400`

<div :class="[$style.swatch, $style.small]" style="background:var(--fw-beige-100)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-beige-200)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-beige-300)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-beige-400)" />

---

`fw-pastel-blue-1..4`

<div :class="[$style.swatch, $style.small]" style="background:var(--fw-pastel-blue-1)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-pastel-blue-2)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-pastel-blue-3)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-pastel-blue-4)" />

`fw-pastel-red-1..4`

<div :class="[$style.swatch, $style.small]" style="background:var(--fw-pastel-red-1)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-pastel-red-2)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-pastel-red-3)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-pastel-red-4)" />

`fw-pastel-purple-1..4`

<div :class="[$style.swatch, $style.small]" style="background:var(--fw-pastel-purple-1)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-pastel-purple-2)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-pastel-purple-3)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-pastel-purple-4)" />

`fw-pastel-green-1..4`

<div :class="[$style.swatch, $style.small]" style="background:var(--fw-pastel-green-1)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-pastel-green-2)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-pastel-green-3)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-pastel-green-4)" />

`fw-pastel-yellow-1..4`

<div :class="[$style.swatch, $style.small]" style="background:var(--fw-pastel-yellow-1)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-pastel-yellow-2)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-pastel-yellow-3)" />
<div :class="[$style.swatch, $style.small]" style="background:var(--fw-pastel-yellow-4)" />

---

In addition, we have a single shade of orange used for secondary indicators such as active tabs: `fw-secondary`

<div :class="$style.swatch" style="background:var(--fw-secondary)" />

## Theme

Many browsers automatically turn on "night mode" to lower the light emission of the screen. Users can override the browser theme in their settings menu.

In both "dark mode" and "light mode", the colors must provide adequate contrast and consistency.

All colors added through the `color` or the `propsToColor` function in `composable/colors.ts` respect this setting. If you need to define new colors, use the following syntax in your `scss`:

```scss
@include light-theme {
  --my-new-color: var(--fw-blue-400);
}
@include dark-theme {
  --my-new-color: var(--fw-blue-800);
}
```

It's good practice to limit the scope of a variable to the module that needs it:

```vue
<template>
  <div :class="$style.newColor" />
</template>

<style module lang="scss">
@include light-theme {
  --foreground-color: var(--fw-blue-400);
  --background-color: var(--fw-beige-100);
}
@include dark-theme {
  --foreground-color: var(--fw-pastel-blue-1);
  --background-color: var(--fw-gray-960);
}
.new-color {
  color: var(--foreground-color);
  background-color: var(--background-color);
}
</style>
```

Read more about [style modules in the corresponding vue docs](https://vuejs.org/api/sfc-css-features.html#css-modules).

For testing purposes and side-by-side comparisons, you can add the classes `force-dark-theme` and `force-light-theme`.

## Semantic colors

We use semantic color variables that can mean a different shade depending on the currently chosen theme

- primary
- secondary (default)
- destructive

## Color variants

For each semantic color, we set a foreground and a background. In addition, we need to check context: A button should have a stronger shade when the mouse is hovering over it. When a surface is raised over another surface, it should have a stronger shade, too.

**Variants:**

- ghost (default for most things except buttons)

  > affects text color but leaves the border and background transparent.
  > Make sure to provide a surface beneath with adequate contrast.

- outline

  > affects text color and border and leaves the background transparent
  > Make sure to provide a surface beneath with adequate contrast.

- solid (default for buttons)
  > affects text color, border color and background color

[-> Example: #variant](#variant)

**Variants can optionally be made interactive and/or raised:**

- no alteration (default)

- raised

> affects text color, border color and background color

- interactive

  > user interaction affects text color, border color and background color
  >
  > - can be disabled
  > - can be active
  > - can be exact-active
  > - can be hovering

- interactive-raised
  > combine `raised` and `interactive`

[-> Example: #interactive-and-or-raised](#interactive-and-or-raised)

## Theme color definitions

All colors are defined in `front/src/style/colors.scss`.

Its structure is as follows:

<Layout stack style="--width:100%; background:#0002;">

<Card solid purple title="(1) Palette">

Defining [all funkwhale color values](#palette)

</Card>

<Card solid blue title="(2) Choosing the semantic colors from the palette">

both for light and dark theme, and both normal and raised:

- default
- secondary
- primary
- destructive
- blue
- red
- purple
- green
- yellow

</Card>

<Card solid green title="(3) Applying colors">

(for all elements not managed by vitepress)

- (a) Applying colors to things with no explicit Variant props, such as headings and paragraphs, simple links, focusable elements
- (b) Applying colors to things with explicit Variant props: - solid (and default buttons) - ghost - outline

</Card>

</Layout>

## Change a color value

For example, you want to make all blue hues more cyan-ish or mute all reds.

- Find the color value you want to change in **section 1 (Palette)**
- Change it
- Keep this page open and check under [Palette](#palette) if the colors are still in harmony with each other. Also make sure all recommended color combinations still meet the relevant WCGA2 recommendations for contrast

## Alter the shade of a color

In funkwhale components, we use semantic color names such as `primary`, `destructive`, `default` (neutral). Now, you find, for example, that a secondary button has low contrast in light mode, and you decide to alter the text color.

- Find the relevant section in **section 2 (hoosing the semantic colors from the palette)**. In our example, it's `.secondary` under `theme-light`.
- You see that the values are `--color: var(--fw-gray-700);` and `--background-color: var(--fw-gray-200);`, and you change `--color` to `var(--fw-gray-900)`.
- Test your changes. If nothing changes, then there is a Css rule with higher precedence. Find and eliminate these sorts of competing rules.

## Choose a different style for a specific variant

For example, you want to add visible lines around ghost links and buttons when the user hovers over them.

- Find the variant class in **section 3 (Applying colors)**. In our example, it is `.ghost`.
- In our example, we would add the line `border-color: var(--hover-border-color);` under `&:hover` to make the outline on interactive items visible on hover.
- Make sure to test all affected components before committing and merging the changes

<style module>
    .swatch {
      transition:all .15s, filter 0s;
        border-radius: 2em;
        min-width: 3.2em;
        min-height: 3.2em;
        margin: 1ch;
        display: inline-flex;
        box-shadow: 1px 2px 7px #0003, 0px 0px 1px #0009;
        align-items:center;
        justify-items:center;
        position:relative;

        &::after {
          position:absolute;
          inset:13%;
          content:"fw";
          line-height:2.68em;
          font-size:80%;
          text-align: center;
          transform:rotate(15deg);
          letter-spacing:-.02em;
          font-weight:800;
        }
        &:is(:not(:global(.solid)):not(:hover),:has(*))::after {
          opacity:0
        }
    }
    :not(:hover)>.deemphasized {
      filter:blur(4px);
      opacity:.5;
      &::after {
        opacity:0;
      }
    }

    .small, .tiny {
        margin: .25rem;
        min-width: 1.6em;
        min-height: 1.6em;
        box-shadow: 1px 2px 4px #0002, 0px 0px 1px #0007;
        &::after{
          font-size:43%;
          outline: none;
        }
    }
    .tiny{
        margin:  .5rem .25rem;
        min-width: 1em;
        min-height: 1em;
        box-shadow: 1px 2px 4px #0002, 0px 0px 1px #0007;
        &::after{
          font-size:27%;
        }
    }
</style>