Once the design part is done, the Dev team of ZDS needs to translate the designs and specifications into code libraries that interpret the set of foundations, components and guidelines from a technical perspective to come with a translation into development tools that can be:
Easy to install, use, and integrate with different workflows, frameworks and programming languages.
Can support the widest amount of devices, browsers, viewports, etc.
Have a concise documentation about the use of the libraries and the configuration and application of the components.
Have tooling developed around the coding environments to improve de DX and easy and speed the development when our libraries are used.
Have a consistent framework/language for the development basis that can ease the adaptation of developers between projects by sharing a big part of the code base with these libraries.
All packages that are released with an specific version are 100% compatible. That means that the version common to the whole ecosystem. This reduces the confusion or having to deal with incompatibilities. Just one number per release for all packages. That applies to the interdependencies, so version 1.2.3 of @zurich/css-components would use the version 1.2.3 of @zurich/design-tokens. Even when this can lead to package versions with no changes at all, it help us keep the consistency as set, making sure that when a component is released, changed, or fixed, this is going be applied to all the packages consistently, setting the concept of the design system as a whole.
Even when there are some ways of using different versions of the ZDS at the same time, we encourage not to do so and ask the ZDS team if some special needs need to be considered so we can provide the best solution possible. An example of this will be using new components of higher minor versions with a previous package version. This is possible, but requires to be tested for compatibility in each case.
The development part of Zurich Design System are in the end on 4 different packages that are served via NPM as public packages, so they are open and don't require any type of authentication to be installed. That eases the integration with every kind of project.
Here's a diagram showing the available packages and their relationships:
@zurich/dev-utils is an independent package that contains development utils that can be used during the coding and testing, but that are not relevant for production and will be transpiled (like SCSS or TS utils). When this package is used to build the others (like some of their SCSS code), it leaves no footprint or dependency after build.
The @zurich/react-native just uses @zurich/web-components for the typing, to ensure that the API of the WebComponents is the same (or as close as possible ensuring compatibility) as for the React Native components in order to reduce complexity and make them interchangeable. Also, the @zurich/react-native library doesn't use CSS mechanics, so the customization of the components works differently.
To know more about each package, check the packages installation section, and in order to know which package you should use, check the "how it works" section to know about the mechanics and compatibilities of the Zurich Design System.
We are providing TypeScript support to all the libraries; including the ones that only implement CSS. This ensure, not only a great developer experience (DX) due to the intellisense and error identifications that TypeScript provides, but allows to have a smoother adoption of the ZDS as a tool without having to continuously check the documentation.
We've also added a great inside documentation for every component, attribute, and functionality using JSDoc, so everything you need in order to use each feature can be consulted without leaving your IDE. This includes explanations, description, examples with snippets, links, and even visualization examples.
In order to provide a great service, we need to make sure that we are providing all the necessary assets in a well thought nd optimized way. That's why we have our own CDN with versioned, systemized, and optimized assets to be consumed for third parties.
This CDN is ensured for high availability and really fast access for all the regions we give support to.
Most of our packages are also available to be consumed via CDN link, not only via local installation. That allows Fast prototyping and super easy use of the components and features of our ZDS. Check each package to check how to use them via CDN.
The CDN is still not ready due to the cloud infrastructure.
The Zurich Design System hosts all the necessary assets to utilize the components and code implementations in its own CDN. This avoids the need of having to serve again everything regarding the ZDS, saving costs and reducing the complexity for start using it.
The high availability endpoints are:
https://zds.zurich.com/0.5.18/<category>/<path>: access to the different produced assets via HTTPS URLs (SVGs, PNGs, JPEGs, etc.). The <category> options would go according to the asset type:
Every ZDS component is capable of handling its own internal states. That means that you can use them without having to worry about the control of the component for this one to work. However, there are five configurations to take into account:
(Or pre-populated) the component is pre-populated using JavaScript. Configurations can also be set like this, specially for complex ones. This way, we can pre-populate the models, but still allowing the component to have self control.
The component has the model hardcoded in the HTML. This is great for configurations, since it renders directly without having to wait for the JS to execute and avoiding two or more renderings, but not for models (avoid for those).
(Or reactive) the component handles its own but we perform actions based of emitted events It can be combined with the preset approach. Configurations can always be done via forced.
html
<z-text-input id="my-input" config="shaped"></z-text-input><script type="module"> const input = document.getElementById('my-input'); /* Dynamic configuration can de done here */ input?.addEventListener('change', ({ detail }) => { /* Perform something with the value */ const isInvalid = detail && detail.length < 3; input.invalid = isInvalid; });</script>
(Or bound) the component is controlled by the parent. That means that we need to listen to the events (specially the ones related to the model of the component), and then returning the value via model attribute or property. External transformations can be performed, but the control loop needs to be closed to keep consistency between the component and its model, and the bound variable in our application.
Configurations can be done forced in the HTML and dynamic reactive manipulation can be done.
html
<z-text-input id="my-input" config="shaped"></z-text-input><output id="my-output"></output><script type="module"> const input = document.getElementById('my-input'); const output = document.getElementById('my-output'); input?.addEventListener('change', ({ detail }) => { /* perform something with the value, or transform it */ output.innerHTML = detail.toLowerCase(); });</script>
This can be achieved in frameworks using the corresponding directives ([(ngModel)] in Angular or v-model in Vue) or mechanisms (assignation and callbacks in React).
