Using the design system

The design system gives every Government of Barbados service a shared set of styles, components and patterns, so services look and behave consistently and teams do not solve the same problems twice. Use @govtech-bb/frontend for framework-agnostic HTML, or add the thin @govtech-bb/react wrappers when your service is built in React.

Install for HTML or server-rendered services

pnpm add @govtech-bb/frontend@alpha

Every 1.0 build so far is a prerelease, published under the alpha npm tag. Ask for that tag explicitly: a bare install resolves latest, which still points at an older build.

Import the complete stylesheet once:

import '@govtech-bb/frontend/css';

Header, file upload and number input markup use progressive enhancement. Add the matching data-govbb-module attribute shown in the component example and initialise those modules after the document exists:

import { initAll } from '@govtech-bb/frontend';

initAll();

Install for React services

pnpm add @govtech-bb/frontend@alpha @govtech-bb/react@alpha

Import the stylesheet once at the application root, then import components from the React package. React components include their own behaviour, so do not run initAll() over them.

import '@govtech-bb/frontend/css';
import { Button } from '@govtech-bb/react';

<Button type="submit">Continue</Button>;

Assets and tokens

Images and fonts ship below @govtech-bb/frontend/assets/*. Host the image assets through your bundler or public directory and pass their resulting URLs to components such as Header, Footer and OfficialBanner.

Use semantic tokens such as --govbb-color-brand and --govbb-space-s in service CSS. Tailwind applications can reference them directly with arbitrary values such as bg-[var(--govbb-color-brand)]; the design-system core does not require Tailwind.

Build with an AI assistant

Give your assistant the AI documentation index, then ask it to read the linked Markdown pages relevant to your task. The index identifies the package versions used for these docs; implementation details must also match your project’s installed version.

Install the GovBB skills from your service project’s directory:

npx skills add govtech-bb/govbb-design-system

Choose your coding assistant and the skills you need. The AI skills guide explains each skill’s purpose, prerequisites and installation. Review generated code and test your complete service journey before release.

Standards

Every official Government of Barbados service should:

• use components where they meet the user need and test them in the complete service journey
• meet the accessibility standard and check your service against it
• use the GovBB design tokens for colour, typography and spacing

Guidelines

Guidelines explain how and when to use each part of the system. Where a component has a choice of variants or states, its page describes when each one is appropriate. See the Button page for an example.

How this is written

Guidance is written in plain language, in the second person, and describes concrete situations rather than abstract rules. If the same question keeps coming up, we treat that as a sign the guidance is unclear and fix it (see why we don’t use FAQs).

How accessibility reviews work

Documented HTML and React implementations are reviewed in source for semantic structure and keyboard behaviour. Automated accessibility checks cover references with React wrappers.

This is component-level evidence, not a WCAG certificate for a complete service. Content, validation, integrations and the surrounding journey can introduce new barriers.

Every service team remains responsible for testing its complete implementation against the accessibility standard, including its content, validation and surrounding journey. Teams can follow dated decisions in the changelog or report a problem with the guidance.