chore(ui-docs): improve color documentation and clean up colors.ts

front/src/composables/colors.ts

@@ -1,6 +1,4 @@
-import { toValue, type MaybeRefOrGetter } from "@vueuse/core"
+import type { KeysOfUnion } from "type-fest"
-import type { Entry, Join, KeysOfUnion, RequireExactlyOne, RequireOneOrNone, Simplify, SingleKeyObject, UnionToIntersection } from "type-fest"
-import { computed } from 'vue'
 
 export type DefaultProps =
   | { default?: true }

front/ui-docs/using-color.md

@@ -2,6 +2,8 @@
 import { color } from "~/composables/colors.ts"
 import Button from "~/components/ui/Button.vue"
 import Card from "~/components/ui/Card.vue"
+import Layout from "~/components/ui/Layout.vue"
+import Spacer from "~/components/ui/layout/Spacer.vue"
 </script>
 
 # Using Color
@@ -10,21 +12,29 @@ import Card from "~/components/ui/Card.vue"
 
 [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 title="solid red" solid red />
+<Card solid red title='🌈' />
 ```
 
-<Card title="solid red" solid red />
+<div class="preview">
+  <Card solid red title='🌈' />
+</div>
+
+</Layout>
 
 ## Add color to a any component or Html tag
 
-1. Choose a
+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";
@@ -35,7 +45,11 @@ import { color } from "~/composables/colors.ts";
 </template>
 ```
 
-<div :class="$style.swatch" v-bind="color('primary solid interactive raised')" />
+<div class="preview">
+  <div :class="$style.swatch" v-bind="color('primary solid interactive raised')" />
+</div>
+
+</Layout>
 
 ## Base colors
 
@@ -88,6 +102,7 @@ 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>
 
@@ -96,6 +111,7 @@ Solid (default), Ghost, Outline
 <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>
 
@@ -133,8 +149,11 @@ Solid (default), Ghost, Outline
 
 The color palette consists of Blues, Reds, Grays, Beiges, as well as pastel blue/red/green/yellow.
 
-<div :class="[$style.swatch, $style.small]" style="background:var(--fw-blue-010)" />
+`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)" />
@@ -142,10 +161,11 @@ The color palette consists of Blues, Reds, Grays, Beiges, as well as pastel blue
 <div :class="[$style.swatch, $style.small]" style="background:var(--fw-blue-800)" />
 <div :class="[$style.swatch, $style.small]" style="background:var(--fw-blue-900)" />
 
-<br/>
+`fw-red-010 - 100 - 400..900`
 
-<div :class="[$style.swatch, $style.small]" style="background:var(--fw-red-010)" />
+<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)" />
@@ -153,7 +173,7 @@ The color palette consists of Blues, Reds, Grays, Beiges, as well as pastel blue
 <div :class="[$style.swatch, $style.small]" style="background:var(--fw-red-800)" />
 <div :class="[$style.swatch, $style.small]" style="background:var(--fw-red-900)" />
 
-<br/>
+`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)" />
@@ -169,7 +189,7 @@ The color palette consists of Blues, Reds, Grays, Beiges, as well as pastel blue
 <div :class="[$style.swatch, $style.tiny]" style="background:var(--fw-gray-960)" />
 <div :class="[$style.swatch, $style.tiny]" style="background:var(--fw-gray-970)" />
 
-<br/>
+`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)" />
@@ -178,40 +198,44 @@ The color palette consists of Blues, Reds, Grays, Beiges, as well as pastel blue
 
 ---
 
+`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)" />
 
-<br/>
+`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)" />
 
-<br/>
+`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)" />
 
-<br/>
+`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)" />
 
-<br/>
+`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:
+---
+
+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)" />
 
@@ -221,6 +245,42 @@ Many browsers automatically turn on "night mode" to lower the light emission of
 
 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).
+
 ## Semantic colors
 
 We use semantic color variables that can mean a different shade depending on the currently chosen theme
@@ -233,37 +293,44 @@ We use semantic color variables that can mean a different shade depending on the
 
 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.
 
-- ghost (default for most other things)
+**Variants:**
 
-  - text color
+- 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
 
-  - border color
+  > affects text color and border and leaves the background transparent
+  > Make sure to provide a surface beneath with adequate contrast.
 
 - solid (default for buttons)
-  - bg color
+  > affects text color, border color and background color
-  - border color
 
-Variants can be made interactive and/or raised:
+[-> Example](#variant)
+
+**Variants can optionally be made interactive and/or raised:**
 
 - no alteration (default)
 
 - raised
 
-  - text color
+> affects text color, border color and background color
-  - border color
-  - bg color
 
 - interactive
 
-  - can be disabled
+  > user interaction affects text color, border color and background color
-  - can be active
+  >
-  - can be exact-active
+  > - can be disabled
-  - can be hovering
+  > - can be active
+  > - can be exact-active
+  > - can be hovering
 
 - interactive-raised
-  - combine `raised` and `interactive`
+  > combine `raised` and `interactive`
+
+[-> Example](#interactive-andor-raised)
 
 <style module>
     .swatch {
@@ -275,18 +342,47 @@ Variants can be made interactive and/or raised:
         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;
+          outline: 2.5px dashed currentcolor;
+          outline-offset:-.95em;
+          transform:rotate(15deg);
+          letter-spacing:-.02em;
+          font-weight:800;
+        }
+        &:is(:not(:global(.solid)):not(:hover),:has(*))::after{
+          opacity:0
+        }
+
+        &:not(:hover)::after{
+          outline-color:transparent;
+        }
     }
 
-    .small{
+    .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>