feat(ppw-ds): extend design system with generated color tokens and spacing semantic tokens

projects/ppwcode/ng-ppw-ds/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ppwcode/ng-ppw-ds",
-    "version": "0.0.3",
+    "version": "0.0.4",
     "peerDependencies": {
         "@angular/common": "^22.0.0",
         "@angular/core": "^22.0.0"

projects/ppwcode/ng-ppw-ds/ppw-ds.scss

@@ -1,2 +1,4 @@
+@forward 'src/lib/scss/colors';
+
 @use 'src/lib/scss/shapes';
 @use 'src/lib/scss/spacings';

projects/ppwcode/ng-ppw-ds/src/lib/docs/Colors.mdx

@@ -0,0 +1,35 @@
+import { Canvas, Meta } from '@storybook/addon-docs/blocks';
+import * as ColorsStories from '../stories/colors.stories'
+
+<Meta of={ColorsStories} />
+
+# Colors
+
+Color tokens provide a consistent set of shades for brand, supporting, status, and neutral colors. Use these tokens instead of hardcoded color values so applications can share a coherent palette and update it centrally.
+
+## Setup
+
+Generate the color tokens from Angular Material M3 primary and tertiary palettes in a global selector. The other scales are derived from the primary palette.
+
+```scss
+@use '@angular/material' as mat;
+@use '@ppwcode/ng-ppw-ds' as ppwDs;
+
+:root {
+    @include ppwDs.ppw-ds-material-color-tokens(mat.$azure-palette, mat.$green-palette);
+}
+```
+
+## Usage
+
+Tokens follow the syntax `--ppw-ds-[scheme]-[level]`.
+
+The available schemes are `primary`, `secondary`, `tertiary`, `error`, `success`, and `neutral`; each scheme provides levels from `100` through `600`, progressively darkening.
+
+```scss
+.call-to-action {
+    background-color: var(--ppw-ds-primary-500);
+}
+```
+
+<Canvas of={ColorsStories.AllColors} />

projects/ppwcode/ng-ppw-ds/src/lib/docs/Spacings.mdx

@@ -18,3 +18,18 @@ A linear spacing level is the multiplication of 4. Level 0 thus means 0px, where
 <Canvas of={SpacingsStories.AllLevels} />
 
 The tokens `--ppw-ds-spacing-1px` and `--ppw-ds-spacing-2px` are explicit and intended for usage where space is limited and decreasing density would otherwise bring visual items far too close to each other.
+
+### Semantic tokens
+
+Use the semantic spacing tokens when the required spacing corresponds to a named size. These tokens reference the linear scale, so their values remain consistent with the rest of the spacing system.
+
+| Token                       | Linear token           | Value |
+| --------------------------- | ---------------------- | ----- |
+| `--ppw-ds-spacing-small`    | `--ppw-ds-spacing-2`   | 8px   |
+| `--ppw-ds-spacing-medium`   | `--ppw-ds-spacing-4`   | 16px  |
+| `--ppw-ds-spacing-large`    | `--ppw-ds-spacing-6`   | 24px  |
+| `--ppw-ds-spacing-xlarge`   | `--ppw-ds-spacing-8`   | 32px  |
+
+### Layout tokens
+
+Use `--ppw-ds-spacing-gutter` for the spacing between layout elements. It currently references `--ppw-ds-spacing-small` (8px).

projects/ppwcode/ng-ppw-ds/src/lib/scss/_colors.scss

@@ -0,0 +1,53 @@
+@use 'sass:map';
+
+/*
+Mixin that generates the ppwcode design system tokens for the given name, Material palette and tone mapping.
+ */
+@mixin _ppw-color-scale($name, $palette, $tones) {
+    @each $token, $tone in $tones {
+        --ppw-ds-#{$name}-#{$token}: #{map.get($palette, $tone)};
+    }
+}
+
+/*
+Mixin that generates the ppwcode design system color tokens for primary, secondary, tertiary, error, success and neutral
+color schemes based on the given Material design primary and tertiary palettes.
+ */
+@mixin ppw-ds-material-color-tokens($primary-palette, $tertiary-palette) {
+    // Default mapping for tones from our levels (100-600) and their corresponding values in the Material palette.
+    $standard-tones: (
+        100: 95,
+        200: 90,
+        300: 80,
+        400: 60,
+        500: 40,
+        600: 30
+    );
+
+    @include _ppw-color-scale('primary', $primary-palette, $standard-tones);
+    @include _ppw-color-scale('secondary', map.get($primary-palette, 'secondary'), $standard-tones);
+    @include _ppw-color-scale('tertiary', $tertiary-palette, $standard-tones);
+    @include _ppw-color-scale('error', map.get($primary-palette, 'error'), $standard-tones);
+
+    // Neutral uses a different tone mapping because the standard mapping has no clear differences between the values.
+    @include _ppw-color-scale(
+        'neutral',
+        map.get($primary-palette, 'neutral'),
+        (
+            100: 100,
+            200: 98,
+            300: 90,
+            400: 80,
+            500: 60,
+            600: 30
+        )
+    );
+
+    // Material theming provides an error palette, but no success palette, so these are hardcoded for now.
+    --ppw-ds-success-100: #b5e7cf;
+    --ppw-ds-success-200: #92dcb8;
+    --ppw-ds-success-300: #60cc97;
+    --ppw-ds-success-400: #41c283;
+    --ppw-ds-success-500: #11b364;
+    --ppw-ds-success-600: #0fa35b;
+}

projects/ppwcode/ng-ppw-ds/src/lib/scss/_spacings.scss

@@ -11,4 +11,11 @@ $_base-spacing: 4px;
     @for $i from 0 through 20 {
         --ppw-ds-spacing-#{$i}: #{$i * $_base-spacing};
     }
+
+    --ppw-ds-spacing-small: var(--ppw-ds-spacing-2);
+    --ppw-ds-spacing-medium: var(--ppw-ds-spacing-4);
+    --ppw-ds-spacing-large: var(--ppw-ds-spacing-6);
+    --ppw-ds-spacing-xlarge: var(--ppw-ds-spacing-8);
+
+    --ppw-ds-spacing-gutter: var(--ppw-ds-spacing-small);
 }

projects/ppwcode/ng-ppw-ds/src/lib/stories/colors.stories.scss

@@ -0,0 +1,41 @@
+@use '@angular/material' as mat;
+@use 'ppw-ds' as ppwDs;
+
+:host {
+    @include ppwDs.ppw-ds-material-color-tokens(mat.$azure-palette, mat.$green-palette);
+
+    display: block;
+}
+
+.schemes {
+    display: grid;
+    gap: var(--ppw-ds-spacing-8);
+}
+
+.scheme h2 {
+    margin: 0 0 var(--ppw-ds-spacing-3);
+    font-size: 18px;
+}
+
+.swatches {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(112px, 1fr));
+    gap: 12px;
+}
+
+.swatch {
+    overflow: hidden;
+    border: 1px solid light-dark(#d8d8d8, #5f5f5f);
+    border-radius: var(--ppw-ds-radius-small);
+    background: light-dark(#ffffff, #242424);
+}
+
+.swatch__color {
+    min-height: 80px;
+}
+
+.swatch code {
+    display: block;
+    padding: var(--ppw-ds-spacing-2) var(--ppw-ds-spacing-3);
+    color: light-dark(#242424, #f5f5f5);
+}

projects/ppwcode/ng-ppw-ds/src/lib/stories/colors.stories.ts

@@ -0,0 +1,56 @@
+import { ChangeDetectionStrategy, Component } from '@angular/core'
+import { Meta, StoryObj } from '@storybook/angular'
+
+const colorSchemes = [
+    { id: 'primary', label: 'Primary' },
+    { id: 'secondary', label: 'Secondary' },
+    { id: 'tertiary', label: 'Tertiary' },
+    { id: 'error', label: 'Error' },
+    { id: 'success', label: 'Success' },
+    { id: 'neutral', label: 'Neutral' }
+] as const
+
+const colorLevels = [100, 200, 300, 400, 500, 600] as const
+
+@Component({
+    selector: 'ppw-colors-example',
+    standalone: true,
+    template: `
+        <div class="schemes">
+            @for (scheme of colorSchemes; track scheme.id) {
+                <section class="scheme" [attr.aria-labelledby]="scheme.id + '-heading'">
+                    <h2 [id]="scheme.id + '-heading'">{{ scheme.label }}</h2>
+                    <div class="swatches">
+                        @for (level of colorLevels; track level) {
+                            <div class="swatch">
+                                <div
+                                    class="swatch__color"
+                                    [style.background-color]="'var(--ppw-ds-' + scheme.id + '-' + level + ')'"
+                                    [attr.aria-label]="scheme.label + ' color, level ' + level"
+                                    role="img"
+                                ></div>
+                                <code>{{ level }}</code>
+                            </div>
+                        }
+                    </div>
+                </section>
+            }
+        </div>
+    `,
+    styleUrl: './colors.stories.scss',
+    changeDetection: ChangeDetectionStrategy.OnPush
+})
+export class ColorsExampleComponent {
+    protected readonly colorSchemes = colorSchemes
+    protected readonly colorLevels = colorLevels
+}
+
+const meta: Meta<ColorsExampleComponent> = {
+    title: 'ng-ppw-ds/Colors',
+    component: ColorsExampleComponent
+}
+
+export default meta
+type Story = StoryObj<ColorsExampleComponent>
+
+export const AllColors: Story = {}