Garden Design System React Components

All Garden packages follow a standardized directory structure to separate concerns between demos, logic, and styling. A typical package (e.g., /packages/test) contains:

• demo/: Visual component demos generated via Storybook.
• src/: The core component source code and spec tests.
  • elements/: High-abstraction components that wrap interaction behavior and visual styling.
  • styled/: View-level styled-components containing theme-based CSS.
  • index.ts: The public-facing component exports for the package.
• package.json: Configuration for the package as it would be published to the registry.
• README.md: Essential package description, installation, and usage instructions.

To ensure proper categorization in Storybook, use argTypes and parameters effectively.

argTypes

Categorize props into two acceptable categories:

1. Subcomponent: All subcomponent props (including children) should be specified under the associated subcomponent name.
2. "Story": Ancillary controls needed to stress the full flexibility of the component.

Use argTypes to rename props with subcomponent notation for clarity:

argTypes={{
  hasHint: { name: Hint, table: { category: 'Story' } }
}}

parameters

Use parameters to link to Figma designs. This helps developers see the intended design for a specific story state.

args

Storybook provides main component props as args. For Garden boolean props that default to true, you must explicitly specify them in args to match the default behavior.

Garden components are published under the @zendeskgarden npm namespace and follow semantic versioning (SemVer).

Key versioning behaviors:

• Patch versions: Bug fixes.
• Minor versions: New features.
• Major versions: Breaking changes.
• Release Cadence: Fixes are released upon approval, features are released weekly, and breaking changes are released once per quarter.
• Fixed Mode: Garden uses a fixed (common major) versioning strategy. While you can upgrade individual packages independently, it is best practice to keep all Garden dependencies up-to-date to ensure compatibility.

A Pattern is a demo story that demonstrates how a component works in conjunction with other Garden components or external libraries.

Patterns may violate the 'isolation' best practice because they focus on layout and behavior that supercede a single component. They are often used for visual testing or to demonstrate complex interactions.

Important: Patterns are intended to be short-lived. Developers should move successful patterns to the official documentation website and remove them from Storybook to ensure the website remains the single source of truth.

Garden does not explicitly export type definitions. Instead, consumers should reuse types by accessing them through the publicly exported interface using indexed access types. This ensures a single source of truth for component properties.

For example, if you need to reference a specific property type from a component's props, use the following pattern:

// Instead of importing a specific type, use the interface's property
type ButtonSize = IButtonProps['size'];

Garden components are built using a three-tier architecture to separate concerns:

1. Container components: No-UI components that manage complex logic like accessibility, keyboard interactions, and RTL (Right-to-Left) awareness. They expose this logic via React hooks or render props.
2. View components: Responsible for visual rendering using styled-components. They should extend semantic HTML elements and follow strict CSS ordering rules.
3. Element components: High-abstraction wrappers that combine Container logic and View styling. These are the public-facing components used by consumers.

To ensure new components follow these rules, use the npm run new command to generate starter code.