Project entropy is complexity that increases the effort required to understand, change or use the system. The rule distinguishes required complexity from avoidable burden. In UI Kit, consider component maintainers, developers consuming the public API and people using the rendered controls. Entropy is an engineering metaphor, not a numeric score or a thermodynamic quantity.
Every task may introduce only complexity justified by its validated requirements. Prefer a safe reduction of complexity in the affected area when it helps deliver those requirements.
- Choose the simplest viable design that preserves correctness, accessibility, demonstrated performance needs and supported public contracts. Necessary complexity is valid; fewer lines, files, props or visible controls do not by themselves establish simplicity.
- Keep added concepts, state, configuration and special cases proportional to the capability delivered. Ask whether a materially simpler design satisfies the same requirements; task size and implementation time do not justify additional complexity.
- Put responsibility in its owning component or layer. Evaluate the whole affected path: moving work into another module, dependency, public API or every consumer does not by itself reduce complexity.
- Require a demonstrated benefit for an API change. Flag a change that merely exchanges one obligation or problem for another without improving the validated requirements, even when ongoing complexity is unchanged. Include migration work, new failure modes and lost contracts in that judgment.
- Prefer existing patterns and implementations when their contracts fit. Do not force different contracts into one abstraction, invent speculative flexibility or add indirection merely to remove similar-looking code.
- Simplify safely within the task's scope. Preserve behavior and supported customization, and verify any refactoring using the applicable authoring and testing rules. Do not demand unrelated cleanup, a rewrite or removal of compatibility the task must preserve.
- Document any accepted avoidable complexity through the exception procedure below. An exception does not waive correctness, accessibility, security or public-contract requirements.
During implementation, identify the required capability and constraints before choosing a design. Before requesting review, be able to explain what complexity was added or removed, who bears its cost and why it is justified. Routine work needs no separate report or approval; put material tradeoffs and exceptions in the task record or PR description.
These signals guide investigation; none is an automatic violation.
| Signal | Code, APIs and consumer usage | UX |
|---|---|---|
| Additional concepts | New abstractions, props or configuration modes that callers must understand. | New terminology, choices or interaction patterns that users must learn. |
| Fragmented responsibility | Duplicate sources of truth, parallel implementations or one change requiring coordinated edits in several places. | Multiple places to configure or perform the same operation. |
| Hidden rules | Implicit dependencies, event-order assumptions, surprising defaults or undocumented combinations of props. | Invisible prerequisites, surprising behavior or inconsistent defaults between comparable controls. |
| Extra work | A wrapper that exposes no useful boundary, or a new API that makes every consumer implement the same workaround. | Extra navigation, repeated input or remembering information between steps to complete one user goal. |
| Unnecessary flexibility | Options and extension points without an actual supported use case. | Rare choices competing with the common path without helping the intended user. |
For library changes, inspect supported overrides and representative callers as well as internals. An additional prop can simplify consumer code; an internal abstraction can increase it. Keep distinct contracts separate, and do not break the frozen legacy Form contract to make implementation smaller.
For UX, name the user goal and relevant audience. Compare the concepts, decisions, steps and information the user must remember before and after the change. Use familiar control semantics and expose complexity when it becomes useful. Hiding a frequently needed action or removing a helpful label can increase burden even when the screen looks simpler. Verify interaction, focus, keyboard behavior and layout through the shared review procedure where relevant; screenshots alone cannot prove task difficulty.
Every Entropy review, including the pass within a broader UI Kit review, reports Entropy change: <level> — <affected context>; <brief rationale>. Compare the ongoing effort before and after the change in the component, API, consumer path or UX flow it affects. Include necessary effects on owners and callers, but judge the magnitude relative to that context, not the whole project. Report materially different directions in affected areas separately; do not average them away or offset an unjustified burden with unrelated cleanup.
| Level | Meaning within the affected context |
|---|---|
| Neutral | No material change in ongoing effort to understand, change or use the affected path. |
| Slightly Increased | A small, straightforward addition to ongoing effort. |
| Moderately Increased | Noticeably more reasoning, coordination or decision-making on relevant tasks. |
| Significantly Increased | The affected path becomes substantially harder to understand, change or use. |
| Slightly Decreased | A small, straightforward reduction in ongoing effort. |
| Moderately Decreased | Noticeably less reasoning, coordination or decision-making on relevant tasks. |
| Significantly Decreased | The affected path becomes substantially easier to understand, change or use. |
These are qualitative judgments supported by concrete before/after scenarios, not numeric scores or count thresholds. State migration costs and demonstrated benefits separately. A level does not determine severity or approval: Neutral can still require changes for an API change without a demonstrated benefit, and an increase can be justified or explicitly accepted. Assess the current implementation; a promised follow-up does not make its present burden Neutral or Decreased. If evidence is insufficient to assign a level, state that the assessment is unverified and name the missing context.
A developer may explicitly accept a scoped complexity tradeoff in task instructions, a PR description or a PR comment. Agents may propose and document exceptions, and must honor an existing developer acceptance that covers the current change; they must not infer acceptance from silence or approve their own exception.
Possible reasons include a verified pre-existing UI Kit limitation, an upstream defect in Tasty or React Aria, a platform constraint, supported compatibility or an urgent fix where a broader change would add disproportionate risk. First consider a safe fix in the owning layer. A dependency issue or deadline alone does not automatically exempt the change.
A concrete follow-up task is also a valid basis for accepting a bounded, temporary entropy increase when the required refactoring is too large or risky for the current task. Record its reference, the complexity it will remove and its completion criteria, alongside the reason for deferral and the developer's scoped acceptance. A tracked issue or a defined task in a developer-accepted plan can supply this evidence; a vague promise to clean up later cannot. Report the current increase and the pending follow-up. Reassess the exception if that task is cancelled or the accepted scope changes.
Record:
- Cause and evidence: the concrete limitation or constraint; link an existing issue when available.
- Alternative and cost: the simpler design considered and why it cannot be used in this task.
- Scope and acceptance: the exact workaround or tradeoff accepted and the developer's acceptance reference.
- Removal condition: for a temporary workaround, the upstream fix, version or event that permits its removal. A permanent constraint needs a durable rationale rather than an invented cleanup promise.
For example: Entropy exception accepted: keep the local adapter because dependency version X cannot express Y (issue link). It is limited to Z and can be removed when the supported dependency implements Y. The developer posts or supplies the acceptance; an agent writing this sentence does not establish it.
An accepted exception covers only that tradeoff. Keep reviewing the rest of the change, and reassess any later expansion beyond the accepted scope. Where another repository rule requires a particular owner's acceptance, follow that rule too.
Use the shared review scope and verification procedure. Review complexity introduced or amplified by the requested change and API changes without a demonstrated benefit, reading owners and callers for context without requiring migrations of untouched code.
- Identify the validated requirements and constraints. If missing context prevents judging a design, state the uncertainty rather than inventing requirements or reporting a violation.
- Identify added and removed complexity across implementation, public APIs, consumer usage and applicable UX. Classify the entropy change in each materially distinct affected context using the levels above, and explain it with a before/after scenario.
- For each candidate, name who bears the cost and a concrete maintenance or user scenario. Actively check whether the complexity is required, whether an existing abstraction really fits and whether a simpler alternative preserves the same requirements. For API changes, verify the benefit against new obligations, problems and migration cost even when the level is Neutral; retaining the existing contract can be the smallest improvement.
- Check recorded developer exceptions and any required follow-up task before reporting. Respect accepted scope, and distinguish a proposed exception awaiting acceptance from an accepted one. Do not count deferred refactoring as a completed reduction.
- Report only established findings, using the shared review format. Each finding needs a file and line, the relevant rule, the concrete burden, evidence and the smallest verified improvement. When a tradeoff needs developer acceptance, describe it as a design decision awaiting acceptance rather than claiming a behavior defect.
Do not block a change with only “this increases entropy,” personal preference, raw counts or speculative future maintenance. Severity follows the demonstrated consequence. Drop refuted candidates; record material verification limits without claiming a pass for unexamined behavior.
A focused Entropy review states its scope/base, entropy change level with affected context and rationale, and concludes pass, changes needed, exception accepted or unverified. Include verified findings, material accepted exceptions, their required follow-ups and any limits that affect the conclusion. Use changes needed while a confirmed avoidable burden or API change without a demonstrated benefit remains unresolved, or its proposed exception lacks developer acceptance; use exception accepted only when all remaining tradeoffs requiring an exception are covered by recorded developer acceptance. Use unverified when missing context or evidence prevents a conclusion. In a broader UI Kit review, include the brief entropy change assessment even when there are no findings, and include findings, material exceptions, required follow-ups and verification limits with the other results; do not duplicate the report or list routine passed checks.
The policy applies established ideas to UI Kit; these sources motivate the rule rather than provide a formula for scoring changes.
The references below are attribution only, not required reading. Agents must not search for, retrieve or read the cited works as part of implementation or review; the rules in this document are self-contained.
- Lehman and colleagues, Metrics and Laws of Software Evolution: evolving software requires deliberate work to maintain or reduce complexity.
- Frederick P. Brooks Jr., No Silver Bullet — Essence and Accident in Software Engineering: distinguish difficulty inherent in the problem from difficulty in its implementation.
- John Ousterhout, A Philosophy of Software Design: investigate change amplification, cognitive load and hard-to-discover dependencies.
- John Sweller, Jeroen J. G. van Merriënboer and Fred Paas, Cognitive Architecture and Instructional Design: 20 Years Later: distinguish inherent learning difficulty from burden introduced by presentation. Applying that distinction to developer experience and UX is this policy's design interpretation.