Adapt Button component
This guided example shows how you'd often add components to your Design System that use a kickstartDS base component pretty directly. This mostly includes components that are needed in every Design System, and that typically also get added with the same name (like our Button here).
Even while directly using the component, including its name, 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 Adaptation. 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
There are some straight foward things we'd want to do with a button in our Design System. Most obvious ones would probably be putting a label on it, and making the target of it available for users. If the target is set, the resulting button should look like one, but use the a tag semantically. It should just be a styled, but native, <button> otherwise.
Additionally we'll want to be able to influence the size of a button, and be able to choose from a limited set of variants. We'll use the options offered by kickstartDS 1:1 for the size property (small, medium, large). But for variant we opt to define our own naming, further removing how a button looks from the naming scheme (like outline, clear, etc) and going for straight priority with primary, secondary and tertiary.
Finally, being able to mark a button as disabled should be possible!
Structure
Defining the structure of a component means finding the component API for it:
| Property | Type | Description |
|---|---|---|
label * | string | Label shown on the button |
target | string | Target that should be linked |
variant | enum | Variant of button used |
size | enum | Size the button should be shown in |
disabled | boolean | Whether the button should be shown as disabled |
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/button, from our Design System repository root:
_10mkdir -p src/components/button
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 label and target fields...
Both fields are straight-forward string type properties, so we just document them a bit!
We do mark target by setting format to uri, though, to enable validation later on.
... and make label required
We declare label as required on the uppermost object!
Add allowed sizes 1/2
We add a size property of type string...
Add allowed sizes 2/2
... and make it an enum, defining its available options explicitly. We also set a default.
Add allowed variants 1/2
We add a variant property of type string...
Add allowed variants 2/2
... and make it an enum, defining its available options explicitly. We also set a default.
Add disabled property
Finally, we add a property disabled, of type boolean.
Finished JSON Schema
Let's have a look at our completed JSON Schema definition.
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 label and target fields...
Both fields are straight-forward string type properties, so we just document them a bit!
We do mark target by setting format to uri, though, to enable validation later on.
... and make label required
We declare label as required on the uppermost object!
Add allowed sizes 1/2
We add a size property of type string...
Add allowed sizes 2/2
... and make it an enum, defining its available options explicitly. We also set a default.
Add allowed variants 1/2
We add a variant property of type string...
Add allowed variants 2/2
... and make it an enum, defining its available options explicitly. We also set a default.
Add disabled property
Finally, we add a property disabled, of type boolean.
Finished JSON Schema
Let's have a look at our completed JSON Schema definition.
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:
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.
React template
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 kickstartDS Storytelling component.
Finished React template
We'll work our way up to this React template.
Start with a boilerplate
Again we'll start with a very basic skeleton for our React component. We're using TypeScript here (.tsx), but it works the same with plain JSX (.jsx).
Add correct typings
Import and add generated props from ButtonProps.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 include and forward a reference to the underlying <button> with forwardRef<HTMLAnchorElement | HTMLBUttonElement>, and allow HTMLAttributes<HTMLElement> to be passed to the root element.
Destructure props
We also need to add our own properties, so we'll destructure props. We add our default values here, too. We'll just pass through everything HTMLAttributes related!
Add Button component 1/5
Now we'll import and add the kickstartDS Button component. To start, we'll use the hard-coded properties of the solid Button variant from our kickstartDS Design System.
Add Button component 2/5
We remove all of the unneeded stuff, as there are a bunch of properties that are completely optional, mainly those having their values undefined or null in the copied JSX, or ones which just state the default value of that property anyway. Those can be freely removed.
Add Button component 3/5
We then connect the props as defined in our component API that are directly taken from the underlying kickstartDS base component by just passing them through. We also destructure props first, so our own properties take precedence when set, and pass ref off to the base component.
Add Button component 4/5
We renamed href to target in our component API, so we add that in its renamed form.
Add Button component 5/5
Finally we have to remap the values for variant, because we've actually renamed the values here.
Add component Provider
We want our Button to replace all default kickstartDS base Buttons, no matter where they appear. We add a Provider for that purpose now!
Finished React template
Let's have a look at our completed React template.
Finished React template
We'll work our way up to this React template.
Start with a boilerplate
Again we'll start with a very basic skeleton for our React component. We're using TypeScript here (.tsx), but it works the same with plain JSX (.jsx).
Add correct typings
Import and add generated props from ButtonProps.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 include and forward a reference to the underlying <button> with forwardRef<HTMLAnchorElement | HTMLBUttonElement>, and allow HTMLAttributes<HTMLElement> to be passed to the root element.
Destructure props
We also need to add our own properties, so we'll destructure props. We add our default values here, too. We'll just pass through everything HTMLAttributes related!
Add Button component 1/5
Now we'll import and add the kickstartDS Button component. To start, we'll use the hard-coded properties of the solid Button variant from our kickstartDS Design System.
Add Button component 2/5
We remove all of the unneeded stuff, as there are a bunch of properties that are completely optional, mainly those having their values undefined or null in the copied JSX, or ones which just state the default value of that property anyway. Those can be freely removed.
Add Button component 3/5
We then connect the props as defined in our component API that are directly taken from the underlying kickstartDS base component by just passing them through. We also destructure props first, so our own properties take precedence when set, and pass ref off to the base component.
Add Button component 4/5
We renamed href to target in our component API, so we add that in its renamed form.
Add Button component 5/5
Finally we have to remap the values for variant, because we've actually renamed the values here.
Add component Provider
We want our Button to replace all default kickstartDS base Buttons, no matter where they appear. We add a Provider for that purpose now!
Finished React template
Let's have a look at our completed React template.
To complete the template we add the ButtonProvider to our src/components/Providers.jsx:
This concludes the creation of our new Button 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!
Use of Storybook
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/button folder:
Import Button component
Import Button component and add it to the Template that we'll bind Stories to.
Import Storybook Controls helpers
Import dereferenced component JSON Schema and getArgsShared helper to generate Storybook Controls, and parameterize Storybook JSON Schema Addon.
Import re-usable Button Stories...
We import the existing Button Story part of @kickstartDS/base, to re-use all the default settings.
... and overwrite values where needed
We set all the Story defaults specific to our component.
Convert args to flat keys
We use pack to convert all deep JSON args to flat (. delimited) keys and values. This is the format your Storybook Controls get generated off.
Create Button variants
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.
If you reopen your Storybook now, or if you kept it running while following along, you should now see your new Button in all its glory!
Finished Code Sandbox
You can also have a look at the completed component in the following Code Sandbox:
Toggle the file browser with the hamburger icon at the top left, or open it directly in your browser.
_10
_10