FKL Design System (fkl-ds)

@fat-karting-league/design-system is FKL's reusable React component library. It provides accessible components, design tokens, semantic content styling and compiled CSS for React applications.

An Angular sibling package (@fat-karting-league/design-system-angular) is available from the same monorepo as an addition, not a replacement. Both share the same compiled stylesheet and fkl-ds-* DOM contracts.

Colour, typography and button styles follow the FKL styleguide. Button variants are primary (blue fill), secondary (white with black border), tertiary (underlined link style), plus ghost and destructive.

Installation

npm install @fat-karting-league/design-system

React and React DOM are peer dependencies. Consumers do not need Tailwind CSS.

import {
  Button,
  Heading,
  Text,
  cn,
} from "@fat-karting-league/design-system";
import "@fat-karting-league/design-system/styles.css";

export function Example() {
  return (
    <section>
      <Heading level={1}>Account</Heading>
      <Text>Manage your account details.</Text>
      <Button>Save changes</Button>
    </section>
  );
}

CSS entry points

Import the complete design system once:

import "@fat-karting-league/design-system/styles.css";

styles.css includes tokens, a minimal reset, document defaults, semantic HTML defaults, rich-content styles, component styles and accessibility styles.

Import tokens without global element styles:

import "@fat-karting-league/design-system/tokens.css";

Import standalone rich-content tokens and styles:

import "@fat-karting-league/design-system/content.css";

Tailwind CSS 4 is used only during development and compilation. The package publishes ordinary CSS, so consuming applications do not install Tailwind, scan library source, copy configuration or recreate tokens.

Global-style policy

Tailwind Preflight is deliberately excluded. The full stylesheet applies only:

• border-box sizing;
• zero body margin;
• inherited fonts for form controls;
• responsive maximum widths for images and SVGs;
• document font, colour and background defaults;
• FKL heading styles (uppercase; Rapid ST for h1–h3, FAT Camera for h4–h6);
• links, text selection and accessible focus outlines.

This explicit reset is intentionally smaller than an application-level reset. Generated Tailwind utilities use the fkl: prefix, while owned public classes and properties use fkl-ds.

Typography and fonts

The FKL visual language uses Rapid ST Bold for display headings (h1–h3) and FAT Camera for supporting headings and body copy. The published CSS entry points include local @font-face rules and the package ships the font assets under dist/fonts, so consumers do not need to configure Google Fonts or a separate font bucket.

The type scale follows the supplied guide: h1–h3 scale across tablet and desktop breakpoints, while h4, h5, intro, body and small text remain fixed across breakpoints.

Rich content

Use .fkl-ds-content for CMS, blog or static semantic content:

export function Article() {
  return (
    <article className="fkl-ds-content">
      <h1>Article title</h1>
      <p>Article introduction.</p>
      <h2>Section heading</h2>
      <p>Section content.</p>
    </article>
  );
}

For CMS HTML:

export function BlogPost({ html }: { html: string }) {
  return (
    <article
      className="fkl-ds-content"
      dangerouslySetInnerHTML={{ __html: html }}
    />
  );
}

Untrusted HTML must be sanitised before it is passed to dangerouslySetInnerHTML.

Lovable integration

Import design-system CSS before application overrides:

import React from "react";
import ReactDOM from "react-dom/client";

import "@fat-karting-league/design-system/styles.css";
import "./index.css";

import App from "./App";

ReactDOM.createRoot(document.getElementById("root")!).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
);

Development

Requires Node.js 20 or newer.

npm install
npm run dev
npm run test
npm run typecheck
npm run lint
npm run build
npm run build:storybook

The library build writes JavaScript, source maps, declarations and styles.css, tokens.css and content.css to dist.

Storybook and deployment

Storybook is the primary documentation site for foundations and components. It includes introduction and getting-started guides, interactive examples, controls and source snippets.

# Local Storybook
npm run dev

# Production Storybook build (also used for Vercel)
npm run build:demo

# Preview the production output
npm run preview:demo

Component architecture

shadcn/ui is an initial source-code reference, not a runtime component package. Components are copied into FKL-owned folders, then adapted to FKL APIs, tokens, states and visual language. Radix primitives used by that source, such as Slot, remain focused runtime dependencies.

To add a component:

1. Create src/components/ComponentName/.
2. Add the component, focused tests, Storybook stories and a local index.ts.
3. Use semantic tokens and fkl: Tailwind utilities; do not hardcode colour values.
4. Prefix owned global classes, data attributes, properties and animations with fkl-ds.
5. Export the component from src/components/index.ts.
6. Add Storybook stories and an MDX docs page with usage, examples and source.
7. Run type checking, linting, tests and both builds.

Translating Figma into tokens

1. Identify repeated primitive values and the purpose each value serves.
2. Reuse the existing primitive scale where values are deliberately shared.
3. Map component decisions to semantic tokens such as action, text, border and surface roles.
4. Add a semantic token only when it represents a reusable design decision.
5. Capture default, hover, active, focus, disabled, loading, error and selected states where relevant.
6. Verify responsive, reduced-motion, keyboard and screen-reader behaviour.
7. Update stories, tests and assumptions alongside the implementation.

Versioning and releases

The package is published publicly as @fat-karting-league/design-system. Authenticate with npm, then publish:

npm login
npm publish

The prepublishOnly script automatically runs type checking, linting, unit tests and the production build before npm accepts the release.

Navigation notes

Navigation supports appearance="white" | "blue", responsive logos and a mobile sheet menu when the component is narrower than 1024px. Layout uses CSS container queries against the navigation’s own width (not the viewport), so it behaves correctly inside narrow parents. Sign in is optional (showSignIn); when hidden, desktop collapses to a single row of logo and primary links.

Footer notes

Footer is a black bar with the white compact logo, tagline, underlined links and copyright. Layout uses container queries: left-aligned and smaller type below 1024px; centred from 1024px upward, with wider padding from 1440px.

Hero notes

Hero is a full-bleed image banner with a yellow title, optional highlights, description and CTA slot. Desktop alignment is controlled with alignment="center" | "start"; below 1024px content is always left-aligned and action buttons stack at full width.

Icon notes

Icon resolves brand glyphs by name from a typed registry. Add a glyph under src/components/Icon/glyphs/, register it in icons.ts, then use <Icon name="…" />. Optional appearance="white" | "blue" sets hard black or white colour; omit it to inherit currentColor.

Use semantic versioning:

• patch for compatible fixes and token corrections;
• minor for backwards-compatible components, variants and tokens;
• major for breaking APIs, removed exports or materially changed global styling.

Every release should pass the complete validation suite, document user-facing changes and publish the generated dist files. Publishing should be automated through protected CI with npm provenance when repository hosting is configured.