{"id":31037663,"url":"https://github.com/igorskyflyer/commoji","last_synced_at":"2026-03-07T06:04:07.898Z","repository":{"id":306455106,"uuid":"1026249968","full_name":"igorskyflyer/commoji","owner":"igorskyflyer","description":"🐉 Commoji: psychology-based emoji commit convention that makes your git history dramatically more readable, scannable and beautiful. 🏷️","archived":false,"fork":false,"pushed_at":"2026-02-28T04:07:16.000Z","size":159,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-28T07:41:31.001Z","etag":null,"topics":["commit","commoji","congnitive-load","convention","emoji","gestalt-psychology","git","igorskyflyer","log","parafoveal","psychology","saliency","spec","standard","visual-psychology"],"latest_commit_sha":null,"homepage":"","language":null,"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/igorskyflyer.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":".github/FUNDING.yml","license":null,"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},"funding":{"ko_fi":"igorskyflyer"}},"created_at":"2025-07-25T14:59:46.000Z","updated_at":"2026-02-28T04:07:19.000Z","dependencies_parsed_at":"2025-07-25T22:17:23.487Z","dependency_job_id":"ff5627ea-0db8-45ba-94fd-4ac2be91c04f","html_url":"https://github.com/igorskyflyer/commoji","commit_stats":null,"previous_names":["igorskyflyer/commoji"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/igorskyflyer/commoji","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorskyflyer%2Fcommoji","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorskyflyer%2Fcommoji/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorskyflyer%2Fcommoji/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorskyflyer%2Fcommoji/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/igorskyflyer","download_url":"https://codeload.github.com/igorskyflyer/commoji/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/igorskyflyer%2Fcommoji/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30208806,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-07T05:23:27.321Z","status":"ssl_error","status_checked_at":"2026-03-07T05:00:17.256Z","response_time":53,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["commit","commoji","congnitive-load","convention","emoji","gestalt-psychology","git","igorskyflyer","log","parafoveal","psychology","saliency","spec","standard","visual-psychology"],"created_at":"2025-09-14T05:59:06.769Z","updated_at":"2026-03-07T06:04:07.889Z","avatar_url":"https://github.com/igorskyflyer.png","language":null,"funding_links":["https://ko-fi.com/igorskyflyer"],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n  \u003cimg src=\"https://raw.githubusercontent.com/igorskyflyer/commoji/main/assets/commoji.png\" alt=\"Icon of Commoji, an expressive emoji commit tagging system\" width=\"256\" height=\"256\"\u003e\n\u003ch1 align=\"center\"\u003e\u003ccode\u003eCommoji\u003c/code\u003e\u003c/h1\u003e\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\nThis file contains the\n\u003cbr\u003e\n\u003cstrong\u003e\u003ccode\u003ev2.0.1\u003c/code\u003e\u003c/strong\u003e • \u003cem\u003e\u003cstrong\u003e07 Mar 2026\u003c/strong\u003e\u003c/em\u003e\n\u003cbr\u003e\nspecification and documentation of \u003ccode\u003eCommoji\u003c/code\u003e.\n\n\u003cbr\u003e\n\n\u003cblockquote\u003e\n  🚀 Head to the \u003ca href=\"https://github.com/igorskyflyer/commoji/tree/main/revisions\"\u003eRevisions\u003c/a\u003e or \u003ca href=\"https://github.com/igorskyflyer/commoji/releases/\"\u003eReleases\u003c/a\u003e page to browse the other versions.\n\u003c/blockquote\u003e\n\u003c/div\u003e\n\n\u003cbr\u003e\n\n\u003cdiv align=\"center\"\u003e\n  🐉 \u003ccode\u003eCommoji\u003c/code\u003e is a psychology-based emoji commit convention that optimizes Git history for high-speed scanning and semantic clarity. 🏷️\n  \u003cbr\u003e\n  \u003cbr\u003e\n  Need a shorter, shareable summary?\n  \u003cbr\u003e\n  \u003ca href=\"https://github.com/igorskyflyer/commoji/blob/main/RESEARCH.md\"\u003e\u003cstrong\u003eRESEARCH.md – The Science Behind Commoji\u003c/strong\u003e\u003c/a\u003e\n\u003c/div\u003e\n\n\u003cbr\u003e\n\n## Table of Contents\n\n- ✨ [**Features**](#features)\n- 🧠 [**The Psychology**](#the-psychology)\n- 🤹🏼 [**Usage**](#usage)\n  - [**Format**](#format)\n  - [**Breaking Changes**](#breaking-changes)\n  - [**Tags**](#tags)\n  - [**Scope**](#scope)\n  - [**Verbs**](#verbs)\n  - [**Object**](#object)\n  - [**Tooling**](#tooling)\n- 🗒️ [**Examples**](#examples)\n- 🌐 [**References**](#references)\n- 📝 [**Changelog**](#changelog)\n- 🪪 [**License**](#license)\n- 💖 [**Support**](#support)\n- 🧬 [**Related**](#related)\n- 👨🏻‍💻 [**Author**](#author)\n\n---\n\n## Features\n\n`Commoji` blends semantic clarity with visual expressiveness in commit messages to make intent easier to convey. It's not just a tagging system; it's a **psychology-based** visual grammar for storytelling in code.\n\n- ✨ **Visual Expressiveness**: Emojis provide instant, colorful cues that make commit histories pop and easier to scan at a glance. Eye-tracking research confirms emojis are detected parafoveally (before direct fixation) and increase skipping rates of nearby text while reducing total reading time.\n- 🏷️ **Semantic Orthogonality**: Distinct domain tags and operational verbs ensure every message clearly conveys purpose without tautological ambiguity.\n- 📊 **Reduced Cognitive Load**: Fixed format lowers mental effort, allowing quick understanding of changes in logs or diffs. Congruent emojis improve processing fluency and message understanding compared with plain text.\n- 🧠 **Intuitive Design**: Draws on psychological principles like pop-out effect and chunking for a more natural reading experience.\n- 🚀 **Tooling Compatibility**: Designed to work with parsers, linters, and changelog generators; see the [**Tooling**](#tooling) section for ready-to-use examples.\n\n---\n\n## The Psychology\n\n`Commoji` originated from real-world attempts to make dense commit logs easier to skim quickly. Its design choices – visual anchors, strict domain–operation separation, predictable structure – turned out to align closely with well-documented mechanisms of visual perception and cognitive load reduction. The thinking that originated from earlier patterns used in projects like [**AdVoid**](https://github.com/the-advoid/ad-void), where emoji prefixes proved highly effective for instantly identifying module-specific changes in dense histories, evolved to a scientific-based system that `Commoji` is today.  \n\nHere are the key psychological principles that power the system:\n\n- **Visual Indexing \u0026 Attentional Capture** (Treisman \u0026 eye-tracking research)  \n  Emojis act as high-contrast pre-attentive anchors. Their color and shape differences allow rapid detection during skimming – often via parafoveal preview – guiding attention to relevant commits before full text reading begins. Eye-tracking studies confirm congruent emojis are processed parafoveally (like words), are skipped more often than incongruent ones, and reduce total fixation time on the preceding target word (Barach et al., 2021).\n\n- **Semantic Orthogonality** (Information Theory)  \n  Strict noun–verb separation eliminates redundancy. Independent axes maximize information per character and enable near-instant mental model construction. Large-scale analysis of GitHub commits and pull requests shows developers already use emoji prefixes for attention and content organization, leading to measurably faster team responses (Rong et al., 2022).\n\n- **Gestalt Grouping \u0026 Chunking**  \n  The emoji + tag prefix creates immediate perceptual unity (proximity + similarity), turning each commit into a reliable, bite-sized chunk.\n\n- **Cognitive Load Reduction \u0026 Processing Fluency**  \n  Predictable prefix + concise object offloads parsing effort. Once learned, reading feels subjectively effortless and fast (familiarity heuristic). Messages with congruent emojis are rated as more understandable and require less cognitive effort than plain text (Daniel \u0026 Camp, 2020; Boutet et al., 2021).\n\n- **Dual-layer Signaling**  \n  Emoji and matching tag reinforce the same category without overload – increasing clarity in dense, fast-scrolling logs through multimodal (visual + verbal) encoding.\n\n\u003cbr\u003e\n\n\u003e [!NOTE]\n\u003e Emojis are powerful visual cues, but they may not render for every user (colorblindness, certain terminals, screen readers). The standardized shortcodes (`:sparkles:`, etc.) ensure the spec remains accessible and machine-readable.\n\nIn short, `Commoji` doesn't just look nicer, it works *with* your brain instead of against it.\n\n---\n\n## Usage\n\n### Format\n\n`Commoji` relies on a strict **Noun/Action Separation** to eliminate repetition and enforce semantic orthogonality.  \nThe **tag** identifies the *domain* (the “what”), and the **verb** identifies the *operation* (the “how”).\n\n#### Core Format\n\n- **No scope** (global change or scope unknown):  \n  `\u003cemoji\u003e \u003ctag\u003e: \u003cverb\u003e \u003cobject\u003e`\n\n- **With scope** (specific module, component, or directory):  \n  `\u003cemoji\u003e \u003ctag\u003e(\u003cscope\u003e): \u003cverb\u003e \u003cobject\u003e`\n\n#### Spacing \u0026 Casing Rules (mandatory)\n- Exactly **one space** after the emoji  \n- **No space** between `\u003ctag\u003e` and `(` when a scope is present  \n- Exactly **one space** after the colon `:`  \n- `emoji` and `tag` are taken exactly from the official tables  \n- `scope` is always **lowercase** with hyphens (`user-profile`)  \n- `verb` is always **lowercase** imperative present tense; preferably chosen from the Verbs table, but other verbs are allowed when needed\n- `object` must be lowercase by default. Capitalization is reserved strictly for Proper Nouns, Brands, or Technical Identifiers to preserve semantic accuracy.  \n\n#### Emoji Rendering\nUse the actual **UTF-8 emoji character** whenever possible.  \nIf your environment does not render emojis correctly, use the standardized **shortcodes** shown in the Tags table (e.g. `:sparkles:`, `:bug:`, `:lipstick:`).\n\nThe `emoji` and `tag` **must** come from the official tables. The `verb` follows the rules defined in the [**Verbs**](#verbs) section.\n\n\u003e [!TIP]\n\u003e This rigid prefix structure is what enables fast visual scanning and future automated tooling.\n\n\u003cbr\u003e\n\n### Breaking Changes\n\nTo indicate a breaking change (API removal, incompatible API change, removed feature, etc.), place an exclamation mark (`!`) **immediately before the colon**.\n\n#### Syntax\n\n- **No scope**  \n  `\u003cemoji\u003e \u003ctag\u003e!: \u003cverb\u003e \u003cobject\u003e`\n\n- **With scope**  \n  `\u003cemoji\u003e \u003ctag\u003e(\u003cscope\u003e)!: \u003cverb\u003e \u003cobject\u003e`\n\n#### Examples (fully compliant with Format rules)\n\n- `🐛 bug!: update login response format`\n- `✨ feature(ui)!: remove deprecated dark mode toggle`\n- `🔨 logic(auth)!: rename internal token keys`\n- `📦 deps(user-profile)!: remove lodash v4`   \u003c!-- multi-word scope example --\u003e\n\n#### Why the `!` goes before the colon?\nPlacing the `!` immediately before the colon (after `tag` and optional `scope`) follows established conventions while still keeping the breaking signal in the visual prefix. This ensures instant recognition during scanning and better compatibility with conventional commit parsers.\n\n#### Recommended commit body\nAlways explain the impact in the body using the conventional uppercase marker:\n\n```markdown\n**BREAKING CHANGE**: Legacy OAuth1 tokens are no longer supported.  \nMigrate to OAuth2 before v2.0.0.\n```\n\n\u003e [!NOTE]\n\u003e The ! is optional. Use it only when the change truly breaks existing consumers or contracts in that domain.\n\n\u003cbr\u003e\n\n### Tags\n\n`Commoji` defines a fixed set of tags that act as **Nouns** representing the domain or entity being modified.  \nEmoji/tag pairs are **immutable**; the tag must always be preceded by its exact corresponding emoji.\n\n\u003cdiv align=\"center\"\u003e\n\n|**Category**            | **Emoji** | **Tag**          | **Domain / Purpose**                                      | **Shortcode**                  |\n|:----------------------:|:---------:|:----------------:|:----------------------------------------------------------|:-------------------------------|\n| **Core**               |   ✨      | **feature**      | New capabilities or features                              | `:sparkles:`                   |\n| **Core**               |   🐛      | **bug**          | Faults, defects, or issues                                | `:bug:`                        |\n| **Core**               |   🔨      | **logic**        | Code architecture and internal structure                  | `:hammer:`                     |\n| **Core**               |   🔥      | **debt**         | Technical debt and dead code                              | `:fire:`                       |\n| **Core**               |   🐣      | **repo**         | Initial setup or repository metadata                      | `:hatching_chick:`             |\n| **UI \u0026 Experience**    |   💄      | **ui**           | Visual elements, styles, and interface polish             | `:lipstick:`                   |\n| **UI \u0026 Experience**    |   🧠      | **ux**           | User experience flows, interactions, and logic            | `:brain:`                      |\n| **UI \u0026 Experience**    |   ♿      | **accessibility**| Accessibility (a11y) requirements                         | `:wheelchair:`                 |\n| **Docs \u0026 Quality**     |   📚      | **docs**         | Documentation and guides                                  | `:books:`                      |\n| **Docs \u0026 Quality**     |   ✅      | **spec**         | Tests, assertions, and validations                        | `:white_check_mark:`           |\n| **Build \u0026 Ops**        |   📦      | **deps**         | Dependencies and packages                                 | `:package:`                    |\n| **Build \u0026 Ops**        |   🚀      | **env**          | Environments, deployments, and releases                   | `:rocket:`                     |\n| **Build \u0026 Ops**        |   👷      | **ci**           | Continuous integration workflows                          | `:construction_worker:`        |\n| **Build \u0026 Ops**        |   🏭      | **build**        | Build system or compiler instructions                     | `:factory:`                    |\n| **Build \u0026 Ops**        |   ⚙️      | **config**       | System and environment configuration                      | `:gear:`                       |\n| **Performance**        |   ⚡      | **metrics**      | Performance, efficiency, and metrics                      | `:zap:`                        |\n| **Security**           |   🔐      | **security**     | Vulnerabilities and security hardening                    | `:closed_lock_with_key:`       |\n| **Maintenance**        |   🔧      | **chore**        | Miscellaneous maintenance and chores                      | `:wrench:`                     |\n| **Maintenance**        |   ⏪      | **history**      | Git history state or reverts                              | `:rewind:`                     |\n| **Maintenance**        |   🔀      | **branch**       | Merges and branch integration                             | `:twisted_rightwards_arrows:`  |\n| **Maintenance**        |   🌐      | **i18n**         | Localization and internationalization                     | `:globe_with_meridians:`       |\n| **Maintenance**        |   🔬      | **experiment**   | Experimental prototypes                                   | `:microscope:`                 |\n\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cem\u003eTable 1. \u003ccode\u003eCommoji\u003c/code\u003e's tagging system (Domains)\u003c/em\u003e\n\u003c/div\u003e\n\n\u003cbr\u003e\n\n\u003e [!NOTE]\n\u003e - Tags must **always** be written in lowercase.\n\u003e - Emoji/tag pairs are immutable – never invent or swap them.\n\u003e - Note on `chore`: use this tag only for changes that truly don't fit other domains. Frequent `chore` usage reduces semantic clarity – aim to keep it \u003c25–30% of commits by preferring more specific tags when possible.\n\n**Examples**\n\n- ✅ `🐛 bug: fix memory leak in caching layer`\n- ✅ `🔥 debt: remove deprecated v1 api controllers`\n- ❌ `🚨 fix: memory leak…` – `fix` is not a valid tag\n- ❌ `✨ bug: fix memory leak` – emoji/tag mismatch\n\n\u003cbr\u003e\n\n### Scope\n\nThe scope narrows the commit's focus to a specific module, component, feature, or directory. This lets readers instantly know *where* the change applies without opening the diff.\n\n#### Rules (mandatory)\n\n- Use the exact name of the relevant folder, module, or component (e.g. `auth`, `payment-gateway`, `user-profile`).\n- Always **lowercase** with hyphens for multi-word scopes.\n- Omit the scope entirely when:\n  - the change affects the whole project, or\n  - the scope would be identical or semantically duplicate the tag (e.g. `metrics(performance)`, `ui(styles)`).\n- Avoid broad/generic scopes such as `core`, `misc`, `utils`, `main` – they defeat the purpose of scoping. Use `chore` tag instead and put details in the object.\n\n#### Examples (fully compliant with Format \u0026 orthogonality)\n\n- ✅ `✨ feature(payment-gateway): add Stripe webhook handler`\n- ✅ `📚 docs(auth): add table of contents to README`\n- ✅ `🔨 logic: refactor token validation`   \u003c!-- global / no useful scope --\u003e\n- ❌ `💄 ui(ui): update button styles` – scope duplicates tag\n- ❌ `⚡ metrics(performance): optimize startup time` – semantic duplication\n- ❌ `🔧 chore(Misc): update utilities` – capitalized + generic\n\n\u003e [!NOTE]\n\u003e When in doubt, omit the scope. A clean `tag: verb object` is always preferred over a vague or redundant `(scope)`.\n\n\u003cbr\u003e\n\n### Verbs\n\nVerbs represent the Operation (the “how”) applied to the domain tag.  \n**To ensure consistency and fast scanning, verbs should be selected from the official table below.** This enforces semantic orthogonality between domain (`tag`) and operation. If absolutely no table verb fits naturally and accurately, select the semantically closest one and explain nuances in the commit body (not the summary line).\n\n\u003cdiv align=\"center\"\u003e\n\n|   **Verb**     |               **Action Purpose**                          |\n|:--------------:|:---------------------------------------------------------:|\n|**add**         |_Introduce a new element_                                  |\n|**update**      |_Modify an existing element_                               |\n|**remove**      |_Eliminate something_                                      |\n|**rename**      |_Change a name or label_                                   |\n|**move**        |_Reposition without modifying content_                     |\n|**implement**   |_Build out functionality_                                  |\n|**fix**         |_Resolve a fault or issue_                                 |\n|**refactor**    |_Improve structure without changing behavior_              |\n|**optimize**    |_Improve performance or efficiency_                        |\n|**test**        |_Add or modify tests_                                      |\n|**configure**   |_Adjust system or environment settings_                    |\n|**prepare**     |_Set up for release or deployment_                         |\n|**release**     |_Publish or ship a version_                                |\n|**revert**      |_Undo a previous change_                                   |\n|**integrate**   |_Combine branches or changes_                              |\n|**clean**       |_Purge unused or obsolete elements_                        |\n|**translate**   |_Add or revise localization_                               |\n|**document**    |_Add or improve explanatory documentation_                 |\n|**generate**    |_Create generated / derived files or code_                 |\n|**bump**        |_Increment or set a specific version (esp. deps/packages)_ |\n|**upgrade**     |_Move to a newer major/minor version_                      |\n|**migrate**     |_Adapt code/data to new structure/format/system_           |\n|**harden**      |_Apply security measures / strengthen against threats_     |\n\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cem\u003eTable 2. \u003ccode\u003eCommoji\u003c/code\u003e's verbs (Operations)\u003c/em\u003e\n\u003c/div\u003e\n\n\u003cbr\u003e\n\n\u003e [!IMPORTANT]\n\u003e Verbs must come from the table above.\n\u003e\n\u003e When no entry fits perfectly, select the semantically closest verb and clarify nuances in the commit body.\n\n\u003cbr\u003e\n\n**Examples (fully compliant)**\n\n- ✅ `🔨 logic(auth): refactor token validation`\n- ✅ `📚 docs: document new payment flow`\n- ✅ `🔐 security: harden API endpoints against XSS`\n- ❌ `🔬 experiment: experiment with caching` – `verb` repeats `tag` (use clearer phrasing)\n- ❌ `🔀 branch: merge main` – `verb` repeats `tag` (use clearer phrasing)\n- ❌ `🔨 logic(auth): refactored token validation` – wrong tense\n\n\u003e [!TIP]\n\u003e When a change truly spans multiple concerns, choose the highest-level verb and explain details in the body.\n\n\u003cbr\u003e\n\n\u003e [!TIP]\n\u003e **Quick verb cheat-sheet**\n\u003e\n\u003e - New → `add` / `implement`\n\u003e - Change → `update` / `refactor` / `fix`\n\u003e - Delete → `remove` / `clean`\n\n\u003cbr\u003e\n\n### Object\n\nThe object is a concise noun phrase that answers **“what exactly changed?”**.  \nIt completes the sentence started by the tag + verb while staying short and scannable.\n\n#### Rules (mandatory for consistency)\n\n- Use a **specific noun phrase** (never repeat the tag or verb semantically).\n- Keep the entire summary line (emoji through object) under **72** whenever possible; aim for **≤ 65** for best readability in dense logs and small screens.\n- The `object` should be lowercase by default to promote uniform, scannable logs. Capitalize only:\n  - Proper nouns (names, brands: Stripe, React, Vite)\n  - Acronyms and technical terms that are conventionally capitalized (API, XSS, OAuth2, URL, ToC, JSON, HTML)\n  - Do not capitalize the first word of the object (avoid sentence-style capitalization) for consistency across the history.\n- Never turn the `object` into a full sentence or list – use the commit body for details.\n\n\u003e [!IMPORTANT]\n\u003e Avoid semantic repetition of the tag or verb in the object where possible (e.g. avoid bug: fix bug).\n\u003e\n\u003e Exceptions are allowed for concise, idiomatic patterns – especially dependency updates, version bumps, or technical identifiers – where including the action or version adds clarity without vagueness.\n\u003e\n\n**Examples of acceptable mild overlap:**\n- 📦 `deps: bump lodash to 4.17.21`\n- 📦 `deps: upgrade react-router from 6.4 to 6.26`\n- 🏭 `build: pin vite@5.4.0`\n\n#### Examples (fully compliant with all previous rules)\n\n\u003cdiv align=\"center\"\u003e\n\n|                **Summary**                          | **Valid** |                                         **Reason**                                      |\n|:---------------------------------------------------:|:---------:|:---------------------------------------------------------------------------------------:|\n|`📚 docs(api): add table of contents`                |    ✅    |_Specific noun phrase_                                                                   |\n|`🔨 logic(auth): refactor token validation`          |    ✅    |_Precise internal change_                                                                |\n|`🐛 bug: fix null pointer in login`                  |    ✅    |_Identifies exact failure point_                                                         |\n|`⚡ metrics: add cache layer for startup`            |    ✅    |_Specific improvement, no verb echo_                                                     |\n|`📚 docs: update installation guide`                 |    ✅    |_Clear subsection_                                                                       |\n|`📚 docs: update docs`                               |    ❌    |_Object too broad / repeats tag_                                                         |\n|`✨ feature: add mode`                               |    ❌    |_Ambiguous object_                                                                       |\n|`🐛 bug: fix bug`                                    |    ❌    |_Repeats tag_                                                                            |\n|`⚡ metrics: optimize performance`                   |    ❌    |_Vague object + minor verb-tag overlap (prefer specific noun; avoid echo where possible)_|\n\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cem\u003eTable 3. \u003ccode\u003eCommoji\u003c/code\u003e's object examples\u003c/em\u003e\n\u003c/div\u003e\n\n\u003cbr\u003e\n\n\u003e [!TIP]\n\u003e When a change has many small parts, pick the single most important noun phrase for the summary and list the rest in the body:\n\n```markdown\n📚 docs: add table of contents\n\n- generated ToC for every heading\n- updated all internal anchor links\n- fixed minor typos in code blocks\n```\n\n---\n\n### Tooling\n\n`Commoji` is built first and foremost for **human readers**. Full 100% automated enforcement of every rule (especially semantic orthogonality, verb choice, and object quality) is inherently difficult with today's conventional linters.\n\n#### Current possibilities\nStandard tools like `commitlint` can reliably enforce the structural parts of the spec:\n- Presence of emoji + valid tag\n- Lowercase scope\n- Header length\n- Breaking-change `!` placement\n\nDeeper rules (verb appropriateness, avoiding semantic repetition in the object, etc.) cannot be perfectly validated automatically.\n\n#### Recommended approach\n- Use the minimal `commitlint` config below for basic structural guardrails.\n- Rely on the upcoming **official Commoji VS Code Extension** (currently in development) as the primary tool for full guidance, interactive commit creation, real-time validation, and best compliance.\n\n#### Minimal commitlint config (`.commitlintrc.js`)\n\n```js\nmodule.exports = {\n  extends: ['@commitlint/config-conventional'],\n  rules: {\n    'type-enum': [2, 'always', [\n      'repo', 'feature', 'bug', 'docs', 'ui', 'logic', 'metrics', 'spec',\n      'build', 'ci', 'env', 'chore', 'experiment', 'history', 'branch',\n      'deps', 'config', 'debt', 'security', 'ux', 'accessibility', 'i18n'\n    ]],\n    'scope-case': [2, 'always', 'lower-case'],\n    'subject-case': [0],                    // disabled – object allows brands, acronyms, proper nouns\n    'subject-empty': [2, 'never'],\n    'subject-full-stop': [2, 'never'],\n    'header-max-length': [2, 'always', 72],\n    'type-empty': [2, 'never']\n  }\n};\n```\n\n---\n\n## Examples\n\nThe table below demonstrates real commit messages that fully comply – or deliberately violate – the complete set of locked `Commoji` rules (Format, Tags, Scope, Verbs, Object, Breaking Changes, and semantic orthogonality).\n\n\u003cdiv align=\"center\"\u003e\n\n|             **Commit Message**                                      | **Valid** |                                       **Why**                             |\n|:-------------------------------------------------------------------:|:---------:|:-------------------------------------------------------------------------:|\n|`📚 docs(api): add table of contents`                               |    ✅    |_Specific object + valid scope_                                              |\n|`🔨 logic(auth): refactor token validation`                         |    ✅    |_Imperative verb, no repetition_                                             |\n|`🐛 bug: fix null pointer in login`                                 |    ✅    |_Precise object, no scope needed_                                            |\n|`📚 docs: document new payment flow`                                |    ✅    |_Valid table verb + specific object_                                         |\n|`🔐 security: harden API endpoints against XSS`                     |    ✅    |_Valid table verb + avoids tag repetition_                                       |\n|`✨ feature(payment-gateway): add Stripe webhook handler`           |    ✅    |_Valid scope, specific object_                                               |\n|`🔥 debt: remove deprecated v1 controllers`                         |    ✅    |_No verb echo, clean debt usage_                                             |\n|`✨ feature!(ui): remove deprecated dark mode toggle`               |    ✅    |_Breaking change with scope_                                                 |\n|`🐛 bug!: update login response format`                             |    ✅    |_Breaking change without scope_                                              |\n|`📦 deps!(user-profile): remove lodash v4`                          |    ✅    |_Breaking change + multi-word scope_                                         |\n|`📚 docs: update docs`                                              |    ❌    |_Object repeats tag (violates orthogonality)_                                |\n|`⚡ metrics: optimize performance`                                  |    ❌    |_Verb echoes tag + vague object_                                             |\n|`🐛 bug: Fix Login Bug`                                             |    ❌    |_Capitalized verb + object repeats domain_                                   |\n|`🔨 logic(auth): refactored token validation`                       |    ❌    |_Past tense (must be imperative present)_                                    |\n|`💄 ui(ui): update button styles`                                   |    ❌    |_Scope duplicates tag_                                                       |\n\n\u003c/div\u003e\n\n\u003cdiv align=\"center\"\u003e\n  \u003cem\u003eTable 4. \u003ccode\u003eCommoji\u003c/code\u003e commit message examples (v2.0.0)\u003c/em\u003e\n\u003c/div\u003e\n\n\u003cbr\u003e\n\n\u003e [!TIP]\n\u003e Use these examples as quick reference when writing or reviewing. Every valid row above follows **all** locked sections without exception.\n\n---\n\n## References\n\nThe psychological foundation of `Commoji` draws from well-established research in visual perception, cognitive psychology, information theory, and multimedia learning.\n\n### Classic Foundational Works\n- **Feature Integration Theory \u0026 Pop-out Effect**  \n  Treisman, A. M., \u0026 Gelade, G. (1980). A feature-integration theory of attention. *Cognitive Psychology*, 12(1), 97–136. https://doi.org/10.1016/0010-0285(80)90005-5\n\n- **Gestalt Principles**  \n  Wertheimer, M. (1923). Laws of Organization in Perceptual Forms. *Psychologische Forschung*, 4(1), 301–350.  \n  Koffka, K. (1935). *Principles of Gestalt Psychology*. Harcourt, Brace.\n\n- **Cognitive Load Theory**  \n  Sweller, J. (1988). Cognitive load during problem solving: Effects on learning. *Cognitive Science*, 12(2), 257–285.  \n  Sweller, J., Ayres, P., \u0026 Kalyuga, S. (2011). *Cognitive Load Theory*. Springer.\n\n- **Multimedia Learning \u0026 Signaling Principle**  \n  Mayer, R. E. (2021). *The Cambridge Handbook of Multimedia Learning* (3rd ed.). Cambridge University Press.  \n  (See especially chapters on the Signaling Principle and Reducing Extraneous Processing.)\n\n- **Processing Fluency \u0026 Familiarity Heuristic**  \n  Schwarz, N. (2004). Metacognitive experiences in judgment and decision making. *Journal of Consumer Psychology*, 14(4), 332–348.\n\n- **Chunking \u0026 Working Memory**  \n  Miller, G. A. (1956). The magical number seven, plus or minus two: Some limits on our capacity for processing information. *Psychological Review*, 63(2), 81–97.\n\n\u003e [!NOTE]\n\u003e These references informed the consolidation of principles in the Psychology section. For eye-movement and parafoveal preview benefits in reading (supporting fast scanning of emoji-prefixed commits), see Rayner, K. (1998). Eye movements in reading and information processing: 20 years of research. *Psychological Bulletin*, 124(3), 372–422.\n\n### Empirical Studies on Emoji Processing \u0026 Software Communication\n- **Barach, E., et al.** (2021). Are emojis processed like words?: Eye movements reveal the time course of semantic processing for emojified text. *Psychonomic Bulletin \u0026 Review*, 28(3), 983–997. https://doi.org/10.3758/s13423-020-01864-y  \n  *(Core evidence for parafoveal preview, skipping rates, and reduced fixation times – directly supports high-speed Git log scanning.)*\n\n- **Daniel, T. A., \u0026 Camp, A. L.** (2020). Emojis affect processing fluency on social media. *Psychology of Popular Media*, 9(2), 208–213. https://doi.org/10.1037/ppm0000219  \n  *(Shows congruent emojis make messages subjectively easier and faster to understand.)*\n\n- **Boutet, I., LeBlanc, M., et al.** (2021). Emojis influence emotional communication, social attributions, and information processing. *Computers in Human Behavior*, 119, 106722. https://doi.org/10.1016/j.chb.2021.106722  \n  *(Faster processing speed and better comprehension with congruent emojis.)*\n\n- **Rong, S., Wang, W., Mannan, U. A., et al.** (2022). An empirical study of emoji use in software development communication. *Information and Software Technology*, 148, 106912. https://doi.org/10.1016/j.infsof.2022.106912  \n  *(Large-scale GitHub analysis: emoji prefixes speed up responses and improve organization in commits/PRs – perfect real-world validation for Commoji.)*\n\n---\n\n## Changelog\n\nRead about the latest changes in the [**CHANGELOG**](https://github.com/igorskyflyer/commoji/blob/main/CHANGELOG.md).\n\n---\n\n## License\n\nLicensed under the [**MIT license**](https://github.com/igorskyflyer/commoji/blob/main/LICENSE).\n\n---\n\n## Support\n\n\u003cdiv align=\"center\"\u003e\n  Engineering and documenting open-source projects involves a significant investment of time.\n  \u003cbr\u003e\u003cbr\u003e\n  If this project or its implementation has provided value, support is greatly appreciated.\n  \u003cbr\u003e\u003cbr\u003e\n  \u003ca href=\"https://ko-fi.com/igorskyflyer\" target=\"_blank\"\u003e\u003cimg src=\"https://raw.githubusercontent.com/igorskyflyer/igorskyflyer/main/assets/ko-fi.png\" alt=\"Donate to igorskyflyer\" width=\"180\" height=\"46\"\u003e\u003c/a\u003e\n  \u003cbr\u003e\u003cbr\u003e\n  \u003cem\u003eThank you for supporting these efforts!\u003c/em\u003e 🙏😊\n\u003c/div\u003e\n\n---\n\n## Related\n\n[@igorskyflyer/scrollend-polyfill](https://www.npmjs.com/package/@igorskyflyer/scrollend-polyfill)\n\n\u003e _🛴 A performant and light (\u003c 1.5KB) JavaScript polyfill for the scrollend Event. ⛸️_\n\n\u003cbr\u003e\n\n[@igorskyflyer/zing](https://www.npmjs.com/package/@igorskyflyer/zing)\n\n\u003e _🐌 Zing is a C# style String formatter for JavaScript that empowers Strings with positional arguments - composite formatting. 🚀_\n\n\u003cbr\u003e\n\n[@igorskyflyer/strip-yaml-front-matter](https://www.npmjs.com/package/@igorskyflyer/strip-yaml-front-matter)\n\n\u003e _🦓 Strips YAML front matter from a String or a file. 👾_\n\n\u003cbr\u003e\n\n[@igorskyflyer/registry-apppaths](https://www.npmjs.com/package/@igorskyflyer/registry-apppaths)\n\n\u003e _🪀 A Node.js module for reading the AppPaths registry key on Windows. Useful for retrieving applications that can be launched from the command prompt. 🗃_\n\n\u003cbr\u003e\n\n[@igorskyflyer/emojilyzer](https://www.npmjs.com/package/@igorskyflyer/emojilyzer)\n\n\u003e _💬 Emojifies strings, converting textual representations of emojis to graphical ones. 🖌️_\n\n---\n\n## Author\nCreated by **Igor Dimitrijević** ([*@igorskyflyer*](https://github.com/igorskyflyer/)).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Figorskyflyer%2Fcommoji","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Figorskyflyer%2Fcommoji","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Figorskyflyer%2Fcommoji/lists"}