@daffodil/design 0.93.0 → 0.94.0

package/README.md

@@ -37,7 +37,6 @@ Refer to the [Upgrade Guide](/libs/design/guides/upgrading.md).
   * [Native Select](/libs/design/src/atoms/form/native-select/README.md)
   * [Quantity Field](/libs/design/src/atoms/form/quantity-field/README.md)
 * [Image](/libs/design/image/README.md)
-* [Loading Icon](/libs/design/loading-icon/README.md)
 * [Tag](/libs/design/tag/README.md)
 
 ### Molecules

package/accordion/src/accordion-theme.scss

@@ -7,7 +7,7 @@
 	$mode: daff-get-theme-mode($theme);
 
 	.daff-accordion-item {
-		@include light($mode) {
+		@include daff-light-mode($mode) {
 			border-top: 1px solid daff-color($neutral, 20);
 
 			&:last-child {
@@ -23,7 +23,7 @@
 			}
 		}
 
-		@include dark($mode) {
+		@include daff-dark-mode($mode) {
 			border-top: 1px solid daff-color($neutral, 80);
 
 			&:last-child {

package/article/src/article/_stops-article-cascade.scss

@@ -1,6 +1,10 @@
 @mixin stopsArticleCascade($selector...) {
 	#{$selector} {
-		&:not(.daff-ae *, .daff-ae) {
+		// `.daff-ae` only stops the cascade when it sits between the element and
+		// the article. Anchoring it to `.daff-article` keeps article styles
+		// working when an article is nested inside an encapsulated component.
+		// `:where` keeps the anchored selector from raising specificity.
+		&:not(.daff-ae, :where(.daff-article .daff-ae *)) {
 			@content;
 		}
 	}

package/article/src/article-theme.scss

@@ -14,7 +14,7 @@
 	$table-border-dark: daff-color($neutral, 80);
 
 	.daff-article {
-		@include light($mode) {
+		@include daff-light-mode($mode) {
 			color: $text-color-light;
 
 			@include stopsArticleCascade(a) {
@@ -98,7 +98,7 @@
 			}
 		}
 
-		@include dark($mode) {
+		@include daff-dark-mode($mode) {
 			color: $text-color-dark;
 
 			@include stopsArticleCascade(a) {

package/badge/README.md

@@ -0,0 +1,85 @@
+# Badge
+A badge is a compact visual label or indicator used to convey status or display short pieces of information.
+
+## Overview
+Badges are small visual indicators that highlight quick, essential information. Use a badge to draw attention to a piece of content, such as a count, a status, or a short label.
+
+Because badges are not interactive, they aren't meant to group, sort, or filter information. When you need those interactions, use [tags](/libs/design/tag/README.md) instead.
+
+<daff-docs-example-viewer example="basic-badge"></daff-docs-example-viewer>
+
+## Best practices
+
+**When to use**
+- Show a status, such as success, error, or new
+- Display a small piece of metadata
+- Provide quick, scannable context inside a UI
+
+**When not to use**
+- To group, sort, or filter information (use [tags](/libs/design/tag/README.md) instead)
+- For interactive elements, such as buttons or links
+
+## Usage
+
+Import `DAFF_BADGE_COMPONENTS` into your component:
+
+```ts
+import { DAFF_BADGE_COMPONENTS } from '@daffodil/design/badge';
+
+@Component({
+  selector: 'custom-component',
+  templateUrl: './custom-component.component.html',
+  imports: [
+    DAFF_BADGE_COMPONENTS,
+  ],
+})
+export class CustomComponent {}
+```
+
+## Anatomy
+A badge is composed of a wrapper, an optional prefix, and a label:
+
+```html
+<daff-badge>
+  <fa-icon [icon]="faCircleCheck" daffPrefix></fa-icon>
+  Badge label
+</daff-badge>
+```
+
+- **`<daff-badge>`**: The wrapper component that holds the badge content.
+- **`[daffPrefix]`**: A leading visual, typically an icon, displayed before the label.
+- **Label**: The content of the badge, projected as a child element.
+
+## Features
+
+### Icon support
+Use the `[daffPrefix]` element to display a leading visual icon before the badge label.
+
+<daff-docs-example-viewer example="badge-prefix"></daff-docs-example-viewer>
+
+### Appearances
+Use the `appearance` property to change the visual style of a badge.
+
+<daff-docs-example-viewer example="badge-appearances"></daff-docs-example-viewer>
+
+### Colors
+Use the `color` property to change the color of a badge. The default color is `light`.
+
+<daff-docs-example-viewer example="badge-colors"></daff-docs-example-viewer>
+
+### Sizes
+Use the `size` property to change the size of a badge. The default size is `md`.
+
+<daff-docs-example-viewer example="badge-sizes"></daff-docs-example-viewer>
+
+### Statuses
+Use the `status` property to convey semantic meaning. A `status` takes precedence over `color`.
+
+<daff-docs-example-viewer example="badge-statuses"></daff-docs-example-viewer>
+
+## Accessibility
+Badges are not interactive and do not receive focus.
+
+### Developer responsibilities
+- Always provide a text label unless the icon is universally understood and accessible
+- Use the `status` property to communicate semantic meaning

package/badge/src/badge-theme.scss

@@ -0,0 +1,197 @@
+// stylelint-disable selector-class-pattern
+@use '../../scss/theming' as *;
+
+@mixin daff-badge-color-light-variants(
+	$variants,
+	$background,
+	$foreground,
+	$outline-shade
+) {
+	@each $name, $palette in $variants {
+		&.daff-#{$name} {
+			background: daff-color($palette, $background);
+			color: daff-color($palette, $foreground);
+
+			&.outlined {
+				border-color: daff-color($palette, $outline-shade);
+			}
+		}
+	}
+}
+
+@mixin daff-badge-color-dark-variants(
+	$variants,
+	$shade,
+	$foreground,
+	$outline-shade
+) {
+	@each $name, $palette in $variants {
+		&.daff-#{$name} {
+			background: daff-color($palette, $shade);
+			color: daff-color($palette, $foreground);
+
+			&.outlined {
+				border-color: daff-color($palette, $outline-shade);
+			}
+		}
+	}
+}
+
+@mixin daff-badge-theme($theme) {
+	$primary: daff-get-palette($theme, primary);
+	$secondary: daff-get-palette($theme, secondary);
+	$tertiary: daff-get-palette($theme, tertiary);
+	$info: daff-get-palette($theme, informational);
+	$warn: daff-get-palette($theme, warn);
+	$critical: daff-get-palette($theme, critical);
+	$success: daff-get-palette($theme, success);
+	$neutral: daff-get-palette($theme, neutral);
+	$black: daff-get-base-color($theme, 'black');
+	$white: daff-get-base-color($theme, 'white');
+	$mode: daff-get-theme-mode($theme);
+
+	.daff-badge {
+		@include daff-light-mode($mode) {
+			@include daff-badge-color-light-variants(
+				(
+					'primary': $primary,
+					'secondary': $secondary,
+					'tertiary': $tertiary,
+				),
+				10,
+				90,
+				20
+			);
+
+			&.daff-dark {
+				background: daff-color($neutral, 80);
+				color: daff-color($neutral, 10);
+			}
+
+			&.daff-light {
+				background: daff-color($neutral, 10);
+				color: daff-color($neutral, 100);
+			}
+
+			&.daff-theme {
+				background: $white;
+				color: $black;
+			}
+
+			&.daff-theme-contrast {
+				background: daff-color($neutral, 90);
+				color: daff-color($neutral, 10);
+			}
+
+			&.outlined {
+				&.daff-dark {
+					border-color: daff-color($neutral, 90);
+				}
+
+				&.daff-light {
+					border-color: daff-color($neutral, 20);
+				}
+
+				&.daff-theme {
+					border-color: daff-color($neutral, 30);
+				}
+
+				&.daff-theme-contrast {
+					border-color: daff-color($neutral, 100);
+				}
+
+				&.daff-info {
+					border-color: daff-color($neutral, 30);
+				}
+			}
+
+			// `status` is a state modifier that must override `color`. Both apply
+			// equal-specificity `.daff-*` classes to the same element, so these
+			// rules are authored after every color variant above to win the cascade.
+			@include daff-badge-color-light-variants(
+				(
+					'warn': $warn,
+					'critical': $critical,
+					'success': $success,
+				),
+				10,
+				90,
+				20
+			);
+
+			&.daff-info {
+				background: daff-color($neutral, 20);
+				color: daff-color($neutral, 90);
+			}
+		}
+
+		@include daff-dark-mode($mode) {
+			background: daff-color($neutral, 80);
+			color: daff-color($neutral, 20);
+
+			@include daff-badge-color-dark-variants(
+				(
+					'primary': $primary,
+					'secondary': $secondary,
+					'tertiary': $tertiary,
+					'dark': $neutral,
+				),
+				100,
+				20,
+				90
+			);
+
+			&.daff-light {
+				background: daff-color($neutral, 10);
+				color: daff-color($neutral, 100);
+			}
+
+			&.daff-theme {
+				background: $black;
+				color: $white;
+			}
+
+			&.daff-theme-contrast {
+				background: $white;
+				color: $black;
+			}
+
+			&.outlined {
+				&.daff-light {
+					border-color: daff-color($neutral, 30);
+				}
+
+				&.daff-theme {
+					border-color: daff-color($neutral, 90);
+				}
+
+				&.daff-theme-contrast {
+					border-color: daff-color($neutral, 30);
+				}
+
+				&.daff-info {
+					border-color: daff-color($neutral, 80);
+				}
+			}
+
+			// `status` is a state modifier that must override `color`. Both apply
+			// equal-specificity `.daff-*` classes to the same element, so these
+			// rules are authored after every color variant above to win the cascade.
+			@include daff-badge-color-dark-variants(
+				(
+					'warn': $warn,
+					'critical': $critical,
+					'success': $success,
+				),
+				100,
+				20,
+				90
+			);
+
+			&.daff-info {
+				background: daff-color($neutral, 90);
+				color: daff-color($neutral, 20);
+			}
+		}
+	}
+}

package/beacon/README.md

@@ -0,0 +1,61 @@
+# Beacon
+A beacon is a small indicator that draws visual attention to a specific location or element.
+
+## Overview
+Use a beacon to signal a "live" status or highlight a point of interest, such as a new feature or an active notification. It renders as a pulsing dot that draws the eye without interrupting the surrounding content.
+
+<daff-docs-example-viewer example="basic-beacon"></daff-docs-example-viewer>
+
+## Usage
+
+Import `DaffBeaconComponent` into your component:
+
+```ts
+import { DaffBeaconComponent } from '@daffodil/design/beacon';
+
+@Component({
+  selector: 'custom-component',
+  templateUrl: './custom-component.component.html',
+  imports: [
+    DaffBeaconComponent,
+  ],
+})
+export class CustomComponent {}
+```
+
+## Anatomy
+A beacon is a single dot with a ring that pulses outward from it. With no properties set, it renders at the default size and inherits the ambient text color:
+
+```html
+<daff-beacon></daff-beacon>
+```
+
+## Features
+
+### Colors
+Use the `color` property to change the color of a beacon. Left unset, the beacon matches the surrounding text color, so setting `color` on a parent element carries down to the beacon.
+
+> Note: `dark`, `light`, and `theme` should be used on appropriate backgrounds for sufficient contrast.
+
+<daff-docs-example-viewer example="beacon-colors"></daff-docs-example-viewer>
+
+### Status
+Use the `status` property to color the beacon by meaning: `info`, `warn`, `critical`, or `success`. Use `status` instead of `color` when the dot represents a state.
+
+<daff-docs-example-viewer example="beacon-statuses"></daff-docs-example-viewer>
+
+### Sizes
+Use the `size` property to change the diameter of the dot. The default size is `sm`.
+
+<daff-docs-example-viewer example="beacon-sizes"></daff-docs-example-viewer>
+
+### Speed
+Use the `speed` property to set how fast the ring pulses. `slow` is a relaxed 3.6s cycle, `normal` (the default) a 2.4s cycle, and `fast` an urgent 1.2s cycle.
+
+<daff-docs-example-viewer example="beacon-speeds"></daff-docs-example-viewer>
+
+## Accessibility
+
+For users who have reduced motion enabled, the beacon shows as a still dot instead of pulsing.
+
+Beacon is purely decorative and should never be the only thing that conveys status. Always pair it with visible text or another cue that communicates the same meaning.

package/beacon/src/beacon-theme.scss

@@ -0,0 +1,61 @@
+@use '../../scss/theming' as *;
+
+@mixin daff-beacon-theme($theme) {
+	$primary: daff-get-palette($theme, primary);
+	$secondary: daff-get-palette($theme, secondary);
+	$tertiary: daff-get-palette($theme, tertiary);
+	$info: daff-get-palette($theme, informational);
+	$warn: daff-get-palette($theme, warn);
+	$critical: daff-get-palette($theme, critical);
+	$success: daff-get-palette($theme, success);
+	$base: daff-get-base-color($theme, base);
+	$base-contrast: daff-get-base-color($theme, base-contrast);
+	$white: daff-get-base-color($theme, 'white');
+	$black: daff-get-base-color($theme, 'black');
+
+	.daff-beacon {
+		&.daff-primary {
+			color: daff-color($primary);
+		}
+
+		&.daff-secondary {
+			color: daff-color($secondary);
+		}
+
+		&.daff-tertiary {
+			color: daff-color($tertiary);
+		}
+
+		&.daff-theme {
+			color: $base;
+		}
+
+		&.daff-theme-contrast {
+			color: $base-contrast;
+		}
+
+		&.daff-dark {
+			color: $black;
+		}
+
+		&.daff-light {
+			color: $white;
+		}
+
+		&.daff-info {
+			color: daff-color($info);
+		}
+
+		&.daff-warn {
+			color: daff-color($warn);
+		}
+
+		&.daff-critical {
+			color: daff-color($critical);
+		}
+
+		&.daff-success {
+			color: daff-color($success);
+		}
+	}
+}

package/breadcrumb/src/breadcrumb-theme.scss

@@ -6,12 +6,12 @@
 
 	.daff-breadcrumb__item {
 		a, .daff-breadcrumb__menu-activator {
-			@include light($mode) {
+			@include daff-light-mode($mode) {
 				color: daff-color($neutral, 80);
 				text-decoration-color: daff-color($neutral, 80);
 			}
 
-			@include dark($mode) {
+			@include daff-dark-mode($mode) {
 				color: daff-color($neutral, 30);
 				text-decoration-color: daff-color($neutral, 30);
 			}

package/button/src/button/basic/button-theme.scss

@@ -43,7 +43,7 @@
 	$mode: daff-get-theme-mode($theme);
 
 	.daff-button {
-		@include light($mode) {
+		@include daff-light-mode($mode) {
 			@include daff-button-theme-variant(
 				daff-color($neutral, 10),
 				daff-color($neutral, 20),
@@ -131,7 +131,7 @@
 			}
 		}
 
-		@include dark($mode) {
+		@include daff-dark-mode($mode) {
 			@include daff-button-theme-variant(
 				daff-color($neutral, 90),
 				daff-color($neutral, 80),

package/button/src/button/flat/flat-theme.scss

@@ -30,7 +30,7 @@
 	$mode: daff-get-theme-mode($theme);
 
 	.daff-flat-button {
-		@include light($mode) {
+		@include daff-light-mode($mode) {
 			@include daff-flat-button-theme-variant(
 				$base-contrast,
 			);
@@ -96,7 +96,7 @@
 			}
 		}
 
-		@include dark($mode) {
+		@include daff-dark-mode($mode) {
 			@include daff-flat-button-theme-variant(
 				$base-contrast,
 			);

package/button/src/button/icon/icon-theme.scss

@@ -41,7 +41,7 @@
 	$mode: daff-get-theme-mode($theme);
 
 	.daff-icon-button {
-		@include light($mode) {
+		@include daff-light-mode($mode) {
 			@include daff-icon-button-theme-variant(
 				daff-color($neutral, 50),
 				daff-color($neutral, 60),
@@ -129,7 +129,7 @@
 			}
 		}
 
-		@include dark($mode) {
+		@include daff-dark-mode($mode) {
 			@include daff-icon-button-theme-variant(
 				daff-color($neutral, 50),
 				daff-color($neutral, 40),

package/button/src/button/raised/raised-theme.scss

@@ -1,6 +1,6 @@
 @use '../../../../scss/theming' as *;
 
-@mixin daff-raised-button-theme-variant($base-color) {
+@mixin daff-raised-button-theme-variant($theme, $base-color) {
 	@if daff-contrast-ratio($base-color, daff-text-contrast($base-color)) < 4.5 {
 		@error 'Button Initial State: ' + map.get(a11y.$wcag-aa-errors, 'text-contrast');
 	}
@@ -37,39 +37,39 @@
 	$neutral: daff-get-palette($theme, neutral);
 
 	.daff-raised-button {
-		@include daff-raised-button-theme-variant(daff-color($neutral, 20));
+		@include daff-raised-button-theme-variant($theme, daff-color($neutral, 20));
 
 		&.daff-primary {
-			@include daff-raised-button-theme-variant(daff-color($primary));
+			@include daff-raised-button-theme-variant($theme, daff-color($primary));
 		}
 
 		&.daff-secondary {
-			@include daff-raised-button-theme-variant(daff-color($secondary));
+			@include daff-raised-button-theme-variant($theme, daff-color($secondary));
 		}
 
 		&.daff-tertiary {
-			@include daff-raised-button-theme-variant(daff-color($tertiary));
+			@include daff-raised-button-theme-variant($theme, daff-color($tertiary));
 		}
 
 		&.daff-dark {
-			@include daff-raised-button-theme-variant($black);
+			@include daff-raised-button-theme-variant($theme, $black);
 		}
 
 		&.daff-light {
-			@include daff-raised-button-theme-variant($white);
+			@include daff-raised-button-theme-variant($theme, $white);
 		}
 
 		&.daff-theme {
-			@include daff-raised-button-theme-variant($base);
+			@include daff-raised-button-theme-variant($theme, $base);
 		}
 
 		&.daff-theme-contrast {
-			@include daff-raised-button-theme-variant($base-contrast);
+			@include daff-raised-button-theme-variant($theme, $base-contrast);
 		}
 
 		&[disabled],
 		&.daff-disabled {
-			@include daff-raised-button-theme-variant(daff-color($neutral, 30));
+			@include daff-raised-button-theme-variant($theme, daff-color($neutral, 30));
 			color: daff-color($neutral, 50);
 
 			&::after {
@@ -78,15 +78,15 @@
 		}
 
 		&.daff-warn {
-			@include daff-raised-button-theme-variant(daff-color($warn));
+			@include daff-raised-button-theme-variant($theme, daff-color($warn));
 		}
 
 		&.daff-critical {
-			@include daff-raised-button-theme-variant(daff-color($critical));
+			@include daff-raised-button-theme-variant($theme, daff-color($critical));
 		}
 
 		&.daff-success {
-			@include daff-raised-button-theme-variant(daff-color($success));
+			@include daff-raised-button-theme-variant($theme, daff-color($success));
 		}
 	}
 }

package/button/src/button/stroked/stroked-theme.scss

@@ -46,7 +46,7 @@
 			}
 		}
 
-		@include light($mode) {
+		@include daff-light-mode($mode) {
 			&.daff-primary {
 				@include daff-stroked-button-theme-variant(
 					daff-color($primary)
@@ -98,7 +98,7 @@
 			}
 		}
 
-		@include dark($mode) {
+		@include daff-dark-mode($mode) {
 			&.daff-primary {
 				@include daff-stroked-button-theme-variant(
 					daff-color($primary, 40)

package/button/src/button/underline/underline-theme.scss

@@ -24,7 +24,7 @@
 	$mode: daff-get-theme-mode($theme);
 
 	.daff-underline-button {
-		@include light($mode) {
+		@include daff-light-mode($mode) {
 			@include daff-underline-button-theme-variant(
 				daff-color($neutral, 70)
 			);
@@ -80,7 +80,7 @@
 			}
 		}
 
-		@include dark($mode) {
+		@include daff-dark-mode($mode) {
 			@include daff-underline-button-theme-variant(
 				daff-color($neutral, 40)
 			);

package/callout/src/callout-theme.scss

@@ -17,7 +17,7 @@
 	$mode: daff-get-theme-mode($theme);
 
 	.daff-callout {
-		@include light($mode) {
+		@include daff-light-mode($mode) {
 			@include daff-callout-theme-variant(daff-color($neutral, 10));
 
 			&.daff-primary {
@@ -33,7 +33,7 @@
 			}
 		}
 
-		@include dark($mode) {
+		@include daff-dark-mode($mode) {
 			@include daff-callout-theme-variant(daff-color($neutral, 90));
 
 			&.daff-primary {
@@ -57,12 +57,22 @@
 			@include daff-callout-theme-variant($base-contrast);
 		}
 
+		// remove when `DaffColorEnum.Black` is removed in v1.0.0
 		&.daff-black {
 			@include daff-callout-theme-variant($black);
 		}
 
+		// remove when `DaffColorEnum.White` is removed in v1.0.0
 		&.daff-white {
 			@include daff-callout-theme-variant($white);
 		}
+
+		&.daff-dark {
+			@include daff-callout-theme-variant($black);
+		}
+
+		&.daff-light {
+			@include daff-callout-theme-variant($white);
+		}
 	}
 }