{"id":31574494,"url":"https://github.com/wespiper/ufr-ds","last_synced_at":"2026-01-20T17:29:15.934Z","repository":{"id":313397983,"uuid":"1051283551","full_name":"wespiper/ufr-ds","owner":"wespiper","description":"UFR Design System analyzer \u0026 generator powered by the Emergence Engine. Analyze React codebases, discover patterns, and generate canonical components.","archived":false,"fork":false,"pushed_at":"2025-09-05T20:06:14.000Z","size":44,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-09-25T07:55:32.421Z","etag":null,"topics":["babel","cli","design-system","emergence","grammar","mdl","react","typescript"],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wespiper.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-05T18:19:14.000Z","updated_at":"2025-09-05T20:06:18.000Z","dependencies_parsed_at":"2025-09-05T20:34:54.976Z","dependency_job_id":"2b61ee12-80f6-413f-bfa1-73514c34a278","html_url":"https://github.com/wespiper/ufr-ds","commit_stats":null,"previous_names":["wespiper/ufr-ds"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/wespiper/ufr-ds","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wespiper%2Fufr-ds","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wespiper%2Fufr-ds/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wespiper%2Fufr-ds/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wespiper%2Fufr-ds/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wespiper","download_url":"https://codeload.github.com/wespiper/ufr-ds/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wespiper%2Fufr-ds/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278477886,"owners_count":25993558,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-05T02:00:06.059Z","response_time":54,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["babel","cli","design-system","emergence","grammar","mdl","react","typescript"],"created_at":"2025-10-05T16:05:45.335Z","updated_at":"2025-10-05T16:05:49.288Z","avatar_url":"https://github.com/wespiper.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# UFR Design System - Enhanced Technical Specification\n\n[![CI](https://github.com/wespiper/ufr-ds/actions/workflows/ci.yml/badge.svg)](https://github.com/wespiper/ufr-ds/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/ufr-ds.svg)](https://pypi.org/project/ufr-ds/)\n[![npm (tokenizer)](https://img.shields.io/npm/v/%40ufr/ast-tokenizer.svg)](https://www.npmjs.com/package/@ufr/ast-tokenizer)\n\n## Executive Summary\n\n### What We're Building\n\nUFR-DS is a design grammar engine that analyzes existing React design systems (e.g., MUI, custom component libraries) to discover their underlying patterns, compress redundancies, and expose a shared grammar layer that designers and developers can work with together.\n\nUnlike traditional code generation tools, UFR-DS is not about replacing developer ownership of code. Instead, it acts as a translator between design and implementation:\n\n-   Designers work in tokens and patterns.\n-   Developers work in React code.\n-   UFR-DS ensures these two worlds stay in sync via a shared grammar.\n\n### Core Value Proposition\n\n-   **Migration readiness**: Analyze a legacy system (like MUI usage) and output a migration map to a custom system.\n-   **Compression \u0026 deduplication**: Reduce hundreds of slightly different components into clean, canonical pattern families.\n-   **Design-dev bridge**: Provide a visual grammar explorer, Storybook integration, and Figma mapping so both sides share the same vocabulary.\n-   **Standards enforcement**: Accessibility, performance, and testing are baked into the grammar.\n\n## Architecture Overview\n\n```\nInput: React Codebase (TypeScript components + Design Tokens + Figma refs)\n↓\nAnalyzer \u0026 Tokenizer (AST + Tokens)\n↓\nUFR Grammar Core (canonical tokens, component families, usage invariants)\n↓\nTranslator \u0026 Collaboration Tools (Figma ↔ React mapping, MUI ↔ custom migration, Storybook, docs)\n```\n\n## Key Technical Components\n\n### 1. Pattern Discovery Engine\n\n-   **AST Parser**: Analyzes React component files using Babel parser\n-   **Tokenizer**: Converts component structures to analyzable token sequences\n-   **Grammar Induction**: Uses RePair algorithm and Minimum Description Length (MDL) optimization\n-   **Pattern Classification**: Groups similar components into pattern families\n\n### 2. Grammar Core\n\n-   **Canonical Tokens**: Standardized representation of UI patterns\n-   **Component Families**: Groups of related components (e.g., Button variants)\n-   **Usage Invariants**: Rules that ensure consistency across implementations\n-   **Compression Engine**: Achieves 5-10x reduction in component count\n\n### 3. Translation Layer\n\n-   **Component Generator**: Converts grammar patterns back to React components\n-   **Migration Mapper**: Creates transition plans from legacy to optimized systems\n-   **Type Preservation**: Maintains TypeScript definitions through transformation\n-   **Variant System**: Handles component variations through props rather than duplication\n\n## Implementation Architecture\n\n```\nufr-design-system/\n├── packages/\n│   ├── core/                    # Grammar engine and pattern discovery\n│   │   ├── src/\n│   │   │   ├── engine/          # RePair + MDL implementation\n│   │   │   ├── grammar/         # Grammar structures and operations\n│   │   │   └── emergence/       # Pattern emergence detection\n│   │\n│   ├── react-analyzer/          # React-specific analysis\n│   │   ├── src/\n│   │   │   ├── parser/          # AST parsing and tokenization\n│   │   │   ├── patterns/        # Pattern recognition\n│   │   │   └── analyzer.ts      # Main analysis engine\n│   │\n│   ├── compiler/                # Grammar to React compiler\n│   │   ├── src/\n│   │   │   ├── generator/       # Component generation\n│   │   │   └── optimizer/       # Code optimization\n│   │\n│   ├── visual-editor/           # Designer interface\n│   │   └── src/                # Grammar Explorer UI\n│   │\n│   └── cli/                     # Command-line interface\n│       └── src/commands/        # analyze, generate, dedupe commands\n```\n\n## Key Features\n\n### 1. Pattern Discovery\n\nParse a React codebase into tokens and detect recurring structures using advanced grammar induction algorithms.\n\n**Example Analysis Output:**\n\n```\n✓ Found 127 components\n✓ Extracted 18 canonical patterns\n✓ Identified 42 duplicates\n✓ Compression ratio: 7.0x\n\nSuggested Consolidations:\n• Button, PrimaryButton, SecondaryButton → Button with variant\n• IconButton, Fab → Button with size + icon\n```\n\n### 2. Deduplication Reports\n\nCLI tool outputs duplicates, frequency, and suggested consolidations with actionable refactoring suggestions.\n\n### 3. Migration Mapping\n\nAnalyze an existing system and output grammar + migration suggestions for transitioning from legacy systems to optimized implementations.\n\n### 4. Design-Dev Bridge\n\n-   **Grammar Explorer UI**: Visual interface for browsing discovered patterns\n-   **Figma Plugin**: Token mapping between design and code\n-   **Storybook Integration**: Auto-generated stories for pattern documentation\n\n### 5. Standards Enforcement\n\n-   **Accessibility Checks**: Ensure WCAG compliance in generated components\n-   **Performance Constraints**: Optimize bundle size and runtime performance\n-   **Testing Hooks**: Auto-generate test suites for pattern families\n\n## Example Workflow\n\n### Analyzing a Legacy System\n\n```bash\nufr analyze ./node_modules/@mui/material --output analysis.json\n```\n\n**Output:**\n\n```\n✓ Found 127 components\n✓ Extracted 18 canonical patterns\n✓ Identified 42 duplicates\n✓ Compression ratio: 7.0x\n\nSuggested Consolidations:\n• Button, PrimaryButton, SecondaryButton → Button with variant\n• IconButton, Fab → Button with size + icon\n```\n\n### Generating Optimized Components\n\n```bash\nufr generate analysis.json --output ./optimized --typescript --storybook\n```\n\n**Generated Component Example:**\n\n```typescript\n// Before: 3 separate components\nimport { Button, PrimaryButton, SecondaryButton } from './legacy';\n\n// After: 1 pattern-based component\nimport { Button } from '@ufr/optimized';\n\n// Usage with variants\n\u003cButton variant=\"primary\" /\u003e\n\u003cButton variant=\"secondary\" /\u003e\n\u003cButton variant=\"icon\" icon={\u003cCheckIcon /\u003e} /\u003e\n```\n\n## Success Metrics\n\n### Technical Metrics\n\n-   **Compression ratio**: 5-10× component reduction\n-   **Type safety**: 95%+ generated code compiles without errors\n-   **Performance**: 20%+ bundle size reduction through deduplication\n-   **Speed**: CLI analyzes 1000+ components in \u003c30 seconds\n\n### Adoption Metrics\n\n-   **Migration coverage**: % of legacy components mapped to new grammar\n-   **Developer adoption**: Number of teams using grammar explorer/CLI\n-   **Design-dev alignment**: Reduction in translation errors between design and code\n\n## Roadmap\n\n-   **Phase 1**: AST parsing + tokenization → compression reports\n-   **Phase 2**: Grammar Explorer UI + Storybook integration\n-   **Phase 3**: Figma plugin for token mapping\n-   **Phase 4**: Migration mapping and CI integration\n\n## Technical Requirements\n\n### Dependencies\n\n-   **Core**: TypeScript, React, Babel (parser/traverse/types)\n-   **CLI**: Commander.js, Chalk, Ora\n-   **Analysis**: RePair algorithm implementation, MDL optimization\n-   **Generation**: TypeScript Compiler API, Prettier\n\n### Performance Targets\n\n-   Parse 1000+ components in \u003c30 seconds\n\n## Quick Start (Prototype CLI)\n\n- Analyze a React project directory using the vendored Emergence Engine:\n\n  python -m ufr_ds.cli analyze ./examples/material-ui-subset --pretty\n\n- Include emergence analysis (entropy trajectory + events):\n\n  python -m ufr_ds.cli analyze ./examples/material-ui-subset --emergence --pretty\n\n- Generate canonical components from discovered families (writes TSX stubs):\n\n  python -m ufr_ds.cli generate ./examples/material-ui-subset --out ./generated --pretty\n\nWhat this does:\n\n- Tokenizes JSX/TSX/JS files for tags, props, and imports (regex-based).\n- Runs RePair + MDL scoring to induce a grammar and compute compression.\n- Reports discovered rules and top tokens; optional emergence events.\n - Generates family-based component skeletons with a `variant` prop.\n-   Generate optimized library in \u003c10 seconds\n-   Visual editor loads in \u003c2 seconds\n-   Support codebases up to 10,000 components\n\n## Integration Examples\n\n### With Existing Workflow\n\n```typescript\n// Current: Multiple similar components\nimport { PrimaryButton, SecondaryButton, IconButton } from './components';\n\n// After UFR Analysis: Single flexible component\nimport { Button } from '@ufr/optimized';\n\n// Automatic migration suggestions\n\u003cButton variant=\"primary\" /\u003e    // was PrimaryButton\n\u003cButton variant=\"secondary\" /\u003e  // was SecondaryButton\n\u003cButton variant=\"icon\" /\u003e       // was IconButton\n```\n\n### With Design Systems\n\n```typescript\n// Integration with design tokens\nconst Button = ({ variant, size, ...props }) =\u003e {\n    return (\n        \u003cStyledButton\n            className={buttonVariants({ variant, size })}\n            {...props}\n        /\u003e\n    );\n};\n\n// Auto-generated from discovered patterns\nconst buttonVariants = cva(\"base-button-styles\", {\n    variants: {\n        variant: {\n            primary: \"bg-primary text-white\",\n            secondary: \"bg-secondary text-gray\",\n        },\n        size: {\n            small: \"px-2 py-1 text-sm\",\n            large: \"px-4 py-2 text-lg\",\n        },\n    },\n});\n```\n\n## Philosophy\n\nThe best design system is not the biggest—it's the smallest set of reusable patterns that both designers and developers can own together. UFR-DS exists to discover, enforce, and evolve that shared grammar.\n\n**Core Principles:**\n\n-   **Developer Ownership**: Code remains in developer control, UFR-DS provides translation\n-   **Pattern-First**: Focus on discovering existing patterns rather than imposing new ones\n-   **Compression Over Creation**: Reduce complexity rather than add new abstractions\n-   **Shared Vocabulary**: Bridge design and development through common grammar\n-   **Evidence-Based**: All recommendations backed by actual usage analysis\n\n## Getting Started\n\n### Installation\n\n```bash\nnpm install -g @ufr/cli\n# or\nnpx @ufr/cli analyze ./src/components\n```\n\n### Quick Analysis\n\n```bash\n# Analyze your components\nufr analyze ./src/components --output analysis.json\n\n# Review suggestions\nufr report analysis.json\n\n# Generate optimized components\nufr generate analysis.json --output ./optimized\n```\n\n### Integration\n\n```bash\n# Add to existing project\nnpm install @ufr/core @ufr/react-analyzer\n\n# Use programmatically\nimport { ReactPatternAnalyzer } from '@ufr/react-analyzer';\nconst analyzer = new ReactPatternAnalyzer();\nconst results = await analyzer.analyzeCodbase('./src');\n```\n\n---\n\n**Next Steps:** Start with a pilot analysis of your existing component library to see compression opportunities, then gradually adopt the generated patterns while maintaining your existing development workflow.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwespiper%2Fufr-ds","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwespiper%2Fufr-ds","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwespiper%2Fufr-ds/lists"}