@gv-tech/design-system 0.8.0

package/package.json

@@ -0,0 +1,130 @@
+{
+  "name": "@gv-tech/design-system",
+  "version": "0.8.0",
+  "description": "Garcia Ventures react design system",
+  "license": "MIT",
+  "author": "Eric N. Garcia <eng618@garciaericn.com>",
+  "main": "dist/index.cjs.js",
+  "module": "dist/index.es.js",
+  "types": "dist/index.d.ts",
+  "repository": "git@github.com:Garcia-ventures/gvtech-design.git",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && vite build",
+    "build-storybook": "storybook build",
+    "build-storybook-docs": "storybook build --docs",
+    "dev": "vite dev",
+    "format": "prettier --write .",
+    "format:ci": "prettier --check .",
+    "lint": "eslint . --cache",
+    "lint:fix": "eslint . --cache --fix",
+    "lint:report": "eslint . --cache -o ./eslintReport.html -f html",
+    "prepare": "husky",
+    "start": "vite dev",
+    "storybook": "storybook dev -p 9009",
+    "serve": "yarn build-storybook && yarn dlx serve storybook-static -l 6006",
+    "test": "vitest",
+    "test:ci": "CI=true vitest --run --reporter=dot",
+    "test:watch": "vitest --watch",
+    "test-storybook": "test-storybook",
+    "test-storybook:ci": "concurrently -k -s first -n \"SB,TEST\" \"yarn dlx serve storybook-static -p 6006\" \"wait-on http://127.0.0.1:6006 && test-storybook --url http://127.0.0.1:6006\"",
+    "validate": "node ./scripts/validate.js",
+    "validate:fix": "node ./scripts/validate.js --fix"
+  },
+  "peerDependencies": {
+    "polished": "^4.0.0",
+    "prop-types": "^15.8.0",
+    "react": "^18 || ^19",
+    "react-dom": "^18 || ^19",
+    "react-is": "^16 || ^17 || ^18 || ^19",
+    "styled-components": "^5 || ^6"
+  },
+  "devDependencies": {
+    "@babel/cli": "^7.28.6",
+    "@babel/core": "^7.28.6",
+    "@babel/preset-env": "^7.28.6",
+    "@babel/preset-react": "^7.28.5",
+    "@babel/preset-typescript": "^7.28.5",
+    "@eng618/prettier-config": "^2.5.2",
+    "@eslint/js": "^9.39.2",
+    "@mdx-js/react": "^3.1.1",
+    "@storybook/addon-a11y": "10.2.1",
+    "@storybook/addon-docs": "10.2.1",
+    "@storybook/addon-links": "10.2.1",
+    "@storybook/builder-vite": "10.2.1",
+    "@storybook/cli": "10.2.1",
+    "@storybook/jest": "^0.2.3",
+    "@storybook/react-vite": "10.2.1",
+    "@storybook/test-runner": "^0.24.2",
+    "@storybook/testing-library": "^0.2.2",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.2.10",
+    "@types/react-dom": "^19.2.3",
+    "@typescript-eslint/eslint-plugin": "^8.54.0",
+    "@typescript-eslint/parser": "^8.54.0",
+    "@vitejs/plugin-react": "5.1.2",
+    "axe-core": "^4.7.2",
+    "babel-loader": "^10.0.0",
+    "concurrently": "^9.2.1",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-jsx-a11y": "^6.10.2",
+    "eslint-plugin-prettier": "^5.5.5",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-storybook": "10.2.1",
+    "globals": "^17.2.0",
+    "husky": "^9.1.7",
+    "jsdom": "^27.4.0",
+    "lint-staged": "^16.2.7",
+    "polished": "^4.3.1",
+    "prettier": "^3.8.1",
+    "prop-types": "^15.8.1",
+    "react": "^19.2.4",
+    "react-docgen-typescript": "^2.4.0",
+    "react-dom": "^19.2.4",
+    "react-is": "^19.2.4",
+    "storybook": "10.2.1",
+    "styled-components": "^6.3.8",
+    "typescript": "^5.9.3",
+    "vite": "7.3.1",
+    "vitest": "^4.0.18",
+    "wait-on": "^9.0.3"
+  },
+  "lint-staged": {
+    "*.(js|ts|mjs|cjs)?(x)": [
+      "prettier --write",
+      "eslint --cache --fix"
+    ],
+    "*.(md)?(x)": [
+      "prettier --write"
+    ]
+  },
+  "prettier": "@eng618/prettier-config",
+  "babel": {
+    "presets": [
+      "@babel/preset-env",
+      "@babel/preset-react"
+    ]
+  },
+  "browserslist": {
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ],
+    "production": [
+      ">0.2%",
+      "not dead"
+    ]
+  },
+  "packageManager": "yarn@4.12.0"
+}

package/public/index.demo.html

@@ -0,0 +1,40 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <link rel="icon" href="%PUBLIC_URL%/favicon.ico" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="theme-color" content="#000000" />
+    <meta name="description" content="Garcia Ventures design system" />
+    <link rel="apple-touch-icon" href="logo192.png" />
+    <!--
+      manifest.json provides metadata used when your web app is installed on a
+      user's mobile device or desktop. See https://developers.google.com/web/fundamentals/web-app-manifest/
+    -->
+    <link rel="manifest" href="%PUBLIC_URL%/manifest.json" />
+    <!--
+      Notice the use of %PUBLIC_URL% in the tags above.
+      It will be replaced with the URL of the `public` folder during the build.
+      Only files inside the `public` folder can be referenced from the HTML.
+
+      Unlike "/favicon.ico" or "favicon.ico", "%PUBLIC_URL%/favicon.ico" will
+      work correctly both with client-side routing and a non-root public URL.
+      Learn how to configure a non-root public URL by running `npm run build`.
+    -->
+    <title>GV Tech Design System</title>
+  </head>
+  <body>
+    <noscript>You need to enable JavaScript to run this app.</noscript>
+    <div id="root"></div>
+    <!--
+      This HTML file is a template.
+      If you open it directly in the browser, you will see an empty page.
+
+      You can add webfonts, meta tags, or analytics to this file.
+      The build step will place the bundled scripts into the <body> tag.
+
+      To begin the development, run `npm start` or `yarn start`.
+      To create a production bundle, use `npm run build` or `yarn build`.
+    -->
+  </body>
+</html>

package/public/manifest.json

@@ -0,0 +1,25 @@
+{
+  "short_name": "GV Design",
+  "name": "GV Tech Design System",
+  "icons": [
+    {
+      "src": "favicon.ico",
+      "sizes": "64x64 32x32 24x24 16x16",
+      "type": "image/x-icon"
+    },
+    {
+      "src": "logo192.png",
+      "type": "image/png",
+      "sizes": "192x192"
+    },
+    {
+      "src": "logo512.png",
+      "type": "image/png",
+      "sizes": "512x512"
+    }
+  ],
+  "start_url": ".",
+  "display": "standalone",
+  "theme_color": "#000000",
+  "background_color": "#ffffff"
+}

package/public/robots.txt

@@ -0,0 +1,2 @@
+# https://www.robotstxt.org/robotstxt.html
+User-agent: *

package/scripts/validate.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require('child_process');
+
+const args = process.argv.slice(2);
+const fix = args.includes('--fix');
+
+const steps = [
+  {
+    name: fix ? 'Prettier fix' : 'Prettier check',
+    cmd: fix ? 'yarn format' : 'yarn format:ci',
+  },
+  {
+    name: fix ? 'Lint fix (eslint)' : 'Lint (eslint)',
+    cmd: fix ? 'yarn lint:fix' : 'yarn lint',
+  },
+  { name: 'TypeScript type check', cmd: 'npx tsc --noEmit' },
+  { name: 'Build (vite)', cmd: 'yarn build' },
+  { name: 'Storybook build', cmd: 'yarn build-storybook' },
+  { name: 'Storybook docs build', cmd: 'yarn build-storybook-docs' },
+];
+
+const SEP = '------------------------------------------------------------';
+const green = (s) => `\x1b[32m${s}\x1b[0m`;
+const red = (s) => `\x1b[31m${s}\x1b[0m`;
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
+
+console.log(SEP);
+console.log('\x1b[1mRunning validate steps (sequential)\x1b[0m');
+console.log(SEP);
+
+for (const step of steps) {
+  console.log(yellow(`\n> ${step.name}`));
+  console.log(yellow(`> ${step.cmd}\n`));
+
+  const result = spawnSync(step.cmd, { stdio: 'inherit', shell: true });
+
+  if (result.error) {
+    console.error(red(`\nFailed to run: ${step.cmd}`));
+    console.error(red(result.error));
+    process.exit(1);
+  }
+
+  if (result.status !== 0) {
+    console.error(red(`\n${step.name} failed with exit code ${result.status}.`));
+    console.error(red('Stopping further steps.'));
+    process.exit(result.status || 1);
+  }
+
+  console.log(green(`\n${step.name} succeeded.`));
+}
+
+console.log('\n' + SEP);
+console.log(green('All validate steps completed successfully ✅'));
+console.log(SEP + '\n');
+process.exit(0);

package/serve.json

@@ -0,0 +1,4 @@
+{
+  "cleanUrls": false,
+  "trailingSlash": false
+}

package/src/Avatar.stories.tsx

@@ -0,0 +1,67 @@
+import { Meta, StoryObj } from '@storybook/react-vite';
+import { Avatar } from './Avatar';
+
+const meta: Meta<typeof Avatar> = {
+  title: 'Design System/Avatar',
+  component: Avatar,
+  argTypes: {
+    loading: {
+      control: 'boolean',
+      description: 'Use the loading state to indicate that the data Avatar needs is still loading.',
+    },
+    username: {
+      description:
+        "Avatar falls back to the user's initial when no image is provided. Supply a `username` and omit `src` to see what this looks like.",
+    },
+    src: {
+      description: "The URL of the Avatar's image.",
+    },
+    size: {
+      description: "Avatar comes in four sizes. In most cases, you'll be fine with `medium`.",
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+import { expect } from '@storybook/jest';
+import { within } from '@storybook/testing-library';
+
+export const Standard: Story = {
+  args: {
+    username: 'John Doe',
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const avatar = canvas.getByLabelText('John Doe');
+    expect(avatar).toBeInTheDocument();
+    expect(avatar).toHaveTextContent('J');
+  },
+};
+
+export const Loading: Story = {
+  args: {
+    loading: true,
+    username: 'Loading',
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const avatar = canvas.getByLabelText('Loading avatar ...');
+    expect(avatar).toBeInTheDocument();
+    // In loading state, it might show a placeholder or nothing specific
+  },
+};
+
+export const WithImage: Story = {
+  args: {
+    src: 'https://avatars.githubusercontent.com/u/1?v=4',
+    username: 'GitHub',
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const img = canvas.getByRole('img');
+    expect(img).toBeInTheDocument();
+    expect(img).toHaveAttribute('src', 'https://avatars.githubusercontent.com/u/1?v=4');
+  },
+};

package/src/Avatar.tsx

@@ -0,0 +1,174 @@
+import React from 'react';
+import styled, { css } from 'styled-components';
+import { color, typography } from './shared/styles';
+import { glow } from './shared/animation';
+import { Icon } from './Icon';
+
+/**
+ * Available avatar sizes with their pixel values
+ */
+export const sizes = {
+  large: 40,
+  medium: 28,
+  small: 20,
+  tiny: 16,
+} as const;
+
+/**
+ * Union type for avatar size keys
+ */
+export type AvatarSize = keyof typeof sizes;
+
+/**
+ * Props for the Avatar component
+ */
+interface AvatarProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** Whether the avatar is in a loading state */
+  loading?: boolean;
+  /** The username to display (used for initials or alt text) */
+  username?: string;
+  /** Image source URL for the avatar */
+  src?: string;
+  /** Size variant of the avatar */
+  size?: AvatarSize;
+}
+
+/**
+ * Props for styled Image component
+ */
+interface ImageProps {
+  loading?: boolean;
+  size?: AvatarSize;
+  src?: string;
+}
+
+/**
+ * Props for styled Initial component
+ */
+interface InitialProps {
+  size?: AvatarSize;
+}
+
+const Image = styled.div<ImageProps>`
+  background: ${(props) => (!props.loading ? 'transparent' : color.light)};
+  border-radius: 50%;
+  display: inline-block;
+  vertical-align: top;
+  overflow: hidden;
+  text-transform: uppercase;
+
+  height: ${sizes.medium}px;
+  width: ${sizes.medium}px;
+  line-height: ${sizes.medium}px;
+
+  ${(props) =>
+    props.size === 'tiny' &&
+    css`
+      height: ${sizes.tiny}px;
+      width: ${sizes.tiny}px;
+      line-height: ${sizes.tiny}px;
+    `}
+
+  ${(props) =>
+    props.size === 'small' &&
+    css`
+      height: ${sizes.small}px;
+      width: ${sizes.small}px;
+      line-height: ${sizes.small}px;
+    `}
+
+  ${(props) =>
+    props.size === 'large' &&
+    css`
+      height: ${sizes.large}px;
+      width: ${sizes.large}px;
+      line-height: ${sizes.large}px;
+    `}
+
+  ${(props) =>
+    !props.src &&
+    css`
+      background: ${!props.loading && '#37D5D3'};
+    `}
+
+  img {
+    width: 100%;
+    height: auto;
+    display: block;
+  }
+
+  svg {
+    position: relative;
+    bottom: -2px;
+    height: 100%;
+    width: 100%;
+    vertical-align: top;
+  }
+
+  path {
+    fill: ${color.medium};
+    animation: ${glow} 1.5s ease-in-out infinite;
+  }
+`;
+
+// prettier-ignore
+const Initial = styled.div<InitialProps>`
+  color: ${color.lightest};
+  text-align: center;
+
+  font-size: ${typography.size.s2}px;
+  line-height: ${sizes.medium}px;
+
+  ${(props) => props.size === 'tiny' && css`
+    font-size: ${Number(typography.size.s1) - 2}px;
+    line-height: ${sizes.tiny}px;
+  `}
+
+  ${(props) => props.size === 'small' && css`
+    font-size: ${typography.size.s1}px;
+    line-height: ${sizes.small}px;
+  `}
+
+  ${(props) => props.size === 'large' && css`
+    font-size: ${typography.size.s3}px;
+    line-height: ${sizes.large}px;
+  `}
+`;
+
+/**
+ * Avatar component for displaying user profile images or initials
+ *
+ * @example
+ * ```tsx
+ * <Avatar username="John Doe" size="large" />
+ * <Avatar src="https://example.com/avatar.jpg" username="Jane Doe" />
+ * <Avatar loading username="Loading..." />
+ * ```
+ */
+export const Avatar = ({ loading = false, username = 'loading', src, size = 'medium', ...props }: AvatarProps) => {
+  let avatarFigure = <Icon icon="useralt" block={false} />;
+  const a11yProps: {
+    'aria-busy'?: boolean;
+    'aria-label'?: string;
+  } = {};
+
+  if (loading) {
+    a11yProps['aria-busy'] = true;
+    a11yProps['aria-label'] = 'Loading avatar ...';
+  } else if (src) {
+    avatarFigure = <img src={src} alt={username} />;
+  } else {
+    a11yProps['aria-label'] = username;
+    avatarFigure = (
+      <Initial size={size} aria-hidden="true">
+        {username.substring(0, 1)}
+      </Initial>
+    );
+  }
+
+  return (
+    <Image size={size} loading={loading} src={src} {...a11yProps} {...props}>
+      {avatarFigure}
+    </Image>
+  );
+};

package/src/Badge.stories.tsx

@@ -0,0 +1,87 @@
+import type { ReactNode } from 'react';
+import { Meta, StoryObj } from '@storybook/react-vite';
+
+import { Badge } from './Badge';
+import { Icon } from './Icon';
+
+const meta: Meta<typeof Badge> = {
+  title: 'Design System/Badge',
+  component: Badge,
+};
+
+import { expect } from '@storybook/jest';
+import { within } from '@storybook/testing-library';
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const AllBadges: Story = {
+  args: {
+    children: 'Badge',
+  },
+  render: (_args) => (
+    <div>
+      <Badge status="positive">Positive</Badge>
+      <Badge status="negative">Negative</Badge>
+      <Badge status="neutral">Neutral</Badge>
+      <Badge status="error">Error</Badge>
+      <Badge status="warning">Warning</Badge>
+      <Badge status="positive">
+        <Icon icon="facehappy" inline block={false} />
+        with icon
+      </Badge>
+    </div>
+  ),
+};
+
+export const Positive: Story = {
+  render: () => <Badge status="positive">Positive</Badge>,
+};
+export const Negative = () => <Badge status="negative">Negative</Badge>;
+export const Warning = () => <Badge status="warning">Warning</Badge>;
+export const Neutral = () => <Badge status="neutral">Neutral</Badge>;
+export const Error = () => <Badge status="error">Error</Badge>;
+
+interface BadgeArgs {
+  status?: 'positive' | 'negative' | 'neutral' | 'error' | 'warning';
+  children?: ReactNode;
+}
+
+interface IconArgs {
+  icon: string;
+  inline?: boolean;
+  block: boolean;
+}
+
+type WithIconArgs = BadgeArgs & IconArgs;
+
+export const WithIcon = (args: WithIconArgs) => (
+  <Badge {...args}>
+    <Icon {...args} />
+    with icon
+  </Badge>
+);
+WithIcon.args = {
+  status: 'warning',
+  icon: 'check',
+  inline: true,
+  block: false,
+};
+
+WithIcon.storyName = 'with icon';
+WithIcon.play = async ({ canvasElement }: { canvasElement: HTMLElement }) => {
+  const canvas = within(canvasElement);
+  const badge = canvas.getByText(/with icon/i);
+  expect(badge).toBeInTheDocument();
+  const icon = canvasElement.querySelector('svg');
+  expect(icon).toBeInTheDocument();
+};
+
+AllBadges.play = async ({ canvasElement }: { canvasElement: HTMLElement }) => {
+  const canvas = within(canvasElement);
+  expect(canvas.getByText('Positive')).toBeInTheDocument();
+  expect(canvas.getByText('Negative')).toBeInTheDocument();
+  expect(canvas.getByText('Neutral')).toBeInTheDocument();
+  expect(canvas.getByText('Error')).toBeInTheDocument();
+  expect(canvas.getByText('Warning')).toBeInTheDocument();
+};

package/src/Badge.tsx

@@ -0,0 +1,76 @@
+import styled, { css } from 'styled-components';
+import { background, color, typography } from './shared/styles';
+import { BadgeProps, BADGE_STATUSES, StatusProps } from './types';
+
+/**
+ * Styled badge wrapper with status-based styling
+ */
+const BadgeWrapper = styled.div<StatusProps>`
+  display: inline-block;
+  vertical-align: top;
+  font-size: 11px;
+  line-height: 12px;
+  padding: 4px 12px;
+  border-radius: 3em;
+  font-weight: ${typography.weight.bold};
+
+  svg {
+    height: 12px;
+    width: 12px;
+    margin-right: 4px;
+    margin-top: -2px;
+  }
+
+  ${(props) =>
+    props.status === BADGE_STATUSES.POSITIVE &&
+    css`
+      color: ${color.positive};
+      background: ${background.positive};
+    `};
+
+  ${(props) =>
+    props.status === BADGE_STATUSES.NEGATIVE &&
+    css`
+      color: ${color.negative};
+      background: ${background.negative};
+    `};
+
+  ${(props) =>
+    props.status === BADGE_STATUSES.WARNING &&
+    css`
+      color: ${color.warning};
+      background: ${background.warning};
+    `};
+
+  ${(props) =>
+    props.status === BADGE_STATUSES.ERROR &&
+    css`
+      color: ${color.lightest};
+      background: ${color.negative};
+    `};
+
+  ${(props) =>
+    props.status === BADGE_STATUSES.NEUTRAL &&
+    css`
+      color: ${color.dark};
+      background: ${color.mediumlight};
+    `};
+`;
+
+/**
+ * Badge component for displaying status indicators and labels
+ *
+ * @example
+ * ```tsx
+ * <Badge status="positive">Success</Badge>
+ * <Badge status="error">Error</Badge>
+ * <Badge>Default</Badge>
+ * ```
+ */
+export const Badge = ({ status = BADGE_STATUSES.NEUTRAL, children, ...props }: BadgeProps) => {
+  return (
+    <BadgeWrapper status={status} {...props}>
+      {children}
+    </BadgeWrapper>
+  );
+};