@govos/wc

Framework‑agnostic Web Components for the GovOS design system, built with Lit and powered by the same token pipeline as our React components.

• Custom elements are prefixed with neumo- (for example, <neumo-button>, <neumo-checkbox>).
• Internal components use neumo-*-internal (e.g., <neumo-checkbox-internal>, <neumo-label>).
• Composed components combine internal atoms (e.g., neumo-checkbox = neumo-checkbox-internal + neumo-label).
• All styling flows through design tokens and a 3‑tier token system.
• Components are multi‑theme by design: swapping theme stylesheets (or data-theme) updates the look without changing component code.

For a detailed look at file layout, naming, tokens, events, and a11y expectations, see ARCHITECTURE.md.

Installing

npm install @govos/wc
# or
yarn add @govos/wc

Usage

In your application:

import "@govos/wc";
// Then use <neumo-*> tags in your HTML/templates

In your HTML:

<link rel="stylesheet" href="/node_modules/@govos/wc/styles/theme-quiet.css" />

<neumo-button data-variant="primary">Save changes</neumo-button>
<neumo-checkbox checked label="Accept terms"></neumo-checkbox>

To switch themes, swap the theme stylesheet or change data-theme on the root element (see ARCHITECTURE.md §5–6).

Contributing

Required Reading

Before creating or modifying a component, you MUST read:

1. ARCHITECTURE.md - Complete architecture documentation covering:

   • Component anatomy and naming conventions
   • Token usage and theming (3-tier token system)
   • Event patterns (neumo-* prefix)
   • Accessibility and testing expectations
   • Shadow DOM and styling strategy

2. CONTRIBUTING.md - Development workflow and requirements:

   • Required icon library (Phosphor only)
   • Required token pipeline (MCP → Anova → foundations)
   • Required tests for each component
   • Storybook requirements
   • Internal vs. public component rules

Using Cursor AI

If you're using Cursor, automated guardrails are enforced via .cursor/rules.json:

• Enforces Lit + LitElement base
• Requires neumo-* event prefixes
• Prevents raw hex values (must use tokens)
• Enforces Phosphor icons only
• Requires ARIA attributes for interactive components
• Requires story + test file generation
• Requires export in index file

See CONTRIBUTING.md for details.

File Structure

• Component implementations: packages/wc/src/components/{name}/{name}.ts
• Tests (colocated): packages/wc/src/components/{name}/{name}.spec.ts
• Stories: packages/wc/stories/{name}.stories.ts
• Shared foundations: packages/wc/src/foundations/ (base-element, events, a11y, icons, tokens)
• Theme stylesheets: packages/wc/styles/themes/

Quick Checklist

• [ ] Read ARCHITECTURE.md
• [ ] Read CONTRIBUTING.md
• [ ] Use LitElement or extend NeumoBaseElement
• [ ] Use tokens only (no raw hex values)
• [ ] Use Phosphor icons only
• [ ] Use neumo-* event prefixes
• [ ] Include ARIA attributes for interactive components
• [ ] Create colocated test file
• [ ] Create Storybook story
• [ ] Export public components from src/index.ts