Introduction

Welcome

Blue Yonder Fractal Design is a new design language for Blue Yonder that is smart, beautiful and scalable. It is a design philosophy that will shape the future of Blue Yonder's user experience.

In a world of unprecedented volatility — the global economy, the weather, consumer behaviours — fractals help us find answers in the chaos, by demystifying complexity and delivering outcomes in elegantly simplified packaging. They are designed to scale — infinitely up and down. Even better, research has shown that exposure fractal patterns can reduce a person's stress level by up to 60%.

Fractals reveal themselves in the beauty of nature: from leaves to rivers to mountains to seashells to hurrycanes. They produce stunning and realistic computer graphics, help diagnosis some diseases, and provide ways to understand complexity in systems, like the timing and size of earthquakes.

These are just a few examples of how fractals can describe the unpredictable. Their patterns will help us to know when to automate; the anomalies will alert; warn, ad guide us. Fractals help us to uncover intelligence — and beauty — in complexity.

Why it Matters

It shows us new ways to work:

Self-Similarity and Scalability
Fractal patterns remain consistent as they scale, a concept known as self-similarity or expanding/ unfolding symmetry.

Education and Insights
Fractals help us understand complex concepts in mathematics, science, and business. Unlocking their formulas has been a catalyst for significant breakthroughs and innovations.

Psychological and Cognitive Benefits
Exposure to fractal patterns can reduce stress, enhance mood, and boost cognitive function, as humans naturally find fractals visually appealing.

Optimizing Structure for Growth
Fractals are pervasive in nature, optimizing the existence of various organisms. For instance, fractal patterns enable plants to grow in ways that maximize exposure to sunlight, enhancing the plant’s ability to survive and flourish.

Scope

The following defines the scope of the Blue Yonder Experience System to reduce scope creep, avoid duplicate component creation, and keep ownership clear across shared packages and apps.

What the Experience System is

The Experience System is the shared, reusable UI platform for Blue Yonder product teams. In this repository, that platform is delivered primarily through package APIs and design foundations:

• @by/experience-system from packages/experience-system: shared React primitives and composed UI building blocks.
• @by/table from packages/table: headless table abstractions built on TanStack Table for reusable data-grid foundations.
• Shared theme and token infrastructure (for example, colors, spacing, typography, density) used by components through Tailwind and ThemeProvider.

If a capability is intended to be reused across multiple products and can be expressed as a stable, composable API, it is an Experience System concern.

What the Experience System provides

The Experience System provides four layers with different responsibilities.

Foundations

Foundations are cross-cutting standards used by all components and consumers.

• Theme contract and runtime context via ThemeProvider.
• Semantic tokens and styling conventions used by shared components.
• Accessibility and interaction baselines expected across reusable UI.

In this repo, foundations live in places such as:

• packages/experience-system/src/theme/
• packages/experience-system/src/components/ThemeProvider/
• apps/blue-yonder-design-site/content/docs/foundation/

Core components (shared package APIs)

Core components are reusable, product-agnostic UI primitives and composed patterns that belong in shared packages.

Examples from packages/experience-system/src/components/ include:

• Input and forms primitives: Input, Textarea, Checkbox, RadioGroup, Select, Field.
• Actions and feedback: Button, ButtonGroup, Alert, Badge, Spinner, Sonner.
• Navigation and overlay primitives: Dialog, Drawer, DropdownMenu, Popover, Tooltip, Tabs.

Examples from packages/table/src/ include:

• Table component.
• useTable hook.
• Re-exported TanStack helpers such as createColumnHelper and row-model utilities.

Criteria for core components:

• Reusable in multiple products/domains.
• Stable API and behavior (typed, documented, testable).
• Not tied to one business workflow, one route, or one product-only dependency.

Registry distribution

Registry items are a distribution mechanism, not a second source of truth for core UI.

In apps/design-system-registry:

• Most registry/by/ui/* items are thin re-exports of core components from @by/experience-system.
• registry/by/components/* items are optional starter composites or examples for CLI-based consumption.
• Item metadata and classification are declared in apps/design-system-registry/registry.json (registry:ui, registry:component, setup/docs items).

Examples:

• Core re-export registry item: registry/by/ui/button.tsx.
• Composite registry example: registry/by/components/search.tsx.

Use the registry when teams want shadcn-style installation and file generation workflows. Do not treat registry files as a replacement for core package ownership.

Application-level implementations (out of core scope)

Application-level components are local to a specific app and should stay in that app when they are not broadly reusable.

Examples in this repo include implementation-specific UI in app folders, such as:

• apps/design-system-mfe/src/components/
• apps/design-system-storybook/src/stories/

These may demonstrate usage, migration states, app experiments, or scenario-specific compositions. They are valid but are not automatically candidates for core packages.

What the Experience System will not provide as components

The Experience System will not add components that are only useful for a single consumer or a single product workflow.

Do not create a core component when the request is:

• Specific to one domain flow (for example, one product's custom search panel behavior).
• Tightly coupled to app state, backend schema, feature flags, or routing unique to one application.
• Primarily a page section, dashboard widget, or business template rather than a reusable UI primitive/pattern.

Instead:

• Keep it in the application codebase as an application-level component.
• If useful for adoption, optionally publish it as a registry example/composite (not as a core primitive).
• Promote it to core only after repeated cross-product reuse demonstrates stable, generic requirements.

Decision guide

Use this quick classification:

• Foundation: global styling/behavior contract used by everything.
• Core component (packages/experience-system or packages/table): reusable, generic, stable API.
• Registry item (apps/design-system-registry): install/distribution wrapper or starter composition for consumers.
• Application-level component (independent app folders): product-specific implementation, not intended for broad reuse.

Recommended workflow for app teams

Step 1: Check existing components

Before building anything:

• Search @by/experience-system
• Check registry examples

Step 2: Compose using existing components

Prefer composition over creating new components.

Step 3: Build locally if needed

If no reusable abstraction exists:

• Build inside your app
• Keep it isolated

Step 4: Evaluate reuse

If multiple teams need it:

• Propose promotion to core

Step 5: Use registry for distribution

If helpful:

• Publish as a registry example

Applying these boundaries keeps shared packages focused, avoids duplicate implementations, and preserves a clean separation between platform UI and product UI.

Sections