npm package: @kofile/gds-wc
Description: Framework‑agnostic Web Components for the GovOS design system, built with [Lit](https://lit.dev) and powered by the same token pipeline as our React components.
Latest version: 1.4.18

# @govos/wc

Framework‑agnostic Web Components for the GovOS design system, built with [Lit](https://lit.dev) 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](./ARCHITECTURE.md).

## Installing

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

## Usage

In your application:

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

In your HTML:

```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](./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](../../CONTRIBUTING.md#web-component-development)** - 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](https://cursor.sh), automated guardrails are enforced via [`.cursor/rules.json`](../../.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](../../CONTRIBUTING.md#using-cursor-ai) 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](./ARCHITECTURE.md)
- [ ] Read [CONTRIBUTING.md](../../CONTRIBUTING.md#web-component-development)
- [ ] 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`