Packages and boundaries
One public package with twenty-two private modules, explicit ownership and one-way dependencies.
One package and explicit imports
Consumers install one package, @fayegram-ai/faye-ui, and import its public subpaths. Component families are public subpaths within that package. Consumers do not need source repository access. See installation for npm instructions and the current publication status.
Dependency direction
Contracts are framework-independent. Tokens declare names and types. Theme resolves and validates values. Styles compiles portable component sheets. Static core and layout primitives do not require React client context.
Provider owns preferences and environment transport. Component-family packages consume that environment and Base UI where needed. Patterns combine public components but do not introduce remote data ownership.
The optional runtime-styles and nextjs packages provide dynamic stylesheet collection and framework insertion. Developer tools and the example extension are separate from the core graph.
Maintainability rules
A package may depend on lower-level contracts, not a global component registry. Private helpers are not consumer contracts. Component parts, variant attributes, token meanings and rendering boundaries are versioned interfaces.
The API index and component reference are generated from declarations and component contracts. Documentation tooling is not required by application components.
Data extensions
A plain table is core presentation. Sorting, fetching, row models, virtualization, charts, calendars and editors belong in separate extensions when they require an engine. TablePagination owns no records; its state is supplied by the application.
Rendering classification
Static primitives can execute in a Server Component. Interactive components are Client Components and may still produce server-rendered initial HTML. A client provider cannot change the already-executed logic of a Server Component.
Artwork boundaries
@lucide/icons@1.52.0 supplies raw upstream data. @fayegram-ai/faye-ui/icons provides an independently imported organization artwork module inside the single UI package. That module has no React, DOM, CSS, UI-runtime or Lucide imports. @fayegram-ai/faye-ui/contracts/icon owns portable definitions and validation. @fayegram-ai/faye-ui/core/icon imports neither collection; components and applications import only their chosen artwork. The foundations chapter includes executable examples and the authoring procedure.