@neuravision/construct 1.1.0

package/foundations.css

@@ -0,0 +1,299 @@
+@import url('https://fonts.googleapis.com/css2?family=Sora:wght@400;500;600;700&family=Source+Sans+3:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500;600;700&display=swap');
+@import './tokens/tokens.css';
+
+:root {
+  color-scheme: var(--theme-color-scheme, light);
+  font-family: var(--font-family-text);
+  text-rendering: optimizeLegibility;
+  -webkit-font-smoothing: antialiased;
+  font-synthesis: none;
+  accent-color: var(--color-brand-accent);
+}
+
+*,
+*::before,
+*::after {
+  box-sizing: border-box;
+}
+
+html {
+  height: 100%;
+  text-size-adjust: 100%;
+}
+
+body {
+  min-height: 100%;
+  margin: 0;
+  background: var(--color-bg-canvas);
+  color: var(--color-text-primary);
+  font-family: var(--font-family-text);
+  font-size: var(--font-size-md);
+  line-height: var(--line-height-md);
+}
+
+main {
+  display: block;
+}
+
+img,
+picture,
+video,
+canvas,
+svg {
+  display: block;
+  max-width: 100%;
+}
+
+a {
+  color: var(--color-brand-primary);
+  text-decoration: underline;
+  text-decoration-thickness: 1px;
+  text-underline-offset: 0.15em;
+}
+
+a:hover {
+  color: var(--color-brand-primary-hover);
+  text-decoration-thickness: 2px;
+}
+
+a:active {
+  color: var(--color-brand-primary-active);
+}
+
+p {
+  margin: 0 0 var(--space-6);
+}
+
+small {
+  font-size: var(--font-size-sm);
+  color: var(--color-text-muted);
+}
+
+h1,
+h2,
+h3,
+h4,
+h5,
+h6 {
+  margin: 0 0 var(--space-5);
+  color: var(--color-text-primary);
+}
+
+h1 {
+  font-family: var(--type-h1-font-family);
+  font-size: var(--type-h1-font-size);
+  line-height: var(--type-h1-line-height);
+  font-weight: var(--type-h1-font-weight);
+  letter-spacing: var(--type-h1-letter-spacing);
+}
+
+h2 {
+  font-family: var(--type-h2-font-family);
+  font-size: var(--type-h2-font-size);
+  line-height: var(--type-h2-line-height);
+  font-weight: var(--type-h2-font-weight);
+  letter-spacing: var(--type-h2-letter-spacing);
+}
+
+h3 {
+  font-family: var(--type-h3-font-family);
+  font-size: var(--type-h3-font-size);
+  line-height: var(--type-h3-line-height);
+  font-weight: var(--type-h3-font-weight);
+  letter-spacing: var(--type-h3-letter-spacing);
+}
+
+h4 {
+  font-family: var(--type-h4-font-family);
+  font-size: var(--type-h4-font-size);
+  line-height: var(--type-h4-line-height);
+  font-weight: var(--type-h4-font-weight);
+  letter-spacing: var(--type-h4-letter-spacing);
+}
+
+label {
+  font-family: var(--type-label-font-family);
+  font-size: var(--type-label-font-size);
+  line-height: var(--type-label-line-height);
+  font-weight: var(--type-label-font-weight);
+  letter-spacing: var(--type-label-letter-spacing);
+}
+
+code,
+pre,
+kbd,
+samp {
+  font-family: var(--font-family-mono);
+  font-size: var(--font-size-sm);
+}
+
+pre {
+  margin: 0 0 var(--space-6);
+  padding: var(--space-6);
+  background: var(--color-bg-muted);
+  border-radius: var(--radius-md);
+  overflow: auto;
+}
+
+hr {
+  border: 0;
+  border-top: var(--border-thin) solid var(--color-border-subtle);
+  margin: var(--space-8) 0;
+}
+
+table {
+  width: 100%;
+  border-collapse: collapse;
+}
+
+th,
+td {
+  padding: var(--space-4) var(--space-5);
+  text-align: left;
+  border-bottom: var(--border-thin) solid var(--color-border-subtle);
+}
+
+thead th {
+  font-weight: var(--font-weight-semibold);
+  color: var(--color-text-secondary);
+}
+
+button,
+input,
+select,
+textarea {
+  font: inherit;
+  color: inherit;
+}
+
+textarea {
+  resize: vertical;
+}
+
+button {
+  cursor: pointer;
+}
+
+:disabled {
+  cursor: not-allowed;
+  opacity: var(--opacity-disabled);
+}
+
+:focus-visible {
+  outline: 3px solid var(--color-focus-ring);
+  outline-offset: 2px;
+}
+
+::selection {
+  background: var(--color-brand-accent);
+  color: var(--color-text-inverse);
+}
+
+.ct-container {
+  width: min(100%, var(--container-lg));
+  margin-inline: auto;
+  padding-inline: clamp(var(--gutter-sm), 3vw, var(--gutter-lg));
+}
+
+.ct-grid {
+  display: grid;
+  gap: var(--grid-gap-md);
+  grid-template-columns: repeat(
+    auto-fit,
+    minmax(var(--ct-grid-min, 240px), 1fr)
+  );
+}
+
+.ct-stack > * + * {
+  margin-top: var(--ct-stack-space, var(--space-6));
+}
+
+.ct-cluster {
+  display: flex;
+  flex-wrap: wrap;
+  gap: var(--ct-cluster-gap, var(--space-4));
+  align-items: center;
+}
+
+.ct-card {
+  background: var(--color-bg-elevated);
+  border: var(--border-thin) solid var(--color-border-subtle);
+  border-radius: var(--radius-card);
+  box-shadow: var(--shadow-card);
+  padding: var(--space-7);
+}
+
+.ct-surface {
+  background: var(--color-bg-surface);
+}
+
+.ct-muted {
+  color: var(--color-text-muted);
+}
+
+.ct-text-center {
+  text-align: center;
+}
+
+.ct-w-100 {
+  width: 100%;
+}
+
+.ct-max-readable {
+  max-width: 65ch;
+}
+
+.ct-sr-only {
+  border: 0;
+  clip: rect(0 0 0 0);
+  height: 1px;
+  margin: -1px;
+  overflow: hidden;
+  padding: 0;
+  position: absolute;
+  width: 1px;
+  white-space: nowrap;
+}
+
+/* ============================================================
+   Visually Hidden
+   Hides content visually while keeping it accessible to screen
+   readers. Uses the modern clip-path technique with clip fallback.
+   ============================================================ */
+
+.ct-visually-hidden {
+  border: 0;
+  clip: rect(0 0 0 0);
+  clip-path: inset(50%);
+  height: 1px;
+  margin: -1px;
+  overflow: hidden;
+  padding: 0;
+  position: absolute;
+  width: 1px;
+  white-space: nowrap;
+}
+
+.ct-visually-hidden--focusable:focus,
+.ct-visually-hidden--focusable:focus-visible,
+.ct-visually-hidden--focusable:active {
+  clip: auto;
+  clip-path: none;
+  height: auto;
+  margin: 0;
+  overflow: visible;
+  position: static;
+  width: auto;
+  white-space: normal;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@neuravision/construct",
+  "version": "1.1.0",
+  "description": "Construct Design System - Accessible, token-based design system for modern web applications",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Samyssmile/construct.git"
+  },
+  "homepage": "https://samyssmile.github.io/construct",
+  "keywords": [
+    "design-system",
+    "design-tokens",
+    "accessibility",
+    "a11y",
+    "css",
+    "components"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "node scripts/build-tokens.mjs",
+    "check": "node scripts/build-tokens.mjs --check",
+    "storybook": "storybook dev -p 6006",
+    "storybook:build": "storybook build"
+  },
+  "exports": {
+    "./foundations.css": "./foundations.css",
+    "./components/components.css": "./components/components.css",
+    "./components/index.css": "./components/index.css",
+    "./components/*.css": "./components/*.css",
+    "./tokens/tokens.css": "./tokens/tokens.css",
+    "./tokens/tokens.json": "./tokens/tokens.json",
+    "./tokens/tokens": {
+      "types": "./tokens/tokens.ts",
+      "default": "./tokens/tokens.js"
+    },
+    "./tokens": {
+      "types": "./tokens/tokens.ts",
+      "default": "./tokens/tokens.js"
+    }
+  },
+  "files": [
+    "foundations.css",
+    "tokens/tokens.css",
+    "tokens/tokens.json",
+    "tokens/tokens.js",
+    "tokens/tokens.ts",
+    "tokens/README.md",
+    "docs/guidelines.md",
+    "components/*.css",
+    "components/README.md",
+    "README.md"
+  ],
+  "devDependencies": {
+    "@storybook/addon-a11y": "^10.2.3",
+    "@storybook/addon-docs": "^10.2.3",
+    "@storybook/addon-themes": "^10.2.3",
+    "@storybook/addon-vitest": "^10.2.3",
+    "@storybook/html-vite": "^10.2.3",
+    "@vitest/browser-playwright": "^4.0.18",
+    "@vitest/coverage-v8": "^4.0.18",
+    "playwright": "^1.58.1",
+    "storybook": "^10.2.3",
+    "vitest": "^4.0.18"
+  }
+}

package/tokens/README.md

@@ -0,0 +1,179 @@
+# Construct Design Tokens
+
+Design tokens are the single source of truth for all design decisions in the Construct Design System. They provide consistent values for colors, typography, spacing, and more across all applications.
+
+## Design Direction
+
+- **Enterprise-grade**: Clean, professional, high-trust aesthetic
+- **Ocean primary**: Deep, authoritative blue for key actions
+- **Teal accent**: Modern, clear accent for highlights
+- **Slate neutrals**: Versatile grays for typography and surfaces
+
+## Files
+
+- **`primitives.json`**: Raw values (color palettes, typography scale, spacing, radius, shadows, layout)
+- **`semantic.light.json`**: Semantic mappings for light theme (brand, text, background, state colors)
+- **`semantic.dark.json`**: Dark theme overrides (color + theme metadata)
+- **`semantic.high-contrast.json`**: High-contrast theme overrides (color + theme metadata)
+- **`tokens.css`**: Generated CSS Custom Properties (ready for import)
+- **`tokens.json`**: Generated, resolved token values with units (for tooling)
+- **`tokens.js`**: Generated JavaScript module for runtime imports
+- **`tokens.ts`**: Generated TypeScript definitions and typed exports
+
+## Two-Tier Token System
+
+### Primitives
+Raw design values that form the foundation:
+
+```json
+{
+  "color": {
+    "ocean": {
+      "700": "#174C5D"
+    }
+  },
+  "space": {
+    "4": 8
+  }
+}
+```
+
+### Semantic
+Contextual tokens that reference primitives:
+
+```json
+{
+  "color": {
+    "brand": {
+      "primary": "{color.ocean.700}"
+    }
+  }
+}
+```
+
+This approach means:
+- **Primitives** rarely change (your color palette)
+- **Semantic** tokens can be remapped for themes without touching primitives
+- Consistency is enforced automatically
+
+## Usage
+
+### CSS
+
+Import the generated CSS file:
+
+```css
+@import "@neuravision/construct/tokens/tokens.css";
+
+body {
+  font-family: var(--font-family-body);
+  color: var(--color-text-primary);
+  background: var(--color-bg-canvas);
+}
+
+.button {
+  background: var(--color-brand-primary);
+  padding: var(--space-4) var(--space-6);
+  border-radius: var(--radius-control);
+}
+```
+
+### Themes
+
+Construct ships with light (default), dark, and high-contrast themes. The generated CSS includes theme overrides and system preference fallbacks.
+
+```html
+<html data-theme="dark">
+  ...
+</html>
+```
+
+Available values:
+- `light` (default)
+- `dark`
+- `high-contrast`
+
+If no `data-theme` is set, the system preferences are respected:
+- `prefers-color-scheme: dark` → dark theme
+- `prefers-contrast: more` → high-contrast theme
+
+### TypeScript/JavaScript
+
+Import the generated token module:
+
+```typescript
+import { tokens, cssVars } from '@neuravision/construct/tokens/tokens';
+
+// Use resolved values
+console.log(tokens.semantic.color.brand.primary); // "#174C5D"
+
+// Or use CSS variable references
+console.log(cssVars.semantic.color.brand.primary); // "var(--color-brand-primary)"
+
+// Access full theme maps
+console.log(tokens.semanticThemes.dark.color.background.canvas);
+```
+
+## Building Tokens
+
+The build script generates CSS, JSON, JavaScript, and TypeScript outputs from the source token files.
+
+### Run Build
+
+From repository root:
+```bash
+node design/scripts/build-tokens.mjs
+```
+
+From `design/` directory:
+```bash
+npm run build
+```
+
+### Check if Up-to-Date (CI)
+
+Verify outputs match sources without rebuilding:
+
+```bash
+npm run check
+```
+
+This command exits with a non-zero code if outputs are outdated, making it perfect for CI/CD pipelines.
+
+## Token Naming Conventions
+
+### CSS Variables
+
+Tokens are converted to kebab-case CSS variables:
+
+- Primitives: `--color-ocean-700`, `--space-4`, `--radius-md`
+- Semantic: `--color-brand-primary`, `--color-text-primary`, `--color-bg-canvas`
+
+### TypeScript
+
+Tokens are available as nested objects with camelCase properties:
+
+```typescript
+tokens.primitives.color.ocean[700]
+tokens.semantic.color.brand.primary
+cssVars.semantic.color.brand.primary
+```
+
+## Brand Guidance
+
+- **Primary**: Use for key actions, primary buttons, and main navigation
+- **Accent**: Use sparingly for highlights, special emphasis, and interactive elements
+- **Backgrounds**: Prefer `surface` and `muted` for large content areas
+- **Text**: Use `primary` for body text, `secondary` for less important text, `muted` for hints
+
+## Versioning
+
+Tokens follow Semantic Versioning:
+
+- **MAJOR**: Removing/renaming tokens or changing existing token values
+- **MINOR**: Adding new tokens, scales, or semantic aliases
+- **PATCH**: Documentation, build scripts, internal changes (no token value changes)
+
+---
+
+**Construct** - Build accessible design constructs