@devclubnst/ui

v2.0.7

Published

2 hours ago

DevClub UI animated component primitives

0High
0Medium
0Low

DevClub UI

High-Performance, Production-Ready Animated UI Primitives & WebGL Shaders for Modern Web Applications

Explore Components • Documentation • API Specification • Contributing

Overview & Engineering Philosophy

DevClub UI is an open-source, copy-paste component engineering library designed for developer platforms, high-aesthetic SaaS products, and generative AI interfaces. Built on Next.js 16, React 19, Tailwind CSS v4, GSAP 3.15, and OGL WebGL 2.0, DevClub UI bridges the gap between raw graphics programming and modern React component architecture.

Key Architectural Pillars

Copy-Paste Modularity: Zero lock-in. Each component is a self-contained .tsx file that you own, inspect, and modify directly in your codebase.
Zero Cumulative Layout Shift (CLS 0.0): GPU-accelerated compositing ensures hardware-bound layout stability during heavy micro-interactions.
Declarative Physics & WebGL Shaders: Procedural dither noise, 3D Raymarched AI Orbs, dynamic scale hatch marks, and proximity vector cards running on GPU fragment execution units.
Strict GSAP Context Scoping: Fully compliant with @gsap/react useGSAP() lifecycles, ensuring zero memory leaks or unhandled scroll triggers on unmount.
WCAG 2.1 AA Accessibility Compliance: Semantic HTML tags, full keyboard tab order (Enter/Space), and automatic prefers-reduced-motion detection.

Technical Architecture & Dependency Stack

                        ┌─────────────────────────────────────────┐
                        │              DevClub UI                 │
                        └────────────────────┬────────────────────┘
                                             │
      ┌──────────────────────┬───────────────┴───────────────┬──────────────────────┐
      │                      │                               │                      │
┌─────▼───────────┐    ┌─────▼───────────┐         ┌─────────▼─────────┐    ┌───────▼───────────┐
│ Next.js 16 App  │    │  Tailwind v4    │         │  GSAP 3.15 Engine │    │ WebGL 2.0 / OGL   │
│ React 19 Engine │    │ Design System   │         │ Animated Timeline │    │  GPU Fragment     │
└─────────────────┘    └─────────────────┘         └───────────────────┘    └───────────────────┘

| Technology | Version | Purpose | | :---------------------- | :------------------- | :--------------------------------------------------------------------------------- | | Next.js | ^16.3.4 | App Router framework, server component rendering, and REST API endpoints | | React | ^19.2.8 | UI component primitives and concurrent rendering | | Tailwind CSS | ^4.0 | Sub-pixel CSS utility styling, grid layouts, and color variable tokens | | GSAP & @gsap/react | ^3.15.0 / ^2.1.2 | Timeline choreography, micro-interaction spring curves, and hook lifecycle scoping | | OGL | ^1.0.11 | Lightweight WebGL 2.0 fragment shader rendering pipeline | | Framer Motion | ^13.4.0 | Motion layout transitions and gesture spring physics | | Radix UI Primitives | ^1.3 / ^1.2 | Accessible unstyled primitives (@radix-ui/react-icons, avatar, slot) |

Quick Start & Installation

1. Install Base Core Dependencies

Install the lightweight utility packages required across DevClub UI components:

# Using npm
npm install clsx tailwind-merge @radix-ui/react-icons

# Using pnpm
pnpm add clsx tailwind-merge @radix-ui/react-icons

# Using yarn
yarn add clsx tailwind-merge @radix-ui/react-icons

# Using bun
bun add clsx tailwind-merge @radix-ui/react-icons

For components requiring advanced animations or 3D WebGL shaders:

npm install gsap @gsap/react ogl motion

2. Configure Class Merging Utility (`src/lib/utils.ts`)

Create a unified class name merger using clsx and tailwind-merge:

import { clsx, type ClassValue } from "clsx";
import { twMerge } from "tailwind-merge";

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs));
}

3. Setup Global CSS Design Tokens (`src/app/globals.css`)

Add monochromatic design system variables to your root stylesheet:

@import "tailwindcss";

:root {
  --background: #050505;
  --foreground: #f4f4f5;
  --border-subtle: rgba(255, 255, 255, 0.08);
  --border-hairline: rgba(255, 255, 255, 0.16);
  --pattern-line: rgba(255, 255, 255, 0.1);
  --pattern: rgba(255, 255, 255, 0.05);
}

@layer base {
  body {
    background-color: var(--background);
    color: var(--foreground);
  }
}

Component Registry & Technical Directory

Below is the complete catalog of all production components included in DevClub UI:

Detailed Component Specifications & Code Usage

1. Scales & Borders (`scales`)

Architectural boundary divider primitives designed for developer consoles, code documentation, and high-density SaaS headers.

import { HorizontalScale, VerticalScale, Lines } from "@/components/ui/scales";

export function SectionDivider() {
  return (
    <div className="w-full space-y-6">
      <HorizontalScale className="my-4" />
      <div className="flex h-40">
        <p className="flex-1 text-xs text-zinc-400">Left Workspace</p>
        <VerticalScale />
        <p className="flex-1 text-xs text-zinc-400">Right Inspector</p>
      </div>
      <Lines />
    </div>
  );
}

2. Dither WebGL Grainient (`dither`)

A GPU-bound procedural WebGL 2.0 fragment shader generating fluid dithered noise, animated filmic grain, and multi-chromatic palette blending.

import { Grainient } from "@/components/ui/dither";

export function HeroBackground() {
  return (
    <div className="relative w-full h-125 overflow-hidden rounded-2xl">
      <Grainient
        color1="#FF9FFC"
        color2="#5227FF"
        color3="#B497CF"
        timeSpeed={0.25}
        warpStrength={1.2}
        grainAmount={0.12}
        grainAnimated={true}
      />
      <div className="relative z-10 flex items-center justify-center h-full">
        <h1 className="text-4xl font-bold text-white">
          Next Generation Interfaces
        </h1>
      </div>
    </div>
  );
}

3. Spotlight Card (`spotlight-card`)

Cursor-tracking glassmorphic container projecting a smooth 600px radial lighting mask.

import { SpotlightCard } from "@/components/ui/spotlight-card";

export function FeatureCard() {
  return (
    <SpotlightCard
      spotlightColor="rgba(59, 130, 246, 0.18)"
      className="max-w-md p-8"
    >
      <h3 className="text-lg font-medium text-white">Real-Time Telemetry</h3>
      <p className="mt-2 text-xs text-zinc-400">
        Monitor GPU fragment execution time and frame latency across distributed
        clusters.
      </p>
    </SpotlightCard>
  );
}

GSAP & Animation Standards

DevClub UI enforces strict GSAP practices (documented in skills/ and project rules) to ensure 60fps performance and leak-free memory cleanup:

Always Scope via @gsap/react useGSAP():

useGSAP(
  () => {
    gsap.to(".element", { x: 100, duration: 0.5 });
  },
  { scope: containerRef, dependencies: [value] },
);

Context Cleanup: useGSAP automatically reverts all tweens, timelines, and ScrollTriggers created during execution upon component unmount.

Reduced Motion Fallback:

const prefersReducedMotion = window.matchMedia(
  "(prefers-reduced-motion: reduce)",
).matches;
if (prefersReducedMotion) {
  gsap.set(".target", { opacity: 1, y: 0 });
  return;
}

WebGL & Shader Performance Guidelines

For WebGL components (dither, ai-orb):

Resolution Capping: Device Pixel Ratio (DPR) is dynamically capped at 2.0 (Math.min(window.devicePixelRatio || 1, 2)).
Tab Visibility Listener: Animation frames (requestAnimationFrame) pause when document.hidden is true.
Memory Lifecycle: WebGL textures, geometries, programs, and array buffers are deleted during React useEffect unmount teardown.

Programmatic REST API Reference

DevClub UI provides built-in REST API endpoints to query component metadata, source code, dependencies, and system status programmatically.

`GET /api/components`

Returns a list of all registered UI components with metadata and category filters.

Query Parameters:
- category (optional): Filter by category (scales, buttons, cards, accordion, feedback, layout).
- tag (optional): Filter by keyword tag (e.g. webgl, shimmer, border).
- query (optional): Free-text search matching name, description, or tags.

Example Request:

curl -X GET "http://localhost:3000/api/components?category=buttons"

Example Response:

{
  "success": true,
  "count": 3,
  "data": [
    {
      "slug": "animated-button",
      "name": "Animated Button",
      "description": "Multi-variant interactive button with shimmering effects.",
      "category": "buttons",
      "tags": ["button", "shimmer", "interaction"],
      "version": "1.0.0"
    }
  ]
}

`GET /api/components/[slug]`

Retrieves full component details including TSX source code, prop specifications, physics engine metadata, guidelines, and accessibility attributes.

Example Request:

curl -X GET "http://localhost:3000/api/components/dither"

`GET /api/health`

System health check endpoint returning API version, uptime, registry component count, and status.

Example Response:

{
  "status": "ok",
  "timestamp": "2026-09-22T09:50:00.000Z",
  "version": "0.1.0",
  "componentsCount": 21
}

Accessibility & Keyboard Navigation (WCAG 2.1 AA)

All components undergo rigorous accessibility audits:

Keyboard Interaction:
- Tab / Shift + Tab: Focus moves logically through interactive elements with high-contrast visible focus rings (focus-visible:ring-2).
- Enter / Space: Triggers button clicks, accordion toggle states, and task check items.
- Escape: Closes active dialogs or overlays.
ARIA Semantic Markup: Components expose explicit ARIA roles (role="button", role="separator", role="region", aria-expanded, aria-hidden="true").

Contributing

We welcome community contributions! Please read our Contributing Guide to learn about:

Setting up your local development environment
Authoring new animated or WebGL primitives
Registering components in src/registry/components/ and src/registry/index.ts
Submitting pull requests

Please adhere to our Code of Conduct in all community interactions.

Security Policy

If you discover a security vulnerability or component prop injection risk, please review our Security Policy and report it via [email protected] or GitHub Private Security Advisories.

License & Copyright

DevClub UI is open-source software distributed under the MIT License.

Copyright (c) 2026 DevClub (devclubnst / dev-club-components)

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme