{"id":27488256,"url":"https://github.com/ameritusweb/ycss","last_synced_at":"2026-05-03T22:34:56.783Z","repository":{"id":287461321,"uuid":"964803760","full_name":"ameritusweb/YCSS","owner":"ameritusweb","description":"YAML to CSS with semantically intelligent transpilation","archived":false,"fork":false,"pushed_at":"2025-04-12T23:11:30.000Z","size":349,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-01T08:44:16.832Z","etag":null,"topics":["css","style-optimization","yaml","yaml-to-css"],"latest_commit_sha":null,"homepage":"https://yamlcss.com","language":"C#","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/ameritusweb.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}},"created_at":"2025-04-11T20:15:13.000Z","updated_at":"2025-04-12T23:11:33.000Z","dependencies_parsed_at":"2025-04-16T20:03:08.685Z","dependency_job_id":null,"html_url":"https://github.com/ameritusweb/YCSS","commit_stats":null,"previous_names":["ameritusweb/ycss"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/ameritusweb/YCSS","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ameritusweb%2FYCSS","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ameritusweb%2FYCSS/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ameritusweb%2FYCSS/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ameritusweb%2FYCSS/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ameritusweb","download_url":"https://codeload.github.com/ameritusweb/YCSS/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ameritusweb%2FYCSS/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271073387,"owners_count":24694538,"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-08-18T02:00:08.743Z","response_time":89,"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":["css","style-optimization","yaml","yaml-to-css"],"created_at":"2025-04-16T19:55:41.250Z","updated_at":"2026-05-03T22:34:56.757Z","avatar_url":"https://github.com/ameritusweb.png","language":"C#","funding_links":[],"categories":[],"sub_categories":[],"readme":"# YCSS (YAML CSS) — Semantic, Pattern-Aware Style Compiler\n\n## Overview\nYCSS is a next-generation styling language and compiler built around YAML. It enables semantic, declarative, and intelligent styling through structured YAML definitions, replacing low-level SCSS complexity with composable, analyzable, and scalable visual architecture.\n\nYCSS is more than just a preprocessor — it's a **style compiler** that:\n- Parses YAML-based design tokens and component styles\n- Detects patterns and style duplication\n- Suggests utility classes and CSS variables\n- Generates CSS/SCSS output\n- Supports theming and component variants\n\n---\n\n## Features\n\n- **Declarative YAML Stylesheets**\n- **Token-Driven Design System Support**\n- **Pattern Analysis \u0026 Clustering**\n- **SCSS \u0026 CSS Code Generation**\n- **Component and Variant Modeling**\n- **Theming System (Light/Dark/Custom)**\n- **Built-in Suggestions for Optimization**\n\n---\n\n## Why YCSS?\n\nModern styling ecosystems face several recurring challenges:\n\n- 🔁 **Repetition \u0026 Duplication** — Common values and patterns repeat endlessly across CSS files.\n- ❓ **Lack of Semantic Context** — Class names and style groupings are often arbitrary, fragile, or legacy-bound.\n- 🤖 **No Built-In Analysis** — SCSS and utility-first tools offer no insight into what styles are being overused, under-optimized, or redundant.\n- 🧩 **Poor Reusability \u0026 Maintainability** — Without structure, design systems drift and grow inconsistent over time.\n\n**YCSS addresses these pain points** by offering a high-level, introspectable, and intelligence-driven approach:\n\n- 📦 **Design Token Native** — Treats your design tokens as first-class citizens. Easily refactor into CSS variables or SCSS maps.\n- 🧠 **Pattern-Aware Compiler** — Uses statistical techniques to detect duplicated values, clusters of properties, and high-cohesion design fragments.\n- 💡 **Refactoring Insights** — Suggests utility class abstractions, variable extraction, and mixin grouping automatically.\n- 🛠️ **Declarative, Not Procedural** — Write what your components are, not how the styles should unfold line by line.\n- 🌐 **Framework-Agnostic Output** — Generate CSS, SCSS, or even just token maps — no runtime overhead, no proprietary markup.\n- 📊 **Visualization \u0026 Auditing** — Export analysis results as graphs or reports to help teams see and improve the health of their style layer.\n\nYCSS is designed for scale, clarity, and optimization — for teams and systems that want style intelligence without sacrificing simplicity.\n\n---\n\n## Getting Started\n\n### Installation\n```bash\ndotnet tool install --global ycss\n```\n\n### Example YAML\n```yaml\ntokens:\n  color-primary: \"#1f2937\"\n  radius-md: \"0.5rem\"\n\ncomponents:\n  card:\n    base:\n      class: card\n      styles:\n        - background-color: var(--color-primary)\n        - border-radius: var(--radius-md)\n        - padding: 2rem\n\n    header:\n      class: card__header\n      styles:\n        - font-weight: bold\n        - padding: 1rem\n\n    variants:\n      compact:\n        class: card--compact\n        styles:\n          - padding: 1rem\n```\n\n---\n\n## CLI Commands\n\n### Build\nGenerate CSS or SCSS output from YAML:\nbash\nycss build design.yaml --out dist/styles.css\n\n\nOptional flags:\n- --format css (default) - Outputs standard CSS\n- --format scss - Outputs SCSS with $tokens and nested syntax\n- --theme dark - Applies theme overrides if defined in the YAML\n\nExample:\nbash\nycss build design.yaml --format scss --theme dark --out dist/dark-theme.scss\n\n\n### Analyze\nGenerate optimization suggestions (utility classes, tokens, property clusters):\nbash\nycss analyze design.yaml --report report.md\n\n\nOptional flags:\n- --verbose - Include raw pattern data\n- --min-cohesion 0.6 - Set cohesion threshold\n\n### Tokens Only\nOutput only the :root CSS variable definitions:\nbash\nycss tokens design.yaml --out dist/tokens.css\n\n\nOptional:\n- --format scss to output as $variables\n\n### Visualize\nGenerate a property correlation graph or cluster diagram (Graphviz-compatible):\nbash\nycss visualize design.yaml --out dist/graph.dot\n\n\nOptional flags:\n- --format png|svg|dot\n- --depth 3 - Controls cluster recursion\n\n---\n\n## How the Compiler Works\n\nYCSS operates in multiple stages to transform declarative YAML into optimized CSS or SCSS:\n\n### 1. Parsing Stage\n- Reads YAML and maps tokens and components into internal models.\n- Flattens nested structures and normalizes shorthand notations.\n\n### 2. Token Resolution\n- Builds a global token table.\n- Resolves var(--token-name) references.\n- Supports scoped or themed overrides.\n\n### 3. Pattern Detection\n\n#### Example Analysis Output\nHere are some real-world examples of what YCSS might report during analysis:\n\n**Example 1 — Utility Class Suggestion:**\nSuggestion: Create utility class `.util-padding-lg`\nDetected in:\n- .card\n- .card__body\n- .modal\nShared properties:\n  padding: 2rem;\n\nRationale: Padding 2rem appears in 6 different components. Use a shared utility class to reduce duplication.\n\n\n**Example 2 — CSS Variable Recommendation:**\nSuggestion: Extract CSS variable --border-radius-sm\nDetected in:\n- .button, .input, .badge\nShared value: border-radius: 4px;\nUsage count: 9\n \n\n**Example 3 — High-Cohesion Property Group:**\nPattern Cluster Detected: layout-flex-row\nProperties:\n- display: flex\n- flex-direction: row\n- align-items: center\n- gap: 1rem\nFrequency: 11 components\nCohesion Score: 0.92\n\nSuggestion: Abstract into mixin or reusable component block.\n\n\n**Example 4 — Outlier Detection:**\nAnomaly: padding: 1.125rem detected only once in .nav-link\nRecommendation: Normalize to token-based spacing (e.g. --spacing-md = 1rem or --spacing-lg = 1.5rem)\n\n\n**Example 5 — Correlation Insight:**\nStrong Property Correlation:\n  color + font-weight appear together in 89% of typographic components.\nConsider grouping into a text-style token.\n\n\n- Executes statistical analysis on the style rules to uncover latent structure and redundancy. This includes:\n  - **Property-Value Frequency Analysis**: Identifies high-frequency values that may warrant tokenization or variable extraction.\n  - **Pairwise Property Correlation (Jaccard Index)**: Measures the co-occurrence of style properties across components to assess how frequently properties appear together.\n  - **Mutual Information Estimation**: Quantifies the reduction in uncertainty about one property given knowledge of another. High mutual information indicates potential semantic grouping.\n  - **Chi-Square Test of Independence**: Evaluates whether the presence of one property is statistically dependent on another. A high chi-square score flags a non-random association, useful for discovering class-level design patterns.\n  - **Cluster Analysis**: Groups properties into hierarchies based on similarity metrics (cohesion, correlation) to suggest reusable style abstractions or mixins.\n  - **Value Distribution Modeling**: Constructs histograms for numeric values (e.g., margin, padding, border-radius) to detect outliers or non-standardized scales.\n- Generates actionable suggestions for:\n  - Utility class abstraction\n  - CSS variable introduction\n  - Semantic cluster naming and reuse\n- Emits CSS/SCSS based on:\n  - Selected output format (--format css|scss)\n  - Token usage and theme layering\n  - SCSS-specific syntax (e.g., $variables and mixins)\n- Supports minified or pretty-printed output.\n\n### 5. Visualization (Optional)\n- Generates data structures representing property correlation graphs.\n- Outputs DOT or SVG files for static or interactive visual analysis.\n\n---\n\n## Output Example\ncss\n:root {\n  --color-primary: #1f2937;\n  --radius-md: 0.5rem;\n}\n\n.card {\n  background-color: var(--color-primary);\n  border-radius: var(--radius-md);\n  padding: 2rem;\n}\n\n.card__header {\n  font-weight: bold;\n  padding: 1rem;\n}\n\n.card--compact {\n  padding: 1rem;\n}\n\n\n---\n\n## Comparison with Other Tools\n\n| Feature / Tool         | YCSS                      | SCSS/SASS                  | Tailwind CSS              | CSS-in-JS (e.g., Emotion)     | Stylelint + Tokens Studio |\n|------------------------|---------------------------|----------------------------|---------------------------|-------------------------------|----------------------------|\n| **Source Format**     | YAML                      | SCSS                       | Utility-first CSS         | JavaScript                   | CSS / JSON / YAML          |\n| **Tokens Support**    | Native (YAML-based)       | Partial (manual vars)      | Requires plugin           | Manual                       | Native (via plugin)        |\n| **Pattern Detection** | ✅ Statistical, clustered  | ❌                         | ❌                        | ❌                            | ✅ (Lint rules only)        |\n| **Theme System**      | Multi-theme via YAML      | Manual theme logic         | Manual via @apply       | Manual via props             | Manual token switching     |\n| **Output Types**      | CSS / SCSS / Tokens       | CSS                        | CSS                       | Injected CSS                 | N/A                        |\n| **Analysis CLI**      | ✅ Built-in                | ❌                         | ❌                        | ❌                            | ✅                          |\n| **Visualization**     | ✅ Graph/Cluster export    | ❌                         | ❌                        | ❌                            | Limited                    |\n| **Developer Ergonomics** | High (semantic YAML)    | Medium (expressive syntax) | Medium (opinionated)      | Low (JS coupling)            | Medium                     |\n\n---\n\n## Roadmap\n- [x] YAML Style Definitions\n- [x] Token-Driven Output\n- [x] Pattern Analysis \u0026 Suggestion Engine\n- [ ] IDE/Editor Plugins (VSCode, JetBrains)\n- [ ] Web-based Visual Editor\n- [ ] Integration with Blazor / React / Svelte\n\n---\n\n## Contributing\nWe welcome contributions! Help us build:\n- More YAML syntax sugar\n- Theme layering strategies\n- Advanced suggestion logic\n- SCSS mixin generation\n- Integration plugins for popular frameworks\n\n---\n\n## License\nMIT\n\n---\n\n## Author \u0026 Vision\nYCSS is created by engineers who lived through the complexity of SCSS, the memory leaks of Silverlight, and the verbosity of CSS-in-JS. It's built to bring **clarity, performance, and semantic structure** to modern UI development.\n\n\u003e YCSS is not just a preprocessor. It's a compiler for the future of design systems.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fameritusweb%2Fycss","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fameritusweb%2Fycss","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fameritusweb%2Fycss/lists"}