Extend `Section` component

This guided example shows how you'd add components to your Design System that use a kickstartDS base component pretty directly. But unlike just adapting a component, extending a component also involves adding something to it, or changing the way certain things work under the hood, by composing multiple kickstartDS base components (whereas customizing a component does that by adding changes to the customized components React template). This expands possible applications of existing kickstartDS components greatly.

Even while using the component rather directly from kickstartDS, you'll want to find the correct set of properties for your own use case. Components in kickstartDS come equipped with properties for a wide range of possible use cases, so it makes sense to reduce those to the ones you really need... to make components easier to understand, use and reason about!

We call this type of workflow Extension. Learn more about it in our dedicated guide about it. If you're unsure about something, have a look over there. We go into more background detail there about what we're doing here.

Not touching the actual markup generated by components let's us get by without adding any custom styling (CSS / SCSS) to it. We simply reuse the already existing Design Token and component structure.

Overview

This is how the result of this guide will look like:

It will only need two simple steps for that:

Component Definition, and
Component Creation

For more details about those steps, have a look at the guide about different component processes and their shared structure.

Requirements

This guide assumes that you already have a working Design System, that is based on kickstartDS, running.
If that's not the case, follow our Create your Design System guide.

1. Component Definition

Purpose

We've found that we'd love to use the existing kickstartDS Section, but it's not quite flexible enough for our taste. We'd like to add more call-to-actions to our page, which mostly consists of such Sections, and don't need as much flexibility for the included headline.

We take width, gutter, mode, content, spaceBefore, spaceAfter and inverted directly from the Section, and rename background to style for our version of it. And crucially we add our own property ctas, to hold call-to-actions, into the mix, while reducing the complexity of headline significantly... from mapping to all of the Headline properties, to just a single string type prop setting its content.

We also keep the name Section, as it fits our use case well enough already.

Structure

Defining the structure of a component means finding the component API for it:

Property	Type	Description
`headline`	`string`	Headline for the section
`width`	`enum`	Width of section to use
`gutter`	`enum`	Size of gutter to use
`mode`	`enum`	Layout mode used for section contents
`content`	`array`	Allowed content for the section
`style`	`enum`	Style of section, influences background
`spaceBefore`	`enum`	Amount of spacing before the section
`spaceAfter`	`enum`	Amount of spacing after the section
`inverted`	`boolean`	Whether to invert the section
`ctas`	`array`	Call-to-actions to show
`ctas[].label *`	`string`	Label for the Call to action
`ctas[].target *`	`string`	Target for the Call to action

Fields that should be required are marked with a *.

While directly helping us get a better grasp on our new component, these will also be used to write our JSON Schema later!

2. Component Creation

We like to colocate components. This means to have all involved files next to each other in the same folder; the template (.jsx / .tsx), potential CSS / SASS (.css / .scss), JavaScript (.js / .ts), our JSON Schema component definition (.schema.json), and so on.

So we start by creating the directory src/components/section, from our Design System repository root:

mkdir -p src/components/section

This is the folder we'll add new files to in the coming few paragraphs.

JSON Schema definition

First file we'll create is the JSON Schema definition, encoding the structure we've defined for our component before:

Finished JSON Schema

We'll work our way up to this JSON Schema definition.

Start with just the boilerplate for a component definition

This includes all necessarily required values for a valid component definition in kickstartDS.

Add basic info describing component

We start by adding a title, description and $id attribute. The correct $id depends on your Design System configuration. We'll assume you've created components before, living under the schema prefix http://schema.mydesignsystem.com.

Create `headline` field

The headline field is a straight-forward string type properties, so we just document it a bit!
We do mark it by setting format to markdown, though, to enable some light RTE-like formatting options of the rendered text later on.