Follow our main guide to learn how you can "Create your Design System" in just 5 steps: Open guide
Customize Headline 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, customizing a component also involves adding something to it, or changing the way certain things work under the hood, by modifying its React template (whereas extending a component does that by composing multiple kickstartDS base components). 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 Customization. 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.
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.
We like what the kickstartDS base Headline component has to offer. We just feel that we need a bit more flexibility in arranging the headlines different contents, which we try to achieve by making the order of headline and subheadline switcheable. We also want some light RTE-like content formatting options for all rendered text, while keeping the component simple by just mapping properties really needed by our use case.
We take level and spaceAfter directly, and rename subheadline to sub, styleAs to style and content to text for our version of the Headline. And crucially we add our own property switchOrder into the mix.
We also keep the name Headline, as it fits our use case well enough already.
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/headline, from our Design System repository root:
_10
mkdir -p src/components/headline
This is the folder we'll add new files to in the coming few paragraphs.
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.
Both fields are straight-forward string type properties, so we just document them a bit!
We do mark text and sub by setting format to markdown, though, to enable some light RTE-like formatting options of rendered text later on.
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.
Both fields are straight-forward string type properties, so we just document them a bit!
We do mark text and sub by setting format to markdown, though, to enable some light RTE-like formatting options of rendered text later on.
"description": "Switch order of headline and subheadline",
_49
"default": false
_49
},
_49
"level": {
_49
"type": "string",
_49
"title": "Level",
_49
"description": "Level of headline to use",
_49
"enum": ["h1", "h2", "h3", "h4", "p"],
_49
"default": "h2"
_49
},
_49
"style": {
_49
"type": "string",
_49
"title": "Style",
_49
"description": "Style of headline to show",
_49
"enum": ["h1", "h2", "h3", "h4", "p"],
_49
"default": "h2"
_49
},
_49
"spaceAfter": {
_49
"type": "string",
_49
"title": "Space after?",
_49
"description": "Whether to display space after headline",
_49
"enum": ["minimum", "small", "large"],
_49
"default": "small"
_49
}
_49
},
_49
"required": ["level", "text"]
_49
}
This concludes creating the JSON Schema. When running the schema generation in our Design System again, we should now automatically end up with a corresponding type definition to be used in creation of the template in the next step:
src/components/headline/HeadlineProps.ts
src/components/headline/headline.schema.json
_46
/* eslint-disable */
_46
/**
_46
* This file was automatically generated by json-schema-to-typescript.
_46
* DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,
_46
* and run `yarn run schema` to regenerate this file.
export type SpaceAfter = "minimum" | "small" | "large";
_46
_46
/\*\*
_46
_46
- Component used for headlines
_46
\*/
_46
export interface HeadlineProps {
_46
text: Text;
_46
sub?: Sub;
_46
switchOrder?: SwitchOrder;
_46
level: Level;
_46
style?: Style;
_46
spaceAfter?: SpaceAfter;
_46
[k: string]: unknown;
_46
}
How your schema generation is started might change depending on your setup. If you've followed our "Create your Design System" guide before, or want to add it like we do, follow this section of it closely.
As the final step for this example, we'll add the template. This will be a purely functional React component, mapping our component structure (as defined in the JSON Schema) to the original component we're basing our work off of; the kickstartDSStorytelling component.
Import and add generated props from HeadlineProps.ts. Generated by our JSON Schema, these guarantee you're matching your expected component structure while implementing. In combination with TypeScript this enables auto-complete and auto-fix for even better DX! (see here, at the very end of that section, for more details)
We also add our rendering functions and HTMLAttributes<HTMLElement> to the type signature.
src/components/headline/HeadlineComponent.tsx
_14
import { HTMLAttributes, FC } from "react";
_14
_14
import { defaultRenderFn } from '@kickstartds/core/lib/core';
We also need to add our own properties, so we'll destructure props. We add our default values here, too. Because we're using rendering functions, we also need to have those in there... we'll just pass through everything HTMLAttributes related!
src/components/headline/HeadlineComponent.tsx
_26
import { HTMLAttributes, FC } from "react";
_26
_26
import { defaultRenderFn } from '@kickstartds/core/lib/core';
As we can't use the underlying kickstartDS base component export directly, because we intend to customize its behaviour, we start with the raw component template of the original kickstartDSHeadline instead. You can find its markup in our Github mono-repository here.
We also write the level into TagName, which we'll use to generically render the correct markup tag for the Headline.
src/components/headline/HeadlineComponent.tsx
_53
import classnames from "classnames";
_53
import { HTMLAttributes, FC } from "react";
_53
_53
import { defaultRenderFn } from '@kickstartds/core/lib/core';
Import and add generated props from HeadlineProps.ts. Generated by our JSON Schema, these guarantee you're matching your expected component structure while implementing. In combination with TypeScript this enables auto-complete and auto-fix for even better DX! (see here, at the very end of that section, for more details)
We also add our rendering functions and HTMLAttributes<HTMLElement> to the type signature.
We also need to add our own properties, so we'll destructure props. We add our default values here, too. Because we're using rendering functions, we also need to have those in there... we'll just pass through everything HTMLAttributes related!
As we can't use the underlying kickstartDS base component export directly, because we intend to customize its behaviour, we start with the raw component template of the original kickstartDSHeadline instead. You can find its markup in our Github mono-repository here.
We also write the level into TagName, which we'll use to generically render the correct markup tag for the Headline.
To complete the template we add the HeadlineProvider to our src/components/Providers.jsx:
src/components/Providers.jsx
_14
import { ButtonProvider } from "./button/ButtonComponent";
_14
import { SectionProvider } from "./section/SectionComponent";
_14
import { TeaserBoxProvider } from "./teaser-card/TeaserCardComponent";
_14
import { HeadlineProvider } from "./headline/HeadlineComponent";
_14
_14
export default (props) => (
_14
<ButtonProvider>
_14
<HeadlineProvider>
_14
<SectionProvider>
_14
<TeaserBoxProvider {...props} />
_14
</SectionProvider>
_14
</HeadlineProvider>
_14
</ButtonProvider>
_14
);
This concludes the creation of our new Headline component. It's now ready to be used inside your Design System, and available to your down stream consumers... hopefully efficiently closing a gap for them!
If you're using Storybook, you can follow this part of the example to get all the integration goodness possible with kickstartDS!
Storybook setup
This guide assumes you're using a set up like described in our Create your
Design System guide! Be sure to adapt commands and
configuration to your use accordingly, when following this part!
Add the following file to your src/components/headline folder:
We do this by binding to our Template, and use pack to convert all deep JSON args to flat (. delimited) keys and values. This is the format your Storybook Controls get generated off.
src/components/headline/Headline.stories.jsx
_65
import { Headline } from "./HeadlineComponent";
_65
import { pack, getArgsShared } from "@kickstartds/core/lib/storybook";
_65
import HeadlineStories from "@kickstartds/base/lib/headline/headline.stories";
_65
import schema from "./headline.schema.dereffed.json";
