@justeattakeaway/pie-css 0.28.0 → 0.28.1

package/docs/components/RADIO.md

@@ -0,0 +1,130 @@
+# PIE CSS Radio Component Styles
+
+[Source Code](https://github.com/justeattakeaway/pie/tree/main/packages/tools/pie-css) | [NPM Package](https://www.npmjs.com/package/@justeattakeaway/pie-css)
+
+Style native HTML `<input type="radio">` elements with PIE design system styling.
+
+## Table of Contents
+
+- [Why?](#why)
+- [Installation](#installation)
+- [Importing](#importing)
+- [Basic Usage](#basic-usage)
+- [Available Classes](#available-classes)
+- [Visual States](#visual-states)
+- [Accessibility](#accessibility)
+
+## Why?
+
+The PIE CSS Radio Component Styles are designed to provide the PIE visual styling to native HTML radio inputs. This is needed when
+your designs use radio buttons in more complex ways than simple lists of options. For example complex radio button-based card components.
+
+## Installation
+
+The radio component styles are included as part of the `@justeattakeaway/pie-css` package:
+
+```bash
+# Using Yarn
+yarn add @justeattakeaway/pie-css
+
+# Using NPM
+npm install @justeattakeaway/pie-css
+```
+
+## Importing
+
+### CSS Import (JavaScript/Framework)
+
+Import the pre-compiled CSS file in your JavaScript/TypeScript application:
+
+```javascript
+import '@justeattakeaway/pie-css/dist/components/radio.css';
+```
+
+**React Example:**
+
+```jsx
+import '@justeattakeaway/pie-css/dist/components/radio.css';
+
+function MyForm() {
+  return (
+    <label>
+      <input type="radio" className="c-radio" name="option" value="1" />
+      Option 1
+    </label>
+  );
+}
+```
+
+**Vue Example:**
+
+```html
+<script setup>
+import '@justeattakeaway/pie-css/dist/components/radio.css';
+</script>
+
+<template>
+  <label>
+    <input type="radio" class="c-radio" name="option" value="1" />
+    Option 1
+  </label>
+</template>
+```
+
+## Basic Usage
+
+Apply the `c-radio` class to a native radio input:
+
+```html
+<!-- Basic radio -->
+<input type="radio" class="c-radio" name="option" value="1">
+
+<!-- With label -->
+<label>
+  <input type="radio" class="c-radio" name="option" value="2" checked>
+  Option 2
+</label>
+
+<!-- Error state -->
+<input type="radio" class="c-radio c-radio--error" name="option" value="3">
+```
+
+## Available Classes
+
+| Class | Description |
+|-------|-------------|
+| `.c-radio` | Base radio input styling with all default states |
+| `.c-radio--error` | Error state styling |
+
+**Note:** All other visual states (`:checked`, `:disabled`, `:hover`, `:active`, `:focus-visible`) are handled automatically by CSS pseudo-classes.
+
+## Visual States
+
+All states are applied automatically via CSS pseudo-classes, except for error which is applied with a class.
+
+| State | CSS Selector | Appearance | When Applied |
+|-------|--------------|------------|--------------|
+| **Error** | `.c-radio--error` | Error border color | Add `c-radio--error` class |
+| **Unchecked** | `.c-radio` | Empty circle with border | Default state |
+| **Checked** | `.c-radio:checked` | Filled circle with center dot | When selected |
+| **Disabled** | `.c-radio:disabled` | Faded, not-allowed cursor | When `disabled` attribute is present |
+| **Hover** | `.c-radio:hover` | Darkened background overlay | Mouse hover (not disabled) |
+| **Active** | `.c-radio:active` | Further darkened overlay | Mouse press (not disabled) |
+| **Focus** | `.c-radio:focus-visible` | Focus ring | Keyboard navigation only |
+
+The focus ring is applied automatically on `:focus-visible` (keyboard navigation only) and will not show on mouse clicks.
+
+### State Combinations
+
+The radio input supports multiple state combinations:
+
+- **Checked + Disabled**: Faded with dot visible
+- **Error + Checked**: Error color with dot visible
+- **Error + Disabled**: Faded (disabled takes precedence)
+
+
+## Accessibility
+
+When using native HTML radio inputs with the `c-radio` class, please follow the best practices found in the [MDN Web Docs on Radio Buttons](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/radio).
+
+

package/docs/design-tokens-cookbook.md

@@ -0,0 +1,187 @@
+# Design Tokens Cookbook
+
+Below are common recipes for using our design tokens. For web engineers, design tokens are simply **CSS variables** that expose raw values - such as **colours, spacing, and motion**. These form the foundation of the PIE visual language.
+
+For a more in-depth introduction to design tokens, please visit our [design documentation website](https://pie.design/foundations/design-tokens/).
+
+All of our design tokens can be added to your project by following our [CSS setup guide](https://github.com/justeattakeaway/pie/blob/main/packages/tools/pie-css/README.md#using-the-pie-css-css-stylesheet-in-your-web-application).
+
+> ⚠️ Token names may evolve as the design system is updated. While we strive to keep this guide up-to-date, some variable names may differ in future versions.
+>
+> These examples are purely for illustrating how to use our design token variables. They are not intended as recommendations for how to structure your CSS or name your classes.
+
+## Table of Contents
+
+- [Codepen](#codepen)
+- [Colour](#colour)
+    - [Use brand colour as button background](#use-brand-colour-as-button-background)
+    - [Using HSL](#using-hsl)
+- [Spacing](#spacing)
+    - [Stack items with spacing token](#stack-items-with-spacing-token)
+    - [Add padding using spacing alias](#add-padding-using-spacing-alias)
+- [Typography](#typography)
+    - [Font size](#font-size)
+    - [Body text](#body-text)
+    - [Heading example](#heading-example)
+    - [Line height](#line-height)
+- [Radius](#radius)
+    - [Rounded card](#rounded-card)
+- [Motion](#motion)
+    - [Animate-in transition](#animate-in-transition)
+- [Elevation](#elevation)
+    - [Card with elevation](#card-with-elevation)
+
+## Codepen
+All of these examples can be seen and edited on [Codepen](https://codepen.io/JamieMaguire/pen/azOKVxo)!
+
+## Colour
+This example uses a semantic colour token (`--dt-color-interactive-brand`) to define the background, and a complementary content token (`--dt-color-content-interactive-primary`) for the text. These tokens abstract away raw hex or HSL values in favour of role-based names, which makes them more adaptable to different themes (like dark mode) and helps maintain accessibility and brand consistency.
+
+### Use brand colour as button background
+```css
+.box-brand {
+    background-color: var(--dt-color-interactive-brand);
+    color: var(--dt-color-content-interactive-primary);
+}
+```
+
+### Using HSL
+
+For greater flexibility, we provide `-h`, `-s`, and `-l` variants of all our colour tokens. These expose the hue, saturation, and lightness components separately, allowing you to compose colours using the native CSS `hsl()` function.
+
+You can combine these with our [state tokens](https://pie.design/foundations/colour/tokens/alias/light/#States), such as `--dt-color-hover-01`, which typically represents a percentage to dynamically adjust things like lightness for hover or focus states.
+
+> You will need to apply the state token to a `calc()` css function with `-1` to darken the colour.
+
+```css
+.hsl-example-darken {
+  background-color: hsl(var(--dt-color-container-default-h), var(--dt-color-container-default-s), calc(var(--dt-color-container-default-l) + calc(-1 * var(--dt-color-hover-01))));
+}
+```
+
+```css
+.hsl-example-lighten {
+    background-color: hsl(var(--dt-color-container-default-h), var(--dt-color-container-default-s), calc(var(--dt-color-container-default-l) + var(--dt-color-hover-01)));
+}
+```
+
+## Spacing
+
+### Stack items with spacing token
+This example uses a spacing token (`--dt-spacing-d`) with the CSS gap property to control vertical rhythm between stacked elements. By using tokens for spacing rather than hardcoded values, we ensure consistent layout behaviour across all components and make global spacing updates easier to apply.
+
+```css
+.stack-vertical {
+    display: flex;
+    flex-direction: column;
+    gap: var(--dt-spacing-d);
+}
+```
+
+### Add padding using spacing alias
+A spacing token (`--dt-spacing-e`) is applied to padding, providing internal space around content. These tokens act as aliases for specific steps in our spacing scale, allowing for a semantically meaningful way to apply spacing while keeping layout consistent with the design system.
+
+```css
+.padded-box {
+    padding: var(--dt-spacing-e);
+}
+```
+
+## Typography
+
+**Note:** Whenever you set a `font-size`, you must also set a compatible `line-height` rule to ensure the font looks correct.
+
+### Font size
+Our font-size tokens only store the raw number, not a `px` unit. Therefore, you must multiply the token by `1px` to create a `px` value that CSS will understand.
+
+```css
+.font-size-example {
+    font-size: calc(var(--dt-font-body-l-size) * 1px);
+}
+```
+
+### Body text
+Font tokens define the typography for body content, including font family, size, weight, and line height. Each token maps to a specific design choice in the type scale, and using them ensures that text remains visually consistent and readable, even as underlying type styles evolve in the system.
+
+```css
+.body-text {
+    font-family: var(--dt-font-body-l-family);
+    font-size: calc(var(--dt-font-body-l-size) * 1px);
+    font-weight: var(--dt-font-body-l-weight);
+    line-height: calc(var(--dt-font-body-l-line-height) * 1px);
+}
+```
+
+### Heading example
+Typography tokens are again used here, but with heading-specific values - including a `--wide` variant for font size and line height. This demonstrates how token modifiers allow flexibility (e.g. tighter vs wider spacing) without diverging from the core type system.
+
+```css
+.heading-m {
+    font-family: var(--dt-font-heading-m-family);
+    font-size: calc(var(--dt-font-heading-m-size--wide) * 1px);
+    font-weight: var(--dt-font-heading-m-weight);
+    line-height: calc(var(--dt-font-heading-m-line-height--wide) * 1px);
+}
+```
+
+### Line height
+
+Line height tokens only contain the raw number, not a `px` unit. Therefore they must be multipled by `1px` to create a `px` value CSS will understand.
+
+```css
+.applied-lineheight {
+    line-height: calc(var(--dt-font-heading-m-line-height--wide) * 1px);
+}
+```
+
+## Radius
+
+### Rounded card
+A radius token (`--dt-radius-rounded-c`) controls the roundness of corners, making the visual shape consistent with other rounded elements in the system. The token abstracts the exact pixel value, allowing us to tweak the roundness globally if the design direction changes.
+
+```css
+.card-rounded {
+    border-radius: var(--dt-radius-rounded-c);
+    border: 1px solid var(--dt-color-border-default);
+    padding: var(--dt-spacing-e);
+}
+```
+
+## Motion
+
+### Animate-in transition
+This example uses motion tokens to control the timing and easing of a keyframe animation. The `--dt-motion-timing-200` token defines the duration of the animation, while `--dt-motion-easing-out` provides a standard easing curve.
+
+By using tokens instead of hardcoded values, we ensure that all animations across the product feel consistent and aligned with the system's motion principles. These tokens abstract away raw timing values, allowing the design team to update motion characteristics centrally - improving coherence.
+
+```css
+@keyframes animate-in {
+    from {
+        transform: translateX(-100%);
+    }
+
+    to {
+        transform: translateX(0);
+    }
+}
+
+.animated {
+    animation-duration: var(--dt-motion-timing-200);
+    animation-name: animate-in;
+    animation-timing-function: var(--dt-motion-easing-out);
+    transform: translateX(0);
+}
+```
+
+## Elevation
+
+### Card with elevation
+This uses an elevation token (`--dt-elevation-below-10`) to apply a standardized shadow. Elevation tokens encapsulate not just a single box-shadow, but a visual effect aligned with the design system's depth model, helping create consistent layering and hierarchy throughout the UI.
+
+```css
+.card-elevated {
+    box-shadow: var(--dt-elevation-below-10);
+    padding: var(--dt-spacing-e);
+    border-radius: var(--dt-radius-rounded-b);
+}
+```

package/docs/typography-utility-classes.md

@@ -0,0 +1,327 @@
+# PIE CSS Typography Utility Classes
+
+[Source Code](https://github.com/justeattakeaway/pie/tree/main/packages/tools/pie-css) | [NPM Package](https://www.npmjs.com/package/@justeattakeaway/pie-css)
+
+The PIE CSS Typography Utilities provide a comprehensive set of utility classes for applying consistent typography styles across your application. These classes are built on top of PIE design tokens and ensure your typography follows the design system's guidelines automatically.
+
+## Table of Contents
+
+- [Why?](#why)
+- [Installation](#installation)
+- [Importing](#importing)
+    - [JavaScript/Framework Import (via bundler)](#javascriptframework-import-via-bundler)
+    - [SCSS/Sass Import](#scsssass-import)
+- [Which Class Should I Use?](#which-class-should-i-use)
+    - [If You Have Designs](#if-you-have-designs)
+    - [If You Don't Have Designs](#if-you-dont-have-designs)
+- [Available Classes](#available-classes)
+- [the `font-theme` mixin](#the-font-theme-mixin)
+- [Usage Examples](#usage-examples)
+- [What Each Utility Class Applies](#what-each-utility-class-applies)
+- [Troubleshooting](#troubleshooting)
+    - [Utilities Not Working](#utilities-not-working)
+    - [Font Not Displaying](#font-not-displaying)
+
+## Why?
+
+Our typography utility classes offer several key benefits:
+
+- **Consistency**: Ensures all typography across your application follows the PIE design system standards
+- **Responsive by Default**: Many utilities automatically adjust for narrow and wide viewports (breakpoint at 768px)
+- **Design Token Integration**: Built directly on PIE design tokens, so updates to tokens automatically propagate
+- **Maintainability**: Single source of truth for typography styles reduces duplication and makes updates easier. You don't need to manually apply individual token combinations, it's done for you
+
+## Installation
+
+The typography utilities are included as part of the `@justeattakeaway/pie-css` package. If you haven't already installed it:
+
+```bash
+# Using Yarn
+yarn add @justeattakeaway/pie-css
+
+# Using NPM
+npm install @justeattakeaway/pie-css
+```
+
+## Importing
+
+To use the typography utility classes, you need to import the typography CSS file. The import method depends on your project setup:
+
+### JavaScript/Framework Import (via bundler)
+
+```javascript
+// Import the typography utilities
+import '@justeattakeaway/pie-css/dist/helpers/typography.css';
+```
+
+### SCSS/Sass Import
+
+```scss
+@use '@justeattakeaway/pie-css/dist/helpers/typography.css';
+```
+
+> **Note**: Make sure you've also imported the base `@justeattakeaway/pie-css` package, as the typography utilities depend on the design token CSS variables defined there.
+
+## Which Class Should I Use?
+
+### If You Have Designs
+
+If you have access to Figma designs, the font token used in the design should be available in Figma. The CSS utility class name directly matches the token name by prefixing it with `u-font-`.
+
+**Note**: In Figma, token names may appear differently in the Typography section. For example, the `body-l` token might be displayed as "Body Large", "Large", or "Body Large/Large". The underlying token name will match the CSS class name format.
+
+For example:
+- If the design uses the `body-l-link` token (may appear as "Body Large Link" in Figma) → use the `.u-font-body-l-link` class
+- If the design uses the `heading-m` token (may appear as "Heading Medium" in Figma) → use the `.u-font-heading-m` class
+- If the design uses the `caption-strong` token (may appear as "Caption Strong" in Figma) → use the `.u-font-caption-strong` class
+
+Simply take the token name from Figma and add the `u-font-` prefix to get the corresponding CSS class.
+
+### If You Don't Have Designs
+
+If you don't have access to designs, you have two options:
+
+1. **Use the most appropriate class** by reading the use cases for each utility class in the tables below. Each class is documented with its intended use case to help you make the right choice.
+
+2. **Reach out to the design system team** for guidance on which typography utility class to use for your specific use case.
+
+## Available Classes
+
+The typography utilities are organized into several categories. This documentation is automatically generated from the CSS source file.
+
+### the `font-theme` mixin
+
+In addition to the typography utility classes, the `font-theme` mixin can also be used directly to apply the styles to your SCSS.
+
+**N.b. We recommend only using this when using the classes isn't possible – and only if you are serving your CSS gzipped, to ensure that this code is properly optimised when served to your users.**
+
+Using the `font-theme` mixin will apply the corresponding typography styles to the element selected. It takes a typography token name as an argument.
+
+To use the mixin as part of the full set of PIE SCSS Utilities, you can import the mixin as follows:
+
+```scss
+@use '@justeattakeaway/pie-css/scss' as p;
+
+.my-element {
+    @include p.font-theme('heading-l');
+}
+```
+
+Alternatively, you can import the mixin directly, without importing the other SCSS utilities:
+
+```scss
+@use '@justeattakeaway/pie-css/scss/mixins/font-theme' as *;
+
+.my-element {
+    @include font-theme('heading-l');
+}
+```
+
+### Headings
+
+Heading utilities are designed for page titles, section headers, and other prominent text. All heading utilities are responsive and adjust font size and line height at the 768px breakpoint.
+
+#### Standard Headings
+
+| Class | Use Case |
+| --- | --- |
+| `.u-font-heading-xxl` | Extra extra large heading |
+| `.u-font-heading-xl` | Extra large heading |
+| `.u-font-heading-l` | Large heading |
+| `.u-font-heading-m` | Medium heading |
+| `.u-font-heading-s` | Small heading |
+| `.u-font-heading-xs` | Extra small heading |
+
+#### Italic Headings
+
+| Class | Use Case |
+| --- | --- |
+| `.u-font-heading-xxl-italic` | Extra extra large heading italic |
+| `.u-font-heading-xl-italic` | Extra large heading italic |
+| `.u-font-heading-l-italic` | Large heading italic |
+| `.u-font-heading-m-italic` | Medium heading italic |
+| `.u-font-heading-s-italic` | Small heading italic |
+| `.u-font-heading-xs-italic` | Extra small heading italic |
+
+### Subheadings
+
+Subheadings are used for secondary headings and section titles.
+
+| Class | Use Case |
+| --- | --- |
+| `.u-font-subheading-l` | Large subheading |
+| `.u-font-subheading-s` | Small subheading |
+
+### Interactive Text
+
+Interactive text utilities are optimized for buttons, links, and other interactive elements.
+
+| Class | Use Case |
+| --- | --- |
+| `.u-font-interactive-l` | Large interactive text |
+| `.u-font-interactive-s` | Small interactive text |
+| `.u-font-interactive-xs` | Extra small interactive text |
+
+### Body Text
+
+Body text utilities are for paragraphs and general content. These utilities include automatic paragraph spacing via `margin-block-end`.
+
+| Class | Use Case |
+| --- | --- |
+| `.u-font-body-l` | Large body text |
+| `.u-font-body-s` | Small body text |
+
+### Body Link
+
+Body link utilities combine body text styling with link-specific properties like text decoration.
+
+| Class | Use Case |
+| --- | --- |
+| `.u-font-body-s-link` | Small body text link |
+| `.u-font-body-l-link` | Large body text link |
+
+### Body Strong
+
+Body strong utilities are for bold/emphasized body text.
+
+| Class | Use Case |
+| --- | --- |
+| `.u-font-body-strong-l` | Large body text bold/strong |
+| `.u-font-body-strong-s` | Small body text bold/strong |
+
+### Body Strong Link
+
+Body strong link utilities combine bold body text styling with link properties.
+
+| Class | Use Case |
+| --- | --- |
+| `.u-font-body-strong-s-link` | Small body text bold/strong link |
+| `.u-font-body-strong-l-link` | Large body text bold/strong link |
+
+### Captions
+
+Caption utilities are for small supporting text, labels, and metadata.
+
+| Class | Use Case |
+| --- | --- |
+| `.u-font-caption` | caption |
+
+### Caption Link
+
+Caption link utilities combine caption styling with link properties.
+
+| Class | Use Case |
+| --- | --- |
+| `.u-font-caption-link` | caption link |
+
+### Caption Strong
+
+Caption strong utilities are for bold captions.
+
+| Class | Use Case |
+| --- | --- |
+| `.u-font-caption-strong` | caption bold/strong |
+
+### Caption Strong Link
+
+Caption strong link utilities combine bold caption styling with link properties.
+
+| Class | Use Case |
+| --- | --- |
+| `.u-font-caption-strong-link` | caption bold/strong link |
+
+## Usage Examples
+
+### Basic Usage
+
+Simply add the utility class to your HTML element:
+
+```html
+<h1 class="u-font-heading-xl">Page Title</h1>
+<p class="u-font-body-l">This is a paragraph of body text.</p>
+```
+
+### React Example
+
+```jsx
+function MyComponent() {
+  return (
+    <div>
+      <h1 className="u-font-heading-xl">Welcome</h1>
+      <h2 className="u-font-heading-m">Section Title</h2>
+      <p className="u-font-body-l">
+        This is a paragraph using the body large utility class.
+      </p>
+      <a href="#" className="u-font-body-l-link">Learn more</a>
+    </div>
+  );
+}
+```
+
+### Vue Example
+
+```html
+<template>
+  <div>
+    <h1 class="u-font-heading-xl">Welcome</h1>
+    <h2 class="u-font-heading-m">Section Title</h2>
+    <p class="u-font-body-l">
+      This is a paragraph using the body large utility class.
+    </p>
+    <a href="#" class="u-font-body-l-link">Learn more</a>
+  </div>
+</template>
+```
+
+### Combining with Other Classes
+
+You can combine typography utilities with other CSS classes:
+
+```html
+<div class="card">
+  <h2 class="u-font-heading-m card-title">Card Title</h2>
+  <p class="u-font-body-s card-description">Card description text.</p>
+</div>
+```
+
+### Responsive Behavior
+
+Heading and subheading utilities automatically adjust at the 768px breakpoint:
+
+```html
+<!-- This heading will be smaller on mobile and larger on desktop -->
+<h1 class="u-font-heading-xl">Responsive Heading</h1>
+```
+
+The utility classes handle the responsive behavior automatically, so you don't need to write additional media queries.
+
+## What Each Utility Class Applies
+
+Each typography utility class applies a complete set of typography properties:
+
+- **`font-family`**: Uses the appropriate design token font family ([MDN reference](https://developer.mozilla.org/en-US/docs/Web/CSS/font-family))
+- **`font-weight`**: Applies the correct font weight from design tokens ([MDN reference](https://developer.mozilla.org/en-US/docs/Web/CSS/font-weight))
+- **`font-size`**: Sets the font size (responsive for headings/subheadings) ([MDN reference](https://developer.mozilla.org/en-US/docs/Web/CSS/font-size))
+- **`line-height`**: Applies the appropriate line height for readability ([MDN reference](https://developer.mozilla.org/en-US/docs/Web/CSS/line-height))
+- **`font-style`**: Applied for italic variants ([MDN reference](https://developer.mozilla.org/en-US/docs/Web/CSS/font-style))
+- **`text-decoration`**: Applied for link variants ([MDN reference](https://developer.mozilla.org/en-US/docs/Web/CSS/text-decoration))
+- **`margin-block-end`**: Applied for body and caption variants to provide paragraph spacing ([MDN reference](https://developer.mozilla.org/en-US/docs/Web/CSS/margin-block-end))
+
+## Troubleshooting
+
+### Utilities Not Working
+
+If the typography utilities aren't applying:
+
+1. Ensure you've imported the typography CSS file: `@justeattakeaway/pie-css/dist/helpers/typography.css`
+2. Verify the base `@justeattakeaway/pie-css` package is imported (required for design tokens)
+3. Check that your build process is including the CSS file
+4. Inspect the element in browser dev tools to see if classes are being applied
+
+### Font Not Displaying
+
+If fonts aren't displaying correctly:
+
+1. Ensure you've set up the JETSansDigital font as described in the Typography setup guide
+2. Check that font files are loading correctly
+3. Verify font-face declarations are correct

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@justeattakeaway/pie-css",
-  "version": "0.28.0",
+  "version": "0.28.1",
   "description": "A styling library that provides both a shared collection of ready to use CSS styles to be used across JET web front-ends, and SCSS-based style helpers for our PIE Web Component library.",
   "repository": {
     "type": "git",
@@ -11,7 +11,8 @@
   "author": "Just Eat Takeaway.com - Design System Team",
   "files": [
     "scss",
-    "dist"
+    "dist",
+    "docs"
   ],
   "main": "dist/index.css",
   "pieMetadata": {