@neuravision/construct 1.1.0

package/components/toolbar.css

@@ -0,0 +1,222 @@
+/* ── Toolbar ── */
+
+.ct-toolbar {
+  /* ── Control Variables ── */
+  --ct-toolbar-height: var(--control-height-lg);
+  --ct-toolbar-padding-x: var(--space-6);
+  --ct-toolbar-gap: var(--space-4);
+  --ct-toolbar-brand-img-height: var(--space-9);
+  --ct-toolbar-nav-gap: var(--space-1);
+  --ct-toolbar-actions-gap: var(--space-3);
+  --ct-toolbar-nav-font-size: var(--font-size-sm);
+  --ct-toolbar-nav-padding-y: var(--space-3);
+  --ct-toolbar-nav-padding-x: var(--space-4);
+
+  display: flex;
+  align-items: center;
+  gap: var(--ct-toolbar-gap);
+  height: var(--ct-toolbar-height);
+  padding: 0 var(--ct-toolbar-padding-x);
+  background: var(--color-bg-elevated);
+  border-bottom: var(--border-thin) solid var(--color-border-subtle);
+  color: var(--color-text-primary);
+  z-index: var(--z-sticky);
+}
+
+/* ── Brand ── */
+
+.ct-toolbar__brand {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-3);
+  text-decoration: none;
+  color: inherit;
+  font-weight: var(--font-weight-semibold);
+  flex-shrink: 0;
+}
+
+.ct-toolbar__brand img {
+  height: var(--ct-toolbar-brand-img-height);
+  width: auto;
+}
+
+/* ── Navigation ── */
+
+.ct-toolbar__nav {
+  display: flex;
+  align-items: center;
+  gap: var(--ct-toolbar-nav-gap);
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.ct-toolbar__nav-link {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  padding: var(--ct-toolbar-nav-padding-y) var(--ct-toolbar-nav-padding-x);
+  border-radius: var(--radius-sm);
+  color: var(--color-text-secondary);
+  text-decoration: none;
+  font-size: var(--ct-toolbar-nav-font-size);
+  font-weight: var(--font-weight-medium);
+  white-space: nowrap;
+  transition: background var(--duration-fast) var(--easing-standard),
+    color var(--duration-fast) var(--easing-standard);
+}
+
+@media (hover: hover) {
+  .ct-toolbar__nav-link:hover {
+    background: var(--color-bg-muted);
+    color: var(--color-text-primary);
+  }
+}
+
+.ct-toolbar__nav-link:focus-visible {
+  outline: var(--border-medium) solid var(--color-focus-ring);
+  outline-offset: var(--border-medium);
+}
+
+.ct-toolbar__nav-link--active,
+.ct-toolbar__nav-link[aria-current='page'] {
+  background: var(--color-bg-muted);
+  color: var(--color-brand-primary);
+  font-weight: var(--font-weight-semibold);
+}
+
+/* ── Spacer ── */
+
+.ct-toolbar__spacer {
+  flex: 1;
+}
+
+/* ── Actions ── */
+
+.ct-toolbar__actions {
+  display: flex;
+  align-items: center;
+  gap: var(--ct-toolbar-actions-gap);
+  margin-inline-start: auto;
+}
+
+/* ── Groups (role="group" within role="toolbar") ── */
+
+.ct-toolbar__group {
+  display: flex;
+  align-items: center;
+  gap: var(--space-2);
+}
+
+/* ── Separator (visual divider between groups) ── */
+
+.ct-toolbar__separator {
+  width: var(--border-thin);
+  height: var(--space-6);
+  background: var(--color-border-subtle);
+  flex-shrink: 0;
+}
+
+/* ── Size: Small ── */
+
+.ct-toolbar--sm {
+  --ct-toolbar-height: var(--control-height-md);
+  --ct-toolbar-padding-x: var(--space-5);
+  --ct-toolbar-brand-img-height: var(--space-8);
+  --ct-toolbar-nav-font-size: var(--font-size-xs);
+  --ct-toolbar-nav-padding-y: var(--space-2);
+  --ct-toolbar-nav-padding-x: var(--space-3);
+}
+
+/* ── Size: Large ── */
+
+.ct-toolbar--lg {
+  --ct-toolbar-height: var(--space-12);
+  --ct-toolbar-padding-x: var(--space-8);
+  --ct-toolbar-brand-img-height: var(--space-10);
+  --ct-toolbar-nav-font-size: var(--font-size-md);
+  --ct-toolbar-nav-padding-y: var(--space-4);
+  --ct-toolbar-nav-padding-x: var(--space-5);
+}
+
+/* ── Dense ── */
+
+.ct-toolbar--dense {
+  --ct-toolbar-height: var(--control-height-sm);
+  --ct-toolbar-padding-x: var(--space-4);
+  --ct-toolbar-brand-img-height: var(--space-7);
+  --ct-toolbar-nav-font-size: var(--font-size-xs);
+  --ct-toolbar-nav-padding-y: var(--space-1);
+  --ct-toolbar-nav-padding-x: var(--space-3);
+  --ct-toolbar-gap: var(--space-3);
+  --ct-toolbar-nav-gap: var(--space-0);
+  --ct-toolbar-actions-gap: var(--space-2);
+}
+
+/* ── Sticky ── */
+
+.ct-toolbar--sticky {
+  position: sticky;
+  inset-block-start: 0;
+}
+
+/* ── Borderless ── */
+
+.ct-toolbar--borderless {
+  border-bottom: none;
+}
+
+/* ── Secondary ── */
+
+.ct-toolbar--secondary {
+  background: var(--color-bg-surface);
+}
+
+.ct-toolbar--secondary .ct-toolbar__nav-link--active,
+.ct-toolbar--secondary .ct-toolbar__nav-link[aria-current='page'] {
+  background: var(--color-bg-elevated);
+}
+
+/* ── Mobile Trigger ── */
+
+.ct-toolbar__mobile-trigger {
+  display: none;
+}
+
+@media (max-width: 899px) { /* < md breakpoint (900px) */
+  .ct-toolbar {
+    position: relative;
+  }
+
+  .ct-toolbar__nav {
+    display: none;
+  }
+
+  .ct-toolbar__mobile-trigger {
+    display: inline-flex;
+  }
+
+  .ct-toolbar[data-mobile-nav='open'] .ct-toolbar__nav {
+    display: flex;
+    flex-direction: column;
+    align-items: stretch;
+    position: absolute;
+    inset-block-start: 100%;
+    inset-inline-start: 0;
+    inset-inline-end: 0;
+    background: var(--color-bg-elevated);
+    border-bottom: var(--border-thin) solid var(--color-border-subtle);
+    padding: var(--space-4);
+    gap: var(--space-2);
+    z-index: var(--z-dropdown);
+    box-shadow: var(--shadow-md);
+  }
+}
+
+/* ── Reduced Motion ── */
+
+@media (prefers-reduced-motion: reduce) {
+  .ct-toolbar__nav-link {
+    transition: none;
+  }
+}

package/components/tooltip.css

@@ -0,0 +1,124 @@
+.ct-tooltip {
+  position: relative;
+  display: inline-flex;
+}
+
+.ct-tooltip__content {
+  --_tt-offset: calc(100% + var(--space-2));
+  --_tt-origin-x: 0px;
+  --_tt-origin-y: 0px;
+  --_tt-slide-dir-x: 0;
+  --_tt-slide-dir-y: 0;
+  --_tt-open: 0;
+
+  position: absolute;
+  z-index: var(--z-tooltip);
+  width: max-content;
+  max-width: min(var(--ct-tooltip-max-width), 90vw);
+  padding: var(--space-2) var(--space-3);
+  background: var(--ct-tooltip-bg);
+  color: var(--ct-tooltip-color);
+  border-radius: var(--ct-tooltip-radius);
+  box-shadow: var(--ct-tooltip-shadow);
+  font-size: var(--font-size-xs);
+  line-height: var(--line-height-xs);
+  white-space: normal;
+  overflow-wrap: anywhere;
+  opacity: 0;
+  visibility: hidden;
+  pointer-events: none;
+  transform: translate(
+    calc(var(--_tt-origin-x) + var(--_tt-slide-dir-x) * 4px * (1 - var(--_tt-open))),
+    calc(var(--_tt-origin-y) + var(--_tt-slide-dir-y) * 4px * (1 - var(--_tt-open)))
+  );
+  transition: opacity var(--duration-fast) var(--easing-standard),
+    transform var(--duration-fast) var(--easing-standard),
+    visibility 0s linear var(--duration-fast);
+}
+
+.ct-tooltip[data-state='open'] .ct-tooltip__content,
+.ct-tooltip:focus-within .ct-tooltip__content {
+  --_tt-open: 1;
+  opacity: 1;
+  visibility: visible;
+  transition: opacity var(--duration-fast) var(--easing-standard),
+    transform var(--duration-fast) var(--easing-standard),
+    visibility 0s linear 0s;
+}
+
+@media (hover: hover) {
+  .ct-tooltip:hover .ct-tooltip__content {
+    --_tt-open: 1;
+    opacity: 1;
+    visibility: visible;
+    transition: opacity var(--duration-fast) var(--easing-standard),
+      transform var(--duration-fast) var(--easing-standard),
+      visibility 0s linear 0s;
+  }
+}
+
+/* Side positioning (default center alignment) */
+
+.ct-tooltip[data-side='top'] .ct-tooltip__content {
+  inset-block-end: var(--_tt-offset);
+  inset-inline-start: 50%;
+  --_tt-origin-x: -50%;
+  --_tt-slide-dir-y: -1;
+}
+
+.ct-tooltip[data-side='bottom'] .ct-tooltip__content {
+  inset-block-start: var(--_tt-offset);
+  inset-inline-start: 50%;
+  --_tt-origin-x: -50%;
+  --_tt-slide-dir-y: 1;
+}
+
+.ct-tooltip[data-side='left'] .ct-tooltip__content {
+  inset-inline-end: var(--_tt-offset);
+  inset-block-start: 50%;
+  --_tt-origin-y: -50%;
+  --_tt-slide-dir-x: -1;
+}
+
+.ct-tooltip[data-side='right'] .ct-tooltip__content {
+  inset-inline-start: var(--_tt-offset);
+  inset-block-start: 50%;
+  --_tt-origin-y: -50%;
+  --_tt-slide-dir-x: 1;
+}
+
+/* Cross-axis alignment: start */
+
+.ct-tooltip[data-align='start'][data-side='top'] .ct-tooltip__content,
+.ct-tooltip[data-align='start'][data-side='bottom'] .ct-tooltip__content {
+  inset-inline-start: 0;
+  --_tt-origin-x: 0px;
+}
+
+.ct-tooltip[data-align='start'][data-side='left'] .ct-tooltip__content,
+.ct-tooltip[data-align='start'][data-side='right'] .ct-tooltip__content {
+  inset-block-start: 0;
+  --_tt-origin-y: 0px;
+}
+
+/* Cross-axis alignment: end */
+
+.ct-tooltip[data-align='end'][data-side='top'] .ct-tooltip__content,
+.ct-tooltip[data-align='end'][data-side='bottom'] .ct-tooltip__content {
+  inset-inline-start: auto;
+  inset-inline-end: 0;
+  --_tt-origin-x: 0px;
+}
+
+.ct-tooltip[data-align='end'][data-side='left'] .ct-tooltip__content,
+.ct-tooltip[data-align='end'][data-side='right'] .ct-tooltip__content {
+  inset-block-start: auto;
+  inset-block-end: 0;
+  --_tt-origin-y: 0px;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ct-tooltip__content {
+    transition: none;
+  }
+}

package/docs/guidelines.md

@@ -0,0 +1,141 @@
+# Construct Design Guidelines
+
+## Goal
+
+A consistent, accessible, professional design system for modern web applications built with Angular, React, Svelte, or vanilla HTML/CSS.
+
+**Accessibility is Priority #1.**
+
+## Do / Don't
+
+### Do
+
+- Use semantic HTML (`button`, `input`, `label`, `table`, `nav`)
+- Use design tokens for colors, spacing, typography, and border radius
+- Maintain clear state logic (hover, focus, active, disabled, error)
+- Use consistent sizes (sm, md, lg) for form controls and buttons
+- Establish clear hierarchies (Primary vs. Secondary actions)
+- Test all components with keyboard navigation (Tab, Shift+Tab, Enter, Space)
+
+### Don't
+
+- Don't rely on color alone for status information without text or icons
+- Don't create custom controls without ARIA roles and keyboard support
+- Don't use fixed pixel layouts for content that can grow
+- Don't use low-contrast text or disabled states that are unreadable
+- Don't add unnecessary animations for critical actions
+
+## Accessibility Rules (Minimum)
+
+- **Visible Focus**: All interactive elements must have visible focus indication
+- **Labels**: Every form input must have a label (explicit `<label>` or `aria-label`)
+- **Keyboard Navigation**: Full support for dropdowns, tabs, modals, tooltips, datepickers
+- **ARIA**: Use ARIA attributes only where semantic HTML isn't sufficient
+- **Links**: Links must be distinguishable without color alone (e.g., underline)
+- **Contrast**: Text, icons, and focus rings must meet WCAG AA standards
+- **Themes**: Support light, dark, and high-contrast modes; respect user preferences
+- **Disabled States**: Must be recognizable, but content should remain readable
+- **Motion**: Respect `prefers-reduced-motion` for animations
+- **Live Regions**: Use `aria-live` for toasts and status messages
+- **Modal**: Requires `aria-modal`, `role="dialog"`, and focus trap
+
+## Keyboard Patterns for Composite Components
+
+### Tabs
+- **Arrow keys**: Move focus between tabs
+- **Home/End**: Jump to first/last tab
+- **Enter/Space**: Activate tab
+- **Implementation**: Use roving tabindex (active tab `tabindex="0"`, others `tabindex="-1"`)
+
+### Dropdown (Action-List)
+- **Trigger**: Uses `aria-expanded` and `aria-controls`
+- **Open**: Focus moves to first item
+- **Esc**: Closes and returns focus to trigger
+- **Items**: Normal buttons/links in tab order
+
+### Dropdown (Role=menu)
+- **Only use if implementing**: Arrow-key navigation, Home/End, typeahead, and roving tabindex
+- Most dropdowns should use Action-List pattern instead
+
+### Datepicker
+- **Arrow keys**: Move by day in calendar grid
+- **PageUp/PageDown**: Switch months
+- **Home/End**: Jump to start/end of week
+- **Enter/Space**: Select date
+- **Esc**: Close and return focus to trigger
+
+### Modal
+- **Focus trap**: Focus stays within modal
+- **Initial focus**: Set to first focusable element or designated element
+- **Esc**: Close modal
+- **Close**: Return focus to trigger element
+
+### Drawer
+- **Focus trap**: Focus stays within drawer panel
+- **Initial focus**: First focusable element or designated element
+- **Esc**: Close drawer
+- **Close**: Return focus to trigger element
+- **Backdrop**: Click closes drawer
+
+### Tooltip
+- **Open**: On hover and focus
+- **Close**: On blur and Esc
+- **Role**: `role="tooltip"` with `aria-describedby`
+
+## Component States
+
+Use these attributes for state management:
+
+- **error**: `aria-invalid="true"` + visible error text
+- **disabled**: `disabled` or `aria-disabled="true"`
+- **selected**: `aria-selected="true"`
+- **current**: `aria-current="page"`
+- **expanded**: `aria-expanded="true|false"`
+
+## Breakpoints & Media Queries
+
+Construct defines breakpoint tokens in `tokens/primitives.json`:
+
+| Token | Value | Typical use |
+|-------|-------|-------------|
+| `xs`  | 360px | Small phones |
+| `sm`  | 600px | Large phones / small tablets |
+| `md`  | 900px | Tablets / small laptops |
+| `lg`  | 1200px | Desktops |
+| `xl`  | 1536px | Large screens |
+
+### Convention
+
+CSS custom properties cannot be used inside `@media` queries. Use the raw pixel values with a reference comment:
+
+```css
+@media (max-width: 599px) { /* < sm breakpoint (600px) */
+  /* Mobile styles */
+}
+
+@media (max-width: 899px) { /* < md breakpoint (900px) */
+  /* Tablet styles */
+}
+```
+
+**Rules:**
+- Always use `max-width: <token - 1>px` to target viewports *below* a breakpoint
+- Always add a reference comment noting the breakpoint name and token value
+- Only use values derived from the token system — never arbitrary pixel values
+- Current components use two breakpoints: `< sm` (599px) and `< md` (899px)
+
+## Fonts
+
+- **Default**: Fonts are loaded via Google Fonts in `foundations.css` (Sora, Source Sans 3, JetBrains Mono)
+- **Self-hosting**: For CSP or privacy requirements, replace Google Fonts import with local `@font-face` rules
+- **Weights**: Ensure 400, 500, 600, and 700 are available
+
+## Governance
+
+- **New components require**: Design tokens, state definitions, accessibility notes, Storybook story
+- **Before merge**: Visual QA + keyboard testing + contrast check
+- **Review process**: At least one accessibility review for new interactive components
+
+---
+
+**Construct** - Build accessible design constructs