@portfoliablejs/valence 0.1.0

package/src/stories/sub-atomic/Architecture/Architecture.mdx

@@ -0,0 +1,176 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Sub-atomic/Architecture" />
+
+# Web Component Architecture
+
+The Web Component Architecture document defines platform-wide technical standards, Shadow DOM encapsulation patterns, state management strategies, and accessibility delegation protocols across Valence components.
+
+<br />
+
+## Core Architectural Principles
+
+Valence Web Components adhere to four architectural tenets to guarantee cross-browser compatibility, framework-agnostic integration, and strict design token encapsulation.
+
+<table style={{ width: '100%', borderCollapse: 'collapse' }}>
+  <thead>
+    <tr>
+      <th style={{ textAlign: 'left' }}>Principle</th>
+      <th style={{ textAlign: 'left' }}>Implementation Standard</th>
+      <th style={{ textAlign: 'left' }}>Architectural Purpose</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><strong>Shadow DOM Encapsulation</strong></td>
+      <td><code>`this.attachShadow({ mode: 'open' })`</code></td>
+      <td>Isolates internal DOM structure and prevents application CSS leakages.</td>
+    </tr>
+    <tr>
+      <td><strong>Sub-Atomic Property Overrides</strong></td>
+      <td><code>var(--custom-*, var(--token-*))</code></td>
+      <td>Allows component instance customization without breaking design token encapsulation.</td>
+    </tr>
+    <tr>
+      <td><strong>Root Class Reflection</strong></td>
+      <td><code>MutationObserver</code> on <code>document.documentElement</code></td>
+      <td>Bypasses lack of <code>:host-context()</code> support in Safari/WebKit browsers.</td>
+    </tr>
+    <tr>
+      <td><strong>ARIA Delegation & Scrubbing</strong></td>
+      <td>Attribute delegation to internal focusable nodes</td>
+      <td>Prevents <code>aria-prohibited-attr</code> violations on custom element host tags.</td>
+    </tr>
+  </tbody>
+</table>
+
+<br />
+
+## Shadow DOM & CSS Token Encapsulation
+
+Components consume scoped CSS via template literal injection or imported stylesheets. CSS custom variables cascade through the Shadow root boundary, allowing global sub-atomic tokens (`--color-*`, `--space-*`, `--radius-*`) to style internal shadow trees seamlessly.
+
+### Sub-Atomic Fallback Override Pattern
+
+To permit one-off customizations (or Storybook Control overrides) while maintaining token fallback integrity, component styles consume fallback variables:
+
+```css
+/* Custom background override with design token default */
+.button-primary {
+  background: var(--custom-bg, var(--color-black));
+  border-radius: var(--custom-radius, var(--radius-pill));
+  border: var(--custom-border-width, var(--border-width-thin)) 
+          var(--border-style-solid) 
+          var(--custom-border-color, var(--color-black));
+}
+
+```
+
+## Cross-Browser Accessibility & Theme Reflection
+
+The CSS pseudo-class `:host-context()` is unsupported in Safari and WebKit environments. To guarantee universal compatibility across Chrome, Safari, and Firefox, Web Components observe class mutations on `document.documentElement` and reflect active accessibility modes directly onto host attributes.
+
+### MutationObserver Sync Pattern
+
+```javascript
+_observeRootAccessibility() {
+  const root = this.ownerDocument.documentElement;
+
+  const sync = () => {
+    this.toggleAttribute('a11y-dark-mode', root.classList.contains('a11y-dark-mode'));
+    this.toggleAttribute('a11y-high-contrast', root.classList.contains('a11y-high-contrast'));
+    this.toggleAttribute('a11y-dyslexia', root.classList.contains('a11y-dyslexia'));
+    this.toggleAttribute('a11y-reduce-motion', root.classList.contains('a11y-reduce-motion'));
+  };
+
+  sync(); // Initial execution on mount
+
+  this._themeObserver = new MutationObserver(sync);
+  this._themeObserver.observe(root, {
+    attributes: true,
+    attributeFilter: ['class'],
+  });
+}
+
+disconnectedCallback() {
+  if (this._themeObserver) {
+    this._themeObserver.disconnect();
+  }
+}
+
+```
+
+### Host Attribute Styling Pattern
+
+Components target boolean host attributes within internal stylesheets rather than relying on `:host-context()`:
+
+```css
+/* Dark mode floating element states */
+:host([a11y-dark-mode]) .variant-floating {
+  background: var(--custom-bg, var(--color-player-bg, #101218)) !important;
+  color: var(--color-white) !important;          
+  border: var(--border-width-medium) var(--border-style-solid) var(--color-surface-border) !important;
+  box-shadow: var(--shadow-none) !important;
+}
+:host([a11y-dark-mode]) .variant-floating:hover:not(:disabled) {
+  background-color: var(--custom-hover-bg, #1C1C1E) !important;
+  border-color: var(--color-white) !important;
+}
+
+/* Dyslexia mode overrides */
+:host([a11y-dyslexia]) button {
+  font-family: "Comic Sans MS", "Comic Sans", cursive, sans-serif !important;
+  letter-spacing: 0.05em !important;
+  word-spacing: 0.1em !important;
+}
+```
+
+## ARIA Delegation & Host Attribute Scrubbing
+
+When generic Web Component tags receive descriptive properties like `aria-label`, leaving these attributes on the outer host element can trigger accessibility compliance errors (`aria-prohibited-attr`).
+
+Valence components delegate ARIA properties to internal focusable nodes and scrub the host tag during lifecycle rendering updates.
+
+### ARIA Delegation Lifecycle Pattern
+
+```javascript
+updateAttributes() {
+  const ariaLabel = this.getAttribute('aria-label');
+  const disabled = this.hasAttribute('disabled');
+
+  if (this.buttonEl) {
+    this.buttonEl.disabled = disabled;
+  }
+
+  // Delegate aria-label to internal primitive and scrub host element
+  if (ariaLabel) {
+    if (this.buttonEl) {
+      this.buttonEl.setAttribute('aria-label', ariaLabel);
+    }
+    this.removeAttribute('aria-label'); // Keeps outer host DOM compliant
+  }
+}
+
+```
+
+## Layout & Slot Hygiene
+
+To prevent unwanted whitespace or layout shifts caused by empty text nodes between HTML slot tags, component template rendering strings are compressed without extraneous whitespace surrounding shadow DOM primitives:
+
+```javascript
+constructor() {
+  super();
+  this.attachShadow({ mode: 'open' });
+  
+  // Compressed template string prevents ghost text nodes inside Shadow DOM layouts
+  this.shadowRoot.innerHTML = `<style>${css}</style><button type="button"><ds-icon class="btn-icon" style="display: none;"></ds-icon><slot></slot></button>`;
+}
+
+```
+
+## Best Practices
+
+* **Memory Management**: Always call `this._themeObserver.disconnect()` inside `disconnectedCallback()` to prevent memory leaks when components unmount.
+* **Observed Attributes Syncing**: List core properties (`variant`, `disabled`, `aria-label`, `icon`) inside `static get observedAttributes()` and trigger `updateAttributes()` on change.
+* **Universal Safari Support**: Never use `:host-context()`. Always reflect root accessibility modifier classes to host boolean attributes (`:host([a11y-*])`).
+* **Clean Shadow DOM**: Always delegate host accessibility attributes (`aria-label`) down to native interactive primitives (`<button>`, `<input>`) and remove them from the host wrapper tag.

package/src/stories/sub-atomic/Borderography/Borderography.mdx

@@ -0,0 +1,94 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Sub-atomic/Borderography"/>
+
+# Borderography
+
+The Borderography system defines standardized border widths and line styles across components. Paired with Curvography (border radii), it completes the structural framing of Valence interfaces.
+
+<br />
+
+## Border Width & Style Tokens
+
+Border tokens manage outlines, structural dividers, focus rings, and card encasements.
+
+<table style={{ width: '100%', borderCollapse: 'collapse' }}>
+  <thead>
+    <tr>
+      <th style={{ textAlign: 'left' }}>Token</th>
+      <th style={{ textAlign: 'left' }}>CSS Variable</th>
+      <th style={{ textAlign: 'left' }}>Value</th>
+      <th style={{ textAlign: 'left' }}>Usage Guidelines</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><strong>Thin Border</strong></td>
+      <td>`var(--border-width-thin)`</td>
+      <td>`1px`</td>
+      <td>Standard card outlines, table borders, input fields, dividers.</td>
+    </tr>
+    <tr>
+      <td><strong>Medium Border</strong></td>
+      <td>`var(--border-width-medium)`</td>
+      <td>`2px`</td>
+      <td>Selected states, tab highlights, active input rings.</td>
+    </tr>
+    <tr>
+      <td><strong>Thick Border</strong></td>
+      <td>`var(--border-width-thick)`</td>
+      <td>`4px`</td>
+      <td>Accessibility focus rings, prominent status banners.</td>
+    </tr>
+    <tr>
+      <td><strong>Solid Style</strong></td>
+      <td>`var(--border-style-solid)`</td>
+      <td>`solid`</td>
+      <td>Default border rendering across standard UI elements.</td>
+    </tr>
+    <tr>
+      <td><strong>Dashed Style</strong></td>
+      <td>`var(--border-style-dashed)`</td>
+      <td>`dashed`</td>
+      <td>File upload drop zones, placeholder containers.</td>
+    </tr>
+  </tbody>
+</table>
+
+<br />
+
+## Usage Guidelines
+
+Use standard border shorthand or explicit border variables when constructing component styles.
+
+### CSS Example
+
+```css
+.card {
+  border: var(--border-width-thin) var(--border-style-solid) var(--color-card-border);
+}
+
+.dropzone {
+  border: var(--border-width-medium) var(--border-style-dashed) var(--color-gray-med);
+}
+
+.button:focus-visible {
+  outline: var(--border-width-thick) var(--border-style-solid) var(--color-accent);
+}
+```
+
+## Sub-Atomic Property Overrides
+
+For dynamic border customization in molecules or story controls, components reference custom border variables before defaulting to design tokens:
+
+```css
+.card {
+  border: var(--custom-border-width, var(--border-width-thin)) 
+          var(--border-style-solid) 
+          var(--custom-border-color, var(--color-card-border));
+}
+````
+
+## Best Practices
+- Explicit Thickness: Always use --border-width-thin (1px) for internal dividing lines and structural cards to keep UI geometry sharp and clean.
+- Focus Rings: Standardize active accessibility focus indicators around --border-width-thick (4px) for clear keyboard visibility.

package/src/stories/sub-atomic/Borderography/borderography.css

@@ -0,0 +1,12 @@
+:root {
+  /* Border Width Tokens */
+  --border-width-none: 0px;
+  --border-width-thin: 1px;
+  --border-width-medium: 2px;
+  --border-width-thick: 4px;
+
+  /* Border Style Tokens */
+  --border-style-solid: solid;
+  --border-style-dashed: dashed;
+  --border-style-dotted: dotted;
+}

package/src/stories/sub-atomic/Choreography/Choreography.mdx

@@ -0,0 +1,322 @@
+import { Meta, Controls } from '@storybook/addon-docs/blocks';
+
+<Meta title="Sub-atomic/Choreography" />
+
+# Choreography
+
+The Choreography system provides standardized easing curves and timing values to bring fluid, responsive motion to Valence components. Using consistent motion principles ensures transitions feel purposeful, deliberate, and delightful across the entire platform.
+
+<br />
+
+## Easing Tokens
+
+Easing functions dictate standard acceleration and deceleration curves for regular UI transitions.
+
+<table style={{ width: '100%', borderCollapse: 'collapse' }}>
+  <thead>
+    <tr>
+      <th style={{ textAlign: 'left' }}>Curve</th>
+      <th style={{ textAlign: 'left' }}>Token</th>
+      <th style={{ textAlign: 'left' }}>Value</th>
+      <th style={{ textAlign: 'left' }}>Description / Best For</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><strong>Standard Ease</strong></td>
+      <td>`var(--ease-standard)`</td>
+      <td>`ease`</td>
+      <td>Default CSS transition curve. Good for simple state changes.</td>
+    </tr>
+    <tr>
+      <td><strong>Fluid Ease</strong></td>
+      <td>`var(--ease-fluid)`</td>
+      <td>`cubic-bezier(0.16, 1, 0.3, 1)`</td>
+      <td>Starts fast and gently decelerates toward the end position. Ideal for modals, panels, and primary transitions.</td>
+    </tr>
+  </tbody>
+</table>
+*Hover over the cards to compare standard vs. fluid deceleration curves:*
+
+<div style={{ display: 'flex', gap: '16px', margin: '20px 0', flexWrap: 'wrap' }}>
+  <div 
+    style={{
+      padding: '20px 24px',
+      background: '#f4f6f8',
+      borderRadius: '8px',
+      border: '1px solid #e1e4e8',
+      cursor: 'pointer',
+      width: '200px',
+      transition: 'transform var(--anim-normal) var(--ease-standard)',
+    }}
+    onMouseEnter={(e) => e.currentTarget.style.transform = 'translateY(-8px)'}
+    onMouseLeave={(e) => e.currentTarget.style.transform = 'translateY(0)'}
+  >
+    <strong style={{ fontSize: '14px' }}>Standard Ease</strong>
+    <p style={{ margin: '4px 0 0', fontSize: '12px', color: '#666' }}><code>var(--ease-standard)</code></p>
+  </div>
+
+  <div 
+    style={{
+      padding: '20px 24px',
+      background: '#f4f6f8',
+      borderRadius: '8px',
+      border: '1px solid #e1e4e8',
+      cursor: 'pointer',
+      width: '200px',
+      transition: 'transform var(--anim-normal) var(--ease-fluid)',
+    }}
+    onMouseEnter={(e) => e.currentTarget.style.transform = 'translateY(-8px)'}
+    onMouseLeave={(e) => e.currentTarget.style.transform = 'translateY(0)'}
+  >
+    <strong style={{ fontSize: '14px' }}>Fluid Ease</strong>
+    <p style={{ margin: '4px 0 0', fontSize: '12px', color: '#666' }}><code>var(--ease-fluid)</code></p>
+  </div>
+</div>
+
+<br />
+
+## Physics & Motion Tokens
+
+Physics curves mimic real-world mechanical behaviors or continuous motion.
+
+<table style={{ width: '100%', borderCollapse: 'collapse' }}>
+  <thead>
+    <tr>
+      <th style={{ textAlign: 'left' }}>Type</th>
+      <th style={{ textAlign: 'left' }}>Token</th>
+      <th style={{ textAlign: 'left' }}>Value</th>
+      <th style={{ textAlign: 'left' }}>Description / Best For</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><strong>Spring Physics</strong></td>
+      <td>`var(--anim-spring)`</td>
+      <td>`cubic-bezier(0.34, 1.56, 0.64, 1)`</td>
+      <td>A bouncy, overshooting curve mimicking natural physics. Great for micro-interactions and toggles.</td>
+    </tr>
+    <tr>
+      <td><strong>Linear</strong></td>
+      <td>`var(--anim-linear)`</td>
+      <td>`linear`</td>
+      <td>Constant speed throughout without acceleration. Continuous looping animations (e.g., loading spinners).</td>
+    </tr>
+  </tbody>
+</table>
+
+*Hover over the Spring card or watch the Linear spinner:*
+
+<style>{`
+  @keyframes spin {
+    from { transform: rotate(0deg); }
+    to { transform: rotate(360deg); }
+  }
+`}</style>
+
+<div style={{ display: 'flex', gap: '16px', margin: '20px 0', alignItems: 'stretch', flexWrap: 'wrap' }}>
+  {/* Spring Card */}
+  <div 
+    style={{
+      padding: '16px 20px',
+      background: '#f4f6f8',
+      borderRadius: '8px',
+      border: '1px solid #e1e4e8',
+      cursor: 'pointer',
+      width: '200px',
+      height: '84px',
+      boxSizing: 'border-box',
+      display: 'flex',
+      flexDirection: 'column',
+      justifyCenter: 'center',
+      transition: 'transform var(--anim-fast) var(--anim-spring)',
+    }}
+    onMouseEnter={(e) => e.currentTarget.style.transform = 'scale(1.05)'}
+    onMouseLeave={(e) => e.currentTarget.style.transform = 'scale(1)'}
+  >
+    <strong style={{ fontSize: '14px' }}>Spring Bounce</strong>
+    <p style={{ margin: '4px 0 0', fontSize: '12px', color: '#666' }}><code>var(--anim-spring)</code></p>
+  </div>
+
+  {/* Linear Spinner Card */}
+  <div 
+    style={{
+      padding: '16px 20px',
+      background: '#f4f6f8',
+      borderRadius: '8px',
+      border: '1px solid #e1e4e8',
+      display: 'flex',
+      alignItems: 'center',
+      gap: '12px',
+      width: '200px',
+      height: '84px',
+      boxSizing: 'border-box',
+    }}
+  >
+    <div 
+      style={{
+        width: '20px',
+        height: '20px',
+        minWidth: '20px',
+        border: '3px solid #ccc',
+        borderTopColor: '#0052cc',
+        borderRadius: '50%',
+        animation: 'spin 1s var(--anim-linear) infinite',
+      }} 
+    />
+    <div>
+      <strong style={{ fontSize: '14px', display: 'block', lineHeight: '1.2' }}>Linear</strong>
+      <span style={{ fontSize: '12px', color: '#666' }}>Continuous loop</span>
+    </div>
+  </div>
+</div>
+
+
+
+<br />
+
+## Duration Tokens
+
+Duration tokens control the speed and timeframe of an animation from start to finish. Pair these values with easing curves to keep interface timing predictable.
+
+<table style={{ width: '100%', borderCollapse: 'collapse' }}>
+  <thead>
+    <tr>
+      <th style={{ textAlign: 'left' }}>Token</th>
+      <th style={{ textAlign: 'left' }}>CSS Variable</th>
+      <th style={{ textAlign: 'left' }}>Value</th>
+      <th style={{ textAlign: 'left' }}>Usage Guidelines</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><strong>Fast Speed</strong></td>
+      <td>`var(--anim-fast)`</td>
+      <td>`0.2s`</td>
+      <td>Immediate micro-interactions (hover states, active feedback, tooltips).</td>
+    </tr>
+    <tr>
+      <td><strong>Normal Speed</strong></td>
+      <td>`var(--anim-normal)`</td>
+      <td>`0.3s`</td>
+      <td>Standard UI state transitions (dropdowns, accordions, toast notifications).</td>
+    </tr>
+    <tr>
+      <td><strong>Slow Speed</strong></td>
+      <td>`var(--anim-slow)`</td>
+      <td>`0.4s`</td>
+      <td>Large layout shifts (panel slides, modal entrances, page transitions).</td>
+    </tr>
+  </tbody>
+</table>
+
+
+*Hover over each card to feel the speed difference (`0.2s` vs `0.3s` vs `0.4s`):*
+
+<div style={{ display: 'flex', gap: '16px', margin: '20px 0', flexWrap: 'wrap' }}>
+  <div 
+    style={{
+      padding: '20px 24px',
+      background: '#f4f6f8',
+      borderRadius: '8px',
+      border: '1px solid #e1e4e8',
+      cursor: 'pointer',
+      width: '160px',
+      transition: 'transform var(--anim-fast) var(--ease-fluid)',
+    }}
+    onMouseEnter={(e) => e.currentTarget.style.transform = 'translateY(-6px)'}
+    onMouseLeave={(e) => e.currentTarget.style.transform = 'translateY(0)'}
+  >
+    <strong style={{ fontSize: '14px' }}>Fast Speed</strong>
+    <p style={{ margin: '4px 0 0', fontSize: '12px', color: '#666' }}><code>0.2s</code></p>
+  </div>
+
+  <div 
+    style={{
+      padding: '20px 24px',
+      background: '#f4f6f8',
+      borderRadius: '8px',
+      border: '1px solid #e1e4e8',
+      cursor: 'pointer',
+      width: '160px',
+      transition: 'transform var(--anim-normal) var(--ease-fluid)',
+    }}
+    onMouseEnter={(e) => e.currentTarget.style.transform = 'translateY(-6px)'}
+    onMouseLeave={(e) => e.currentTarget.style.transform = 'translateY(0)'}
+  >
+    <strong style={{ fontSize: '14px' }}>Normal Speed</strong>
+    <p style={{ margin: '4px 0 0', fontSize: '12px', color: '#666' }}><code>0.3s</code></p>
+  </div>
+
+  <div 
+    style={{
+      padding: '20px 24px',
+      background: '#f4f6f8',
+      borderRadius: '8px',
+      border: '1px solid #e1e4e8',
+      cursor: 'pointer',
+      width: '160px',
+      transition: 'transform var(--anim-slow) var(--ease-fluid)',
+    }}
+    onMouseEnter={(e) => e.currentTarget.style.transform = 'translateY(-6px)'}
+    onMouseLeave={(e) => e.currentTarget.style.transform = 'translateY(0)'}
+  >
+    <strong style={{ fontSize: '14px' }}>Slow Speed</strong>
+    <p style={{ margin: '4px 0 0', fontSize: '12px', color: '#666' }}><code>0.4s</code></p>
+  </div>
+</div>
+
+<br />
+
+## Usage Guidelines
+
+Always combine choreography tokens in standard CSS `transition` or `animation` shorthand properties. Do not hardcode custom `cubic-bezier` curves or timing values in individual components.
+
+### CSS Example
+
+```css
+.card {
+  /* Transition transform property using standard duration and fluid easing */
+  transition: transform var(--anim-normal) var(--ease-fluid);
+}
+
+.card:hover {
+  transform: translateY(-4px);
+}
+
+.button-toggle {
+  /* Use spring physics for interactive feedback */
+  transition: transform var(--anim-fast) var(--anim-spring);
+}
+```
+
+## Keyframe Animation Example
+
+```css
+@keyframes spin {
+  from {
+    transform: rotate(0deg);
+  }
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+.loading-spinner {
+  animation: spin var(--anim-slow) var(--anim-linear) infinite;
+}
+```
+
+## Reduced Motion Integration
+
+When `.a11y-reduce-motion` is active on `document.documentElement`, all choreography timing tokens and scale transformations automatically reset to instant values to prevent vestibular triggers:
+
+* `--component-transition` evaluates to `all 0s linear !important`
+* `--btn-active-scale`, `--btn-hover-scale`, and `--btn-hover-scale-lg` evaluate to `1`
+* Global `transition-duration` and `animation-duration` are forced to `0s` (This bulletproofs the UI against Safari/WebKit bugs that fail to parse `transition: none`).
+
+This ensures interactive components respect user accessibility preferences automatically without requiring custom `@media (prefers-reduced-motion)` blocks in every single component.
+
+## Best Practices
+Purposeful Motion: Avoid animating elements unnecessarily. Every transition should communicate a state change or visual hierarchy shift to the user.
+Accessibility (html.a11y-reduce-motion): Respect user accessibility settings by disabling or simplifying movement when reduced motion is requested.

package/src/stories/sub-atomic/Choreography/choreography.css

@@ -0,0 +1,18 @@
+:root { 
+  /* Timing */ 
+  --anim-fast: 0.2s; 
+  --anim-normal: 0.3s; 
+  --anim-slow: 0.4s; 
+  
+  /* Physics */ 
+  --anim-spring: cubic-bezier(0.34, 1.56, 0.64, 1); /* Bouncy spring */ 
+  --anim-linear: linear; 
+
+  /* Speeds & Easing */
+  --ease-standard: ease;
+  --ease-fluid: cubic-bezier(0.16, 1, 0.3, 1);
+
+  /* Component Tokens (For Shadow DOM piercing) */
+  --component-transition: all var(--anim-normal) var(--ease-fluid);
+  
+}