Structure A Shared Ui Lib

Structure a shared UI library

A design-system package (placeholder @org/web-ui) that multiple apps depend on for components, hooks, utils, the data/state primitives, and theme tokens. Examples are React/TS over a base component library (e.g. Ant Design); each rule is principle → ▸ Example → ▸ Other stacks. Apps that consume this lib follow structure-a-frontend-app / write-frontend-code.

Core principle

The lib is the single source of truth for UI + shared primitives — apps import from it, never re-implement. It ships subpath entry points (/store, /queries, /utils, /theme/, …) so apps pull only what they need, and it lets old and new versions of a component coexist so a redesign never forces a big-bang migration.

1. src/ layout (built to lib/)

▸ Example:

src/
├── components/      # folder-per-component (the bulk) — see §2
├── store/           # Zustand wrapper consumed as @org/web-ui/store (createStore + query helpers)
├── queries/         # React Query wrapper: useQuery / useMutationData / useInfiniteDataQuery / provider
├── hooks/           # shared React hooks + index barrel
├── utils/           # pure *.util.ts (date/currency/string/array/csv/...) + co-located *.test.ts
├── theme/           # versioned design tokens: core, v1, v1_1, v7 — see §4
├── icons/  charts/  # icon set, chart wrappers
├── hoc/  providers/ # higher-order components, context providers
├── models/ types/ enums/ constants/   # shared TS contracts
├── services/        # shared API clients used across apps
├── stories/         # Storybook
└── index.ts         # main barrel

Source lives in src/; a build step compiles it to lib/ (what apps import). ▸ Other stacks: one package, organized by capability, built to a dist/ consumers import.

2. Component organization

• Folder-per-component, flat (no atomic-design atoms/molecules layering). Each folder:

`` components/Button2/ ├── Button.tsx # forwardRef, typed props ├── Button.less # BEM-scoped classes (e.g. ui-button-v2__primary--small) └── index.ts # barrel: export { Button, ButtonProps } ``

• Every component's props extend a shared base for test/observability hooks — e.g. a

CustomAttributeProps carrying data-test-id + privacy/analytics data-attributes — plus AriaAttributes.

• Version coexistence for redesigns. A breaking restyle ships as a NEW component beside the old

(Button → Button2 → Button3); apps migrate per-usage during a deprecation grace period instead of all at once. Mark the old one deprecated; delete it once no app imports it. ▸ Other stacks: folder-per-component + a versioned name (or major-version export path) for breaking redesigns.

3. Shared runtime wrappers (the lib owns these; apps consume them)

The lib wraps the state/data libraries ONCE so every app uses the same configured primitive:

• createStore (Zustand wrapper): createStore(stateCreator, { storeName, enabledDevTools? })

→ [useBoundStore, selector]. Devtools dev-only; persist middleware optional. Apps build feature stores on this (see write-frontend-code §3).

• Query wrapper (React Query): useQuery(key, fn, options?), useMutationData,

useInfiniteDataQuery, and the QueryClientProvider with the org's default config. Normalizes quirks (e.g. a select returning undefined → original data).

• Utils namespace (pure, no React): default export `{ DateUtil, CurrencyUtil, StringUtil,

CommonUtil, FileUtil, CsvUtil, ... }; CommonUtil` re-exports the lodash functions the org uses so apps import them from one place. Each util is unit-tested in the lib. ▸ Other stacks: the shared lib centralizes the data/state/util choices; apps don't import the raw libraries.

4. Design tokens — versioned, generated, not hand-edited

• Tokens are versioned folders (theme/v1, v1_1, v7, core); a new visual language is a new

version, exported separately, so existing apps don't break.

• Generated from a source-of-truth JSON, not hand-written:

`` theme/v1_1/ ├── tokens.json # SOURCE (color ramps, spacing, radius, typography, shadows) ├── _variables.js # AUTO-GENERATED token getters (colorNeutral50, spacingSmall, ...) ├── _variables.css # AUTO-GENERATED CSS custom properties └── index.ts # getColorPalettes('Neutral'), getSpacings(), getRadiuses(), getSemanticTokens() ` Pipeline: Figma → a tokens transform (Tokens Studio / Style Dictionary) → JSON → JS + CSS (a tokens:build script). Edit tokens.json (or Figma) and regenerate — **never edit _variables.`*.

• Apps consume via the token getters + the theme/Tailwind preset (see write-frontend-code §7); they

never hard-code hex. ▸ Other stacks: tokens JSON → generated CSS vars / platform files — same "design source → generated, versioned" idea.

5. Public API — subpath entry points

• The build emits many small entry points to lib/ so apps import only what they use:

@org/web-ui (components + main), /store, /queries, /utils, /hooks, /theme/, /charts, /models, /constants, /enums, /services. ``ts import { Button, Modal } from '@org/web-ui'; import { useQuery } from '@org/web-ui/queries'; import Utils from '@org/web-ui/utils'; import { createStore } from '@org/web-ui/store'; import { theme } from '@org/web-ui/theme/v1_1'; ``

• Built as UMD + emitted .d.ts (works via ESM, CommonJS, and a global script). ▸ Other stacks: a

package exports map / multiple entry points so consumers tree-shake to what they need.

6. Storybook + tests

• Storybook is the dev surface + living docs: src/**/*.stories.tsx auto-discovered;

visual-regression (e.g. Chromatic) gates UI changes.

• Pure utils are unit-tested (Jest + Testing Library, co-located *.test.ts); components are

exercised through Storybook + visual regression rather than heavy render unit tests.

7. Versioning & consumption

• Semver the package. Components version by coexistence (§2); theme versions are separate

entry points (§4) — both let apps adopt incrementally.

• Apps consume the built lib via the package registry, OR vendored at a pinned branch/tag (e.g. a

meta git checkout into the app's libs/), so every app runs a known version. Bump deliberately. ▸ Other stacks: publish to your registry or pin a submodule/vendored copy; one shared version per app.

Verification

• src/ is split by capability (components, store, queries, hooks, utils, theme, icons, …); source in

src/, shipped from lib/.

• Components are folder-per-component (.tsx + styles + index.ts), props extend the shared

base, and a redesigned component coexists under a new name rather than mutating the old.

• The lib exposes state/query/utils primitives via subpaths; apps import those, not the raw libs.
• Theme tokens live in versioned folders, generated from a source JSON (the _variables.* are not

hand-edited).

• Storybook stories exist for components; pure utils have unit tests.

Related

• structure-a-frontend-app / write-frontend-code — the apps that consume this library.
• code-conventions — general code style.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: kennguyen887
• Source: kennguyen887/agent-foundation
• License: MIT

Install and usage instructions live in the source repository linked above.