A token-based, framework-agnostic design system for accessible, modern web UI.
Live Storybook · Components · Design Tokens · Accessibility · Contributing
Construct is a single source of design truth that ships as plain CSS and design tokens — no runtime, no framework lock-in. Style values live once as JSON tokens and compile to CSS custom properties, JSON, and typed TypeScript exports. Components are pure CSS classes (ct- prefix), so they work with vanilla HTML, Angular, React, Svelte, or anything that renders markup.
- 🎯 Token-driven — colors, spacing, typography & radii defined once, consumed everywhere
- 🧩 Framework-agnostic — 47 components as portable CSS, zero JS dependencies
- ♿ Accessibility first — WCAG 2.1 AA, full keyboard support, ARIA, focus management
- 🎨 Three themes —
light,dark,high-contrast, with system-preference fallback - 📐 The "datum" grammar — a signature orange reference line for focus / active / current state
- 🛠️ Typed tokens — autocomplete-friendly TypeScript exports
- 📖 Interactive docs — every component documented & a11y-tested in Storybook
npm install @neuravision/constructUsing Angular? Reach for the official wrapper @neuravision/ng-construct — typed, signal-based components built on top of these styles.
Import the foundation styles and the component bundle once (e.g. in your global stylesheet):
@import "@neuravision/construct/foundations.css";
@import "@neuravision/construct/components/components.css";Then use the classes in your markup:
<button class="ct-button">Primary</button>
<button class="ct-button ct-button--secondary">Secondary</button>
<div class="ct-field">
<label class="ct-field__label" for="email">Email</label>
<input class="ct-input" id="email" type="email" placeholder="name@company.com" />
</div>Or build custom UI directly on the tokens:
.custom-card {
background: var(--color-surface);
color: var(--color-text);
padding: var(--space-4);
border-radius: var(--radius-control);
}💡 Need a smaller bundle? Import only what you use — every component is also a standalone file, e.g.
@import "@neuravision/construct/components/button.css";
Set data-theme on the root element (or any container) to switch modes:
<html data-theme="dark"> … </html>| Value | Description |
|---|---|
light |
Default theme |
dark |
Dark theme |
high-contrast |
Maximum-contrast theme |
With no data-theme set, Construct respects system preferences automatically:
prefers-color-scheme: dark → dark, prefers-contrast: more → high-contrast.
47 production-ready components, each documented and accessibility-tested in Storybook.
| Category | Components |
|---|---|
| Actions | Button · Toggle Group · Toolbar |
| Forms & Inputs | Field · Input · Textarea · Select · Select Menu · Checkbox · Radio · Switch · Slider · Combobox · Chip · File Upload · Datepicker |
| Data Display | Table · Data Table · List · Tree · Avatar · Badge · Icon · Tooltip · Chart |
| Feedback | Alert · Banner · Toast · Spinner · Skeleton · Progress Bar · Empty State |
| Navigation | Navbar · Breadcrumbs · Tabs · Pagination · Sidebar · Skip Link |
| Overlays | Modal · Drawer · Popover · Dropdown |
| Layout | Card · Divider · Accordion · App Shell · App Shell V2 |
→ Explore every component in the live Storybook
Construct uses a two-tier token system: raw primitives and contextual semantic aliases.
The build pipeline (npm run build) compiles tokens/*.json into:
tokens.css— CSS custom properties (--color-brand-accent)tokens.json— resolved values for toolingtokens.ts/tokens.js— typed exports
⚠️ Never hand-edit generated files (tokens/tokens.*). Edit the source JSON and runnpm run build.
Accessibility is a first-class requirement, not an afterthought:
- ✅ Semantic HTML & correct ARIA attributes
- ✅ Full keyboard navigation (roving tabindex, focus traps, arrow-key patterns)
- ✅ Visible focus indicators (the orange "datum")
- ✅ WCAG 2.1 AA contrast across all three themes
- ✅ Screen-reader support & live regions for dynamic content
- ✅ Respects
prefers-reduced-motion
The Storybook a11y addon is configured to fail the build on violations. See docs/guidelines.md for the detailed patterns.
| Distribution | Plain CSS + design tokens (no runtime) |
| Docs & tests | Storybook 10 · Vitest 4 · Playwright (story-driven) |
| a11y testing | @storybook/addon-a11y (fails on violations) |
| Token build | Custom pipeline (scripts/build-tokens.mjs) |
npm install # install dependencies
npm run storybook # dev server → http://localhost:6006
npm run build # build token outputs
npm run check # verify token outputs are up to date (CI)
npx vitest --run # run tests headless| Framework | Status |
|---|---|
| Vanilla HTML / CSS | ✅ Available — use the ct- classes directly |
| Angular | ✅ Available — @neuravision/ng-construct |
| React | 🛣️ Planned |
| Svelte | 🛣️ Planned |
- Design Guidelines — do's, don'ts & accessibility patterns
- Component Usage — HTML patterns and examples
- Token Reference — token structure & naming
- Changelog — release history
Contributions are welcome! Please read the Contributing Guide and our Code of Conduct before opening a PR. Found a security issue? See SECURITY.md.
MIT © Construct contributors