@ds-mo/ui 1.2.0 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ds-mo/ui",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "CompoMo — composable web components styled with TokoMo design tokens",
   "keywords": [
     "web-components",
@@ -62,14 +62,20 @@
     "test:e2e": "npm run build && playwright test",
     "test:e2e:install": "playwright install chromium",
     "build:docs": "stencil build --docs",
-    "dev": "node scripts/generate-icon-catalog.mjs && stencil build --dev --watch",
-    "storybook": "stencil build && storybook dev -p 6006",
+    "dev": "node scripts/generate-icon-catalog.mjs && stencil build --watch",
+    "storybook:ui": "storybook dev -p 6006 --no-open",
+    "storybook": "node scripts/storybook-dev.mjs",
     "storybook:build": "storybook build",
     "clean": "rm -rf dist",
     "typecheck": "tsc --noEmit",
     "lint": "eslint src/",
     "registry:build": "node scripts/build-registry.mjs",
-    "mcp": "node scripts/mcp-server.mjs"
+    "mcp": "node scripts/mcp-server.mjs",
+    "figma:connect:help": "figma connect --help",
+    "figma:connect:publish:dry-run": "figma connect publish --dry-run -c figma.config.json --exit-on-unreadable-files",
+    "figma:connect:publish": "figma connect publish -c figma.config.json --exit-on-unreadable-files",
+    "figma:connect:preview": "figma connect preview -c figma.config.json",
+    "typecheck:figma": "tsc -p tsconfig.figma.json --noEmit"
   },
   "peerDependencies": {
     "@ds-mo/icons": "^6.0.0",
@@ -87,8 +93,9 @@
   },
   "devDependencies": {
     "@ds-mo/icons": "^6.0.0",
-    "@ds-mo/tokens": "^2.9.1",
+    "@ds-mo/tokens": "^2.10.0",
     "@eslint/js": "^10.0.1",
+    "@figma/code-connect": "^1.4.8",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@playwright/test": "^1.55.0",
     "@stencil/angular-output-target": "^1.3.1",

package/src/angular/index.ts

@@ -12,6 +12,7 @@ export const DIRECTIVES = [
   d.DsButtonGroup,
   d.DsCard,
   d.DsCheckbox,
+  d.DsChip,
   d.DsDivider,
   d.DsEmptyState,
   d.DsFade,

package/src/angular/proxies.ts

@@ -36,14 +36,14 @@ export declare interface DsAccordion extends Components.DsAccordion {
 
 
 @ProxyCmp({
-  inputs: ['count', 'isSelected', 'label']
+  inputs: ['background', 'count', 'isSelected', 'label', 'max', 'surface', 'variant']
 })
 @Component({
   selector: 'ds-badge',
   changeDetection: ChangeDetectionStrategy.OnPush,
   template: '<ng-content></ng-content>',
   // eslint-disable-next-line @angular-eslint/no-inputs-metadata-property
-  inputs: ['count', 'isSelected', 'label'],
+  inputs: ['background', 'count', 'isSelected', 'label', 'max', 'surface', 'variant'],
   standalone: false
 })
 export class DsBadge {
@@ -296,6 +296,46 @@ export declare interface DsCheckbox extends Components.DsCheckbox {
 }
 
 
+@ProxyCmp({
+  inputs: ['background', 'contrast', 'elevation', 'inactive', 'intent', 'label', 'maxWidth', 'pressed', 'removable', 'rounded', 'size']
+})
+@Component({
+  selector: 'ds-chip',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  template: '<ng-content></ng-content>',
+  // eslint-disable-next-line @angular-eslint/no-inputs-metadata-property
+  inputs: ['background', 'contrast', 'elevation', 'inactive', 'intent', { name: 'label', required: true }, 'maxWidth', 'pressed', 'removable', 'rounded', 'size'],
+  outputs: ['dsRemove', 'dsClick', 'dsPressedChange'],
+  standalone: false
+})
+export class DsChip {
+  protected el: HTMLDsChipElement;
+  @Output() dsRemove = new EventEmitter<CustomEvent<void>>();
+  @Output() dsClick = new EventEmitter<CustomEvent<void>>();
+  @Output() dsPressedChange = new EventEmitter<CustomEvent<boolean>>();
+  constructor(c: ChangeDetectorRef, r: ElementRef, protected z: NgZone) {
+    c.detach();
+    this.el = r.nativeElement;
+  }
+}
+
+
+export declare interface DsChip extends Components.DsChip {
+  /**
+   * Fired when the remove button is clicked.
+   */
+  dsRemove: EventEmitter<CustomEvent<void>>;
+  /**
+   * Fired when an interactive chip is clicked.
+   */
+  dsClick: EventEmitter<CustomEvent<void>>;
+  /**
+   * Fired when the pressed state toggles.
+   */
+  dsPressedChange: EventEmitter<CustomEvent<boolean>>;
+}
+
+
 @ProxyCmp({
   inputs: ['inset', 'length', 'orientation', 'semantic', 'surface']
 })
@@ -343,14 +383,14 @@ export declare interface DsEmptyState extends Components.DsEmptyState {}
 
 
 @ProxyCmp({
-  inputs: ['background', 'height', 'side']
+  inputs: ['background', 'height', 'side', 'size', 'surface', 'visible']
 })
 @Component({
   selector: 'ds-fade',
   changeDetection: ChangeDetectionStrategy.OnPush,
   template: '<ng-content></ng-content>',
   // eslint-disable-next-line @angular-eslint/no-inputs-metadata-property
-  inputs: ['background', 'height', { name: 'side', required: true }],
+  inputs: ['background', 'height', 'side', 'size', 'surface', 'visible'],
   standalone: false
 })
 export class DsFade {
@@ -902,22 +942,18 @@ export declare interface DsTable extends Components.DsTable {
 
 
 @ProxyCmp({
-  inputs: ['background', 'contrast', 'elevation', 'inactive', 'intent', 'interactive', 'label', 'maxWidth', 'pressed', 'removable', 'rounded', 'size']
+  inputs: ['contrast', 'elevation', 'intent', 'label', 'maxWidth', 'rounded', 'size']
 })
 @Component({
   selector: 'ds-tag',
   changeDetection: ChangeDetectionStrategy.OnPush,
   template: '<ng-content></ng-content>',
   // eslint-disable-next-line @angular-eslint/no-inputs-metadata-property
-  inputs: ['background', 'contrast', 'elevation', 'inactive', 'intent', 'interactive', { name: 'label', required: true }, 'maxWidth', 'pressed', 'removable', 'rounded', 'size'],
-  outputs: ['dsRemove', 'dsClick', 'dsPressedChange'],
+  inputs: ['contrast', 'elevation', 'intent', { name: 'label', required: true }, 'maxWidth', 'rounded', 'size'],
   standalone: false
 })
 export class DsTag {
   protected el: HTMLDsTagElement;
-  @Output() dsRemove = new EventEmitter<CustomEvent<void>>();
-  @Output() dsClick = new EventEmitter<CustomEvent<void>>();
-  @Output() dsPressedChange = new EventEmitter<CustomEvent<boolean>>();
   constructor(c: ChangeDetectorRef, r: ElementRef, protected z: NgZone) {
     c.detach();
     this.el = r.nativeElement;
@@ -925,20 +961,7 @@ export class DsTag {
 }
 
 
-export declare interface DsTag extends Components.DsTag {
-  /**
-   * Fired when the remove button is clicked.
-   */
-  dsRemove: EventEmitter<CustomEvent<void>>;
-  /**
-   * Fired when an interactive tag is clicked.
-   */
-  dsClick: EventEmitter<CustomEvent<void>>;
-  /**
-   * Fired when the pressed state toggles.
-   */
-  dsPressedChange: EventEmitter<CustomEvent<boolean>>;
-}
+export declare interface DsTag extends Components.DsTag {}
 
 
 @ProxyCmp({

package/src/react/components.ts

@@ -14,6 +14,7 @@ export { DsButtonGroup } from "./ds-button-group.js";
 export { DsButton } from "./ds-button.js";
 export { DsCard } from "./ds-card.js";
 export { DsCheckbox } from "./ds-checkbox.js";
+export { DsChip } from "./ds-chip.js";
 export { DsDivider } from "./ds-divider.js";
 export { DsEmptyState } from "./ds-empty-state.js";
 export { DsFade } from "./ds-fade.js";

package/src/react/ds-chip.ts

@@ -0,0 +1,35 @@
+'use client';
+
+/**
+ * This file was automatically generated by the Stencil React Output Target.
+ * Changes to this file may cause incorrect behavior and will be lost if the code is regenerated.
+ */
+
+/* eslint-disable */
+
+import type { EventName, StencilReactComponent } from '@stencil/react-output-target/runtime';
+import { createComponent } from '@stencil/react-output-target/runtime';
+import React from 'react';
+
+import { type DsChipCustomEvent } from "@ds-mo/ui";
+import type { Components } from "@ds-mo/ui/dist/components";
+import { DsChip as DsChipElement, defineCustomElement as defineDsChip } from "@ds-mo/ui/dist/components/ds-chip.js";
+
+export type DsChipEvents = {
+    onDsRemove: EventName<DsChipCustomEvent<void>>,
+    onDsClick: EventName<DsChipCustomEvent<void>>,
+    onDsPressedChange: EventName<DsChipCustomEvent<boolean>>
+};
+
+export const DsChip: StencilReactComponent<DsChipElement, DsChipEvents, Components.DsChip> = /*@__PURE__*/ createComponent<DsChipElement, DsChipEvents, Components.DsChip>({
+    tagName: 'ds-chip',
+    elementClass: DsChipElement,
+    // @ts-ignore - ignore potential React type mismatches between the Stencil Output Target and your project.
+    react: React,
+    events: {
+        onDsRemove: 'dsRemove',
+        onDsClick: 'dsClick',
+        onDsPressedChange: 'dsPressedChange'
+    } as DsChipEvents,
+    defineCustomElement: defineDsChip
+});

package/src/react/ds-tag.ts

@@ -7,29 +7,20 @@
 
 /* eslint-disable */
 
-import type { EventName, StencilReactComponent } from '@stencil/react-output-target/runtime';
+import type { StencilReactComponent } from '@stencil/react-output-target/runtime';
 import { createComponent } from '@stencil/react-output-target/runtime';
 import React from 'react';
 
-import { type DsTagCustomEvent } from "@ds-mo/ui";
 import type { Components } from "@ds-mo/ui/dist/components";
 import { DsTag as DsTagElement, defineCustomElement as defineDsTag } from "@ds-mo/ui/dist/components/ds-tag.js";
 
-export type DsTagEvents = {
-    onDsRemove: EventName<DsTagCustomEvent<void>>,
-    onDsClick: EventName<DsTagCustomEvent<void>>,
-    onDsPressedChange: EventName<DsTagCustomEvent<boolean>>
-};
+export type DsTagEvents = NonNullable<unknown>;
 
 export const DsTag: StencilReactComponent<DsTagElement, DsTagEvents, Components.DsTag> = /*@__PURE__*/ createComponent<DsTagElement, DsTagEvents, Components.DsTag>({
     tagName: 'ds-tag',
     elementClass: DsTagElement,
     // @ts-ignore - ignore potential React type mismatches between the Stencil Output Target and your project.
     react: React,
-    events: {
-        onDsRemove: 'dsRemove',
-        onDsClick: 'dsClick',
-        onDsPressedChange: 'dsPressedChange'
-    } as DsTagEvents,
+    events: {} as DsTagEvents,
     defineCustomElement: defineDsTag
 });

package/src/wc/components/Badge/Badge.tsx

@@ -1,32 +1,82 @@
 import { Component, Prop, h, Host } from '@stencil/core';
 
+export type BadgeVariant = 'counter' | 'dot';
+export type BadgeSurface =
+  | 'default'
+  | 'primary'
+  | 'secondary'
+  | 'medium'
+  | 'bold'
+  | 'strong'
+  | 'navigation'
+  | 'always-dark';
+
+const SURFACE_RING: Record<BadgeSurface, string> = {
+  default: 'var(--color-background-secondary)',
+  primary: 'var(--color-background-primary)',
+  secondary: 'var(--color-background-secondary)',
+  medium: 'var(--color-background-medium-neutral)',
+  bold: 'var(--color-background-bold-neutral)',
+  strong: 'var(--color-background-strong-neutral)',
+  navigation: 'var(--color-navigation-background)',
+  'always-dark': 'var(--color-always-dark-background)',
+};
+
 @Component({
   tag: 'ds-badge',
   styleUrl: 'Badge.css',
   scoped: true,
 })
 export class Badge {
+  /** Render as a compact counter or notification dot. */
+  @Prop() variant: BadgeVariant = 'counter';
+
+  /** Count shown for counter badges. Count 0 hides the badge. */
   @Prop() count: number = 0;
+
+  /** Highest count shown before compacting to "+". */
+  @Prop() max: number = 9;
+
+  /** Surface context for the ring around dots. */
+  @Prop() surface: BadgeSurface = 'default';
+
+  /** Direct ring background override for component-local surfaces. */
+  @Prop() background: string | undefined;
+
+  /** Deprecated alias for selected counter styling. Prefer context-specific color in the parent. */
   @Prop() isSelected: boolean = false;
+
   /** Accessible label. Defaults to the count as a string. */
   @Prop() label: string | undefined;
 
   render() {
-    if (this.count === 0) return <Host style={{ display: 'none' }} />;
+    const isDot = this.variant === 'dot';
+
+    if (!isDot && this.count === 0) return <Host style={{ display: 'none' }} />;
 
-    const display = this.count > 9 ? '+' : String(this.count);
-    const ariaLabel = this.label ?? String(this.count);
+    const display = this.count > this.max ? '+' : String(this.count);
+    const ariaLabel = this.label ?? (isDot ? 'Notification' : String(this.count));
+    const ring = this.background ?? SURFACE_RING[this.surface];
 
     return (
-      <Host class="badge" aria-label={ariaLabel}>
+      <Host
+        class={{
+          badge: true,
+          'badge--counter': !isDot,
+          'badge--dot': isDot,
+          'badge--selected': this.isSelected,
+        }}
+        aria-label={ariaLabel}
+        style={{ '--_badge-ring': ring }}
+      >
         <span
           class={{
-            'text-caption-emphasis': true,
-            'badge__text': true,
-            'badge__text--selected': this.isSelected,
+            'badge__mark': true,
+            'text-caption-emphasis': !isDot,
           }}
+          aria-hidden="true"
         >
-          {display}
+          {!isDot && display}
         </span>
       </Host>
     );

package/src/wc/components/Badge/index.ts

@@ -1 +1 @@
-export type {} from './Badge';
+export type { BadgeVariant, BadgeSurface } from './Badge';

package/src/wc/components/Banner/Banner.tsx

@@ -87,8 +87,8 @@ export class Banner {
 
   private getElevation(): string {
     return this.floating
-      ? 'var(--effect-elevation-elevated-floating, var(--effect-elevation-floating))'
-      : 'var(--effect-elevation-elevated)';
+      ? 'var(--effect-elevation-elevated-floating)'
+      : 'var(--effect-elevation-elevated-sm)';
   }
 
   render() {

package/src/wc/components/BarNav/BarNav.tsx

@@ -551,7 +551,13 @@ export class BarNav {
                     {this.activeTabLabel}
                   </span>
                   {this.activeTabHasDot && (
-                    <span class="bar-nav__tab-trigger-dot" aria-hidden="true" />
+                    <ds-badge
+                      class="bar-nav__tab-trigger-dot"
+                      variant="dot"
+                      background="var(--_dot-ring)"
+                      label=""
+                      aria-hidden="true"
+                    />
                   )}
                 </span>
                 <ds-icon

package/src/wc/components/BarNavAction/BarNavAction.tsx

@@ -58,7 +58,15 @@ export class BarNavAction {
         >
           <span class="action-btn__icon-wrap">
             <ds-icon name={this.icon} size="md" color="inherit" />
-            {this.dot && <span class="action-btn__dot" aria-hidden="true" />}
+            {this.dot && (
+              <ds-badge
+                class="action-btn__dot"
+                variant="dot"
+                background="var(--_dot-ring)"
+                label=""
+                aria-hidden="true"
+              />
+            )}
           </span>
         </button>
       </Host>

package/src/wc/components/Chip/Chip.tsx

@@ -0,0 +1,127 @@
+import { Component, Prop, Event, EventEmitter, h, Host } from '@stencil/core';
+
+export type ChipIntent     = 'neutral' | 'brand' | 'ai' | 'negative' | 'warning' | 'caution' | 'positive';
+export type ChipContrast   = 'strong' | 'bold' | 'medium' | 'faint';
+export type ChipElevation  = 'none' | 'flat' | 'elevated';
+export type ChipSize       = 'md' | 'sm' | 'xs';
+export type ChipBackground = 'faint' | 'medium' | 'bold' | 'strong' | 'always-dark';
+
+const TEXT_VARIANT: Record<ChipSize, string> = {
+  md: 'text-body-medium',
+  sm: 'text-body-small',
+  xs: 'text-caption',
+};
+
+const ICON_SIZE: Record<ChipSize, number> = { md: 20, sm: 16, xs: 12 };
+
+@Component({
+  tag: 'ds-chip',
+  styleUrl: 'Chip.css',
+  scoped: true,
+})
+export class Chip {
+  @Prop() label!: string;
+  @Prop() intent: ChipIntent = 'neutral';
+  @Prop() contrast: ChipContrast = 'faint';
+  @Prop() elevation: ChipElevation = 'none';
+  @Prop() size: ChipSize = 'md';
+  @Prop() rounded: boolean = false;
+  @Prop() removable: boolean = false;
+  @Prop() maxWidth: string | number | undefined;
+  @Prop() inactive: boolean = false;
+  @Prop() background: ChipBackground | undefined;
+  @Prop({ mutable: true }) pressed: boolean = false;
+
+  /** Fired when the remove button is clicked. */
+  @Event() dsRemove!: EventEmitter<void>;
+  /** Fired when an interactive chip is clicked. */
+  @Event() dsClick!: EventEmitter<void>;
+  /** Fired when the pressed state toggles. */
+  @Event() dsPressedChange!: EventEmitter<boolean>;
+
+  private handleClick = () => {
+    if (this.inactive) return;
+    this.pressed = !this.pressed;
+    this.dsPressedChange.emit(this.pressed);
+    this.dsClick.emit();
+  };
+
+  private handleKeyDown = (e: KeyboardEvent) => {
+    if (this.inactive) return;
+    if (e.key === 'Enter' || e.key === ' ') {
+      e.preventDefault();
+      this.handleClick();
+    }
+  };
+
+  private handleRemove = (e: MouseEvent) => {
+    e.stopPropagation();
+    this.dsRemove.emit();
+  };
+
+  render() {
+    const sz = this.size.toUpperCase() as 'MD' | 'SM' | 'XS';
+    const textVariant = TEXT_VARIANT[this.size];
+    const iconSize = ICON_SIZE[this.size];
+
+    const maxWidthStyle = this.maxWidth != null
+      ? { maxWidth: typeof this.maxWidth === 'number' ? `${this.maxWidth}px` : this.maxWidth }
+      : undefined;
+
+    const hostCls: Record<string, boolean> = {
+      'tag': true,
+      [`tag--intent-${this.intent}`]: true,
+      [`tag--contrast-${this.contrast}`]: true,
+      [`tag--elevation-${this.elevation}`]: true,
+      [`tag--size-${this.size}`]: true,
+      'tag--rounded': this.rounded,
+      'tag--rounded-no-icon-left': this.rounded,
+      'tag--rounded-no-remove-right': this.rounded && !this.removable,
+      [`tag--icon-left-${sz}`]: false,
+      [`tag--icon-right-${sz}`]: this.removable,
+      'tag--removable': this.removable,
+      'tag--interactive': true,
+      'tag--inactive': this.inactive,
+      'tag--pressed': this.pressed,
+      'tag--on-medium':      this.background === 'medium',
+      'tag--on-bold':        this.background === 'bold',
+      'tag--on-strong':      this.background === 'strong',
+      'tag--on-always-dark': this.background === 'always-dark',
+    };
+
+    return (
+      <Host
+        class={hostCls}
+        style={maxWidthStyle}
+        onClick={this.handleClick}
+        onKeyDown={this.handleKeyDown}
+        role="button"
+        tabIndex={this.inactive ? -1 : 0}
+        aria-pressed={String(this.pressed)}
+        aria-disabled={this.inactive || undefined}
+      >
+        <span class="tag__icon-slot" style={{ fontSize: `${iconSize}px`, lineHeight: '0' }}>
+          <slot name="icon" />
+        </span>
+        <span class={{ 'tag__label': true, [textVariant]: true }}>
+          {this.label}
+        </span>
+        {this.removable && (
+          <button
+            type="button"
+            class="tag__remove"
+            onClick={this.handleRemove}
+            aria-label={`Remove ${this.label}`}
+            tabIndex={-1}
+          >
+            <slot name="remove-icon">
+              <span class="tag__remove-x" style={{ fontSize: `${iconSize}px`, lineHeight: '0' }}>
+                ✕
+              </span>
+            </slot>
+          </button>
+        )}
+      </Host>
+    );
+  }
+}

package/src/wc/components/Chip/index.ts

@@ -0,0 +1 @@
+export type { ChipIntent, ChipContrast, ChipElevation, ChipSize, ChipBackground } from './Chip';

package/src/wc/components/Fade/Fade.tsx

@@ -1,30 +1,110 @@
 import { Component, Prop, h, Host } from '@stencil/core';
 
 export type FadeSide = 'top' | 'bottom' | 'left' | 'right';
+export type FadeSurface =
+  | 'default'
+  | 'primary'
+  | 'secondary'
+  | 'navigation'
+  | 'media'
+  | 'always-dark'
+  | 'inverted';
+export type FadeSizeToken =
+  | 'size-000'
+  | 'size-050'
+  | 'size-075'
+  | 'size-100'
+  | 'size-150'
+  | 'size-200'
+  | 'size-250'
+  | 'size-300'
+  | 'size-400'
+  | 'size-500'
+  | 'size-600'
+  | 'size-800';
+export type FadeSize = FadeSizeToken | (string & {});
+
+const SIZE_VALUE: Record<FadeSizeToken, string> = {
+  'size-000': 'var(--dimension-size-000)',
+  'size-050': 'var(--dimension-size-050)',
+  'size-075': 'var(--dimension-size-075)',
+  'size-100': 'var(--dimension-size-100)',
+  'size-150': 'var(--dimension-size-150)',
+  'size-200': 'var(--dimension-size-200)',
+  'size-250': 'var(--dimension-size-250)',
+  'size-300': 'var(--dimension-size-300)',
+  'size-400': 'var(--dimension-size-400)',
+  'size-500': 'var(--dimension-size-500)',
+  'size-600': 'var(--dimension-size-600)',
+  'size-800': 'var(--dimension-size-800)',
+};
+
+const SURFACE_BACKGROUND: Record<FadeSurface, string> = {
+  default: 'var(--color-background-secondary)',
+  primary: 'var(--color-background-primary)',
+  secondary: 'var(--color-background-secondary)',
+  navigation: 'var(--color-navigation-background)',
+  media: 'var(--color-media-background)',
+  'always-dark': 'var(--color-always-dark-background)',
+  inverted: 'var(--color-inverted-background)',
+};
 
 @Component({
   tag: 'ds-fade',
   styleUrl: 'Fade.css',
-  shadow: true,
+  scoped: true,
 })
 export class Fade {
-  @Prop() side!: FadeSide;
-  /** Height (or width for left/right) of the fade overlay — any CSS value. */
+  /** Edge where the fade is anchored. */
+  @Prop() side: FadeSide = 'bottom';
+
+  /** Fade depth along the fade axis. Accepts dimension size token names or any CSS length. */
+  @Prop() size: FadeSize = 'size-600';
+
+  /**
+   * Deprecated alias for size. Kept for existing consumers that pass a raw CSS length.
+   * Prefer `size`.
+   */
   @Prop() height: string | undefined;
-  /** Background color to fade from. Defaults to var(--color-background-secondary). */
+
+  /** Surface context used to choose the fade target background token. */
+  @Prop() surface: FadeSurface = 'default';
+
+  /** Direct background override for contexts that already expose a resolved surface var. */
   @Prop() background: string = 'var(--color-background-secondary)';
 
+  /** Controls visibility without removing the element from layout/positioning. */
+  @Prop() visible: boolean = true;
+
+  private resolveSize(): string {
+    if (this.height) return this.height;
+
+    return Object.prototype.hasOwnProperty.call(SIZE_VALUE, this.size)
+      ? SIZE_VALUE[this.size as FadeSizeToken]
+      : this.size;
+  }
+
+  private resolveBackground(): string {
+    if (this.background !== 'var(--color-background-secondary)') return this.background;
+    return SURFACE_BACKGROUND[this.surface];
+  }
+
   render() {
+    const isVerticalEdge = this.side === 'top' || this.side === 'bottom';
+
     return (
       <Host
         aria-hidden="true"
         class={{
           fade: true,
+          'fade--hidden': !this.visible,
+          'fade--vertical-edge': isVerticalEdge,
+          'fade--horizontal-edge': !isVerticalEdge,
           [`fade--${this.side}`]: true,
         }}
         style={{
-          height: this.height,
-          '--ds-fade-bg': this.background,
+          '--ds-fade-size': this.resolveSize(),
+          '--ds-fade-bg': this.resolveBackground(),
         } as Record<string, string>}
       />
     );

package/src/wc/components/Fade/index.ts

@@ -1 +1 @@
-export type { FadeSide } from './Fade';
+export type { FadeSide, FadeSize, FadeSizeToken, FadeSurface } from './Fade';