API surface

What is an API?

API refers to those parts of the Jutro Design System that compose the contract between the Design System and its users.

APIs have a long life span, advanced deprecation announcements will be given before any changes are made to APIs. Elements will remain in a "deprecated" or "legacy" status for a period of time before being fully decommissioned.

Only backwards-compatible changes will be implemented for APIs in minor releases. The rare exception to this rule is necessary security fixes, or bug fixes that address previously broken backwards-compatibility.

We recommend that you avoid relying on non-API elements in order to facilitate the maintenance and upgrade of the applications.

Jutro Design System API

The following aspects are considered to be Jutro Design System APIs:

• App configuration and configuration default values, including package.json and /src/config/config.json
• CLI commands: availability, signature, and purpose (outcome might be modified to adapt it to the latest versions and practices)
• Components' accessibility tree
• Component visual aspects and behavior, such as colors, sizes, shapes, and whitespaces
• Configuration of the developer tooling inherited by the customer
• Micro frontends nesting compatibility
• Package names and package and module public export structures or signatures
• React component props: their names, being optional or required, and data types or shapes
• Schema of the configuration files, such as app configs
• Support for major third-party dependencies that affect develop / build / deploy infrastructure: for example support for Node.js, React, or Webpack versions would be maintained, but support for new versions might be added
• Theming API: design tokens and a limited set of CSS variables (only those applied to legacy components)
• Translation keys and default values
• TypeScript definitions

Aspects that are not APIs

Given the nature of the frontend development, there are some details of the implementation, or its outcome, that are exposed to consumers. However, not all of them are part of the API.

Breaking changes (non backwards compatible changes) to aspects that are not APIs can occur in minor releases without any mention in the release notes. Users are strongly advised not to rely on these aspects in any production code.

What aspects are not APIs?

The following is a list of aspects that are not APIs but still exist within the API surface:

• Any exports from under internal path
• Component HTML Markup
• CSS class names
• CSS variables (except those applied to legacy components)
• CSS mixins
• Design patterns and examples, which are typically written in the documentation
• Developer and build tooling messaging, such as error text and warnings
• Runtime errors: error throwing and associated error codes (specific messages and additional properties are not part of the API)
• Templates

Internal elements

Please note that in the different library packages there might some components or functions that are exported under the internal path (e.g. @jutro/components/internal/Collapse). While these elements are available and can be imported as any other element, they are only exposed for internal implementation reasons with the purpose of using them in the composition of other library elements. As a result, they are not considered part of the Jutro Design System API and they can be modified or even deleted without prior notification.