Synergy Design System

The shared design framework for Synergy Network products and sites. The package is designed to be installed from npm and consumed progressively in the same general way as Bootstrap: one compiled stylesheet provides the visual system and component classes, an optional framework-agnostic JavaScript entry adds interactive behavior, and React adapters are available for teams that want typed component APIs.

The documentation and brand site lives at https://brand.synergy-network.io/ and is built from apps/docs in this repository. Public components are not considered complete until their usage, states, accessibility contract, and copy-paste examples are documented there.

Install

npm install @synergy-network/design-system

Import the compiled stylesheet once:

import '@synergy-network/design-system/styles.css';

Use CSS classes directly

No framework is required for the visual layer.

<button class="sds-button sds-button--solid sds-button--md">Continue</button>

<div class="sds-surface sds-surface--deep-glass sds-surface--radius-2xl sds-surface--padding-lg">
  High-emphasis glass content
</div>

Add framework-agnostic behavior

Interactive CSS components expose data-sds-* hooks. Initialize the DOM runtime once after the application shell is mounted.

import '@synergy-network/design-system/styles.css';
import { initSynergyDesignSystem } from '@synergy-network/design-system/js';

const sds = initSynergyDesignSystem();

// Optional SPA teardown:
sds.dispose();

The DOM entry currently includes behavior for the redesign-derived sidebar navigation and pointer-aware electric-border effects. Additional interactive components should follow this same progressive-enhancement contract rather than requiring React.

Use React adapters

React is optional for the package as a whole. React applications can use the typed adapters over the same public CSS classes and tokens.

import '@synergy-network/design-system/styles.css';
import {
  Button,
  SidebarNavigation,
  Surface,
  ThemeProvider,
} from '@synergy-network/design-system/react';

export function App() {
  return (
    <ThemeProvider defaultTheme="dark">
      <SidebarNavigation brand="Synergy Network" items={navigation} />
      <Surface appearance="deep-glass" glow="cyan">
        Secure by Design
      </Surface>
      <Button variant="lime">Connect wallet</Button>
    </ThemeProvider>
  );
}

Optional GSAP integration

The core package does not bundle GSAP. Applications that need scrubbed scrolling, pinned storyboards, horizontal journeys, or GSAP-based reveal choreography install GSAP separately and use the dedicated adapter entry.

npm install gsap

import { gsap } from 'gsap';
import { ScrollTrigger } from 'gsap/ScrollTrigger';
import { createGsapRuntime, initGsapMotion } from '@synergy-network/design-system/gsap';

const runtime = createGsapRuntime(gsap, ScrollTrigger);
const motion = initGsapMotion(document, runtime);

The GSAP adapter intentionally uses native document scrolling. This follows the brand-site redesign, where native scroll produced more predictable sticky and pinned behavior across desktop and mobile than an additional smooth-scroll layer.

Configure the central SCSS palette

Projects that need a deliberate approved theme override can compile the source entry. All palette values are !default, so one configuration updates primitive variables, semantic themes, components, and utilities together.

@use '@synergy-network/design-system/scss' with (
  $brand-lime: #38ff8b,
  $brand-blue: #2575ff,
  $canvas-dark: #02040a
);

Most applications should import the compiled CSS and override semantic CSS custom properties at a theme boundary instead of forking the palette.

Package entry points

| Import | Purpose | | ------------------------------------------- | --------------------------------------------------------------- | | @synergy-network/design-system | Existing aggregate API for compatibility | | @synergy-network/design-system/react | Typed React adapters and providers | | @synergy-network/design-system/js | Framework-agnostic DOM behavior for data-sds-* components | | @synergy-network/design-system/gsap | Optional GSAP/ScrollTrigger integration and data API | | @synergy-network/design-system/tokens | Typed token references | | @synergy-network/design-system/icons | Synergy icon API | | @synergy-network/design-system/motion | Motion constants and framework-neutral motion helpers | | @synergy-network/design-system/styles.css | Complete minified CSS, fonts, themes, components, and utilities | | @synergy-network/design-system/scss | Configurable SCSS source entry | | @synergy-network/design-system/assets/* | Approved network and ecosystem assets |

Redesign-derived system additions

The redesign(2)(3).html reference has been translated into reusable design-system contracts rather than copied as page-specific CSS. The package now includes:

• semantic deep-canvas, glass, strong-glass, and glass-border tokens;
• Surface appearances for deep-glass and ambient surfaces;
• the .sds-ambient-canvas atmospheric background utility;
• SidebarNavigation, including desktop flyouts, mobile drill-in submenus, per-section accent colors, focus/Escape behavior, and reduced-motion support;
• a framework-agnostic SidebarNavigationController and initSynergyDesignSystem() data API;
• framework-agnostic pointer-glow behavior for the existing electric-border visual contract;
• GsapReveal for React;
• framework-neutral GSAP helpers for reveals, stagger groups, pinned timelines, and horizontal journeys;
• data-sds-gsap-* initialization through the optional /gsap entry.

Documentation contract

Every published component or behavior must have a corresponding example on the brand site. At minimum, documentation should include:

1. a rendered specimen;
2. CSS/HTML usage when a framework-neutral contract exists;
3. JavaScript initialization for data-sds-* behavior when required;
4. React usage when a React adapter exists;
5. supported states, responsive behavior, reduced-motion behavior, and accessibility notes;
6. the public API or stable class/data-attribute contract.

Development

npm install
npm run validate
npm run storybook
npm run docs:dev

The complete target architecture, component inventory, migration plan, and release gates are in DESIGN_SYSTEM_OUTLINE.md. The source consolidation and Bootstrap coverage reviews are in RAW_STYLE_CONSOLIDATION.md and BOOTSTRAP_PARITY_AUDIT.md.