SoufianeDev 713eef51b0
feat(search): add RTL compatibility levels and --rtl filter (#553)
* feat(data): add rtl_level to styles and products

Classify every style and product row for right-to-left interfaces:
full (mirrors unchanged), partial (mirrors with per-component work),
caveats (layout encodes reading direction).

One column is appended per row; existing fields, column order and LF
line endings are untouched. Mirrors under cli/assets and .claude are
synced with npm run sync:assets.

* feat(search): add --rtl filter to style and product searches

search() accepts rtl="all|full|partial|caveats" and projects the new
rtl_level column, so filtered rows still carry their compatibility
level. Without that projection the filter saw None and dropped every
row, which is what broke the earlier attempt.

The filter runs after BM25 scoring but before max_results truncation.
Filtering the corpus before indexing shifted IDF and made calibrated
searches abstain incorrectly (dashboard --domain style --rtl=partial
returned nothing); scoring first keeps the corpus and thresholds
stable while still preventing -n 1 from hiding a matching row.

--rtl requires an explicit style/product domain, and is rejected with
--design-system and --stack.

relevance thresholds: runtimeFingerprint refreshed; every metric is
identical to the committed baseline.

* test: cover rtl data contract and filter ordering

Pin the behaviour the RTL filter depends on:

- rtl_level is projected, not a search signal;
- every row in both CSVs carries a supported level;
- known layouts keep their curated level;
- filtering happens before max_results truncation (saas --domain
  product -n 1 with --rtl=full returns Micro SaaS, while the unfiltered
  top hit is a partial row);
- omitting --rtl keeps previous results;
- unsupported domains raise ValueError and exit non-zero through the
  CLI.

* docs: document the rtl compatibility filter

Explain the three levels, the CLI flag and its domain restriction in
the README, CLAUDE.md, the generated skill content and the
hand-authored Claude skill. The agent guidance tells the skill to add
--rtl for Arabic, Hebrew, Persian and Urdu work and to respect the
returned level instead of silently mirroring a caveats layout.
2026-11-02 23:10:22 +07:00

6.1 KiB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

UI UX Pro Max is an AI-powered design intelligence toolkit providing searchable databases of UI styles, color palettes, font pairings, chart types, and UX guidelines. It works as a skill/workflow for AI coding assistants (Claude Code, Windsurf, Cursor, etc.).

Search Command

python3 src/ui-ux-pro-max/scripts/search.py "<query>" --domain <domain> [-n <max_results>]

Domain search:

  • product - Product type recommendations (SaaS, e-commerce, portfolio)
  • style - UI styles (glassmorphism, minimalism, brutalism) + AI prompts and CSS keywords
  • typography - Font pairings with Google Fonts imports
  • color - Color palettes by product type
  • landing - Page structure and CTA strategies
  • chart - Chart types and library recommendations
  • ux - Best practices and anti-patterns
  • icons - Icon recommendations with import code (Phosphor, Heroicons, Lucide)
  • react - React/Next.js performance patterns
  • web - App interface guidelines (iOS/Android/React Native)
  • google-fonts - Individual Google Fonts lookup
  • gsap - GSAP animation skeletons by intensity tier (hover, scroll reveal, stagger, page transition, parallax, loading)

Design dials (optional, only with --design-system):

python3 src/ui-ux-pro-max/scripts/search.py "<query>" --design-system --variance <1-10> --motion <1-10> --density <1-10>

--variance biases style selection (centered/minimal → bold/asymmetric), --motion attaches a matching GSAP snippet from motion.csv, --density overrides the spacing-scale tokens (spacious → dense/dashboard). Any dial left unset behaves exactly as before.

RTL filter (optional, style and product only):

python3 src/ui-ux-pro-max/scripts/search.py "<query>" --domain style --rtl[=full|partial|caveats]

styles.csv and products.csv carry an rtl_level column (full, partial, caveats) that describes how well the layout survives mirroring for Arabic, Hebrew, Persian and Urdu interfaces. --rtl without a value accepts every level; with a value it keeps only that level. The filter runs after BM25 scoring but before -n/--max-results truncation, so a small limit cannot hide a matching row. It is rejected with --design-system, with --stack, and with domains that have no RTL column.

Stack search:

python3 src/ui-ux-pro-max/scripts/search.py "<query>" --stack <stack>

Available stacks: html-tailwind (default), react, nextjs, astro, vue, nuxtjs, nuxt-ui, svelte, swiftui, react-native, flutter, shadcn, jetpack-compose, threejs, angular, laravel, javafx, wpf, winui, avalonia, uno, uwp

Architecture

src/ui-ux-pro-max/                # Source of Truth
├── data/                         # Canonical CSV databases
│   ├── products.csv, styles.csv, colors.csv, typography.csv, ...
│   └── stacks/                   # Stack-specific guidelines
├── scripts/
│   ├── search.py                 # CLI entry point
│   ├── core.py                   # BM25 + regex hybrid search engine
│   └── design_system.py          # Design system generation
└── templates/
    ├── base/                     # Base templates (skill-content.md, quick-reference.md)
    └── platforms/                # Platform configs (claude.json, cursor.json, ...)

cli/                              # CLI installer (ui-ux-pro-max-cli on npm)
├── src/
│   ├── commands/init.ts          # Install command with template generation
│   └── utils/template.ts         # Template rendering engine
├── scripts/sync-assets.mjs       # Mirrors src/ -> cli/assets/ AND src/ -> .claude/skills/ui-ux-pro-max/
└── assets/                       # Bundled assets (~564KB)
    ├── data/                     # Copy of src/ui-ux-pro-max/data/
    ├── scripts/                  # Copy of src/ui-ux-pro-max/scripts/
    └── templates/                # Copy of src/ui-ux-pro-max/templates/

.claude/skills/ui-ux-pro-max/     # Claude Code skill: hand-authored SKILL.md +
                                   # data/, scripts/ mirrored from src/ (see Sync Rules)
.claude-plugin/                   # Claude Marketplace publishing

The search engine uses BM25 ranking combined with regex matching. Domain auto-detection is available when --domain is omitted.

Sync Rules

Source of Truth: src/ui-ux-pro-max/

There are no symlinks in this repo (git-on-Windows checks them out as plain text files pointing at a path, which silently breaks the skill) -- every mirrored copy below is a real, independently-committed file kept in sync by cli/scripts/sync-assets.mjs, enforced by the "Check asset sync" CI workflow.

When modifying files:

  1. Data & Scripts - Edit in src/ui-ux-pro-max/:

    • data/*.csv and data/stacks/*.csv
    • scripts/*.py
    • Then run the sync below -- changes are NOT automatically reflected anywhere else.
  2. Templates - Edit in src/ui-ux-pro-max/templates/:

    • base/skill-content.md - Common SKILL.md content
    • base/quick-reference.md - Quick reference section (Claude only)
    • platforms/*.json - Platform-specific configs
  3. Sync before publishing / committing data or script changes:

    cd cli
    npm run sync:assets   # mirrors src/ -> cli/assets/ AND src/ -> .claude/skills/ui-ux-pro-max/{data,scripts}
    npm run check:assets  # verify, no npm install required
    

    .claude/skills/ui-ux-pro-max/SKILL.md itself is hand-authored, not mirrored or template-generated -- edit it directly.

  4. Reference Folders - No manual sync needed. The CLI generates these from templates during uipro init.

Prerequisites

Python 3.x (no external dependencies required)

Note: On Windows, use python instead of python3 to run the scripts.

Git Workflow

Never push directly to main. Always:

  1. Create a new branch: git checkout -b feat/... or fix/...
  2. Commit changes
  3. Push branch: git push -u origin <branch>
  4. Create PR: gh pr create