(this page was created automatically. In case of formatting issues, please visit the official Wiki Page)

Clock

Overview

• The Dynamic Clock Component is a countdown timer that provides visual feedback as time progresses.
• Users can start, stop, and monitor countdown periods.
• The timer shows visual warnings when approaching time limits.
• It is useful for time-sensitive operations, timing processes, or activity monitoring.

Specs

Tokens

Structure

• The Clock component displays a countdown timer with a visual progress indicator.
• The timer tracks elapsed time until reaching zero.
• A warning state appears when the configured threshold is reached.

(Configured in General Properties)

• displayName: Sets the display name of the component shown in the structure panel. For example, "Operation Timer" allows easy identification of the clock’s purpose.

Styling

(Configured in Visual Properties)

• countDownBarInSeconds: Defines the total countdown duration in seconds. For example, 300 creates a five-minute timer with visual progress.
• warningRangeInPercent: Sets the percentage threshold at which the timer shows a warning. For example, 80 means the timer warns when 80% of the time has elapsed.

Actions & Variants

(Configured in Events)

• events: Configures the events that the component can trigger and respond to.
• ON_CLOCK_COUNTDOWN_START: Triggered when the countdown timer is started. Can be used to synchronize other components or log the start of a process.
• ON_CLOCK_COUNTDOWN_STOP: Triggered when the countdown is manually stopped. Useful for capturing interrupted processes or user interventions.
• ON_CLOCK_COUNTDOWN_WARNING_REACHED: Triggered when the timer reaches the warning threshold defined by warningRangeInPercent. Can be used to display alerts or trigger preparatory actions.
• ON_CLOCK_COUNTDOWN_EXCEEDED: Triggered when the countdown timer reaches zero. Can be used to execute follow-up actions or notify users that time has expired.
• ON_GLOBAL_PARAMETERS_CHANGE: Triggered when global parameters affecting the component change. Allows the component to respond to system-wide settings changes.
• ON_INIT: Triggered when the component is initialized. Can be used for setup operations.
• ON_DESTROY: Triggered when the component is removed from the DOM. Useful for cleanup operations.

Tests

(Configured in Testing Hooks)

• enableAsHotspot: Enables the clock component as a guided tour hotspot. When enabled, the clock can be highlighted during guided tours to draw user attention to timing features.
• guidedTourHotSpotTitle: Sets the title for the guided tour hotspot with multilingual support. For example, {"en-US": "Monitor Operation Time", "de-DE": "Betriebszeit überwachen"}.
• guidedTourHotSpotDescription: Sets the description for the guided tour hotspot with multilingual support. For example, {"en-US": "Click the play button to start timing your operation. The timer will warn you when time is running out.", "de-DE": "Klicken Sie auf die Wiedergabetaste, um die Zeitmessung Ihres Vorgangs zu starten. Der Timer warnt Sie, wenn die Zeit knapp wird."}.

Links

Figma: https://www.figma.com/design/yck1tcUXgdQ5aYX6iUAwrO/GE---Astronaut-Design-System?node-id=11613-77301&t=iosNC2AkSTGs5lMh-1 Live style guide: https://e1-dev.k8s.myapp.de/live-style-guide/id7/3-clock

Guidelines

Usage

• Use the Clock to time a bounded activity by setting the total duration via countDownBarInSeconds.
• Provide an early warning window so users can prepare before time expires by configuring warningRangeInPercent.

Interactions & Events

• React to environment or preference changes using ON_GLOBAL_PARAMETERS_CHANGE.
• Clean up timers, listeners, or analytics hooks when the Clock is removed via ON_DESTROY.

Dos & Don’ts

Accessibility

• Do not rely on color alone to communicate the warning state; pair the visual change with ON_CLOCK_COUNTDOWN_WARNING_REACHED so downstream cues (e.g., announcements) can run for users with color-vision deficiencies.
• Provide adequate time to perceive changes: set warningRangeInPercent early enough to give users a meaningful buffer before expiry, acknowledging low-vision scenarios where perceivability can be reduced.
• Keep hotspot text concise microcontent and never the sole place for critical instructions; it should supplement, not replace, primary UI affordances.