|
| 1 | +# AGENTS.md |
| 2 | + |
| 3 | +## Project Overview |
| 4 | + |
| 5 | +Dev Kit Italia is a Web Components library implementing the Italian design system (.italia). Components are built with **Lit 3** and published to NPM under the `@italia` scope. The project is a **pnpm monorepo** orchestrated by **Turborepo**. |
| 6 | + |
| 7 | +## Common Commands |
| 8 | + |
| 9 | +```bash |
| 10 | +pnpm install # Install dependencies |
| 11 | +pnpm build # Build all packages (turbo run build analyze) |
| 12 | +pnpm test # Run all tests (serial via turbo) |
| 13 | +pnpm lint # Lint all packages |
| 14 | +pnpm format # Format all packages |
| 15 | +pnpm storybook # Start Storybook dev server on port 6006 |
| 16 | +pnpm storybook:build # Build storybook static folder for production docs |
| 17 | +``` |
| 18 | + |
| 19 | +### Working with individual packages |
| 20 | + |
| 21 | +```bash |
| 22 | +pnpm --filter=@italia/button build # Build a single package |
| 23 | +pnpm --filter=@italia/button test # Test a single package |
| 24 | +pnpm --filter=@italia/button lint # Lint a single package |
| 25 | +``` |
| 26 | + |
| 27 | +Build must run before tests (configured in turbo.json). Build depends on upstream packages (`^build`), so building a leaf package also builds its dependencies. |
| 28 | + |
| 29 | +## Architecture |
| 30 | + |
| 31 | +### Monorepo Layout |
| 32 | + |
| 33 | +- **`packages/*`** — All workspace packages (components, utilities, bundle) |
| 34 | +- **`examples/`** — Framework integration examples (React, Vue, Svelte, Angular, Vanilla JS) |
| 35 | +- **`.storybook/`** — Storybook configuration (discovers stories from `packages/**/stories/**/*.stories.ts`) |
| 36 | + |
| 37 | +### Package Types |
| 38 | + |
| 39 | +| Package | Purpose | |
| 40 | +| --------------------------- | -------------------------------------------------------------------------------------- | |
| 41 | +| `@italia/globals` | Base classes, controllers, directives, form utilities, mixins shared by all components | |
| 42 | +| `@italia/i18n` | Internationalization (LocalizeMixin) | |
| 43 | +| `@italia/test-config` | Shared Web Test Runner config and test utilities | |
| 44 | +| `@italia/typescript-config` | Shared tsconfig presets | |
| 45 | +| `@italia/dev-kit-italia` | Meta-package that re-exports all components | |
| 46 | +| `@italia/<component>` | Individual component packages (button, input, modal, etc.) | |
| 47 | + |
| 48 | +### Component Structure |
| 49 | + |
| 50 | +Each component package follows this layout: |
| 51 | + |
| 52 | +``` |
| 53 | +packages/<name>/ |
| 54 | + src/ |
| 55 | + it-<name>.ts # Lit component class (tagged as <it-name>) |
| 56 | + <name>.scss # Component styles (compiled via rollup-plugin-scss-lit) |
| 57 | + types.ts # Component-specific types/enums |
| 58 | + index.ts # Barrel exports |
| 59 | + test/ |
| 60 | + it-<name>.test.ts # Tests using @open-wc/testing |
| 61 | + stories/ |
| 62 | + it-<name>.stories.ts # Storybook stories |
| 63 | + it-<name>.mdx # Storybook docs |
| 64 | + rollup.config.js # Rollup build config |
| 65 | + web-test-runner.config.js # Extends @italia/test-config |
| 66 | + tsconfig.build.json # Extends @italia/typescript-config |
| 67 | +``` |
| 68 | + |
| 69 | +### Component Base Classes |
| 70 | + |
| 71 | +All components extend `BaseComponent` (from `@italia/globals`), which extends `LitElement` and provides: |
| 72 | + |
| 73 | +- `composeClass` (clsx) for className composition |
| 74 | +- `_ariaAttributes` getter that maps `it-aria-*` / `it-role` host attributes to standard ARIA attributes |
| 75 | +- `generateId()` for internal element IDs |
| 76 | +- `prefersReducedMotion` check |
| 77 | +- `Logger` instance |
| 78 | + |
| 79 | +Form components use the `FormControl` mixin and `FormControlController` from `@italia/globals/form`. |
| 80 | + |
| 81 | +### Build Pipeline |
| 82 | + |
| 83 | +- **Rollup** bundles each component: TypeScript + SCSS (via `rollup-plugin-scss-lit`) + node-resolve |
| 84 | +- `lit` is marked as external (peer dependency) |
| 85 | +- **Custom Elements Manifest Analyzer** generates `custom-elements.json` per component (the `analyze` turbo task) |
| 86 | +- SCSS imports resolve from `node_modules` (Bootstrap Italia, design-tokens-italia) |
| 87 | + |
| 88 | +### Testing |
| 89 | + |
| 90 | +- **@web/test-runner** with **Playwright** browsers |
| 91 | +- Tests use `@open-wc/testing` (fixture, expect, html helpers) |
| 92 | +- Each package has its own `web-test-runner.config.js` extending the shared base config |
| 93 | + |
| 94 | +### Releases |
| 95 | + |
| 96 | +Managed via **Changesets**: run `pnpm changeset` to document changes, then merging the changeset PR bumps versions. Publishing is triggered by git tags via GitHub Actions. |
| 97 | + |
| 98 | +## Key Dependencies |
| 99 | + |
| 100 | +- **lit** ^3.3.0 — Web Component framework |
| 101 | +- **bootstrap-italia** — Italian design system CSS (pinned to specific commit) |
| 102 | +- **design-tokens-italia** ^1.3.3 — Design tokens |
| 103 | +- **sass** ^1.89.0 — SCSS compilation |
| 104 | + |
| 105 | +## Code Style |
| 106 | + |
| 107 | +- Prettier: single quotes, trailing commas, 120 char width |
| 108 | +- ESLint: `@open-wc` config + `@typescript-eslint` + lit/lit-a11y plugins |
| 109 | +- Pre-commit hooks via Husky + lint-staged |
| 110 | +- Node.js 20.x / 22.x / 24.x, pnpm 10.11.0 |
| 111 | + |
| 112 | +## Naming Conventions |
| 113 | + |
| 114 | +- Component tag names: `it-<name>` (e.g., `it-button`, `it-accordion`) |
| 115 | +- Component classes: PascalCase (e.g., `ItButton`, `ItAccordion`) |
| 116 | +- Package names: `@italia/<name>` |
| 117 | +- ARIA passthrough: use `it-aria-*` and `it-role` attributes on the host element (mapped internally by BaseComponent) |
0 commit comments