@gv-tech/design-system 0.8.0

package/src/shared/styles.js

@@ -0,0 +1,98 @@
+import { css } from 'styled-components';
+
+// Global style variables
+export const background = {
+  app: '#F6F9FC',
+  appInverse: '#7A8997',
+  positive: '#E1FFD4',
+  negative: '#FEDED2',
+  warning: '#FFF5CF',
+};
+
+export const color = {
+  // Palette
+  primary: '#FF4785', // coral
+  secondary: '#1EA7FD', // ocean
+  tertiary: '#DDDDDD',
+
+  orange: '#FC521F',
+  gold: '#FFAE00',
+  green: '#66BF3C',
+  seafoam: '#37D5D3',
+  purple: '#6F2CAC',
+  ultraviolet: '#2A0481',
+
+  // Monochrome
+  lightest: '#FFFFFF',
+  lighter: '#F8F8F8',
+  light: '#F3F3F3',
+  mediumlight: '#EEEEEE',
+  medium: '#DDDDDD',
+  mediumdark: '#999999',
+  dark: '#666666',
+  darker: '#444444',
+  darkest: '#333333',
+
+  border: 'rgba(0,0,0,.1)',
+
+  // Status
+  positive: '#66BF3C',
+  negative: '#FF4400',
+  warning: '#E69D00',
+};
+
+export const spacing = {
+  padding: {
+    small: 10,
+    medium: 20,
+    large: 30,
+  },
+  borderRadius: {
+    small: 5,
+    default: 10,
+  },
+};
+
+export const typography = {
+  type: {
+    primary: '"Nunito Sans", "Helvetica Neue", Helvetica, Arial, sans-serif',
+    code: '"SFMono-Regular", Consolas, "Liberation Mono", Menlo, Courier, monospace',
+  },
+  weight: {
+    regular: '400',
+    bold: '700',
+    extrabold: '800',
+    black: '900',
+  },
+  size: {
+    s1: '12',
+    s2: '14',
+    s3: '16',
+    m1: '20',
+    m2: '24',
+    m3: '28',
+    l1: '32',
+    l2: '40',
+    l3: '48',
+    code: '90',
+  },
+};
+
+export const breakpoint = 600;
+export const pageMargin = '5.55555';
+
+export const pageMargins = css`
+  padding: 0 ${spacing.padding.medium}px;
+  @media (min-width: ${breakpoint * 1}px) {
+    margin: 0 ${pageMargin * 1}%;
+  }
+  @media (min-width: ${breakpoint * 2}px) {
+    margin: 0 ${pageMargin * 2}%;
+  }
+  @media (min-width: ${breakpoint * 3}px) {
+    margin: 0 ${pageMargin * 3}%;
+  }
+  @media (min-width: ${breakpoint * 4}px) {
+    margin: 0 ${pageMargin * 4}%;
+  }
+`;

package/src/test-utils/axe.ts

@@ -0,0 +1,25 @@
+import axe from 'axe-core';
+
+export async function assertNoA11yViolations(container: HTMLElement | Document) {
+  const results = await axe.run(container as unknown as Node);
+  if (results.violations && results.violations.length > 0) {
+    const messages = results.violations
+      .map((v: unknown) => {
+        const violation = v as {
+          id: string;
+          impact?: string | null;
+          help: string;
+          nodes: Array<{ target: string[]; failureSummary?: string; html?: string }>;
+        };
+
+        const nodes = violation.nodes
+          .map((n) => `  - ${n.target.join(', ')}: ${n.failureSummary || n.html || ''}`)
+          .join('\n');
+        return `${violation.id} (${violation.impact || 'unknown'}): ${violation.help}\n${nodes}`;
+      })
+      .join('\n\n');
+    throw new Error(`Accessibility violations detected:\n\n${messages}`);
+  }
+}
+
+export default assertNoA11yViolations;

package/src/types.ts

@@ -0,0 +1,316 @@
+/**
+ * Shared TypeScript types and utilities for the GVTech Design System
+ */
+
+import React from 'react';
+
+// =============================================================================
+// COMMON TYPES
+// =============================================================================
+
+/**
+ * Common HTML element attributes that can be extended by components
+ */
+export type HTMLAttributes<T = HTMLElement> = React.HTMLAttributes<T>;
+
+/**
+ * Common button element attributes
+ */
+export type ButtonHTMLAttributes = React.ButtonHTMLAttributes<HTMLButtonElement>;
+
+/**
+ * Common anchor element attributes
+ */
+export type AnchorHTMLAttributes = React.AnchorHTMLAttributes<HTMLAnchorElement>;
+
+/**
+ * Common input element attributes
+ */
+export type InputHTMLAttributes = React.InputHTMLAttributes<HTMLInputElement>;
+
+// =============================================================================
+// DESIGN SYSTEM CONSTANTS & TYPES
+// =============================================================================
+
+/**
+ * Available color values in the design system
+ */
+export type ColorValue =
+  | 'primary'
+  | 'secondary'
+  | 'tertiary'
+  | 'positive'
+  | 'negative'
+  | 'warning'
+  | 'error'
+  | 'neutral';
+
+/**
+ * Available size variants
+ */
+export type SizeVariant = 'small' | 'medium' | 'large' | 'tiny';
+
+/**
+ * Available appearance variants for buttons and similar components
+ */
+export type AppearanceVariant =
+  | 'primary'
+  | 'secondary'
+  | 'tertiary'
+  | 'outline'
+  | 'primaryOutline'
+  | 'secondaryOutline';
+
+/**
+ * Status variants for badges and status indicators
+ */
+export type StatusVariant = 'positive' | 'negative' | 'neutral' | 'error' | 'warning';
+
+// =============================================================================
+// BRANDED TYPES
+// =============================================================================
+
+/**
+ * Branded type for icon names to ensure type safety
+ */
+export type IconName = string & { readonly __brand: 'IconName' };
+
+/**
+ * Branded type for CSS color values
+ */
+export type CSSColor = string & { readonly __brand: 'CSSColor' };
+
+/**
+ * Branded type for pixel values
+ */
+export type PixelValue = number & { readonly __brand: 'PixelValue' };
+
+// =============================================================================
+// UTILITY TYPES
+// =============================================================================
+
+/**
+ * Extract the props type from a React component
+ */
+export type ComponentProps<T> = T extends React.ComponentType<infer P> ? P : never;
+
+/**
+ * Make all properties of T optional except for K
+ */
+export type RequiredKeys<T, K extends keyof T> = Omit<T, K> & Required<Pick<T, K>>;
+
+/**
+ * Make all properties of T nullable
+ */
+export type Nullable<T> = { [P in keyof T]: T[P] | null };
+
+/**
+ * Extract the children prop type
+ */
+export type ChildrenType = React.ReactNode;
+
+/**
+ * Common props that most components should accept
+ */
+export interface CommonProps {
+  /** Additional CSS classes */
+  className?: string;
+  /** Inline styles */
+  style?: React.CSSProperties;
+  /** Child elements */
+  children?: ChildrenType;
+}
+
+/**
+ * Props for components that can be disabled
+ */
+export interface DisableableProps {
+  /** Whether the component is disabled */
+  disabled?: boolean;
+}
+
+/**
+ * Props for components that can show loading state
+ */
+export interface LoadableProps {
+  /** Whether the component is in a loading state */
+  loading?: boolean;
+  /** Backwards-compatible alias used across the codebase */
+  isLoading?: boolean;
+  /** Text to display while loading */
+  loadingText?: string;
+}
+
+// =============================================================================
+// COMPONENT-SPECIFIC TYPES
+// =============================================================================
+
+/**
+ * Props for styled components that need size information
+ */
+export interface SizeableProps {
+  size?: SizeVariant;
+}
+
+/**
+ * Props for styled components that need appearance information
+ */
+export interface AppearanceProps {
+  appearance?: AppearanceVariant;
+}
+
+/**
+ * Props for styled components that need status information
+ */
+export interface StatusProps {
+  status?: StatusVariant;
+}
+
+/**
+ * Props for icon components
+ */
+export interface IconProps extends CommonProps, React.SVGProps<SVGSVGElement> {
+  /** The icon name/key */
+  icon: IconName | string;
+  /** Whether to display as a block element */
+  block?: boolean;
+  /** Whether to display as an inline-only variant */
+  inline?: boolean;
+}
+
+/**
+ * Props for avatar components
+ */
+export interface AvatarProps extends CommonProps, 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?: SizeVariant;
+}
+
+/**
+ * Props for badge components
+ */
+export interface BadgeProps extends CommonProps, HTMLAttributes<HTMLDivElement> {
+  /** Status variant that determines the badge styling */
+  status?: StatusVariant;
+}
+
+/**
+ * Props for button components
+ */
+export interface ButtonProps extends CommonProps, ButtonHTMLAttributes, DisableableProps, LoadableProps {
+  /** Visual appearance variant */
+  appearance?: AppearanceVariant;
+  /** Size variant */
+  size?: SizeVariant;
+  /** Whether the button contains only an icon */
+  containsIcon?: boolean;
+  /** Whether the button should render as a link */
+  isLink?: boolean;
+  /** Backwards-compatible aliases used in the codebase */
+  isLoading?: boolean;
+  isDisabled?: boolean;
+  isUnclickable?: boolean;
+  /** Custom wrapper component */
+  ButtonWrapper?: React.ComponentType<Record<string, unknown> & { children: React.ReactNode }>;
+}
+
+/**
+ * Props for link components
+ */
+export interface LinkProps extends CommonProps, AnchorHTMLAttributes {
+  /** Whether the link should render as a button */
+  isButton?: boolean;
+  /** Whether to show an arrow icon */
+  withArrow?: boolean;
+  /** Whether to use secondary styling */
+  secondary?: boolean;
+  /** Whether to use tertiary styling */
+  tertiary?: boolean;
+  /** Whether to remove default chrome/styling */
+  nochrome?: boolean;
+  /** Whether to use inverse colors */
+  inverse?: boolean;
+  /** Whether the link contains only an icon */
+  containsIcon?: boolean;
+  /** Custom wrapper component */
+  LinkWrapper?: React.ComponentType<Record<string, unknown> & { children: React.ReactNode }>;
+}
+
+// =============================================================================
+// CONSTANTS WITH PROPER TYPING
+// =============================================================================
+
+/**
+ * Button appearance constants
+ */
+export const BUTTON_APPEARANCES = {
+  PRIMARY: 'primary',
+  PRIMARY_OUTLINE: 'primaryOutline',
+  SECONDARY: 'secondary',
+  SECONDARY_OUTLINE: 'secondaryOutline',
+  TERTIARY: 'tertiary',
+  OUTLINE: 'outline',
+} as const;
+
+/**
+ * Button size constants
+ */
+export const BUTTON_SIZES = {
+  SMALL: 'small',
+  MEDIUM: 'medium',
+} as const;
+
+/**
+ * Badge status constants
+ */
+export const BADGE_STATUSES = {
+  POSITIVE: 'positive',
+  NEGATIVE: 'negative',
+  NEUTRAL: 'neutral',
+  ERROR: 'error',
+  WARNING: 'warning',
+} as const;
+
+/**
+ * Avatar size constants with pixel values
+ */
+export const AVATAR_SIZES = {
+  large: 40,
+  medium: 28,
+  small: 20,
+  tiny: 16,
+} as const;
+
+// =============================================================================
+// TYPE GUARDS
+// =============================================================================
+
+/**
+ * Type guard to check if a value is a valid size variant
+ */
+export function isSizeVariant(value: unknown): value is SizeVariant {
+  return typeof value === 'string' && ['small', 'medium', 'large', 'tiny'].includes(value);
+}
+
+/**
+ * Type guard to check if a value is a valid appearance variant
+ */
+export function isAppearanceVariant(value: unknown): value is AppearanceVariant {
+  return (
+    typeof value === 'string' &&
+    ['primary', 'secondary', 'tertiary', 'outline', 'primaryOutline', 'secondaryOutline'].includes(value)
+  );
+}
+
+/**
+ * Type guard to check if a value is a valid status variant
+ */
+export function isStatusVariant(value: unknown): value is StatusVariant {
+  return typeof value === 'string' && ['positive', 'negative', 'neutral', 'error', 'warning'].includes(value);
+}

package/tsconfig.build.json

@@ -0,0 +1,12 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "noEmit": false,
+    "declaration": true,
+    "emitDeclarationOnly": true,
+    "declarationMap": true,
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src"]
+}

package/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "lib": ["ES2020", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "noFallthroughCasesInSwitch": true
+  },
+  "include": ["src", ".storybook"],
+  "references": [{ "path": "./tsconfig.node.json" }]
+}

package/tsconfig.node.json

@@ -0,0 +1,10 @@
+{
+  "compilerOptions": {
+    "composite": true,
+    "skipLibCheck": true,
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "allowSyntheticDefaultImports": true
+  },
+  "include": ["vite.config.ts"]
+}

package/vite.config.ts

@@ -0,0 +1,35 @@
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import { resolve } from 'path';
+
+export default defineConfig({
+  plugins: [react()],
+  build: {
+    sourcemap: true,
+    lib: {
+      entry: resolve(__dirname, 'src/index.ts'),
+      name: 'GvtechDesign',
+      fileName: 'index',
+      formats: ['es', 'cjs'],
+    },
+    rollupOptions: {
+      external: ['react', 'react-dom', 'styled-components', 'polished', 'prop-types'],
+      output: {
+        globals: {
+          react: 'React',
+          'react-dom': 'ReactDOM',
+          'styled-components': 'styled',
+          polished: 'polished',
+          'prop-types': 'PropTypes',
+        },
+        manualChunks(id) {
+          if (id.includes('node_modules')) {
+            if (id.includes('axe-core')) return 'axe';
+            if (id.includes('react-docgen')) return 'docgen';
+            return 'vendor';
+          }
+        },
+      },
+    },
+  },
+});

package/vitest.config.ts

@@ -0,0 +1,13 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    setupFiles: './src/setupTests.ts',
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'lcov'],
+    },
+  },
+});