Skip to main content

Components

Overview​

There are a lot of different basic ways of building a component with kickstartDS. And then there's combinations of those basic ones, to create more complex ones!

We try to give you an overview over the main, basic processes that can be involved when creating a component for your Design System. That doesn't mean that these are exclusively what you should do. There are other ways of approaching things, and it is highly encouraged to use components as you see fit. That extends to the ways you customize them, in the end we're just using widely accepted concepts and best practices that should never get into your way.

Nonetheless, there are some processes that we've found to be pretty universal. They also align really well with the way kickstartDS is built... reducing created technical debt, and minimizing overall effort required to get a good, consistent component in tune with your Design System:

  1. Adapt a component
  2. Create a component
  3. Customize a component
  4. Extend a component

All of these workflows currently involve using kickstartDS components as your foundation, even if customizing their React template in the process. It's completely possible to just use our conventions around having a component API (using JSON Schema) for structure, using Design Token and Component Token for design and layout and CSS / SCSS to connect both. And that last one is optional, you can use any approach to CSS, as long as you're using the semantic Design Token as required.

That way you completely and explicitly own how the template of a component is constructed, without involving any kickstartDS base components. Even better, you can stay compatible with them... as long as you have a matching component API (for example using exclusively your own markup for your Button, but being able to use it in all other existing kickstartDS base components by providing API compatibility through JSON Schema).

Every process is described in roughly the same way, this should helpfully aid in recognizing differences, while also finding your way around more efficiently. You can also freely combine all of those processes, as they are very similar in nature... and described with composability in mind.

We start by giving a short definition, followed by talking about the process itself a bit. This is always followed by descriptions of the two or three main steps involved. Finally we add some background info about the technical debt added that way, and link some example component guides that match that process type.

Every process has the steps "Component Definition" and "Component Creation". And in the case of creating a component, an additional step "Component Mapping".

Accompanying each general guide is a corresponding example component guide, illustrating the process in detail for a demo component:

  1. Adapt a component: Adapt Button component
  2. Customize a component: Customize Headline component
  3. Create a component: Create TeaserCard component
  4. Extend a component: Extend Section component

Four main processes​

See below for a small description about the different proccesses. Each has its own dedicated general guide, and at least one example component guide illustrating it in detail.

Adapt a component​

This is the most basic way of building up a kickstartDS base component. We already have eyed up a specific component, that we want to adapt into our own Design System.

We just reduce the number of properties we use in our own adaptation of the selected component. We can also rename properties (to be a better fit for our own use), or even the component itself. It's pretty normal to end up with multiple components being based on the same kickstartDS base component in the end, but with each having a unique name and component API... thus fulfilling a much more specialized and semantic function in your Design System (for example having both a LinkButton and a NativeButton in your Design System, both based on the kickstartDS Button behind the scenes).

General structure:

  1. Component Definition
  2. Component Creation

Our React template imports kickstartDS components, and rewires them to our own component API.

kickstartDS components are meant to be specialized, but general purpose, components in that way. This is also the reason for every other of the processes including the expectation of also adapting the kickstartDS base components (or more specifically: their component API).

Start adapting

Create a component​

Instead of already having a kickstartDS base component in mind, we start with "just" a concept for a componnent.

We narrow that concept down, find a matching component in kickstartDS and then massage its properties to fit our use case, just like established by "Adapt a component".

General structure:

  1. Component Definition
  2. Component Mapping
  3. Component Creation

The React template imports kickstartDS components, and rewires them to our own component API.

Start creating

Customize a component​

Unlike with adaptation, we do start out with a kickstartDS base component in mind. But it's still missing a crucial feature we need, or one of its features needs a little adjustment to work for us. This means while also following everything established by "Adapt a component", we potentially add new, custom properties to our component API that were not part of the original kickstartDS base component.

General structure:

  1. Component Definition
  2. Component Creation

We can't just re-use existing kickstartDS exports here. Instead we custommize the React template by copying the original markup and adding our own modifications on top.

Start customizing

Extend a component​

While customizing a component allows adding or mutating functionality directly localized to your selected kickstartDS base component, we use composition when extending a component. To combine features of multiple kickstartDS base components, without actually changing React templates or markup.

General structure:

  1. Component Definition
  2. Component Creation

We import multiple kickstartDS base components for our React template, and rewire them to our own component API.

Start extending

General guide structure​

All the guides follow the same general structure. See below for a small description of the parts involved.

Component Definition​

This is always started with a small intro, and introduces an example component that is used throughout that guide to illustrate the key concepts at play.

It's divided into two parts itself:

  • Purpose, and
  • Structure

Purpose​

Every component you add to your Design System should have a clear purpose. This section is about defining that purpose, and introduces the options and restrictions introduced by the chosen processes. We also define a fitting purpose for our example componnent.

Structure​

Following the purpose, we narrow down on the options and fields our component will need to fulfill that purpose. How we actually go about that will depend on the chosen process again. But it will always end in explicitly writing down your components properties, each with a name (e.g. label), type (e.g. string) and short description (e.g. Text used on button).

Component Creation​

We bring our structure to life here, by defining our components component API through JSON Schema. We then add a React template parameterized with those properties, wiring them up to kickstartDS base components as needed.

JSON Schema definition​

First a JSON Schema encoding your structure into a component API is created. This can range from copying existing, re-used properties from kickstartDS base components to writing wholly new schemas.

React template​

The TypeScript types generated by our component API get used to create the JSX needed to render your component. This usually involves importing some kickstartDS base components. We then wire our properties to those base components. In the case of customizing a component we will not use the export / template of the customized base component... instead we copy its markup and add our modifications to it.

Component Mapping​

This is (currently) only done as part of creating a component. It's where we take a component structure and match it to one or more existing kickstartDS base components.

Matching it​

Look through all existing kickstartDS components, and find one or more matching the intended purpose and structure.

Adjustments​

Some properties of our component API will probably not fit 1:1, so we'll rename and rewire them to fit our purpose.

Technical debt added​

Different ways of using components and best practices in kickstartDS, to create your own Design System, result in different technical debt being accrued. Simply using a kickstartDS components, maybe renaming a few of their properties, doesn't add much technical debt in the case of upgrades to kickstartDS, or your own code base... because they are minimally invasive in that sense.

But when customizing a component, and especially it's rendered markup, you inherit that technical debt. In case that component gets changed in the future, you will have to manage the migration. Changing the markup of a component means a Breaking Change in kickstartDS, and we will always provide a detailed migration guide in those cases... but it's more technical debt nontheless.

We try to illustrate the ways each proccess adds such technical debt to your Design System code base.

Examples​

We finish each guide with some example component guides that illustrate that process in practice and detail.