Initial commit: Clean DSS implementation

Migrated from design-system-swarm with fresh git history. Old project history preserved in /home/overbits/apps/design-system-swarm Core components: - MCP Server (Python FastAPI with mcp 1.23.1) - Claude Plugin (agents, commands, skills, strategies, hooks, core) - DSS Backend (dss-mvp1 - token translation, Figma sync) - Admin UI (Node.js/React) - Server (Node.js/Express) - Storybook integration (dss-mvp1/.storybook) Self-contained configuration: - All paths relative or use DSS_BASE_PATH=/home/overbits/dss - PYTHONPATH configured for dss-mvp1 and dss-claude-plugin - .env file with all configuration - Claude plugin uses ${CLAUDE_PLUGIN_ROOT} for portability Migration completed: $(date) 🤖 Clean migration with full functionality preserved
2025-12-09 18:45:48 -03:00
commit 276ed71f31
884 changed files with 373737 additions and 0 deletions
--- a/admin-ui/DESIGN-SYSTEM.md
+++ b/admin-ui/DESIGN-SYSTEM.md
@@ -0,0 +1,221 @@
+# Design System Implementation
+
+## Overview
+
+The DSS Admin UI is built using a layered CSS architecture that consumes the Design System as the source of truth. This document explains how the design system is implemented and how other projects can replicate this pattern.
+
+## Architecture
+
+The design system is organized into **5 distinct layers**, each with a specific responsibility:
+
+### Layer 0: Reset
+**Location**: `/src/styles/0-reset/`
+
+Establishes a consistent baseline across all browsers by normalizing default styles and setting sensible defaults for all HTML elements.
+
+- Removes margins and padding
+- Sets box-sizing to border-box
+- Normalizes form elements
+- Improves font smoothing
+
+### Layer 1: Design Tokens
+**Location**: `/src/styles/1-tokens/`
+
+Defines all base design decisions as CSS custom properties (variables). These tokens are the single source of truth and are derived from `design-tokens.json`.
+
+**Token Categories**:
+- **Colors**: Primary, secondary, accent, semantic (success, warning, error), and neutral colors
+- **Spacing**: Scale from 0-8 using a 4px base unit
+- **Typography**: Font families, sizes, weights, and line heights
+- **Radius**: Border radius values for different element sizes
+- **Shadows**: Shadow system for depth and elevation
+- **Durations**: Animation timing values
+- **Easing**: Animation easing functions
+
+**Example Token Usage**:
+```css
+button {
+  background: var(--primary);
+  color: var(--primary-foreground);
+  padding: var(--space-3) var(--space-4);
+  border-radius: var(--radius);
+  transition: background var(--duration-fast) var(--ease-default);
+}
+```
+
+### Layer 2: Theme
+**Location**: `/src/styles/2-theme/`
+
+Applies semantic meaning to tokens by mapping them to functional roles. This layer enables theme switching (light/dark mode) without changing component code.
+
+**Files**:
+- `_palette.css`: Maps tokens to semantic roles (primary, secondary, destructive, success, etc.)
+- `_theme-dark.css`: Dark mode color overrides
+
+### Layer 3: Layout
+**Location**: `/src/styles/3-layout/`
+
+Defines the application structure and major layout components:
+
+- **_grid.css**: Main app grid (sidebar + content)
+- **_sidebar.css**: Sidebar structure
+- **_header.css**: Page header and action bars
+- **_main.css**: Main content area and sections
+
+### Layer 4: Components
+**Location**: `/src/styles/4-components/`
+
+Reusable component styles built from tokens and layout primitives:
+
+- **_navigation.css**: Navigation items and sections
+- **_buttons.css**: Button variants (primary, secondary, ghost, destructive)
+- **_inputs.css**: Form controls and inputs
+- **_panels.css**: Cards, panels, help elements
+- **_utilities.css**: Utility classes for common patterns
+
+### Layer 5: Admin
+**Location**: `/src/styles/5-admin/`
+
+Admin-specific customizations and overrides:
+
+- **_sidebar-custom.css**: Admin UI sidebar styling
+- **_responsive.css**: Media queries for responsive behavior
+- **_overrides.css**: Emergency overrides (should be minimal)
+
+## Import Order
+
+The CSS files are imported in strict order via `/src/styles/index.css`:
+
+1. Reset (establishes baseline)
+2. Tokens (defines all design values)
+3. Theme (applies semantic mapping)
+4. Layout (defines structure)
+5. Components (builds on top)
+6. Admin (project-specific)
+
+This order ensures proper CSS cascade and prevents specificity conflicts.
+
+## Design Tokens JSON
+
+The source of truth is `design-tokens.json` in the root directory:
+
+```json
+{
+  "colors": {
+    "primary": {
+      "value": "oklch(0.65 0.18 250)",
+      "description": "Primary brand color",
+      "category": "semantic",
+      "usage": "Links, buttons, active states"
+    }
+  },
+  "spacing": { ... },
+  "typography": { ... }
+}
+```
+
+## Using the Design System
+
+### Replicating This Pattern
+
+To use this design system in another project:
+
+1. **Copy the token definitions**:
+   ```
+   design-tokens.json
+   src/styles/
+   ```
+
+2. **Link the stylesheet**:
+   ```html
+   <link rel="stylesheet" href="/src/styles/index.css">
+   ```
+
+3. **Use tokens in custom CSS**:
+   ```css
+   .custom-element {
+     background: var(--primary);
+     padding: var(--space-4);
+   }
+   ```
+
+4. **Customize tokens as needed**:
+   - Edit `design-tokens.json`
+   - Regenerate CSS variable files from the tokens
+   - Your entire project updates automatically
+
+### Theme Switching
+
+Implement light/dark mode:
+
+```js
+// Switch to dark mode
+document.documentElement.style.setProperty('--color-foreground', 'oklch(0.92 0.02 280)');
+// or use media query
+@media (prefers-color-scheme: dark) { ... }
+```
+
+### Extending Components
+
+Create project-specific components:
+
+```css
+/* layers/5-admin/_custom-components.css */
+.custom-card {
+  padding: var(--space-4);
+  background: var(--card);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+}
+```
+
+## CSS Variable Reference
+
+### Colors
+- `--color-primary`, `--primary`
+- `--color-secondary`, `--secondary`
+- `--color-accent`, `--accent`
+- `--color-destructive`, `--destructive`
+- `--color-success`, `--success`
+- `--color-warning`, `--warning`
+- `--color-info`, `--info`
+- `--color-foreground`, `--muted-foreground`
+- `--color-background`, `--surface`, `--card`, `--input`, `--muted`
+- `--color-border`, `--ring`
+
+### Spacing
+- `--space-0` through `--space-8` (4px base unit)
+
+### Typography
+- `--font-sans`, `--font-mono`
+- `--text-xs` through `--text-2xl`
+- `--font-400` through `--font-700`
+- `--line-height-tight` through `--line-height-loose`
+
+### Other
+- `--radius-none`, `--radius-sm`, `--radius`, `--radius-md`, `--radius-lg`, `--radius-full`
+- `--shadow-sm`, `--shadow`, `--shadow-md`, `--shadow-lg`
+- `--duration-fast`, `--duration-normal`, `--duration-slow`
+- `--ease-default`, `--ease-in`, `--ease-out`, `--ease-in-out`
+
+## Best Practices
+
+1. **Always use tokens**: Never hardcode colors, spacing, or sizing
+2. **Respect the cascade**: Each layer builds on previous ones
+3. **Keep overrides minimal**: Layer 5 should be small and well-documented
+4. **Semantic naming**: Use semantic tokens (--primary) over base tokens (--color-primary)
+5. **Component consistency**: Use the same tokens across all components
+6. **Responsive first**: Layer 5 handles responsive adjustments
+7. **Document changes**: Update TOKEN-REFERENCE.md when adding new tokens
+
+## Maintenance
+
+When updating the design system:
+
+1. Update `design-tokens.json`
+2. Regenerate token CSS files (Layers 1-2)
+3. Test all components
+4. Update documentation
+5. Deploy changes
+
+All projects using the design system will automatically inherit the updates.