structure-a-shared-ui-liblisted

# 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/<v>`, …) 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 ├─