186 Shared components package

.github/PULL_REQUEST_TEMPLATE.md

@@ -22,7 +22,6 @@ _Pull request authors must complete the following tasks before marking the PR as
 - [ ] Complete a self-review of changes
 - [ ] Unit tests have been created or updated
 - [ ] The code is free of [new] lint errors and warnings
-- [ ] Update storybook stories as needed
 - [ ] Update project documentation as needed, README, JSDoc, etc.
 
 ### :test_tube: Steps to Test

.github/workflows/ci.yml

@@ -57,11 +57,6 @@ jobs:
       - name: Run unit tests
         run: npm run test:coverage
 
-      # --- Web Package Checks ---
-      # --- Storybook Checks ---
-      - name: Build Storybook
-        run: npm run build:storybook -w packages/web
-
       # --- Infrastructure Package Checks ---
       - name: Configure AWS credentials
         uses: aws-actions/configure-aws-credentials@v6
@@ -80,7 +75,6 @@ jobs:
           echo "🧹 Cleaning up sensitive files..."
           rm -f packages/web/.env
           rm -rf packages/web/dist
-          rm -rf packages/web/storybook-static
           rm -f packages/infra/.env
           rm -rf packages/infra/dist
           rm -rf packages/infra/cdk.out

.github/workflows/deploy-reusable.yml

@@ -66,9 +66,6 @@ jobs:
       - name: Build the app
         run: npm run build
 
-      - name: Build storybook
-        run: npm run build:storybook -w packages/web
-
       - name: Configure AWS credentials
         uses: aws-actions/configure-aws-credentials@v6
         with:
@@ -100,7 +97,6 @@ jobs:
           echo "🧹 Cleaning up sensitive files..."
           rm -f packages/web/.env
           rm -rf packages/web/dist
-          rm -rf packages/web/storybook-static
           rm -f packages/infra/.env
           rm -rf packages/infra/dist
           rm -rf packages/infra/cdk.out

.gitignore

@@ -33,10 +33,6 @@ __snapshots__
 *.sln
 *.sw?
 
-# Storybook
-storybook-static
-*storybook.log
-
 # dotenv environment variable files
 .env*
 !.env.example

AGENTS.md

@@ -59,8 +59,9 @@ Definition of Done)       coverage floors)         or unified scripts)
 │   │   ├── src/
 │   │   │   ├── components/         # Reusable UI components
 │   │   │   │   └── shadcn/         # Atomic shadcn/ui components (DO NOT modify internals)
-│   │   │   ├── models/             # Unified Type & Interface definitions (e.g., Task.ts)
-│   │   │   ├── schemas/            # Common Zod verification schemas
+│   │   │   ├── hooks/              # Reusable React hooks
+│   │   │   ├── types/              # Unified Type & Interface definitions (e.g., Task.ts) and Zod schemas
+│   │   │   ├── stypes/             # Common CSS styles
 │   │   │   └── utils/              # Universal helper functions
 │   │   ├── package.json
 │   │   └── tsconfig.json
@@ -80,7 +81,7 @@ Definition of Done)       coverage floors)         or unified scripts)
 │       │   │       ├── delete/
 │       │   │       ├── hooks/      # Feature-isolated API/State hooks (e.g., useGetTasks.ts)
 │       │   │       └── utils/      # Feature-isolated pure utility logic
-│       │   ├── globals.css         # Global styles and Tailwind variables
+│       │   ├── index.css           # App-specific CSS styles which extend the shared global styles (optional)
 │       │   └── main.tsx            # Web application entrypoint
 │       ├── package.json
 │       └── tsconfig.json
@@ -105,19 +106,19 @@ Definition of Done)       coverage floors)         or unified scripts)
 
 You are authorized to execute the following shell commands to validate your work. Do not use unlisted tools, invent flags, or circumvent the root workspace manager.
 
-| Task                     | Command                                                               | Scope                                       |
-| ------------------------ | --------------------------------------------------------------------- | ------------------------------------------- |
-| **Install Dependencies** | `npm install`                                                         | Root Project (Updates lockfile)             |
-| **Scoped Installation**  | `npm install <package> -w <workspace-name>`                           | Installs dependency into specific package   |
-| **Run All Unit Tests**   | `npm test --workspaces`                                               | Comprehensive Repo Testing (Vitest)         |
-| **Run Frontend Tests**   | `npm run test -w packages/web` or `npm run test -w @monorepo/web`     | Frontend Component/Hook Validation          |
-| **Run API Lambda Tests** | `npm run test -w packages/api` or `npm run test -w @monorepo/api`     | Lambda Handler Validation                   |
-| **Run Infra Tests**      | `npm run test -w packages/infra` or `npm run test -w @monorepo/infra` | Infrastructure Stack Validation             |
-| **Check Code Coverage**  | `npm run test:coverage --workspaces`                                  | Global Multi-Package Coverage Review        |
-| **Lint Entire Codebase** | `npm run lint`                                                        | Full Monorepo Linting & Formatting Analysis |
-| **Format Code**          | `npx run format`                                                      | Global Prettier/Formatter execution         |
-| **Add shadcn Component** | `npx shadcn@latest add [component]`                                   | Executed inside `packages/shared` directory |
-| **CDK Synthesize**       | `npm run cdk synth -w packages/infra`                                 | AWS CDK Infrastructure Validation           |
+| Task                     | Command                                                                      | Scope                                       |
+| ------------------------ | ---------------------------------------------------------------------------- | ------------------------------------------- |
+| **Install Dependencies** | `npm install`                                                                | Root Project (Updates lockfile)             |
+| **Scoped Installation**  | `npm install <package> -w <workspace-name>`                                  | Installs dependency into specific package   |
+| **Run All Unit Tests**   | `npm test --workspaces`                                                      | Comprehensive Repo Testing (Vitest)         |
+| **Run Frontend Tests**   | `npm run test -w packages/web` or `npm run test -w @react-starter/web`       | Frontend Component/Hook Validation          |
+| **Run API Lambda Tests** | `npm run test -w packages/shared` or `npm run test -w @react-starter/shared` | Shared UI components, hooks, utils, etc.    |
+| **Run Infra Tests**      | `npm run test -w packages/infra` or `npm run test -w @react-starter/infra`   | Infrastructure Stack Validation             |
+| **Check Code Coverage**  | `npm run test:coverage --workspaces`                                         | Global Multi-Package Coverage Review        |
+| **Lint Entire Codebase** | `npm run lint`                                                               | Full Monorepo Linting & Formatting Analysis |
+| **Format Code**          | `npx run format`                                                             | Global Prettier/Formatter execution         |
+| **Add shadcn Component** | `npx shadcn@latest add [component]`                                          | Executed inside `packages/shared` directory |
+| **CDK Synthesize**       | `npm run cdk synth -w packages/infra`                                        | AWS CDK Infrastructure Validation           |
 
 ---
 
@@ -138,21 +139,22 @@ You are authorized to execute the following shell commands to validate your work
 - **PascalCase for React Components:** React component files must use `PascalCase`. Example: `TaskCard.tsx`, `SearchForm.tsx`, `Modal.tsx`.
 - **Test File Colocation:** Test files follow the same naming convention as their source file, with `.test` suffix. Example: `document.test.ts`, `useGetTasks.test.ts`, `TaskCard.test.tsx`.
 
-### Frontend React Component Layout (`packages/web`)
+### Web Package Standards (`packages/web`)
 
 - Write components as **Arrow Functions** using explicit functional component patterns (`const MyComponent: React.FC<Props> = ...`).
-- Always use **Default Exports** for page components and standard UI components.
+- Use `export default` for page components to support lazy loading. Use plain `export` for standard UI components.
 - Enforce code splitting by leveraging route-level `lazy()` and `Suspense` operations in routing definitions.
 - **Component Testing Hooks:** Always inject a `data-testid` attribute or accept a `testId` prop on components to ensure reliable test selection. The `testId` prop must default to the component's name written in `kebab-case`.
-- **Styling & UI Systems (shadcn/ui & Tailwind):** Use **Tailwind CSS** classes natively. Apply thematic alterations through CSS variables via `packages/web/src/index.css`. Use `class-variance-authority` (CVA) within `packages/web/src/common/utils/css.ts` when handling multi-variant components.
-- **shadcn Rule:** Never modify underlying code files inside `packages/web/src/common/components/shadcn/` by hand. If behavior adjustments are required, write a wrapper component around them. Scaffold new ones using the authorized CLI command.
+- **Styling & UI Systems (shadcn/ui & Tailwind):** Use **Tailwind CSS** classes natively. Apply thematic alterations through CSS variables via `packages/web/src/index.css`. Use `class-variance-authority` (CVA) within `packages/shared/src/utils/css.ts` when handling multi-variant components.
 
-### Shared Workspace Standards (`packages/shared`)
+### Shared UI Package Standards (`packages/shared`)
 
 - **Single Source of Truth:** Place common structural interfaces, data models, and Zod validation schemas inside this package so they can be consumed symmetrically by `packages/web` (frontend forms/state) and future packages.
+- **shadcn Rule:** Never modify underlying code files inside `packages/shared/src/components/shadcn/` by hand. If behavior adjustments are required, write a wrapper component around them. Scaffold new ones using the authorized CLI command.
 - **Environment Agnosticism:** Code within `packages/shared` must be pure and free of browser-specific (`window`, `document`) or Node.js runtime-specific (`process.env`) assumptions unless strictly isolated into explicit type contexts.
+- **Styling & UI Systems (shadcn/ui & Tailwind):** Use **Tailwind CSS** classes natively. Apply thematic alterations through CSS variables via `packages/shared/src/styles/global.css`. Use `class-variance-authority` (CVA) within `packages/shared/src/utils/css.ts` when handling multi-variant components.
 
-### Infrastructure (`packages/infra`)
+### Infrastructure Package Standards (`packages/infra`)
 
 - **AWS CDK Isolation:** Keep the `packages/infra/` directory entirely decoupled from front-end runtime mechanics and backend business logic. It reads built lambda artifacts or source file paths but does not execute backend logic.
 - **Configuration Security:** Use **dotenv** in conjunction with **Zod** to rigorously validate infrastructure environment configurations and parameters prefixed with `CDK_`.

README.md

@@ -11,6 +11,10 @@ A serverless, progressive, responsive starter user interface (UI) with React at
 
 This project is licensed under the MIT License - see [LICENSE](./LICENSE) file for details.
 
+## Learn About This Project
+
+**New to this project?** Start with the [Project Overview](docs/OVERVIEW.md) — a comprehensive guide to the architecture, features, technology stack, and how to get started developing.
+
 ## Documentation
 
 For detailed guides and reference materials, see the [Project Documentation](docs/README.md).
@@ -101,7 +105,7 @@ When using the application, you may sign in with any of the JSON Placeholder [Us
 
 - **Vitest** as the core unit testing framework with V8 code coverage support
 - **React Testing Library** for user-centric component testing (prefer testing behaviors over implementation)
-- **Mock Service Worker (MSW)** for seamless API mocking in both tests and Storybook
+- **Mock Service Worker (MSW)** for seamless API mocking in tests
 - **Co-located test files** (`.test.ts`, `.test.tsx`) adjacent to source for easy maintenance and discovery
 - **80% minimum code coverage** requirement ensuring testability and reliability
 - **Test utilities and helpers** (`test-utils.tsx`) for consistent test setup and common operations
@@ -118,7 +122,6 @@ When using the application, you may sign in with any of the JSON Placeholder [Us
 
 ### Documentation & Developer Experience
 
-- **Storybook UI** for isolated component development, documentation, and visual testing
 - **Inline code comments** explaining complex logic and architectural decisions
 - **Project documentation** guides covering configuration, infrastructure, shadcn/ui setup, and more
 - **Type definitions** and JSDoc comments for better IDE intellisense and developer handoff
@@ -161,14 +164,12 @@ The application development technology stack includes:
 - Vitest - core unit test framework
 - React Testing Library - user-centric UI component testing
 - Mock Service Worker - API mocking
-- Storybook - UI component visualization and documentation
 - TypeScript - the TypeScript language
 
 The infrastructure technology stack includes:
 
 - AWS CDK - framework for provisioning AWS cloud infrastructure
 - Zod - schema based validation
-- Jest: unit test framework
 
 ### Repository
 
@@ -228,9 +229,13 @@ Infrastructure provisioning and deployment automation using AWS CDK. This packag
 
 ### Workspace Dependencies
 
-```
-web ──→ shared
-infra ──→ shared
+```mermaid
+---
+title: Package Dependencies
+---
+flowchart TD
+  web --- shared
+  infra --- shared
 ```
 
 The `web` and `infra` packages both depend on `shared` for common types and schemas, but maintain independence from each other. This architecture enables parallel development, independent testing, and clear separation of concerns across frontend and infrastructure concerns.
@@ -239,58 +244,7 @@ See [AGENTS.md](./AGENTS.md) for comprehensive architectural guidelines, coding
 
 ## Installation
 
-### Prerequistes
-
-It is strongly recommended that you install Node Version Manager, [`nvm`][nvm]. Node Version Manager simplifies working on multiple projects with different versions of Node.js.
-
-### Clone the Repository
-
-Open the [repository][repo] in a browser. Follow the instructions to clone the repository to your local machine.
-
-### Install Node
-
-Open a terminal window and navigate to the project base directory. Issue the following command to install the version of Node and NPM used by the application:
-
-```bash
-# If you already have this version of Node, simply switch to it...
-nvm use
-
-# If you do NOT have this version of Node, install it...
-nvm install
-```
-
-Node Version Manager inspects the `.nvmrc` file in the project base directory and uses or installs the specified version of Node and the Node Package Manager, npm.
-
-### Install the Dependencies
-
-To install the project dependencies, issue the following commands at a terminal prompt in the project base directory:
-
-```bash
-# Switch to the project node version...
-nvm use
-
-# Install project dependencies
-npm install
-```
-
-### After Installation
-
-The installation is now complete! You may open the project in your favorite source code editor (we recommend [Visual Studio Code](https://code.visualstudio.com/)).
-
-We recommend the following VS Code extensions:
-
-- Prettier - Code formatter (required)
-- Tailwind CSS IntelliSense (required)
-- GitHub Copilot (recommended)
-- ESLint (recommended)
-- Indent Rainbow (optional)
-- GitLens (optional)
-- Dotenv Official +Vault (optional)
-- GitHub Actions (optional)
-
-Install the _Prettier_ extension to ensure that all project participants' contributions are formatted using the same rules. The extension leverages project-specific rules found in the `.prettierrc` file in the project base directory.
-
-The _Tailwind CSS IntelliSense_ extension is a must-have companion in all projects using Tailwind. The extension ensures that Tailwind CSS classes are named and ordered correctly and flags any conflicting classes.
+For detailed instructions to install and run this project on your local machine, see the [Local Setup Guide](./docs/LOCAL_SETUP.md).
 
 ## Configuration
 
@@ -340,14 +294,6 @@ Open [http://localhost:5173](http://localhost:5173) to view it in the browser.
 
 The page will reload when source files are saved.
 
-### `npm run storybook -w packages/web`
-
-Starts the [Storybook][storybook] UI. Open [http://localhost:6006](http://localhost:6006) to view it in the browser.
-
-### `npm run build:storybook -w packages/web`
-
-Build a static version the [Storybook][storybook] UI which may be deployed to a CDN or HTTP server.
-
 ## Further Reading
 
 - [Project Documentation](./docs/README.md)
@@ -367,7 +313,6 @@ Build a static version the [Storybook][storybook] UI which may be deployed to a
 - [React i18next][reacti18next]
 - [Recharts][recharts]
 - [React Testing Library][testing-library]
-- [Storybook][storybook]
 - [GitHub Actions][ghactions]
 
 [app]: https://react-starter.leanstacks.net/ 'React Starter Kit | LeanStacks'
@@ -388,6 +333,5 @@ Build a static version the [Storybook][storybook] UI which may be deployed to a
 [ghactions]: https://docs.github.com/en/actions 'GitHub Actions'
 [reacti18next]: https://react.i18next.com/ 'React i18next'
 [reactspring]: https://www.react-spring.dev/ 'React Spring'
-[storybook]: https://storybook.js.org/ 'Storybook'
 [recharts]: https://recharts.org/ 'Recharts'
 [zod]: https://zod.dev/ 'Zod'