@W-21859986 Ux design system (#11)

* Clean up CSS: consolidate variables and remove Lume namespace

- Remove all lume- prefixed variables
- Consolidate into single unified namespace (--color-*, --space-*, --font-*, etc.)
- Remove unused variables (lume-color-info, lume-color-success-light, method colors, etc.)
- Eliminate double-layering of variables (direct values instead of var() chains)
- Remove commented-out dark mode section
- Keep legacy semantic aliases for backward compatibility
- All 316 CSS classes preserved and functional

This makes the CSS more maintainable with a clean, unified variable system.

* Add smooth expand/collapse transitions to Try It Out panel

- Add 0.3s cubic-bezier transitions to operation-try-panel and wrapper
- Add fadeInGrid animation for two-column grid layout
- Add slideInFromLeft animation for form container
- Add slideInFromRight animation for response panel
- Smooth transitions enhance UX when toggling between collapsed/expanded states

* Fix Try It Out panel animation direction - expand from right to left

- Remove slideInFromLeft animation (not needed)
- Both form and response panels now slide in from right
- Add staggered timing: form at 0.1s, response at 0.2s for cascade effect
- Use 'backwards' to prevent initial flash before animation starts
- Matches natural expansion from right sidebar position

* Simplify Try It Out panel transitions - remove flickering animations

- Remove all keyframe animations (fadeInGrid, slideInFromRight)
- Use only smooth width/height/opacity transitions
- Set transform-origin to 'right' to anchor expansion from right side
- Transition duration: 0.4s for width/height, 0.3s for opacity
- Eliminates flickering and janky behavior from previous animation approach

* Add proper right-to-left expand animation for Try It Out panel

- Add expandFromRight keyframe animation with scaleX from 0.95 to 1
- Set transform-origin to 'right center' to anchor scaling from right side
- Animation creates visual effect of content expanding from right
- 0.4s duration with cubic-bezier easing for smooth motion

* Remove all Try It Out panel animations - keep it simple

- Remove all transitions and animations from operation-try-panel
- Remove expandFromRight keyframe animation
- Remove transitions from operation-content-wrapper
- Clean, instant expand/collapse with no visual effects
- Simpler is better - no flickering, no weird scaling effects

* Add smooth fade-in transition to Try It Out panel expansion

- Add simple fadeIn animation (0.3s) when grid expands
- Opacity transition from 0 to 1 - clean and smooth
- No directional movement, just fade - avoids all flickering issues
- Add overflow:hidden to prevent scroll during transition

* Remove all Try It Out animations - instant expand/collapse only

- Remove fadeIn animation
- Remove overflow hidden
- No transitions, no animations
- Clean instant state changes

* Add width-based expand/collapse transition anchored to right edge

- Panel expands from right to left: right border stays fixed, left border moves
- Use margin-left: auto to anchor panel to right side when collapsed
- Smooth 0.4s transition on width with cubic-bezier easing
- Content fades in after 0.2s delay to avoid flash during layout change
- On collapse: left border moves back right (reverse of expand)

* Invert expand direction - left border fixed, right border moves left

- Remove margin-left: auto so panel anchors to left side
- On expand: left border stays fixed, right border moves left as width increases
- On collapse: right border moves back right as width decreases
- Smooth 0.4s transition with content fade-in after 0.2s delay

* Revert all Try It Out panel transitions - back to instant

- Remove all transitions from operation-try-panel
- Remove fadeInContent animation
- Back to clean, instant expand/collapse with no effects
- Simpler is better

* Replace hardcoded font and border-radius values with CSS variables

- Replace all font-size px/rem values with --font-size-* variables
- Replace all font-weight numeric values (300, 400, 500, 600, 700) with --font-weight-* variables
- Replace border-radius values (4px, 8px, 12px, 16px, etc.) with --radius-* variables
- Improves consistency and maintainability
- Makes theme changes easier by centralizing all values in CSS variables

* Add color variables and replace common hardcoded colors

- Add --color-white variable for #FFFFFF
- Add Tailwind-compatible gray scale (--color-gray-50 through --color-gray-900)
- Add additional colors: --color-navy, --color-indigo, --color-slate
- Replace hardcoded white colors (#fff, #ffffff, white) with var(--color-white)
- Replace all gray hex values with corresponding --color-gray-* variables
- Improves consistency and makes color theming easier

* Fix circular variable references in color definitions

Replace self-referencing variables with actual hex values for gray scale and additional colors.

* Remove 311 unused CSS rules from styles.css

Analyzed all HTML templates and JavaScript files to identify actually used CSS classes.
Removed 195 unused class definitions including:
- Debugger controls (btn-debugger-*, debugger-*)
- Old catalog card styles
- Unused enum display styles
- Old operation and skill styles
- Infrastructure classes (ace_editor, ms-com-*, etc.)

Reduced file from 8,279 to 6,628 lines (20% reduction).

* Restore try-expanded flex-direction rule

The .operation-content-wrapper.try-expanded rule was incorrectly removed,
causing the content to move horizontally instead of vertically when expanding.

* Restore response-block and responses-table CSS rules

These classes are actively used in templates but were incorrectly
identified as unused and removed.

* Revert mass CSS deletion - was too aggressive

The automated removal deleted many classes that are actually used.
Restoring the file to analyze more carefully.

* Fix undefined CSS variables and remove unused variable

- Replace undefined --color-text-secondary with --color-text-muted
- Replace undefined --text-tertiary with --color-text-muted
- Remove unused --space-xx-large variable

All 94 CSS variables are now properly defined and used.

* Replace hardcoded colors with CSS variables

Added comprehensive color scale variables:
- Blue, Sky, Red, Green, Yellow, Purple scales
- Shadow and overlay rgba patterns
- Replaced 170+ hardcoded color values with variables
- 38 specialized colors remain (terminal, specific UI elements)

All variable definitions in :root remain intact with actual hex/rgba values.

* Remove 27 unused CSS variables

Removed unused color scale variables:
- Blue: 200, 300, 400
- Sky: 50, 100, 300, 400, 800, 900
- Red: 300, 900
- Green: 500, 600, 800, 900
- Yellow: 400, 500, 600, 900
- Purple: 200, 300, 400, 500, 600, 900
- Legacy: bg-hover, bg-tertiary

All 132 CSS variables are now actively used.

* Add semantic HTTP method color variables

Created semantic color variables for HTTP method badges:
- --method-get-bg/text/bg-hover (green)
- --method-post-bg/text/bg-hover (blue)
- --method-put-bg/text/bg-hover (yellow)
- --method-patch-bg/text/bg-hover (purple)
- --method-delete-bg/text/bg-hover (red)
- --method-other-bg/text/bg-hover (gray for HEAD/OPTIONS)

This makes it easier to customize method badge colors and understand
their purpose without knowing color-blue-50 means POST.

* Add semantic color system for text, backgrounds, and borders

Created semantic color variables organized by purpose:

Text colors:
- --color-text-primary (headings, primary content)
- --color-text-secondary (muted text, descriptions)
- --color-text-tertiary, quaternary (helper text, placeholders)
- --color-text-inverse (text on dark backgrounds)
- --color-text-link, link-hover (interactive links)

Background colors:
- --color-bg-primary (page background)
- --color-bg-secondary, bg-surface (card/panel backgrounds)
- --color-bg-overlay (modal overlays)

Border colors:
- --color-border-primary (default borders)
- --color-border-secondary (subtle borders)
- --color-border-focus (focused inputs)

Legacy aliases maintained for backward compatibility.
Updated typography and links to use semantic names.

* Replace all legacy color aliases with semantic names

Replaced throughout the entire CSS file:
- var(--color-bg) → var(--color-bg-primary)
- var(--color-surface) → var(--color-bg-surface)
- var(--color-border) → var(--color-border-primary)
- var(--color-text) → var(--color-text-primary)
- var(--color-text-muted) → var(--color-text-secondary)
- var(--bg-primary) → var(--color-bg-primary)
- var(--bg-secondary) → var(--color-bg-secondary)
- var(--text-primary) → var(--color-text-primary)
- var(--text-secondary) → var(--color-text-secondary)
- var(--text-muted) → var(--color-text-secondary)
- var(--border-color) → var(--color-border-primary)

Removed all legacy alias definitions from :root.
All color variables now use consistent semantic naming.

* Remove unused stats.html template and all related CSS

Removed:
- scripts/portal_generator/templates/homepage/stats.html (not included in homepage)
- .stats, .stat, .stat-dot, .stat-value CSS rules
- .stats-grid, .stat-item CSS rules
- .stats-summary, .stat-number, .stat-label responsive CSS
- .catalog-stats, .stat-separator CSS rules

These were legacy/unused components not referenced anywhere in the portal generation.

* Remove unused workflow_step_try.html template and all related CSS

Removed:
- scripts/portal_generator/templates/skills/workflow_step_try.html (not included anywhere)
- .workflow-try-container CSS
- All .wf-* CSS classes (params, body, tabs, status badges, outputs, etc.)
- Responsive workflow CSS
- .wf-url-bar-header, .wf-header-actions

This was legacy code for an old workflow implementation not used in current portal.

* Add comprehensive Design System documentation

Created docs/design-system.md covering:
- Semantic color token system (text, background, border, status, HTTP methods)
- Spacing system with token reference
- Typography system (fonts, sizes, weights)
- Border radius tokens
- Shadows and elevation system
- Component patterns (buttons, cards, inputs, method badges)
- 4 core design principles:
  1. White background = interactive
  2. No boxes inside boxes
  3. Hover = selected style
  4. Buttons use --radius-large minimum
- Quick reference cheat sheet

This documents the CSS variable system we've been building and
establishes design guidelines for maintaining consistency.

* Add Portal Generator architecture guidelines

Created comprehensive architecture documentation covering:

Core Principles:
1. Avoid duplicated HTML - reuse via Jinja2 macros and includes
2. Python-first processing - avoid JavaScript logic for data transformation
3. Generate tests for any new feature - no exceptions

Detailed Sections:
- Template architecture (hierarchy, macros vs includes)
- Python-first processing pipeline and guidelines
- Testing requirements (unit, OAS parser, smoke tests)
- Project structure and separation of concerns
- Best practices for templates, Python code, and tests
- Common patterns and code examples
- Pre-PR checklist

This establishes engineering standards for maintaining and extending
the portal generator codebase.

* Add Portal Generator and Design System sections to CLAUDE.md

Added comprehensive summaries with pointers to detailed documentation:

Portal Generator Architecture:
- Core principles (no duplicate HTML, Python-first, test everything)
- What goes where (Python vs JavaScript vs Templates)
- Testing requirements and commands
- Link to full guide: docs/portal-generator-architecture.md

Design System:
- Semantic token system overview
- Quick reference with ✅ correct vs ❌ wrong examples
- 4 core design principles
- Token categories reference
- Link to full guide: docs/design-system.md

Updated Key Files section to include new documentation files.

This ensures agents working on the project have immediate access to
architectural guidelines and design system rules with links to
comprehensive documentation when needed.

* Document ACE Editor usage for editable code blocks

Added Code Editor Pattern section to design system:
- When to use ACE Editor (request body editing, interactive JSON/YAML)
- Implementation example with initialization code
- Styling guidelines using design tokens
- Note that read-only code blocks should use standard <pre><code>

This clarifies the distinction between editable code (ACE Editor) and
static code examples (standard HTML elements).

* Improve homepage layout and add icon guidelines

- Move results count next to search bar for better grouping
- Constrain search bar width to 850px (fixed) so results count stays adjacent
- Add icon guidelines to design system (prefer SVG, store in assets/icons/)
- Maintain alignment between controls wrapper and catalog grid

* Refactor CSS: Extract homepage-specific styles into separate file

Step 1 of incremental CSS refactoring to manage growing styles.css file.

Changes:
- Created extract_homepage_css.py script to identify and extract homepage-only CSS
- Generated homepage.css (278 lines) with 39 homepage-specific rules:
  * Hero section (.hero, .hero-content, .hero-title, .hero-subtitle, .hero-tabs)
  * Catalog controls (.catalog-controls-wrapper, .catalog-results-header, .catalog-grid)
  * Sort modal (.sort-btn, .sort-modal, .sort-modal-*)
  * Search UI (.search-icon-catalog, .results-count)
- Added extra_styles block to base.html for page-specific CSS includes
- Updated homepage.html to include homepage.css
- Restored .stats-grid, .stat-item CSS (was incorrectly removed, still used in detail pages)

Architecture:
- styles.css remains the foundation (loaded on all pages, 7,534 lines)
- homepage.css contains homepage-only styles (loaded only on index.html, 278 lines)
- Future: Extract detail-page.css and skill-page.css following same pattern

* Remove un used py files

Author: machaval

CLAUDE.md

@@ -158,16 +158,117 @@ When adding x-origin:
 - `values` is required (JSONPath), `labels` is optional
 - Validate: `python3 scripts/build/validate_xorigin.py`
 
+## Portal Generator Architecture
+
+The static portal generator (`scripts/portal_generator/`) follows strict architectural principles:
+
+### Core Principles
+
+1. **No Duplicate HTML** — Extract common patterns into Jinja2 macros and includes. If HTML appears in 2+ places, create a reusable component.
+
+2. **Python-First Processing** — All data transformation, filtering, sorting, and business logic happens in Python. JavaScript only handles user interactions and dynamic UI updates.
+
+3. **Test Everything** — Every new feature requires tests. No exceptions.
+
+### What Goes Where
+
+**Python handles:**
+- Data transformation and normalization
+- Filtering, sorting, aggregations
+- Schema validation and parsing
+- Complex string formatting
+- Business logic
+
+**JavaScript handles:**
+- DOM manipulation and event handling
+- Animations and transitions
+- Form interactions and modal toggling
+- Copy-to-clipboard, syntax highlighting
+- Client-side filtering (after Python preprocessing)
+
+**Templates use:**
+- Jinja2 macros for reusable components with parameters
+- Includes for static sections and layout
+- Filters for formatting only, not complex logic
+
+### Testing Requirements
+
+```bash
+# Run all tests before committing portal changes
+make test-portal
+
+# Tests must cover:
+# - Unit tests for pure functions (utils, parsers, builders)
+# - OAS parser tests ($ref resolution, allOf merging, schema extraction)
+# - Smoke tests (end-to-end generation, HTML structure validation)
+```
+
+**Read more:** `docs/portal-generator-architecture.md` — Complete guide with examples, patterns, and best practices.
+
+## Design System
+
+The portal uses a semantic token system with CSS custom properties. **Always use tokens, never hard-coded colors or values.**
+
+### Quick Reference
+
+```css
+/* ✅ CORRECT - Semantic tokens */
+.card {
+  color: var(--color-text-primary);
+  background: var(--color-bg-surface);
+  border: 1px solid var(--color-border-primary);
+  border-radius: var(--radius-large);
+  padding: var(--space-md);
+  box-shadow: var(--shadow-md);
+}
+
+/* ❌ WRONG - Hard-coded values */
+.card {
+  color: #3E3E3C;
+  background: #FFFFFF;
+  border: 1px solid #DDDBDA;
+  border-radius: 12px;
+  padding: 16px;
+  box-shadow: 0 2px 8px rgba(0,0,0,0.08);
+}
+```
+
+### Core Design Principles
+
+1. **White Background = Interactive** — Surface backgrounds (`--color-bg-surface`) signal clickable elements. Gray backgrounds (`--color-bg-primary`) are non-interactive containers.
+
+2. **No Boxes Inside Boxes** — Avoid nested bordered/shadowed containers. Use background color changes and spacing instead.
+
+3. **Hover = Selected Style** — For selectable elements, hover state must match the selected state for predictable interactions.
+
+4. **Buttons Use --radius-large Minimum** — All buttons require at least `--radius-large` (12px) border radius for a modern, friendly aesthetic.
+
+### Token Categories
+
+- **Text:** `--color-text-primary`, `--color-text-secondary`, `--color-text-link`
+- **Backgrounds:** `--color-bg-primary`, `--color-bg-surface`, `--color-bg-overlay`
+- **Borders:** `--color-border-primary`, `--color-border-focus`
+- **Spacing:** `--space-xs` through `--space-2xl` (2px → 48px)
+- **Typography:** `--font-size-1` through `--font-size-11`, `--font-weight-*`
+- **Radius:** `--radius-small`, `--radius-medium`, `--radius-large`, `--radius-xl`
+- **Shadows:** `--shadow-sm`, `--shadow-md`, `--shadow-lg`, `--shadow-xl`
+- **HTTP Methods:** `--method-get-bg/text`, `--method-post-bg/text`, etc.
+
+**Read more:** `docs/design-system.md` — Complete token reference, component patterns, and usage examples.
+
 ## Key Files
 
 - `Makefile`: Validation orchestration, report generation
 - `scripts/build/validate_xorigin.py`: Validates x-origin annotations across all specs
 - `scripts/build/validate_jtbd.py`: Validates Jobs To Be Done format
 - `scripts/portal_generator/`: Static API portal generator package
+- `scripts/portal_generator/assets/styles.css`: Design system CSS variables (lines 39-270)
 - `scripts/tests/`: Portal generator test suite (pytest)
 - `scripts/pyproject.toml`: Pytest configuration for the portal generator
 - `.agents/skills/`: Agent skills (api-spec-validator, validate-imperative-format, jtbd-generator, etc.)
 - `docs/VALIDATION.md`: Detailed validation guide with CI/CD examples
+- `docs/design-system.md`: Complete design system documentation
+- `docs/portal-generator-architecture.md`: Architecture guidelines and best practices
 - `docs/schemas/x-origin.schema.json`: JSON Schema for x-origin extension (source of truth)
 - `docs/x-origin-schema.md`: Complete x-origin documentation with examples
 - `docs/jobs-readme.md`: JTBD documentation and usage guide