@neuravision/construct

v1.2.0

Published

16 days ago

Construct Design System - Accessible, token-based design system for modern web applications

0High
0Medium
0Low

samyssmile

design-system design-tokens accessibility a11y css components

Construct - Design System

Build accessible design constructs for modern web applications

Construct is an open-source, token-based design system foundation that provides a consistent, accessible UI across Angular, React, Svelte, and vanilla HTML/CSS.

✨ Features

Design Tokens - Single source of truth for colors, typography, spacing, and more
Framework-Agnostic CSS - Works with any framework or vanilla HTML
Accessibility First - WCAG 2.1 AA compliant, keyboard navigation, ARIA support
Themes - Light, dark, and high-contrast modes with system preference support
Token Pipeline - Automated build system (JSON → CSS Variables + TypeScript)
Comprehensive Components - 16+ production-ready components
Storybook Documentation - Interactive component explorer with a11y testing
TypeScript Support - Full type definitions for tokens

🚀 Quick Start

Installation

npm install @neuravision/construct

Usage

Import the foundation styles and components:

@import "@neuravision/construct/foundations.css";
@import "@neuravision/construct/components/components.css";

Use the components in your HTML:

<button class="ct-button">Primary Button</button>
<button class="ct-button ct-button--secondary">Secondary</button>

Or use design tokens directly:

.custom-component {
  background: var(--color-brand-primary);
  padding: var(--space-4);
  border-radius: var(--radius-control);
}

Themes

Set a theme on the root element (or any container) to switch modes:

<html data-theme="dark">
  ...
</html>

Available values:

light (default)
dark
high-contrast

If no data-theme is set, system preferences are respected:

prefers-color-scheme: dark → dark theme
prefers-contrast: more → high-contrast theme

📦 What's Included

@neuravision/construct/
├── tokens/                     # Design tokens (JSON, CSS, JS, TS)
│   ├── primitives.json         # Base values (colors, sizes)
│   ├── semantic.light.json     # Semantic mappings
│   ├── semantic.dark.json      # Dark theme overrides
│   ├── semantic.high-contrast.json # High-contrast theme overrides
│   ├── tokens.css              # CSS Custom Properties
│   ├── tokens.json             # Resolved JSON output
│   ├── tokens.js               # JavaScript exports
│   └── tokens.ts               # TypeScript exports
├── components/                 # Framework-agnostic styles
│   ├── components.css          # All component styles
│   └── README.md               # Component documentation
├── foundations.css             # Reset, typography, layout utilities
└── docs/                       # Guidelines & best practices
    └── guidelines.md

🎨 Design Tokens

Construct uses a two-tier token system:

Primitives

Raw design values (colors, spacing, typography)

{
  "color": {
    "ocean": {
      "700": "#174C5D"
    }
  },
  "space": {
    "4": 8
  }
}

Semantic

Contextual aliases that reference primitives

{
  "color": {
    "brand": {
      "primary": "{color.ocean.700}"
    }
  }
}

Build Pipeline

The token build system automatically generates:

CSS Variables (--color-brand-primary)
TypeScript exports with type definitions
Resolved JSON for tooling

npm run build

🧩 Components

Base Components

Button (6 variants, 3 sizes)
Input (text, email, password, search)
Select (native dropdown)
Textarea
Checkbox
Radio
Switch

Complex Components

Card
Table / Data Table
Modal
Toast (notifications)
Tabs
Dropdown
Pagination
Breadcrumbs
Datepicker

View all components in Storybook

♿ Accessibility

Accessibility is a core principle of Construct:

✅ Semantic HTML
✅ ARIA attributes where needed
✅ Full keyboard navigation
✅ Focus management
✅ WCAG 2.1 AA contrast standards
✅ Screen reader support
✅ Respects prefers-reduced-motion
✅ Live regions for dynamic content

See Guidelines for detailed accessibility rules.

🛠️ Development

Run Storybook

npm run storybook

Open http://localhost:6006

Build Tokens

npm run build

Check Token Outputs

npm run check

🎯 Framework Support

Current: CSS/HTML

All components work with vanilla HTML and can be used with any framework.

Planned: Framework Libraries

Angular (standalone components)
React (React 18+)
Svelte (Svelte 4+)

📖 Documentation

Design Guidelines - Do/Don'ts, accessibility rules
Component Usage - HTML patterns and examples
Token Details - Token structure and naming

🤝 Contributing

Contributions are welcome! Please read our contributing guidelines (coming soon).

📄 License

MIT License - see LICENSE file for details

🙏 Credits

Built with accessibility and modern design principles in mind.

Construct - Build accessible design constructs