@muskanmeet/invoicing-design-system 0.1.0

package/.local/tasks/task-1.md

@@ -0,0 +1,42 @@
+---
+title: Invoicing design system & screens (Next.js + shadcn)
+---
+### Invoicing Design System & Screens (Next.js + shadcn)
+
+## What & Why
+Scaffold a Next.js + TypeScript project for the UI/UX designer to define the design system, breakpoints, shadcn-based components, and final invoicing screens (Dashboard, Invoices list, Auth). The codebase is structured so the design system lives in an internal folder that can later be extracted and published as an npm package, while final screens stay in this repo for developers to pull via GitHub. Frontend-only — no Next.js server features (API routes, server actions, server-only data fetching) will be used.
+
+## Done looks like
+- A running Next.js (App Router) + TypeScript app the designer can open and navigate.
+- A `design-system/` folder containing:
+  - Design tokens (colors, typography, spacing, radii, shadows) in a "Modern SaaS — subtle color accents, rounded, friendly" direction.
+  - Defined responsive breakpoints (mobile / tablet / desktop / wide) used consistently via Tailwind.
+  - shadcn/ui set up and themed so all shadcn components inherit the custom look.
+  - A baseline set of components (Button, Input, Select, Textarea, Checkbox, Radio, Switch, Badge, Card, Avatar, Dialog, DropdownMenu, Tabs, Table, Toast, Tooltip, Form fields).
+  - A `/design-system` route in the app that previews tokens, breakpoints, and every component with their variants/states (a living styleguide).
+- Folder structure that keeps the design system self-contained (no imports from screens into it) so it can be lifted into its own npm package later with minimal changes.
+- Final invoicing screens implemented as pure client components consuming the design system:
+  - Dashboard (KPIs, recent activity, charts placeholders)
+  - Invoices list (filterable/sortable table with status badges, pagination)
+  - Auth — Login and Signup screens
+- Screens are consumable by downstream developers in both a Next.js app and a plain TypeScript/React app (no Next.js-only APIs such as `next/headers`, server components with server data, or route handlers used inside screens — `next/link` and `next/image` are wrapped or kept optional).
+- A short README explaining: how to run the app, where the design system lives, how it will be extracted to npm later, and how to consume the screens from the repo.
+
+## Out of scope
+- Publishing the npm package now (structure-only; publishing happens later).
+- Backend, database, auth logic, or real API integration — screens use mock/static data.
+- Remaining screens (Invoice detail, Create/edit, Clients, Products, Payments, Settings) — can be added in follow-up tasks.
+- Monorepo / pnpm workspace setup (explicitly rejected — single app with internal folder).
+- Storybook (the `/design-system` preview route serves this role for now).
+
+## Steps
+1. **Project scaffold** — Create a Next.js App Router project with TypeScript, Tailwind CSS, ESLint, and strict mode. Configure it as a frontend-only app (no API routes, no server data fetching in screens).
+2. **shadcn/ui setup** — Initialize shadcn/ui with a custom theme that reflects the Modern SaaS direction (rounded radii, subtle accent color, friendly typography). Add the baseline components listed above.
+3. **Design tokens & breakpoints** — Define tokens (colors, typography scale, spacing, radii, shadows, z-index) and responsive breakpoints in the Tailwind config and as CSS variables so they're consumable outside Tailwind too.
+4. **Design-system folder structure** — Create a self-contained `design-system/` folder with `tokens/`, `components/`, `hooks/`, `lib/`, and a clean public `index.ts` barrel. Enforce no inbound imports from screens; configure path alias `@ds/*`.
+5. **Styleguide preview route** — Build a `/design-system` route in the app that renders token swatches, breakpoint demos, and every component with all variants and states for the designer to iterate on.
+6. **Invoicing screens** — Build Dashboard, Invoices list, Login, and Signup as client components under `app/(screens)/` consuming only `@ds/*`. Use mock data. Ensure none rely on Next.js server-only APIs so they're portable to a plain React/TS app.
+7. **Portability check & README** — Add a README explaining structure, how to run, the future npm-extraction plan for `design-system/`, and how developers consume the screens. Note any caveats (e.g., `next/link` usage and how to swap it).
+
+## Relevant files
+- None yet — this is a greenfield scaffold.

package/.local/tasks/task-7.md

@@ -0,0 +1,92 @@
+---
+title: Add Breadcrumb to design system + screens
+---
+# Add Breadcrumb component to design system
+
+## What & Why
+Add the shadcn `Breadcrumb` component to the `design-system/` package so screens can
+show navigation trails. It must follow the same architectural conventions as the
+other DS components (semantic tokens only, typed props, exported through the
+top-level barrel) so it ships cleanly when the package is extracted to npm.
+Demonstrate it on the Dashboard and Invoices screens.
+
+## Done looks like
+- A new "Breadcrumbs" section appears in `/design-system` showing: a default
+  breadcrumb, a breadcrumb with a custom separator (e.g. dot), a truncated
+  breadcrumb using `BreadcrumbEllipsis`, and a breadcrumb where the current page
+  is a dropdown trigger.
+- The Dashboard screen renders `Home / Dashboard` above its page title.
+- The Invoices screen renders `Home / Invoices` above its page title (and the
+  invoice-detail variant, if one exists, renders `Home / Invoices / INV-xxxx`).
+- Importing from `@ds` (the barrel) exposes all breadcrumb parts:
+  `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`,
+  `BreadcrumbPage`, `BreadcrumbSeparator`, `BreadcrumbEllipsis`.
+- Hover, current-page, focus-visible, and chevron colors all resolve through
+  semantic tokens (`text-muted-foreground`, `text-foreground`, `ring`, etc.) —
+  no hex/HSL literals in the component file.
+- Typography uses the existing semantic scale (`text-body-sm` for the trail,
+  `text-body-md-em` or equivalent for the current page) rather than raw
+  Tailwind sizes.
+- `npm run build` and `npm run lint` pass.
+
+## Out of scope
+- A router-aware "auto-breadcrumb from pathname" helper. Screens declare their
+  own trail explicitly.
+- Mobile-specific drawer/sheet variant from the shadcn responsive example.
+- Any change to the existing palette / typography / spacing tokens.
+
+## Steps
+1. **Add the component file** — Port the official shadcn `breadcrumb.tsx` as a
+   new file in `design-system/components/`. Replace any raw Tailwind text-size
+   classes with the project's semantic typography classes; ensure every color
+   class is a semantic token (no hex/HSL). Use the same `forwardRef` + named
+   `displayName` pattern as the sibling components and the project's `cn`
+   helper from `design-system/lib/cn`. Add a small `cva` variants block only if
+   a real second variant is needed (e.g. `size: "sm" | "md"` for compact vs
+   default density) — otherwise keep it variant-free, like `Separator`.
+   Export every part plus any `*Props` types.
+2. **Wire the barrel export** — Add the new component to
+   `design-system/index.ts` so `@ds` consumers get it without reaching into
+   sub-paths.
+3. **Add styleguide preview** — Add a `Breadcrumbs` section to the design-system
+   page (and a nav chip linking to it) showing the four states listed in "Done
+   looks like". Each example should be wrapped in a card body, like the other
+   sections.
+4. **Use it on the screens** — Render a breadcrumb above the page title on the
+   Dashboard and Invoices screens. Use `next/link` via `asChild` so the
+   breadcrumb links participate in Next.js client-side navigation.
+5. **Verify** — Run `npm run lint` and `npm run build`; visually confirm the
+   styleguide section and both screens.
+
+### Token / file impact (so the user knows where edits land)
+- **New component file:** `design-system/components/breadcrumb.tsx`
+- **Barrel export:** `design-system/index.ts`
+- **Styleguide preview:** `app/design-system/page.tsx` (new section + nav chip)
+- **Screen usage:** `screens/dashboard/dashboard-screen.tsx`,
+  `screens/invoices/invoices-screen.tsx` (or sibling header components if the
+  screens delegate their headers)
+- **Tokens — no change expected:** `design-system/tokens/tokens.ts`,
+  `design-system/tokens/tokens.css` should NOT be touched. The breadcrumb
+  consumes existing semantic roles (`muted-foreground`, `foreground`,
+  `accent`, `ring`).
+- **Global CSS — no change expected:** `design-system/styles.css` should NOT
+  be touched. All typography is via existing `.text-body-sm` /
+  `.text-body-md-em` classes already defined there.
+- If a real need surfaces during implementation (e.g. a separator-color role
+  that doesn't exist), add a new semantic token in `tokens.css` + `tokens.ts`
+  rather than hardcoding, and call it out in the merge summary.
+
+## Relevant files
+- `design-system/components/separator.tsx`
+- `design-system/components/button.tsx`
+- `design-system/components/tabs.tsx`
+- `design-system/index.ts`
+- `design-system/lib/cn.ts`
+- `design-system/styles.css`
+- `design-system/tokens/tokens.css`
+- `app/design-system/page.tsx`
+- `screens/dashboard/dashboard-screen.tsx`
+- `screens/invoices/invoices-screen.tsx`
+- `app/dashboard/page.tsx`
+- `app/invoices/page.tsx`
+- `package.json`

package/.local/tasks/task-8.md

@@ -0,0 +1,96 @@
+---
+title: Add Calendar (single + range date picker) to design system + screens
+---
+# Add Calendar (date picker) to design system + screens
+
+## What & Why
+The design system has no date input yet. The user wants a shadcn-based
+Calendar component that supports both single-date and date-range selection,
+uses only semantic tokens (so it themes for free in dark mode and can be
+extracted to npm without refactor), and is wired into the Dashboard and
+Invoices screens so the designer can see it in context.
+
+## Scope
+1. **Dependencies** — install `react-day-picker@^8` and `date-fns@^3`
+   (peer of react-day-picker). No other deps.
+2. **New DS primitive** — `design-system/components/calendar.tsx`, ported
+   from the official shadcn Calendar:
+   - `"use client"` directive (uses React state internally).
+   - Wraps `DayPicker` from `react-day-picker`.
+   - `forwardRef` + `displayName`, `cn` from `design-system/lib/cn`.
+   - **Semantic tokens only** — `bg-background`, `text-foreground`,
+     `bg-primary`, `text-primary-foreground`, `bg-muted`,
+     `text-muted-foreground`, `border-border`, `ring-ring`,
+     `bg-popover`, `text-popover-foreground`, `bg-accent`,
+     `text-accent-foreground`. **No hex / no HSL literals.**
+   - Uses existing `buttonVariants({ variant: "outline" / "ghost" })`
+     for nav + day cells so day-picker theming follows the Button.
+   - Exports `Calendar` plus `CalendarProps` (mirrors
+     `React.ComponentProps<typeof DayPicker>` so both `mode="single"`
+     and `mode="range"` work via discriminated union).
+3. **New DS composite** — `design-system/components/date-picker.tsx`:
+   - Popover-style trigger (uses existing `Button` + existing
+     `dropdown-menu` patterns OR a thin Popover; if a Popover primitive
+     doesn't exist yet, add `design-system/components/popover.tsx`
+     based on `@radix-ui/react-popover`).
+   - Two thin wrappers exported: `DatePicker` (single) and
+     `DateRangePicker` (range), both controlled + uncontrolled,
+     typed with `Date | undefined` and `DateRange | undefined`
+     respectively.
+   - Trigger renders formatted value via `date-fns/format` (`"LLL d, y"`
+     single; `"LLL d"` – `"LLL d, y"` range).
+4. **Barrel** — add `calendar`, `date-picker`, and (if added) `popover`
+   to `design-system/index.ts`.
+5. **Styleguide** — new `Calendar` section + nav chip in
+   `app/design-system/page.tsx` with four examples: single inline,
+   range inline, single via `DatePicker` trigger, range via
+   `DateRangePicker` trigger. Use semantic typography classes
+   (`text-body-md`, `text-body-sm`) for any helper copy.
+6. **Dashboard screen** — replace the static `7d / 30d / 90d` Tabs in
+   `screens/dashboard/dashboard-screen.tsx` with a `DateRangePicker`
+   (default = last 30 days). Keep the existing `New invoice` button next
+   to it. KPI/chart copy can stay static.
+7. **Invoices screen** — add a `DateRangePicker` to the filter bar in
+   `screens/invoices/invoices-screen.tsx`, alongside the existing
+   search + status select. Wire it to filter the `allInvoices` array
+   by `issued` (compare via `date-fns`; treat the existing
+   "May 22" / "Jun 21" strings by parsing with current year — keep
+   the in-memory model the simplest change).
+
+## Out of scope
+- Time picker / clock.
+- Localisation beyond default (`en-US`).
+- Touching `tokens.ts` / `tokens.css` / `styles.css` (semantic vars
+  already cover everything Calendar needs).
+- Anything related to npm packaging (covered by #5 / #6).
+
+## Constraints
+- Components must keep zero hex / HSL literals — designer rule.
+- All new files live under `design-system/` so future npm extraction
+  is a folder move, no refactor.
+- Dark mode must work via the existing `.dark` class on `<html>` —
+  verified by toggling and inspecting the rendered calendar.
+
+## Acceptance
+- `/design-system` page shows the new `Calendar` section with all four
+  examples and the nav chip.
+- Dashboard renders a date-range picker in the header; clicking it
+  opens an inline calendar; selecting a range closes the popover and
+  shows the formatted range on the trigger.
+- Invoices renders a date-range picker in the filter bar; selecting
+  a range filters the table rows accordingly.
+- `npm run lint` passes with no warnings.
+- `npm run build` succeeds.
+- No new hex / HSL appears under `design-system/` or `screens/`
+  (grep clean).
+
+## Relevant files
+- `design-system/components/calendar.tsx` (new)
+- `design-system/components/date-picker.tsx` (new)
+- `design-system/components/popover.tsx` (new — only if not present)
+- `design-system/components/button.tsx` (consumed via `buttonVariants`)
+- `design-system/index.ts`
+- `app/design-system/page.tsx`
+- `screens/dashboard/dashboard-screen.tsx`
+- `screens/invoices/invoices-screen.tsx`
+- `package.json` (deps)

package/.replit

@@ -0,0 +1,34 @@
+modules = ["nodejs-20", "python-3.11"]
+[agent]
+expertMode = true
+
+[nix]
+channel = "stable-25_05"
+
+[workflows]
+runButton = "Project"
+
+[[workflows.workflow]]
+name = "Project"
+mode = "parallel"
+author = "agent"
+
+[[workflows.workflow.tasks]]
+task = "workflow.run"
+args = "Start application"
+
+[[workflows.workflow]]
+name = "Start application"
+author = "agent"
+
+[[workflows.workflow.tasks]]
+task = "shell.exec"
+args = "npm run dev"
+waitForPort = 5000
+
+[workflows.workflow.metadata]
+outputType = "webview"
+
+[[ports]]
+localPort = 5000
+externalPort = 80

package/.upm/store.json

@@ -0,0 +1 @@
+{"version":2,"languages":{"nodejs-npm":{"specfileHash":"b710899450236d21504df37a57641b09","lockfileHash":"9f7b766224b12209dc6f688819be002a"}}}

package/README.md

@@ -0,0 +1,121 @@
+# Invoicing System — Design Reference
+
+A Next.js + TypeScript reference project for the **Invoicing System** initiative.
+It owns the design system, breakpoints, shadcn-based components, and the final
+screens the development team will consume.
+
+> Frontend-only. No Next.js server features (API routes, server actions,
+> server-only data fetching) are used. The app exists purely to design, preview,
+> and hand off UI.
+
+## Quick start
+
+```bash
+npm install
+npm run dev
+```
+
+Open <http://localhost:5000>.
+
+## Routes
+
+| Route             | What it is                                                      |
+| ----------------- | --------------------------------------------------------------- |
+| `/`               | Index of everything in this repo                                |
+| `/design-system`  | Living styleguide — tokens, breakpoints, every component        |
+| `/dashboard`      | Final screen: dashboard with KPIs, activity, recent invoices    |
+| `/invoices`       | Final screen: filterable, sortable invoice list with pagination |
+| `/login`          | Final screen: login                                             |
+| `/signup`         | Final screen: signup                                            |
+
+## Repo layout
+
+```
+app/                  → Next.js App Router (preview pages only)
+design-system/        → THE design system (future npm package)
+  tokens/             → Design tokens (TS + CSS variables)
+  components/         → shadcn-based components, custom-themed
+  lib/                → Utilities (e.g. cn())
+  styles.css          → Tailwind entry + token import
+  index.ts            → Public barrel — import only from here
+screens/              → Final invoicing screens (consumed via GitHub)
+  _shared/            → Shell layout shared across screens
+  dashboard/          → DashboardScreen
+  invoices/           → InvoicesScreen
+  auth/               → AuthScreen (login + signup)
+  index.ts            → Public barrel
+```
+
+Path aliases:
+
+- `@ds/*` → `design-system/*`
+- `@screens/*` → `screens/*`
+
+## Design system
+
+Built on top of **shadcn/ui** primitives (Radix + Tailwind) with a custom
+"Modern SaaS" theme: subtle indigo accent, rounded radii, friendly Inter
+typography. All colors are HSL CSS variables (`--ds-*`), so retinting the
+system requires changing tokens only — no component edits.
+
+Breakpoints (Tailwind `screens`):
+
+| Token | Min width | Target          |
+| ----- | --------- | --------------- |
+| sm    | 480px     | Large phones    |
+| md    | 768px     | Tablets         |
+| lg    | 1024px    | Small laptops   |
+| xl    | 1280px    | Desktops        |
+| 2xl   | 1536px    | Wide displays   |
+
+### Future: extract `design-system/` to an npm package
+
+The folder is intentionally **self-contained**:
+
+- Has its own `tokens/`, `lib/`, `components/`, `styles.css`, and `index.ts`.
+- Has **no inbound imports** from `app/` or `screens/`.
+- Uses only `clsx`, `tailwind-merge`, `class-variance-authority`, `lucide-react`,
+  and `@radix-ui/*` — all standard, framework-agnostic.
+
+To publish later:
+
+1. Move `design-system/` to its own repo (e.g. `@yourteam/invoicing-ui`).
+2. Add a `package.json` with the same Radix / Tailwind peer deps.
+3. Move the matching parts of `tailwind.config.ts` into a preset the consumer
+   extends, and ship `styles.css` + `tokens.css` as the CSS entrypoint.
+4. Publish. Consumers do `import { Button } from "@yourteam/invoicing-ui"`.
+
+This project consumes the design system via the `@ds/*` alias today — after
+extraction, switching to the published package is a find-and-replace.
+
+## Final screens (for developers)
+
+The `screens/` folder is what your developers will pull from this GitHub repo.
+Each screen:
+
+- Is a **client component** (`"use client"`) with no Next.js server APIs.
+- Imports **only** from `@ds/*`. No imports from `app/` or other framework code.
+- Uses mock/static data — wire it to your real API on consumption.
+
+Consumers can drop these into:
+
+- A **Next.js + TypeScript** project (just place under `app/` or `pages/` and
+  import the screen).
+- A **plain React + TypeScript** project (Vite, CRA, etc.) — the screens have
+  no Next-specific dependencies.
+
+### Caveat — navigation
+
+`AppShell` uses plain `<a>` tags for portability. In a Next.js host, replace
+them with `next/link` if you want client-side navigation. The screens
+themselves (`DashboardScreen`, `InvoicesScreen`, `AuthScreen`) do not contain
+any links that depend on the framework.
+
+## Scripts
+
+| Script          | Description                  |
+| --------------- | ---------------------------- |
+| `npm run dev`   | Start dev server on `:5000`  |
+| `npm run build` | Production build             |
+| `npm run start` | Run production build         |
+| `npm run lint`  | Run ESLint                   |

package/app/dashboard/page.tsx

@@ -0,0 +1,10 @@
+import { AppShell } from "@screens/_shared/app-shell";
+import { DashboardScreen } from "@screens/dashboard/dashboard-screen";
+
+export default function DashboardPage() {
+  return (
+    <AppShell activeHref="/dashboard">
+      <DashboardScreen />
+    </AppShell>
+  );
+}