# Orange Design System (ODS)

> A framework-agnostic, accessible component library built with vanilla JavaScript, CSS/SCSS, and optional React wrappers.

[![NPM](https://img.shields.io/npm/v/@orangesk/orange-design-system)](https://www.npmjs.com/package/@orangesk/orange-design-system)
[![Node](https://img.shields.io/badge/node->=20.x-green)](https://nodejs.org)

## 📚 Table of Contents

- [Orange Design System (ODS)](#orange-design-system-ods)
  - [📚 Table of Contents](#-table-of-contents)
  - [Overview](#overview)
    - [Architecture](#architecture)
  - [Key Features](#key-features)
  - [Installation](#installation)
    - [Requirements](#requirements)
  - [Quick Start](#quick-start)
    - [React](#react)
    - [Vanilla JavaScript](#vanilla-javascript)
    - [CSS Only](#css-only)
  - [Documentation](#documentation)
    - [Documentation Sections](#documentation-sections)
    - [Component Documentation Format](#component-documentation-format)
  - [Development](#development)
    - [Setup](#setup)
    - [Development Server](#development-server)
    - [Building](#building)
    - [Testing](#testing)
    - [Linting](#linting)
    - [File Structure](#file-structure)
  - [Contributing](#contributing)
    - [Code Standards](#code-standards)
    - [Component Guidelines](#component-guidelines)
  - [Support](#support)
    - [Resources](#resources)
    - [Getting Help](#getting-help)
  - [Changelog](#changelog)

## Overview

Orange Design System (ODS) is a comprehensive component library designed to work **outside of React** as the primary use case. React is used only for documentation and templating, making ODS truly framework-agnostic.

### Architecture

ODS components follow a three-layer architecture:

```
┌─────────────────────────────────────────┐
│  Your Application                       │
│  (React, Vue, Angular, Vanilla JS, etc.)│
└──────────────┬──────────────────────────┘
               │
               ├─ React Components (optional)
               │  └─ .tsx wrappers
               │
               ├─ Vanilla JavaScript (core)
               │  └─ .static.ts classes
               │
               └─ CSS/SCSS Styles
                  └─ BEM naming, design tokens
```

**Core:** Vanilla JavaScript + CSS/SCSS  
**Optional:** React wrappers for convenient React integration  
**Styling:** CSS custom properties (design tokens) with responsive breakpoints

## Key Features

✅ **Framework Agnostic** - Use in React, Vue, Angular, or vanilla JavaScript  
✅ **Vanilla JavaScript Core** - No framework dependencies required  
✅ **Accessible** - WCAG compliant components with ARIA attributes  
✅ **Responsive** - Mobile-first design with breakpoint system  
✅ **Themable** - CSS custom properties for easy customization  
✅ **Type Safe** - Full TypeScript support  
✅ **Performance Focused** - Lightweight, modular bundles  
✅ **Well Documented** - Comprehensive documentation with live previews

## Installation

```bash
npm install @orangesk/orange-design-system
# or
yarn add @orangesk/orange-design-system
# or
pnpm add @orangesk/orange-design-system
```

### Requirements

- **Node.js:** >= 20.x
- **Package Manager:** npm, yarn, or pnpm

## Quick Start

### React

```tsx
import { Button } from "@orangesk/orange-design-system";

export default function App() {
  return (
    <Button type="primary" onClick={() => alert("Clicked!")}>
      Click Me
    </Button>
  );
}
```

**Interactive Components** with JavaScript behavior:

```tsx
import { Accordion, AccordionItem } from "@orangesk/orange-design-system";

export default function MyAccordion() {
  return (
    <Accordion>
      <AccordionItem headingLevel={3}>
        <button>Section 1</button>
        <div>Content goes here</div>
      </AccordionItem>
    </Accordion>
  );
}
```

The React component automatically instantiates the vanilla JavaScript class for you.

### Vanilla JavaScript

ODS components work perfectly without React:

```html
<!DOCTYPE html>
<html>
  <head>
    <link
      rel="stylesheet"
      href="node_modules/@orangesk/orange-design-system/build/lib/components.css"
    />
  </head>
  <body>
    <!-- HTML Structure -->
    <div class="accordion" id="myAccordion">
      <button
        class="accordion__button"
        data-accordion-toggle
        aria-expanded="false"
        aria-controls="panel-1"
      >
        Section 1
      </button>
      <div id="panel-1" hidden>Content here</div>
    </div>

    <!-- Instantiate JavaScript -->
    <script type="module">
      import Accordion from "@orangesk/orange-design-system/build/components/Accordion/Accordion.static.js";

      const accordionEl = document.getElementById("myAccordion");
      const accordion = new Accordion(accordionEl, {
        buttonSelector: "[data-accordion-toggle]",
      });
    </script>
  </body>
</html>
```

### CSS Only

Many components are CSS-only and don't require JavaScript:

```html
<link
  rel="stylesheet"
  href="node_modules/@orangesk/orange-design-system/build/lib/components.css"
/>

<!-- Button -->
<button class="button button--primary">Click Me</button>

<!-- Badge -->
<span class="badge badge--success">Active</span>

<!-- Card -->
<div class="card">
  <div class="card__section">
    <h3>Title</h3>
    <p>Description</p>
  </div>
</div>

<!-- Grid -->
<div class="grid grid--3">
  <div class="grid__col">Column 1</div>
  <div class="grid__col">Column 2</div>
  <div class="grid__col">Column 3</div>
</div>
```

## Documentation

**📖 Full documentation**: [https://ods2.lb.sk](https://ods2.lb.sk)

### Documentation Sections

- **[Getting Started](https://ods2.lb.sk/getting-started)** - Installation, setup, and resources
- **[Fundamentals](https://ods2.lb.sk/fundamentals)** - Accessibility, breakpoints, color, tokens, spacing, typography
- **[Components](https://ods2.lb.sk/components)** - Full component library with examples and API docs
- **[Copy](https://ods2.lb.sk/copy)** - Tone of voice, form validation, form labels, CTA guidelines
- **[Changelog](./CHANGELOG.mdx)** - Release notes and migration guides

### Component Documentation Format

Each component page includes:

- **Basic Usage** - Getting started with the component
- **Element Types** - When to use `<a>` vs `<button>`, etc.
- **Variants** - Visual style variations
- **Sizes** - Component size options
- **States** - Active, disabled, error states
- **Accessibility** - ARIA attributes and keyboard navigation
- **Code Examples** - Live, interactive previews

## Development

### Setup

```bash
# Install dependencies
npm install

# Build SCSS exports and search index
npm run build:scss-exports
npm run build:search-index
```

### Development Server

```bash
# Start development server with hot reload
npm run dev
```

Open [http://localhost:3000](http://localhost:3000) to view the documentation site.

### Building

```bash
# Build documentation and component bundles
npm run build

# Build component bundle only
npm run build:bundle

# Build megamenu bundle
npm run build:megamenu

# Build footer bundle
npm run build:footer
```

### Testing

```bash
# Run tests
npm test

# Watch mode
# Watch mode
npm test

# Visual tests in pinned Playwright Docker image (stable rendering in CI)
npm run test:visual:docker

# Generate/update visual baselines in Docker
npm run test:visual:docker:update

# Coverage report
npm run coverage
```

### Linting

```bash
# Run Biome lint checks
npm run lint

# Run Biome lint checks and auto-fix where possible
npm run lint:fix

# Format code with Biome
npm run format
```

### File Structure

```
src/
  components/          # Component source files
    Button/
      Button.tsx       # React wrapper
      IconButton.tsx
      styles/
        style.scss
      index.ts
    Accordion/
      Accordion.tsx    # React wrapper
      Accordion.static.ts  # Vanilla JS class
      AccordionItem.tsx
      styles/
        style.scss
      index.ts
    ...
  styles/              # Global styles
    tokens.scss        # Design tokens (CSS variables)
    mixins.scss
  utils/               # Shared utilities
    hooks.ts           # React hooks (useStatic)
    keyboard.ts        # Keyboard navigation
  app/                 # Next.js documentation site
    components/        # Component docs pages
    fundamentals/      # Design system docs
    getting-started/   # Getting started guides

build/                 # Compiled components (generated)
public/                # Static assets

package.json           # Dependencies and scripts
tsconfig.json          # TypeScript configuration
rollup.config.mjs      # Bundle configuration
biome.json             # Linting and formatting configuration
```

## Contributing

Contributions are welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md) first.

### Code Standards

- **Valid, semantic, and accessible** HTML
- **TypeScript** for component logic
- **SCSS** for styles using BEM methodology
- **PropTypes** for React components (for runtime validation in addition to TypeScript)
- **Unit and integration tests** for components

### Component Guidelines

Each component should include:

- ✅ Folder structure following ODS conventions
- ✅ React wrapper component (`.tsx`)
- ✅ Vanilla JavaScript class (`.static.ts`) if interactive
- ✅ SCSS styles in `styles/` directory
- ✅ TypeScript interfaces for props
- ✅ Unit tests
- ✅ MDX documentation page
- ✅ Accessibility attributes (ARIA)

See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.

## Support

### Resources

- **Documentation**: [https://ods2.lb.sk](https://ods2.lb.sk)
- **GitHub**: [github.com/orangesk/design-system](https://github.com/orangesk/design-system)
- **NPM Package**: [@orangesk/orange-design-system](https://www.npmjs.com/package/@orangesk/orange-design-system)

### Getting Help

- 📖 Check the [documentation](https://ods2.lb.sk)

## Changelog

See [CHANGELOG.mdx](CHANGELOG.mdx) for detailed release notes, migration guides, and V1-to-V2 migration checklist.
