@portfoliablejs/valence 0.1.0

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

@@ -0,0 +1,116 @@
+import { Meta, ColorPalette, ColorItem } from '@storybook/addon-docs/blocks';
+
+<Meta title="Sub-atomic/Chromography" />
+
+# Chromography
+
+The Chromography system forms the core visual foundation of Valence. It is a curated set of colors exposed as CSS Custom Properties (design tokens) to ensure strict consistency, accessibility, and theming capabilities across all components and applications.
+
+## Semantic Role Tokens (Theme Aware)
+
+These are the primary tokens components should consume. They automatically adjust across **Light Mode**, **Dark Mode**, and **High Contrast Mode** without breaking component-level logic.
+
+<ColorPalette>
+  <ColorItem 
+    title="Backgrounds & Surfaces" 
+    subtitle="Core UI canvas, container surfaces, and borders" 
+    colors={{ 
+      '--color-bg': '#FFFFFF', 
+      '--color-surface': '#F2F2F7', 
+      '--color-surface-border': 'rgba(0, 0, 0, 0.08)' 
+    }} 
+  />
+
+  <ColorItem 
+    title="Text & Foreground Content" 
+    subtitle="Primary headings, body text, and muted copy" 
+    colors={{ 
+      '--color-text-primary': '#000000', 
+      '--color-text-secondary': '#323232', 
+      '--color-text-muted': '#777777' 
+    }} 
+  />
+</ColorPalette>
+
+
+## Primitive Palette
+
+Immutable baseline colors used to build semantic roles and specialized states.
+
+<ColorPalette>
+  <ColorItem 
+    title="Base Primitives" 
+    subtitle="Static absolute black, white, and player canvas" 
+    colors={{ 
+      '--color-white': '#FFFFFF', 
+      '--color-black': '#000000', 
+      '--color-player-bg': '#101218' 
+    }} 
+  />
+  
+  <ColorItem 
+    title="Grayscale Scale" 
+    subtitle="Raw grayscale primitives" 
+    colors={{ 
+      '--color-gray-dark': '#323232', 
+      '--color-gray-med': '#777777', 
+      '--color-gray-light': '#B2B2B2', 
+      '--color-gray-xlight': '#D9D9D9' 
+    }} 
+  />
+  
+  <ColorItem 
+    title="Semantic Feedback & Accents" 
+    subtitle="Action triggers, states, and feedback indicators" 
+    colors={{ 
+      '--color-accent': '#2B71F0', 
+      '--color-success': '#34C759', 
+      '--color-error': '#FF3B30', 
+      '--color-error-alt': '#D73A49' 
+    }} 
+  />
+
+  <ColorItem 
+    title="Overlays & Glass" 
+    subtitle="Layering surfaces, backdrop blur accents, and modals" 
+    colors={{ 
+      '--color-overlay-dark': 'rgba(0, 0, 0, 0.85)', 
+      '--color-overlay-light': 'rgba(255, 255, 255, 0.1)', 
+      '--color-glass-bg': 'rgba(235, 235, 240, 0.6)' 
+    }} 
+  />
+</ColorPalette>
+
+
+## Usage Guidelines
+
+When implementing styles in Web Components or application stylesheets, **always reference semantic role variables directly** (`--color-text-primary`, `--color-surface`, `--color-bg`) rather than hardcoding primitive hex or RGB values.
+
+### Basic Implementation
+
+```css
+.card {
+  background-color: var(--color-surface);
+  border: 1px solid var(--color-surface-border);
+  color: var(--color-text-primary);
+}
+
+.button-primary {
+  background-color: var(--color-text-primary);
+  color: var(--color-bg);
+}
+```
+
+## Sub-Atomic Property Overrides
+To allow one-off background color customizations (or Storybook control overrides) without breaking token encapsulation, components consume background tokens using fallback variables:
+```css
+.variant-primary {
+  /* Uses --custom-bg if defined; otherwise defaults to --color-text-primary */
+  background: var(--custom-bg, var(--color-text-primary));
+}
+```
+
+## Best Practices
+- Semantic Priority: Prefer --color-text-primary and --color-surface over hardcoded --color-black or --color-white to ensure automatic dark mode and high-contrast compliance.
+- Feedback Standards: Use --color-error and --color-success exclusively for feedback, validation, and status updates—never purely for decorative accenting.
+- Accessibility (Contrast): Text rendered over --color-bg or custom container backgrounds maintains a contrast ratio meeting WCAG 2.1/2.2 AA guidelines (4.5:1 ratio for normal body text, 3:1 for large text).

package/src/stories/sub-atomic/Chromography/chromography.css

@@ -0,0 +1,44 @@
+:root {
+  /* ==========================================================================
+     PRIMITIVE PALETTE (DO NOT OVERRIDE IN THEMES)
+     ========================================================================== */
+  --color-white: #FFFFFF;
+  --color-black: #000000;
+  --color-player-bg: #101218;
+  
+  /* Gray Scale Primitives */
+  --color-gray-dark: #323232;
+  --color-gray-med: #777777;
+  --color-gray-light: #B2B2B2;
+  --color-gray-xlight: #D9D9D9;
+
+  /* Semantic Feedback & Accents */
+  --color-accent: #2B71F0;
+  --color-success: #34C759;
+  --color-error: #FF3B30;
+  --color-error-alt: #D73A49;
+  
+  /* Overlays & Glass */
+  --color-overlay-dark: rgba(0, 0, 0, 0.85);
+  --color-overlay-light: rgba(255, 255, 255, 0.1);
+  --color-glass-bg: rgba(235, 235, 240, 0.6);
+
+  /* KBD & Tooltips */
+  --color-kbd-border: rgba(0, 0, 0, 0.15);
+  --color-tooltip-kbd-border: rgba(255, 255, 255, 0.2);
+
+  /* ==========================================================================
+     SEMANTIC ROLE TOKENS (LIGHT MODE DEFAULT)
+     ========================================================================== */
+  --color-bg: var(--color-white);
+  --color-surface: #F2F2F7;
+  --color-surface-border: rgba(0, 0, 0, 0.15);
+  
+  --color-text-primary: var(--color-black);
+  --color-text-secondary: var(--color-gray-dark);
+  --color-text-muted: var(--color-gray-med);
+  
+  /* Backward Compatibility Alias */
+  --color-card-bg: var(--color-surface);
+  --color-card-border: rgba(0, 0, 0, 0.062);
+}

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

@@ -0,0 +1,104 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Sub-atomic/Curvography" />
+
+# Curvography
+
+The Curvography system defines standardized border-radius tokens across Valence. Regulating corner rounding soft-softens visual geometry, establishes structural hierarchy, and reinforces consistent tactile feedback for interactive UI components.
+
+<br />
+
+## Border Radii Tokens
+
+Border radius tokens control corner rounding to soften visual geometry and reinforce the visual feel of interactive elements.
+
+<table style={{ width: '100%', borderCollapse: 'collapse' }}>
+  <thead>
+    <tr>
+      <th style={{ textAlign: 'left' }}>Token Name</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>Small Radius</strong></td>
+      <td>`var(--radius-sm)`</td>
+      <td>`4px`</td>
+      <td>Subtle corner rounding (checkboxes, tags, tooltips).</td>
+    </tr>
+    <tr>
+      <td><strong>Medium Radius</strong></td>
+      <td>`var(--radius-md)`</td>
+      <td>`8px`</td>
+      <td>Standard component rounding (inputs, small buttons, cards).</td>
+    </tr>
+    <tr>
+      <td><strong>Large Radius</strong></td>
+      <td>`var(--radius-lg)`</td>
+      <td>`16px`</td>
+      <td>Container components (modals, large cards, popovers).</td>
+    </tr>
+    <tr>
+      <td><strong>XL Radius</strong></td>
+      <td>`var(--radius-xl)`</td>
+      <td>`24px`</td>
+      <td>Distinctive layout containers and feature cards.</td>
+    </tr>
+    <tr>
+      <td><strong>Pill</strong></td>
+      <td>`var(--radius-pill)`</td>
+      <td>`100px`</td>
+      <td>Pill-shaped elements (badges, action buttons, toggle switches).</td>
+    </tr>
+    <tr>
+      <td><strong>Circle</strong></td>
+      <td>`var(--radius-circle)`</td>
+      <td>`50%`</td>
+      <td>Fully circular elements (avatars, round icon buttons, status dots).</td>
+    </tr>
+  </tbody>
+</table>
+
+<br />
+
+## Usage Guidelines
+
+Apply border-radius tokens to ensure component geometry matches visual hierarchy. Do not hardcode static pixel values for corner rounding in scoped styles.
+
+### Component Implementation
+
+```css
+.button {
+  border-radius: var(--radius-md);
+}
+
+.modal-dialog {
+  border-radius: var(--radius-lg);
+}
+
+.status-badge {
+  border-radius: var(--radius-pill);
+}
+
+.user-avatar {
+  border-radius: var(--radius-circle);
+}
+```
+
+## Sub-Atomic Property Overrides
+
+Components accept `--custom-radius` overrides while preserving design token fallbacks:
+
+```css
+.button {
+  /* Uses --custom-radius if defined; defaults to design token */
+  border-radius: var(--custom-radius, var(--radius-pill));
+}
+```
+
+## Best Practices
+- **Nested Radii Hierarchy**: When nesting rounded containers inside one another, match or scale down inner radii (`--radius-sm` inside `--radius-md`) to avoid unnatural visual overlaps.
+- **Consistency across States**: Avoid altering `border-radius` dynamically on hover/active states unless explicitly designing morphing controls.
+- **Pill vs. Circle Usage**: Use `--radius-pill` for fluid width containers like buttons and tags; reserve `--radius-circle` exclusively for fixed 1:1 aspect ratio elements.

package/src/stories/sub-atomic/Curvography/curvography.css

@@ -0,0 +1,9 @@
+:root {
+  /* Border Radii */
+  --radius-sm: 4px;
+  --radius-md: 8px;
+  --radius-lg: 16px;
+  --radius-xl: 24px;
+  --radius-pill: 100px;
+  --radius-circle: 50%;
+}

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

@@ -0,0 +1,79 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Sub-atomic/Depthography" />
+
+# Depthography
+
+The Depthography system provides standardized backdrop blurs, surface layering, and glassmorphic elevation effects to establish depth across Valence components. Using structured translucency and blur tokens creates spatial hierarchy while maintaining contextual awareness of underlying content.
+
+<br />
+
+## Depth Tokens
+
+Depth tokens define atmospheric effects, translucency ratios, and backdrop blurs used to separate spatial layers.
+
+<table style={{ width: '100%', borderCollapse: 'collapse' }}>
+  <thead>
+    <tr>
+      <th style={{ textAlign: 'left' }}>Token Name</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>Glass Background</strong></td>
+      <td>`var(--overlay-glass-bg)`</td>
+      <td>`rgba(0, 0, 0, 0.1)`</td>
+      <td>Base surface color for translucent elements, floating headers, and popovers.</td>
+    </tr>
+    <tr>
+      <td><strong>Glass Blur</strong></td>
+      <td>`var(--overlay-glass-blur)`</td>
+      <td>`6px`</td>
+      <td>Defines the backdrop blur intensity for depth-based separation.</td>
+    </tr>
+  </tbody>
+</table>
+
+<br />
+
+## Usage Guidelines
+
+Always reference depth design tokens via CSS variables or standard utility classes to maintain consistency across elevated UI elements.
+
+### Utility Class Implementation
+
+For standard layout structures, apply the `.foundation-glass` utility class directly to your container components.
+
+```css
+/* Global foundation glass utility */
+.foundation-glass {
+  background: var(--overlay-glass-bg);
+  backdrop-filter: blur(var(--overlay-glass-blur));
+  -webkit-backdrop-filter: blur(var(--overlay-glass-blur));
+}
+```
+
+### CSS Variable Implementation
+When crafting custom Web Components or scoped styles, combine the individual variables to match specific UI requirements.
+```css
+.sticky-header {
+  background: var(--overlay-glass-bg);
+  backdrop-filter: blur(var(--overlay-glass-blur));
+  -webkit-backdrop-filter: blur(var(--overlay-glass-blur));
+  border-bottom: 1px solid rgba(255, 255, 255, 0.1);
+}
+
+.floating-panel {
+  background: var(--overlay-glass-bg);
+  backdrop-filter: blur(var(--overlay-glass-blur));
+  -webkit-backdrop-filter: blur(var(--overlay-glass-blur));
+}
+```
+
+## Best Practices
+- **Layering & Hierarchy**: Limit glassmorphic surfaces to floating or overlay elements (e.g., sticky headers, modals, context menus) to prevent visual clutter and maintain visual hierarchy.
+- **Cross-Browser Compatibilit**: Always include `-webkit-backdrop-filter` alongside standard `backdrop-filter` to guarantee full support across Safari and older WebKit-based browsers.
+- **Readability & Contrast**: Ensure text overlaid on translucent background layers meets WCAG AA contrast standards regardless of dynamic content scrolling beneath the surface.

package/src/stories/sub-atomic/Depthography/depthography.css

@@ -0,0 +1,11 @@
+:root {
+  --overlay-glass-bg: rgba(0, 0, 0, 0.1);
+  --overlay-glass-blur: 6px;
+}
+
+/* Utility class for global usage if needed */
+.foundation-glass {
+  background: var(--overlay-glass-bg);
+  backdrop-filter: blur(var(--overlay-glass-blur));
+  -webkit-backdrop-filter: blur(var(--overlay-glass-blur));
+}

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

@@ -0,0 +1,202 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Sub-atomic/Formography" />
+
+# Formography
+
+The Formography system defines design standards, structural geometry, validation state behaviors, and accessibility requirements across Valence form controls (inputs, textareas, selects, checkboxes, radios, and switches).
+
+<br />
+
+## Form Control Sizing & Target Bounds
+
+Form elements leverage `Sizography` height tokens to align predictably on horizontal layout grids while meeting WCAG touch target recommendations.
+
+<table style={{ width: '100%', borderCollapse: 'collapse' }}>
+  <thead>
+    <tr>
+      <th style={{ textAlign: 'left' }}>Size Token</th>
+      <th style={{ textAlign: 'left' }}>Control Height</th>
+      <th style={{ textAlign: 'left' }}>Internal Padding</th>
+      <th style={{ textAlign: 'left' }}>Usage Guidelines</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><code>var(--size-height-sm)</code></td>
+      <td><code>32px</code></td>
+      <td><code>var(--space-xs) var(--space-sm)</code></td>
+      <td>Compact form layouts, inline table controls, search bars.</td>
+    </tr>
+    <tr>
+      <td><strong>Default: </strong><code>var(--size-height-md)</code></td>
+      <td><code>40px</code></td>
+      <td><code>var(--space-xs) var(--space-md)</code></td>
+      <td>Standard form inputs, select dropdowns, and text inputs.</td>
+    </tr>
+    <tr>
+      <td><code>var(--size-height-lg)</code></td>
+      <td><code>48px</code></td>
+      <td><code>var(--space-sm) var(--space-lg)</code></td>
+      <td>Prominent mobile-first inputs and search interfaces (WCAG AAA touch target).</td>
+    </tr>
+  </tbody>
+</table>
+
+<br />
+
+## Validation & Feedback States
+
+Formography standardizes validation semantics across four structural states: **Default / Rest**, **Focus**, **Error / Invalid**, and **Success / Valid**.
+
+<table style={{ width: '100%', borderCollapse: 'collapse' }}>
+  <thead>
+    <tr>
+      <th style={{ textAlign: 'left' }}>State</th>
+      <th style={{ textAlign: 'left' }}>Border & Focus Color</th>
+      <th style={{ textAlign: 'left' }}>Background / Icon Token</th>
+      <th style={{ textAlign: 'left' }}>Accessibility Requirement</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td><strong>Rest</strong></td>
+      <td><code>var(--color-gray-light)</code></td>
+      <td><code>var(--color-bg)</code></td>
+      <td>Label associated via <code>for</code> or <code>aria-labelledby</code>.</td>
+    </tr>
+    <tr>
+      <td><strong>Active / Focus</strong></td>
+      <td><code>var(--color-accent)</code></td>
+      <td><code>outline: 3px solid var(--color-accent)</code></td>
+      <td>Visible focus ring via <code>:focus-visible</code>.</td>
+    </tr>
+    <tr>
+      <td><strong>Invalid / Error</strong></td>
+      <td><code>var(--color-error)</code></td>
+      <td>Helper text in <code>var(--color-error)</code></td>
+      <td>Requires <code>aria-invalid="true"</code> and <code>aria-describedby="[error-id]"</code>.</td>
+    </tr>
+    <tr>
+      <td><strong>Valid / Success</strong></td>
+      <td><code>var(--color-success)</code></td>
+      <td>Optional checkmark icon</td>
+      <td>Communicates valid input criteria upon blur or submit.</td>
+    </tr>
+  </tbody>
+</table>
+
+<br />
+
+## Usage Guidelines
+
+Construct form inputs using sub-atomic border, sizing, and color tokens. Ensure label containers and helper messages maintain standard spatial hierarchy (`--space-xs` gaps).
+
+### Text Input CSS Implementation
+
+```css
+.form-field {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-xs);
+  width: 100%;
+}
+
+.input-control {
+  height: var(--size-height-md);
+  padding: 0 var(--space-md);
+  font-family: var(--font-family);
+  font-size: 16px;
+  color: var(--color-black);
+  background: var(--custom-bg, var(--color-bg));
+  border: var(--border-width-thin) var(--border-style-solid) var(--color-gray-light);
+  border-radius: var(--custom-radius, var(--radius-md));
+  transition: border-color var(--anim-fast) var(--ease-fluid),
+              box-shadow var(--anim-fast) var(--ease-fluid);
+}
+
+/* Active Focus State */
+.input-control:focus-visible {
+  outline: none;
+  border-color: var(--color-accent);
+  box-shadow: 0 0 0 3px rgba(43, 113, 240, 0.2);
+}
+
+/* Invalid / Error State */
+.input-control[aria-invalid="true"] {
+  border-color: var(--color-error);
+}
+
+.input-control[aria-invalid="true"]:focus-visible {
+  box-shadow: 0 0 0 3px rgba(255, 59, 48, 0.2);
+}
+
+/* Disabled State */
+.input-control:disabled {
+  opacity: var(--opacity-disabled);
+  background: var(--color-card-bg);
+  cursor: not-allowed;
+}
+
+```
+
+## Accessible Form Anatomy
+
+Every interactive form control must maintain an explicit, accessible structure connecting labels, inputs, and feedback messages.
+
+```html
+<div class="form-field">
+  <!-- Explicit Label Binding -->
+  <label for="email-input" class="p2" style="font-weight: 600; color: var(--color-black);">
+    Email Address
+  </label>
+  
+  <!-- Native Primitive Control -->
+  <input 
+    id="email-input"
+    type="email" 
+    class="input-control" 
+    placeholder="user@valence.design"
+    aria-invalid="true"
+    aria-describedby="email-error"
+  />
+
+  <!-- Validation Feedback Message -->
+  <span id="email-error" class="p2" style="color: var(--color-error); font-size: 14px;">
+    Please enter a valid email address.
+  </span>
+</div>
+
+```
+
+## High Contrast & Dyslexia Mode Overrides
+
+In high-contrast mode, form controls rely on high-visibility solid borders (`--border-width-medium`) rather than subtle background fills.
+
+```css
+/* High Contrast Mode Overrides */
+:host([a11y-high-contrast]) .input-control {
+  background: #000000 !important;
+  color: #FFFFFF !important;
+  border: var(--border-width-medium) var(--border-style-solid) #FFFFFF !important;
+}
+
+:host([a11y-high-contrast]) .input-control:focus-visible {
+  outline: 4px solid #FFFFFF !important;
+  outline-offset: 2px;
+}
+
+/* Dyslexia Mode Overrides */
+:host([a11y-dyslexia]) .input-control {
+  font-family: "Comic Sans MS", cursive, sans-serif !important;
+  letter-spacing: 0.05em !important;
+}
+
+```
+
+## Best Practices
+
+* **Never Rely Solely on Color**: When communicating an invalid input state, pair `--color-error` borders with explanatory error text and an `aria-invalid="true"` attribute.
+* **Form Association**: Always link labels to input fields using `for="[id]"` or nested structural markup. Avoid orphan form controls.
+* **Helper Text Programmatic Association**: Always link helper or error messages to input fields using `aria-describedby="[message-id]"`.
+* **Keyboard Navigation & Traps**: Ensure form fields support standard `Tab` and `Shift+Tab` flows without trapping focus inside custom shadow DOM boundaries.

package/src/stories/sub-atomic/Formography/formography.css

@@ -0,0 +1,82 @@
+/* Light DOM Form Resets & Base Styles */
+.form-field {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-xs);
+  width: 100%;
+  font-family: var(--font-family);
+}
+
+.form-label {
+  font-size: 14px;
+  font-weight: 600;
+  color: var(--color-black);
+  letter-spacing: -0.01em;
+}
+
+.input-control {
+  box-sizing: border-box;
+  width: 100%;
+  height: var(--size-height-md);
+  padding: 0 var(--space-md);
+  font-family: var(--font-family);
+  font-size: 16px;
+  color: var(--color-black);
+  background: var(--custom-bg, var(--color-bg));
+  border: var(--border-width-thin) var(--border-style-solid) var(--color-gray-light);
+  border-radius: var(--custom-radius, var(--radius-md));
+  transition: border-color var(--anim-fast) var(--ease-fluid),
+              box-shadow var(--anim-fast) var(--ease-fluid);
+}
+
+/* Control Sizing Variants */
+.input-control-sm {
+  height: var(--size-height-sm);
+  padding: 0 var(--space-sm);
+  font-size: 14px;
+}
+
+.input-control-lg {
+  height: var(--size-height-lg);
+  padding: 0 var(--space-lg);
+  font-size: 18px;
+}
+
+/* Interaction & Validation States */
+.input-control:hover:not(:disabled) {
+  border-color: var(--color-gray-med);
+}
+
+.input-control:focus-visible {
+  outline: none;
+  border-color: var(--color-accent);
+  box-shadow: 0 0 0 3px rgba(43, 113, 240, 0.2);
+}
+
+.input-control[aria-invalid="true"] {
+  border-color: var(--color-error);
+}
+
+.input-control[aria-invalid="true"]:focus-visible {
+  box-shadow: 0 0 0 3px rgba(255, 59, 48, 0.2);
+}
+
+.input-control:disabled {
+  opacity: var(--opacity-disabled);
+  background: var(--color-card-bg);
+  cursor: not-allowed;
+}
+
+.form-helper-text {
+  font-size: 13px;
+  color: var(--color-gray-med);
+  line-height: 1.2;
+}
+
+.form-helper-text.error {
+  color: var(--color-error);
+}
+
+.form-helper-text.success {
+  color: var(--color-success);
+}