@gv-tech/design-system 0.8.0

package/.github/CODEOWNERS

@@ -0,0 +1,2 @@
+.github/CODEOWNERS @eng618
+* @eng618

package/.github/CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# Contributing Guidelines
+
+This project uses **Vite** for development and builds and **Storybook** for component documentation.
+
+## Available Scripts
+
+In the project directory, you can run:
+
+### `yarn dev`
+
+Runs the Vite development server for local development.<br />
+Open [http://localhost:5173](http://localhost:5173) (or the port Vite shows) to view it in the browser.
+
+The page will reload if you make edits, and HMR will update components instantly. You will also see any lint errors in the console.
+
+### `yarn test`
+
+Runs the test suite using **Vitest** (configured in `vitest.config.ts`). For interactive watch mode run `yarn test` locally; for CI the project uses `yarn test:ci`.
+
+See the Vitest docs for more information: https://vitest.dev/guide/.
+
+### `yarn build`
+
+Builds the library or production bundle using Vite (`yarn build`).
+
+For Storybook docs and component builds, run `yarn build-storybook` to generate Storybook static output.
+
+### Build configuration
+
+This project uses Vite for development and builds. If you need to customize build behavior, edit `vite.config.ts` or add Vite plugins. This project does not use `react-scripts` or `eject`.
+
+## Learn More
+
+- Vite docs: https://vitejs.dev/ (build, config and plugins)
+- Vitest docs: https://vitest.dev/ (testing guide)
+- Storybook docs: https://storybook.js.org/docs/react/get-started/introduction (component docs and addons)
+
+To customize build behavior edit `vite.config.ts` or add Vite plugins. For component docs and testing examples check the Storybook setup in `.storybook` and `src` stories.

package/.github/FUNDING.yml

@@ -0,0 +1,4 @@
+# Funding
+
+github: [eng618]
+custom: ["https://www.paypal.me/garciaericn"]

package/.github/PULL_REQUEST_TEMPLATE/build.md

@@ -0,0 +1,5 @@
+<!-- This PR is used for build and dependency changes -->
+
+# Build updates
+
+<!-- Describe what dependency changes are made, and how you have tested them. -->

package/.github/PULL_REQUEST_TEMPLATE/standard.md

@@ -0,0 +1,3 @@
+# Description
+
+<!-- Describe the contents of this PR in more detail here: -->

package/.github/RELEASING.md

@@ -0,0 +1,37 @@
+# Releasing & Publishing 🔁
+
+This document explains how releases and publishing are handled for this repository and how to test or modify the release flow.
+
+## Release Please (automated Release PRs)
+
+**Overview**
+
+- We use `googleapis/release-please-action` to create Release PRs and tags based on Conventional Commits.
+
+**One-time setup**
+
+1. Create a **Personal Access Token (PAT)** with `repo` (write) permissions and a short expiration.
+2. Add the PAT as a repository secret named `RELEASE_PLEASE_TOKEN` (Repository → Settings → Secrets and variables → Actions → New repository secret).
+3. Confirm branch protection rules allow the PAT or the actor to create tags/releases, or allow the bot account to bypass restrictions where necessary.
+
+**Testing**
+
+- Trigger the action manually: GitHub → Actions → _Release Please_ → _Run workflow_ → choose `main` and run.
+- A Release PR (usually titled `chore(release): release X.Y.Z`) should be created. Review the changelog and changes in the PR.
+- Merge the PR into `main` to create a tag/release. If using a PAT (not `GITHUB_TOKEN`), downstream workflows triggered by `release` events should run normally.
+
+**Notes**
+
+- Make sure your commits follow **Conventional Commits** to get meaningful changelogs and correct SemVer bumps.
+- If release PRs are not being created, confirm that the `RELEASE_PLEASE_TOKEN` is present and has proper repository permissions.
+
+## Publishing to npm (current process)
+
+- The CI publish step currently expects `NPM_TOKEN` as a repository secret (Stored in repository secrets as `NPM_TOKEN`).
+- Publishing will continue unchanged for now. In a later phase we will migrate to either OIDC or scoped automation tokens and switch the package name to `@gvtech/*` as part of the migration.
+
+## Troubleshooting & Tips
+
+- **Release PR not generated**: Confirm commits use Conventional Commit messages, check action logs, and ensure the PAT is set.
+- **Downstream workflows not running on release**: Ensure releases/tags are created with a PAT (not `GITHUB_TOKEN`), otherwise they won't trigger other workflows.
+- **Scoped package publishing**: If you plan to publish to a scope (e.g., `@gvtech`), update `package.json.name` and set `publishConfig.access` to `public` for public scoped packages.

package/.github/copilot-instructions.md

@@ -0,0 +1,93 @@
+# GVTech Design System - AI Coding Guidelines
+
+## Architecture Overview
+
+This is a React component library built with TypeScript, styled-components, and Vite. It provides reusable UI components (Avatar, Badge, Button, Icon, Link) for Garcia Ventures applications.
+
+**Key Structure:**
+
+- `src/` - Components and shared utilities
+- `src/shared/` - Design tokens (colors, typography, spacing), global styles, animations, icons
+- Components follow a pattern: `{Component}.tsx` + `{Component}.stories.tsx` for Storybook docs
+
+**Build System:**
+
+- Vite library build outputs ES modules and CommonJS
+- Externalizes React, styled-components, polished, prop-types
+- Use `yarn build` for production builds
+
+## Component Patterns
+
+**Styling:** Use styled-components with design tokens from `src/shared/styles.js`
+
+```tsx
+import styled from 'styled-components';
+import { color, typography } from './shared/styles';
+
+const StyledComponent = styled.div`
+  color: ${color.primary};
+  font-size: ${typography.size.s2}px;
+`;
+```
+
+**Props & Types:**
+
+- Define interfaces in `src/types.ts` using branded types for safety
+- Extend common HTML attributes: `interface ComponentProps extends HTMLAttributes<HTMLDivElement>`
+- Use constants like `BUTTON_APPEARANCES`, `BUTTON_SIZES` from types
+
+**Example Component Structure:**
+
+```tsx
+import React from 'react';
+import styled from 'styled-components';
+import { ComponentProps } from './types';
+
+interface MyComponentProps extends ComponentProps {
+  variant?: 'primary' | 'secondary';
+}
+
+const StyledDiv = styled.div<StyledDivProps>``;
+
+export const MyComponent: React.FC<MyComponentProps> = ({ variant, ...props }) => (
+  <StyledDiv variant={variant} {...props} />
+);
+```
+
+## Development Workflow
+
+- **Local dev:** `yarn storybook` (runs Storybook on port 9009)
+- **Build lib:** `yarn build` (outputs to `dist/`)
+- **Test:** `yarn test` (Vitest with jsdom, watch mode)
+- **Lint:** `yarn lint` (ESLint with TypeScript, auto-fix with `yarn lint:fix`)
+- **Format:** `yarn format` (Prettier)
+
+**Testing Setup:**
+
+- Uses `@testing-library/react` and `@testing-library/jest-dom`
+- Auto-imports via `src/setupTests.ts`
+- Run `yarn test:ci` for CI (non-interactive)
+
+## Key Conventions
+
+- **Imports:** Group external libs, then internal shared, then types
+- **Naming:** PascalCase for components, camelCase for props
+- **Styling:** Prefer design tokens over hardcoded values
+- **Type Safety:** Use branded types (e.g., `IconName`, `CSSColor`) for runtime validation
+- **Stories:** Write comprehensive Storybook stories with controls and interactions
+
+**Shared Utilities:**
+
+- `styles` - Colors, spacing, typography
+- `global` - Global CSS resets
+- `animation` - Easing functions, keyframes
+- `icons` - Icon components and names
+
+## Integration Points
+
+- **Storybook:** Used for component development and documentation
+- **Vite:** Handles build, dev server, and library bundling
+- **ESLint + Prettier:** Code quality with custom configs
+- **Husky:** Git hooks for pre-commit checks
+
+Reference `src/Button.tsx` and `src/types.ts` for implementation examples.

package/.github/workflows/ci.yml

@@ -0,0 +1,82 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  fossa-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - name: "Checkout Code"
+        uses: actions/checkout@v6
+
+      - name: "Run FOSSA Scan"
+        uses: fossas/fossa-action@main # Use a specific version if locking is preferred
+        with:
+          api-key: ${{ secrets.FOSSA_API_KEY }}
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        node: ["20", "22", "24"]
+    steps:
+      - uses: actions/checkout@v6
+      - name: Use Node.js ${{ matrix.node }}
+        uses: actions/setup-node@v6
+        with:
+          node-version: ${{ matrix.node }}
+          cache: "yarn"
+
+      - name: Cache Yarn (optional extra)
+        uses: actions/cache@v4
+        with:
+          path: |
+            .yarn/cache
+            .yarn/unplugged
+            .yarn/build-state.yml
+            .yarn/install-state.gz
+          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-yarn-
+
+      - name: Install dependencies
+        run: yarn install
+
+      - name: Format
+        run: yarn format:ci
+
+      - name: Lint
+        run: yarn lint
+
+      - name: Run Tests
+        run: yarn test:ci
+
+  build:
+    runs-on: ubuntu-latest
+    needs: [test]
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Use Node.js 24
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          cache: "yarn"
+
+      - name: Install dependencies
+        run: yarn install --immutable
+
+      - name: Build
+        run: yarn build
+
+      - name: Build Storybook
+        run: yarn build-storybook
+
+      - name: Build Storybook Docs
+        run: yarn build-storybook-docs
+
+      - name: Install Playwright Browsers
+        run: npx playwright install --with-deps
+
+      - name: Run Storybook Tests
+        run: yarn test-storybook:ci

package/.github/workflows/codeql-analysis.yml

@@ -0,0 +1,34 @@
+name: "CodeQL"
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "34 7 * * 4"
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language: ["javascript"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v2
+        with:
+          languages: ${{ matrix.language }}
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v2
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v2

package/.github/workflows/release-please.yml

@@ -0,0 +1,53 @@
+name: Release Please
+
+on:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  id-token: write # For OIDC trusted publishing
+  contents: write # For tags and releases
+  pull-requests: write # For creating release PRs
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Run release-please
+        id: release
+        uses: googleapis/release-please-action@v4.4
+        with:
+          release-type: node
+          # Use a PAT with repo scopes; set as repository secret `RELEASE_PLEASE_TOKEN`
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Show notice
+        run: echo "If a release PR is created, review and merge it to create a tag/release."
+
+      - name: Checkout Code
+        if: ${{ steps.release.outputs.release_created }}
+        uses: actions/checkout@v6
+
+      - name: Use Node.js 24
+        if: ${{ steps.release.outputs.release_created }}
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+          registry-url: 'https://registry.npmjs.org'
+          cache: 'yarn'
+
+      - name: Install dependencies
+        if: ${{ steps.release.outputs.release_created }}
+        run: yarn install --immutable
+
+      - name: Build
+        if: ${{ steps.release.outputs.release_created }}
+        run: yarn build
+
+      - name: Publish to npm
+        if: ${{ steps.release.outputs.release_created }}
+        run: npm publish --provenance

package/.husky/pre-commit

@@ -0,0 +1 @@
+npx lint-staged

package/.nvmrc

@@ -0,0 +1 @@
+24

package/.prettierignore

@@ -0,0 +1 @@
+CHANGELOG.md

package/.storybook/.preview-head.html

@@ -0,0 +1 @@
+<link rel="stylesheet" href="https://fonts.googleapis.com/css?family=Nunito+Sans:400,700,800,900" />

package/.storybook/main.ts

@@ -0,0 +1,38 @@
+import type { UserConfig } from 'vite';
+import type { StorybookConfig } from '@storybook/react-vite';
+
+export default {
+  stories: ['../src/Intro.stories.tsx', '../src/**/*.stories.@(js|jsx|ts|tsx|mdx)'],
+  staticDirs: [{ from: '../public', to: '/public' }],
+  addons: ['@storybook/addon-links', '@storybook/addon-a11y', '@storybook/addon-docs'],
+
+  framework: {
+    name: '@storybook/react-vite',
+    options: {
+      typescript: {
+        check: true,
+        // Use react-docgen-typescript for TypeScript prop documentation in Vite-based Storybook
+        // This leverages Storybook's built-in integration instead of the webpack-only plugin
+        reactDocgen: 'react-docgen-typescript',
+        reactDocgenTypescriptOptions: {
+          shouldExtractLiteralValuesFromEnum: true,
+          shouldRemoveUndefinedFromOptional: true,
+          propFilter: (prop: unknown) => {
+            const p = prop as { parent?: { fileName?: string } } | undefined;
+            return p?.parent ? !/node_modules/.test(p.parent.fileName || '') : true;
+          },
+        },
+      },
+    },
+  },
+
+  features: {
+    interactionsDebugger: true,
+  },
+
+  async viteFinal(config: UserConfig) {
+    // Use the project's Vite config as-is to avoid duplicating or re-injecting runtime plugins
+    // (adding the project's `react()` plugin here previously caused duplicate injections)
+    return config;
+  },
+} as StorybookConfig;

package/.storybook/preview.tsx

@@ -0,0 +1,30 @@
+import React from 'react';
+import type { StoryFn, Preview, StoryContext } from '@storybook/react';
+import { GlobalStyle } from '../src/shared/global';
+
+export const decorators: Preview['decorators'] = [
+  (Story: StoryFn, context: StoryContext) => (
+    <>
+      <GlobalStyle />
+      {Story(context.args, context)}
+    </>
+  ),
+];
+
+export const parameters: Preview['parameters'] = {
+  actions: { argTypesRegex: '^on[A-Z].*' },
+  controls: {
+    matchers: {
+      color: /(background|color)$/i,
+      date: /Date$/,
+    },
+  },
+  docs: {
+    codePanel: true,
+  },
+  a11y: {
+    config: {},
+    options: {},
+  },
+};
+export const tags: string[] = ['autodocs'];

package/.tool-versions

@@ -0,0 +1 @@
+nodejs 22.21.1

package/.vscode/launch.json

@@ -0,0 +1,22 @@
+{
+  // Use IntelliSense to learn about possible attributes.
+  // Hover to view descriptions of existing attributes.
+  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "type": "chrome",
+      "request": "launch",
+      "name": "React app",
+      "url": "http://localhost:3000",
+      "webRoot": "${workspaceFolder}"
+    },
+    {
+      "type": "chrome",
+      "request": "launch",
+      "name": "Storybook",
+      "url": "http://localhost:6006",
+      "webRoot": "${workspaceFolder}"
+    }
+  ]
+}

package/.vscode/settings.json

@@ -0,0 +1,30 @@
+{
+  "workbench.colorCustomizations": {
+    "activityBar.background": "#696969",
+    "activityBar.activeBorder": "#40bf40",
+    "activityBar.foreground": "#e7e7e7",
+    "activityBar.inactiveForeground": "#e7e7e799",
+    "activityBarBadge.background": "#40bf40",
+    "activityBarBadge.foreground": "#15202b",
+    "titleBar.activeBackground": "#505050",
+    "titleBar.inactiveBackground": "#50505099",
+    "titleBar.activeForeground": "#e7e7e7",
+    "titleBar.inactiveForeground": "#e7e7e799",
+    "statusBar.background": "#505050",
+    "statusBarItem.hoverBackground": "#696969",
+    "statusBar.foreground": "#e7e7e7",
+    "activityBar.activeBackground": "#696969",
+    "sash.hoverBorder": "#696969",
+    "statusBarItem.remoteBackground": "#505050",
+    "statusBarItem.remoteForeground": "#e7e7e7",
+    "commandCenter.border": "#e7e7e799"
+  },
+  "peacock.color": "#505050",
+  "spellright.language": ["en"],
+  "spellright.documentTypes": ["markdown", "latex", "plaintext", "json", "jsonc", "mdx", "javascript", "html"],
+  "spellright.parserByClass": {
+    "mdx": {
+      "parser": "plain"
+    }
+  }
+}