Component creation

The when and how of component modification

Creating and amending code is a technical task that follows certain styles and is actioned in a process.


Before writing code or designing the first step is to consider:

  1. What behaviour needs to be facilitated?
  2. Is there an existing component that does this?
  3. Are there other components that can be adapted?

Begin by chatting on Slack or creating a discussion in GitHub.


Once you're confident you need a new component, you can make an official component proposal. You'll want to answer questions like:

Those questions should be answered in an "issue" on GitHub; there's a nice template:

Propose a component


With a proposal made, the idea is evaluated for implementation as a core VF component available for all projects.

At a high level the component creation and revision process follows this flow diagram. If the component has technical complications, an unclear use case or other issues, it will be discussed in our Consultation Process.

Even if a component won't be centrally supported, it can still be implemented at your project level.


With an agreed concept, reference designs should be made in Figma (to be used with the Figma design resources).

The design and technical implementation are an asynchronous process and both code and visuals will often need to be adapted as the other evolves. But, in an ideal world, each component implementation begins with a fully designed reference.

Technical implementation

With an agreed concept and a reference design (hopefully) done, the work to begin coding can begin.

As first steps the developer should:

Creating new component files

The VF codebase includes a folder and file creation tool to quickly create all the required files to make a component — it gives you the option to create an element, block, or container.

Install Yeoman
Set up your project

If you're creating a component for all VF users:

If you're adding a custom component to any other project

Generate the new component files
Use the new CSS and JS

If your component uses Sass/CSS, add it to ./components/vf-component-rollup/index.scss

@import "@visual-framework/<%= componentName %>/<%= componentName %>.scss";

If your component uses JS, import this component in ./components/vf-component-rollup/scripts.js or your other JS process:

import { vfComponentName } from '<%= componentName %>/<%= componentName %>';
vfComponentName(); // if needed, invoke it

Technical tips and considerations

Visual design and design tokens

The visual design of the Visual Framework is done in with the Figma design resources and visuals can be created or revised as part of the parent issue for a ticket.

The design decisions of spacing, colours, branding, typography and the like are stored in the Visual Framework's Design tokens and accessible to your code through the mixins in the Sass config and templates component; some common examples: color: set-color(vf-ui-color--black); and @include set-type(text-body--3);

Layout and spacing

Components can typically implement their layout and spacing by leveraging other components; here are the most common:

You can reference these components' classes from your HTML markup and avoid duplicating layout CSS.

Using VF Sass tooling

Follow the VF's CSS and Sass style guidance.

Using JavaScript

Typically we avoid using JavaScript with the Visual Framework, but sometimes it's requires and we have guidance on creating JavaScript.

Maintaining a ``
  • Add a line of what is new in your component.
  • Use sentence styling.
  • Keep your notes, short and punchy.
  • End your sentences with periods.
  • Link to any related issues or discussions, such as the above.
Developing your component
Sharing a component


The work is never done. Components will change and be improved based on learnings.

Find an issue on this page? Propose a change or discuss it.