From 7670446f7cd055c401e1f4327ecfd27bb58d9130 Mon Sep 17 00:00:00 2001
From: Ifeoluwa Sanni <47613365+pheobeayo@users.noreply.github.com>
Date: Sat, 1 Feb 2025 20:15:29 +0100
Subject: [PATCH] docs: enhance component documentation and storybook
 integration (#114)

---
 apps/web/.env.example                         |  13 -----
 apps/web/src/stories/Alert.stories.tsx        |   8 ++-
 apps/web/src/stories/Badge.stories.tsx        |  19 ++++++-
 apps/web/src/stories/Button.stories.tsx       |  23 ++++++++-
 apps/web/src/stories/CarouselCard.stories.tsx |  17 ++++++-
 .../src/stories/ChatWithSeller.stories.tsx    |  17 ++++++-
 apps/web/src/stories/IconButton.stories.tsx   |  23 ++++++++-
 apps/web/src/stories/InfoCard.stories.tsx     |  26 ++++++++--
 apps/web/src/stories/Modal.stories.tsx        |  10 +++-
 apps/web/src/stories/NftCard.stories.tsx      |   9 ++--
 apps/web/src/stories/Page.stories.ts          |   7 ++-
 apps/web/src/stories/Particle.stories.tsx     |  31 +++++++++++-
 apps/web/src/stories/ProductCard.stories.tsx  |  47 +++++++++++++++++-
 apps/web/src/stories/Skeleton.stories.tsx     |  33 ++++++++++--
 apps/web/src/stories/Tooltip.stories.tsx      |   7 ++-
 apps/web/src/stories/dataCard.stories.tsx     |  25 +++++++++-
 apps/web/src/stories/typography.stories.tsx   |  22 +++++++-
 bun.lockb                                     | Bin 611520 -> 611520 bytes
 18 files changed, 290 insertions(+), 47 deletions(-)
 delete mode 100644 apps/web/.env.example

diff --git a/apps/web/.env.example b/apps/web/.env.example
deleted file mode 100644
index a3a1561..0000000
--- a/apps/web/.env.example
+++ /dev/null
@@ -1,13 +0,0 @@
-# DATABASE_URL='mysql://root:RbofLLysJtcYrazMMsSzpuTAYxMkaVsw@roundhouse.proxy.rlwy.net:21057/railway'
-DATABASE_URL=""
-NEXTAUTH_URL="http://localhost:3000"
-NODE_ENV="development"
-NEXT_PUBLIC_STARKNETKIT_PROJECT_ID=abc123
-NEXTAUTH_SECRET=secret
-NEXT_PUBLIC_BASE_URL=/
-NEXT_PUBLIC_SIGNER_ADDRESS=0x123
-
-PINATA_JWT=
-NEXT_PUBLIC_GATEWAY_URL=https://api.cartridge.gg/x/starknet/sepolia
-
-STARKNET_ENV=sepolia
\ No newline at end of file
diff --git a/apps/web/src/stories/Alert.stories.tsx b/apps/web/src/stories/Alert.stories.tsx
index 1f67966..3b5fe77 100644
--- a/apps/web/src/stories/Alert.stories.tsx
+++ b/apps/web/src/stories/Alert.stories.tsx
@@ -3,14 +3,18 @@ import type { Meta, StoryObj } from "@storybook/react";
 import type React from "react";
 import { useState } from "react";
 
+//This meta object defines metadata for the Alert component story,
+// including its title, tags, and component settings.
+
 const meta: Meta<typeof Alert> = {
-	title: "Components/Alert",
+	title: "Components/Alert", //Specifies the name and hierarchical path for the story given an example "Alert"
 	tags: ["autodocs"],
 	component: Alert,
 	parameters: {
 		controls: { expanded: true },
 	},
 	argTypes: {
+		//Defines controls for component props, enabling dynamic interaction in the Storybook UI.
 		type: {
 			control: { type: "select" },
 			options: ["success", "error", "info"],
@@ -22,6 +26,7 @@ export default meta;
 
 type Story = StoryObj<typeof Alert>;
 
+//This Template story demonstrates how the Alert component behaves with specific arguments (args). It includes a state (isVisible) to manage the visibility of the Alert
 export const Template: Story = (
 	args: React.JSX.IntrinsicAttributes & {
 		message: string;
@@ -30,6 +35,7 @@ export const Template: Story = (
 		onDismiss: () => void;
 	},
 ) => {
+	//Example code
 	const [isVisible, setIsVisible] = useState(true);
 
 	if (!isVisible) return null;
diff --git a/apps/web/src/stories/Badge.stories.tsx b/apps/web/src/stories/Badge.stories.tsx
index 293ae10..4473916 100644
--- a/apps/web/src/stories/Badge.stories.tsx
+++ b/apps/web/src/stories/Badge.stories.tsx
@@ -1,11 +1,14 @@
+//The Badge component is a versatile UI element designed to display small amounts of contextual information
+
 import type { Meta, StoryFn } from "@storybook/react";
 import React from "react";
 import Badge from "../../../../packages/ui/src/badge";
 
 export default {
-	title: "Components/Badge",
+	// This meta object configures the Storybook settings for the Badge component
+	title: "Components/Badge", //organises the components under the "Components" section here.
 	component: Badge,
-	tags: ["autodocs"],
+	tags: ["autodocs"], //automates documentation generation
 	argTypes: {
 		variant: {
 			control: "radio",
@@ -20,6 +23,7 @@ export default {
 
 const Template: StoryFn<typeof Badge> = (args) => <Badge {...args} />;
 
+//This is the default story that showcases the basic badge components
 export const Default = Template.bind({});
 Default.args = {
 	text: "Default Badge",
@@ -27,6 +31,7 @@ Default.args = {
 	size: "md",
 };
 
+//This showcases variant options of the Badge component.
 export const Variants: StoryFn = () => (
 	<div style={{ display: "flex", gap: "1rem" }}>
 		<Badge variant="primary" text="Primary" />
@@ -36,6 +41,7 @@ export const Variants: StoryFn = () => (
 	</div>
 );
 
+//This demonstrates all the size options of the Badge component.
 export const Sizes: StoryFn = () => (
 	<div style={{ display: "flex", gap: "1rem" }}>
 		<Badge variant="primary" text="Primary" size="sm" />
@@ -43,3 +49,12 @@ export const Sizes: StoryFn = () => (
 		<Badge variant="secondary" text="Primary" size="lg" />
 	</div>
 );
+
+// Aria best practices with the Badge include using aria-live for a content to dynamically update as in below:
+<Badge aria-live="polite" variant="primary" text="Success" />;
+
+// for an interactive badge ; example
+<Badge variant="accent" text="Clickable Badge" />;
+
+//If the badge contains icons or dynamic data, ensure there is an accessible label using aria-label or visually hidden text.e.g
+<Badge variant="success" text=" " aria-label="Success Badge" />;
diff --git a/apps/web/src/stories/Button.stories.tsx b/apps/web/src/stories/Button.stories.tsx
index 62930a4..3118ab7 100644
--- a/apps/web/src/stories/Button.stories.tsx
+++ b/apps/web/src/stories/Button.stories.tsx
@@ -1,10 +1,13 @@
+//This is a reusable UI component for intereactive actions
+
 import { ArrowRightIcon } from "@heroicons/react/24/solid";
 import Button from "@repo/ui/button";
 import type { Meta, StoryFn } from "@storybook/react";
 
 export default {
-	title: "Components/Button",
-	tags: ["autodocs"],
+	//Meta configures the settings for the Button component
+	title: "Components/Button", //organizes components under the "Button component"
+	tags: ["autodocs"], //automates documentation generation
 	component: Button,
 	argTypes: {
 		variant: {
@@ -34,12 +37,14 @@ export default {
 
 const Template: StoryFn<typeof Button> = (args) => <Button {...args} />;
 
+//showcases a button in the disabled state
 export const Disabled = Template.bind({});
 Disabled.args = {
 	children: "Disabled",
 	disabled: true,
 };
 
+//showcases using a icon with a button text
 export const WithIcon = Template.bind({});
 WithIcon.args = {
 	children: "Icon",
@@ -47,6 +52,7 @@ WithIcon.args = {
 	icon: <ArrowRightIcon />,
 };
 
+//illustrates the variant options "primary" and "secondary"
 export const Variants: StoryFn = () => (
 	<div style={{ display: "flex", gap: "1rem" }}>
 		<Button variant="primary">Primary</Button>
@@ -54,6 +60,7 @@ export const Variants: StoryFn = () => (
 	</div>
 );
 
+//showcases all size options for the button component
 export const Sizes: StoryFn = () => (
 	<div style={{ display: "flex", gap: "1rem" }}>
 		<Button variant="primary" size="sm">
@@ -70,3 +77,15 @@ export const Sizes: StoryFn = () => (
 		</Button>
 	</div>
 );
+
+// Aria best practices with the Button include using aria-label or aria-labelledby attribute
+// to provide accessible name without visible text such as
+<Button aria-label="Submit Form" variant="primary" />;
+
+// using in disabled button example:
+<Button disabled aria-disabled="true" variant="secondary">
+	Disabled Button
+</Button>;
+
+//using accessible label with icon button example:
+<Button icon={<ArrowRightIcon />} aria-label="Next Page" />;
diff --git a/apps/web/src/stories/CarouselCard.stories.tsx b/apps/web/src/stories/CarouselCard.stories.tsx
index 88498f5..6836b46 100644
--- a/apps/web/src/stories/CarouselCard.stories.tsx
+++ b/apps/web/src/stories/CarouselCard.stories.tsx
@@ -1,11 +1,13 @@
+//This is a reusable card component designed for use in carousels or grids.
 import type { Meta, StoryObj } from "@storybook/react";
 import CarouselCard, {
 	type CardProps,
 } from "../../../../packages/ui/src/carouselCard";
 
+//This meta object configures the CarouselCard for Storybook.
 const meta: Meta<typeof CarouselCard> = {
-	title: "Components/CarouselCard",
-	tags: ["autodocs"],
+	title: "Components/CarouselCard", //organizes components under the "CarouselCard component"
+	tags: ["autodocs"], //automates documentation generation
 	component: CarouselCard,
 	parameters: {
 		controls: { expanded: true },
@@ -30,6 +32,7 @@ export default meta;
 
 type Story = StoryObj<typeof CarouselCard>;
 
+// showcases a typical/default CarouselCard with all its properties
 const defaultArgs: CardProps = {
 	tag: "Tech",
 	title: "Latest Innovations in Technology",
@@ -40,3 +43,13 @@ const defaultArgs: CardProps = {
 export const Default: Story = {
 	args: { ...defaultArgs },
 };
+
+// Aria best accessibility practices with the CarouselCard include using aria-label or aria-labelledby attribute
+// to link the card's title to its content for users; example :
+<CarouselCard
+	tag="Cofiblock Store"
+	title="Latest Cofiblock Stores "
+	id="1"
+	image="https://via.placeholder.com/380x180?text=Card+Image"
+	aria-label="Latest Cofiblock Stores"
+/>;
diff --git a/apps/web/src/stories/ChatWithSeller.stories.tsx b/apps/web/src/stories/ChatWithSeller.stories.tsx
index f13f19b..c7294ef 100644
--- a/apps/web/src/stories/ChatWithSeller.stories.tsx
+++ b/apps/web/src/stories/ChatWithSeller.stories.tsx
@@ -1,10 +1,12 @@
+//The ChatWithSeller component is a reusable UI element for initiating a chat with a seller
 import { ChatWithSeller } from "@repo/ui/chatWithSeller";
 import type { Meta, StoryFn } from "@storybook/react";
 import React from "react";
 
+//This meta object configures the ChatWithSeller for Storybook.
 export default {
-	title: "Components/ChatWithSeller",
-	tags: ["autodocs"],
+	title: "Components/ChatWithSeller", //organizes components under the "ChatWithSeller component"
+	tags: ["autodocs"], //automates documentation generation
 	component: ChatWithSeller,
 	argTypes: {
 		name: {
@@ -35,6 +37,7 @@ const Template: StoryFn<typeof ChatWithSeller> = (args) => (
 	</div>
 );
 
+//This template showcases a default/typical ChatWithSeller setup.
 export const Default = Template.bind({});
 Default.args = {
 	name: "Jane Doe",
@@ -42,3 +45,13 @@ Default.args = {
 	avatarSrc: "/images/user-profile/avatar.svg",
 	onClick: () => alert("Navigating to chat..."),
 };
+
+//This component is made accessible by ensuring that the seller's name and description are announced by screen readers
+// using aria-labelledby and aria-describedby.Example as shown below
+<ChatWithSeller
+	name="Jane Doe"
+	description="Click to chat with the seller"
+	avatarSrc="/images/user-profile/avatar.svg"
+	aria-labelledby="chat-with-seller-name"
+	aria-describedby="chat-with-seller-description"
+/>;
diff --git a/apps/web/src/stories/IconButton.stories.tsx b/apps/web/src/stories/IconButton.stories.tsx
index 1826641..5b71cef 100644
--- a/apps/web/src/stories/IconButton.stories.tsx
+++ b/apps/web/src/stories/IconButton.stories.tsx
@@ -1,10 +1,12 @@
+//This IconButton component is a button designed to display an icon with various sizes, styles, and states.
 import { ArrowRightIcon, HomeIcon } from "@heroicons/react/24/solid";
 import IconButton from "@repo/ui/iconButton";
 import type { Meta, StoryFn } from "@storybook/react";
 
+//This meta object configures the IconButton for Storybook
 export default {
-	title: "Components/IconButton",
-	tags: ["autodocs"],
+	title: "Components/IconButton", //organizes components under the "IconButton component"
+	tags: ["autodocs"], //automates documentation generation
 	component: IconButton,
 	argTypes: {
 		variant: {
@@ -34,6 +36,7 @@ export default {
 
 const Template: StoryFn<typeof IconButton> = (args) => <IconButton {...args} />;
 
+//Shows the IconButton with a HomeIcon.
 export const WithHomeIcon = Template.bind({});
 WithHomeIcon.args = {
 	icon: <HomeIcon />,
@@ -41,6 +44,7 @@ WithHomeIcon.args = {
 	size: "lg",
 };
 
+//Shows the IconButton in a disabled state
 export const Disabled = Template.bind({});
 Disabled.args = {
 	icon: <ArrowRightIcon />,
@@ -49,6 +53,7 @@ Disabled.args = {
 	disabled: true,
 };
 
+//shows both primary and secondary variants of the IconButton
 export const Variants: StoryFn = () => (
 	<div style={{ display: "flex", gap: "1rem" }}>
 		<IconButton variant="primary" size="md" icon={<ArrowRightIcon />}>
@@ -60,6 +65,7 @@ export const Variants: StoryFn = () => (
 	</div>
 );
 
+//Demonstrates all size options for the IconButton.
 export const Sizes: StoryFn = () => (
 	<div style={{ display: "flex", gap: "1rem" }}>
 		<IconButton variant="primary" size="sm" icon={<ArrowRightIcon />}>
@@ -76,3 +82,16 @@ export const Sizes: StoryFn = () => (
 		</IconButton>
 	</div>
 );
+
+//To make the IconButton accessible, you can use [role="group"] explicitly for non-button elements styled as buttons.
+// and [aria-disabled="true"] when the button is disabled to communicate its state to assistive technologies..
+//example as seen below:
+
+<IconButton
+	icon={<HomeIcon />}
+	variant="primary"
+	size="md"
+	aria-label="Navigate to home"
+	disabled={true}
+	aria-disabled="true"
+/>;
diff --git a/apps/web/src/stories/InfoCard.stories.tsx b/apps/web/src/stories/InfoCard.stories.tsx
index 547f1eb..785b3f6 100644
--- a/apps/web/src/stories/InfoCard.stories.tsx
+++ b/apps/web/src/stories/InfoCard.stories.tsx
@@ -1,18 +1,21 @@
+//The InfoCard component is a versatile UI element designed to display
+// a title and a list of interactive options or child components.
 import { InfoCard } from "@repo/ui/infoCard";
 import type { Meta, StoryFn } from "@storybook/react";
 import React from "react";
 
+//This meta object configures the InfoCard for Storybook
 export default {
-	title: "Components/InfoCard",
+	title: "Components/InfoCard", //organizes components under the "InfoCard component"
 	component: InfoCard,
-	tags: ["autodocs"],
+	tags: ["autodocs"], //automates documentation generation
 	argTypes: {
 		title: { control: "text", description: "The title of the InfoCard" },
 		options: {
 			control: false,
 			description: "Options displayed in the InfoCard",
 		},
-		children: { control: false, description: "Optional child components" },
+		children: { control: false, description: "Optional child components" }, //Optional child components, useful when no options are provided
 	},
 } as Meta;
 
@@ -41,15 +44,32 @@ const Template: StoryFn = (args) => (
 	<InfoCard title={""} options={options} {...args} />
 );
 
+//shows an InfoCard with a title and multiple options.
 export const Default = Template.bind({});
 Default.args = {
 	title: "Default InfoCard",
 	options,
 };
 
+// shows the InfoCard without options, showing a fallback message using children.
 export const NoOptions = Template.bind({});
 NoOptions.args = {
 	title: "InfoCard with No Options",
 	options: [],
 	children: <p>No options available</p>,
 };
+
+//To make the InfoCard accessible, you can use [role="group"] for the InfoCard to indicate it groups related options
+// and 'aria-labelledby' on the options container to associate it with the title.
+// Use 'aria-pressed' for selectable options to indicate their current state.
+<InfoCard
+	title="Accessible InfoCard"
+	options={[
+		{
+			label: "Option 1",
+			iconSrc: "/images/Avatar.png",
+			selected: false,
+			onClick: () => alert("Option 1 clicked"),
+		},
+	]}
+/>;
diff --git a/apps/web/src/stories/Modal.stories.tsx b/apps/web/src/stories/Modal.stories.tsx
index cc709f3..bd7d974 100644
--- a/apps/web/src/stories/Modal.stories.tsx
+++ b/apps/web/src/stories/Modal.stories.tsx
@@ -1,11 +1,14 @@
+//The Modal component is a pop-up dialog used to
+// present information or actions in a focused manner.
 import Modal from "@repo/ui/modal";
 import type { Meta, StoryFn } from "@storybook/react";
 import React from "react";
 import TestIcon from "./assets/youtube.svg";
 
+//This meta object configures the Modal for Storybook
 export default {
-	title: "Components/Modal",
-	tags: ["autodocs"],
+	title: "Components/Modal", //organizes components under the "Modal component"
+	tags: ["autodocs"], //automates documentation generation
 	component: Modal,
 	argTypes: {
 		isOpen: {
@@ -45,6 +48,7 @@ const Template: StoryFn = (args) => (
 	/>
 );
 
+//The default modal configuration with basic buttons.
 export const Default = Template.bind({});
 Default.args = {
 	isOpen: true,
@@ -52,6 +56,7 @@ Default.args = {
 	buttons,
 };
 
+//This modal includes buttons with icons (e.g., accept and decline buttons).
 export const Icons = Template.bind({});
 Icons.args = {
 	isOpen: true,
@@ -66,6 +71,7 @@ Icons.args = {
 	],
 };
 
+//This modal is displayed without any buttons, useful for informational modals or alerts.
 export const NoButtons = Template.bind({});
 NoButtons.args = {
 	isOpen: true,
diff --git a/apps/web/src/stories/NftCard.stories.tsx b/apps/web/src/stories/NftCard.stories.tsx
index 3f2d359..adbfca9 100644
--- a/apps/web/src/stories/NftCard.stories.tsx
+++ b/apps/web/src/stories/NftCard.stories.tsx
@@ -1,10 +1,13 @@
+//The NFTCard component is used to display details about an NFT (Non-Fungible Token).
+// It includes metadata such as the image, title, and a button to view more details
 import NFTCard from "@repo/ui/nftCard";
 import type { Meta, StoryObj } from "@storybook/react";
 import type React from "react";
 
+///This meta object configures the NFTcard for Storybook
 export default {
-	title: "Components/NFTCard",
-	tags: ["autodocs"],
+	title: "Components/NFTCard", //organizes components under the "NFTcard component"
+	tags: ["autodocs"], //automates documentation generation
 	component: NFTCard,
 	argTypes: {
 		onDetailsClick: { action: "clicked" },
@@ -30,7 +33,7 @@ export const Template: Story = (
 ) => {
 	return <NFTCard {...args} />;
 };
-
+//The default story with the basic NFT metadata
 Template.args = {
 	title: "Interactive NFT",
 	nftMetadata: {
diff --git a/apps/web/src/stories/Page.stories.ts b/apps/web/src/stories/Page.stories.ts
index e11bef8..62fa02d 100644
--- a/apps/web/src/stories/Page.stories.ts
+++ b/apps/web/src/stories/Page.stories.ts
@@ -1,10 +1,13 @@
+//The Page component serves as an example layout with conditional rendering
+// for a logged-in or logged-out user
 import type { Meta, StoryObj } from "@storybook/react";
 import { expect, userEvent, within } from "@storybook/test";
 
 import { Page } from "./Page";
 
+//This meta object configures the Page
 const meta = {
-	title: "Example/Page",
+	title: "Example/Page", //organizes components under the "Page Component"
 	component: Page,
 	parameters: {
 		// More on how to position stories at: https://storybook.js.org/docs/configure/story-layout
@@ -15,9 +18,11 @@ const meta = {
 export default meta;
 type Story = StoryObj<typeof meta>;
 
+//This story shows the default, logged-out state.
 export const LoggedOut: Story = {};
 
 // More on interaction testing: https://storybook.js.org/docs/writing-tests/interaction-testing
+// This shows Logged-In State with Interactions
 export const LoggedIn: Story = {
 	play: async ({ canvasElement }) => {
 		const canvas = within(canvasElement);
diff --git a/apps/web/src/stories/Particle.stories.tsx b/apps/web/src/stories/Particle.stories.tsx
index 68d4c0a..93dbc1d 100644
--- a/apps/web/src/stories/Particle.stories.tsx
+++ b/apps/web/src/stories/Particle.stories.tsx
@@ -1,9 +1,13 @@
+//This Particle component animates particles within a container.
+// It is a visual, aesthetic component often used for decorative
+// or interactive purposes in UI design.
 import Particle from "@repo/ui/particle";
 import type { Meta, StoryFn } from "@storybook/react";
 
+//This meta object configures the Particle for Storybook
 export default {
-	title: "Components/Particle",
-	tags: ["autodocs"],
+	title: "Components/Particle", //organizes components under the "Particle component"
+	tags: ["autodocs"], //automates documentation generation
 	component: Particle,
 	argTypes: {
 		delay: {
@@ -19,12 +23,35 @@ const Template: StoryFn<typeof Particle> = (args) => (
 	</div>
 );
 
+//This implements the default behavior of the Particle component with delay.
 export const Default = Template.bind({});
 Default.args = {
 	delay: 0,
 };
 
+//This implements the particle animation with a 1-second delay.
 export const WithDelay = Template.bind({});
 WithDelay.args = {
 	delay: 1,
 };
+
+//This shows how the Particle component behaves when the user prefers reduced motion.
+export const ReducedMotion = Template.bind({});
+ReducedMotion.args = {
+	delay: 0,
+};
+ReducedMotion.parameters = {
+	css: `
+    @media (prefers-reduced-motion: reduce) {
+      .particle-animation {
+        animation: none;
+      }
+    }
+  `,
+};
+
+//In the aria attributes and accessibilities, you can use [aria-hidden="true"]
+// to hide it from assistive technologies like screen readers.
+<div className="relative w-[200px] h-[200px] bg-black">
+	<Particle delay={1} aria-hidden="true" />
+</div>;
diff --git a/apps/web/src/stories/ProductCard.stories.tsx b/apps/web/src/stories/ProductCard.stories.tsx
index 5bc0539..4be9392 100644
--- a/apps/web/src/stories/ProductCard.stories.tsx
+++ b/apps/web/src/stories/ProductCard.stories.tsx
@@ -1,9 +1,11 @@
+//This ProductCard component displays product details in a card format
 import { ProductCard } from "@repo/ui/productCard";
 import type { Meta, StoryFn } from "@storybook/react";
 
+//This meta object configures the ProductCard for Storybook
 export default {
-	title: "Components/ProductCard",
-	tags: ["autodocs"],
+	title: "Components/ProductCard", //organizes components under the "ProductCard component"
+	tags: ["autodocs"], //automates documentation generation
 	component: ProductCard,
 	argTypes: {
 		image: {
@@ -49,6 +51,7 @@ const Template: StoryFn<typeof ProductCard> = (args) => (
 	<ProductCard {...args} />
 );
 
+//This implements the default Product Card
 export const Default = Template.bind({});
 Default.args = {
 	image: "https://via.placeholder.com/358x188",
@@ -60,6 +63,7 @@ Default.args = {
 	onClick: () => alert("View product details"),
 };
 
+//This implements the Product On Sale
 export const OnSale = Template.bind({});
 OnSale.args = {
 	...Default.args,
@@ -67,6 +71,7 @@ OnSale.args = {
 	price: 20,
 };
 
+//This implements the Featured Card
 export const Featured = Template.bind({});
 Featured.args = {
 	...Default.args,
@@ -74,15 +79,53 @@ Featured.args = {
 	variety: "Geisha Coffee",
 };
 
+//This implements a card without an image
 export const NoImage = Template.bind({});
 NoImage.args = {
 	...Default.args,
 	image: "",
 };
 
+//This implements how to add to Cart
 export const AddToCart = Template.bind({});
 AddToCart.args = {
 	...Default.args,
 	badgeText: "Best Seller",
 	onAddToCart: () => alert("Item added to cart"),
 };
+
+//Usage Examples
+//Basic Product Card
+<ProductCard
+	image="https://via.placeholder.com/358x188"
+	region="Ethiopia"
+	farmName="Sunrise Farms"
+	variety="Arabica Coffee"
+	price={25}
+	badgeText="New Arrival"
+	onClick={() => alert("View product details")}
+/>;
+
+//Product On Sale
+<ProductCard
+	image="https://via.placeholder.com/358x188"
+	region="Ethiopia"
+	farmName="Sunrise Farms"
+	variety="Arabica Coffee"
+	price={20}
+	badgeText="On Sale"
+	onClick={() => alert("View product details")}
+/>;
+
+//In the aria attributes and accessibilities,
+// You can add a [role="status"] and [aria-live="polite"] attribute to the badge element to announce status
+//  changes to users. Example;
+<span role="status" aria-live="polite">
+	New Arrival
+</span>;
+// You should use meaningful alt text for the product image.
+// If the image is decorative or missing, provide an empty alt="".
+<img
+	src="https://via.placeholder.com/358x188"
+	alt="Arabica Coffee from Sunrise Farms"
+/>;
diff --git a/apps/web/src/stories/Skeleton.stories.tsx b/apps/web/src/stories/Skeleton.stories.tsx
index cbe2642..a94cc39 100644
--- a/apps/web/src/stories/Skeleton.stories.tsx
+++ b/apps/web/src/stories/Skeleton.stories.tsx
@@ -1,9 +1,12 @@
+//This SkeletonLoader component is a placeholder UI element used to indicate loading state
+
 import SkeletonLoader from "@repo/ui/skeleton";
 import type { Meta, StoryObj } from "@storybook/react";
 
+//This meta object configures the SkeletonLoader for Storybook
 export default {
-	title: "Components/SkeletonLoader",
-	tags: ["autodocs"],
+	title: "Components/SkeletonLoader", //organizes components under the "SkeletonLoader component"
+	tags: ["autodocs"], //automates documentation generation
 	component: SkeletonLoader,
 	argTypes: {
 		width: {
@@ -31,8 +34,30 @@ export const Template: Story = (
 ) => {
 	return <SkeletonLoader {...args} />;
 };
-
+//This implements the default Skeleton Loader
 Template.args = {
-	width: "w-[25rem]",
+	width: "w-[25rem]", // This can also be customized as  "w-full" and "h-24"
 	height: "h-[50rem]",
 };
+
+// dimensions can also be full screen loader
+// using width: "w-screen",
+// height: "h-screen",
+
+// Usage examples
+//Basic SkeletonLoader
+<SkeletonLoader width="w-[20rem]" height="h-[40rem]" />;
+
+//Customized SkeletonLoader
+<SkeletonLoader width="w-full" height="h-24" />;
+
+//In the aria attributes and accessibilities,
+// you should [role="progressbar"] to indicate that the component represents a loading state
+// Add aria-busy="true" to inform users that the content is still loading.
+// Use aria-hidden="true" if the SkeletonLoader is purely decorative and not necessary for users.
+// example as seen below;
+<div
+	aria-busy="true"
+	aria-label="Loading content"
+	className="skeleton-loader"
+/>;
diff --git a/apps/web/src/stories/Tooltip.stories.tsx b/apps/web/src/stories/Tooltip.stories.tsx
index 7edeca6..a5a302b 100644
--- a/apps/web/src/stories/Tooltip.stories.tsx
+++ b/apps/web/src/stories/Tooltip.stories.tsx
@@ -1,9 +1,12 @@
+//Thia Tooltip component provides contextual information
+// when users hover over, focus on, or tap on an element
 import Tooltip from "@repo/ui/tooltip";
 import type { Meta } from "@storybook/react";
 
+//This meta object configures the Tooltip for Storybook
 export default {
-	title: "Components/Tooltip",
-	tags: ["autodocs"],
+	title: "Components/Tooltip", //organizes components under the "Tooltip component"
+	tags: ["autodocs"], //automates documentation generation
 	component: Tooltip,
 	argTypes: {
 		content: {
diff --git a/apps/web/src/stories/dataCard.stories.tsx b/apps/web/src/stories/dataCard.stories.tsx
index 2ca14f6..21a1029 100644
--- a/apps/web/src/stories/dataCard.stories.tsx
+++ b/apps/web/src/stories/dataCard.stories.tsx
@@ -1,10 +1,12 @@
+//Th is a  DataCard component  that displays a label, value, and optional icon in a card format
 import { DataCard } from "@repo/ui/dataCard";
 import type { Meta, StoryFn } from "@storybook/react";
 import React from "react";
 
+//This meta object configures the dataCard for Storybook
 export default {
-	title: "Components/DataCard",
-	tags: ["autodocs"],
+	title: "Components/DataCard", //organizes components under the "dataCard component"
+	tags: ["autodocs"], //automates documentation generation
 	component: DataCard,
 	argTypes: {
 		label: {
@@ -37,6 +39,7 @@ const Template: StoryFn<typeof DataCard> = (args) => (
 	</div>
 );
 
+//This showcases the default appearance of the DataCard.
 export const Default = Template.bind({});
 Default.args = {
 	label: "Default Label",
@@ -45,6 +48,7 @@ Default.args = {
 	variant: "default",
 };
 
+//This demonstrates the error variant of the DataCard.
 export const ErrorCard = Template.bind({});
 ErrorCard.args = {
 	label: "Error Label",
@@ -53,6 +57,7 @@ ErrorCard.args = {
 	variant: "error",
 };
 
+//This displays a custom icon in the DataCard.
 export const CustomIcon = Template.bind({});
 CustomIcon.args = {
 	label: "Custom Icon Label",
@@ -60,3 +65,19 @@ CustomIcon.args = {
 	iconSrc: "https://via.placeholder.com/250",
 	variant: "default",
 };
+
+//To make the DataCard accessible, you can use [role="group"] to signify that the card groups related content.
+// and also use aria-labelledby for the label and aria-describedby for the value to associate them with the card.
+//example as seen below:
+<div
+	role="group"
+	aria-labelledby="data-card-label"
+	aria-describedby="data-card-value"
+>
+	<DataCard
+		label="Accessible Label"
+		value="Accessible Value"
+		iconSrc="https://via.placeholder.com/250"
+		variant="default"
+	/>
+</div>;
diff --git a/apps/web/src/stories/typography.stories.tsx b/apps/web/src/stories/typography.stories.tsx
index 12b95c0..9a382dc 100644
--- a/apps/web/src/stories/typography.stories.tsx
+++ b/apps/web/src/stories/typography.stories.tsx
@@ -1,3 +1,5 @@
+//These Typography components (H1, H2, H3, H4, Text, TextSecondary, TextLegend)
+// provide a set of styled text elements for headings, paragraphs, and supplementary content.
 import {
 	H1,
 	H2,
@@ -10,9 +12,10 @@ import {
 import type { Meta } from "@storybook/react";
 import React from "react";
 
+//This meta object configures the Typography for Storybook
 export default {
-	title: "Components/Typography",
-	tags: ["autodocs"],
+	title: "Components/Typography", //organizes components under the "Typography component"
+	tags: ["autodocs"], //automates documentation generation
 	argTypes: {
 		className: {
 			control: "text",
@@ -42,3 +45,18 @@ export const TypographyShowcase = ({ className = "", isSemiBold = false }) => (
 		<TextLegend className={className}>This is legend text.</TextLegend>
 	</div>
 );
+
+//Usage Examples
+//Basic Typography
+<TypographyShowcase />;
+
+//Custom Styling
+<TypographyShowcase className="text-blue-600" />;
+
+//Semi-Bold Text
+<Text isSemiBold>This is a semi-bold paragraph.</Text>;
+
+//In the aria attributes and accessibilities,
+// you should use H1, H2, H3, and H4 for headings to convey the structure of
+// the content to assistive technologies. If the Typography components are used
+// as interactive elements, add role, aria-label, or aria-describedby attributes as appropriate.
diff --git a/bun.lockb b/bun.lockb
index 4e2a0c632fcf43f9498cc288184a424d1a639f3c..8e812ac0e664b5f952e799520f8901886d552527 100755
GIT binary patch
delta 43
xcmX@GQuV+})rJ<v7N!>F7M2#)Eo|Ob*cs!@^o;Zj+k>vK0Wtgbper1C4FFog53T?J

delta 47
zcmX@GQuV+})rJ<v7N!>F7M2#)Eo|Ob*q9hVVERRIHsSV^D{Mf_zCGm%M@$0%f=dt=