npm package: @oscarrf2/goo-ds
Description: A token-first React component library built with TypeScript and design tokens exported from Figma.
Latest version: 0.1.4

# @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.