Component creation

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:

• What does this component look like?
• What does this component do?
• Would a rebrand change the structure or layout of this component?
• Can other websites use this component? Or is it only useful in your organisation or website?
• Do you have any designs or concepts?
• Have you done any user testing already?
• How often do you expect to make use of this component?
• Can you list out major elements in this component?
• Will all elements of this component be used every time?
• Does this component contain other components?
• Do you already have a component?

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.

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

As first steps the developer should:

• Consult the guidelines for the naming of things and coding standards.
• Ensure the local development environment is configured

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

• Check if it is installed yo --version
• If you need to install yarn global add yo@latest
• If you get stuck, see the official install guide

Set up your project

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

• Clone the vf-core project

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

• Install the vf-component-generator package
• yarn add @visual-framework/vf-component-generator --dev

Generate the new component files

• yarn install
• gulp vf-component
• Run vf-component-generator and answer the questions when prompted
• Type of component: See component guidance
• Name of component: See component naming guidance
• npm package: If you're making something interesting (probably not an 'element'), then saying 'yes' will allow the component to be shared as an optional part of the framework on npm.
• Your customised template component will be in the /components directory and contain a number of pre-generated 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

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

• Consultation process
• Deprecating code