@oscarrf2/goo-ds 0.1.0

package/README.md

@@ -0,0 +1,163 @@
+# @oscarrf2/goo-ds
+
+A token-first React component library built with TypeScript and design tokens exported from Figma.
+
+## Installation
+
+```bash
+npm install @oscarrf2/goo-ds
+# or
+pnpm add @oscarrf2/goo-ds
+# or
+yarn add @oscarrf2/goo-ds
+```
+
+## Quick Start
+
+### 1. Import Styles
+
+Import the design system styles once in your app root:
+
+```tsx
+// In Next.js app/layout.tsx
+import '@oscarrf2/goo-ds/styles.css';
+
+// In Vite/React src/main.tsx
+import '@oscarrf2/goo-ds/styles.css';
+```
+
+### 2. Use Components
+
+```tsx
+import { Button, CoreText, Spacer } from '@oscarrf2/goo-ds';
+
+function App() {
+  return (
+    <div>
+      <CoreText variant="heading-lg-bold">Hello World</CoreText>
+      <Spacer size="24" />
+      <Button variant="primary" size="medium" onClick={() => alert('Clicked!')}>
+        Click Me
+      </Button>
+    </div>
+  );
+}
+```
+
+## Available Components
+
+- **Button** - Versatile button with variants (primary, secondary, tertiary, ghost) and sizes
+- **CoreText** - Typography component with text styles from design tokens
+- **Spacer** - Layout spacing component
+- **Divider** - Horizontal/vertical divider
+- **Sidebar** / **SidebarItem** - Navigation sidebar components
+- **Skeleton** - Loading skeleton with animation
+- **Table** / **TableRow** / **Cell** - Table components
+- **Tabs** / **TabItem** - Tab navigation
+- **Codeblock** - Code display with syntax highlighting
+- **InputImage** - Image input with drag-and-drop and comparison slider
+
+## Token-First Architecture
+
+All visual styling comes from design tokens:
+
+- **Global tokens** - Base color and size values
+- **Semantic tokens** - Contextual aliases (e.g., `--color-text-primary`)
+- **Number tokens** - Spacing and sizing scales
+- **Typography tokens** - Font families, sizes, line heights
+- **Component tokens** - Component-specific styling
+- **Style tokens** - Text styles, gradients, effects
+
+### Custom Theming
+
+To create a custom theme, copy the component tokens file and modify values:
+
+```bash
+# Copy default tokens
+cp node_modules/@oscarrf2/goo-ds/src/styles/component-tokens.css ./src/styles/my-theme.css
+
+# Edit my-theme.css with your brand colors
+```
+
+Then import your custom tokens instead of the default:
+
+```tsx
+// Import individual token layers + your custom component tokens
+import '@oscarrf2/goo-ds/styles/fonts.css';
+import '@oscarrf2/goo-ds/styles/global-tokens.css';
+import '@oscarrf2/goo-ds/styles/semantic-tokens.css';
+import '@oscarrf2/goo-ds/styles/number-tokens.css';
+import '@oscarrf2/goo-ds/styles/typography-tokens.css';
+import '@oscarrf2/goo-ds/styles/style-tokens.css';
+import './styles/my-theme.css'; // Your custom component tokens
+```
+
+All component token files must define the same CSS variable names - only values should differ.
+
+## TypeScript Support
+
+Full TypeScript definitions are included. All components are fully typed with prop interfaces.
+
+```tsx
+import type { ButtonProps } from '@oscarrf2/goo-ds';
+
+const MyButton: React.FC<ButtonProps> = (props) => {
+  return <Button {...props} />;
+};
+```
+
+## Requirements
+
+- **React**: 19.0.0 or higher
+- **React DOM**: 19.0.0 or higher
+
+## Browser Support
+
+Modern browsers with CSS custom properties support:
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+
+## Documentation
+
+Full documentation with interactive examples (coming soon).
+
+## Component Extension
+
+All components support standard React patterns for extension:
+
+```tsx
+// Event handler extension
+<Button onClick={() => trackEvent('click')}>Click Me</Button>
+
+// Wrapper components
+function AnalyticsButton({ analyticsId, ...props }) {
+  const handleClick = (e) => {
+    trackButtonClick(analyticsId);
+    props.onClick?.(e);
+  };
+  return <Button {...props} onClick={handleClick} />;
+}
+
+// Composition
+function FormActions({ onSave, onCancel }) {
+  return (
+    <>
+      <Button variant="secondary" onClick={onCancel}>Cancel</Button>
+      <Spacer size="md" />
+      <Button variant="primary" onClick={onSave}>Save</Button>
+    </>
+  );
+}
+```
+
+## License
+
+MIT
+
+## Version
+
+0.1.0 - Pre-1.0 Release
+
+This is an early release. APIs may change in future versions. The package is functional but some features are still being refined.

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@oscarrf2/goo-ds",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./styles.css": "./src/styles.css"
+  },
+  "files": [
+    "src/**/*.ts",
+    "src/**/*.tsx",
+    "src/**/*.css",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/App.tsx",
+    "!src/App.css",
+    "!src/main.tsx",
+    "!src/assets",
+    "README.md"
+  ],
+  "dependencies": {
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.1",
+    "@playwright/test": "^1.57.0",
+    "@tailwindcss/vite": "^4.1.18",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.1",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/node": "^24.10.1",
+    "@types/react": "^19.2.5",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^5.1.1",
+    "@vitest/ui": "^4.0.17",
+    "eslint": "^9.39.1",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-refresh": "^0.4.24",
+    "globals": "^16.5.0",
+    "identity-obj-proxy": "^3.0.0",
+    "jsdom": "^26.1.0",
+    "playwright": "^1.57.0",
+    "tailwindcss": "^4.1.18",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.46.4",
+    "vite": "^7.2.4",
+    "vitest": "^4.0.17"
+  },
+  "scripts": {
+    "dev": "vite",
+    "build": "tsc -b && vite build",
+    "lint": "eslint .",
+    "preview": "vite preview",
+    "test": "vitest",
+    "test:e2e": "playwright test"
+  }
+}

package/src/components/Button/Button.css

@@ -0,0 +1,107 @@
+/**
+ * Button component styles
+ * Token-driven button styling for the goo-ds design system
+ */
+
+.gds-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--btn-gap);
+  padding: var(--btn-padding-v) var(--btn-padding-h);
+  min-height: var(--btn-min-height);
+  border-radius: var(--btn-radius);
+  border: var(--btn-stroke-width) solid var(--btn-stroke);
+  background-color: var(--btn-background);
+  color: var(--btn-text);
+  font-family: var(--coreText-family-primary);
+  font-size: var(--btn-font-size);
+  font-weight: var(--font-weight-medium);
+  line-height: var(--btn-line-height);
+  cursor: pointer;
+  transition: all 0.2s ease;
+  user-select: none;
+  text-decoration: none;
+}
+
+.gds-button-icon-only {
+  min-width: var(--btn-min-width);
+}
+
+.gds-button:hover:not(:disabled) {
+  background-color: var(--btn-background-hover);
+  border-color: var(--btn-stroke-hover);
+}
+
+.gds-button:active:not(:disabled) {
+  background-color: var(--btn-background-pressed);
+}
+
+.gds-button:disabled {
+  background-color: var(--btn-background-disabled);
+  border-color: var(--btn-stroke-disabled);
+  color: var(--btn-text-disabled);
+  cursor: not-allowed;
+  opacity: 0.6;
+}
+
+.gds-button:disabled .gds-button-icon {
+  color: var(--btn-icon-disabled);
+}
+
+.gds-button:focus-visible {
+  outline: 2px solid var(--color-stroke-focus);
+  outline-offset: 2px;
+}
+
+.gds-button-text {
+  white-space: nowrap;
+}
+
+.gds-button-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  color: var(--btn-icon);
+}
+
+/* Link variant special styling */
+.gds-button-link {
+  background-color: transparent;
+  border-color: transparent;
+  padding-left: 0;
+  padding-right: 0;
+  text-decoration: underline;
+}
+
+.gds-button-link:hover:not(:disabled) {
+  background-color: transparent;
+  border-color: transparent;
+  text-decoration: none;
+}
+
+/* Ghost variant special styling */
+.gds-button-ghost {
+  background-color: transparent;
+  border-color: transparent;
+}
+
+.gds-button-ghost:hover:not(:disabled) {
+  border-color: transparent;
+}
+
+.gds-button-ghost:active:not(:disabled) {
+  border-color: transparent;
+}
+
+.gds-button-ghost:disabled {
+  border-color: transparent;
+}
+
+/* Respect user's motion preferences */
+@media (prefers-reduced-motion: reduce) {
+  .gds-button {
+    transition: none;
+  }
+}

package/src/components/Button/Button.tsx

@@ -0,0 +1,82 @@
+import type { ButtonProps } from "./Button.types";
+import "./Button.css";
+
+/**
+ * Button - Interactive button component for the goo-ds design system
+ *
+ * Provides consistent button styles with multiple variants, sizes, and states.
+ * Supports icons, disabled state, and all standard button interactions.
+ * Token-first per Constitution (no hardcoded values).
+ *
+ * @example
+ * ```tsx
+ * <Button>Click me</Button>
+ * <Button variant="secondary" size="small">Small button</Button>
+ * <Button variant="destructive" disabled>Disabled</Button>
+ * <Button iconLeft={<PlusIcon />}>With icon</Button>
+ * ```
+ */
+export function Button({
+  variant = "primary",
+  size = "medium",
+  iconLeft,
+  iconRight,
+  disabled = false,
+  children,
+  className = "",
+  type = "button",
+  ...props
+}: ButtonProps) {
+  const hasIcons = iconLeft || iconRight;
+  const isIconOnly = hasIcons && !children;
+
+  // Build CSS custom properties for the button variant
+  const buttonVars = {
+    "--btn-background": `var(--button-${variant}-background-default)`,
+    "--btn-background-hover": `var(--button-${variant}-background-hover, var(--button-${variant}-background-default))`,
+    "--btn-background-pressed": `var(--button-${variant}-background-pressed, var(--button-${variant}-background-default))`,
+    "--btn-background-disabled": `var(--button-${variant}-background-disabled, var(--button-${variant}-background-default))`,
+    "--btn-text": `var(--button-${variant}-text-default)`,
+    "--btn-text-disabled": `var(--button-${variant}-text-disabled, var(--button-${variant}-text-default))`,
+    "--btn-icon": `var(--button-${variant}-icon-default)`,
+    "--btn-icon-disabled": `var(--button-${variant}-icon-disabled, var(--button-${variant}-icon-default))`,
+    "--btn-stroke": `var(--button-${variant}-stroke-default, transparent)`,
+    "--btn-stroke-hover": `var(--button-${variant}-stroke-hover, var(--button-${variant}-stroke-default, transparent))`,
+    "--btn-stroke-disabled": `var(--button-${variant}-stroke-disabled, var(--button-${variant}-stroke-default, transparent))`,
+  } as React.CSSProperties;
+
+  // Size-dependent layout tokens
+  const buttonType = isIconOnly ? "icon" : "cta";
+  const sizeKey = size === "extraSmall" ? "extraSmall" : size;
+
+  const layoutVars = {
+    "--btn-gap": `var(--button-${sizeKey}-${buttonType}-gap)`,
+    "--btn-padding-v": `var(--button-${sizeKey}-${buttonType}-paddingVertical)`,
+    "--btn-padding-h": `var(--button-${sizeKey}-${buttonType}-paddingHorizontal)`,
+    "--btn-min-height": `var(--button-${sizeKey}-${buttonType}-minHeight)`,
+    "--btn-radius": `var(--button-${sizeKey}-${buttonType}-radius)`,
+    "--btn-stroke-width": `var(--button-${sizeKey}-${buttonType}-strokeWidth)`,
+    "--btn-min-width": isIconOnly ? `var(--button-${sizeKey}-${buttonType}-minWidth)` : "auto",
+    "--btn-font-size": `var(--font-size-${size === "large" ? "md" : size === "medium" ? "sm" : "xs"})`,
+    "--btn-line-height": `var(--font-lineHeight-${size === "large" ? "md" : size === "medium" ? "sm" : "xs"})`,
+  } as React.CSSProperties;
+
+  return (
+    <button
+      type={type}
+      disabled={disabled}
+      className={`gds-button gds-button-${variant} gds-button-${size} ${isIconOnly ? "gds-button-icon-only" : ""} ${className}`.trim()}
+      style={{ ...buttonVars, ...layoutVars }}
+      data-component="Button"
+      data-variant={variant}
+      data-size={size}
+      {...props}
+    >
+      {iconLeft && <span className="gds-button-icon gds-button-icon-left">{iconLeft}</span>}
+      {children && <span className="gds-button-text">{children}</span>}
+      {iconRight && <span className="gds-button-icon gds-button-icon-right">{iconRight}</span>}
+    </button>
+  );
+}
+
+export default Button;

package/src/components/Button/Button.types.ts

@@ -0,0 +1,62 @@
+import type { ReactNode } from "react";
+
+/**
+ * Button component props
+ * Provides interactive buttons using design system tokens
+ */
+
+export type ButtonVariant =
+  | "primary"
+  | "secondary"
+  | "destructive"
+  | "outline"
+  | "ghost"
+  | "link";
+
+export type ButtonSize = "extraSmall" | "small" | "medium" | "large";
+
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  /**
+   * The visual style variant of the button
+   * @default "primary"
+   */
+  variant?: ButtonVariant;
+
+  /**
+   * The size of the button
+   * @default "medium"
+   */
+  size?: ButtonSize;
+
+  /**
+   * Icon to display before the text
+   */
+  iconLeft?: ReactNode;
+
+  /**
+   * Icon to display after the text
+   */
+  iconRight?: ReactNode;
+
+  /**
+   * Whether the button is disabled
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Button content (text or other elements)
+   */
+  children?: ReactNode;
+
+  /**
+   * Additional CSS class names
+   */
+  className?: string;
+
+  /**
+   * Button type attribute
+   * @default "button"
+   */
+  type?: "button" | "submit" | "reset";
+}

package/src/components/Button/index.ts

@@ -0,0 +1,3 @@
+export { Button } from "./Button";
+export type { ButtonProps, ButtonVariant, ButtonSize } from "./Button.types";
+export { default } from "./Button";

package/src/components/Cell/Cell.css

@@ -0,0 +1,64 @@
+/**
+ * Cell component styles
+ * Token-driven table cell styling for the goo-ds design system
+ */
+
+.gds-cell {
+  box-sizing: border-box;
+  padding: var(--table-cell-paddingVertical) var(--table-cell-paddingHorizontal);
+  vertical-align: top;
+  
+  /* Typography - body-sm-regular */
+  font-family: var(--coreText-family-primary);
+  font-size: var(--font-size-sm);
+  font-weight: var(--font-weight-regular);
+  line-height: var(--font-lineHeight-sm);
+}
+
+/* Header cell - secondary color */
+.gds-cell-header {
+  color: var(--coreText-text-secondary-default);
+}
+
+/* Body cell - primary color */
+.gds-cell-body {
+  color: var(--coreText-text-primary-default);
+}
+
+/* Alignment */
+.gds-cell-align-left {
+  text-align: left;
+}
+
+.gds-cell-align-center {
+  text-align: center;
+}
+
+.gds-cell-align-right {
+  text-align: right;
+}
+
+/* Width presets */
+.gds-cell-width-xs {
+  width: var(--table-cell-width-xs);
+}
+
+.gds-cell-width-sm {
+  width: var(--table-cell-width-sm);
+}
+
+.gds-cell-width-md {
+  width: var(--table-cell-width-md);
+}
+
+.gds-cell-width-lg {
+  width: var(--table-cell-width-lg);
+}
+
+.gds-cell-width-xl {
+  width: var(--table-cell-width-xl);
+}
+
+.gds-cell-width-fill {
+  width: auto;
+}

package/src/components/Cell/Cell.tsx

@@ -0,0 +1,42 @@
+import type { CellProps } from "./Cell.types";
+import "./Cell.css";
+
+/**
+ * Cell - Table cell component for the goo-ds design system
+ *
+ * Provides consistent table cell layout with alignment and width presets.
+ * Designed to be used within table structures.
+ * Token-first per Constitution (no hardcoded values).
+ *
+ * @example
+ * ```tsx
+ * <Cell type="header">Name</Cell>
+ * <Cell>John Doe</Cell>
+ * <Cell alignment="right" width="sm">$100</Cell>
+ * ```
+ */
+export function Cell({
+  type = "body",
+  alignment = "left",
+  width = "md",
+  children,
+  className = "",
+  ...props
+}: CellProps) {
+  const Tag = type === "header" ? "th" : "td";
+  
+  return (
+    <Tag
+      className={`gds-cell gds-cell-${type} gds-cell-align-${alignment} gds-cell-width-${width} ${className}`.trim()}
+      data-component="Cell"
+      data-type={type}
+      data-alignment={alignment}
+      data-width={width}
+      {...props}
+    >
+      {children}
+    </Tag>
+  );
+}
+
+export default Cell;

package/src/components/Cell/Cell.types.ts

@@ -0,0 +1,42 @@
+import type { ReactNode } from "react";
+
+/**
+ * Cell component props
+ * Provides table cell layout using design system tokens
+ */
+
+export type CellType = "header" | "body";
+
+export type CellAlignment = "left" | "center" | "right";
+
+export type CellWidth = "xs" | "sm" | "md" | "lg" | "xl" | "fill";
+
+export interface CellProps extends React.HTMLAttributes<HTMLDivElement> {
+  /**
+   * The type of cell (header or body)
+   * @default "body"
+   */
+  type?: CellType;
+
+  /**
+   * Horizontal alignment of cell content
+   * @default "left"
+   */
+  alignment?: CellAlignment;
+
+  /**
+   * Width preset for the cell
+   * @default "md"
+   */
+  width?: CellWidth;
+
+  /**
+   * Cell content
+   */
+  children?: ReactNode;
+
+  /**
+   * Additional CSS class names
+   */
+  className?: string;
+}

package/src/components/Cell/index.ts

@@ -0,0 +1,3 @@
+export { Cell } from "./Cell";
+export type { CellProps, CellType, CellAlignment, CellWidth } from "./Cell.types";
+export { default } from "./Cell";