@aleph-alpha/config-css

Config CSS Preset

@aleph-alpha/config-css-preset

This package provides a basic configuration preset for CSS. It includes a set of default styles and configurations that can be easily customized to fit your project's needs.

Installation

To integrate this package into your project, Install the package using a package manager e.g pnpm:

pnpm add @aleph-alpha/config-css-preset

Usage

To use the preset in your project, follow these steps:

CSS Setup

You need to set up UnoCSS in your project. UnoCSS is a utility-first CSS framework that allows for a more efficient and consistent styling approach.

For detailed instructions on setting up UnoCSS, please refer to the UnoCSS Installation Guide. This guide will walk you through the process of installing UnoCSS and configuring it for your project.

After setting up UnoCSS, you need to add the Aleph Alpha CSS preset to your UnoCSS configuration.

// unocss.config.ts
import { defineConfig } from 'unocss';

import { presetAlephAlpha, designSystemContentPathConfig } from '@aleph-alpha/config-css-preset';
import { presetAlephAlphaIcons } from '@aleph-alpha/ds-icons';

export default defineConfig({
  ...getDesignSystemContentPathConfig('svelte' | 'vue'),
  presets: [presetAlephAlpha()],
});

How to use

All available design tokens are defined here tokens. Use the design tokens in your project as following:

<p class="color-core-content-primary">color-core-content-primary</p>
<div class="border-r-core-border-primary">border-r-core-border-primary</div>
<p class="label-12">label-12</p>
<div class="shadow-dropdowns">Dropdown Shadow</div>

Dark Theme

If you want to apply the dark theme, set a top level dark class, e.g. to the body tag

<body class="dark">
  <p class="color-core-content-primary">color-core-content-primary</p>
</body>

Development

To develop this package, clone the repository and run the following commands:

pnpm install
pnpm build

Explaination

The packages purpose is to take in Figma Tokens via the Figma Plugin Tokens Studio and transform it to be exposed as Tokens in UnoCss.

The build steps are as follows:

1. Designer pushes token changes from Figma to a tokens.json file and opens a MR.
2. When the MR is merged, the pipeline runs and triggers the build process.
3. Tokens from tokens.json are transformed, split into different categories and stored in the transformed-tokens directory with token-transformer so that style dictionary can read them. Categories are light-mode, dark-mode and global
4. The transformed tokens are then processed with style-dictionary to generate tokens that can be used in UnoCss. The processed tokens are stored in the sd-output directory.
5. The processed tokens in sd-output are then used to create UnoCss presets.
6. The UnoCss presets are then bundled up with vite and the final package is stored in the dist directory.

graph TD
    A[Designer pushes token changes from Figma to tokens.json] --> B[Open MR]
    B --> C{MR merged?}
    C -->|Yes| D[Pipeline runs]
    D --> E[Trigger build process]
    E --> F[Transform and split tokens with token-transformer]
    F --> G[Store transformed tokens in transformed-tokens directory]
    G --> H[Process tokens with style-dictionary]
    H --> I[Store processed tokens in sd-output directory]
    I --> J[Create UnoCss presets]
    J --> K[Bundle presets with Vite]
    K --> L[Store final package in dist directory]
    C -->|No| B
    subgraph Token Categories
        F --> F1[light-mode]
        F --> F2[dark-mode]
        F --> F3[global]
    end

Font Conversion Utility

This package includes a utility script for converting WOFF2 font files to TypeScript files with base64-encoded data. This is useful for embedding fonts directly in your application.

Usage

The convert-fonts.js script is located at packages/config-css-preset/src/utils/convert-fonts.js and can be used as follows:

node packages/config-css-preset/src/utils/convert-fonts.js <input.woff2> <output.ts>

Example

node packages/config-css-preset/src/utils/convert-fonts.js montserrat600.woff2 montserrat600.woff2.ts

This will:

1. Read the WOFF2 font file
2. Convert it to base64 format
3. Generate a TypeScript file with an exported constant containing the base64 data
4. The constant name is derived from the output filename

The generated TypeScript file will look like:

export const montserrat600 = 'data:font/woff2;base64,<base64-encoded-font-data>';

Config CSS Preset helps in UI Customization

Read more here

References

The following packages are used to generate the presets:

• unocss
• unocss-preset-theme
• @tokens-studio/sd-transforms
• token-transformer
• style-dictionary

See the source code for details on the configuration of the Aleph Alpha CSS preset.