# Bundle-Aware Component Imports

## Objective

Stop a single icon or helper from dragging a whole library into the shipped bundle.

Import rules and a check that keep component and icon libraries from arriving whole when only a fraction is used.

## Before You Begin

This feature is being added to an application that already exists and already
works. Do not scaffold a new project, and do not assume a blank slate.

Inspect the codebase first and establish:

- The existing application structure and where code of this kind already lives.
- The framework and version in use.
- The existing design system — colours, spacing, typography, and component conventions.
- Existing UI components you can reuse instead of writing new ones.
- The existing database structure, if this feature needs to persist anything.
- The existing authentication and authorization system, if this feature is user-scoped.
- Dependencies already installed, so you don't add a library that duplicates one.
- The existing test setup and conventions.

Only start writing code once you understand the above. If the application
already implements part of this feature, extend it rather than replacing it.

## Implementation Instructions

1. Inspect what the app currently ships and identify the packages whose contribution is far larger than the number of things imported from them. Icon sets, chart libraries, and date utilities are where this usually starts.
2. Import from the narrowest entry point each package offers, and where a package cannot be reduced, wrap it behind a local module so the constraint is enforced in one place instead of at every call site.
3. Audit the app's own shared index files. A single index re-exporting every component means importing one thing can reach everything, including modules with side effects that defeat elimination entirely.
4. Keep code intended for the server out of what is sent to the browser, and check it rather than assuming — configuration objects, secrets-adjacent helpers, and heavy parsing libraries cross that line easily.
5. Do not solve this by lazily loading everything. Deferring a component that is on screen at first paint trades a smaller bundle for a visible delay, which is a worse outcome than the weight.

## UI and UX Requirements

Match the application's existing design system exactly. Reuse its components,
spacing, and typography. This feature should look like it was always there.

## Responsive Requirements

Works on mobile, tablet, and desktop. Touch targets are large enough to hit on a
phone, and nothing overflows horizontally at 320px.

## Accessibility Requirements

- Fully keyboard navigable.
- Correct semantic elements and ARIA roles.
- Visible focus states.
- Meets WCAG AA contrast.
- Dynamic changes are announced to screen readers.
- Respects prefers-reduced-motion.

## Edge Cases

- A package that only offers a single whole-library entry point cannot be reduced by import style alone; either use a narrower distribution or wrap it and load it on demand.
- The app's own shared index files are a common cause of accidental bloat, because one import through the index can pull in every module it re-exports.
- Server-only code that leaks into the browser bundle is both weight and a disclosure risk, and it must be verified rather than assumed from where the file sits.
- Bundle impact has to be visible while a change is being reviewed. A number discovered after release is a number nobody acts on.
- This entry prevents the regression at import time; UI Performance Budget owns the enforced ceiling and the failing check. Report into that budget rather than adding a second, separate threshold.
- A module with side effects at import time cannot be eliminated even when unused, so those must be identified and isolated.
- Duplicate copies of the same dependency at different versions are invisible in a per-package view and need checking separately.

## Testing

Exercise the feature end to end in the running application. Cover every edge case
above, then run the existing test suite and confirm nothing regressed.

## Acceptance Criteria

- [ ] No package contributes substantially more weight than the surface actually imported from it.
- [ ] Shared index files do not cause unrelated modules to be pulled into a bundle.
- [ ] Server-only code is verified absent from the browser bundle.
- [ ] Bundle size impact is reported on every proposed change during review.
- [ ] Modules with import-time side effects are identified and isolated.
- [ ] Content visible at first paint is not deferred behind lazy loading.
- [ ] The same dependency does not appear twice at different versions.
- [ ] The feature matches the existing design system.
- [ ] No existing functionality is broken.

## Adaptation Rules

- Match the existing design system. Do not introduce a new colour palette,
  spacing scale, or component library.
- Reuse existing components and utilities wherever they fit.
- Follow the naming, file layout, and code style already present.
- Do not upgrade, replace, or remove existing dependencies to make this
  feature fit. Adapt the feature to the app, not the app to the feature.
- Do not break existing functionality. If a change is genuinely required in
  existing code, make the smallest one that works and say so.
- If something in these instructions conflicts with how the application is
  built, follow the application and explain the deviation.

## Final Verification

Before you report the work as done:

1. Re-read the acceptance criteria above and check each one against what you
   actually built.
2. Run the application and exercise the feature end to end.
3. Run the existing test suite and confirm you have broken nothing.
4. Check the feature on mobile, tablet, and desktop widths.
5. Check keyboard navigation and focus handling.
6. Summarize what changed: files added, files modified, and anything you
   deliberately did differently because of how this application is built.

If any acceptance criterion is unmet, fix it before reporting completion.