🌾 gofio-components

Lightweight, agent-friendly, and ultra-fast Web Component library built with Lit, TypeScript, and Vite.

Designed with Atomic Design principles ⚛️, full tree-shaking support 🌲, and automated Custom Elements Manifest 🤖 for IDE autocompletion and AI tooling.

⚡ Features

• Zero-Bloat & Tree-Shakeable: Import only the components you use.
• Agent & Tooling Friendly: Generates custom-elements.json on every build for complete IDE and AI agent context.
• Framework Agnostic: Works natively in Vanilla JS, React, Vue, Angular, Svelte, or any HTML/JS environment.

gofio-components

Lightweight, framework-agnostic Web Components built with Lit, TypeScript and Vite. The library follows Atomic Design, uses Shadow DOM encapsulation and ships a generated Custom Elements Manifest for editor and tooling support.

Features

• Tree-shakeable ES module distribution with side-effect registration.
• TypeScript declarations and custom-elements.json generated on every build.
• Self-contained primitive design tokens in every component Shadow DOM.
• Optional global token stylesheet for cross-browser theme switching.
• Native events for basic controls and semantic custom events for complex components.
• Tested with Storybook, Vitest, Playwright and the Storybook accessibility addon.

Installation

pnpm add gofio-components lit
# or
npm install gofio-components lit
# or
yarn add gofio-components lit

lit is a peer dependency and must be installed by the consuming application.

Quick Start

Import the package once in the browser entry point. This registers all gofi-* custom elements:

import 'gofio-components';

<gofi-button variant="filled" size="md" shape="rounded">
  Save changes
</gofi-button>
<gofi-input label="Email" type="email" name="email"></gofi-input>

The package also exports the component classes and TypeScript types from its main entry point. The generated manifest is available at gofio-components/custom-elements.json and the global token stylesheet at gofio-components/gofio-components.css.

Components

Atoms

gofi-aspect-ratio, gofi-avatar, gofi-badge, gofi-button, gofi-checkbox, gofi-code, gofi-direction-provider, gofi-empty-state, gofi-icon, gofi-input, gofi-kbd, gofi-label, gofi-loader, gofi-native-select, gofi-overlay, gofi-radio, gofi-separator, gofi-skeleton, gofi-slider, gofi-switch, gofi-textarea, gofi-toggle

Molecules

gofi-accordion, gofi-action-bar, gofi-alert, gofi-breadcrumb, gofi-card, gofi-collapsible, gofi-dropdown-menu-item, gofi-file-upload, gofi-form-field, gofi-hover-card, gofi-input-otp, gofi-list-item, gofi-pagination, gofi-popover, gofi-scroll-area, gofi-search-input, gofi-stat, gofi-steps, gofi-tabs, gofi-toggle-group, gofi-tooltip, gofi-user-menu-button

Use the Storybook documentation for the complete property, slot, state and accessibility reference for each component.

Common Examples

Button and icons

<gofi-button
  variant="filled"
  size="lg"
  shape="pill"
  icon-leading="save"
>
  Save
</gofi-button>

<gofi-button icon-only="settings" aria-label="Settings"></gofi-button>
<gofi-icon name="home" size="32" decorative></gofi-icon>

Data-driven components

Properties whose values are arrays or objects should be assigned as DOM properties, not serialized as HTML attributes:

const tabs = document.querySelector('gofi-tabs');

if (tabs) {
  tabs.tabs = [
    { id: 'overview', label: 'Overview', icon: 'dashboard' },
    { id: 'settings', label: 'Settings', icon: 'settings' },
  ];
}

Boolean attributes use presence/absence in HTML. For example, use disabled, not disabled="false".

Events

Basic controls expose native DOM events such as click, input, change, focus and blur. Complex components emit composed, bubbling semantic events without a library-specific prefix:

| Component | Events | | :--- | :--- | | gofi-accordion, gofi-collapsible | toggle | | gofi-action-bar | deselect-all | | gofi-alert | alert-dismiss | | gofi-breadcrumb | breadcrumb-select | | gofi-card | card-action, card-cancel | | gofi-code | code-copy | | gofi-dropdown-menu-item, gofi-list-item | item-select | | gofi-file-upload | file-add, file-remove | | gofi-hover-card | follow-click | | gofi-input-otp | otp-complete | | gofi-pagination | page-change | | gofi-popover | popover-apply, popover-cancel, popover-close | | gofi-search-input | search-clear | | gofi-stat | stat-click | | gofi-tabs | tab-select | | gofi-toggle-group | toggle-change | | gofi-user-menu-button | menu-toggle |

document.querySelector('gofi-tabs')?.addEventListener('tab-select', (event) => {
  const { tabId } = (event as CustomEvent<{ tabId: string }>).detail;
  console.log('Selected tab:', tabId);
});

Vue and Nuxt 3

Register the library in a client-only plugin because custom elements require the browser DOM:

// plugins/gofio-components.client.ts
import 'gofio-components';

Tell Vue to treat gofi-* tags as custom elements and include the global stylesheet when using data-theme:

// nuxt.config.ts
export default defineNuxtConfig({
  vue: {
    compilerOptions: {
      isCustomElement: (tag) => tag.startsWith('gofi-'),
    },
  },
  css: ['gofio-components/gofio-components.css'],
});

Use standard HTML attributes in templates. For reactive object and array properties, assign them with a Vue property binding where supported by the integration.

Theming

Components include primitive tokens in their Shadow DOM, so basic rendering needs no global CSS. Import the optional stylesheet to enable semantic light/dark tokens through a document-level data-theme attribute in every supported browser:

import 'gofio-components/gofio-components.css';

document.documentElement.dataset.theme = 'dark';
// document.documentElement.dataset.theme = 'light';

System dark mode works through prefers-color-scheme. A scoped dark section can use data-theme="dark" on an ancestor:

<section data-theme="dark">
  <gofi-button>Dark section</gofi-button>
</section>

Accessibility

Components provide semantic HTML, keyboard interaction and reflected state attributes where applicable. Always provide an accessible name for icon-only controls, associate form controls with labels, and keep focusable content usable when composing components.

Local Development

pnpm dev              # Start the Vite development server
pnpm storybook        # Start Storybook on port 6006
pnpm test             # Run Storybook interaction tests in Chromium
pnpm test:watch       # Run tests in watch mode
pnpm build            # Build dist/, declarations, CSS and the manifest
pnpm build-storybook  # Build the static Storybook site

Before publishing, prepublishOnly runs the production build. Release versioning and publishing use Changesets:

pnpm changeset
pnpm version-packages
pnpm release

License

MIT (Gofio Team)