@aleph-alpha/config-css 0.14.23 → 0.15.1

package/CHANGELOG.md

@@ -1,3 +1,23 @@
+## 0.15.1 (2025-07-06)
+
+### 🩹 Fixes
+
+- **deps:** update unocss monorepo to v66.3.3
+
+### ❤️ Thank You
+
+- Renovatebot
+
+## 0.15.0 (2025-07-03)
+
+### 🚀 Features
+
+- **AST-1989:** Customization doc
+
+### ❤️ Thank You
+
+- Suraj Jadhav
+
 ## 0.14.23 (2025-07-03)
 
 ### 🧱 Updated Dependencies

package/README.md

@@ -103,6 +103,10 @@ graph TD
 
 ```
 
+## Config CSS Preset helps in UI Customization
+
+[Read more here](./customization.md)
+
 ## References
 
 The following packages are used to generate the presets:

package/customization.md

@@ -0,0 +1,217 @@
+# Config CSS Preset Customization Guide
+
+## Overview
+
+The Config CSS Preset package (`@aleph-alpha/config-css`) provides a centralized theming system that enables consistent customization across all Aleph Alpha Design System components and Pharia applications. This package allows developers to customize fonts and colors throughout the entire ecosystem by modifying CSS custom properties.
+
+## What Does Config CSS Preset Customize?
+
+The Config CSS Preset enables customization of two main visual aspects:
+
+- **Typography**: Font families that apply to all design system components
+- **Color Themes**: Brand and core UI colors used throughout applications
+
+These customizations are automatically applied to:
+- All components from `@aleph-alpha/ds-components-vue`
+- Any Pharia applications that consume the `@aleph-alpha/config-css` package
+
+## Font Customization
+
+### How Font Customization Works
+
+Config CSS Preset uses a sophisticated transformation process to make fonts customizable across the entire design system:
+
+#### 1. Token Processing
+The system processes font tokens defined in [`tokens.json`](https://gitlab.aleph-alpha.de/engineering/frontend-hub/-/blob/main/packages/config-css-preset/tokens.json) using Style Dictionary, a build system for design tokens.
+
+#### 2. Custom Transform Application
+A custom Style Dictionary transform called `custom/typography/font-family` (defined in the [config file](https://gitlab.aleph-alpha.de/engineering/frontend-hub/-/blob/main/packages/config-css-preset/sd.config.js)) processes these tokens.
+
+#### 3. Variable Substitution
+The transform replaces hardcoded font family references with CSS custom properties:
+
+**Before transformation:**
+```css
+font-family: 'Raleway';
+```
+
+**After transformation:**
+```css
+font-family: var(--custom-font-family, Raleway);
+```
+
+This approach ensures that:
+- All typography classes automatically expose the customizable font family variable
+- Applications can override fonts by simply updating the `--custom-font-family` CSS variable
+- A fallback font (Raleway) is always available if no custom font is specified
+
+### Available Font Options
+
+Currently, Config CSS Preset provides built-in support for two font families through the [font preset file](https://gitlab.aleph-alpha.de/engineering/frontend-hub/-/blob/main/packages/config-css-preset/src/presetWebFontsAlephAlpha.ts):
+
+- **Raleway** (default)
+- **Roboto**
+
+### Adding Custom Font Families
+
+You have two options for extending font family support:
+
+#### Option 1: Extend the Preset (Recommended for System-Wide Fonts)
+Add new font definitions to the existing preset file by following the established code patterns. This approach makes fonts available across all applications using the preset.
+
+#### Option 2: Application-Level Implementation (Recommended for App-Specific Fonts)
+1. Define your custom `@font-face` declarations in your Pharia application
+2. Update the `--custom-font-family` CSS variable to reference your custom font
+
+**Example:**
+```css
+@font-face {
+  font-family: 'MyCustomFont';
+  src: url('./assets/fonts/MyCustomFont.woff2') format('woff2');
+  font-weight: normal;
+  font-style: normal;
+}
+
+:root {
+  --custom-font-family: 'MyCustomFont';
+}
+```
+
+### Updating Font Variables
+
+#### JavaScript Method
+```javascript
+// Update font family dynamically
+document.documentElement.style.setProperty(
+  '--custom-font-family',
+  'Your-Custom-Font-Family'
+);
+```
+
+#### CSS Method
+```css
+:root {
+  --custom-font-family: 'Your-Custom-Font-Family';
+}
+```
+
+## Color Customization
+
+### Understanding the Color Token System
+
+Config CSS Preset transforms design system color tokens into customizable CSS variables using a combination of Style Dictionary and UnoCSS preset functionality.
+
+### Exploring Available Color Tokens
+
+To discover all available color tokens in your system:
+
+#### 1. Build the Token Files
+Run the following command from your project root:
+```bash
+nx run config-css-preset:build
+```
+
+#### 2. Examine Generated Files
+This command generates a structured output directory:
+```
+config-css-preset/
+  sd-output/
+    box-shadows.json     # Shadow token definitions
+    dark-mode.json       # Dark theme color tokens
+    global.json          # Global design tokens
+    light-mode.json      # Light theme color tokens
+    spacings.json        # Spacing and layout tokens
+    typography.json      # Typography-related tokens
+```
+
+#### 3. Review Color Tokens
+Open `config-css-preset/sd-output/light-mode.json` to see all available color tokens, including:
+- `brand-*` tokens: Brand-specific colors
+- `core-*` tokens: Core UI and system colors
+
+### Color Token Transformation
+
+The Config CSS Preset automatically transforms design tokens into CSS custom properties using a consistent naming convention:
+
+#### Transformation Examples
+
+**Brand Background Token:**
+```
+Design Token: brand-bg-brand
+CSS Variable: --un-preset-theme-colors-brand-bg-brand
+```
+
+**Core Content Token:**
+```
+Design Token: core-content-secondary
+CSS Variable: --un-preset-theme-colors-core-content-secondary
+```
+
+#### Naming Convention Breakdown
+- **Prefix**: `--un-preset-theme-colors-`
+- **Token Name**: The original design token name (e.g., `brand-bg-brand`)
+- **Result**: A globally accessible CSS custom property
+
+### Color Value Format
+
+Color values in Config CSS Preset use a specific RGB format optimized for flexibility:
+
+**Format**: Space-separated RGB values without `rgb()` wrapper
+**Example**: `"205 231 4"`
+
+### Updating Color Variables
+
+#### JavaScript Method
+```javascript
+// Update a specific color token
+document.documentElement.style.setProperty(
+  '--un-preset-theme-colors-brand-bg-brand',
+  '255 128 0' // RGB values for orange
+);
+
+// Update multiple colors programmatically
+const customColors = {
+  'brand-bg-brand': '255 128 0',
+  'core-content-secondary': '64 64 64',
+  'core-bg-primary': '248 250 252'
+};
+
+Object.entries(customColors).forEach(([token, value]) => {
+  document.documentElement.style.setProperty(
+    `--un-preset-theme-colors-${token}`,
+    value
+  );
+});
+```
+
+#### CSS Method
+```css
+:root {
+  /* Brand colors */
+  --un-preset-theme-colors-brand-bg-brand: 255 128 0;
+  
+  /* Core UI colors */
+  --un-preset-theme-colors-core-content-secondary: 64 64 64;
+  --un-preset-theme-colors-core-bg-primary: 248 250 252;
+}
+```
+
+## Technical Architecture
+
+### Style Dictionary Integration
+Config CSS Preset leverages Style Dictionary's token transformation capabilities to:
+- Process design tokens from JSON files
+- Apply custom transforms for font and color handling
+- Generate CSS custom properties with consistent naming
+
+### UnoCSS Preset Integration
+The UnoCSS preset automatically:
+- Generates utility classes based on design tokens
+- Creates CSS custom properties for runtime customization
+- Ensures consistent theming across atomic CSS classes
+
+## Additional Resources
+
+- [Style Dictionary Documentation](https://amzn.github.io/style-dictionary/) - Complete guide to design token transformations
+- [UnoCSS Documentation](https://unocss.dev/) - Atomic CSS framework reference
+- [Aleph Alpha Design System](https://gitlab.aleph-alpha.de/engineering/frontend-hub) - Design system repository and guidelines

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@aleph-alpha/config-css",
   "license": "Apache-2.0",
-  "version": "0.14.23",
+  "version": "0.15.1",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",
   "prettier": "@aleph-alpha/prettier-config-frontend",
@@ -15,7 +15,7 @@
   },
   "dependencies": {
     "@tokens-studio/sd-transforms": "2.0.1",
-    "@unocss/preset-legacy-compat": "66.3.1",
+    "@unocss/preset-legacy-compat": "66.3.3",
     "token-transformer": "0.0.33",
     "unocss": "^66.0.0",
     "unocss-preset-animations": "1.2.1",