diff --git a/packages/react/src/docs/colors.mdx b/packages/react/src/docs/colors.mdx index 18d07af..f771e4a 100644 --- a/packages/react/src/docs/colors.mdx +++ b/packages/react/src/docs/colors.mdx @@ -17,7 +17,7 @@ Cunningham comes with an existing toolkit to deal with colors, and it's easy. dark format={false} code={` -
+
`} /> @@ -32,7 +32,7 @@ You can use custom utility classes to set the background color of an element. Th dark format={false} code={` -
+
`} /> @@ -51,7 +51,7 @@ You can use custom utility classes to set the color attribute of an element. The dark format={false} code={` -
Nice primary-500 colored text
+
Nice primary-500 colored text
`} /> @@ -77,10 +77,9 @@ You can customize the values of the color design tokens with the configuration f export default { themes: { default: { - theme: { + globals: { colors: { - 'primary-500': 'purple', // You can customize the existing primary-500 color. ( bg-primary-500, clr-primary-500 classes ), - 'primary-text': 'cream', + 'brand-500': 'purple', // You can customize the existing brand color. 'amazing-500': 'pink', // You can add a new color. ( bg-amazing-500, clr-amazing-500 classes will be generated ) }, }, diff --git a/packages/react/src/docs/colors.stories.tsx b/packages/react/src/docs/colors.stories.tsx index 9e8023d..09aaf7c 100644 --- a/packages/react/src/docs/colors.stories.tsx +++ b/packages/react/src/docs/colors.stories.tsx @@ -72,7 +72,7 @@ export const BackgroundColors: Story = { className={"bg-" + color + "-" + tint} /> 
-                  bg-{color}-{tint}
+                  bg-semantic-{color}-{tint}
))} @@ -85,10 +85,10 @@ export const BackgroundColors: Story = { export const ContextualBackgrounds: Story = { render: () => { - const { background } = tokens.themes.default.contextuals; + const { semantic } = tokens.themes.default.contextuals.background; // Extract all background values from the contextuals - const backgroundEntries = Object.entries(background).flatMap( + const backgroundEntries = Object.entries(semantic).flatMap( ([category, values]) => { if (typeof values === "object" && values !== null) { return Object.entries(values).map(([key, value]) => ({ @@ -176,7 +176,7 @@ export const ContextualBackgrounds: Story = { marginTop: "0.25rem", }} > - .bg-{fullKey} + .bg-semantic-{fullKey}
))} @@ -225,13 +225,13 @@ export const Example: Story = { render: () => { return ( <> -
+
I am a text on top of a primary-500 background 👋
-
+
I am a text on top of a secondary-500 background 👋
-
+
I am a text on top of a danger-500 background 👋
diff --git a/packages/react/src/docs/customization.mdx b/packages/react/src/docs/customization.mdx index 06d5c5c..5fbc4bf 100644 --- a/packages/react/src/docs/customization.mdx +++ b/packages/react/src/docs/customization.mdx @@ -14,7 +14,7 @@ Design tokens are the fundamental variables defining the precise behavior and re For example it could be: -- The primary color of a text element +- The brand color - The standard spacing between two elements - The border radius of a button - ... @@ -36,9 +36,9 @@ import { DefaultTokens } from "@openfun/cunningham-react"; const config: DefaultTokens = { themes: { default: { - theme: { + globals: { colors: { - "primary-500": "purple", + "brand-500": "purple", }, }, }, @@ -58,9 +58,9 @@ Or if you prefer Javascript, create a file named `cunningham.cjs` at the root of module.exports = { themes: { default: { - theme: { + globals: { colors: { - "primary-500": "purple", + "brand-500": "purple", }, }, }, @@ -103,7 +103,7 @@ import { DefaultTokens } from "@openfun/cunningham-react"; const config: DefaultTokens = { themes: { default: { - theme: { + globals: { ... }, components: { @@ -143,7 +143,7 @@ import { defaultTokens, DefaultTokens } from "@openfun/cunningham-react"; const config: DefaultTokens = { themes: { default: { - theme: { + globals: { ... }, components: { @@ -161,7 +161,7 @@ export default config; > Be careful, `DefaultTokens` with a capital `D` is the type of the default tokens, while `defaultTokens` with a lowercase `d` is the object containing the default tokens. -You can also use more global design tokens from `defaultTokens.theme`, like that: +You can also use more global design tokens from `defaultTokens.globals` and `defaultTokens.contextuals`, like that: + +# Objective + +The Cunningham color system has been revised with a methodical approach focused on modularity and accessibility. This revision enables the systematic generation of coherent themes, the automatic implementation of display modes (light/dark), the constant maintenance of contrast ratios independently of the selected theme, and the structured allocation of colors according to their role (background, content, border). + +An algorithm (available soon) has been developed to facilitate the rapid generation and adaptation of color palettes, producing a JSON file compatible with the existing infrastructure and natively supporting both light and dark display modes. This algorithmic solution optimizes Cunningham's adaptability to a wide range of user environments. + + + +# Structure + +The color system is structured around two complementary, interdependent palettes: + +1. The "Color Primitive" palette is the exhaustive repository of color values specific to a given theme, defining all available shades. +2. The "Color Contextual" palette establishes a functional interface between primitive values and user interface components via a semantic abstraction layer. + +This two-tier architecture facilitates the systematic propagation of changes: any alteration to the primitive palette is automatically reflected in all interface elements without the need for additional adjustments (see Figure 1). + + +
+ Changing the color primitive palette automatically updates the color contextual palette while maintaining contrast ratios inside components. +
Figure 1. Changing the color primitive palette automatically updates the color contextual palette while maintaining contrast ratios inside components.
+
+ +A **theme** is a comprehensive color configuration derived from a brand's visual identity. It constitutes a specific implementation of the "Color Primitive" palette with predetermined color values. The Cunningham theme is provided as the default reference. + +A **mode** represents a systematic modulation of luminance and contrast parameters from an established theme, executed through the "Color Contextual" palette. This parametric adjustment accommodates diverse usage contexts while preserving the fundamental chromatic identity. Standard implementations include light and dark modes. These could be supplemented with specialized modes (such as high contrast) to meet specific accessibility needs or style requirements. + + +# Palettes + +## Color Primitive + +The Color Primitive palette includes 16 colors. Each color is available in 19 distinct shades, except gray, which contains 22. Each shade is referenced by a number between 000 and 1000. A shade of 000 corresponds to pure white, while a shade of 1000 corresponds to pure black. Each intermediate shade value is then defined on the basis of the perceived luminance noted L* in the CIELAB color space ([more info on CIELAB](https://en.wikipedia.org/wiki/CIELAB_color_space)). Using L* as a reference ensures that each primitive color fits into a predictable tonal scale, regardless of hue or saturation. This ensures consistent contrast levels across all themes, promoting universal accessibility. The correspondence between shade (S) and perceived luminance (L*) is as follows: $S=1000 \times (1-L^*)$ with $L^* \in [0;1]$. See Figure 2 for an example. + + +
+ Breakdown of the first 6 colors of a Color Primitive theme. Gray includes 3 complementary shades. +
Figure 2. Breakdown of the first 6 colors of a "Color Primitive" theme. Gray includes 3 complementary shades.
+
+ +To optimize visual ergonomics in dark mode, it is necessary to reduce color saturation in the darkest shades (S > 600). This gradual desaturation avoids perceptual glare in dark mode and improves legibility in low ambient light environments. + +An algorithm will soon be available to automatically adjust the parameters of perceived luminance (L*) and saturation (C*) according to a decreasing function for dark shades, while preserving the integrity of the theme's visual identity. + +## Color Contextual + +
+ Excerpt from the Color Contextual palette for the background.semantic.brand role, with light and dark modes. +
Figure 3. excerpt from the "Color Contextual" palette for the background.semantic.brand role, with light and dark modes.
+
+ +The "Color Contextual" palette allows you to classify the various colors of a theme according to their actual use, differentiating between each of the modes (light, dark, etc.). This makes it possible (1) to simplify and limit errors when assigning colors to different components, and (2) to manage multiple modes. + +This palette introduces the notion of roles, whose format is as follows: + + + +### Layer + +The layer designates the visual rendering level of an interface element, and is divided into three distinct categories: + +- Background: Background layer serving as visual support for components (e.g., button background). +- Content: Informative elements conveying a message (e.g., text, iconography) +- Border : Peripheral delimitation of components + +### Scope + +The scope determines the functional area of application of a color according to the following hierarchy: + +- Surface: Structural elements of the interface with different levels of elevation (e.g., backgrounds, modals, maps). +- Semantic: Interactive elements communicating a specific meaning to the user. +- Palette: set of colors for specific applications requiring customization (e.g., color selection for avatars) + +### Intent (optional) + +The intent specifies the communicative function associated with the scope. It provides an additional contextual specification of the element's purpose in the interface. + +### Variant + +The variant establishes a hierarchy of visual importance according to the following taxonomy: + +- Primary: Overriding importance, attracts priority attention +- Secondary: Intermediate importance, supports primary elements +- Tertiary: Subordinate importance, provides additional information +- On [...]: Color inversion mechanism to ensure legibility of superimposed content (applicable to layer content only) + +### State (optional) + +The state characterizes the interactional state of an interface element (e.g., Hover, Active, Disabled), making it possible to visually communicate its reactivity to the user. + +# **Accessibility** + +Accessibility is a fundamental principle guiding the design of this color system. As demonstrated in the Color Primitive section, the methodical standardization of luminance values (L*) ensures consistent contrast ratios, regardless of the theme or display mode selected. This systematic approach eliminates the need to re-evaluate accessibility parameters when implementing new themes, ensuring ongoing compliance with WCAG accessibility standards. The main objective is to establish an accessibility framework that is invariant and resilient in the face of multiple usage contexts. + +# **Technical implementation** + +Du à tout les changements, et à l'architecture des tokens, toutes les variables css ont changés. Vous devez donc mettre à jour vos variables css. Il faut absolument +regénérer vos tokens avec la commande `cunningham -g css,ts,js` pour avoir les nouvelles variables css. + +Dans le cas des tokens d'un theme, toutes les valeurs sémantiques sont dans le ```theme.globals```. Cela correspond aux couleurs primitives, transitions, fonts, spacings, breakpoints, font weights, font families, etc. +De fait toutes les valeurs contextuelles sont dans le ```theme.contextuals```. Cela correspond aux couleurs de fond, aux couleurs de contenu, aux couleurs de bordure, aux couleurs de palette, etc. + + +```json +// Old structure +{ + "themes": { + "default": { + "theme": { + "colors": "..." + "font": "..." + "spacings": "..." + "breakpoints": "..." + "...": "..." + }, + "components": { + "button": { + "...": "..." + } + } + + } + } +} + + +// New structure +{ + "themes": { + "default": { + "globals": { + "colors": "..." + "font": "..." + "spacings": "..." + "breakpoints": "..." + "...": "..." + }, + "contextuals": { + "background": { + "...": "..." + } + "content": { + "...": "..." + } + "border": { + "...": "..." + } + } + "components": { + "button": { + "...": "..." + } + } + } + + } + +} +``` + +## **Migration Steps** + + +### **1. Update Dependencies** + +First, update your `package.json` to use version 4.0.0: + +```json +{ + "dependencies": { + "@openfun/cunningham-react": "^4.0.0" + } +} +``` + +### **2. Regenerate Tokens** + +Run the token generation command to get the new CSS variables: + +```bash +cunningham -g css,ts,js +``` + +This command will generate the new CSS variables compatible with the new structure. + +### **3. Update CSS Variables in Your Code** + +All your references to old CSS variables will need to be updated. The new variables follow this structure: + +```css +/* Old structure (v3) */ +.test { + color: var(--c--theme--colors--primary-500) +} + +/* New structure (v4) */ +.test { + color: var(--c--globals--colors--brand-500); + color: var(--c--contextuals--background--semantic--brand--primary); + color: var(--c--contextuals--content--semantic--brand--primary); + color: var(--c--contextuals--border--semantic--brand--primary); + color: var(--c--contextuals--palette--brand--primary); +} + +``` + +### **3. Update Button Props** + +Dans le cas du button, il faut mettre à jour les props `color` et `variant` pour utiliser le nouveau structure. +La props color correspond au color primitive et la props variant au type de button. + +```tsx +/* Old structure (v3) */ +