neotoma 0.3.0 → 0.3.2

package/docs/ui/design_constraints_template.yaml

@@ -1,228 +0,0 @@
-# Neotoma Design Constraints Template
-# Brand, Density, Hierarchy, A11y, and i18n Constraints
-
-# Brand
-brand:
-  name: "Neotoma"
-  tagline: "Your structured AI memory"
-  tone:
-    - "Minimal"
-    - "Direct"
-    - "Technical"
-    - "Trustworthy"
-  
-  # Do NOT use
-  forbidden_tone:
-    - "Playful"
-    - "Hype-driven"
-    - "Marketing-forward"
-
-# Visual Identity
-visual:
-  # Colors (TBD - defer to design system)
-  primary_color: "#0066CC"
-  secondary_color: "#6B7280"
-  success_color: "#10B981"
-  error_color: "#EF4444"
-  warning_color: "#F59E0B"
-  
-  # Typography
-  font_family_body: "Inter, system-ui, sans-serif"
-  font_family_mono: "'Roboto Mono', monospace"
-  
-  # Spacing scale (rem)
-  spacing_scale: [0.25, 0.5, 1, 1.5, 2, 3, 4, 6, 8]
-
-# Density
-density:
-  default: "comfortable"               # compact | comfortable | spacious
-  
-  compact:
-    row_height: "32px"
-    padding: "4px 8px"
-  
-  comfortable:
-    row_height: "40px"
-    padding: "8px 12px"
-  
-  spacious:
-    row_height: "48px"
-    padding: "12px 16px"
-
-# Visual Hierarchy
-hierarchy:
-  # Headings
-  h1:
-    font_size: "2rem"
-    font_weight: "700"
-    line_height: "1.2"
-  
-  h2:
-    font_size: "1.5rem"
-    font_weight: "600"
-    line_height: "1.3"
-  
-  h3:
-    font_size: "1.25rem"
-    font_weight: "600"
-    line_height: "1.4"
-  
-  # Body
-  body:
-    font_size: "1rem"
-    line_height: "1.5"
-  
-  small:
-    font_size: "0.875rem"
-    line_height: "1.4"
-
-# Accessibility (A11y)
-accessibility:
-  # Contrast ratios (WCAG AA minimum)
-  contrast_ratios:
-    normal_text: 4.5                   # 4.5:1
-    large_text: 3.0                    # 3.0:1
-    ui_components: 3.0                 # 3.0:1
-  
-  # Focus indicators
-  focus:
-    outline_width: "2px"
-    outline_style: "solid"
-    outline_color: "#0066CC"
-    outline_offset: "2px"
-  
-  # Keyboard navigation
-  keyboard:
-    tab_order: "logical"               # Follow visual order
-    skip_links: true                   # Provide skip to main content
-    shortcuts: true                    # Document keyboard shortcuts
-  
-  # Screen reader
-  screen_reader:
-    aria_labels: "required"            # All interactive elements
-    live_regions: "use_for_dynamic_content"
-    landmark_roles: "required"         # nav, main, aside, footer
-
-# Internationalization (i18n)
-i18n:
-  # Supported locales (MVP)
-  supported_locales:
-    - "en-US"
-    - "es-ES"
-    - "fr-FR"
-  
-  # Locale formatting
-  locale_formatting:
-    dates:
-      format: "locale_aware"           # Use Intl.DateTimeFormat
-      timezone: "user_timezone"
-    
-    numbers:
-      format: "locale_aware"           # Use Intl.NumberFormat
-      currency: "locale_currency"
-    
-    times:
-      format: "24h_or_12h_per_locale"
-  
-  # Content language preservation
-  content_language:
-    preserve_original: true            # Never auto-translate documents
-    detect_language: true              # Detect document language
-    display_language_tag: true         # Show language indicator
-
-# Component Guidelines
-components:
-  buttons:
-    primary:
-      background: "primary_color"
-      text: "white"
-      min_width: "80px"
-      height: "40px"
-    
-    secondary:
-      background: "transparent"
-      border: "1px solid"
-      text: "primary_color"
-  
-  inputs:
-    height: "40px"
-    border: "1px solid #D1D5DB"
-    border_radius: "4px"
-    focus_border: "primary_color"
-  
-  tables:
-    row_height: "40px"
-    header_background: "#F9FAFB"
-    border: "1px solid #E5E7EB"
-    hover_background: "#F3F4F6"
-
-# Responsive Design
-responsive:
-  breakpoints:
-    mobile: "640px"
-    tablet: "768px"
-    desktop: "1024px"
-    wide: "1280px"
-  
-  # Layout behavior
-  layout:
-    mobile: "single_column"
-    tablet: "two_column_optional"
-    desktop: "multi_column"
-
-# Animation and Motion
-motion:
-  # Respect prefers-reduced-motion
-  respect_reduced_motion: true
-  
-  # Transition durations
-  transitions:
-    fast: "150ms"
-    normal: "300ms"
-    slow: "500ms"
-  
-  # Easing
-  easing: "ease-in-out"
-
-# Error and Empty States
-states:
-  loading:
-    show_skeleton: true
-    min_display_time: "300ms"          # Avoid flash
-  
-  error:
-    show_icon: true
-    show_message: true
-    show_retry_button: true
-  
-  empty:
-    show_illustration: false           # Keep minimal
-    show_message: true
-    show_action_button: true
-
-# Notes
-notes: |
-  - All components MUST be keyboard accessible
-  - All interactive elements MUST have ARIA labels
-  - All text MUST be translatable (no hardcoded strings)
-  - All dates/numbers MUST use locale formatting
-  - UI is an inspection window, not an action interface
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-

package/docs/ui/design_system/accessibility.md

@@ -1,38 +0,0 @@
-# Accessibility
-
-## Contrast Requirements
-
-**WCAG AA Minimum:**
-
-- Normal text: 4.5:1 contrast ratio
-- Large text (18px+): 3:1 contrast ratio
-- UI components: 3:1 contrast ratio
-
-**WCAG AAA Target (Where Possible):**
-
-- Normal text: 7:1 contrast ratio
-- Large text: 4.5:1 contrast ratio
-
-## Focus Indicators
-
-```yaml
-focus:
-  outline: "2px solid primary_color"
-  outline_offset: "2px"
-  border_radius: "4px" # Match element border radius
-```
-
-**Rationale:** Clear, visible focus indicators are essential for keyboard navigation (strong preference in developer tools).
-
-## Keyboard Navigation
-
-- All interactive elements must be keyboard accessible
-- Logical tab order
-- Skip links for main content
-- Keyboard shortcuts documented
-
-## Related Documents
-
-- [`../design_system.md`](../design_system.md) - Design system index
-- [`../subsystems/accessibility.md`](../subsystems/accessibility.md) - Complete accessibility requirements
-- [`dark_mode.md`](./dark_mode.md) - Dark mode contrast considerations

package/docs/ui/design_system/authentication_components.md

@@ -1,38 +0,0 @@
-# Authentication Components
-
-## Signup/Signin Forms (FU-700)
-
-**Form Layout:**
-
-- Centered card (max-width: 400px)
-- Title: "Sign Up" or "Sign In"
-- Email input
-- Password input
-- Submit button (primary, full-width)
-- OAuth buttons (Google, GitHub) — outline variant, full-width
-- Link to alternate form ("Already have an account?" / "Don't have an account?")
-
-**OAuth Buttons:**
-
-- Icon + text ("Continue with Google")
-- Outline variant
-- Full-width
-- Spacing: 8px between buttons
-
-**Password Reset:**
-
-- Email input only
-- Submit button
-- Back to signin link
-
-**Error States:**
-
-- Inline error below form
-- Specific error message
-- No auto-dismiss
-
-## Related Documents
-
-- [`../design_system.md`](../design_system.md) - Design system index
-- [`component_styles.md`](./component_styles.md) - Input and button styles
-- [`error_states.md`](./error_states.md) - Error display patterns

package/docs/ui/design_system/billing_components.md

@@ -1,36 +0,0 @@
-# Billing Components
-
-## Subscription Management (FU-702)
-
-**Plan Selection:**
-
-- Card-based plan options
-- Plan name, price, features (bullet list)
-- "Current Plan" badge for active plan
-- "Select Plan" button (primary for upgrade, outline for current)
-
-**Subscription Details:**
-
-- Current plan display
-- Billing cycle (monthly/annual)
-- Next billing date
-- Cancel subscription link (destructive variant)
-
-**Invoice History:**
-
-- Table layout
-- Columns: Date, Amount, Status, Download
-- Status badges: Paid (green), Pending (amber), Failed (red)
-- Download button (ghost variant)
-
-**Usage Dashboard:**
-
-- Stats widgets (sources, entities, observations, API calls, storage)
-- Usage charts (minimal, data-first)
-- Billing period selector
-
-## Related Documents
-
-- [`../design_system.md`](../design_system.md) - Design system index
-- [`component_styles.md`](./component_styles.md) - Card, table, and badge styles
-- [`data_visualization.md`](./data_visualization.md) - Dashboard widgets

package/docs/ui/design_system/brand_alignment.md

@@ -1,35 +0,0 @@
-# Brand Alignment
-
-## Design Principles Applied
-
-**Minimal:**
-
-- Clean layouts
-- Minimal decoration
-- Content-first
-- No unnecessary elements
-
-**Technical:**
-
-- Monospace for data
-- Structured layouts
-- Clear hierarchy
-- Functional aesthetics
-
-**Trustworthy:**
-
-- Professional color palette
-- Consistent patterns
-- Clear feedback
-- Reliable interactions
-
-**Deterministic:**
-
-- Predictable layouts
-- Consistent spacing
-- Standard components
-
-## Related Documents
-
-- [`../design_system.md`](../design_system.md) - Design system index
-- [`../NEOTOMA_MANIFEST.md`](../../NEOTOMA_MANIFEST.md) - Brand principles

package/docs/ui/design_system/color_palette.md

@@ -1,95 +0,0 @@
-# Color Palette
-
-## Base Colors
-
-**Light Mode:**
-
-```yaml
-background:
-  primary: "#FFFFFF" # Pure white for main canvas
-  secondary: "#F9FAFB" # Subtle gray for cards/sections
-  tertiary: "#F3F4F6" # Hover states, subtle backgrounds
-foreground:
-  primary: "#111827" # Near-black for primary text (high contrast)
-  secondary: "#6B7280" # Medium gray for secondary text
-  tertiary: "#9CA3AF" # Light gray for tertiary text, placeholders
-  muted: "#D1D5DB" # Borders, dividers
-```
-
-**Dark Mode:**
-
-```yaml
-background:
-  primary: "#0F172A" # Deep slate (similar to Cursor/GitHub dark) for main canvas
-  secondary: "#1E293B" # Slightly lighter for cards/sections
-  tertiary: "#334155" # Hover states, subtle backgrounds
-foreground:
-  primary: "#F1F5F9" # Near-white for primary text
-  secondary: "#94A3B8" # Medium gray for secondary text
-  tertiary: "#64748B" # Light gray for tertiary text
-  muted: "#475569" # Borders, dividers
-```
-
-## Semantic Colors
-
-**Primary (Trust/Action):**
-
-```yaml
-light:
-  primary: "#0066CC" # Professional blue (matches existing)
-  primary_hover: "#0052A3"
-  primary_foreground: "#FFFFFF"
-dark:
-  primary: "#3B82F6" # Brighter blue for dark mode visibility
-  primary_hover: "#2563EB"
-  primary_foreground: "#FFFFFF"
-```
-
-**Status Colors:**
-
-```yaml
-success: "#10B981" # Green (matches existing)
-error: "#EF4444" # Red (matches existing)
-warning: "#F59E0B" # Amber (matches existing)
-info: "#3B82F6" # Blue (matches primary)
-```
-
-**Status Colors (Dark Mode):**
-
-```yaml
-success: "#22C55E" # Brighter green for dark mode
-error: "#F87171" # Softer red for dark mode
-warning: "#FBBF24" # Brighter amber
-info: "#60A5FA" # Lighter blue
-```
-
-## Data Visualization Colors
-
-**Entity Type Colors (Subtle, Distinguishable):**
-
-```yaml
-person: "#6366F1" # Indigo
-company: "#8B5CF6" # Purple
-location: "#EC4899" # Pink
-event: "#F59E0B" # Amber
-document: "#10B981" # Green
-```
-
-**Use sparingly:** Only for entity badges, timeline markers, graph nodes. Never for primary UI elements.
-
-## Border and Divider Colors
-
-```yaml
-light:
-  border: "#E5E7EB" # Subtle gray borders
-  divider: "#D1D5DB" # Slightly darker for dividers
-dark:
-  border: "#334155" # Subtle slate borders
-  divider: "#475569" # Slightly lighter for dividers
-```
-
-## Related Documents
-
-- [`../design_system.md`](../design_system.md) - Design system index
-- [`dark_mode.md`](./dark_mode.md) - Dark mode color adjustments
-- [`data_visualization.md`](./data_visualization.md) - Data visualization color usage

package/docs/ui/design_system/component_styles.md

@@ -1,241 +0,0 @@
-# Component Styles
-
-## Buttons
-
-**Primary:**
-
-```yaml
-primary:
-  background: "primary_color"
-  color: "white"
-  padding: "8px 16px"
-  height: "40px"
-  border_radius: "6px"
-  font_weight: "500"
-  font_size: "0.9375rem"
-  transition: "all 150ms ease-in-out"
-
-  hover:
-    background: "primary_hover"
-    transform: "translateY(-1px)" # Subtle lift
-    box_shadow: "0 2px 4px rgba(0,0,0,0.1)"
-
-  active:
-    transform: "translateY(0)"
-    box_shadow: "none"
-
-  disabled:
-    opacity: "0.5"
-    cursor: "not-allowed"
-```
-
-**Secondary:**
-
-```yaml
-secondary:
-  background: "transparent"
-  color: "primary_color"
-  border: "1px solid currentColor"
-  padding: "8px 16px"
-  height: "40px"
-  border_radius: "6px"
-  font_weight: "500"
-
-  hover:
-    background: "primary_color / 0.1" # 10% opacity
-```
-
-**Ghost (Tertiary):**
-
-```yaml
-ghost:
-  background: "transparent"
-  color: "foreground_secondary"
-  padding: "6px 12px"
-  height: "auto"
-
-  hover:
-    background: "background_tertiary"
-    color: "foreground_primary"
-```
-
-## Inputs
-
-```yaml
-input:
-  height: "40px"
-  padding: "8px 12px"
-  border: "1px solid border_color"
-  border_radius: "6px"
-  background: "background_primary"
-  color: "foreground_primary"
-  font_size: "0.9375rem"
-  transition: "border-color 150ms ease-in-out"
-
-  focus:
-    border_color: "primary_color"
-    outline: "2px solid primary_color / 0.2"
-    outline_offset: "2px"
-
-  disabled:
-    background: "background_secondary"
-    color: "foreground_tertiary"
-    cursor: "not-allowed"
-
-  error:
-    border_color: "error_color"
-```
-
-## Tables
-
-```yaml
-table:
-  width: "100%"
-  border_collapse: "separate"
-  border_spacing: "0"
-
-  header:
-    background: "background_secondary"
-    font_weight: "600"
-    font_size: "0.8125rem"
-    text_transform: "uppercase"
-    letter_spacing: "0.05em"
-    color: "foreground_secondary"
-    padding: "12px 16px"
-    border_bottom: "2px solid border_color"
-
-  row:
-    height: "40px"
-    border_bottom: "1px solid border_color"
-
-    hover:
-      background: "background_tertiary"
-
-  cell:
-    padding: "12px 16px"
-    font_size: "0.9375rem"
-```
-
-### Table Functionality (Required for Tier 1 ICPs)
-
-**Sorting:**
-
-- Clickable column headers with sort indicators (ArrowUpDown, ArrowUp, ArrowDown icons)
-- Multi-column sorting support (optional, for advanced use cases)
-- Sort state persistence (optional, via localStorage)
-- Visual indicators: Icon shows current sort direction (asc/desc) or unsorted state
-- Sort button styling: Ghost variant, small size, no border on hover
-
-**Column Management:**
-
-- Column visibility toggle (show/hide columns via dropdown menu)
-- Column reordering (drag-and-drop column headers)
-- Column width resizing (drag column borders to resize)
-- Column state persistence (visibility, order, widths saved to localStorage)
-- Column menu: Dropdown with visibility checkboxes, reset options
-
-**Search and Filtering:**
-
-- Global search input (full-text search across all visible columns)
-- Type filter dropdown (filter by entity type)
-- Search placeholder: "Search sources..." or "Search entities..." (context-dependent)
-- Filter state: Clear visual indication of active filters
-- Clear filters button (when filters active)
-
-**Pagination:**
-
-- Load more button (infinite scroll pattern preferred for high-density)
-- Display count: "Showing X of Y sources" or "Showing X of Y entities" (context-dependent)
-- Pagination controls (optional, for very large datasets)
-
-**Row Interactions:**
-
-- Row selection (checkbox column for bulk actions)
-- Row click → navigate to detail view
-- Row hover: Subtle background change (background_tertiary)
-- Row actions: Dropdown menu per row (view, delete, etc.)
-- Keyboard navigation: Arrow keys, Enter to select, Space to toggle selection
-
-**Table Controls:**
-
-- Column visibility menu (dropdown with checkboxes)
-- Reset columns button (restore default visibility/order/widths)
-- Export options (optional, CSV/JSON export)
-
-**Accessibility:**
-
-- ARIA labels for sort buttons
-- Keyboard navigation support
-- Screen reader announcements for sort changes
-- Focus indicators on interactive elements
-
-**Rationale:** Tier 1 ICPs (especially High-Context Knowledge Workers) expect professional table functionality matching legal platforms (Westlaw, LexisNexis) and research tools (Zotero, Mendeley). These tools provide high-density, sortable, filterable table interfaces for managing large document collections.
-
-**Tier 1 ICP Expectations:**
-
-- **High-Context Knowledge Workers:** Work with hundreds of documents across multiple projects. Require sortable, filterable tables to manage information overload. Expect column management (visibility, reordering) and advanced search capabilities.
-- **AI-Native Individual Operators:** Expect developer-friendly interfaces with keyboard navigation, efficient data inspection, and customizable layouts.
-- **AI-Native Founders:** Expect modern, functional interfaces with fast interactions and professional appearance matching tools like Linear and GitHub.
-
-**Implementation Status:**
-
-- ✅ Sorting (multi-column, ascending/descending with visual indicators)
-- ✅ Column visibility (show/hide via dropdown menu)
-- ✅ Column reordering (drag-and-drop)
-- ✅ Column width resizing
-- ✅ Global search (full-text across visible columns)
-- ✅ Type filtering (dropdown filter)
-- ✅ Row selection (checkbox column)
-- ✅ Row actions (dropdown menu per row)
-- ✅ State persistence (localStorage for column state)
-- ✅ Keyboard navigation (arrow keys, Enter, Space)
-
-## Cards
-
-```yaml
-card:
-  background: "background_primary"
-  border: "1px solid border_color"
-  border_radius: "8px"
-  padding: "1rem"
-  box_shadow: "0 1px 3px rgba(0,0,0,0.1)" # Subtle shadow
-
-  hover:
-    box_shadow: "0 4px 6px rgba(0,0,0,0.1)" # Slightly more on hover
-    border_color: "border_color (slightly darker)"
-```
-
-## Badges/Tags
-
-```yaml
-badge:
-  display: "inline-flex"
-  align_items: "center"
-  padding: "4px 8px"
-  border_radius: "4px"
-  font_size: "0.8125rem"
-  font_weight: "500"
-
-  variants:
-    default:
-      background: "background_tertiary"
-      color: "foreground_secondary"
-
-    primary:
-      background: "primary_color / 0.1"
-      color: "primary_color"
-
-    success:
-      background: "success_color / 0.1"
-      color: "success_color"
-
-    error:
-      background: "error_color / 0.1"
-      color: "error_color"
-```
-
-## Related Documents
-
-- [`../design_system.md`](../design_system.md) - Design system index
-- [`../shadcn_components.md`](../shadcn_components.md) - shadcn/ui component inventory
-- [`visual_hierarchy.md`](./visual_hierarchy.md) - Component usage in content structure