@orangesk/orange-design-system

v2.0.0-beta.22

Published

5 days ago

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

0High
0Medium
0Low

jurajk

dtuzinsky

benjamin.stary

Orange Design System (ODS)

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

📚 Table of Contents

Orange Design System (ODS)

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

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

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:

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:

<!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:

<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.vercel.app

Documentation Sections

Getting Started - Installation, setup, and resources
Fundamentals - Accessibility, breakpoints, color, tokens, spacing, typography
Components - Full component library with examples and API docs
Copy - Tone of voice, form validation, form labels, CTA guidelines
Changelog - 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

# Install dependencies
npm install

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

Development Server

# Start development server with hot reload
npm run dev

Open http://localhost:3000 to view the documentation site.

Building

# 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

# Run tests
npm test

# Watch mode
npm test:watch

# Coverage report
npm test:coverage

Linting

# Run ESLint
npm run lint

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
jest.config.js         # Test configuration
eslint.config.mjs      # Linting configuration

Contributing

Contributions are welcome! Please read our Contributing Guidelines 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 for detailed guidelines.

Support

Resources

Documentation: https://ods2.vercel.app
GitHub: github.com/orangesk/design-system
NPM Package: @orangesk/orange-design-system

Getting Help

📖 Check the documentation

Changelog

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